@slotted/angular 0.0.0-stage → 0.1.0-beta.1

package/docs/carousel.md

@@ -0,0 +1,357 @@
+<!-- index: ./index.md -->
+# carousel
+
+`data-ui="carousel"` · Slides that scroll one page at a time.
+
+## Import
+
+```ts
+import {
+  provideCarouselDefaults,
+  SlCarousel,
+  SlCarouselAutoplay,
+  SlCarouselControls,
+  SlCarouselCounter,
+  SlCarouselIndicator,
+  SlCarouselIndicators,
+  SlCarouselIndicatorTemplate,
+  SlCarouselNext,
+  SlCarouselPrevious,
+  SlCarouselSlide,
+  SlCarouselViewport,
+} from '@slotted/angular/carousel';
+```
+
+Selector: `section[slCarousel]` · exportAs: `slCarousel`
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<section slCarousel aria-label="Coleção Outono">
+  <div slCarouselViewport>
+    @for (piece of pieces; track piece.name) {
+      <div slCarouselSlide>
+        <div slImage ratio="landscape" [alt]="piece.name" [src]="piece.image"></div>
+      </div>
+    }
+  </div>
+  <button slCarouselPrevious></button>
+  <button slCarouselNext></button>
+  <div slCarouselControls>
+    <div slCarouselIndicators></div>
+    <span slCarouselCounter></span>
+  </div>
+</section>
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | section[slCarousel] | yes |
+| `viewport` | div[slCarouselViewport] | yes |
+| `slide` | div[slCarouselSlide] | yes |
+| `previous` | button[slCarouselPrevious] | no |
+| `next` | button[slCarouselNext] | no |
+| `controls` | div[slCarouselControls] | no |
+| `autoplay` | button[slCarouselAutoplay] | no |
+| `indicators` | div[slCarouselIndicators] role="tablist" | no |
+| `indicator` | button[slCarouselIndicator] role="tab" | no |
+| `counter` | span[slCarouselCounter] aria-hidden | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `page` | `number` | — | slCarousel | Present means the consumer owns the page, counted from 0; [(page)] binds both ways |
+| `defaultPage` | `number` | 0 | slCarousel | The page an uncontrolled carousel starts on |
+| `autoplay` | `boolean \| number` | false | slCarousel | Turns the rotation on: present as an attribute waits autoplayDelay, a number waits that many milliseconds |
+| `autoplayDelay` | `number` | 5000 | provideCarouselDefaults | The wait on a page when autoplay carries no number; written as --slotted-carousel-autoplay-delay |
+| `playing` | `boolean` | — | slCarousel | Present means the consumer owns whether the rotation runs; [(playing)] binds both ways |
+| `defaultPlaying` | `boolean` | true with autoplay, false under reduced motion | slCarousel | Whether an uncontrolled rotation starts running |
+| `loop` | `boolean` | false | slCarousel, provideCarouselDefaults | Next on the last page goes to the first; without it the rotation stops there |
+| `orientation` | `'horizontal' \| 'vertical'` | horizontal | slCarousel, provideCarouselDefaults | The axis of the track, the arrows and the keys |
+| `transition` | `'slide' \| 'fade'` | slide | slCarousel, provideCarouselDefaults | A scroll with snap, or slides stacked and crossfaded |
+| `align` | `'start' \| 'center'` | start | slCarousel, provideCarouselDefaults | Where a page snaps; center makes every slide a page |
+| `arrows` | `'inset' \| 'outside'` | inset | slCarousel, provideCarouselDefaults | Where previous and next stand when they are children of the root |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | slCarousel, provideCarouselDefaults | The step of the control scale the round controls take |
+| `slidesPerView` | `number` | 1 | slCarousel | Written as --slotted-carousel-slides-per-view; unset, a container query of the consumer’s may write it |
+| `slidesPerMove` | `number \| 'page'` | page | slCarousel | How many slides a page moves; page is the slides wholly in view |
+| `draggable` | `boolean` | true | slCarousel, provideCarouselDefaults | Whether a mouse drags the row; a finger and a trackpad always scroll it |
+| `messages` | `PartialMessages<CarouselMessages>` | — | slCarousel | Words laid over the language in force, key by key: roleDescription, slide, indicators, indicator, previous, next, stop, start, viewport, announce — with {index}, {page} and {count} |
+| `placement` | `'below' \| 'overlay'` | below | slCarouselControls | Under the viewport, or over its foot on a raised pill |
+| `variant` | `'dots' \| 'line' \| 'thumbnails'` | dots | slCarouselIndicators | The mark of each page; thumbnails is the consumer’s picture inside each indicator |
+| `page` | `number` | — | slCarouselIndicator | The page this indicator shows |
+| `exportAs` | `'slCarousel'` | — | section[slCarousel] | scrollTo(page), scrollToSlide(index) and refresh(): the actions a consumer cannot express declaratively |
+| `slCarouselIndicatorTemplate` | `ng-template, let-page` | — | inside slCarouselIndicators | Draws each indicator from the consumer’s template, re-rendered per page |
+| `ng-content` | `projected content` | the chevron, play or pause glyph | previous, next, autoplay | Replaces the glyph; the accessible name stays the message unless aria-label is written |
+| `aria-label` | `static attribute` | the message | viewport, previous, next, autoplay, indicators, indicator | Read with HostAttributeToken before the host binding writes the family’s word, so it survives |
+| `provideCarouselDefaults` | `{ orientation, transition, align, arrows, size, loop, draggable, autoplayDelay }` | — | an injector | The decisions an application takes once |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `pageRequest` | `ChangeRequest<number> — value, previous, reason, source, cancel()` | Before the page moves: a control or an indicator ("pointer" or "keyboard"), a key in the viewport ("keyboard"), a swipe, a trackpad or a wheel that came to rest ("scroll"), a mouse drag ("pointer"), the rotation ("timeout"), a page that stopped existing ("resize"), scrollTo or scrollToSlide ("programmatic"). cancel() keeps the page; a refused request brings the viewport back. |
+| `pageChange` | `number` | After a request nobody cancelled, for [(page)]. |
+| `playingRequest` | `ChangeRequest<boolean>` | Before the rotation starts or stops: the rotation control ("pointer" or "keyboard"), keyboard focus entering ("keyboard"), the reader moving the page by hand ("pointer", "keyboard", "scroll"), the last page reached without a loop ("timeout"). |
+| `playingChange` | `boolean` | After a rotation request nobody cancelled, for [(playing)]. |
+| `(click), (keydown), (focusin)` | `the elements’ own events` | Whenever the elements fire them; a handler that calls preventDefault() first stops the family’s answer. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `orientation` | `horizontal`, `vertical` | `horizontal` |
+| `transition` | `slide`, `fade` | `slide` |
+| `align` | `start`, `center` | `start` |
+| `arrows` | `inset`, `outside` | `inset` |
+| `size` | `sm`, `md`, `lg` | `md` |
+
+## Rules
+
+- The root is a region with aria-roledescription "carousel" and the consumer’s name; each slide is a group with aria-roledescription "slide" and the name "3 of 8", as the APG carousel asks, and a name the consumer gives a slide is never replaced, because the engine skips a slide that already carries one.
+- The slides out of view are inert, so the Tab key and a screen reader reach only what the reader can see; a press on a slide that peeks reaches the viewport, which brings that slide in.
+- Previous and next at an end without a loop are aria-disabled rather than disabled, so the focus they hold is not dropped onto the page; a press does nothing and the disabled ink says so.
+- The slide picker is the APG tabs pattern: one tab stop, arrows that move and show and stop at the ends, Home and End. Each tab names its page and controls its first slide; the slides stay groups because a page can hold several.
+- A page the reader asked for is announced once through the shared live announcer — "Slide 3 of 8" — and nothing is announced while the rotation turns, so a screen reader is never interrupted by a page the reader did not ask for.
+- The rotation never starts unless asked, does not start under reduced motion, pauses on hover and on a hidden browser tab, and stops on the first keyboard focus inside; its control is named by its action and carries no pressed state.
+
+## Tokens
+
+`--slotted-border-strong`, `--slotted-border-subtle`, `--slotted-border-width-thick`, `--slotted-border-width-thin`, `--slotted-carousel-controls-gap`, `--slotted-carousel-duration`, `--slotted-carousel-gap`, `--slotted-carousel-peek`, `--slotted-carousel-radius`, `--slotted-carousel-slide-min-size`, `--slotted-carousel-thumbnail-size`, `--slotted-carousel-viewport-size`, `--slotted-control-border-color`, `--slotted-control-border-width`, `--slotted-control-height-lg`, `--slotted-control-height-md`, `--slotted-control-height-sm`, `--slotted-control-icon-size-lg`, `--slotted-control-icon-size-md`, `--slotted-control-icon-size-sm`, `--slotted-control-inner-size-lg`, `--slotted-control-inner-size-md`, `--slotted-control-inner-size-sm`, `--slotted-control-shadow`, `--slotted-control-surface`, `--slotted-control-transition-duration`, `--slotted-control-transition-easing`, `--slotted-disabled-border`, `--slotted-disabled-foreground`, `--slotted-duration-instant`, `--slotted-duration-long`, `--slotted-duration-loop-slow`, `--slotted-duration-medium`, `--slotted-easing-enter`, `--slotted-easing-exit`, `--slotted-easing-standard`, `--slotted-focus-ring-color`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-font-family-sans`, `--slotted-font-size-sm`, `--slotted-line-height-sm`, `--slotted-radius-full`, `--slotted-radius-lg`, `--slotted-radius-md`, `--slotted-shadow-sm`, `--slotted-space-12`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-space-4`, `--slotted-space-5`, `--slotted-space-6`, `--slotted-space-8`, `--slotted-surface-raised`, `--slotted-target-min`, `--slotted-text`, `--slotted-text-muted`, `--slotted-tone-accent-solid`, `--slotted-tone-secondary-subtle-active`, `--slotted-tone-secondary-subtle-hover`
+
+## Examples
+
+### A column of slides
+
+orientation="vertical" turns the scroller and both arrows a quarter; the arrows of the keyboard that page it are now Up and Down, and Left and Right are left to the page. The column needs a height, which --slotted-carousel-viewport-size gives it.
+
+Excerpt — not a complete module
+
+```html
+<section slCarousel aria-label="Novidades" orientation="vertical" [slidesPerView]="2">
+  <div slCarouselViewport>…</div>
+  <button slCarouselPrevious></button>
+  <button slCarouselNext></button>
+</section>
+```
+
+### Slide or fade
+
+slide moves the track on a spring timed by the theme’s long duration, which keeps the speed of a hand that lets go or of a movement it interrupts; fade stacks the slides and crossfades them — the arriving one on the enter curve, the leaving one faster on the exit curve. Under reduced motion both change at once.
+
+Excerpt — not a complete module
+
+```html
+<section slCarousel aria-label="Avisos" loop transition="fade">
+  <div slCarouselViewport>…</div>
+  <div slCarouselControls>
+    <button slCarouselPrevious></button>
+    <div slCarouselIndicators></div>
+    <button slCarouselNext></button>
+  </div>
+</section>
+```
+
+### Centred, with the neighbours showing
+
+align="center" makes every slide a page and centres it; --slotted-carousel-peek pads the viewport so the slides either side show at its edges. Press a slide that peeks and it comes to the centre.
+
+Excerpt — not a complete module
+
+```html
+<section slCarousel align="center" aria-label="Peças únicas" class="peek">
+  <div slCarouselViewport>…</div>
+  <button slCarouselPrevious></button>
+  <button slCarouselNext></button>
+</section>
+<!-- .peek { --slotted-carousel-peek: 2.5rem; } -->
+```
+
+### Over the picture, or beside the row
+
+arrows="inset" stands previous and next over the ends of the viewport, for a slideshow; "outside" gives them columns of their own, so a row of cards keeps its whole width and no arrow covers the first card.
+
+Excerpt — not a complete module
+
+```html
+<section slCarousel aria-label="Mais vendidos" arrows="outside" [slidesPerView]="3">
+  <div slCarouselViewport>…</div>
+  <button slCarouselPrevious></button>
+  <button slCarouselNext></button>
+</section>
+```
+
+### Three control sizes
+
+size steps the round controls along the control scale — 30, 34 and 38 pixels at comfortable — and the density shrinks them with every other control. The dots keep the 24-pixel target in every size.
+
+Excerpt — not a complete module
+
+```html
+<section slCarousel aria-label="Pequeno" size="sm">…</section>
+<section slCarousel aria-label="Grande" size="lg">…</section>
+```
+
+### Dots, a line, and many pages
+
+dots draw the current page as a bar three dots long; line shares the width between segments; past eight pages the dots window themselves, the ones two steps away shrink and the rest fold away while staying in the arrow ring.
+
+Excerpt — not a complete module
+
+```html
+<div slCarouselIndicators></div>
+<div slCarouselIndicators variant="line"></div>
+```
+
+### A product gallery
+
+variant="thumbnails" with an slCarouselIndicatorTemplate draws each indicator from the consumer’s picture. The strip scrolls on its own when it holds more than it shows, and keeps the current picture in view — one carousel, nothing to synchronise.
+
+Excerpt — not a complete module
+
+```html
+<div slCarouselIndicators aria-label="Fotografias" variant="thumbnails">
+  <ng-template slCarouselIndicatorTemplate let-page>
+    <button slCarouselIndicator [page]="page">
+      <img [alt]="photos[page].alt" [src]="photos[page].thumbnail" />
+    </button>
+  </ng-template>
+</div>
+```
+
+### A rotation the reader controls
+
+autoplay turns it on; the current dot fills over the delay. Hovering holds it with the time that was left, a hidden browser tab holds it, and the first keyboard focus inside stops it until the rotation control starts it again.
+
+Excerpt — not a complete module
+
+```html
+<section slCarousel aria-label="Destaques" loop [autoplay]="6000">
+  <div slCarouselViewport>…</div>
+  <div slCarouselControls placement="overlay">
+    <button slCarouselAutoplay></button>
+    <div slCarouselIndicators></div>
+  </div>
+</section>
+```
+
+### A row of cards that pages by what it shows
+
+[slidesPerView]="3" sizes the cards; the pages are read from the layout, so the row pages by three and its last page ends flush. --slotted-carousel-slide-min-size keeps a card readable when the container narrows: at 240 pixels the same carousel shows one card and the edge of the next.
+
+Excerpt — not a complete module
+
+```html
+<section slCarousel aria-label="Mais vendidos" arrows="outside" [slidesPerView]="3">
+  <div slCarouselViewport>
+    @for (piece of pieces; track piece.name) {
+      <div slCarouselSlide [attr.aria-label]="piece.name">
+        <article slCard>…</article>
+      </div>
+    }
+  </div>
+  <button slCarouselPrevious></button>
+  <button slCarouselNext></button>
+  <div slCarouselControls>
+    <div slCarouselIndicators variant="line"></div>
+  </div>
+</section>
+```
+
+### Past the last page
+
+loop sends next on the last page to the first and previous on the first to the last; the track travels back rather than cloning a slide, so ids, focus and form state stay single. Without it the controls at the ends say they have nowhere to go.
+
+Excerpt — not a complete module
+
+```html
+<section slCarousel aria-label="Coleção" loop>…</section>
+```
+
+### A page the application owns
+
+[(page)] and (pageRequest) make the page the application’s; the request carries the reason — pointer, keyboard, scroll, timeout, resize, programmatic. The buttons outside the carousel move it through the same state, and the log shows each request.
+
+Excerpt — not a complete module
+
+```html
+<section slCarousel aria-label="Coleção" [(page)]="page" (pageRequest)="log($event.reason)">
+  …
+</section>
+```
+
+### Every control in every state
+
+Hover lifts a round control onto the neutral hover ground, a press shrinks it to 94 per cent, focus draws the ring two pixels out; at an end it keeps its place in the disabled ink. Use Tab to see the rings.
+
+Excerpt — not a complete module
+
+```html
+<div slCarouselControls>
+  <button slCarouselPrevious></button>
+  <div slCarouselIndicators></div>
+  <button slCarouselNext></button>
+</div>
+```
+
+### Content the family did not choose
+
+Cards of different heights stand at the height of the tallest; a long Portuguese name wraps inside its card; a right-to-left page mirrors the track, the arrows and the dots, and the counter still reads first to last.
+
+Excerpt — not a complete module
+
+```html
+<div dir="rtl">
+  <section slCarousel aria-label="معرض" [slidesPerView]="2">…</section>
+</div>
+```
+
+### Nothing yet, and loading
+
+With no slide the controls are disabled and the counter reads 0 / 0; the empty state is a result-state the consumer puts in the viewport. While the pieces load, skeleton slides with the same anatomy hold the height.
+
+Excerpt — not a complete module
+
+```html
+<section slCarousel aria-label="Coleção">
+  <div slCarouselViewport>
+    <section slResultState status="empty">
+      <div slResultStateContent>
+        <div slResultStateTitle>Sem peças nesta coleção</div>
+      </div>
+    </section>
+  </div>
+</section>
+```
+
+### Inside a product page
+
+The gallery beside the buy box, as a product page lays them out: the picture and its thumbnails on the start, the name, the price and the action on the end. the instance’s scrollToSlide, reached through exportAs takes the gallery to the picture of the colour chosen.
+
+Excerpt — not a complete module
+
+```html
+<section slCarousel #gallery="slCarousel" aria-label="Fotografias">…</section>
+<div slSegmentedControl aria-label="Cor" (valueChange)="gallery.scrollToSlide(photoOf($event))">
+  …
+</div>
+```
+
+### The keyboard
+
+Tab reaches the rotation control, the viewport, the arrows and then one tab stop in the dots. In the viewport the arrows, PageUp, PageDown, Home and End move a page; in the dots the arrows move and show, and stop at the ends. Holding a key moves without animating.
+
+Excerpt — not a complete module
+
+```html
+<section slCarousel aria-label="Coleção">
+  <div slCarouselViewport>…</div>
+  <div slCarouselControls>
+    <div slCarouselIndicators></div>
+  </div>
+</section>
+```