docs(studies): carousel and pager candidate study

[k08200]

What

Adds docs/studies/carousel-and-pager.md — a candidate study for the "Carousel and existing pager" entry in the widget candidate landscape (#19) — plus its index line in docs/studies/README.md.

Docs only; no code, no syntax reservation, no obligation created for the future ui sub-specification (per the studies charter).

Method

• Primary-source reading of the two references the candidate cites: the APG Carousel pattern and CSS Scroll Snap Level 1 (retrieved 2026-07-20, quotes verified verbatim against the sources).
• Direct verification of the current implementations on main and the feat!: replace Uhura with the 0.4 machine-first language #24 branch, updated to its current head 7f69fc0 (spike catalog contract, ui_catalog vocabulary, the pager primitive adapter and its tests).
• The state-ownership boundary articulated in the feat!: replace Uhura with the 0.4 machine-first language #24 discussion applied as the analysis frame.

Findings the study rests on

• As of 7f69fc0, the pager primitive now dispatches page-change — with a Unit payload, fired on rounded-index crossings during scrolling. The machine learns that the page changed but not which page; the current page itself stays renderer-internal, and no example binds the event on either branch. The position half of the contract — whether, when, and in what vocabulary a program may own the current page — is the open question the study addresses.
• APG defines the semantic-controls half (unconditional prev/next buttons, rotation-control rules) but says nothing about touch, swipe, or reduced motion; Scroll Snap defines resting states and deliberately leaves all kinetics to the UA. Both leave gaps a Uhura contract has to close itself.

Candidate answers (summary)

1. Smallest contract: keyed slides + resting current page (key, not index) + logical axis + required label + indicator token; everything kinetic excluded.
2. Current page: renderer-owned while unobserved; machine-owned (controlled, PageChanged at rest) once anything observes it — the textfield rule applied to paging.
3. Static preview = declared current key, which also gives the pose story for a scrolled viewport.
4. Carousel: composition over pager + button (semantic controls + rotation policy), not a separate Element — conditional on whichever composition tier the ui sub-specification defines.
5. APG baseline features become conformance obligations; reduced motion and non-drag alternatives are named as the places the contract must go beyond the prior art.

Open questions the study cannot decide are listed at the end for the ui sub-specification.

Closes nothing; intended as input for the future ui sub-specification. Feedback welcome — happy to rework or drop per your direction.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: ed0805b4-b806-4fda-a0a4-54dfafd94de5

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/study-carousel-pager

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}