## carousel (`poetry_carousel`)

A slideshow for cycling through content, built on native scroll-snap.

Class: Poetry::Ui::Carousel::Component - BEM block `poetry-ui-carousel`.
Slot REQUIRED: with_item (at least one slide) - a call without it raises.
- `label:` (string) - required - The carousel region's accessible name - required; rendering without it raises.
- `orientation:` (symbol) - one of horizontal|vertical, default "horizontal" - The scroll axis; snapping, controls, and arrow keys follow it.
- `show_controls:` (boolean) - default true - Renders the prev/next buttons; slides stay reachable by swipe, wheel, and keyboard without them.
- `track_classes:` (string) - Utility classes for the slide track - change spacing as a trio: track_classes: "-ml-1" pairs with item classes "pl-1 -scroll-ml-1".
Slots: items (Declares one slide. The content block is required; classes: sizes the slide (basis-full default).; many; with_item yields NOTHING to the block - no |param|, write content directly; with_item keywords: classes: ONLY; with_item REQUIRES a content block (the slide)).
- PART `carousel` - The role=region root - the controller (paging, button state, arrow keys) rides here | states: data-orientation=horizontal|vertical (the scroll axis)
- PART `carousel-content` - The viewport - a real scroll-snap container (tabindex=0); the platform owns the physics
- PART `carousel-item` - One role=group slide - sized by item classes (basis-full default)
- WIRING root: `poetry--core--carousel` registers; values orientation; actions keydown on keydown
- WIRING viewport: `poetry--core--carousel` actions scrolled on scroll; targets viewport
- WIRING previous: `poetry--core--carousel` actions previous on click; targets previous
- WIRING next: `poetry--core--carousel` actions next on click; targets next
- RULE: label: is REQUIRED - the carousel region's accessible name.
- RULE: Declare slides with with_item - the component stamps the slide roles (role=group + aria-roledescription=slide).
- RULE: Slides are REAL scroll content: they stay reachable by swipe, wheel, and keyboard even before JS - never gate content behind the buttons alone.
- RULE: Size slides with item classes (basis-full default; basis-1/2 lg:basis-1/3 for a gallery).
- RULE: Change slide spacing as a TRIO: track_classes: "-ml-1" plus item classes "pl-1 -scroll-ml-1" - the gutter padding and its snap scroll-margin move together.