forty-cdk 0.4.0 → 0.6.0

package/calendar/README.md

@@ -1,12 +1,14 @@
 # Calendar
 
-Headless single-date calendar grid following the [WAI-ARIA Grid pattern](https://www.w3.org/WAI/ARIA/apg/patterns/grid/) — the date table at the heart of the APG [Date Picker Dialog](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/examples/datepicker-dialog/) example. Roving-tabindex focus management, full grid keyboard interaction (arrows / `Home` / `End` / `PageUp` / `PageDown` / `Shift+PageUp` / `Shift+PageDown`), focus paging across month boundaries, `aria-current="date"` on today, `min` / `max` / per-date availability, RTL arrow mirroring, and a pluggable, date-library-agnostic `DateAdapter<D>`.
+A single-date calendar grid implementing the APG Grid pattern over a pluggable date adapter: roving-tabindex day navigation, month / year paging, and min / max / per-date availability.
+
+Headless and styleless — the date table at the heart of the APG [Date Picker Dialog](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/examples/datepicker-dialog/) example. Full grid keyboard interaction (arrows / `Home` / `End` / `PageUp` / `PageDown` / `Shift+PageUp` / `Shift+PageDown`), focus paging across month boundaries, `aria-current="date"` on today, RTL arrow mirroring, and a pluggable, date-library-agnostic `DateAdapter<D>`.
 
 `ForCalendar` is the grid widget, **not a form value** — it exposes `[(value)]` as a `model<D | null>`. The form-control contract (`FormValueControl<D>`) arrives with the follow-up `ForDatePicker` / `ForDateField`.
 
-## Date adapter — pick one (required)
+## Date adapter
 
-All date math goes through a `DateAdapter<D>`, so the library hard-depends on **no** date library. Provide exactly one adapter in your application (or component) providers:
+All date math goes through a `DateAdapter<D>`, so the library hard-depends on **no** date library. Provide exactly one adapter in your application (or component) providers (required):
 
 | Provider                                | Date type `D`                              | Dependency                                                                                                |
 | --------------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------- |
@@ -24,37 +26,35 @@ bootstrapApplication(App, {
 
 `@internationalized/date` is a widely-used immutable date primitive; it works in every browser today with no polyfill, and its reference-equality-on-mutation makes it signal-friendly. Both `@internationalized/date` adapters operate on the **Gregorian** calendar today — `createDate` always builds a Gregorian date, so the grid stays Gregorian regardless of the runtime locale. True non-Gregorian calendar systems are deferred to the planned `Temporal.PlainDate` adapter ([#354](https://github.com/tutkli/forty-cdk/issues/354)), a non-breaking addition once the Temporal API is broadly available across browsers — the `DateAdapter<D>` seam means adopting it later is a drop-in, not a migration.
 
-## Pieces
-
-| Class                   | Selector                  | Role                                                                                                |
-| ----------------------- | ------------------------- | --------------------------------------------------------------------------------------------------- |
-| `ForCalendar`           | `[forCalendar]`           | Root. Owns `value`, the focused date, the visible month, and the shared context.                    |
-| `ForCalendarHeading`    | `[forCalendarHeading]`    | Month/year title and the grid's `aria-labelledby` target; its text is set to the visible period.    |
-| `ForCalendarPrevButton` | `[forCalendarPrevButton]` | Pages to the previous month. Auto-disabled at the `min` bound.                                      |
-| `ForCalendarNextButton` | `[forCalendarNextButton]` | Pages to the next month. Auto-disabled at the `max` bound.                                          |
-| `ForCalendarGrid`       | `[forCalendarGrid]`       | Date table (`role="grid"`, `aria-labelledby` the heading). Exposes `weekDays()` / `weeks()`.        |
-| `ForCalendarGridHeader` | `[forCalendarGridHeader]` | Header rowgroup (`role="rowgroup"`) holding the weekday `columnheader`s. Also exposes `weekDays()`. |
-| `ForCalendarCell`       | `[forCalendarCell]`       | One day (`role="gridcell"`). Roving tab stop, ARIA state, and keyboard / click interaction.         |
-
-## Inputs / models — `ForCalendar`
-
-| API                 | Type                                   | Description                                                                                                                                    |
-| ------------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| `value`             | `model<D \| null>`                     | Two-way bindable selected date, or `null`. Used in `selectionMode="single"`. `(valueChange)` fires only on internal selection. Default `null`. |
-| `selectionMode`     | `input<'single' \| 'range'>`           | `'single'` (default) keeps the single-date `value` flow. `'range'` switches to anchor → commit and exposes `range`.                            |
-| `range`             | `model<CalendarDateRange<D> \| null>`  | Two-way bindable committed range. Only used in `selectionMode="range"`. `(rangeChange)` fires only on internal commits/clears. Default `null`. |
-| `minRangeLength`    | `input<number \| null>`                | Minimum inclusive day count. A commit shorter than this is a no-op. Default `null` (no minimum).                                               |
-| `maxRangeLength`    | `input<number \| null>`                | Maximum inclusive day count. A commit longer than this is a no-op. Default `null` (no maximum).                                                |
-| `min`               | `input<D \| null>`                     | Minimum selectable date (inclusive). Earlier dates are unavailable. Default `null`.                                                            |
-| `max`               | `input<D \| null>`                     | Maximum selectable date (inclusive). Later dates are unavailable. Default `null`.                                                              |
-| `isDateUnavailable` | `input<(date: D) => boolean>`          | Per-date predicate marking a date unavailable (present but not selectable). Default `() => false`.                                             |
-| `dateLabel`         | `input<CalendarDateLabelFormatter<D>>` | Formats each gridcell's `aria-label` (full accessible date). Default: localized full date, outside-month days suffixed.                        |
-| `disabled`          | `input<boolean>`                       | Disables the whole calendar (no focus movement, no selection). Reflected as `data-disabled`.                                                   |
-| `readonly`          | `input<boolean>`                       | Read-only: dates stay focusable, selection is blocked. Reflected as `data-readonly`.                                                           |
-| `firstDayOfWeek`    | `input<number \| null>`                | First column's weekday, **0-6** (`0` = Sunday). Default `null` → the adapter's value (or `provideForCalendarDefaults`).                        |
-| `dir`               | `input<'ltr' \| 'rtl' \| null>`        | Writing direction. Default `null` resolves the ambient direction; reflected to the host `dir` and mirrors horizontal arrows.                   |
-
-## Usage
+## Anatomy
+
+```html
+<div forCalendar [(value)]="date">
+  <header>
+    <button forCalendarPrevButton [ariaLabel]="'Previous month'">‹</button>
+    <h2 forCalendarHeading #heading="forCalendarHeading">{{ heading.label() }}</h2>
+    <button forCalendarNextButton [ariaLabel]="'Next month'">›</button>
+  </header>
+
+  <table forCalendarGrid #grid="forCalendarGrid">
+    <thead forCalendarGridHeader>
+      <tr>
+        <!-- @for (day of grid.weekDays(); track day.key) -->
+        <th scope="col" [attr.aria-label]="day.long">{{ day.short }}</th>
+      </tr>
+    </thead>
+    <tbody>
+      <!-- @for (week of grid.weeks(); track week.key) -->
+      <tr>
+        <!-- @for (cell of week.days; track cell.key) -->
+        <td forCalendarCell [date]="cell.date">{{ cell.label }}</td>
+      </tr>
+    </tbody>
+  </table>
+</div>
+```
+
+## Examples
 
 ```ts
 import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
@@ -117,6 +117,40 @@ export class DatePage {
 
 The library is styleless: style the boolean `data-*` hooks on `[forCalendarCell]` yourself (`[data-selected]`, `[data-today]`, `[data-outside-month]`, `[data-highlighted]`, and `:not([data-disabled])` for the enabled state).
 
+## API
+
+### `ForCalendar`
+
+| Property            | Type                                   | Description                                                                                                                                           |
+| ------------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `value`             | `model<D \| null>`                     | Two-way bindable selected date, or `null`. Used in `selectionMode="single"`. `(valueChange)` fires only on internal selection.<br>**Default:** `null` |
+| `selectionMode`     | `input<'single' \| 'range'>`           | `'single'` (default) keeps the single-date `value` flow. `'range'` switches to anchor → commit and exposes `range`.<br>**Default:** `'single'`        |
+| `range`             | `model<CalendarDateRange<D> \| null>`  | Two-way bindable committed range. Only used in `selectionMode="range"`. `(rangeChange)` fires only on internal commits/clears.<br>**Default:** `null` |
+| `minRangeLength`    | `input<number \| null>`                | Minimum inclusive day count. A commit shorter than this is a no-op.<br>**Default:** `null` (no minimum)                                               |
+| `maxRangeLength`    | `input<number \| null>`                | Maximum inclusive day count. A commit longer than this is a no-op.<br>**Default:** `null` (no maximum)                                                |
+| `min`               | `input<D \| null>`                     | Minimum selectable date (inclusive). Earlier dates are unavailable.<br>**Default:** `null`                                                            |
+| `max`               | `input<D \| null>`                     | Maximum selectable date (inclusive). Later dates are unavailable.<br>**Default:** `null`                                                              |
+| `isDateUnavailable` | `input<(date: D) => boolean>`          | Per-date predicate marking a date unavailable (present but not selectable).<br>**Default:** `() => false`                                             |
+| `dateLabel`         | `input<CalendarDateLabelFormatter<D>>` | Formats each gridcell's `aria-label` (full accessible date).<br>**Default:** localized full date, outside-month days suffixed                         |
+| `disabled`          | `input<boolean>`                       | Disables the whole calendar (no focus movement, no selection). Reflected as `data-disabled`.<br>**Default:** —                                        |
+| `readonly`          | `input<boolean>`                       | Read-only: dates stay focusable, selection is blocked. Reflected as `data-readonly`.<br>**Default:** —                                                |
+| `firstDayOfWeek`    | `input<number \| null>`                | First column's weekday, **0-6** (`0` = Sunday).<br>**Default:** `null` → the adapter's value (or `provideForCalendarDefaults`)                        |
+| `dir`               | `input<'ltr' \| 'rtl' \| null>`        | Writing direction.<br>**Default:** `null` resolves the ambient direction; reflected to the host `dir` and mirrors horizontal arrows                   |
+
+### Data attributes
+
+| Piece                     | Attribute            | Values            |
+| ------------------------- | -------------------- | ----------------- |
+| `[forCalendar]`           | `data-disabled`      | present \| absent |
+| `[forCalendar]`           | `data-readonly`      | present \| absent |
+| `[forCalendarPrevButton]` | `data-disabled`      | present \| absent |
+| `[forCalendarNextButton]` | `data-disabled`      | present \| absent |
+| `[forCalendarCell]`       | `data-selected`      | present \| absent |
+| `[forCalendarCell]`       | `data-today`         | present \| absent |
+| `[forCalendarCell]`       | `data-highlighted`   | present \| absent |
+| `[forCalendarCell]`       | `data-disabled`      | present \| absent |
+| `[forCalendarCell]`       | `data-outside-month` | present \| absent |
+
 ## Range selection
 
 Set `selectionMode="range"` and bind `[(range)]` to get date-range selection. In range mode the single-date `value` is unused and stays `null`.
@@ -245,7 +279,7 @@ The default window is **anchored to the current year** (not the visible year), s
 
 The lower-level hooks (`visibleMonthNumber()`, `visibleYear()`, `monthOptions()`, `goToMonth()`, `goToYear()`, `isYearDisabled()`) in the table above remain available for any other UI.
 
-## View switching (month / year picker)
+## View switching
 
 `ForCalendar` supports two additional views — **month grid** and **year grid** — so users can jump quickly to a different month or year without paging one at a time. All three views share a single `[(view)]` model and the same `focusedDate` cursor.
 
@@ -364,23 +398,44 @@ Auto-disabled when the entire previous / next page would be outside `[min, max]`
 | `[forCalendarYearCell]`  | `data-highlighted` | present \| absent                |
 | `[forCalendarYearCell]`  | `data-disabled`    | present \| absent                |
 
-## Styling
+## Scope defaults
 
-forty-cdk ships no styles. Add your own class to each piece — the `forCalendar*` selectors are the behavior API, not a styling contract (see [Styling forty-cdk](../../../../../docs/styling.md)). Key your CSS off the reflected `data-*` attributes below.
+```ts
+import { provideForCalendarDefaults } from 'forty-cdk/calendar';
 
-### Data attributes
+// app config or a component's providers — Monday-first weeks for this scope
+providers: [provideForCalendarDefaults({ firstDayOfWeek: 1 })];
+```
 
-| Piece                     | Attribute            | Values            |
-| ------------------------- | -------------------- | ----------------- |
-| `[forCalendar]`           | `data-disabled`      | present \| absent |
-| `[forCalendar]`           | `data-readonly`      | present \| absent |
-| `[forCalendarPrevButton]` | `data-disabled`      | present \| absent |
-| `[forCalendarNextButton]` | `data-disabled`      | present \| absent |
-| `[forCalendarCell]`       | `data-selected`      | present \| absent |
-| `[forCalendarCell]`       | `data-today`         | present \| absent |
-| `[forCalendarCell]`       | `data-highlighted`   | present \| absent |
-| `[forCalendarCell]`       | `data-disabled`      | present \| absent |
-| `[forCalendarCell]`       | `data-outside-month` | present \| absent |
+## Keyboard
+
+LTR (horizontal arrows mirror under `dir="rtl"`):
+
+| Key                               | Behavior                                                      |
+| --------------------------------- | ------------------------------------------------------------- |
+| **ArrowLeft / ArrowRight**        | Previous / next day.                                          |
+| **ArrowUp / ArrowDown**           | Same weekday, previous / next week.                           |
+| **Home / End**                    | First / last day of the focused week.                         |
+| **PageUp / PageDown**             | Same day-of-month, previous / next month (re-pages the grid). |
+| **Shift+PageUp / Shift+PageDown** | Same month, previous / next year.                             |
+| **Enter / Space**                 | Select the focused date.                                      |
+
+Focus that crosses a month boundary re-pages the visible grid and keeps the focused cell in view. Day-of-month is constrained when paging (e.g. Jan 31 → Feb 28). Paging (the prev / next buttons and `PageUp` / `PageDown`) also clamps the focused date into the `[min, max]` range, so it never lands on a cell outside the selectable bounds; day / week arrows still move freely across unavailable dates so keyboard navigation is never trapped.
+
+## Accessibility
+
+Implements the [WAI-ARIA Grid pattern](https://www.w3.org/WAI/ARIA/apg/patterns/grid/).
+
+- **`role="grid"`** on the table, `columnheader` weekday headers, `gridcell` days — the APG Date Picker Dialog technique over a real `<table>`.
+- **`aria-labelledby`** wires the grid to the heading so it names the visible period. Paging the month is announced through a dedicated off-screen `aria-live="polite"` region (owned by `[forCalendar]`), so the period is read on navigation without the heading double-announcing as both a live region and the grid's label.
+- **`aria-label`** on every cell carries the full localized date (e.g. `"Monday, June 15, 2026"`) so screen readers announce the whole date, not the bare day number that stays the cell's visible content. Outside-month padding days are suffixed (`" (outside month)"`) so they are distinguishable. Override the format via `ForCalendar`'s `dateLabel` input.
+- **`aria-selected`** is always emitted (`"true"` / `"false"`); **`aria-current="date"`** marks today; **`aria-disabled`** marks unavailable dates (truthy-only).
+- **Roving tabindex**: exactly one cell (the focused date) is tabbable. `Tab` enters and leaves the grid in one stop.
+- **Boolean `data-*`** on the cell — `data-selected`, `data-today`, `data-highlighted` (the focused/roving cell), `data-disabled`, `data-outside-month` — present when true, absent when false.
+
+## Styling
+
+forty-cdk ships no styles. Add your own class to each piece — the `forCalendar*` selectors are the behavior API, not a styling contract (see [Styling forty-cdk](../../../../../docs/styling.md)). Key your CSS off the reflected `data-*` attributes listed under [Data attributes](#data-attributes).
 
 ```css
 .calendar-cell {
@@ -402,31 +457,7 @@ forty-cdk ships no styles. Add your own class to each piece — the `forCalendar
 }
 ```
 
-## Keyboard
-
-LTR (horizontal arrows mirror under `dir="rtl"`):
-
-| Key                               | Behavior                                                      |
-| --------------------------------- | ------------------------------------------------------------- |
-| **ArrowLeft / ArrowRight**        | Previous / next day.                                          |
-| **ArrowUp / ArrowDown**           | Same weekday, previous / next week.                           |
-| **Home / End**                    | First / last day of the focused week.                         |
-| **PageUp / PageDown**             | Same day-of-month, previous / next month (re-pages the grid). |
-| **Shift+PageUp / Shift+PageDown** | Same month, previous / next year.                             |
-| **Enter / Space**                 | Select the focused date.                                      |
-
-Focus that crosses a month boundary re-pages the visible grid and keeps the focused cell in view. Day-of-month is constrained when paging (e.g. Jan 31 → Feb 28). Paging (the prev / next buttons and `PageUp` / `PageDown`) also clamps the focused date into the `[min, max]` range, so it never lands on a cell outside the selectable bounds; day / week arrows still move freely across unavailable dates so keyboard navigation is never trapped.
-
-## Scope defaults
-
-```ts
-import { provideForCalendarDefaults } from 'forty-cdk/calendar';
-
-// app config or a component's providers — Monday-first weeks for this scope
-providers: [provideForCalendarDefaults({ firstDayOfWeek: 1 })];
-```
-
-## SSR / hydration
+## SSR
 
 The active adapter's `today()` and `format()` resolve against the **runtime** time zone and default locale. Rendered on the server they reflect the _server's_ environment, so a render near midnight (or under a different server locale) can disagree with the browser by up to a day — `ForCalendar` reads `today()` once to mark the `data-today` / `aria-current="date"` cell, so the mismatch surfaces there as a hydration error and a flicker. For SSR, pin a fixed "today" / time zone / locale for both environments, or defer the today-highlight so it only computes client-side:
 
@@ -447,12 +478,3 @@ export class DatePage {
   }
 }
 ```
-
-## Accessibility notes
-
-- **`role="grid"`** on the table, `columnheader` weekday headers, `gridcell` days — the APG Date Picker Dialog technique over a real `<table>`.
-- **`aria-labelledby`** wires the grid to the heading so it names the visible period. Paging the month is announced through a dedicated off-screen `aria-live="polite"` region (owned by `[forCalendar]`), so the period is read on navigation without the heading double-announcing as both a live region and the grid's label.
-- **`aria-label`** on every cell carries the full localized date (e.g. `"Monday, June 15, 2026"`) so screen readers announce the whole date, not the bare day number that stays the cell's visible content. Outside-month padding days are suffixed (`" (outside month)"`) so they are distinguishable. Override the format via `ForCalendar`'s `dateLabel` input.
-- **`aria-selected`** is always emitted (`"true"` / `"false"`); **`aria-current="date"`** marks today; **`aria-disabled`** marks unavailable dates (truthy-only).
-- **Roving tabindex**: exactly one cell (the focused date) is tabbable. `Tab` enters and leaves the grid in one stop.
-- **Boolean `data-*`** on the cell — `data-selected`, `data-today`, `data-highlighted` (the focused/roving cell), `data-disabled`, `data-outside-month` — present when true, absent when false.

package/carousel/README.md

@@ -1,11 +1,34 @@
 # ForCarousel
 
-Headless, styleless carousel primitive implementing the
-[WAI-ARIA APG Carousel pattern](https://www.w3.org/WAI/ARIA/apg/patterns/carousel/).
-It ships slide tracking, keyboard navigation, focus management, and ARIA; you
-supply the markup and CSS.
+A slideshow of content panels with previous / next controls, an indicator group, optional looping and multi-slide views, and an accessible autoplay mode with a pause control.
 
-## Usage
+Headless and styleless: it ships slide tracking, keyboard navigation, focus management, and ARIA; you supply the markup and CSS.
+
+## Anatomy
+
+```html
+<div forCarousel [(activeIndex)]="index" loop ariaLabel="Featured products">
+  <button forCarouselPrevious aria-label="Previous slide">‹</button>
+
+  <div forCarouselViewport>
+    <div forCarouselTrack>
+      <!-- one [forCarouselSlide] per item -->
+      <div forCarouselSlide>Slide content</div>
+    </div>
+  </div>
+
+  <button forCarouselNext aria-label="Next slide">›</button>
+
+  <div forCarouselIndicators ariaLabel="Choose slide to display">
+    <!-- one [forCarouselIndicator] per slide, same order -->
+    <button forCarouselIndicator></button>
+  </div>
+</div>
+```
+
+## Examples
+
+### Basic carousel
 
 ```html
 <div
@@ -44,49 +67,6 @@ desynchronizes the active-indicator state and is dev-guarded by a `console.warn`
 in development builds. Grouped or summarized indicators (fewer dots than slides)
 are not supported.
 
-## Example CSS
-
-The directive publishes geometry as CSS custom properties on the root element
-so they cascade to the track. The consumer applies the transform and transition.
-
-```css
-[forCarouselViewport] {
-  overflow: hidden;
-}
-[forCarouselTrack] {
-  display: flex;
-  transform: translateX(var(--for-carousel-offset));
-  transition: transform 300ms ease;
-}
-[forCarousel][data-orientation='vertical'] [forCarouselTrack] {
-  flex-direction: column;
-  transform: translateY(var(--for-carousel-offset));
-}
-[forCarouselSlide] {
-  flex: 0 0 calc(100% / var(--for-carousel-slides-per-view));
-}
-@media (prefers-reduced-motion: reduce) {
-  [forCarouselTrack] {
-    transition: none;
-  }
-}
-```
-
-## CSS custom properties
-
-The following properties are set on the `[forCarousel]` host and cascade to
-children, unless noted otherwise:
-
-| Property                         | Host                    | Value         | Notes                                                                                                           |
-| -------------------------------- | ----------------------- | ------------- | --------------------------------------------------------------------------------------------------------------- |
-| `--for-carousel-offset`          | `[forCarousel]`         | e.g. `-100%`  | Pure arithmetic from `activeIndex`, `slidesPerView`, `align`.                                                   |
-| `--for-carousel-active-index`    | `[forCarousel]`         | integer       | Current `activeIndex`.                                                                                          |
-| `--for-carousel-slide-count`     | `[forCarousel]`         | integer       | Total registered slides.                                                                                        |
-| `--for-carousel-slides-per-view` | `[forCarousel]`         | integer       | From the `slidesPerView` input.                                                                                 |
-| `--for-carousel-viewport-width`  | `[forCarousel]`         | e.g. `640px`  | Measured via `ResizeObserver`. Absent on the server and before first measurement.                               |
-| `--for-carousel-viewport-height` | `[forCarousel]`         | e.g. `400px`  | Same as above, for the block axis.                                                                              |
-| `--for-carousel-drag`            | `[forCarouselViewport]` | e.g. `-128px` | Live px offset along the primary axis during a drag; absent at rest and under `prefers-reduced-motion: reduce`. |
-
 ## Autoplay
 
 Add the `autoplay` attribute and a `[forCarouselRotationControl]` as the **first
@@ -130,23 +110,6 @@ the defaults with `startLabel` / `stopLabel` inputs:
 <button forCarouselRotationControl startLabel="Play slideshow" stopLabel="Pause slideshow"></button>
 ```
 
-**Styling hooks:**
-
-```css
-[forCarouselRotationControl]::before {
-  content: '▶';
-}
-[forCarouselRotationControl][data-playing]::before {
-  content: '⏸';
-}
-```
-
-| Attribute       | When present                                            |
-| --------------- | ------------------------------------------------------- |
-| `data-playing`  | On `[forCarouselRotationControl]` — user intent is "on" |
-| `data-rotating` | On `[forCarousel]` — actively rotating right now        |
-| `data-autoplay` | On `[forCarousel]` — the `autoplay` input is `true`     |
-
 **Programmatic control** via `exportAs`:
 
 ```html
@@ -224,39 +187,59 @@ horizontal carousels (allows vertical page scroll) and `pan-x` for vertical
 carousels (allows horizontal page scroll). A mostly-cross-axis swipe is never
 captured, so page scrolling on the perpendicular axis is unaffected.
 
-### Styling hooks
+## Localizing the default labels
 
-| Attribute       | Host                    | When present                           |
-| --------------- | ----------------------- | -------------------------------------- |
-| `data-dragging` | `[forCarouselViewport]` | Present while a drag gesture is armed. |
+Each slide's default `aria-label` is the positional `"N of M"` string, and each
+indicator's is `"Go to slide N"`. Localize both centrally with
+`provideForCarouselDefaults` instead of setting `ariaLabel` on every slide and
+indicator:
+
+```ts
+providers: [
+  provideForCarouselDefaults({
+    slideLabel: (position, total) => `Diapositiva ${position} de ${total}`,
+    indicatorLabel: (position) => `Ir a la diapositiva ${position}`,
+  }),
+];
+```
 
-### Inputs on `[forCarouselDrag]`
+`position` is the 1-based slide index and `total` is the slide count. Overrides
+merge with the parent scope, so you can localize just the labels and inherit the
+rest of the defaults. A per-element `ariaLabel` on `[forCarouselSlide]` /
+`[forCarouselIndicator]` still takes precedence over the localized default.
 
-| Input      | Type      | Default | Description                                                                  |
-| ---------- | --------- | ------- | ---------------------------------------------------------------------------- |
-| `disabled` | `boolean` | `false` | Disable pointer drag without removing the directive. Removes `touch-action`. |
+## API
 
-## Inputs
+### `ForCarousel`
 
 All inputs are on `[forCarousel]` unless noted.
 
-| Input                                            | Type                           | Default                        | Description                                                                                                                        |
-| ------------------------------------------------ | ------------------------------ | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
-| `activeIndex`                                    | `model<number>`                | `0`                            | Two-way bindable current slide index.                                                                                              |
-| `orientation`                                    | `'horizontal' \| 'vertical'`   | `'horizontal'`                 | Scroll axis.                                                                                                                       |
-| `loop`                                           | `boolean`                      | `false`                        | Wrap-around at the boundaries.                                                                                                     |
-| `align`                                          | `'start' \| 'center' \| 'end'` | `'start'`                      | Alignment of the active slide.                                                                                                     |
-| `slidesPerView`                                  | `number`                       | `1`                            | Visible slides at once.                                                                                                            |
-| `containScroll`                                  | `boolean`                      | `false`                        | Clamp the track offset so trailing slides sit flush at the viewport edge (no overscroll) when `slidesPerView > 1` and not looping. |
-| `autoplay`                                       | `boolean`                      | `false`                        | Enable auto-rotation (suppressed by `prefers-reduced-motion: reduce`).                                                             |
-| `autoplayInterval`                               | `number`                       | `5000`                         | Ms between automatic slide advances. `<= 0` disables the timer.                                                                    |
-| `ariaLabel`                                      | `string \| null`               | `null`                         | Accessible label for the carousel root.                                                                                            |
-| `dir`                                            | `'ltr' \| 'rtl' \| null`       | `null` (inherits)              | Writing direction.                                                                                                                 |
-| `ariaLabel` (on `[forCarouselIndicators]`)       | `string \| null`               | `null`                         | Label for the picker group.                                                                                                        |
-| `ariaLabel` (on `[forCarouselSlide]`)            | `string \| null`               | `null`                         | Override the positional "N of M" label.                                                                                            |
-| `disabled` (on `[forCarouselIndicator]`)         | `boolean`                      | `false`                        | Disable this indicator.                                                                                                            |
-| `startLabel` (on `[forCarouselRotationControl]`) | `string`                       | `'Start automatic slide show'` | Accessible name while rotation is stopped.                                                                                         |
-| `stopLabel` (on `[forCarouselRotationControl]`)  | `string`                       | `'Stop automatic slide show'`  | Accessible name while rotation is playing.                                                                                         |
+| Property                                         | Type                           | Description                                                                                                                                                |
+| ------------------------------------------------ | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `activeIndex`                                    | `model<number>`                | Two-way bindable current slide index.<br>**Default:** `0`                                                                                                  |
+| `orientation`                                    | `'horizontal' \| 'vertical'`   | Scroll axis.<br>**Default:** `'horizontal'`                                                                                                                |
+| `loop`                                           | `boolean`                      | Wrap-around at the boundaries.<br>**Default:** `false`                                                                                                     |
+| `align`                                          | `'start' \| 'center' \| 'end'` | Alignment of the active slide.<br>**Default:** `'start'`                                                                                                   |
+| `slidesPerView`                                  | `number`                       | Visible slides at once.<br>**Default:** `1`                                                                                                                |
+| `containScroll`                                  | `boolean`                      | Clamp the track offset so trailing slides sit flush at the viewport edge (no overscroll) when `slidesPerView > 1` and not looping.<br>**Default:** `false` |
+| `autoplay`                                       | `boolean`                      | Enable auto-rotation (suppressed by `prefers-reduced-motion: reduce`).<br>**Default:** `false`                                                             |
+| `autoplayInterval`                               | `number`                       | Ms between automatic slide advances. `<= 0` disables the timer.<br>**Default:** `5000`                                                                     |
+| `ariaLabel`                                      | `string \| null`               | Accessible label for the carousel root.<br>**Default:** `null`                                                                                             |
+| `dir`                                            | `'ltr' \| 'rtl' \| null`       | Writing direction.<br>**Default:** `null` (inherits)                                                                                                       |
+| `ariaLabel` (on `[forCarouselIndicators]`)       | `string \| null`               | Label for the picker group.<br>**Default:** `null`                                                                                                         |
+| `ariaLabel` (on `[forCarouselSlide]`)            | `string \| null`               | Override the positional "N of M" label.<br>**Default:** `null`                                                                                             |
+| `disabled` (on `[forCarouselIndicator]`)         | `boolean`                      | Disable this indicator.<br>**Default:** `false`                                                                                                            |
+| `startLabel` (on `[forCarouselRotationControl]`) | `string`                       | Accessible name while rotation is stopped.<br>**Default:** `'Start automatic slide show'`                                                                  |
+| `stopLabel` (on `[forCarouselRotationControl]`)  | `string`                       | Accessible name while rotation is playing.<br>**Default:** `'Stop automatic slide show'`                                                                   |
+
+Reflected on the `[forCarousel]` host:
+
+| Data attribute     | Values                            |
+| ------------------ | --------------------------------- |
+| `data-orientation` | `horizontal` \| `vertical`        |
+| `data-align`       | `start` \| `center` \| `end`      |
+| `data-autoplay`    | present when `autoplay` is `true` |
+| `data-rotating`    | present while actively rotating   |
 
 ### Contain scroll
 
@@ -275,28 +258,19 @@ same clamped view simply share the same visual position. The clamp has no effect
 when `loop` is enabled (the entire range is valid when wrapping) or when
 `slidesPerView` is `1` (a single-view carousel never overscrolls).
 
-## Localizing the default labels
+### `ForCarouselDrag` inputs
 
-Each slide's default `aria-label` is the positional `"N of M"` string, and each
-indicator's is `"Go to slide N"`. Localize both centrally with
-`provideForCarouselDefaults` instead of setting `ariaLabel` on every slide and
-indicator:
+| Property   | Type      | Description                                                                                          |
+| ---------- | --------- | ---------------------------------------------------------------------------------------------------- |
+| `disabled` | `boolean` | Disable pointer drag without removing the directive. Removes `touch-action`.<br>**Default:** `false` |
 
-```ts
-providers: [
-  provideForCarouselDefaults({
-    slideLabel: (position, total) => `Diapositiva ${position} de ${total}`,
-    indicatorLabel: (position) => `Ir a la diapositiva ${position}`,
-  }),
-];
-```
+Reflected on the `[forCarouselViewport]` host this directive is applied to:
 
-`position` is the 1-based slide index and `total` is the slide count. Overrides
-merge with the parent scope, so you can localize just the labels and inherit the
-rest of the defaults. A per-element `ariaLabel` on `[forCarouselSlide]` /
-`[forCarouselIndicator]` still takes precedence over the localized default.
+| Data attribute  | Values                                |
+| --------------- | ------------------------------------- |
+| `data-dragging` | present while a drag gesture is armed |
 
-## Keyboard interaction (indicator group)
+## Keyboard
 
 Keyboard navigation lives on the indicator group. Only the current
 indicator is in the tab order. Arrow keys move focus and activate the target slide
@@ -310,7 +284,9 @@ automatically.
 | `End`                      | Last indicator and slide.                                             |
 | `Enter` / `Space`          | Activate the focused indicator (via native button).                   |
 
-## Accessibility notes
+## Accessibility
+
+Implements the [WAI-ARIA Carousel pattern](https://www.w3.org/WAI/ARIA/apg/patterns/carousel/).
 
 - The root carries `role="group"` and `aria-roledescription="carousel"`. The `ariaLabel` input
   should describe the carousel's purpose without using the word "carousel" (APG guidance).
@@ -330,7 +306,72 @@ automatically.
   `aria-roledescription`, `aria-label`, and `aria-hidden` toggle carry the screen-reader
   experience for non-auto-rotating carousels.
 
-## Reduced-motion
+## Styling
+
+forty-cdk ships no styles. Add your own class to each piece — the `for*` selectors are the behavior API, not a styling contract (see [Styling forty-cdk](../../../../../docs/styling.md)). The directive publishes geometry as CSS custom properties on the root element so they cascade to the track. The consumer applies the transform and transition.
+
+```css
+[forCarouselViewport] {
+  overflow: hidden;
+}
+[forCarouselTrack] {
+  display: flex;
+  transform: translateX(var(--for-carousel-offset));
+  transition: transform 300ms ease;
+}
+[forCarousel][data-orientation='vertical'] [forCarouselTrack] {
+  flex-direction: column;
+  transform: translateY(var(--for-carousel-offset));
+}
+[forCarouselSlide] {
+  flex: 0 0 calc(100% / var(--for-carousel-slides-per-view));
+}
+@media (prefers-reduced-motion: reduce) {
+  [forCarouselTrack] {
+    transition: none;
+  }
+}
+```
+
+### CSS custom properties
+
+The following properties are set on the `[forCarousel]` host and cascade to
+children, unless noted otherwise:
+
+| Property                         | Host                    | Value         | Notes                                                                                                           |
+| -------------------------------- | ----------------------- | ------------- | --------------------------------------------------------------------------------------------------------------- |
+| `--for-carousel-offset`          | `[forCarousel]`         | e.g. `-100%`  | Pure arithmetic from `activeIndex`, `slidesPerView`, `align`.                                                   |
+| `--for-carousel-active-index`    | `[forCarousel]`         | integer       | Current `activeIndex`.                                                                                          |
+| `--for-carousel-slide-count`     | `[forCarousel]`         | integer       | Total registered slides.                                                                                        |
+| `--for-carousel-slides-per-view` | `[forCarousel]`         | integer       | From the `slidesPerView` input.                                                                                 |
+| `--for-carousel-viewport-width`  | `[forCarousel]`         | e.g. `640px`  | Measured via `ResizeObserver`. Absent on the server and before first measurement.                               |
+| `--for-carousel-viewport-height` | `[forCarousel]`         | e.g. `400px`  | Same as above, for the block axis.                                                                              |
+| `--for-carousel-drag`            | `[forCarouselViewport]` | e.g. `-128px` | Live px offset along the primary axis during a drag; absent at rest and under `prefers-reduced-motion: reduce`. |
+
+### Autoplay styling hooks
+
+```css
+[forCarouselRotationControl]::before {
+  content: '▶';
+}
+[forCarouselRotationControl][data-playing]::before {
+  content: '⏸';
+}
+```
+
+| Attribute       | When present                                            |
+| --------------- | ------------------------------------------------------- |
+| `data-playing`  | On `[forCarouselRotationControl]` — user intent is "on" |
+| `data-rotating` | On `[forCarousel]` — actively rotating right now        |
+| `data-autoplay` | On `[forCarousel]` — the `autoplay` input is `true`     |
+
+### Drag styling hooks
+
+| Attribute       | Host                    | When present                           |
+| --------------- | ----------------------- | -------------------------------------- |
+| `data-dragging` | `[forCarouselViewport]` | Present while a drag gesture is armed. |
+
+### Reduced-motion
 
 The directive performs no animation itself. Add the following CSS to disable the transition
 for users who prefer reduced motion:
@@ -343,7 +384,7 @@ for users who prefer reduced motion:
 }
 ```
 
-## RTL support
+### RTL support
 
 Arrow-key direction (ArrowLeft/ArrowRight) is automatically swapped in RTL — handled by
 `resolveListNavigation` and the reflected `dir` attribute. The **visual** track direction