@primitiv-ui/react 0.1.28 → 0.1.29

package/src/Carousel/types.ts

@@ -7,8 +7,20 @@ import { ComponentProps, ReactNode, RefObject } from "react";
  * rejects shapes that supply both or neither.
  */
 export type CarouselRootLabelProps =
-  | { ariaLabel: string; ariaLabelledBy?: never }
-  | { ariaLabel?: never; ariaLabelledBy: string };
+  | {
+      /** 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,
@@ -87,18 +99,46 @@ export type CarouselRootPlayingStateProps =
 export type CarouselAutoplay = boolean | { delay: number };
 
 /**
- * Visual transition mode for the viewport.
+ * 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.
- * - `"none"` — the Viewport installs no scroll wiring at all.
- *   Consumer CSS owns the visual transition (e.g. crossfade,
- *   dissolve) via the `data-state` hook on each slide, which still
- *   flips with the active page.
+ * - `"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" | "none";
+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
@@ -112,8 +152,135 @@ export type CarouselTransition = "slide" | "none";
  *   `(viewportWidth − slideWidth) / 2`. Use this with
  *   `scroll-snap-align: center` in consumer CSS (e.g. Cover Flow
  *   layouts 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 CarouselSnapAlign = "start" | "center";
+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
@@ -151,6 +318,10 @@ export type CarouselTranslations = {
   /** 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. */
@@ -170,13 +341,27 @@ export type CarouselRootProps = Omit<
      * 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. */
+     * `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 computed so
-     * the visible window always stays full. */
+     * `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. */
@@ -191,6 +376,60 @@ export type CarouselRootProps = Omit<
      * `scroll-snap-align: center` on slides (e.g. Cover Flow layouts
      * 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;
   };
 
 /**
@@ -209,12 +448,33 @@ export type CarouselContextValue = {
   /** 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 (default `1`). */
+  /** 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. */
+   * `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`
@@ -231,13 +491,17 @@ export type CarouselContextValue = {
   /** `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`. */
-  next: () => void;
-  /** Retreat the active page by one step. No-op when `!canGoPrevious`. */
-  previous: () => void;
+  /** 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. */
-  goTo: (target: number) => void;
+   * `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`. */
@@ -260,8 +524,27 @@ export type CarouselContextValue = {
   ids: CarouselIds;
   /** Resolved visual transition mode (defaults to `"slide"`). */
   transition: CarouselTransition;
-  /** Resolved scroll-snap alignment (defaults to `"start"`). */
+  /** 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;
@@ -271,12 +554,55 @@ export type CarouselContextValue = {
   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. */
@@ -289,6 +615,13 @@ export type CarouselSlideProps = Omit<ComponentProps<"div">, "aria-label"> & {
    * (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`. */
@@ -316,14 +649,31 @@ export type CarouselIndicatorGroupProps = Omit<
   "label" | "aria-labelledby"
 > &
   (
-    | { label: string; ariaLabelledBy?: never }
-    | { label?: never; ariaLabelledBy: string }
+    | {
+        /** 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
@@ -338,12 +688,27 @@ export type CarouselIndicatorProps = ComponentProps<"button"> & {
  * fire as if the user had clicked.
  */
 export type CarouselImperativeApi = {
-  /** Advance the active page by one. No-op on the last page. */
-  next: () => void;
-  /** Retreat the active page by one. No-op on the first page. */
-  previous: () => void;
-  /** Jump directly to `target` (zero-based page index). */
-  goTo: (target: number) => void;
+  /** 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;
@@ -361,6 +726,42 @@ export type CarouselImperativeApi = {
    * 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]`. */
@@ -382,9 +783,24 @@ export type CarouselIndicatorsProps = Omit<
   "label" | "aria-labelledby" | "children"
 > &
   (
-    | { label: string; ariaLabelledBy?: never }
-    | { label?: never; ariaLabelledBy: string }
-  );
+    | {
+        /** 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
@@ -406,3 +822,9 @@ export type CarouselPlayPauseTriggerProps = Omit<
    * 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">;

package/src/Checkbox/Checkbox.tsx

@@ -50,6 +50,8 @@ function dataStateOf(checked: CheckedState) {
  * mirror the input, but shipped CSS keys the mark off the input's native
  * `:checked` / `:indeterminate` instead; `data-state` is a convenience mirror.
  *
+ * @extends HTMLInputElement
+ *
  * @example Uncontrolled
  * ```tsx
  * <Checkbox.Root name="terms" value="accepted" defaultChecked aria-label="Accept terms">
@@ -120,7 +122,11 @@ export function CheckboxRoot(props: CheckboxRootProps): ReactElement {
   );
 }
 
-/** @internal */
+// Runtime-dead: the compound alias below (same object via Object.assign)
+// overwrites this to "Checkbox" at load, so the value is never observable. The
+// assignment stays because it declares `displayName` on `typeof CheckboxRoot`,
+// which TCheckboxCompound extends.
+// Stryker disable next-line StringLiteral: overwritten by the compound alias — an equivalent mutant.
 CheckboxRoot.displayName = "CheckboxRoot";
 
 /**
@@ -138,6 +144,8 @@ CheckboxRoot.displayName = "CheckboxRoot";
  * (typically an `<svg>` tick) as the indicator itself, with `data-state`
  * merged onto that element rather than a wrapper.
  *
+ * @extends HTMLSpanElement
+ *
  * @example Icon as the indicator via `asChild`
  * ```tsx
  * <Checkbox.Indicator asChild>