@primitiv-ui/react 0.1.38 → 0.1.39

package/src/Carousel/README.md

@@ -1,1447 +0,0 @@
-# Carousel
-
-Headless, accessible **Carousel** built on native CSS scroll-snap. Implements
-the [WAI-ARIA Carousel pattern](https://www.w3.org/WAI/ARIA/apg/patterns/carousel/),
-ships zero styles, and is fully composable.
-
-The component is built incrementally under strict TDD. This README
-documents the surface that exists today.
-
-## Status
-
-Currently exposes:
-
-- **`Carousel.Root`** — labelled `<section>` wrapper with
-  `aria-roledescription="carousel"`.
-- **`Carousel.Viewport`** — slide container, rendered as a `<div>` with
-  a `data-carousel-viewport` attribute the recommended scroll-snap CSS
-  targets. Must be rendered as a descendant of `Carousel.Root`; rendering
-  it elsewhere throws a descriptive error. Also owns mouse click-and-drag
-  scrolling — pointerdown/pointermove track the pointer into
-  `scrollLeft`/`scrollTop` (amplified by a sensitivity multiplier) once
-  past a small movement threshold (so a link/button inside a slide still
-  receives a plain click), flipping a `data-dragging` styling hook for
-  the duration; release lets the
-  existing `scroll-snap-type` settle to the nearest slide, and a
-  horizontal (non-`Shift`) mouse-wheel notch translates to horizontal
-  scroll — see "JS vs CSS responsibilities" below for both.
-- **`Carousel.Slide`** — an individual slide. Renders a `<div role="group"
-aria-roledescription="slide">` and self-registers with the Root so each
-  slide knows its zero-based `data-index` and the live `data-total`
-  count, even as slides mount and unmount. Each slide is auto-labelled
-  `"N of M"` (e.g. `"1 of 3"`); pass `ariaLabel` to override with a more
-  meaningful description (e.g. `"Hand-picked for you"`). Emits
-  `data-state="active" | "inactive"` tracking the active page, plus a
-  `data-carousel-slide` CSS hook. Also emits
-  `data-snap-align="start" | "center" | "end"` on a page's leading slide
-  only (every slide, when `slidesPerPage` is 1), valued from its own
-  `snapAlign` prop if set, else the root's resolved `snapAlign` — the hook
-  consumer CSS should scope `scroll-snap-align` to, so an interior slide of
-  a multi-slide page is never a valid scroll-snap resting position, and the
-  native resting position agrees with `snapAlign` (see "Multi-slide snap
-  targeting" below). Pass `snapAlign` directly on a `Carousel.Slide` to
-  override the root default for that one slide (e.g. a variable-width
-  layout where only some slides should centre — matches Ark UI's per-`Item`
-  `snapAlign`).
-- **`Carousel.NextTrigger`** — `<button>` that advances the active page
-  by one. `disabled` at the last page, and whenever zero or one slides
-  are registered. Consumer `onClick` runs before the navigation;
-  consumer-supplied `disabled={true}` is honoured alongside the boundary
-  check.
-- **`Carousel.PreviousTrigger`** — `<button>` that retreats the active
-  page by one. `disabled` at the first page, with the same zero/one-slide
-  and consumer-`disabled` semantics as `NextTrigger`.
-- **`Carousel.IndicatorGroup`** — labelled `<div role="group">`
-  wrapping consumer-mapped indicator dots. Pass `label` (becomes
-  `aria-label`) or `ariaLabelledBy`; the discriminated union rejects
-  both-or-neither at compile time.
-- **`Carousel.Indicator`** — individual `<button>` dot. `index` prop
-  targets a zero-based page; clicking jumps to it. Auto-labelled
-  `"Slide N"`. The dot at the current page carries
-  `aria-disabled="true"` (a soft disable per the WAI-ARIA Carousel
-  APG); all dots emit `data-state="active" | "inactive"` and a
-  `data-carousel-indicator` CSS hook so consumer styles can paint the
-  active dot.
-- **`Carousel.Indicators`** — convenience wrapper that auto-renders
-  one `Carousel.Indicator` per registered slide. Reuses the same
-  discriminated `label` / `ariaLabelledBy` shape as `IndicatorGroup`.
-  For custom indicator content, drop down to `IndicatorGroup` +
-  `Indicator`.
-- **`Carousel.PlayPauseTrigger`** — `<button>` that toggles the
-  `playing` flag on Root. Auto-labels itself `"Start automatic slide
-show"` / `"Stop automatic slide show"` per the WAI-ARIA Carousel
-  APG, exposes a `data-state="playing" | "paused"` styling hook, and
-  passes `{ playing }` to a function `children` render prop so
-  consumers can swap icons or labels per state.
-
-Pass `autoplay` on `Carousel.Root` to advance the active page on a
-timer while `playing` is `true`. Hover, focus, and active-touch
-suspend the timer per the WAI-ARIA APG (with a user-initiated play
-override), and the viewport's `aria-live` region flips between
-`"polite"` and `"off"` so assistive tech doesn't announce every
-auto-rotation tick.
-
-## JS vs CSS responsibilities
-
-The component ships zero styles, but a few features sit on the line
-between JS and CSS. This table is the contract — the rule of thumb
-is that JS owns _what is the active page_ and _scrolls the viewport_
-(`viewport.scrollTo`, then the browser's CSS snap engine makes the final
-correction), and CSS owns _what the user sees_:
-
-| Feature                            | JS owns                                                  | CSS owns                                                                 |
-| ---------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------ |
-| Active page state                  | `page` / `defaultPage`, `onPageChange`, `goTo`           | —                                                                        |
-| Boundary clamping                  | `canGoNext` / `canGoPrevious`, trigger `disabled`        | —                                                                        |
-| Crossfade / scale / dissolve       | `data-state="active"` flip on slides                     | `position: absolute`, `opacity` + `transition`                           |
-| Slide layout & widths              | —                                                        | `flex-basis` / `inline-size`, `gap`, `aspect-ratio`                      |
-| Peek of adjacent slides            | `snapAlign` → viewport `scrollTo` alignment              | Viewport `padding-inline`, slide `flex-basis`, `scroll-snap-align`       |
-| Gap between slides                 | —                                                        | `gap` on the viewport (no `spacing` prop — pure CSS)                     |
-| Variable-size slides               | viewport `scrollTo` the target slide's offset            | Per-slide width / `aspect-ratio`, `scroll-snap-align`                    |
-| Snap targeting                     | `snapAlign: "start" \| "center" \| "end"` (Root default, overridable per-`Slide`) | `scroll-snap-type` on viewport, `scroll-snap-align` scoped to `[data-snap-align="start" \| "center" \| "end"]` |
-| Snap strictness                    | `snapType: "mandatory" \| "proximity"` (Root only)       | `scroll-snap-type` strictness scoped to `[data-snap-type="mandatory" \| "proximity"]` on the viewport |
-| Reduced motion                     | `behavior: "instant"`                                    | Optional `@media (prefers-reduced-motion: reduce)` on consumer animations |
-| Keyboard navigation                | Arrow / Home / End on focused viewport                   | `:focus-visible` on viewport                                             |
-| Touch / swipe                      | Native scroll + `scrollsnapchange` to sync state         | `overscroll-behavior-x: contain`, `scrollbar-width: none`                |
-| Mouse click-and-drag (`allowMouseDrag`, off by default) | `scrollLeft`/`scrollTop` set from the pointer delta × sensitivity | `cursor: grab`, `cursor: grabbing` on `[data-dragging]` |
-| Mouse-wheel scroll (horizontal)    | `deltaY` → `scrollLeft` when `deltaX` is negligible       | —                                                                        |
-| Overscroll (keyboard / wheel / drag) | `onOverscrollStatusChange`, `isOverscrolling()` (drag only) | Optional resistance visual on `[data-overscroll="start" \| "end"]` (drag only) |
-| Indicator state                    | `data-state` on `[data-carousel-indicator]`              | Visual: dot, bar, thumbnail, etc.                                        |
-| Continuous scroll progress         | `getScrollProgress()` / `getSlideProgress(index)`, rAF-batched | Reads `--carousel-progress` / `--slide-progress` for real-time effects, no re-render |
-
-The only JS prop on the visual side is `snapAlign`, and only because it
-picks whether the viewport `scrollTo` aligns the target slide's leading
-edge (`"start"`) or centres it (`"center"`) so the programmatic scroll
-lands where the browser's CSS snap engine will settle. Everything else is
-either a state knob (JS) or a visual rule (CSS), with no overlap.
-
-The scroll is issued on the **viewport element itself** (`viewport.scrollTo`),
-never `element.scrollIntoView()` — the latter walks every scrollable
-ancestor (including the page/window) and would scroll the whole document
-when a carousel is off-screen.
-
-The `apps/workbench` workbench at `/carousel` ships worked recipes for
-each cell of the matrix (single / multi / multi-step × slide / fade)
-plus peek, variable-size, and programmatic-control examples.
-
-## Usage
-
-Every carousel must have an accessible name. Pass exactly one of `ariaLabel`
-or `ariaLabelledBy`:
-
-```tsx
-import { Carousel } from "@primitiv-ui/react";
-
-<Carousel.Root ariaLabel="Featured products">
-  <Carousel.Viewport>
-    <Carousel.Slide>
-      <img src="/cube.png" alt="Cube" />
-    </Carousel.Slide>
-    <Carousel.Slide>
-      <img src="/sphere.png" alt="Sphere" />
-    </Carousel.Slide>
-  </Carousel.Viewport>
-  <Carousel.PreviousTrigger>Previous</Carousel.PreviousTrigger>
-  <Carousel.Indicators label="Choose slide" />
-  <Carousel.NextTrigger>Next</Carousel.NextTrigger>
-</Carousel.Root>;
-```
-
-```tsx
-<h2 id="promos">Promotions</h2>
-<Carousel.Root ariaLabelledBy="promos">...</Carousel.Root>
-```
-
-The discriminated union on the props type rejects shapes that supply both
-or neither at compile time.
-
-### Wrapping the slide container
-
-Slides go inside `Carousel.Viewport`:
-
-```tsx
-<Carousel.Root ariaLabel="Featured products">
-  <Carousel.Viewport>
-    <Carousel.Slide>First slide</Carousel.Slide>
-    <Carousel.Slide>Second slide</Carousel.Slide>
-    <Carousel.Slide>Third slide</Carousel.Slide>
-  </Carousel.Viewport>
-</Carousel.Root>
-```
-
-Each `Carousel.Slide` self-registers with the Root, so every slide
-exposes its own `data-index="0"`, `data-index="1"`, ... and a live
-`data-total` reflecting the current slide count. Add or remove slides at
-runtime and the indices and totals update automatically.
-
-Slides are also auto-labelled `"N of M"` (e.g. `"1 of 3"`) — the format
-the WAI-ARIA Carousel APG example uses. To override the auto-label with
-a more meaningful description, pass `ariaLabel`:
-
-```tsx
-<Carousel.Slide ariaLabel="Hand-picked for you">...</Carousel.Slide>
-```
-
-The override remains stable as siblings mount and unmount around it.
-
-### Navigating between slides
-
-`Carousel.NextTrigger` and `Carousel.PreviousTrigger` advance and retreat
-the active page. Each slide's `data-state` flips between `"active"` and
-`"inactive"` so consumer CSS can paint the current slide differently.
-
-#### Uncontrolled
-
-Pass `defaultPage` (or omit it for `0`); the Root owns the active page
-internally:
-
-```tsx
-<Carousel.Root ariaLabel="Featured products" defaultPage={0}>
-  <Carousel.Viewport>
-    <Carousel.Slide>First</Carousel.Slide>
-    <Carousel.Slide>Second</Carousel.Slide>
-    <Carousel.Slide>Third</Carousel.Slide>
-  </Carousel.Viewport>
-  <Carousel.PreviousTrigger>Previous</Carousel.PreviousTrigger>
-  <Carousel.NextTrigger>Next</Carousel.NextTrigger>
-</Carousel.Root>
-```
-
-#### Controlled
-
-Pass `page` and `onPageChange` together to lift state into the parent.
-The Root defers every state change back through the callback — clicks
-on `NextTrigger` / `PreviousTrigger` invoke `onPageChange` with the
-proposed page; the visual reflects whatever `page` value the parent
-re-renders with. Useful for syncing two carousels (e.g. a thumbnail
-strip), persisting the active page to a URL, or reacting to deep links.
-
-```tsx
-const [page, setPage] = useState(0);
-
-<Carousel.Root ariaLabel="Featured products" page={page} onPageChange={setPage}>
-  ...
-</Carousel.Root>;
-```
-
-The discriminated union on the props type rejects mixed shapes (e.g.
-both `defaultPage` and `page`, or `page` without `onPageChange`) at
-compile time.
-
-### Runtime validation
-
-`Carousel.PlayPauseTrigger` rendered under a Root with `autoplay`
-disabled (omitted, or `autoplay={false}`) throws on mount —
-toggling `playing` is meaningless when no autoplay timer is wired,
-and the throw surfaces the misuse during development rather than
-shipping a no-op control to users.
-
-`Carousel.Root` also throws once slides have registered if the
-active `page` (controlled or `defaultPage`-seeded) is negative or
-greater than or equal to the live `totalPages` —
-otherwise the carousel would render with no active slide. The throw
-is gated on `totalPages > 0` so transient zero-slide initial-render
-states don't false-alarm.
-
-### Lightbox composition (with `Modal`)
-
-Two `Carousel.Root`s sharing a controlled `page` stay in sync — pair
-a thumbnail strip with a fullscreen viewer mounted inside the
-in-tree `Modal`. Gate the inner carousel's `playing` flag on the
-modal's `open` so autoplay only runs while the modal is visible:
-
-```tsx
-const [page, setPage] = useState(0);
-const [open, setOpen] = useState(false);
-
-<>
-  <Carousel.Root
-    ariaLabel="Featured products — thumbnails"
-    page={page}
-    onPageChange={setPage}
-    slidesPerPage={3}
-  >
-    <Carousel.Viewport>
-      <Carousel.Slide>...</Carousel.Slide>...
-    </Carousel.Viewport>
-  </Carousel.Root>
-
-  <Modal.Root open={open} onOpenChange={setOpen}>
-    <Modal.Trigger>Open lightbox</Modal.Trigger>
-    <Modal.Portal>
-      <Modal.Content>
-        <Carousel.Root
-          ariaLabel="Featured products — fullscreen"
-          page={page}
-          onPageChange={setPage}
-          autoplay
-          playing={open}
-          onPlayingChange={() => {}}
-        >
-          <Carousel.Viewport>
-            <Carousel.Slide>...</Carousel.Slide>...
-          </Carousel.Viewport>
-          <Carousel.Indicators label="Choose slide" />
-        </Carousel.Root>
-      </Modal.Content>
-    </Modal.Portal>
-  </Modal.Root>
-</>;
-```
-
-`Carousel.Root` doesn't focus anything on mount, so the `Modal`'s
-focus management isn't disturbed when the inner carousel mounts.
-
-### Imperative API
-
-For programmatic control from outside the component (e.g. a global
-keyboard shortcut, a "skip to last slide" button elsewhere on the
-page, or restoring a remembered position on mount), `Carousel.Root`
-exposes an imperative handle via `ref`:
-
-```tsx
-const carouselRef = useRef<CarouselImperativeApi>(null);
-
-<Carousel.Root ref={carouselRef} ariaLabel="Featured products">
-  ...
-</Carousel.Root>;
-
-carouselRef.current?.next();
-carouselRef.current?.previous();
-carouselRef.current?.goTo(2);
-carouselRef.current?.scrollToIndex(5);
-carouselRef.current?.play();
-carouselRef.current?.pause();
-carouselRef.current?.refresh();
-const { page, totalPages, value } = carouselRef.current!.getProgress();
-const pageSnapPoints = carouselRef.current!.getPageSnapPoints();
-const isDragging = carouselRef.current!.isDragging();
-const scrollProgress = carouselRef.current!.getScrollProgress(); // 0..1, continuous
-const slideProgress = carouselRef.current!.getSlideProgress(0); // -1..1, continuous
-```
-
-`next()`, `previous()`, and `goTo()` each take an optional trailing
-`instant` boolean (default `false`) that bypasses the resolved
-smooth/reduced-motion scroll for **just that one call** — matching Ark
-UI's `scrollNext(instant?)` / `scrollPrev(instant?)` /
-`scrollTo(page, instant?)`. Useful for e.g. an instant jump when
-restoring a remembered position on mount, followed by ordinary smooth
-navigation from then on:
-
-```tsx
-carouselRef.current?.goTo(rememberedPage, true); // instant, no animation
-carouselRef.current?.next(); // smooth, as usual
-```
-
-The override never outlives the single call it's passed to — a plain
-`next()` / `previous()` / `goTo()` right after always falls back to
-the normal resolved behavior (`prefers-reduced-motion`-aware smooth
-scrolling by default).
-
-`scrollToIndex(slideIndex, instant?)` is the slide-granularity
-counterpart to `goTo`'s page granularity — matching Ark UI's
-`scrollToIndex(index, instant?)`. In a plain single-slide-per-page
-carousel the two are equivalent; the distinction matters once
-`slidesPerPage > 1`, where an interior slide of a page isn't itself a
-scroll-snap position — `scrollToIndex` maps the given slide index to
-its *containing* page (the same mapping `Carousel.Indicator` uses
-internally) rather than requiring you to compute the page yourself.
-It takes the same optional `instant` override as `next` / `previous` /
-`goTo`.
-
-`refresh()` re-issues the viewport's `scrollTo` for the current
-page — useful when external layout changes (window resize, container
-reflow, dynamic content) leave the scroll position misaligned with
-React state. `getProgress()` returns a normalised
-`value` in `[0, 1]` (`0` when there's at most one page) plus the
-live `page` and `totalPages`, intended for custom progress bars.
-`getPageSnapPoints()` returns the leading slide index each page snaps
-to (one entry per page, length `totalPages`) — the same offset
-formula the carousel uses internally, including the end-aligned last
-page for multi-slide layouts whose total isn't a whole number of
-pages (see "Multi-slide pages and partial page advance" below).
-Useful for a custom progress bar or indicator built from the raw
-offsets instead of just the page count. `isDragging()` is a live
-snapshot of whether a mouse drag is in progress (always `false`
-unless `allowMouseDrag` is set) — see "Drag status" below for the
-matching `onDragStatusChange` callback. For a ready-made rendered
-progress announcement instead of building one from `getProgress()`
-yourself, see "Progress text" below. `getScrollProgress()` and
-`getSlideProgress(slideIndex)` are a *continuous* complement to
-`getProgress()`'s page-granular step function — see "Continuous scroll
-progress" below.
-
-Every method routes through the same internal state machine the
-trigger components use, so controlled-mode `onPageChange` /
-`onPlayingChange` callbacks fire just as if the user had clicked.
-`play()` also dismisses the hover/focus pause for the lifetime of
-that playing session, matching the WAI-ARIA APG semantics for
-user-initiated play.
-
-### `asChild` composition
-
-`Carousel.NextTrigger`, `Carousel.PreviousTrigger`,
-`Carousel.PlayPauseTrigger`, and `Carousel.Indicator` all accept an
-`asChild` prop. When set, the trigger renders the consumer's child
-element via the in-tree `Slot` (instead of its default `<button>`)
-and merges every trigger prop — `onClick`, `aria-label`,
-`aria-disabled`, `data-state`, custom `id`, etc. — onto it. Useful
-for routing links and other elements that need trigger semantics:
-
-```tsx
-<Carousel.NextTrigger asChild>
-  <a href="/products?page=2">Next</a>
-</Carousel.NextTrigger>
-```
-
-Because `<a>` and other non-button elements don't honour the HTML
-`disabled` attribute, the prev/next triggers also short-circuit
-their click handler when boundary clamping says "no further" — so
-asChild on a non-button still respects the boundary clamp.
-
-### Snap alignment
-
-By default the Viewport scrolls so the target slide **centres** in the
-scroll container — matching `scroll-snap-align: center` in consumer CSS.
-For layouts where the leading (or trailing) edge should align instead —
-e.g. a classic edge-to-edge gallery — set `snapAlign="start"` (or
-`"end"`) so programmatic navigation lands on that position without the
-browser snap-correcting after the scroll:
-
-```tsx
-<Carousel.Root ariaLabel="Gallery" snapAlign="start">
-  ...
-</Carousel.Root>
-```
-
-`Carousel.Slide` publishes the resolved value as
-`data-snap-align="start" | "center" | "end"` (on each valid resting slide —
-see "Multi-slide snap targeting" below), so pair it with
-`[data-snap-align="start"] { scroll-snap-align: start }` in your CSS
-rather than hardcoding `scroll-snap-align: start` — that way the
-native snap the user's own scroll settles into always agrees with
-`snapAlign`, not just the programmatic `scrollTo`. The default is
-`"center"`; `snapAlign` picks whether the viewport `scrollTo` aligns the
-target slide's leading edge (`"start"`), centres it (`"center"`), or
-aligns its trailing edge (`"end"`), and the browser's CSS snap engine
-makes the final correction.
-
-**Per-slide override.** `Carousel.Slide` also accepts its own `snapAlign`,
-overriding the root default for just that slide — useful for a
-variable-width layout where only some slides should start- or end-align
-(matches Ark UI's per-`Item` `snapAlign`, which is where the `"end"` value
-comes from too — the root-level prop above has no Ark equivalent):
-
-```tsx
-<Carousel.Root ariaLabel="Gallery">
-  <Carousel.Viewport>
-    <Carousel.Slide>Regular, centre-aligned</Carousel.Slide>
-    <Carousel.Slide snapAlign="start">This one aligns to its leading edge</Carousel.Slide>
-  </Carousel.Viewport>
-</Carousel.Root>
-```
-
-The override only takes effect on a slide that's actually 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 (see "Multi-slide
-snap targeting" below).
-
-### Snap strictness
-
-`snapType` (default `"mandatory"`) is the raw `scroll-snap-type`
-strictness — pass `"proximity"` for a looser, free-scrolling feel where
-the browser only nudges toward a snap point near where the scroll
-ends, rather than always forcing a rest on one:
-
-```tsx
-<Carousel.Root ariaLabel="Gallery" snapType="proximity">
-  ...
-</Carousel.Root>
-```
-
-`Carousel.Viewport` publishes the resolved value as
-`data-snap-type="mandatory" | "proximity"`; pair it with
-`[data-snap-type="proximity"] { scroll-snap-type: x proximity }` (`y`
-when `orientation="vertical"`) in your CSS. Matches Ark UI's `snapType`.
-
-### Orientation
-
-By default the carousel pages along the **inline (horizontal) axis**.
-Pass `orientation="vertical"` to page along the **block (vertical)
-axis** instead:
-
-```tsx
-<Carousel.Root ariaLabel="Featured products" orientation="vertical">
-  ...
-</Carousel.Root>
-```
-
-`orientation` is behavioural, not cosmetic — the primitive ships no
-layout. It changes three things:
-
-- **Scroll axis.** Programmatic paging scrolls the viewport on the
-  `top` (block) axis instead of `left` (inline), leaving the cross axis
-  untouched,
-  and the user-swipe sync reads `snapTargetBlock` off `scrollsnapchange`
-  instead of `snapTargetInline`.
-- **Keyboard.** The viewport pages on `ArrowDown` / `ArrowUp` (the
-  horizontal arrows go inert). See [Keyboard navigation](#keyboard-navigation).
-- **Styling hook.** The resolved value is published as
-  `data-orientation="horizontal" | "vertical"` on the rendered
-  `<section>`, so a single selector can switch your layout to a column
-  viewport with `scroll-snap-type: y mandatory`:
-
-```css
-[data-orientation="vertical"] [data-carousel-viewport] {
-  flex-direction: column;
-  overflow-block: auto;
-  overflow-inline: hidden;
-  scroll-snap-type: y mandatory;
-}
-```
-
-The vertical viewport needs a bounded block-size (a height) for the
-scroll axis to exist — give the root or viewport an explicit
-`block-size` / `aspect-ratio`.
-
-### Transition modes
-
-`Carousel.Root` accepts a `transition` prop that controls how the
-viewport handles slide changes visually. The resolved value is
-published on the Root as `data-transition` so consumer CSS can switch
-the visual off a single hook (mirroring `data-orientation`).
-
-- `transition="slide"` (default) — relies on native CSS scroll-snap.
-  The Viewport scrolls programmatically when the page changes and
-  listens for `scrollsnapchange` so user swipes update React state.
-- `transition="fade"` — installs no scroll wiring (like `"none"`), but
-  names the intent so a styled surface can ship a crossfade by default.
-  Native swipe/drag and peek don't apply (there's no scroll to swipe);
-  controls, indicators, and keyboard paging still work.
-- `transition="none"` — the Viewport installs no scroll wiring at
-  all and no default visual is implied. Consumer CSS owns the visual
-  via the `data-state="active" | "inactive"` hook on each slide, which
-  still flips with the active page.
-
-Both `"fade"` and `"none"` are the entry point for crossfade, dissolve,
-zoom, or any CSS-only transition pattern — stack the slides and drive
-opacity/transform off `data-state`, keyed off the `data-transition`
-hook so the scroll-snap layout isn't affected:
-
-```css
-[data-transition="fade"] [data-carousel-slide] {
-  grid-area: 1 / 1; /* stack every slide in one cell */
-  opacity: 0;
-  transition: opacity 400ms;
-}
-[data-transition="fade"] [data-carousel-slide][data-state="active"] {
-  opacity: 1;
-}
-```
-
-### Reduced motion
-
-The Viewport's programmatic `scrollTo` reads
-`window.matchMedia("(prefers-reduced-motion: reduce)")` once on
-mount. When the user has reduced motion enabled at the OS level,
-page changes use `behavior: "instant"` instead of `"smooth"` so the
-carousel doesn't fight that preference. Touch-driven scrolling is
-unaffected — the browser owns that animation. The imperative API's
-per-call `instant` override (see "Imperative API" above) composes
-with this — it forces `"instant"` for one call regardless of the
-resolved preference, while every other call still follows it.
-
-### Programmatic scroll sync
-
-When the active page changes for any reason (`Carousel.NextTrigger` /
-`Carousel.PreviousTrigger` click, indicator click, autoplay tick),
-the viewport `scrollTo`s to the first slide of the new page (by its
-measured offset — not `element.scrollIntoView()`, which would scroll the
-whole document when the carousel is off-screen) so the visual surface
-tracks React state. Consumer CSS owns slide width and gap, and
-`scroll-snap-align` makes the final correction. Default `behavior` is
-`"smooth"`.
-
-The reverse path is also wired: when the user swipes the viewport,
-the browser fires `scrollsnapchange` with the snapped slide as the
-target. The Viewport listens for that event, maps the snapped slide
-back to its page (grouping by `slidesPerPage` in `"auto"` mode, or
-rounding to the nearest window start in numeric `slidesPerMove` mode,
-clamped so an end-aligned tail slide lands on the last page), and calls
-`goTo` so React state follows the user's scroll. `onPageChange` is only
-invoked when the page genuinely changes, so a snap that lands back on
-the active page doesn't dispatch a spurious callback.
-
-For browsers without `scrollsnapchange`, the same path runs against
-an `IntersectionObserver` (threshold `0.6` by default — see
-`inViewThreshold` below) on each slide — when the observer fires, the
-lowest-index visible slide derives the active page via the same
-slide-index-to-page mapping. This page-drive is **only** a fallback:
-when `scrollsnapchange` is supported it is authoritative (it reports
-the precisely-snapped slide), so the observer stands down and does
-not also drive the page. That matters for `snapAlign="center"`
-carousels with several slides visible at once (e.g. a cover flow) —
-the lowest-index-visible heuristic would otherwise track the
-*leftmost* visible slide rather than the centred one and fight
-`scrollsnapchange`. The observer still always feeds `Carousel.Root`'s
-imperative `isInView(slideIndex)` so consumers can lazy-load slide
-content based on actual visibility, not just the active-page index.
-
-**`inViewThreshold`.** Pass a number or an array of numbers on
-`Carousel.Root` to override the default `0.6`:
-
-```tsx
-<Carousel.Root ariaLabel="Featured products" inViewThreshold={0.3}>
-```
-
-The value is passed straight through as the `IntersectionObserver`'s
-own `threshold` option. For the single "is this slide in view"
-boolean that `isInView` reports (and that the page-drive fallback
-above reads), a plain number is used directly as the cutoff; an array
-uses its **highest** value — the strictest crossing counts as
-genuinely in view, since multiple thresholds otherwise only exist to
-fire the observer's callback more often, not to change what "in view"
-means.
-
-### Custom DOM ids
-
-For SSR / hydration stability or external `aria-controls` linkage,
-pin DOM `id`s on the rendered sub-components via the `ids` bag on
-`Carousel.Root`:
-
-```tsx
-<Carousel.Root
-  ariaLabel="Featured products"
-  ids={{
-    root: "promo-carousel",
-    viewport: "promo-viewport",
-    previousTrigger: "promo-prev",
-    nextTrigger: "promo-next",
-    playPauseTrigger: "promo-play-pause",
-    indicatorGroup: "promo-indicators",
-  }}
->
-  ...
-</Carousel.Root>
-```
-
-Any keys you omit leave the corresponding element unidentified. A
-direct `id` prop on a sub-component (e.g.
-`<Carousel.NextTrigger id="...">`) wins over `ids.*` because it spreads
-last.
-
-### Internationalisation
-
-The component owns four user-visible strings: each slide's auto-
-generated `aria-label` (`"N of M"`), each indicator's auto-generated
-`aria-label` (`"Slide N"`), and the two `Carousel.PlayPauseTrigger`
-accessible names (`"Start automatic slide show"` and
-`"Stop automatic slide show"`). Override any subset of them via the
-`translations` prop on `Carousel.Root`:
-
-```tsx
-<Carousel.Root
-  ariaLabel="Produits en vedette"
-  translations={{
-    slideLabel: ({ index, total }) => `${index} sur ${total}`,
-    indicatorLabel: ({ index }) => `Diapositive ${index}`,
-    startSlideshow: "Démarrer le diaporama",
-    stopSlideshow: "Arrêter le diaporama",
-  }}
->
-  ...
-</Carousel.Root>
-```
-
-`slideLabel` and `indicatorLabel` are functions (they receive
-position info), the slideshow names are plain strings. Any keys you
-omit fall back to the English defaults. Per-slide `ariaLabel`
-overrides on `Carousel.Slide` still take precedence over
-`translations.slideLabel`, so a single slide can carry a
-domain-meaningful label (e.g. `"Hand-picked for you"`) without
-losing the localised `"N of M"` format on the others.
-
-### Multi-slide pages and partial page advance
-
-Pass `slidesPerPage` (default `1`) to make several slides visible per
-page — the "image carousel" / "property cards" pattern. By default,
-`Carousel.NextTrigger` / `Carousel.PreviousTrigger` advance one
-full page at a time (`slidesPerMove="auto"`):
-
-```tsx
-<Carousel.Root ariaLabel="Featured products" slidesPerPage={3}>
-  <Carousel.Viewport>
-    <Carousel.Slide>1</Carousel.Slide>
-    <Carousel.Slide>2</Carousel.Slide>
-    <Carousel.Slide>3</Carousel.Slide>
-    <Carousel.Slide>4</Carousel.Slide>
-    <Carousel.Slide>5</Carousel.Slide>
-  </Carousel.Viewport>
-  <Carousel.PreviousTrigger>Previous</Carousel.PreviousTrigger>
-  <Carousel.Indicators label="Choose page" />
-  <Carousel.NextTrigger>Next</Carousel.NextTrigger>
-</Carousel.Root>
-```
-
-With `slidesPerPage={3}` and 5 slides:
-
-- Total pages = `ceil(5 / 3) === 2`. `Carousel.Indicators` renders 2
-  dots.
-- Page 0 contains slides 0–2; page 1 **end-aligns** to slides 2–4 (a
-  full window flush with the track end, not a partial `[3,4]`). A
-  partial last page's leading slide can't align to the viewport start,
-  so it would snap to the previous slide and desync the active page —
-  end-aligning keeps every page a full, cleanly-snapping window (7
-  slides at `slidesPerPage={3}` → `[0,1,2] [3,4,5] [4,5,6]`).
-- Each slide on the active page emits `data-state="active"`; slides
-  on other pages emit `"inactive"`.
-- `Carousel.NextTrigger` advances one page per click; the boundary
-  clamp is at the last page (so Next is disabled while page 1 is
-  active).
-
-The slide-level `aria-label="N of M"` continues to count individual
-slides (so a 5-slide carousel announces "1 of 5", "2 of 5", ... even
-when grouped into 3-per-page).
-
-Pass a numeric `slidesPerMove` to advance the visible window by an
-arbitrary slide count per click instead of a full page:
-
-```tsx
-<Carousel.Root
-  ariaLabel="Featured products"
-  slidesPerPage={3}
-  slidesPerMove={1}
->
-  ...
-</Carousel.Root>
-```
-
-With `slidesPerPage=3`, `slidesPerMove=1`, and 5 slides, the active
-window slides one slide at a time — pages show `[0,1,2]`, `[1,2,3]`,
-`[2,3,4]`, so `Carousel.Indicators` renders 3 dots and the boundary
-clamp respects the last full window. The indicator count formula is
-`ceil((total - slidesPerPage) / slidesPerMove) + 1` (vs.
-`ceil(total / slidesPerPage)` for `"auto"`), so the visible window
-always stays full in numeric mode.
-
-**The last window is end-aligned.** When the move doesn't divide the
-track evenly, the final page snaps to the track end rather than dropping
-the remainder — so every slide is always reachable. With
-`slidesPerPage={3}`, `slidesPerMove={2}`, and 6 slides the pages are
-`[0,1,2]`, `[2,3,4]`, `[3,4,5]` (the last shifts back by one to include
-slide 5) — never `[0,1,2]`, `[2,3,4]` with slide 5 orphaned.
-
-**Bounds are guarded.** `slidesPerPage` is coerced to an integer ≥ 1 and
-a numeric `slidesPerMove` to an integer in `[1, slidesPerPage]`, so a
-consumer passing `0`, a negative, a fraction, `NaN`, or a move larger
-than a page can never divide by zero, skip past a page (orphaning the
-slides in the gap), or make the carousel inert — it degrades to the
-nearest sane layout.
-
-### Boundary behaviour
-
-The prev/next triggers clamp at the ends: `Carousel.PreviousTrigger` is
-`disabled` at the first slide, `Carousel.NextTrigger` at the last. Both
-are also `disabled` when zero or one slides are registered, since
-there's nowhere to navigate.
-
-### Loop (wrap-around navigation)
-
-Pass `loop` to make navigation wrap around instead of clamping. `loop`
-is a **mode selector** — a boolean for ergonomics, or a named mode:
-
-```tsx
-<Carousel.Root ariaLabel="Featured products" loop>            {/* = "wrap" */}
-<Carousel.Root ariaLabel="Featured products" loop="wrap">     {/* semantic wrap */}
-<Carousel.Root ariaLabel="Featured products" loop="infinite"> {/* continuous infinite */}
-```
-
-| `loop`                    | Resolved `data-loop` | Behaviour                                  |
-| ------------------------- | -------------------- | ------------------------------------------ |
-| omitted / `false`         | `"none"`             | Clamp at the ends (triggers disable).      |
-| `true` / `"wrap"`         | `"wrap"`             | Semantic wrap (visible rewind).            |
-| `"infinite"`              | `"infinite"`         | Continuous infinite (no rewind).           |
-
-In every wrapping mode:
-
-- `Carousel.NextTrigger` on the last page advances to the first;
-  `Carousel.PreviousTrigger` on the first page retreats to the last.
-- Neither trigger `disabled`s at a boundary (the arrow keys wrap too,
-  since they route through the same `next` / `previous`).
-- **Autoplay keeps rotating past the last page** rather than stopping —
-  the natural pairing for an auto-rotating hero.
-
-A single page has no wrap target, so the triggers stay `disabled`
-regardless of `loop`. The resolved mode is published as
-`data-loop="none" | "wrap" | "infinite"` on the Root (mirroring
-`data-orientation` / `data-transition`) for consumer CSS.
-
-**`"wrap"` vs `"infinite"`.** Both share the same page model (the wrap
-arithmetic and never-disable boundaries). They differ only in the visual:
-`"wrap"` smooth-scrolls the whole track back on a last→first wrap (a visible
-rewind, the same path `Home` takes), while `"infinite"` glides one step on
-with no rewind.
-
-Under `loop="infinite"` the Viewport is **not** a scroll container. It clips
-a **JS transform track** (`data-carousel-track`) laid out as one contiguous,
-periodic strip: the real slides are flanked by a full period of `aria-hidden`,
-`inert` **clones** each side (`[clones] [real slides] [clones]`), so every seam
-is already-painted DOM. Navigation only ever translates the **whole track** — no
-slide moves relative to it — and when a glide carries past the last real slide
-onto a clone, the settle **re-bases** the track by exactly one period so the
-identical real slide sits at the same pixels. Because the strip is periodic, the
-re-base reveals nothing unrasterised and moves nothing (RFC 0018, clone-strip
-revision), which is what structurally removes the iOS seam flash a per-slide fill
-could never avoid. Every page change glides the track via a GPU-composited CSS
-`transform` transition, but the **path differs by kind**: a *relative* step
-(Prev / Next, the arrow keys, autoplay) always takes the **short way** —
-continuing forward off the last slide onto the clone rather than rewinding
-across the whole strip — while a *direct jump to a specific page* (an
-indicator/thumbnail click, or `goTo()` / `scrollToIndex()`) takes the
-**literal** distance between the two slides instead, even when the ring's
-wrap would be shorter: picking the last indicator from the first visibly
-travels forward through every slide in between, matching the indicators' own
-reading order, rather than silently rewinding one step the other way around
-the ring. The first positioning is instant (no glide on load).
-`prefers-reduced-motion` sets the offset instantly with no transition.
-
-The glide's **duration and easing** are read off the track from the
-`--primitiv-carousel-glide-duration` and `--primitiv-carousel-glide-easing` custom
-properties, so a consumer retunes the feel purely in CSS (the registry stylesheet
-defaults them to motion tokens and ships `--glide-fast/medium/slow` presets). With
-no stylesheet the engine falls back to a built-in `500ms` ease-out. Every slide is
-also promoted to its own compositor layer (`transform: translateZ(0)` in the
-registry sheet) so its rounded, clipped bitmap is painted before it scrolls in — no
-iOS entering-edge white — while the engine windows the painted set (far slides are
-`visibility: hidden`) to keep that layer count bounded.
-
-The engine **re-measures on a `ResizeObserver`** (watching the track and the
-slides), so it self-heals when the container resizes or a size-affecting knob
-changes at runtime — `peek`, the slide `ratio`, ambient density, a multi-slide
-`gap` — re-homing the track to the current page and re-running the paint window
-against the fresh geometry. (A change that resizes *no* box — e.g. a single-slide
-`gap`, which only alters the between-slide spacing — isn't observable; call the
-imperative `refresh()` after one of those, or it self-corrects on the next
-navigation.)
-
-**Touch / mouse drag.** The track follows the pointer 1:1 (transition off), and
-on release a velocity-projected **fling** snaps to the nearest **page** boundary
-with the same glide, updating the active page from where it lands. With
-`slidesPerPage > 1` the snap is a whole page, so a multi-slide fling advances (or
-holds) a full page rather than settling mid-page and being jerked to the page
-lead. Touch drag is always
-on (there's no native scroll to fall back to); mouse drag stays opt-in via
-`allowMouseDrag`. A tap under a small threshold still reaches a link / button
-inside a slide.
-
-**Direction, peek and multi-slide.** The engine is axis- and direction-generic:
-it reads the sign of the measured stride as the axis direction, so an **RTL**
-loop mirrors every move (no rewind) — including `snapAlign`, whose `start` / `end`
-swap so the reading start stays the right edge — and it cancels the track's own
-inset so **peek** / viewport padding stays centred. **Multi-slide**
-(`slidesPerPage > 1`)
-glides to each page's leading slide, so Prev / Next advance a whole page and wrap
-cleanly; the inter-slide gap returns between the on-screen pair (single-slide
-stays gapless so the gap never flashes through the viewport mid-glide). The gap
-is scoped by the `data-slides-per-page` hook the engine sets on the track.
-
-No slide is ever individually transformed — the strip only ever slides as a unit,
-so there are no per-slide layers to flash. The track is **not** force-promoted to
-one permanent GPU layer either (2D `translate`, no `backface-visibility`): the
-clone strip is several viewports wide, and iOS Safari rasterises a large permanent
-layer in tiles on demand, blanking slides at rest until they fill in. Letting the
-browser composite the transition on the GPU but rasterise the visible region
-normally at rest — like native scroll — sidesteps that.
-
-This is the same transform + clone approach Embla and Swiper use. It replaced two
-earlier attempts that each flashed on iOS: a native-scroll-snap **clone buffer**
-(the native snap fought the teleport) and a clone-free per-slide `wrapShift` fill
-(individual slides teleported, which iOS can't pre-rasterise). Keeping the clones
-but driving them purely in JS — no native snap, no per-slide moves — removes both
-failure modes at once.
-
-> The track geometry is browser-only (jsdom reports no layout), so it ships
-> unit-tested with mocked geometry, and real-browser tested in Playwright.
-
-### Keyboard navigation
-
-`Carousel.Viewport` is in the tab order so keyboard users can reach the
-rotation control without first tabbing through every slide's
-interactive content. With the Viewport focused:
-
-| Key                   | Action                                          |
-| --------------------- | ----------------------------------------------- |
-| `ArrowRight` / `ArrowDown` | Advance by one page (same as `NextTrigger`)     |
-| `ArrowLeft` / `ArrowUp`    | Retreat by one page (same as `PreviousTrigger`) |
-| `Home`                | Jump to the first page                          |
-| `End`                 | Jump to the last page                           |
-
-The paging arrows follow the [orientation](#orientation): `ArrowRight` /
-`ArrowLeft` for the default horizontal axis, `ArrowDown` / `ArrowUp` when
-`orientation="vertical"` (the off-axis arrows go inert). `Home` / `End`
-work in both. Arrow keys clamp at the boundaries, mirroring the trigger
-buttons — or wrap around when [`loop`](#loop-wrap-around-navigation) is
-set. Keypresses are only intercepted when the Viewport itself is the
-focus target — focus inside a slide (e.g. on a link or form control)
-keeps its native arrow-key semantics.
-
-```tsx
-<Carousel.Root ariaLabel="Featured products">
-  <Carousel.Viewport>
-    <Carousel.Slide>First</Carousel.Slide>
-    <Carousel.Slide>Second</Carousel.Slide>
-    <Carousel.Slide>Third</Carousel.Slide>
-  </Carousel.Viewport>
-  <Carousel.PreviousTrigger>Previous</Carousel.PreviousTrigger>
-  <Carousel.NextTrigger>Next</Carousel.NextTrigger>
-</Carousel.Root>
-```
-
-Consumer-supplied `disabled={true}` on either trigger is honoured
-regardless of boundary state — useful for momentarily freezing
-navigation while another part of the UI takes over.
-
-### Mouse input
-
-Two mouse interactions ship on `Carousel.Viewport` alongside the native
-touch/trackpad scroll that already worked with zero custom code (the
-scroll-driven `scrollsnapchange` sync doesn't care how the viewport got
-scrolled):
-
-- **Click-and-drag** — **opt-in** via `allowMouseDrag` on `Carousel.Root`
-  (default `false`; an unconditionally-on drag could conflict with a
-  consumer's own drag-sensitive slide content — a nested carousel, a
-  draggable card, a canvas). When enabled: click and hold on the viewport,
-  drag, and it scrolls like a swipe — `scrollLeft`/`scrollTop` track the
-  pointer, amplified by a 2× sensitivity multiplier so a full-slide
-  transition doesn't require dragging the slide's full on-screen width
-  (still no momentum/flick — the multiplier only scales the tracked
-  delta, motion stops dead on release) once the drag clears a small
-  (3px) movement threshold — below the threshold nothing happens, so a
-  plain click on a
-  link or button inside a slide still reaches it. Releasing the pointer
-  lets the existing `scroll-snap-type` settle to the nearest slide, exactly
-  like a touch swipe — no extra "scroll → state" wiring needed, the
-  `scrollsnapchange` sync already covers it. A `data-dragging` attribute is
-  set on the viewport for the duration of an active drag (see "Recommended
-  CSS" for the `cursor: grab` / `grabbing` pairing). Ignores non-mouse
-  pointer types (`touch`, `pen`) even when enabled — native scroll already
-  handles those. Also suppresses the browser's own native image/link drag
-  (the semi-transparent ghost that follows the cursor) on the viewport via
-  `preventDefault()` on `dragstart` — real `<img>`/`<a>` slide content is
-  natively draggable, and without this its native HTML5 drag would visually
-  compete with the custom pointer-drag above. Only active while
-  `allowMouseDrag` is on; native drag is left untouched otherwise.
-- **Mouse-wheel scroll.** A physical wheel's vertical notches
-  (`deltaY`) already natively scroll a `orientation="vertical"`
-  carousel — nothing needed there. But browsers only auto-translate a
-  plain vertical wheel to horizontal scroll when `Shift` is held, so the
-  default horizontal orientation gets no scroll at all from a plain
-  wheel without help: the Viewport translates `deltaY` into `scrollLeft`
-  whenever `deltaX` is negligible. A trackpad or Magic Mouse horizontal
-  swipe already produces real `deltaX` and already scrolls a horizontal
-  viewport natively (the same mechanism as touch) — the translation
-  stands down whenever `deltaX` is non-negligible so it never fights
-  that. `deltaY` is normalized from `DOM_DELTA_LINE` / `DOM_DELTA_PAGE`
-  units to pixels first, so a physical wheel's larger, fewer ticks feel
-  proportional to a trackpad's many small pixel-mode ones.
-
-Both stand down when `transition` isn't `"slide"` (the viewport isn't a
-scrolling track in `"fade"` / `"none"` mode).
-
-### Drag status
-
-The `data-dragging` DOM hook above is enough for CSS, but a consumer
-reacting in JS — e.g. pausing a video in the active slide while the
-user drags — needs the imperative `isDragging()` and/or the
-`onDragStatusChange` callback (both only ever reachable when
-`allowMouseDrag` is `true`; matches Ark UI's `api.isDragging` /
-`onDragStatusChange`):
-
-```tsx
-const carouselRef = useRef<CarouselImperativeApi>(null);
-
-<Carousel.Root
-  ref={carouselRef}
-  ariaLabel="Featured products"
-  allowMouseDrag
-  onDragStatusChange={({ type, page, isDragging }) => {
-    // type: "dragging.start" | "dragging" | "dragging.end"
-  }}
->
-  ...
-</Carousel.Root>;
-
-carouselRef.current?.isDragging(); // live snapshot, read on demand
-```
-
-`onDragStatusChange` fires `"dragging.start"` the moment a drag crosses
-the click-vs-drag movement threshold, `"dragging"` on every subsequent
-pointer move while it's still active, and `"dragging.end"` on release
-(`pointerup` or `pointercancel`) — never for a plain click that never
-crossed the threshold. `page` is the live active page at that moment.
-
-### Overscroll
-
-Pushing against a boundary with nowhere further to go — via the
-keyboard, the wheel, or a mouse drag — fires `Carousel.Root`'s
-`onOverscrollStatusChange`:
-
-```tsx
-<Carousel.Root
-  ariaLabel="Featured products"
-  allowMouseDrag
-  onOverscrollStatusChange={({ type, edge, source, amount, page }) => {
-    // type: "overscroll.start" | "overscroll" | "overscroll.end"
-    // edge: "start" | "end"
-    // source: "keyboard" | "wheel" | "drag"
-  }}
->
-  ...
-</Carousel.Root>;
-```
-
-Detection is driven by the same page-boundary truth
-(`canGoNext`/`canGoPrevious`) as everything else in the primitive, from
-three input sources the carousel already 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 horizontal-desktop wheel-to-scroll translation (see
-  "Mouse input" above), blocked at a boundary.
-- **Mouse drag** — a 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 — either a reversal back within bounds mid-drag,
-or the drag ending — mirroring `onDragStatusChange`'s shape. A drag
-overscroll also sets a persistent `data-overscroll="start" | "end"`
-attribute on the Viewport for the same duration — a CSS hook for a
-rubber-band resistance visual, with no JS required. For the live
-imperative equivalent of `isDragging()`, `isOverscrolling()` reports
-whether a drag is currently pushing past a boundary (always `false` for
-a keyboard/wheel tap, which is instantaneous rather than a sustained
-state).
-
-**Native touch/swipe overscroll is out of scope.** OS-level rubber-
-banding when a touch swipe is dragged past a boundary is browser-owned
-scroll physics with no JS hook to observe it from — consistent with
-this primitive's "native scroll is the source of truth" approach
-elsewhere (see "Mouse input" above, and "Reduced motion").
-
-### Continuous scroll progress
-
-`getProgress()` and `isInView()` are both coarse — a page-granular step
-function and a threshold boolean, respectively. For a continuous signal
-(a parallax effect, a cover-flow-style scale/rotate, a custom progress
-bar that fills smoothly instead of stepping), `Carousel.Root` exposes
-two additional getters, each mirrored live onto a CSS custom property so
-a consumer's stylesheet can read them directly without touching
-JavaScript at all:
-
-```tsx
-carouselRef.current!.getScrollProgress(); // 0 (start) .. 1 (end)
-carouselRef.current!.getSlideProgress(0); // -1 .. 0 (centered) .. 1
-```
-
-```css
-/* on the Viewport */
-.my-progress-bar {
-  transform: scaleX(var(--carousel-progress));
-}
-
-/* on each Slide */
-.my-slide {
-  opacity: calc(1 - abs(var(--slide-progress)));
-}
-```
-
-`--carousel-progress` (on the Viewport) mirrors `getScrollProgress()` —
-how far the viewport has scrolled along its main axis, `0` at the start
-and `1` at the end (`0` when there's no overflow to scroll at all).
-`--slide-progress` (on each Slide) mirrors `getSlideProgress(index)` —
-`0` when that slide's center coincides with the viewport's center, `±1`
-when the slide's center has reached the viewport edge (clamped beyond
-that). Both recompute on every scroll tick and on viewport/slide resize,
-coalesced to at most once per animation frame so a fast native scroll
-never forces more than one layout read per frame.
-
-`getSlideProgress` is normalised by the **viewport's** half-extent, not
-the slide's own — at `slidesPerPage > 1` a page's outer members can
-already read a large magnitude (e.g. ~±0.67 at three-per-page) while
-still fully on-screen and settled. This is *not* the same signal as
-`isInView` flipping to `false`: `isInView` is an IntersectionObserver
-threshold crossing, while `getSlideProgress` is raw geometry — a slide
-can read a large `getSlideProgress` magnitude and still be fully
-`isInView`, or vice versa near a partial-visibility threshold.
-
-`getScrollProgress()` is robust under RTL with no `dir` check: modern
-browsers standardize RTL `scrollLeft` on the "negative" convention (`0`
-at the start, down to the negative of the max scroll at the end), so the
-implementation takes the absolute value before normalising — the same
-reasoning that lets the mouse-drag handler skip RTL special-casing (see
-"Mouse input" above).
-
-**Under `loop="infinite"`**, this effect stands down (nothing ever
-scrolls — the engine translates the track via a JS transform instead),
-so `--slide-progress` is driven by the infinite engine itself: analytically
-on every discrete paint (an instant move, or any of a drag's many calls),
-plus a live-reading rAF ticker for the duration of an animated glide so
-the drift keeps pace with the track's own CSS transition rather than
-snapping to the settled value once it ends. This covers every CSS
-consumer of `--slide-progress` (parallax included) — the imperative
-**`getSlideProgress()` / `getScrollProgress()` getters are not** (they
-still only read what the native-scroll effect last wrote, so they read
-frozen under infinite); reach for the CSS custom property there instead.
-There is also no infinite equivalent of `--carousel-progress` — a
-0 (start) .. 1 (end) reading has no natural definition for a loop with
-no start or end.
-
-### Indicator dots (manual)
-
-For full control over indicator content, map them yourself with
-`Carousel.IndicatorGroup` + `Carousel.Indicator`. Each dot's `index`
-prop targets a zero-based page; clicking jumps to it.
-
-```tsx
-<Carousel.IndicatorGroup label="Choose slide">
-  <Carousel.Indicator index={0} />
-  <Carousel.Indicator index={1} />
-  <Carousel.Indicator index={2} />
-</Carousel.IndicatorGroup>
-```
-
-Indicators are auto-labelled `"Slide N"` (1-indexed). The dot at the
-current page carries `aria-disabled="true"` per the WAI-ARIA APG and
-`data-state="active"`; non-active dots carry `aria-disabled="false"`
-and `data-state="inactive"`. Style them via the
-`data-carousel-indicator` attribute and the `data-state` hook:
-
-```css
-[data-carousel-indicator][data-state="active"] {
-  background: black;
-}
-```
-
-### Play / pause control
-
-`Carousel.PlayPauseTrigger` toggles a `playing` flag on the Root. The
-flag has the same controlled / uncontrolled split as `page`:
-
-```tsx
-// Uncontrolled
-<Carousel.Root ariaLabel="Featured products" defaultPlaying={false}>
-  <Carousel.PlayPauseTrigger />
-</Carousel.Root>;
-
-// Controlled
-const [playing, setPlaying] = useState(false);
-<Carousel.Root
-  ariaLabel="Featured products"
-  playing={playing}
-  onPlayingChange={setPlaying}
->
-  <Carousel.PlayPauseTrigger />
-</Carousel.Root>;
-```
-
-The discriminated union rejects mixed shapes (e.g. `defaultPlaying` +
-`playing`, or `playing` without `onPlayingChange`) at compile time.
-
-Pass a function as `children` to swap icons or labels per state:
-
-```tsx
-<Carousel.PlayPauseTrigger>
-  {({ playing }) => (playing ? <PauseIcon /> : <PlayIcon />)}
-</Carousel.PlayPauseTrigger>
-```
-
-The trigger is auto-labelled `"Start automatic slide show"` (paused)
-or `"Stop automatic slide show"` (playing) for assistive tech, and
-emits `data-state="playing" | "paused"` for consumer CSS.
-
-### Autoplay timer
-
-Pass `autoplay` on `Carousel.Root` to advance the active page on a
-timer while `playing` is `true`:
-
-```tsx
-// Default 4000ms cadence
-<Carousel.Root ariaLabel="Featured products" autoplay defaultPlaying>
-  ...
-</Carousel.Root>
-
-// Custom delay
-<Carousel.Root
-  ariaLabel="Featured products"
-  autoplay={{ delay: 6000 }}
-  defaultPlaying
->
-  ...
-</Carousel.Root>
-```
-
-The timer reads from the live `playing` flag and the active page —
-toggling pause via `Carousel.PlayPauseTrigger` (or via the controlled
-`onPlayingChange`) cancels the next tick. The timer stops once the
-active page reaches the last slide.
-
-The timer also pauses automatically while the user is hovering the
-Root or has focus on a descendant element, per WCAG 2.2.2 (Pause,
-Stop, Hide). Focus moving between descendants of the Root (e.g.
-tabbing from `Previous` to `Next`) keeps the pause active; the timer
-only resumes once the pointer leaves and focus has moved out of the
-carousel entirely. The `playing` flag is unaffected — it stays
-`true` while suspended, so toggling pause-resume via
-`PlayPauseTrigger` continues to behave as the consumer expects.
-
-Touch gestures pause the timer too: `pointerdown` with
-`pointerType === "touch"` sets the suspension flag, and any
-`pointerup` or `pointercancel` releases it. Mouse / pen
-`pointerdown` is filtered out so the existing hover/focus path
-keeps owning non-touch interaction without double-suspension.
-
-**User-initiated play overrides the hover/focus pause.** Per the
-WAI-ARIA Carousel APG example, when the user explicitly clicks
-`PlayPauseTrigger` to start the slideshow, the hover/focus pause is
-suspended for the lifetime of that playing session — otherwise the
-user would fight a pause every time their pointer was already over
-the carousel when they pressed play. The override resets when
-`playing` flips back to `false` (via another click, or via an
-external state change), so a subsequent play that's _not_ user-
-initiated falls back to the standard WCAG pause.
-
-**Viewport live region.** `Carousel.Viewport` is also the live region
-for slide changes. Its `aria-live` defaults to `"polite"` so paged
-manual navigation is announced to assistive tech, and flips to
-`"off"` while autoplay is actively rotating (`autoplay` enabled and
-`playing=true`) so screen readers aren't spammed with every tick.
-The flip is reactive — pausing via `PlayPauseTrigger` returns the
-viewport to `"polite"` for the duration of the pause.
-
-### Autoplay status
-
-The `playing` flag and `data-state` on `PlayPauseTrigger` cover
-play/pause toggles, but a consumer reacting to the timer itself in JS
-— e.g. logging analytics on every autoplay rotation — needs the
-`onAutoplayStatusChange` callback (only ever reachable when
-`autoplay` is enabled; matches Ark UI's `onAutoplayStatusChange`):
-
-```tsx
-<Carousel.Root
-  ariaLabel="Featured products"
-  autoplay
-  defaultPlaying
-  onAutoplayStatusChange={({ type, page, isPlaying }) => {
-    // type: "autoplay.start" | "autoplay" | "autoplay.stop"
-  }}
->
-  ...
-</Carousel.Root>
-```
-
-`onAutoplayStatusChange` fires `"autoplay.start"` the moment the timer
-becomes active (autoplay enabled, `playing` true, another page
-remains, not suspended by hover/focus/touch), `"autoplay"` on every
-tick while it stays active, and `"autoplay.stop"` when the timer stops
-running — whether because `playing` flipped `false`, the last page was
-reached, or hover/focus/touch suspended it. `page` is the active page
-at that moment.
-
-### Progress text
-
-`getProgress()` on the imperative API gives you the raw
-`{ page, totalPages, value }` data, but wiring an actual rendered
-announcement (`"1 of 3"`) yourself every time is boilerplate.
-`Carousel.ProgressText` renders it for you, formatted by
-`translations.progressText` (matches Ark UI's `Carousel.ProgressText`
-anatomy part):
-
-```tsx
-<Carousel.Root ariaLabel="Featured products">
-  <Carousel.Viewport>...</Carousel.Viewport>
-  <Carousel.ProgressText />
-</Carousel.Root>
-```
-
-Renders `"1 of 3"` by default (1-indexed, matching `slideLabel`); pass a
-`progressText` formatter through `translations` (a
-`({ page, totalPages }) => ...` function) on the Root to customise the
-format, or `children` on `Carousel.ProgressText`
-itself to render something else entirely (an icon alongside the
-count, say) instead of the computed text. `Carousel.ProgressText`
-carries no ARIA wiring of its own — compose it inside your own live
-region if you want page changes announced; this mirrors Ark's
-unopinionated `progressText` part rather than duplicating the
-Viewport's own `aria-live` toggling (see "Autoplay timer" above).
-
-### Indicator dots (auto-rendered)
-
-For the common case of one dot per slide with auto-generated labels,
-use `Carousel.Indicators` — it reads the live slide count from
-context and renders the right number of dots without any mapping
-boilerplate:
-
-```tsx
-<Carousel.Root ariaLabel="Featured products">
-  <Carousel.Viewport>
-    <Carousel.Slide>1</Carousel.Slide>
-    <Carousel.Slide>2</Carousel.Slide>
-    <Carousel.Slide>3</Carousel.Slide>
-  </Carousel.Viewport>
-  <Carousel.Indicators label="Choose slide" />
-</Carousel.Root>
-```
-
-The dot count tracks slide count automatically — add or remove a
-slide and the indicator row updates on the next render. For custom
-indicator content (thumbnails, numbers, mixed icons), drop down to
-the manual `IndicatorGroup` + `Indicator` API above.
-
-### Read-only (presentational) indicators
-
-Pass `readOnly` when the dots are a progress display rather than a
-navigation control — e.g. a carousel driven solely by
-[`allowMouseDrag`](#mouse-input), where clickable dots would be a
-redundant, confusing second way to navigate:
-
-```tsx
-<Carousel.Indicators label="Progress" readOnly />
-// or, on a manually-mapped dot:
-<Carousel.Indicator index={0} readOnly />
-```
-
-A `readOnly` indicator renders a `<span>` instead of a `<button>`
-(no button semantics), carries `aria-hidden="true"` (it's decorative
-and not announced to assistive tech), and no longer calls `goTo`
-when clicked. It still tracks `data-state="active" | "inactive"`, so
-the same CSS that paints a normal indicator keeps working. A
-consumer's own `onClick` on an individual `Indicator`, if passed,
-still fires — only the internal navigation is suppressed. On
-`Carousel.Indicators`, `readOnly` forwards to every generated dot.
-
-## Recommended CSS
-
-The component ships zero styles. The recipe below is the minimum
-needed to get a working horizontal carousel with snap-aligned slides,
-dot indicators, and sane mobile behaviour. Drop it into your stylesheet
-and target the `data-carousel-*` attributes:
-
-```css
-[data-carousel-viewport] {
-  display: flex;
-  overflow-x: auto;
-  scroll-snap-type: x mandatory;
-  scroll-behavior: smooth;
-  /* Prevent vertical page scroll from "rubber-banding" into the
-     carousel and vice-versa on iOS. */
-  overscroll-behavior-x: contain;
-  /* Hide native scrollbars on mobile while keeping scroll behaviour. */
-  scrollbar-width: none;
-}
-[data-carousel-viewport]::-webkit-scrollbar {
-  display: none;
-}
-
-[data-carousel-slide] {
-  flex: 0 0 100%;
-  scroll-snap-align: start;
-}
-
-/* Stop the OS picking up an image for drag/save during a swipe. Repeated on
-   the media element itself, not just the slide wrapper — -webkit-user-drag
-   isn't inherited, so a real <img>'s own native drag-source eligibility is
-   unaffected by an ancestor's value. WebKit-only (no Firefox equivalent);
-   pair with `allowMouseDrag`, which also `preventDefault()`s the drag start
-   in JS for full cross-browser coverage. */
-[data-carousel-slide],
-[data-carousel-slide] > img,
-[data-carousel-slide] > video,
-[data-carousel-slide] > picture,
-[data-carousel-slide] > picture > img {
-  -webkit-user-drag: none;
-}
-
-/* WCAG 2.5.8: 24×24 minimum hit area; 44×44 recommended for comfort
-   on phones. The visible dot stays small via ::before so the button's
-   hit area can be larger than its visual footprint. */
-[data-carousel-indicator] {
-  min-width: 44px;
-  min-height: 44px;
-  display: inline-grid;
-  place-items: center;
-}
-[data-carousel-indicator]::before {
-  content: "";
-  width: 0.5rem;
-  height: 0.5rem;
-  border-radius: 50%;
-  background: lightgray;
-}
-[data-carousel-indicator][data-state="active"]::before {
-  background: black;
-}
-```
-
-For multi-slide pages (`slidesPerPage={3}`, etc.), tune the slide's
-`flex-basis` to share the viewport — e.g. `calc(100% / 3)` for three
-slides per page, plus a `gap` on the viewport for the inter-slide
-spacing. **Scope `scroll-snap-align` to `[data-snap-align]` instead of
-every `[data-carousel-slide]`** once `slidesPerPage > 1` — see
-"Multi-slide snap targeting" below; the recipe above is correct as-is
-for the single-slide-per-page default, where every slide carries the
-hook. For a crossfade transition, use `transition="none"` on
-`Carousel.Root` and style the slides absolute-positioned with an
-opacity transition keyed off `[data-carousel-slide][data-state="active"]`.
-
-### Multi-slide snap targeting
-
-When `slidesPerPage > 1`, only a page's *leading* slide is a valid
-scroll-snap resting position — an interior slide has no page of its
-own, so letting the browser's mandatory snap stop there leaves the
-viewport showing a straddled mix of two pages while `currentPage` (and
-any indicators driven from it) still claim a single clean page is
-active. This is easy to hit with incremental input — a mouse wheel
-notch or a drag release — that lands mid-page rather than jumping a
-full page at once. Scope `scroll-snap-align` to the `data-snap-align`
-hook (present only on each page's leading slide, and on every slide
-when `slidesPerPage` is 1) rather than applying it to every slide. Its
-*value* mirrors the root's resolved `snapAlign` — or the individual
-slide's own override (`Carousel.Slide`'s `snapAlign` prop), if it set
-one — so a user's own scroll (wheel/touch/drag) settles wherever the
-programmatic scroll already targets. Style all three values, not just
-`"start"`, if the consumer might set `snapAlign="center"` / `"end"` on
-the root or on individual slides:
-
-```css
-[data-carousel-slide] {
-  flex: 0 0 calc(100% / 3); /* three slides per page, for example */
-}
-[data-carousel-slide][data-snap-align="start"] {
-  scroll-snap-align: start;
-}
-[data-carousel-slide][data-snap-align="center"] {
-  scroll-snap-align: center;
-}
-[data-carousel-slide][data-snap-align="end"] {
-  scroll-snap-align: end;
-}
-```
-
-**Centering/ending a multi-slide page, not just its leading slide.** A
-`scroll-snap-align` on a single element only ever aligns *that* element's
-own box — `scroll-snap-align: center` on the leading slide would centre
-just the leading slide, leaving the rest of a `slidesPerPage > 1` page
-clipped off the trailing edge, if that were the whole story. It isn't:
-the Viewport also sets `scroll-margin-inline-end` (`-block-end` when
-vertical) on each page's leading slide, extending its native snap area —
-invisibly, with no layout effect — out to the page's actual last member.
-So `scroll-snap-align: center`/`"end"` end up centering/ending the whole
-page, matching what the programmatic `scrollTo` already does. This is
-automatic and needs no consumer CSS; it's a no-op when `slidesPerPage` is
-1 (the leading slide already *is* the whole page).