/**
 * @file Carousel.tsx
 * @input Uses React, StyleX, useScrollOverflow, useLayer, Button, Icon, theme tokens
 * @output Exports Carousel component
 * @position Horizontal scroll container with fade-edge overflow indication,
 *   optional prev/next buttons on the top layer, scroll-snap, a 1px
 *   visual bleed allowance for child selection indicators, and Shift + wheel
 *   mapping so mouse users can scroll horizontally. Supports optional
 *   wrap-around looping and an imperative handle (handleRef) for programmatic
 *   scroll control. Exposes APG
 *   carousel semantics: the root is a labelled region with
 *   aria-roledescription="carousel" and each item wrapper is a group with
 *   aria-roledescription="slide" named "Slide N of M".
 *
 * SYNC: When modified, update:
 * - /packages/core/src/Carousel/index.ts (exports)
 * - /apps/storybook/stories/Carousel.stories.tsx
 * - /packages/cli/assets/templates/blocks/components/Carousel/ (showcase blocks)
 */
import { type ReactNode } from 'react';
import type { BaseProps } from '../BaseProps';
import type { SpacingStep } from '../utils/types';
/**
 * Imperative control surface for the Carousel, accessed via the `handleRef`
 * prop. Methods drive the same native-scroll machinery as the built-in
 * buttons, so they respect RTL, reduced-motion, and `hasLoop`.
 */
export interface CarouselHandle {
    /**
     * Scroll forward by roughly one viewport. With `hasLoop`, wraps to the
     * start once the end is reached.
     */
    scrollNext(): void;
    /**
     * Scroll backward by roughly one viewport. With `hasLoop`, wraps to the
     * end once the start is reached.
     */
    scrollPrev(): void;
    /**
     * Scroll the item at the given 0-based index to the start edge. The index
     * is clamped to the item range, and only the carousel scrolls — the page
     * position is left untouched.
     */
    scrollTo(index: number): void;
    /**
     * Whether there is scrollable content past the trailing edge. With
     * `hasLoop`, returns true whenever the content overflows, since wrapping
     * is always available. Reads live state — safe to call in an event handler.
     */
    canScrollNext(): boolean;
    /**
     * Whether there is scrollable content past the leading edge. With
     * `hasLoop`, returns true whenever the content overflows. Reads live state.
     */
    canScrollPrev(): boolean;
}
export interface CarouselProps extends BaseProps<HTMLDivElement> {
    ref?: React.Ref<HTMLDivElement>;
    /**
     * Imperative handle for programmatic scroll control. Exposes scrollNext,
     * scrollPrev, scrollTo, and the canScrollNext/canScrollPrev queries.
     */
    handleRef?: React.Ref<CarouselHandle>;
    /** Carousel items — rendered in a horizontal scroll container. */
    children: ReactNode;
    /**
     * Gap between items using spacing scale tokens.
     * @default 1
     */
    gap?: 0 | 0.5 | 1 | 1.5 | 2 | 3 | 4;
    /**
     * Show prev/next navigation buttons when content is scrollable.
     * @default true
     */
    hasButtons?: boolean;
    /**
     * Show gradient edge-fade mask when content overflows, signalling that
     * more items exist off-screen. Can be suppressed when items have
     * full-fidelity surfaces that look broken when masked.
     * @default true
     */
    hasEdgeFade?: boolean;
    /**
     * Enable wrap-around scrolling. When the content overflows, pressing Next
     * at the end scrolls back to the start, and Prev at the start scrolls to
     * the end — for both the built-in buttons and the imperative handle. The
     * navigation buttons stay visible at both edges instead of hiding, since a
     * scroll is always available. Has no effect when the content fits without
     * overflowing.
     * @default false
     */
    hasLoop?: boolean;
    /**
     * Enable scroll-snap on items. Each direct child snaps to the start edge.
     * @default false
     */
    hasSnap?: boolean;
    /**
     * Inline padding on the scroll container. Applied as padding-inline
     * so the gutter is inside the scrollable area — items can scroll fully
     * into the padded region. Also sets matching scroll-padding so snap
     * points align to the content edge rather than the viewport edge.
     *
     * Accepts numeric spacing steps: 0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10.
     * @default undefined (no padding)
     */
    padding?: SpacingStep;
    /**
     * Accessible label for the carousel region.
     * @default 'Carousel'
     */
    'aria-label'?: string;
    'data-testid'?: string;
}
/**
 * Horizontal scroll container with fade-edge overflow indication and
 * optional navigation buttons.
 *
 * Wraps any content in a scrollable row. When content overflows, gradient
 * fades appear at the edges to signal more items exist. When content overflows, prev/next buttons appear at the edges,
 * rendered on the top layer via Layer so they escape any parent overflow
 * clipping.
 *
 * @example
 * ```
 * <Carousel gap={1}>
 *   <Thumbnail src="/a.jpg" alt="A" />
 *   <Thumbnail src="/b.jpg" alt="B" />
 *   <Thumbnail src="/c.jpg" alt="C" />
 * </Carousel>
 * ```
 */
export declare function Carousel({ ref, handleRef, children, gap, hasButtons, hasEdgeFade, hasLoop, hasSnap, padding, 'aria-label': ariaLabelFromProps, xstyle, className, style, 'data-testid': testId, ...htmlProps }: CarouselProps): import("react").JSX.Element;
export declare namespace Carousel {
    var displayName: string;
}
//# sourceMappingURL=Carousel.d.ts.map