@primitiv-ui/react 0.1.38 → 0.1.39

package/dist/Carousel/types.d.ts

@@ -0,0 +1,783 @@
+import { ComponentProps, ReactNode, RefObject } from "react";
+/**
+ * Discriminated label shape for `Carousel.Root` — exactly one of
+ * `ariaLabel` or `ariaLabelledBy` must be supplied so every carousel
+ * has an accessible name (per the WAI-ARIA Carousel pattern). TypeScript
+ * rejects shapes that supply both or neither.
+ */
+export type CarouselRootLabelProps = {
+    /** Accessible name for the carousel region, announced as
+     * `aria-label`. Prefer a short, human-readable description (e.g.
+     * `"Featured products"`). Mutually exclusive with `ariaLabelledBy`. */
+    ariaLabel: string;
+    ariaLabelledBy?: never;
+} | {
+    ariaLabel?: never;
+    /** Id of an existing element to name the carousel region, set as
+     * `aria-labelledby`. Use when a visible heading already labels the
+     * carousel. Mutually exclusive with `ariaLabel`. */
+    ariaLabelledBy: string;
+};
+/**
+ * Uncontrolled page state — the Root owns the active page internally,
+ * optionally seeded by `defaultPage`. The discriminated union below
+ * rejects passing `page` or `onPageChange` alongside it.
+ */
+export type UncontrolledCarouselPageProps = {
+    /** Uncontrolled active page index. Defaults to `0`. */
+    defaultPage?: number;
+    page?: never;
+    onPageChange?: never;
+};
+/**
+ * Controlled page state — the parent owns the active page; the Root
+ * defers every state change back through `onPageChange`. Both props
+ * must be supplied together.
+ */
+export type ControlledCarouselPageProps = {
+    /** Controlled active page index. */
+    page: number;
+    /** Callback invoked when the active page should change (e.g. when the
+     * user clicks `Carousel.NextTrigger` or `Carousel.PreviousTrigger`).
+     * The callback is responsible for re-rendering with the new `page`. */
+    onPageChange: (page: number) => void;
+    defaultPage?: never;
+};
+/**
+ * Discriminated state union — TypeScript rejects mixed shapes (e.g.
+ * `defaultPage` + `page`, or `page` without `onPageChange`).
+ */
+export type CarouselRootPageStateProps = UncontrolledCarouselPageProps | ControlledCarouselPageProps;
+/**
+ * Uncontrolled playing state — the Root owns the "playing" flag
+ * internally, optionally seeded by `defaultPlaying`.
+ */
+export type UncontrolledCarouselPlayingProps = {
+    /** Uncontrolled initial playing flag. Defaults to `false`. */
+    defaultPlaying?: boolean;
+    playing?: never;
+    onPlayingChange?: never;
+};
+/**
+ * Controlled playing state — the parent owns the "playing" flag; the
+ * Root defers every change back through `onPlayingChange`. Both props
+ * must be supplied together.
+ */
+export type ControlledCarouselPlayingProps = {
+    /** Controlled playing flag. */
+    playing: boolean;
+    /** Callback invoked when the playing flag should toggle. The callback
+     * is responsible for re-rendering with the new `playing` value. */
+    onPlayingChange: (playing: boolean) => void;
+    defaultPlaying?: never;
+};
+/**
+ * Discriminated playing-state union — mirrors the page-state pattern.
+ */
+export type CarouselRootPlayingStateProps = UncontrolledCarouselPlayingProps | ControlledCarouselPlayingProps;
+/**
+ * Autoplay configuration. Pass `true` for the default 4000ms cadence,
+ * `false` (default) to disable autoplay entirely, or `{ delay: N }` to
+ * tune the interval. The active page advances on each tick while
+ * `playing` is `true`; the timer stops once the active page reaches the
+ * last slide.
+ */
+export type CarouselAutoplay = boolean | {
+    delay: number;
+};
+/**
+ * Visual transition mode for the viewport. The resolved value is
+ * published on the Root as `data-transition` so consumer CSS can switch
+ * the visual off a single hook.
+ *
+ * - `"slide"` (default) — relies on native CSS scroll-snap; the
+ *   Viewport scrolls programmatically when the page changes and
+ *   listens for `scrollsnapchange` to update React state when the
+ *   user swipes.
+ * - `"fade"` — installs no scroll wiring (like `"none"`), but names the
+ *   intent so a styled surface can ship a crossfade by default: stack
+ *   the slides and cross-fade opacity off the per-slide `data-state`
+ *   hook. Native swipe/drag and peek don't apply (there's no scroll);
+ *   controls, indicators, and keyboard paging still work.
+ * - `"none"` — the Viewport installs no scroll wiring at all, and the
+ *   styled surface ships no default visual: consumer CSS owns the
+ *   transition entirely via the `data-state` hook on each slide, which
+ *   still flips with the active page.
+ */
+export type CarouselTransition = "slide" | "fade" | "none";
+/**
+ * Resolved wrap-around navigation mode — the value published as the
+ * `data-loop` styling hook on the Root. The consumer-facing `loop` prop
+ * accepts `boolean | "wrap" | "infinite"` and resolves to this:
+ *
+ * - `"none"` — navigation clamps at the ends (`loop` omitted / `false`).
+ * - `"wrap"` — *semantic* wrapping (`loop` / `loop={true}` / `loop="wrap"`):
+ *   Next/Previous and autoplay wrap past the ends, the triggers never
+ *   disable, but wrapping last→first smooth-scrolls the whole track back
+ *   (a visible rewind, the same path `Home`/`End` take).
+ * - `"infinite"` — continuous infinite (`loop="infinite"`): the same wrap
+ *   page model, plus a cloned edge buffer and a native-scroll recentre so
+ *   the wrap is a continuous glide with no visible rewind.
+ *
+ * Both `"wrap"` and `"infinite"` share the page model (the wrap
+ * arithmetic in `next`/`previous` and the never-disable boundaries);
+ * `"infinite"` layers the clone/scroll behaviour on top, keyed off the
+ * `data-loop="infinite"` hook.
+ */
+export type CarouselLoopMode = "none" | "wrap" | "infinite";
+/**
+ * Scroll-snap alignment that the Viewport should target when
+ * programmatically scrolling to a page.
+ *
+ * - `"start"` (default) — scrolls so the first slide of the target
+ *   page aligns with the **start** (left) edge of the Viewport.
+ *   Matches `scroll-snap-align: start` in consumer CSS.
+ * - `"center"` — scrolls so the first slide of the target page is
+ *   **centred** in the Viewport. The target is offset inward by
+ *   `(viewportWidth − slideWidth) / 2`. Use this with
+ *   `scroll-snap-align: center` in consumer CSS (e.g. a peek
+ *   layout where slides are narrower than the Viewport).
+ * - `"end"` — scrolls so the first slide of the target page's
+ *   **trailing** edge aligns with the Viewport's trailing edge. The
+ *   target is offset inward by the full `viewportWidth − slideWidth`.
+ *   Use with `scroll-snap-align: end`.
+ *
+ * Settable on `Carousel.Root` (the default for every slide) and
+ * overridden per-slide via {@link CarouselSlideProps.snapAlign} — e.g. a
+ * variable-width layout where only some slides should centre. Matches
+ * Ark UI's per-`Item` `snapAlign`.
+ */
+export type CarouselSnapAlign = "start" | "center" | "end";
+/**
+ * `scroll-snap-type` strictness the Viewport scrolls with.
+ *
+ * - `"mandatory"` (default) — the browser always rests on a snap point;
+ *   scrolling can't stop mid-way between slides.
+ * - `"proximity"` — the browser only nudges toward a snap point when the
+ *   scroll ends *near* one, otherwise leaving the scroll wherever it
+ *   stopped — for a looser, free-scrolling feel (e.g. a gallery where
+ *   forcing a rest on every slide feels too rigid).
+ *
+ * The resolved value is published on the Viewport as `data-snap-type` so
+ * consumer CSS can switch `scroll-snap-type`'s strictness off a single hook.
+ * Matches Ark UI's `snapType`.
+ */
+export type CarouselSnapType = "mandatory" | "proximity";
+/**
+ * Payload passed to `Carousel.Root`'s `onDragStatusChange` on every
+ * mouse-drag status transition (only reachable when `allowMouseDrag` is
+ * `true`):
+ *
+ * - `"dragging.start"` — the pointer just crossed the click-vs-drag
+ *   movement threshold; a drag has begun.
+ * - `"dragging"` — a subsequent pointer move while already dragging.
+ * - `"dragging.end"` — the drag ended (`pointerup` or `pointercancel`).
+ *
+ * `page` is the live active page at the moment of the event; `isDragging`
+ * mirrors the imperative `isDragging()` snapshot at that moment (`true`
+ * for `"dragging.start"`/`"dragging"`, `false` for `"dragging.end"`).
+ * Matches Ark UI's `onDragStatusChange` shape.
+ */
+export type CarouselDragStatus = {
+    type: "dragging.start" | "dragging" | "dragging.end";
+    page: number;
+    isDragging: boolean;
+};
+/**
+ * Payload passed to `Carousel.Root`'s `onOverscrollStatusChange` whenever
+ * the user pushes against a boundary that has nowhere further to go —
+ * detected off the same `canGoNext` / `canGoPrevious` page-boundary truth
+ * the rest of the primitive already uses, from three input sources the
+ * carousel directly owns the physics for:
+ *
+ * - `"keyboard"` — the forward/backward arrow key pressed while already
+ *   at that boundary (`Home`/`End` are absolute jumps, not directional
+ *   pushes, so they never fire this).
+ * - `"wheel"` — the existing horizontal-desktop wheel-to-scroll
+ *   translation, blocked at a boundary.
+ * - `"drag"` — a mouse drag (`allowMouseDrag`) pushing past a boundary.
+ *
+ * `"keyboard"` and `"wheel"` are instantaneous taps with no meaningful
+ * distance — they always fire a single bare `"overscroll"` with
+ * `amount: 0`. `"drag"` is the one continuous, physically real case —
+ * it fires `"overscroll.start"` the moment the drag starts pushing past
+ * the boundary, `"overscroll"` on every subsequent move while still
+ * pushing (with the live `amount`, the drag delta past the boundary),
+ * and `"overscroll.end"` when the drag stops pushing past it (a reversal
+ * back within bounds, or the drag ending) — mirroring
+ * `CarouselDragStatus`'s shape. `page` is the active page at the moment
+ * of the event.
+ *
+ * Native touch/swipe overscroll (OS-level rubber-banding) is
+ * deliberately out of scope — that's browser-owned scroll physics with
+ * no JS hook to observe it from, consistent with the primitive's
+ * "native scroll is the source of truth" approach elsewhere.
+ */
+export type CarouselOverscrollStatus = {
+    type: "overscroll.start" | "overscroll" | "overscroll.end";
+    edge: "start" | "end";
+    source: "keyboard" | "wheel" | "drag";
+    amount: number;
+    page: number;
+};
+/**
+ * Payload passed to `Carousel.Root`'s `onAutoplayStatusChange` on every
+ * autoplay status transition (only reachable when `autoplay` is enabled):
+ *
+ * - `"autoplay.start"` — the timer just became active: autoplay is
+ *   enabled, `playing` is `true`, another page remains, and the timer
+ *   isn't suspended by hover/focus/touch.
+ * - `"autoplay"` — a scheduled tick fired and is about to advance the
+ *   page, while the timer stays active.
+ * - `"autoplay.stop"` — the timer stopped running, whether because
+ *   `playing` flipped `false`, the last page was reached, or
+ *   hover/focus/touch suspended it.
+ *
+ * Fires on every tick, not just play/pause toggles. `page` is the active
+ * page at the moment of the event; `isPlaying` mirrors whether the timer
+ * is running right after the event (`true` for `"autoplay.start"`/
+ * `"autoplay"`, `false` for `"autoplay.stop"`). Matches Ark UI's
+ * `onAutoplayStatusChange` shape.
+ */
+export type CarouselAutoplayStatus = {
+    type: "autoplay.start" | "autoplay" | "autoplay.stop";
+    page: number;
+    isPlaying: boolean;
+};
+/**
+ * Axis the carousel scrolls and paginates along.
+ *
+ * - `"horizontal"` (default) — slides lay out inline; the viewport
+ *   scroll-snaps on the inline (x) axis. `Carousel.NextTrigger` /
+ *   `Carousel.PreviousTrigger` and the viewport `ArrowRight` /
+ *   `ArrowLeft` keys advance / retreat.
+ * - `"vertical"` — slides lay out in the block direction; the viewport
+ *   scroll-snaps on the block (y) axis. The viewport `ArrowDown` /
+ *   `ArrowUp` keys advance / retreat instead (the horizontal arrows are
+ *   inert), and programmatic paging scrolls on the block axis.
+ *
+ * The resolved value is published on the Root as `data-orientation` so
+ * consumer CSS can switch layout (e.g. a column viewport with a
+ * `scroll-snap-type: y mandatory`) off a single hook.
+ */
+export type CarouselOrientation = "horizontal" | "vertical";
+/**
+ * Pin DOM `id`s on the rendered sub-components for SSR / hydration
+ * stability or for external `aria-controls` references. Any keys you
+ * omit leave the corresponding element unidentified (or with whatever
+ * the consumer attaches to that sub-component directly via its own
+ * `id` prop, which always wins).
+ */
+export type CarouselIds = {
+    root?: string;
+    viewport?: string;
+    previousTrigger?: string;
+    nextTrigger?: string;
+    playPauseTrigger?: string;
+    indicatorGroup?: string;
+};
+/**
+ * Override the default user-visible strings the component owns —
+ * intended for internationalisation. Any keys you omit fall back to
+ * the English defaults.
+ */
+export type CarouselTranslations = {
+    /** Format used for the auto-generated slide aria-label. Receives
+     * 1-indexed `index` and the live `total`. Default:
+     * `({ index, total }) => "${index} of ${total}"`. */
+    slideLabel?: (params: {
+        index: number;
+        total: number;
+    }) => string;
+    /** Format used for the auto-generated indicator aria-label. Receives
+     * the 1-indexed page position. Default:
+     * `({ index }) => "Slide ${index}"`. */
+    indicatorLabel?: (params: {
+        index: number;
+    }) => string;
+    /** Accessible name for `Carousel.PlayPauseTrigger` while paused.
+     * Default: `"Start automatic slide show"`. */
+    startSlideshow?: string;
+    /** Accessible name for `Carousel.PlayPauseTrigger` while playing.
+     * Default: `"Stop automatic slide show"`. */
+    stopSlideshow?: string;
+    /** Format used for `Carousel.ProgressText`'s default rendered content.
+     * Receives the 0-indexed active `page` and the live `totalPages`.
+     * Default: `({ page, totalPages }) => "${page + 1} of ${totalPages}"`. */
+    progressText?: (params: {
+        page: number;
+        totalPages: number;
+    }) => string;
+};
+/** Props for `Carousel.Root` — the labelled `<section>` wrapping the whole widget; combines label, page-state, and playing-state shapes with autoplay, transition, and layout options. */
+export type CarouselRootProps = Omit<ComponentProps<"section">, "aria-label" | "aria-labelledby"> & CarouselRootLabelProps & CarouselRootPageStateProps & CarouselRootPlayingStateProps & {
+    /** Autoplay configuration — see {@link CarouselAutoplay}. */
+    autoplay?: CarouselAutoplay;
+    /** Visual transition mode — see {@link CarouselTransition}.
+     * Defaults to `"slide"`. */
+    transition?: CarouselTransition;
+    /** Number of slides visible per page. Defaults to `1`. With values
+     * greater than `1`, slides are grouped into pages of that size for
+     * navigation purposes: indicators auto-render per page, boundary
+     * clamp moves to the last page, and `Carousel.NextTrigger` /
+     * `Carousel.PreviousTrigger` advance one page at a time. The **last
+     * page always end-aligns** (its window is full, flush with the track
+     * end) rather than leaving a partial page — a partial page's leading
+     * slide can't align to the viewport start, which desyncs the active
+     * page against the scroll. So 7 slides at `slidesPerPage={3}` are 3
+     * pages — `[0,1,2] [3,4,5] [4,5,6]` — the last shifted back by one to
+     * stay full. Coerced to an integer ≥ 1 — `0`, negative, fractional,
+     * and non-finite values are clamped (e.g. `2.5 → 2`, `0 → 1`) so the
+     * page maths never divides by zero. */
+    slidesPerPage?: number;
+    /** Number of slides advanced by `Carousel.NextTrigger` /
+     * `Carousel.PreviousTrigger`. `"auto"` (default) advances one full page
+     * at a time (= `slidesPerPage`); a number advances exactly that many
+     * slides per click and pages are windowed so the visible window always
+     * stays full. A numeric move is coerced to an integer in
+     * `[1, slidesPerPage]` — it can neither drop below one nor skip past a
+     * page (which would orphan the slides in the gap) — and the **last page
+     * is end-aligned to the track end**, so every slide stays reachable even
+     * when the move doesn't divide the slide count evenly (e.g. 6 slides,
+     * `slidesPerPage={3}`, `slidesPerMove={2}` yields pages
+     * `[0,1,2] [2,3,4] [3,4,5]`). */
+    slidesPerMove?: number | "auto";
+    /** Override the default user-visible strings the component owns —
+     * see {@link CarouselTranslations}. Useful for i18n. */
+    translations?: CarouselTranslations;
+    /** Pin DOM `id`s on the rendered sub-components — see
+     * {@link CarouselIds}. Useful for SSR hydration stability and
+     * external `aria-controls` linkage. */
+    ids?: CarouselIds;
+    /** Scroll-snap alignment the Viewport targets when programmatically
+     * scrolling to a page — see {@link CarouselSnapAlign}.
+     * Defaults to `"start"`. Set to `"center"` when consumer CSS uses
+     * `scroll-snap-align: center` on slides (e.g. a peek layout
+     * where slides are narrower than the Viewport). */
+    snapAlign?: CarouselSnapAlign;
+    /** Axis the carousel scrolls and paginates along — see
+     * {@link CarouselOrientation}. Defaults to `"horizontal"`. Switches
+     * the viewport scroll axis, the arrow-key bindings, and the
+     * `data-orientation` styling hook on the Root. */
+    orientation?: CarouselOrientation;
+    /** Wrap-around navigation mode — see {@link CarouselLoopMode}.
+     * Defaults to `false` (`"none"`). Accepts a boolean for ergonomics or a
+     * named mode:
+     *
+     * - `false` / omitted → `"none"` (clamp at the ends).
+     * - `true` / `"wrap"` → `"wrap"` (semantic wrap: Next/Previous and
+     *   autoplay wrap past the ends and the triggers never disable, but the
+     *   wrap last→first smooth-scrolls the track back — a visible rewind).
+     * - `"infinite"` → continuous infinite: the same wrap page model plus a
+     *   cloned edge buffer and native-scroll recentre so the wrap is a
+     *   continuous glide with no rewind.
+     *
+     * All wrapping requires more than one page — a single-page carousel has
+     * no wrap target, so the triggers stay disabled regardless. The resolved
+     * mode is published as `data-loop="none" | "wrap" | "infinite"` on the
+     * Root. */
+    loop?: boolean | "wrap" | "infinite";
+    /** Whether the Viewport supports mouse click-and-drag scrolling —
+     * the pointer tracks 1:1 into `scrollLeft`/`scrollTop` (no momentum)
+     * once past a small movement threshold, release lets the existing
+     * `scroll-snap-type` settle. Defaults to `false`: an unconditionally-on
+     * drag can conflict with a consumer's own drag-sensitive slide content
+     * (a nested carousel, a draggable card, a canvas), so it's opt-in.
+     * Touch/pen scrolling is unaffected either way — that's native,
+     * independent of this prop. */
+    allowMouseDrag?: boolean;
+    /** Fires on every mouse-drag status transition — see
+     * {@link CarouselDragStatus}. Matches Ark UI's `onDragStatusChange`.
+     * No-op unless `allowMouseDrag` is `true` (a drag can't start
+     * otherwise). */
+    onDragStatusChange?: (status: CarouselDragStatus) => void;
+    /** Fires whenever the user pushes against a boundary with nowhere
+     * further to go, from the keyboard, wheel, or a mouse drag — see
+     * {@link CarouselOverscrollStatus}. */
+    onOverscrollStatusChange?: (status: CarouselOverscrollStatus) => void;
+    /** Fires on every autoplay status transition — see
+     * {@link CarouselAutoplayStatus}. Matches Ark UI's
+     * `onAutoplayStatusChange`. Fires on every tick, not just play/pause
+     * toggles — useful for analytics. No-op unless `autoplay` is enabled. */
+    onAutoplayStatusChange?: (status: CarouselAutoplayStatus) => void;
+    /** Visibility threshold(s) the `isInView` fallback's
+     * `IntersectionObserver` uses — both as the observer's own `threshold`
+     * option and (for an array, the highest value) the cutoff a slide's
+     * `intersectionRatio` must clear to count as "in view". Matches Ark
+     * UI's `inViewThreshold` shape. Defaults to `0.6`. */
+    inViewThreshold?: number | number[];
+    /** `scroll-snap-type` strictness — see {@link CarouselSnapType}.
+     * Defaults to `"mandatory"`. */
+    snapType?: CarouselSnapType;
+};
+/**
+ * Shape of the context published by `Carousel.Root` to descendants.
+ * Fields are added as future cycles introduce shared state (active
+ * page, autoplay, etc.).
+ */
+export type CarouselContextValue = {
+    /** Self-registers a slide. Called as a callback ref by `Carousel.Slide`
+     * with the rendered DOM node on mount and `null` on unmount. */
+    registerSlide: (key: string, element: HTMLDivElement | null) => void;
+    /** Live map from slide key to rendered DOM node. Used by the
+     * Viewport to read `getBoundingClientRect` on the first slide of
+     * the target page when programmatically scrolling. */
+    slidesRef: RefObject<Map<string, HTMLDivElement>>;
+    /** Ordered list of currently-mounted slide keys. The slide's index is
+     * its position in this array; the array's length is the total. */
+    slideKeys: string[];
+    /** Number of slides visible per page — the consumer's `slidesPerPage`
+     * coerced to an integer ≥ 1 (0 / negative / non-finite → 1). */
+    slidesPerPage: number;
+    /** Resolved slides advanced per Prev/Next click — equal to
+     * `slidesPerPage` when the consumer left `slidesPerMove="auto"`, else
+     * the numeric value coerced to an integer in `[1, slidesPerPage]` (a
+     * move can neither drop below one nor skip past a page). */
+    effectiveSlidesPerMove: number;
+    /** Start slide index of the *last* page's window — `max(0, total -
+     * slidesPerPage)`. Every page's own offset is `min(page *
+     * effectiveSlidesPerMove, maxOffset)`; used to derive any page's window
+     * (not just the current one), e.g. the multi-slide `scroll-margin`
+     * extension that keeps native scroll-snap alignment consistent with the
+     * programmatic scroll for `slidesPerPage > 1`. */
+    maxOffset: number;
+    /** Start slide index of the currently-active window. In `"auto"`
+     * (paged) mode this is `currentPage * slidesPerPage` (the last page may
+     * be partial); in numeric (windowed) mode the last page is end-aligned
+     * — clamped to `total − slidesPerPage` — so every slide stays reachable
+     * even when the move doesn't divide the track evenly. Drives the slide
+     * `data-state` window and the viewport scroll target. */
+    currentPageOffset: number;
+    /** Map a leading slide index (e.g. a user swipe's snap target) back to
+     * its page index, clamped into `[0, totalPages − 1]`. Paged mode groups
+     * by `slidesPerPage`; windowed mode inverts the move offset to the
+     * nearest window start. */
+    pageForSlideIndex: (slideIndex: number) => number;
+    /** Live total page count — `ceil(total / slidesPerPage)` in `"auto"`
+     * mode (partial last page allowed), else
+     * `floor((total - slidesPerPage) / effectiveSlidesPerMove) + 1`
+     * (always full-windowed). Drives indicator count and boundary
+     * clamp. */
+    totalPages: number;
+    /** Zero-based index of the currently-active page. */
+    currentPage: number;
+    /** `true` when there is a forward navigation target (a page ahead of
+     * the active one). Drives the `disabled` attribute on
+     * `Carousel.NextTrigger` and short-circuits `next()` when there's
+     * nowhere to go. */
+    canGoNext: boolean;
+    /** `true` when there is a backward navigation target. Drives the
+     * `disabled` attribute on `Carousel.PreviousTrigger`. */
+    canGoPrevious: boolean;
+    /** Advance the active page by one step. No-op when `!canGoNext`. Pass
+     * `instant` to bypass the resolved smooth/reduced-motion scroll for
+     * just this one call — see {@link CarouselImperativeApi.next}. */
+    next: (instant?: boolean) => void;
+    /** Retreat the active page by one step. No-op when `!canGoPrevious`.
+     * See {@link CarouselContextValue.next} for the `instant` override. */
+    previous: (instant?: boolean) => void;
+    /** Jump directly to `target` (zero-based page index). Used by
+     * `Carousel.Indicator` to dispatch click-to-jump. See
+     * {@link CarouselContextValue.next} for the `instant` override. */
+    goTo: (target: number, instant?: boolean) => void;
+    /** Whether autoplay is currently in the "playing" state. */
+    playing: boolean;
+    /** Toggles `playing`. Used by `Carousel.PlayPauseTrigger`. */
+    togglePlaying: () => void;
+    /** `true` when the consumer enabled autoplay (regardless of the
+     * `playing` flag). Used by `Carousel.PlayPauseTrigger` to validate
+     * its own configuration. */
+    autoplayEnabled: boolean;
+    /** `true` when autoplay is enabled AND `playing` is `true` — i.e. the
+     * timer could fire any moment. Drives the Viewport's `aria-live`
+     * flip ("off" while auto-rotating, "polite" otherwise) so screen
+     * readers don't get spammed by every tick. */
+    isAutoRotating: boolean;
+    /** Translations merged with English defaults — every field is
+     * present, even if the consumer passed only a subset. */
+    translations: Required<CarouselTranslations>;
+    /** Custom DOM ids — every field optional. Sub-components apply
+     * their respective entry via spread, so consumer-supplied `id`
+     * props on the sub-component still win. */
+    ids: CarouselIds;
+    /** Resolved visual transition mode (defaults to `"slide"`). */
+    transition: CarouselTransition;
+    /** Resolved scroll-snap alignment (defaults to `"center"`). */
+    snapAlign: CarouselSnapAlign;
+    /** Resolved scroll/pagination axis (defaults to `"horizontal"`).
+     * Drives the viewport scroll axis, the arrow-key bindings, and the
+     * `data-orientation` hook on the Root. */
+    orientation: CarouselOrientation;
+    /** Resolved wrap-around navigation mode (defaults to `"none"`) — see
+     * {@link CarouselLoopMode}. `"wrap"` and `"infinite"` both drive the
+     * boundary flags (`canGoNext`/`canGoPrevious` stay true past the ends
+     * when there is more than one page) and the wrap arithmetic in
+     * `next`/`previous`; `"infinite"` additionally signals the clone/scroll
+     * layer via the `data-loop` hook on the Root. */
+    loop: CarouselLoopMode;
+    /** Resolved mouse click-and-drag scrolling opt-in (defaults to
+     * `false`). */
+    allowMouseDrag: boolean;
+    /** Resolved `isInView` IntersectionObserver threshold(s) (defaults to
+     * `0.6`). */
+    inViewThreshold: number | number[];
+    /** Resolved `scroll-snap-type` strictness (defaults to `"mandatory"`). */
+    snapType: CarouselSnapType;
+    /** Bumped by `refresh()` to force the viewport's scroll-align
+     * effect to re-run without a page change. */
+    refreshTick: number;
+    /** Live set of slide indices currently visible per IntersectionObserver
+     * (≥ 60% intersection). Mutated by the Viewport hook and read by
+     * the imperative `isInView`. */
+    visibleSlideIndicesRef: RefObject<Set<number>>;
+    /** Used by the Viewport hook to record visibility transitions. */
+    setSlideInView: (slideIndex: number, inView: boolean) => void;
+    /** Used by the Viewport hook to report the live continuous scroll
+     * position, read on demand by the imperative `getScrollProgress()`. */
+    setScrollProgress: (value: number) => void;
+    /** Used by the Viewport hook to report a slide's live continuous
+     * center-distance, read on demand by the imperative
+     * `getSlideProgress()`. */
+    setSlideProgress: (slideIndex: number, value: number) => void;
+    /** Set to `true` by `next()` and `previous()` the moment programmatic
+     * navigation begins, and cleared by the Viewport hook once the scroll
+     * animation settles (`scrollend` or a timeout fallback). The
+     * IntersectionObserver callback checks this flag before calling `goTo`
+     * so that IO entries firing mid-animation cannot undo the navigation. */
+    isProgrammaticScrollRef: RefObject<boolean>;
+    /** One-shot override of the resolved smooth/reduced-motion
+     * `scrollBehavior`, set by `next()` / `previous()` / `goTo()` on every
+     * call (`true` when their optional `instant` argument was passed,
+     * `false` otherwise) and consumed — then reset to `false` — by the
+     * Viewport hook's scroll effect on its very next run, so an instant
+     * jump never outlives the single call that requested it. */
+    instantScrollRef: RefObject<boolean>;
+    /** One-shot hint for the infinite-loop engine, set to `true` by `goTo()` /
+     * `scrollToIndex()` (an absolute jump to a specific page — most visibly an
+     * indicator/thumbnail click) and to `false` by `next()` / `previous()` (a
+     * relative step, which should always take the loop's wrap shortcut).
+     * Consumed and reset by the engine's positioning effect on its very next
+     * run, so it never outlives the single navigation that requested it. */
+    directJumpRef: RefObject<boolean>;
+    /** Live mouse-drag state (only ever `true` when `allowMouseDrag` is
+     * `true`). Mutated by the Viewport hook and read by the imperative
+     * `isDragging()`. */
+    isDraggingRef: RefObject<boolean>;
+    /** Used by the Viewport hook to record drag start/end transitions. */
+    setDragging: (value: boolean) => void;
+    /** The consumer's `onDragStatusChange`, if provided — called by the
+     * Viewport hook on every drag status transition. */
+    onDragStatusChange?: (status: CarouselDragStatus) => void;
+    /** Live mouse-drag overscroll state (only ever `true` mid-drag, when
+     * `allowMouseDrag` is `true` and the drag is currently pushing past a
+     * boundary). Mutated by the Viewport hook and read by the imperative
+     * `isOverscrolling()`. Keyboard/wheel overscroll taps never set this —
+     * they're instantaneous, not a sustained state. */
+    isOverscrollingRef: RefObject<boolean>;
+    /** Used by the Viewport hook to record drag-overscroll start/end
+     * transitions. */
+    setOverscrolling: (value: boolean) => void;
+    /** The consumer's `onOverscrollStatusChange`, if provided — called by
+     * the Viewport hook whenever the keyboard, wheel, or a mouse drag
+     * pushes against a boundary with nowhere further to go. */
+    onOverscrollStatusChange?: (status: CarouselOverscrollStatus) => void;
+};
+/** Props for `Carousel.Viewport` — the scroll-snap slide container; accepts all native `<div>` props. */
+export type CarouselViewportProps = ComponentProps<"div">;
+/** Props for `Carousel.Slide` — an individual slide that self-registers with the Root; native `<div>` props plus an optional accessible-label override. */
+export type CarouselSlideProps = Omit<ComponentProps<"div">, "aria-label"> & {
+    /** Override the auto-generated `"N of M"` `aria-label`. Use this when
+     * the slide has a more meaningful description than its position
+     * (e.g. `"Hand-picked for you"`). When omitted, slides are labelled
+     * with their live index and total in registration order. */
+    ariaLabel?: string;
+    /** Override the root's {@link CarouselRootProps.snapAlign | `snapAlign`}
+     * for this slide only — e.g. a variable-width layout where only some
+     * slides should centre or end-align. Only takes effect on a slide
+     * that's a valid scroll-snap resting position (a page's leading
+     * slide); an interior slide of a multi-slide page never snaps,
+     * regardless of this prop. Matches Ark UI's per-`Item` `snapAlign`. */
+    snapAlign?: CarouselSnapAlign;
+};
+/** Props for `Carousel.NextTrigger` — the button that advances one page; native `<button>` props plus `asChild`. */
+export type CarouselNextTriggerProps = ComponentProps<"button"> & {
+    /** Render the child element instead of the default `<button>`. All
+     * trigger props (onClick, disabled, ids.nextTrigger, ...) are merged
+     * onto the child via `Slot`. The child must accept a `ref`. */
+    asChild?: boolean;
+};
+/** Props for `Carousel.PreviousTrigger` — the button that retreats one page; native `<button>` props plus `asChild`. */
+export type CarouselPreviousTriggerProps = ComponentProps<"button"> & {
+    /** See `CarouselNextTriggerProps.asChild`. */
+    asChild?: boolean;
+};
+/**
+ * Discriminated label shape for `Carousel.IndicatorGroup` — exactly one
+ * of `label` (becomes `aria-label`) or `ariaLabelledBy` (points at an
+ * external label element) must be supplied. TypeScript rejects
+ * both-or-neither at compile time.
+ */
+export type CarouselIndicatorGroupProps = Omit<ComponentProps<"div">, "label" | "aria-labelledby"> & ({
+    /** Accessible name for the indicator group, announced as
+     * `aria-label` (e.g. `"Choose slide"`). Mutually exclusive with
+     * `ariaLabelledBy`. */
+    label: string;
+    ariaLabelledBy?: never;
+} | {
+    label?: never;
+    /** Id of an existing element to name the indicator group, set as
+     * `aria-labelledby`. Mutually exclusive with `label`. */
+    ariaLabelledBy: string;
+});
+/** Props for `Carousel.Indicator` — a button that jumps to its target page; native `<button>` props plus the target `index` and `asChild`. */
+export type CarouselIndicatorProps = ComponentProps<"button"> & {
+    /** Zero-based page this indicator targets. Clicking jumps to it. */
+    index: number;
+    /** Renders a presentational-only `<span>` instead of a `<button>`:
+     * `aria-hidden="true"`, and clicking no longer calls `goTo`. Use for a
+     * progress display when navigation happens some other way (e.g. a
+     * carousel driven solely by `allowMouseDrag`). The consumer's own
+     * `onClick`, if passed, still fires. Default `false`. */
+    readOnly?: boolean;
+    /** Render the child element instead of the default `<button>`.
+     * Trigger props (onClick, aria-label, aria-disabled, data-state)
+     * are merged onto the child via `Slot`. The child must accept a
+     * `ref`. */
+    asChild?: boolean;
+};
+/**
+ * Imperative handle exposed via `ref` on `Carousel.Root`. Routes
+ * through the same internal state machine the trigger components
+ * use, so controlled-mode `onPageChange` / `onPlayingChange` still
+ * fire as if the user had clicked.
+ */
+export type CarouselImperativeApi = {
+    /** Advance the active page by one. No-op on the last page. Pass
+     * `instant` (default `false`) to bypass the resolved smooth/
+     * reduced-motion scroll for just this one call — e.g. an instant
+     * jump on initial deep-link vs. smooth for user-initiated
+     * navigation. Matches Ark UI's `scrollNext(instant?)`. */
+    next: (instant?: boolean) => void;
+    /** Retreat the active page by one. No-op on the first page. See
+     * `next`'s `instant` parameter. Matches Ark UI's
+     * `scrollPrev(instant?)`. */
+    previous: (instant?: boolean) => void;
+    /** Jump directly to `target` (zero-based page index). See `next`'s
+     * `instant` parameter. Matches Ark UI's `scrollTo(page, instant?)`. */
+    goTo: (target: number, instant?: boolean) => void;
+    /** Jump to the page containing the given zero-based **slide** index —
+     * slide granularity, distinct from `goTo`'s page granularity. In a
+     * multi-slide (`slidesPerPage > 1`) layout an interior slide isn't its
+     * own scroll-snap position, so this lands on that slide's *containing*
+     * page (the same mapping `Carousel.Indicator` uses internally). See
+     * `next`'s `instant` parameter. Matches Ark UI's
+     * `scrollToIndex(index, instant?)`. */
+    scrollToIndex: (slideIndex: number, instant?: boolean) => void;
+    /** Set `playing` to `true`. Dismisses the hover/focus pause for the
+     * lifetime of the resulting playing session. */
+    play: () => void;
+    /** Set `playing` to `false`. */
+    pause: () => void;
+    /** Re-issue the viewport's scrollTo for the current page. Call when
+     * external layout changes (window resize, container reflow) leave
+     * the scroll position misaligned with React state. */
+    refresh: () => void;
+    /** Live progress snapshot: the active page, the total page count,
+     * and a normalised `value` in `[0, 1]` (0 when there's at most one
+     * page). */
+    getProgress: () => {
+        page: number;
+        totalPages: number;
+        value: number;
+    };
+    /** Reports whether the slide at the zero-based index is currently
+     * visible in the viewport (per IntersectionObserver, ≥ 60%
+     * intersection). Useful for lazy-loading slide content. */
+    isInView: (slideIndex: number) => boolean;
+    /** The leading slide index each page snaps to, one entry per page
+     * (length `totalPages`). The last entry is the end-aligned offset
+     * (see the multi-slide page model), not necessarily a clean multiple
+     * of `slidesPerMove`. Useful for a custom progress bar or indicator
+     * that needs the raw offsets rather than just the page count. */
+    getPageSnapPoints: () => number[];
+    /** Live snapshot of whether a mouse drag is currently in progress
+     * (`allowMouseDrag`-gated — always `false` when it's off). Mirrors
+     * Ark UI's `api.isDragging`; see also `onDragStatusChange`. */
+    isDragging: () => boolean;
+    /** Live snapshot of whether a mouse drag is currently pushing past a
+     * boundary (`allowMouseDrag`-gated — always `false` when it's off, and
+     * never `true` for a keyboard/wheel overscroll tap, which is
+     * instantaneous rather than a sustained state). See
+     * `onOverscrollStatusChange`. */
+    isOverscrolling: () => boolean;
+    /** Continuous `[0, 1]` scroll position along the main axis — `0` at
+     * the start, `1` at the end, `0` when there's no overflow to scroll.
+     * Unlike `getProgress()`'s page-granular step function, this changes
+     * on every scroll tick (mirrored live onto the Viewport's
+     * `--carousel-progress` CSS custom property, rAF-batched, so a
+     * consumer can drive a progress bar from CSS alone without reading
+     * this at all). Robust under RTL without any `dir` check — RTL's
+     * standardized negative-`scrollLeft` convention is handled via
+     * `Math.abs`. */
+    getScrollProgress: () => number;
+    /** Continuous `[-1, 1]` signal for how far the slide at the zero-based
+     * index sits from the viewport's center along the main axis — `0` =
+     * centered, `±1` = the slide's center has reached the viewport edge
+     * (clamped beyond that). `0` for a never-registered/out-of-range
+     * index. Normalised by the *viewport's* half-extent, not the slide's
+     * own, so at `slidesPerPage > 1` a fully on-screen outer page member
+     * can already read a large magnitude — this is not equivalent to
+     * `isInView` flipping to `false`. Mirrored live onto that slide's
+     * `--slide-progress` CSS custom property, rAF-batched. */
+    getSlideProgress: (slideIndex: number) => number;
+};
+/** Live progress snapshot reported by the carousel: the active page, the total page count, and a normalised `value` in `[0, 1]`. */
+export type CarouselProgress = {
+    page: number;
+    totalPages: number;
+    value: number;
+};
+/**
+ * Convenience wrapper that auto-renders one `Carousel.Indicator` per
+ * registered slide. Reuses the same discriminated label shape as
+ * `Carousel.IndicatorGroup`. `children` is reserved (the auto-mapped
+ * indicators take that slot) — drop down to `Carousel.IndicatorGroup`
+ * + `Carousel.Indicator` if you need custom indicator content.
+ */
+export type CarouselIndicatorsProps = Omit<ComponentProps<"div">, "label" | "aria-labelledby" | "children"> & ({
+    /** Accessible name for the indicator group, announced as
+     * `aria-label` (e.g. `"Choose slide"`). Mutually exclusive with
+     * `ariaLabelledBy`. */
+    label: string;
+    ariaLabelledBy?: never;
+} | {
+    label?: never;
+    /** Id of an existing element to name the indicator group, set as
+     * `aria-labelledby`. Mutually exclusive with `label`. */
+    ariaLabelledBy: string;
+}) & {
+    /** Forwarded to every generated `Carousel.Indicator`. See
+     * `CarouselIndicatorProps.readOnly`. Default `false`. */
+    readOnly?: boolean;
+};
+/**
+ * Render-prop or static children supported by
+ * `Carousel.PlayPauseTrigger`. The function form receives the live
+ * `playing` flag so consumers can swap icons / labels per state.
+ */
+export type CarouselPlayPauseTriggerChildren = ReactNode | ((state: {
+    playing: boolean;
+}) => ReactNode);
+/** Props for `Carousel.PlayPauseTrigger` — toggles autoplay; native `<button>` props with a state-aware render-prop `children` and `asChild`. */
+export type CarouselPlayPauseTriggerProps = Omit<ComponentProps<"button">, "children"> & {
+    children?: CarouselPlayPauseTriggerChildren;
+    /** Render the child element instead of the default `<button>`.
+     * The child must accept a `ref`. The render-prop form of `children`
+     * is not supported under `asChild`; pass a single element instead. */
+    asChild?: boolean;
+};
+/**
+ * Props for `Carousel.ProgressText` — renders the live active-page
+ * progress as text; native `<span>` props. `children`, if provided,
+ * overrides the default `translations.progressText` content. */
+export type CarouselProgressTextProps = ComponentProps<"span">;