An open source design system that's fully customizable and agent ready
TypeScript
spec(Carousel): opt-in snap paging through useSnapPaging (#9666)
Cindy Zhangb779b269c2ab
diff --git a/docs/architecture/public-component-api.md b/docs/architecture/public-component-api.mdindex 5e3f6a4f38..45fe0812f9 100644--- a/docs/architecture/public-component-api.md+++ b/docs/architecture/public-component-api.md@@ -444,6 +444,15 @@ Known verification gaps:another keeps its name until a minor renames it under INV9. Outline's`offset` is the distance below the top of its scroll root(`component:Outline` FR4), not a gap from an anchor.+- INV3: Carousel `hasSnap` takes `boolean | SnapPaging`. Omitted or `false` does+ not snap, `true` is native scroll snap, and a value from `useSnapPaging` is+ snap paging. It is a known deviation from three rules: an `is…` or `has…`+ boolean names only a true on/off with no third state (INV3); a prop that+ chooses how a component responds to input is a `<thing>Behavior` closed union+ (INV2); and a behavior that differs by device offers a per-device value+ (INV3), where the paging value pages under a finger and a trackpad swipe and+ keeps native snap under a mouse wheel. It keeps one snap prop for builders+ (`component:Carousel/DEC-2`) and is not renamed.- INV22: known gaps include `useLongPress`, `usePressFeedback`,`useClickableContainer`, `useInputContainer`, `useOverlay`, `useCombobox`,`useMultiCombobox`, `useResizable`, `useTooltip`, `useHoverCard`, anddiff --git a/docs/specs/AST-094-touch-presentations/spec.md b/docs/specs/AST-094-touch-presentations/spec.mdindex 00379f4087..68d6e47bc8 100644--- a/docs/specs/AST-094-touch-presentations/spec.md+++ b/docs/specs/AST-094-touch-presentations/spec.md@@ -128,8 +128,9 @@ a measured, sourced difference exists.measures (0.55 for a scroll view and a sheet), and a release MUST pick itsrest point by projecting its velocity the way its UIKit counterpart does:with a deceleration rate, or with a measured projection time.- A paging scroll view (the pager, and Carousel with `hasSnap` where the- pager runs) picks its rest page as its UIKit counterpart measures it, with no+ A paging scroll view (the pager, and a Carousel given+ `hasSnap={useSnapPaging()}` where the pager runs, an opt-in under+ `component:Carousel` FR7) picks its rest page as its UIKit counterpart measures it, with noprojection: the nearest page, or the next page in the release's directionwhen the release is at least `paging.release.advanceSpeed` (300 pt/s) fast,at any position on the page. It moves at most@@ -1339,7 +1340,7 @@ Rejected: cancelling moves only after the pan begins.**Reference:** `spec:AST-094/DEC-25`**Decider:** `cixzhang`, `2026-11-01`-A pager, Carousel with `hasSnap` where the pager runs, and Lightbox's gallery pick the rest page and+A pager, a Carousel given `hasSnap={useSnapPaging()}` where the pager runs, and Lightbox's gallery pick the rest page andstart the settle as UIKit's paging scroll view does on iOS 26.2. UIKitchooses the page by a speed threshold, the same 300 pt/s at 10, 25 and 40 %of a page, not by a projection, and starts a slow release's settle from rest.diff --git a/docs/specs/components/Carousel/Carousel.spec.md b/docs/specs/components/Carousel/Carousel.spec.mdindex 73fe470016..dd8e2672d3 100644--- a/docs/specs/components/Carousel/Carousel.spec.md+++ b/docs/specs/components/Carousel/Carousel.spec.md@@ -9,7 +9,7 @@ superseded_by: nullapproved_by: cixzhangapproved_at: 2026-10-22owners: [cixzhang]-review_triggers: [behavior, accessibility]+review_triggers: [behavior, accessibility, public-api]verified_by:[packages/core/src/Carousel/Carousel.test.tsx,@@ -18,40 +18,49 @@ verified_by:modules: []families: [family:buttons]design_specs: []-architecture: [architecture:interaction-modality]+architecture:+ [+ architecture:interaction-modality,+ architecture:public-component-api,+ architecture:react-component-runtime,+ ]contributing: []-system_specs: [spec:AST-085, spec:AST-025]+system_specs: [spec:AST-085, spec:AST-025, spec:AST-094]---# Carousel component contract## Contract at a glance-| Area | Contract |-| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |-| Public contract | None changes. |-| Behavior | An edge scroll button whose direction has run out is hidden and takes no tab stop. When the focused edge button runs out, focus moves to the scroll area. |-| End-user impact | A keyboard user who scrolls to the first or last item stays inside the carousel instead of landing on the page body or on an invisible control. The scroll area is a group named like the carousel (`spec:AST-025` FR12), so screen-reader users hear where they landed. |-| Builder impact | None. |-| Compatibility/readiness | No API change. Shipped Carousel and its current tests still use native `disabled` and hand focus to the opposite button; they change with conformance work. |-| Review checks | Reject focus left on a hidden edge button, focus dropped to the page body, or an edge handoff that moves focus to anything but the scroll area. |-| Governing rules | `spec:AST-085` FR1, FR4; `spec:AST-025` FR12; `architecture:interaction-modality` INV1. |+| Area | Contract |+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| Public contract | `hasSnap` takes `boolean \| SnapPaging` (FR5). `hasSnap` or `hasSnap={true}` turns on native CSS scroll snap, exactly as released (FR6). `hasSnap={useSnapPaging()}` turns on snap paging: native snap's stops with UIKit's paging feel under a finger or a trackpad swipe (FR7). `useSnapPaging` has no non-React equivalent by default (FR9). The edge scroll buttons hide and hand off focus at an edge (FR1–FR4). |+| Behavior | Native snap stops each item at its start edge and leaves the momentum to the platform. Snap paging uses the same stops: under a finger, and on a trackpad swipe under every pointer, a flick moves one view by default, or one item with `{pages: 'item'}`, by `spec:AST-094` FR3's paging rule. An edge button whose direction has run out is hidden and takes no tab stop; when the focused one runs out, focus moves to the scroll area. |+| End-user impact | People who swipe a paging carousel on a phone feel iOS paging; people on a carousel without it download no paging code. A keyboard user who scrolls to the first or last item stays inside the carousel. |+| Builder impact | `hasSnap` and `hasSnap={true}` are unchanged. Paging is the same prop given `useSnapPaging()`. A Carousel without the paging config bundles no pager code. |+| Compatibility/readiness | Additive: `hasSnap`'s type widens from `boolean` to `boolean \| SnapPaging`, with no rename, deprecation, or codemod; `true` keeps today's native snapping and gains no paging. Implementation gap: the widened `hasSnap` and `useSnapPaging` are not built; shipped Carousel still uses native `disabled` on edge buttons. Evidence gap: `{pages: 'item'}` is not measured against UIKit's group paging (FR7). |+| Review checks | Reject pager code reachable from Carousel's default import; a lazy `import()` of the pager; snap paging on a carousel whose `hasSnap` is not a `useSnapPaging` value; `hasSnap={true}` that pages; snap paging stops that differ from native snap's; a claim that `{pages: 'item'}` matches UIKit before it is measured; a dependency on a Chromium-only carousel feature; focus left on a hidden edge button. |+| Governing rules | `spec:AST-094` FR3, FR6, FR43, DEC-25; `architecture:public-component-api` INV3 (a known deviation, DEC-2), INV22; `architecture:react-component-runtime` INV13; `spec:AST-085` FR1, FR4; `spec:AST-025` FR12; `architecture:interaction-modality` INV1. |This table is a review projection; the body below is authoritative.## IntentCarousel shows a horizontally scrolling row of items inside a labelled region,-with optional scroll buttons at each edge. This record covers only what the edge-scroll buttons do when their direction runs out. Other Carousel behavior is-uncontracted until this record grows.+with optional scroll buttons at each edge. This record covers how the row snaps,+the opt-in snap paging, and what the edge scroll buttons do when their direction+runs out. Other Carousel behavior is uncontracted until this record grows.## Compatibility and migration-- Released default preserved: yes, except where focus lands at an edge.-- Compatibility class: behavior correction; no API change.+- Released default preserved: yes. `hasSnap` and `hasSnap={true}` keep their+ released native snapping and gain no paging. A carousel whose `hasSnap` is+ omitted or `false` does not snap.+- Compatibility class: additive API. `hasSnap`'s type widens from `boolean` to+ `boolean | SnapPaging`, and `useSnapPaging` is new; no rename, deprecation, or+ codemod. Edge focus is a behavior correction with no API change.- Controlled/uncontrolled behavior: unchanged.-- Migration decision: DEC-1.+- Migration decision: DEC-1 (edge focus), DEC-2 (snap and snap paging).Consumer migration instructions belong in consumer docs and release notes.@@ -59,39 +68,61 @@ Consumer migration instructions belong in consumer docs and release notes.**Owns**+- The `hasSnap` prop, its native snap and its snap paging value, and the+ `useSnapPaging` API.+- Which stops snap paging uses on a carousel, and what one page is (FR7).- Edge scroll button visibility, tab order, and the focus destination when oneruns out.**Does not own / non-goals**+- The paging rule, the settle, and their measured values — `spec:AST-094` FR3,+ FR6, DEC-25.+- The internal pager that snap paging and Lightbox's gallery share —+ `spec:AST-094`; it stays internal.- Scroll area keyboard access and naming — `spec:AST-025`.- Disabled control semantics in general — `spec:AST-085`.- Button naming, sizing, and activation — `family:buttons`.-- Looping, snapping, edge fades, and slide semantics — uncontracted.+- Looping, mouse-drag paging, autoplay, dots, edge fades, and slide semantics —+ uncontracted.## Public concepts-| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |-| ------------------ | ----------------------- | -------------------------------------------------- | ----------------------------------------- | ------- | -------------------- | --------- | ---------------------- |-| Edge scroll button | available, run out | Whether content remains in that button's direction | Both edges when the carousel overflows | — | `component:Carousel` | stable | not applicable |+| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |+| ------------------------- | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | ----------------- | -------------------- | --------- | -------------------------------------------- |+| `hasSnap` | `false`, `true`, a `SnapPaging` value | Omitted or `false`: no snap. `true`: native CSS scroll snap (FR6). A `SnapPaging` value: snap paging on native snap's stops (FR7) | Every Carousel | `false` | `component:Carousel` | stable | TypeScript rejects other values |+| `useSnapPaging(options?)` | returns `SnapPaging` | The hook whose value turns on snap paging. Exported from `@astryxdesign/core/SnapPaging` and the package root | React callers | — | `component:Carousel` | stable | — |+| `SnapPaging` | opaque | The configured snap paging. Callers make it only with `useSnapPaging` and pass it only to `hasSnap` | — | — | `component:Carousel` | stable | — |+| `SnapPagingOptions` | `{pages?: 'view' \| 'item'}` | Options for the hook. `pages` sets what one flick moves (FR7). A field is added only by a current record | — | `{pages: 'view'}` | `component:Carousel` | stable | TypeScript rejects unknown fields and values |+| Edge scroll button | available, run out | Whether content remains in that button's direction | Both edges when the carousel overflows | — | `component:Carousel` | stable | not applicable |## Behavioral and layout contract-| ID | Candidate invariant | Basis | Draft review state |-| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | ------------------ |-| FR1 | An edge scroll button whose direction has run out is hidden. While hidden it takes no tab stop and is not exposed to assistive technology. It stays mounted so layout does not shift. This is removal under `spec:AST-085` FR4, not a disabled control. | DEC-1 | settled |-| FR2 | When the focused edge scroll button runs out, focus moves to the scroll area without scrolling it. This holds when the content no longer overflows and the scroll area is out of the tab order (`spec:AST-025` FR12): it still takes focus programmatically. Focus never lands on the page body or on a hidden button. | DEC-1; `spec:AST-085` FR4 | settled |-| FR3 | The handoff happens once per edge transition, and only while the edge button held focus. An edge reached by swipe, resize, or wheel while focus is elsewhere moves nothing. | `architecture:interaction-modality` INV8 | settled |-| FR4 | An edge scroll button that is available behaves as an ordinary Button. | `family:buttons` | settled |+| ID | Candidate invariant | Basis | Draft review state |+| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | ------------------ |+| FR1 | An edge scroll button whose direction has run out is hidden. While hidden it takes no tab stop and is not exposed to assistive technology. It stays mounted so layout does not shift. This is removal under `spec:AST-085` FR4, not a disabled control. | DEC-1 | settled |+| FR2 | When the focused edge scroll button runs out, focus moves to the scroll area without scrolling it. This holds when the content no longer overflows and the scroll area is out of the tab order (`spec:AST-025` FR12): it still takes focus programmatically. Focus never lands on the page body or on a hidden button. | DEC-1; `spec:AST-085` FR4 | settled |+| FR3 | The handoff happens once per edge transition, and only while the edge button held focus. An edge reached by swipe, resize, or wheel while focus is elsewhere moves nothing. | `architecture:interaction-modality` INV8 | settled |+| FR4 | An edge scroll button that is available behaves as an ordinary Button. | `family:buttons` | settled |+| FR5 | `hasSnap` takes `boolean \| SnapPaging`. Omitted or `false`: the scroll area does not snap. `true` (written `hasSnap`): native snap, FR6, exactly as released, with no gesture code. A `SnapPaging` value, made only by `useSnapPaging`: snap paging, FR7; the carousel snaps on native snap's per-item stops and the pager settles on those same stops. `true` never pages. A new `SnapPaging` value on a later render does not restart a settle or attach the gesture again. The third state is a known deviation from `architecture:public-component-api` INV3, which keeps a `has…` boolean to a true on/off (DEC-2). | DEC-2 | settled |+| FR6 | Native snap uses CSS scroll snap only: mandatory snap along the row on the scroll area, each direct child snapping at its start edge, and scroll padding matching the carousel's padding. Every item is a stop, also when several items show at once, and the platform's own momentum picks where a swipe rests. The current page reported is the page snapped into view when scrolling settles, and edge-button availability follows every scroll, momentum and programmatic included, and every resize. Native snap adds no gesture code. It does not depend on `::scroll-button()`, `::scroll-marker`, `:target-current`, scroll-state container queries, snap events, or `interactivity: inert`; one of these MAY be added under `@supports` only where it changes no behavior, name, role, or focus order. | DEC-2 | settled |+| FR7 | Snap paging uses native snap's stops (FR6): each direct child's start edge, measured from the inline start and mirrored in right-to-left layout, with the last stops clamped where the row ends so no empty space shows. A gap sits between stops and is never a stop. Under a finger, and on a trackpad swipe under every pointer (`spec:AST-094` FR43), a release picks its rest page by `spec:AST-094` FR3's paging rule: at most one page from the page the drag started on. The settle starts as `spec:AST-094` FR6's paging paragraph says. With the paging config, a flick moves one view by default: the release settles on the item start edge nearest one viewport on in the flick's direction, and the last page rests where the row ends; `{pages: 'item'}` moves one item per flick instead. Under right-to-left layout, pages run from the inline start. With one item per view both give the same stops. A mouse wheel keeps native snapping, and `hasSnap={true}` keeps native CSS snap under every pointer. An edge button steps about one view: the viewport width less half an item, landing on the nearest stop and moving at least one stop. Evidence gap: the one-item-per-flick feel is not yet measured against UIKit's group paging; measure before claiming parity. Implementation gap: snap paging is not built, so no trackpad swipe pages yet. | DEC-2; `spec:AST-094` FR3, FR6, DEC-25 | settled |+| FR8 | Carousel's module imports no pager code: not the internal pager, its paging motion, or its gesture code. The `useSnapPaging` module imports that code statically, and Carousel only calls attach and detach on the `SnapPaging` value from an effect. The pager is tree-shaken by module boundary, with no lazy `import()` (`architecture:react-component-runtime` INV13), so a Carousel without `hasSnap={useSnapPaging()}` bundles no pager code. Importing the module does no DOM work. | DEC-2; `architecture:react-component-runtime` INV13 | settled |+| FR9 | `useSnapPaging(options?)` has no non-React equivalent by default: its value feeds only Carousel's `hasSnap` (`architecture:public-component-api` INV22). Carousel attaches FR7 to its scroll area through that value, and detaching it removes every listener it added. | `architecture:public-component-api` INV22 | settled |### Representative states-| State | Required invariant | Allowed variation |-| -------------------------------------- | --------------------------------------------------------------- | ----------------------- |-| Mid-scroll | Both edge buttons available | Loop keeps both enabled |-| Focused "Scroll right" reaches the end | Button hides; focus is on the scroll area; no extra scroll | Reduced motion |-| Edge reached by swipe, focus elsewhere | Button hides; focus does not move | — |-| Content shrinks to fit | Both buttons hidden; a focused one hands off to the scroll area | — |+| State | Required invariant | Allowed variation |+| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |+| Mid-scroll | Both edge buttons available | Loop keeps both enabled |+| Focused "Scroll right" reaches the end | Button hides; focus is on the scroll area; no extra scroll | Reduced motion |+| Edge reached by swipe, focus elsewhere | Button hides; focus does not move | — |+| Content shrinks to fit | Both buttons hidden; a focused one hands off to the scroll area | — |+| One item per view, snap paging | A flick moves one item, as a UIKit paging scroll view moves one page; `{pages: 'item'}` gives the same | — |+| Three items per view, snap paging | A flick moves one view, settling on the item start edge nearest one viewport on; with `{pages: 'item'}` it moves one item; an edge button moves about one view | — |+| Partial last page | The last page rests where the row ends; no empty space | — |+| Right-to-left | Pages run from the inline start; stops and flick directions mirror | — |+| `hasSnap={true}` | Native snap; no pager code loaded or run | Platform momentum |## Accessibility contract@@ -100,6 +131,10 @@ Consumer migration instructions belong in consumer docs and release notes.- **AR2 — Focus stays in the region.** The edge handoff keeps focus inside thelabelled carousel region (FR2), and the keyboard focus indicator follows`architecture:interaction-modality` INV1.+- **AR3 — Snapping keeps every path.** Under native snap and snap paging, the+ scroll area stays a real scroll container: keyboard scrolling, the edge+ buttons, and the region's name work as without snapping. Snap paging's motion+ under Reduce Motion follows `spec:AST-094`.## Design relationships@@ -112,14 +147,26 @@ visual evidence.removes; FR2 names the scroll area.- `spec:AST-025` FR12 owns the scroll area's tab stop and naming.- `family:buttons` owns the edge buttons' behavior while available.+- `spec:AST-094` FR3, FR6, and DEC-25 own the paging rule and settle that snap+ paging runs (FR7). The internal pager stays internal.+- `component:Lightbox` FR7 pages its gallery with the same internal pager and+ rule. Its pages are full-width items in a row it drives itself, so it takes no+ `SnapPaging` value; it shares the rule, not the config.+- `architecture:public-component-api` INV22 gives `useSnapPaging` no non-React+ equivalent by default, since its value feeds only Carousel's `hasSnap`.## Verification map-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |-| -------- | --------------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------ |-| FR1, AR1 | Unit and accessibility-tree tests | at rest at each edge; no overflow | A hidden button that is focusable or exposed fails | `audit:Carousel/accessibility` |-| FR2, AR2 | Real-browser keyboard test | Enter on "Scroll right" until the end; same on the start | Focus on the page body, a hidden button, or the opposite button fails | `audit:Carousel/accessibility` |-| FR3 | Real-browser test with swipe and resize | edge reached with focus outside the carousel | Focus moving without an edge-button press, or moving twice for one edge, fails | `audit:Carousel/accessibility` |+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |+| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |+| FR1, AR1 | Unit and accessibility-tree tests | at rest at each edge; no overflow | A hidden button that is focusable or exposed fails | `audit:Carousel/accessibility` |+| FR2, AR2 | Real-browser keyboard test | Enter on "Scroll right" until the end; same on the start | Focus on the page body, a hidden button, or the opposite button fails | `audit:Carousel/accessibility` |+| FR3 | Real-browser test with swipe and resize | edge reached with focus outside the carousel | Focus moving without an edge-button press, or moving twice for one edge, fails | `audit:Carousel/accessibility` |+| FR5, FR6 | Unit tests of the scroll area's styles and listeners | `hasSnap` absent, `false`, `true`, and a `SnapPaging` value; one and three items per view | Snapping with `hasSnap` omitted or `false`, a stop other than each child's start edge, gesture listeners under `hasSnap={true}`, `hasSnap={true}` that pages, or paging stops that differ from native snap's fails | — |+| FR7, AR3 | Real-browser touch and trackpad tests in Chromium and WebKit, under a finger and a trackpad swipe under a coarse and a fine primary pointer, each for the default and for `{pages: 'item'}` | one item per view; three items per view; a partial last page; right-to-left; a short flick over 300 pt/s; a slow release before and past half a page; an edge-button step at three per view; a mouse wheel; `hasSnap={true}` under a trackpad swipe | A rest stop other than FR7's, a move of more than one page per flick, a default flick at three per view that moves one item, a `{pages: 'item'}` flick that moves more than one item, empty space after the last item, an unmirrored right-to-left flick, a fine-pointer trackpad swipe that does not page, a mouse wheel that runs the pager, or `hasSnap={true}` that pages fails | — |+| FR7 | Preview stories at desktop and phone widths, used under a finger, a trackpad under a coarse and a fine primary pointer, and a mouse wheel | one item per view; three items per view; a partial last page; right-to-left; each with `hasSnap`, with `hasSnap={useSnapPaging()}`, and with `hasSnap={useSnapPaging({pages: 'item'})}` | A missing story, or a story whose paging stops differ from its native-snap stops, fails | — |+| FR8 | Bundle test on the built package: each public import built with the size report's options and its eager output attributed by module, base against head | Carousel alone; Carousel with `useSnapPaging`; a server import of the module | A Carousel without `hasSnap={useSnapPaging()}` that bundles pager code, an `import()` of the pager, or DOM work on import fails | — |+| FR9 | Unit tests of the hook in Carousel | the hook in Carousel; Carousel unmounting, or dropping the value, mid-settle | A listener left after the carousel unmounts or drops the value, or a public `create…` equivalent of the hook, fails | — |## Decision log@@ -136,6 +183,47 @@ tab order, so focus moving there keeps the user in place inside the carousel.Rejected: the opposite edge button — it may be hidden too, and focus would jumpacross the carousel.+### DEC-2 — `hasSnap` takes native snap or a paging config from `useSnapPaging`++**Reference:** `component:Carousel/DEC-2`+**Decider:** cixzhang, 2026-11-02++Paging comes from a hook that returns a paging config, `useSnapPaging`. A plain+name such as `usePaging` reads as generic and collides with Pagination.++The config goes on `hasSnap`, the released snap prop: `hasSnap={useSnapPaging()}`.+One prop answers how the carousel snaps. Omitted or `false` does not snap,+`true` is native CSS scroll snap as released, and the config is snap paging on+the same per-item stops. `hasSnap`'s type widens from `boolean` to+`boolean | SnapPaging`: an additive patch with no rename, deprecation, or+codemod. Only the paging config bundles the pager (FR8).++The third state deviates from `architecture:public-component-api` INV3, which+keeps an `is…` or `has…` boolean to a true on/off. The deviation keeps one snap+prop for builders, and that record lists it as a known deviation.++One page is one view: a flick moves one view by default, landing on the item+start edge nearest one viewport on, and the last page rests where the row ends.+`{pages: 'item'}` moves one item per flick. A view page matches a UIKit paging+scroll view, which moves a viewport's width per flick.++Rejected: a separate paging prop beside `hasSnap` — two props would describe+one choice, and a builder would have to learn which one wins.++The naming family `useSnap<Variant>` stands for future snap behaviors. Each+variant is its own hook, so an app bundles only the variants it imports, and+each keeps one behavior. Their values feed only `hasSnap`, so they have no+non-React equivalent by default (`architecture:public-component-api` INV22).++Native CSS scroll snap is the default because it works in every browser and+uses the platform's own momentum. The CSS carousel features (`::scroll-button()`,+`::scroll-marker`, `:target-current`, scroll-state queries, snap events,+`interactivity: inert`) ship in Chromium only, with open accessibility and+internationalization concerns from another engine, so Carousel keeps its own+buttons. Snap paging does only what native snap cannot: UIKit's paging rule and+settle under a finger and a trackpad swipe. Scroll-driven animations are available in every engine+and suit progress or slide effects.+## Open questionsNone.