forty-cdk 0.38.0 → 0.40.0

package/README.md

@@ -42,18 +42,19 @@ Two packages are regular dependencies, installed automatically and never declare
 
 ## Entry points
 
-**The package name itself exports nothing.** `import { … } from 'forty-cdk'` resolves to no symbol, and your editor will not auto-import anything under the bare package name — by design, so that the bare name never becomes a second import path for a symbol. There are six specifiers you do import from:
+**The package name itself exports nothing.** `import { … } from 'forty-cdk'` resolves to no symbol, and your editor will not auto-import anything under the bare package name — by design, so that the bare name never becomes a second import path for a symbol. There are seven specifiers you do import from:
 
-| Specifier                                | What it exports                                                                                                                                                                                                                                         |
-| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `forty-cdk/<primitive>`                  | The primitive's directives, components, context tokens and defaults provider — `ForDialog` from `forty-cdk/dialog`, `ForAccordion` from `forty-cdk/accordion`, and so on for every entry in the tables below.                                           |
-| [`forty-cdk/shared`](shared)             | The cross-primitive contract types a primitive's public API references — `WritingDirection`, `VetoableEvent`, `DateAdapter`, `FloatingSide`, … — declared once and published once. Eight ship from their own primitive instead; that README names them. |
-| `forty-cdk/internationalized-date`       | The `@internationalized/date` adapters, kept apart so that optional peer stays genuinely optional.                                                                                                                                                      |
-| [`forty-cdk/defaults`](defaults)         | Every `provideFor<Primitive>Defaults` with its token and interface. Each primitive re-exports its own pair too, but a root provider imported from the primitive loads the primitive at startup; imported from here, it does not.                        |
-| [`forty-cdk/date-adapter`](date-adapter) | The `DateAdapter` contract, the `FOR_DATE_ADAPTER` token and `provideNativeDateAdapter`. `forty-cdk/shared` re-exports them, but a root provider imported from there loads the code every primitive shares at startup; imported from here, it does not. |
-| [`forty-cdk/testing`](testing)           | Spec helpers: keyboard and mouse events dispatched the way a browser dispatches them, stubs for the browser APIs jsdom lacks, and dialog and drawer refs for content mounted outside its manager.                                                       |
+| Specifier                                | What it exports                                                                                                                                                                                                                                                                                     |
+| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `forty-cdk/<primitive>`                  | The primitive's directives, components, context tokens and defaults provider — `ForDialog` from `forty-cdk/dialog`, `ForAccordion` from `forty-cdk/accordion`, and so on for every entry in the tables below.                                                                                       |
+| [`forty-cdk/shared`](shared)             | The cross-primitive contract types a primitive's public API references — `WritingDirection`, `VetoableEvent`, `DateAdapter`, `FloatingSide`, … — declared once and published once. Eight ship from their own primitive instead; that README names them.                                             |
+| `forty-cdk/internationalized-date`       | The `@internationalized/date` adapters, kept apart so that optional peer stays genuinely optional.                                                                                                                                                                                                  |
+| [`forty-cdk/defaults`](defaults)         | Every `provideFor<Primitive>Defaults` with its token and interface. Each primitive re-exports its own pair too, but a root provider imported from the primitive loads the primitive at startup; imported from here, it does not.                                                                    |
+| [`forty-cdk/date-adapter`](date-adapter) | The `DateAdapter` contract, the `FOR_DATE_ADAPTER` token and `provideNativeDateAdapter`. `forty-cdk/shared` re-exports them, but a root provider imported from there loads the code every primitive shares at startup; imported from here, it does not.                                             |
+| [`forty-cdk/id-salt`](id-salt)           | `FOR_ID_SALT` and `provideForIdSalt`, the per-app salt for the ids the primitives generate when several forty-cdk apps share a page. `forty-cdk/shared` re-exports them, but a root provider imported from there loads the code every primitive shares at startup; imported from here, it does not. |
+| [`forty-cdk/testing`](testing)           | Spec helpers: keyboard and mouse events dispatched the way a browser dispatches them, stubs for the browser APIs jsdom lacks, and dialog and drawer refs for content mounted outside its manager.                                                                                                   |
 
-`forty-cdk/core` and `forty-cdk/core-overlay` resolve too, but neither is **public**: together they hold the engines and DI singletons the library refactors freely, and they exist so every primitive resolves that shared implementation to one compiled module. They are two rather than one for a bundling reason you get for free: a published module is a bundler's chunk-splitting unit, so keeping the positioning engine (`@floating-ui/dom` and the overlay shells) in its own module means a lazy route that renders no overlay does not load it. Measured on a seven-lazy-route app, that is **41.7 kB raw / 12.1 kB transfer** a non-overlay route no longer pays. If a symbol you need is not exported by the six specifiers above, it is internal by design — [open an issue](https://github.com/tutkli/forty-cdk/issues) rather than importing from either.
+`forty-cdk/core` and `forty-cdk/core-overlay` resolve too, but neither is **public**: together they hold the engines and DI singletons the library refactors freely, and they exist so every primitive resolves that shared implementation to one compiled module. They are two rather than one for a bundling reason you get for free: a published module is a bundler's chunk-splitting unit, so keeping the positioning engine (`@floating-ui/dom` and the overlay shells) in its own module means a lazy route that renders no overlay does not load it. Measured on a seven-lazy-route app, that is **41.7 kB raw / 12.1 kB transfer** a non-overlay route no longer pays. If a symbol you need is not exported by the seven specifiers above, it is internal by design — [open an issue](https://github.com/tutkli/forty-cdk/issues) rather than importing from either.
 
 ## Errors
 
@@ -71,7 +72,7 @@ Fix: Move ForDialogTitle inside a [forDialog] element, declaring any ng-template
 
 The code is `FORCDK-<AREA>-<NUMBER>`, where the area is the entry point you imported from — so `FORCDK-DATE-PICKER-003` came from `forty-cdk/date-picker`, and `FORCDK-CORE-*` from machinery shared across primitives (those still print the prefix of the primitive you actually wrote). **A code is stable and always means the same failure**, so it is safe to search for, quote in an issue, or match on in your own error handling; a retired code is never reused for something else.
 
-Warnings are dev-mode only. Errors are not: a piece that resolved no context would fail one line later anyway, so it throws in production too and says why.
+Warnings are dev-mode only, and so are the checks on a value you passed: an invalid column name, a misordered list of snap points or an unbound required input throws in development and is skipped in a production build, where the primitive degrades instead. Do not rely on catching one of those in production. A piece that resolved no context, or an overlay trigger that resolved no root, is different: it would fail one line later anyway, so it throws in every build and says why.
 
 ## Primitives
 

package/accordion/README.md

@@ -113,12 +113,13 @@ A disabled item cannot be toggled and is skipped by the arrow keys, while stayin
 
 | Property      | Type                                | Description                                                                                                                                                                                    |
 | ------------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `value`       | `model<readonly string[]>`          | Currently open item values. In single mode the array has 0 or 1 element.<br>**Default:** —                                                                                                     |
+| `value`       | `model<readonly string[]>`          | Currently open item values. In single mode the array has 0 or 1 element.<br>**Default:** `[]`                                                                                                  |
 | `multiple`    | `input<boolean>`                    | When true, multiple items can be open simultaneously.<br>**Default:** `false`                                                                                                                  |
 | `collapsible` | `input<boolean>`                    | Single mode only: when true, the open item can be collapsed by clicking it. Otherwise once any item is open, exactly one stays open.<br>**Default:** `false`                                   |
 | `disabled`    | `input<boolean>`                    | When true, disables every item: each trigger reflects the native `disabled` attribute and cannot toggle. Composes with a per-item `[disabled]`.<br>**Default:** `false`                        |
 | `orientation` | `input<'horizontal' \| 'vertical'>` | Layout direction of the trigger list. In horizontal mode ArrowLeft/Right replace ArrowUp/Down.<br>**Default:** `'vertical'`                                                                    |
 | `dir`         | `input<'ltr' \| 'rtl' \| null>`     | Writing direction. Only relevant in horizontal mode, where it swaps the meaning of Left/Right arrows. `null` inherits the nearest `[dir]` / `<html dir>`, else `'ltr'`.<br>**Default:** `null` |
+| `loop`        | `input<boolean>`                    | When true, arrow navigation wraps from the last trigger to the first and back. Set `false` to stop at the ends.<br>**Default:** `true`                                                         |
 
 | Data attribute     | Values                     |
 | ------------------ | -------------------------- |
@@ -127,10 +128,10 @@ A disabled item cannot be toggled and is skipped by the arrow keys, while stayin
 
 ### `ForAccordionItem`
 
-| Property   | Type                     | Description                                                                                          |
-| ---------- | ------------------------ | ---------------------------------------------------------------------------------------------------- |
-| `value`    | `input.required<string>` | Unique identifier within the accordion. Required.<br>**Default:** —                                  |
-| `disabled` | `input<boolean>`         | When true, the trigger ignores clicks and exposes the native `disabled` attribute.<br>**Default:** — |
+| Property   | Type                     | Description                                                                                                |
+| ---------- | ------------------------ | ---------------------------------------------------------------------------------------------------------- |
+| `value`    | `input.required<string>` | Unique identifier within the accordion. Required.<br>**Default:** —                                        |
+| `disabled` | `input<boolean>`         | When true, the trigger ignores clicks and exposes the native `disabled` attribute.<br>**Default:** `false` |
 
 | Data attribute     | Values                     |
 | ------------------ | -------------------------- |
@@ -143,6 +144,7 @@ A disabled item cannot be toggled and is skipped by the arrow keys, while stayin
 | Data attribute     | Values                     |
 | ------------------ | -------------------------- |
 | `data-state`       | `open` \| `closed`         |
+| `data-disabled`    | present \| absent          |
 | `data-orientation` | `horizontal` \| `vertical` |
 
 ### `ForAccordionContent`
@@ -150,17 +152,20 @@ A disabled item cannot be toggled and is skipped by the arrow keys, while stayin
 | Data attribute     | Values                     |
 | ------------------ | -------------------------- |
 | `data-state`       | `open` \| `closed`         |
+| `data-disabled`    | present \| absent          |
 | `data-orientation` | `horizontal` \| `vertical` |
 
+`data-disabled` on the item, trigger and content reflects the item's own `[disabled]` or the root's, whichever is set.
+
 ## Keyboard
 
-| Key                                          | Action                                                                                            |
-| -------------------------------------------- | ------------------------------------------------------------------------------------------------- |
-| <kbd>Enter</kbd> / <kbd>Space</kbd>          | Toggle the focused trigger (native button).                                                       |
-| <kbd>ArrowDown</kbd> / <kbd>ArrowUp</kbd>    | Move focus between triggers (vertical, default). Wrap-around, skips disabled.                     |
-| <kbd>ArrowLeft</kbd> / <kbd>ArrowRight</kbd> | Move focus between triggers (horizontal, flipped under `dir='rtl'`). Wrap-around, skips disabled. |
-| <kbd>Home</kbd>                              | Jump to the first trigger.                                                                        |
-| <kbd>End</kbd>                               | Jump to the last trigger.                                                                         |
+| Key                                          | Action                                                                                                                      |
+| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| <kbd>Enter</kbd> / <kbd>Space</kbd>          | Toggle the focused trigger (native button).                                                                                 |
+| <kbd>ArrowDown</kbd> / <kbd>ArrowUp</kbd>    | Move focus between triggers (vertical, default). Wraps around unless `loop` is `false`, skips disabled.                     |
+| <kbd>ArrowLeft</kbd> / <kbd>ArrowRight</kbd> | Move focus between triggers (horizontal, flipped under `dir='rtl'`). Wraps around unless `loop` is `false`, skips disabled. |
+| <kbd>Home</kbd>                              | Jump to the first trigger.                                                                                                  |
+| <kbd>End</kbd>                               | Jump to the last trigger.                                                                                                   |
 
 ## Accessibility
 

package/aspect-ratio/README.md

@@ -39,7 +39,7 @@ If your ratio is a literal constant, prefer the CSS property directly and keep t
 
 ## Examples
 
-Resize the preview and watch the frame hold its 16 / 9 ratio. The primitive writes the ratio and nothing else, so every border, colour and inset below is your own CSS.
+Narrow the browser window until the frame shrinks and watch it hold its 16 / 9 ratio. The primitive writes the ratio and nothing else, so every border, colour and inset below is your own CSS.
 
 ```ts
 import { ChangeDetectionStrategy, Component } from '@angular/core';

package/avatar/README.md

@@ -96,10 +96,31 @@ When the image errors, the directive flips `shouldShowFallback()` and the initia
 | -------------- | ------------------------------------------ |
 | `data-status`  | `idle` \| `loading` \| `loaded` \| `error` |
 
+## Scoped defaults
+
+`provideForAvatarDefaults` configures avatar defaults for an injector subtree, either at the application root or in any component's `providers` array. Partial overrides inherit unspecified keys from the parent scope (or the library fallbacks at the root).
+
+| Key               | Library fallback | Meaning                                                                                                                                                                                          |
+| ----------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `fallbackDelayMs` | `0`              | Milliseconds to wait before the fallback shows while the image is idle or loading, for avatars that don't set `fallbackDelayMs` themselves. An `error` status always shows the fallback at once. |
+
+Per-instance inputs always win over the scope defaults.
+
+```ts
+import { type ApplicationConfig } from '@angular/core';
+import { provideForAvatarDefaults } from 'forty-cdk/defaults';
+
+export const appConfig: ApplicationConfig = {
+  providers: [provideForAvatarDefaults({ fallbackDelayMs: 500 })],
+};
+```
+
 ## Accessibility
 
 The directive does not impose a `role`. Pair the avatar with visible name text or `aria-label` on the surrounding element when identity matters. Set `alt=""` on the `<img>` for purely decorative avatars next to a name, or provide a meaningful `alt` description if the avatar stands alone.
 
+A meaningful `alt` names the avatar only while the image is shown: once it fails, the image is hidden and the fallback initials are all that is left to announce. When an avatar stands alone, name the root instead (`role="img"` with an `aria-label`) and give the `<img>` `alt=""`, so the fallback carries the same name as the loaded image.
+
 ## Styling
 
 forty-cdk ships no styles: put your own class on each piece and key your CSS off the `data-*` attributes listed under [API](#api), not off the `for*` selectors ([Styling forty-cdk](../../../docs/styling.md) explains why).

package/breadcrumbs/README.md

@@ -23,7 +23,7 @@ A labelled navigation landmark for a breadcrumb trail: links with aria-current='
 
 ## Examples
 
-Walk the trail with `Tab`: the last crumb is the page you are on, so it carries `aria-current="page"` and is not a link back to itself.
+Walk the trail with `Tab`: the last crumb is the page you are on, so it carries `aria-current="page"` and is announced as the current page.
 
 ```ts
 import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
@@ -86,22 +86,6 @@ export class BreadcrumbsDefaultExample {
 
 The primitive renders whatever items you give it, so collapsing a deep path is a consumer decision. Here the middle is folded into an expandable ellipsis button that reveals the hidden crumbs. The trail stays a single accessible navigation landmark either way.
 
-## Localizing the label
-
-`Breadcrumb` is verbalized by screen readers, so translate it per injector scope with `provideForBreadcrumbsDefaults`. Configure it at the application root, or in any component's `providers` to scope the translation to a subtree. A per-instance `[ariaLabel]` still wins over the scope default.
-
-<!-- snippet: fragment -->
-
-```ts
-import { provideForBreadcrumbsDefaults } from 'forty-cdk/defaults';
-
-bootstrapApplication(App, {
-  providers: [provideForBreadcrumbsDefaults({ label: 'Ruta de navegación' })],
-});
-```
-
-For a language the app sets or switches after bootstrap, pass `label` as a function and the overrides as a factory, as [Localizing default text](../shared/README.md#localizing-default-text) shows.
-
 ## API
 
 ### `ForBreadcrumbs`
@@ -112,9 +96,30 @@ For a language the app sets or switches after bootstrap, pass `label` as a funct
 
 ### `ForBreadcrumbItem`
 
-| Property  | Type             | Description                                                              |
-| --------- | ---------------- | ------------------------------------------------------------------------ |
-| `current` | `input<boolean>` | When true, reflects `aria-current="page"` on the link.<br>**Default:** — |
+| Property  | Type             | Description                                                                    |
+| --------- | ---------------- | ------------------------------------------------------------------------------ |
+| `current` | `input<boolean>` | When true, reflects `aria-current="page"` on the link.<br>**Default:** `false` |
+
+## Scoped defaults
+
+`provideForBreadcrumbsDefaults` configures breadcrumb defaults for an injector subtree, either at the application root or in any component's `providers` array. Partial overrides inherit unspecified keys from the parent scope (or the library fallbacks at the root).
+
+| Key     | Library fallback | Meaning                                                                                           |
+| ------- | ---------------- | ------------------------------------------------------------------------------------------------- |
+| `label` | `'Breadcrumb'`   | Accessible name of the `navigation` landmark, for trails that don't set `[ariaLabel]` themselves. |
+
+`label` is verbalized by screen readers, so translate it here to rename every breadcrumb landmark in the scope. It accepts a string or a function returning one; a function can read a language signal, so the name follows a language the app sets or switches after bootstrap, as [Localizing default text](../shared/README.md#localizing-default-text) shows.
+
+Per-instance inputs always win over the scope defaults.
+
+```ts
+import { type ApplicationConfig } from '@angular/core';
+import { provideForBreadcrumbsDefaults } from 'forty-cdk/defaults';
+
+export const appConfig: ApplicationConfig = {
+  providers: [provideForBreadcrumbsDefaults({ label: 'Ruta de navegación' })],
+};
+```
 
 ## Accessibility
 

package/breakpoints/README.md

@@ -10,9 +10,15 @@ A signal-first, zoneless, SSR-safe viewport breakpoint observer (injectBreakpoin
 
 It is a headless reactive utility, not a UI primitive: no DOM, no ARIA, no template. Configure the breakpoint map **once** via a provider and read it anywhere with `injectBreakpoints()`, so there is no need to repeat the breakpoint set at every call site.
 
-## Setup
+## Scoped defaults
 
-Configuring is optional: without a provider the Tailwind scale (`sm` 640, `md` 768, `lg` 1024, `xl` 1280, `2xl` 1536) is used. To define your own:
+`provideForBreakpointsDefaults` sets the scope's `breakpoints` map, so `injectBreakpoints()` can be called with no arguments. Configuring is optional: without a provider the Tailwind scale is used. Provide it in your application config, or again in any component's `providers` array to replace the map for that subtree only. The nearest scope wins, and its map replaces the parent's wholesale: it is never merged key by key.
+
+| Key           | Library fallback                                                               | Meaning                                                                                                                                             |
+| ------------- | ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `breakpoints` | `forBreakpointsTailwind`: `sm` 640, `md` 768, `lg` 1024, `xl` 1280, `2xl` 1536 | Each breakpoint name paired with its `min-width` threshold in CSS pixels. The query methods derive from these names, sorted ascending by threshold. |
+
+The provider takes the map itself rather than an object with a `breakpoints` key, or a function returning the map when it has to be built where `inject()` is available:
 
 ```ts
 import { ApplicationConfig } from '@angular/core';
@@ -25,21 +31,12 @@ export const appConfig: ApplicationConfig = {
 };
 ```
 
-Providing it again on a component injector replaces the map for that subtree only (nearest scope wins; the map is replaced wholesale, never merged key-by-key).
-
 ## Examples
 
-Resize the preview and watch the matched breakpoint change: `injectBreakpoints()` hands back signals, so the template re-renders without a listener of your own.
+Resize the browser window and watch the matched breakpoint change: the breakpoints follow the viewport, not the preview frame. `injectBreakpoints()` hands back signals, so the template, width range included, re-renders without a listener of your own.
 
 ```ts
-import {
-  afterNextRender,
-  ChangeDetectionStrategy,
-  Component,
-  DestroyRef,
-  inject,
-  signal,
-} from '@angular/core';
+import { ChangeDetectionStrategy, Component, computed } from '@angular/core';
 import { forBreakpointsTailwind, injectBreakpoints } from 'forty-cdk/breakpoints';
 
 type TailwindName = keyof typeof forBreakpointsTailwind;
@@ -52,7 +49,7 @@ type TailwindName = keyof typeof forBreakpointsTailwind;
       <div class="bp-readout">
         <span class="bp-readout-label">active breakpoint</span>
         <span class="bp-active">{{ active() ?? 'below sm' }}</span>
-        <span class="bp-width">viewport ≈ {{ width() }}px</span>
+        <span class="bp-width">viewport {{ range() }}</span>
       </div>
 
       <ul class="bp-grid">
@@ -81,17 +78,12 @@ export class BreakpointsActiveExample {
     only: this.bp.only(name),
   }));
 
-  protected readonly width = signal(0);
-
-  constructor() {
-    const destroyRef = inject(DestroyRef);
-    afterNextRender(() => {
-      const onResize = (): void => this.width.set(globalThis.innerWidth);
-      onResize();
-      globalThis.addEventListener('resize', onResize, { passive: true });
-      destroyRef.onDestroy(() => globalThis.removeEventListener('resize', onResize));
-    });
-  }
+  protected readonly range = computed(() => {
+    const index = this.rows.findIndex((row) => row.name === this.active());
+    const from = this.rows[index]?.min ?? 0;
+    const to = this.rows[index + 1]?.min;
+    return to === undefined ? `${from}px and up` : `${from}px to ${to - 1}px`;
+  });
 }
 ```
 

package/button/README.md

@@ -5,7 +5,7 @@ archetype: [composable-ui]
 apgUrl: https://www.w3.org/WAI/ARIA/apg/patterns/button/
 ---
 
-# ForButton
+# Button
 
 Turns any element (a native `<button>` or a custom host like `<div>` / `<span>`) into an accessible button with keyboard activation. Disabled stays focusable (aria-disabled, never the native attribute) and pressed / hovered / focus-visible are reflected as data-\* hooks.
 

package/calendar/README.md

@@ -188,7 +188,7 @@ export class CalendarDefaultExample {
 
 ### States
 
-One class and one directive, three states. `disabled` turns off focus movement and selection for the whole calendar; `readonly` keeps days focusable and the grid still pages, but clicking or pressing `Enter` no longer changes the selection, and a click moves only the focused day to the clicked cell. Each reflects a root hook (`data-disabled` and `data-readonly`), and the example's stylesheet keys on nothing else.
+One class and one directive, three states. `disabled` turns off focus movement and selection for the whole calendar; `readonly` keeps days focusable and the grid still pages, but clicking or pressing `Enter` no longer changes the selection, and a click moves only the focused day to the clicked cell. Each reflects a root hook (`data-disabled` and `data-readonly`) that the example's stylesheet keys on. A disabled calendar also disables its prev / next buttons, which reflect `data-disabled` of their own rather than the native attribute.
 
 ### Constraints & week start
 
@@ -341,12 +341,18 @@ The recommended path is `[forCalendarMonthSelect]` and `[forCalendarYearSelect]`
         />
       </svg>
     </button>
-    <select forCalendarMonthSelect #m="forCalendarMonthSelect">
+    <select forCalendarMonthSelect #m="forCalendarMonthSelect" aria-label="Month">
       @for (opt of m.options(); track opt.value) {
       <option [value]="opt.value" [disabled]="opt.disabled">{{ opt.label }}</option>
       }
     </select>
-    <select forCalendarYearSelect #y="forCalendarYearSelect" [minYear]="1900" [maxYear]="2100">
+    <select
+      forCalendarYearSelect
+      #y="forCalendarYearSelect"
+      aria-label="Year"
+      [minYear]="1900"
+      [maxYear]="2100"
+    >
       @for (opt of y.years(); track opt.value) {
       <option [value]="opt.value" [disabled]="opt.disabled">{{ opt.value }}</option>
       }
@@ -389,6 +395,8 @@ The default window is **anchored to the current year** (not the visible year), s
 
 **Keep `[forCalendarHeading]` in the DOM.** The grid's `aria-labelledby` points at the heading's id. When dropdowns replace the visible heading, keep a visually-hidden `[forCalendarHeading]` so the grid stays named. Removing the heading entirely leaves `aria-labelledby` pointing at a missing element.
 
+**Name each `<select>` yourself.** Neither directive names the element it sits on, and the heading names the grid, not the dropdowns. Without a name a screen reader announces only the value each one holds, so give each an `aria-label` as the snippet above does, or a `<label for>`.
+
 The lower-level hooks (`visibleMonthNumber()`, `visibleYear()`, `monthOptions()`, `goToMonth()`, `goToYear()`, `isYearDisabled()`) in the table above remain available for any other UI.
 
 ## View switching
@@ -536,6 +544,8 @@ Auto-disabled when the entire previous / next page would be outside `[min, max]`
 
 ## Scoped defaults
 
+`provideForCalendarDefaults` configures calendar defaults for an injector subtree, either at the application root or in any component's `providers` array. Partial overrides inherit unspecified keys from the parent scope (or the library fallbacks at the root).
+
 ```ts
 import { provideForCalendarDefaults } from 'forty-cdk/defaults';
 
@@ -548,6 +558,8 @@ providers: [
 ];
 ```
 
+`firstDayOfWeek` sets the first column's weekday as a **0-6** index (`0` = Sunday, `1` = Monday) for calendars that don't bind `[firstDayOfWeek]`. Its fallback `null` takes the week start from the date adapter's `getFirstDayOfWeek()`, and a calendar's own `[firstDayOfWeek]` input always wins over the scope default.
+
 `outsideMonthLabel` builds the `aria-label` of a padding day outside the visible month from its formatted full date (default `"<date> (outside month)"`), so assistive tech can tell it apart from the month on screen. A calendar bound to its own `[dateLabel]` formatter ignores it.
 
 ## Keyboard
@@ -575,7 +587,7 @@ Implements the [WAI-ARIA Grid pattern](https://www.w3.org/WAI/ARIA/apg/patterns/
 - **`aria-selected`** is always emitted (`"true"` / `"false"`); **`aria-current="date"`** marks today; **`aria-disabled`** marks unavailable dates (truthy-only).
 - **`aria-multiselectable="true"`** is set on the day grid in `selectionMode="range"`, where a committed range selects several cells, and is absent in single mode.
 - **Roving tabindex**: exactly one cell (the focused date) is tabbable. `Tab` enters and leaves the grid in one stop.
-- **Boolean `data-*`** on the cell, present when true and absent when false: `data-selected`, `data-today`, `data-highlighted` (the focused/roving cell), `data-disabled` and `data-outside-month`.
+- **Boolean `data-*`** on the cell, present when true and absent when false: `data-selected`, `data-today`, `data-highlighted` (the roving tab-stop cell, kept after focus leaves the grid), `data-disabled` and `data-outside-month`.
 
 ## Styling
 
@@ -592,7 +604,7 @@ forty-cdk ships no styles: put your own class on each piece and key your CSS off
 .calendar-cell[data-today] {
   outline: 1px solid var(--accent);
 }
-.calendar-cell[data-outside-month] {
+.calendar-cell[data-outside-month]:not([data-selected]) {
   opacity: 0.4;
 }
 .calendar-cell[data-disabled] {

package/carousel/README.md

@@ -5,7 +5,7 @@ archetype: [composable-ui]
 apgUrl: https://www.w3.org/WAI/ARIA/apg/patterns/carousel/
 ---
 
-# ForCarousel
+# Carousel
 
 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.
 
@@ -267,7 +267,7 @@ the defaults with `startLabel` / `stopLabel` inputs:
 ```
 
 Both defaults come from the scope's `rotationStartLabel` / `rotationStopLabel`
-(see [Localizing the default labels](#localizing-the-default-labels)); set either
+(see [Scoped defaults](#scoped-defaults)); set either
 input to `null` when the button carries a visible text label and you don't want
 an `aria-label` overriding it.
 
@@ -357,40 +357,47 @@ 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.
 
-## Localizing the default labels
+## Scoped defaults
 
-Each slide's default `aria-label` is the positional `"N of M"` string, each
-indicator's is `"Go to slide N"`, and the rotation control's swaps between
-`"Start automatic slide show"` and `"Stop automatic slide show"`. The root and
-each slide also carry an `aria-roledescription` (`"carousel"` / `"slide"`), which
-a screen reader speaks in place of the `group` role. Localize them all centrally
-with `provideForCarouselDefaults` instead of setting `ariaLabel` on every slide
-and indicator:
+`provideForCarouselDefaults` configures carousel defaults for an injector subtree, either at the application root or in any component's `providers` array. Partial overrides inherit unspecified keys from the parent scope (or the library fallbacks at the root), so you can localize just the labels and inherit the rest.
 
-<!-- snippet: fragment -->
+| Key                    | Library fallback               | Meaning                                                                                                                                                                                |
+| ---------------------- | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `loop`                 | `false`                        | Whether `next` past the last slide wraps to the first and `prev` before the first wraps to the last, for carousels that don't set `loop` themselves.                                   |
+| `align`                | `'start'`                      | Alignment of the active slide within the viewport, for carousels that don't set `align` themselves.                                                                                    |
+| `slidesPerView`        | `1`                            | Number of slides visible at once, for carousels that don't set `slidesPerView` themselves.                                                                                             |
+| `containScroll`        | `false`                        | Whether the track offset is clamped so trailing slides sit flush at the viewport edge, for carousels that don't set `containScroll` themselves. See [Contain scroll](#contain-scroll). |
+| `autoplay`             | `false`                        | Whether the carousel rotates automatically on mount (never under reduced motion), for carousels that don't set `autoplay` themselves.                                                  |
+| `autoplayInterval`     | `5000`                         | Milliseconds between automatic slide advances, for carousels that don't set `autoplayInterval` themselves.                                                                             |
+| `slideLabel`           | `"N of M"`, e.g. `"2 of 5"`    | Builds each slide's default `aria-label` from `position` (1-based) and `total` (the slide count) and returns the string.                                                               |
+| `indicatorLabel`       | `"Go to slide N"`              | Builds each indicator's default `aria-label` from `position` (1-based) and returns the string.                                                                                         |
+| `rotationStartLabel`   | `'Start automatic slide show'` | Accessible name of `[forCarouselRotationControl]` while rotation is stopped, for controls that don't set `[startLabel]` themselves.                                                    |
+| `rotationStopLabel`    | `'Stop automatic slide show'`  | Accessible name of `[forCarouselRotationControl]` while rotation is playing, for controls that don't set `[stopLabel]` themselves.                                                     |
+| `roleDescription`      | `'carousel'`                   | `aria-roledescription` of the carousel root, spoken in place of its `group` role. An empty string drops the attribute.                                                                 |
+| `slideRoleDescription` | `'slide'`                      | `aria-roledescription` of each `[forCarouselSlide]`, spoken in place of its `group` role. An empty string drops the attribute.                                                         |
+
+Per-instance inputs always win over the scope defaults: an `ariaLabel` on `[forCarouselSlide]` / `[forCarouselIndicator]` overrides the built label, as do `[startLabel]` / `[stopLabel]` on `[forCarouselRotationControl]`.
+
+`rotationStartLabel`, `rotationStopLabel`, `roleDescription` and `slideRoleDescription` each accept a string or a function returning one; a function can read a language signal, so the text follows a language the app sets or switches after bootstrap, as [Localizing default text](../shared/README.md#localizing-default-text) shows. Localize them all centrally 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}`,
-    rotationStartLabel: 'Iniciar la presentación',
-    rotationStopLabel: 'Detener la presentación',
-    roleDescription: 'carrusel',
-    slideRoleDescription: 'diapositiva',
-  }),
-];
+import { type ApplicationConfig } from '@angular/core';
+import { provideForCarouselDefaults } from 'forty-cdk/defaults';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideForCarouselDefaults({
+      slideLabel: (position, total) => `Diapositiva ${position} de ${total}`,
+      indicatorLabel: (position) => `Ir a la diapositiva ${position}`,
+      rotationStartLabel: 'Iniciar la presentación',
+      rotationStopLabel: 'Detener la presentación',
+      roleDescription: 'carrusel',
+      slideRoleDescription: 'diapositiva',
+    }),
+  ],
+};
 ```
 
-`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, as do
-`[startLabel]` / `[stopLabel]` on `[forCarouselRotationControl]`. For a language
-the app sets or switches after bootstrap, pass the text keys as functions and the
-overrides as a factory, as
-[Localizing default text](../shared/README.md#localizing-default-text) shows.
-
 ## Indicators map 1:1 to slides
 
 The picker assumes **one `[forCarouselIndicator]` per `[forCarouselSlide]`**: the
@@ -487,7 +494,7 @@ Implements the [WAI-ARIA Carousel pattern](https://www.w3.org/WAI/ARIA/apg/patte
   `aria-label="N of M"` by default. Override per slide with the `ariaLabel` input,
   or localize the default format and both role descriptions app-wide with
   `provideForCarouselDefaults` (see
-  [Localizing the default labels](#localizing-the-default-labels)).
+  [Scoped defaults](#scoped-defaults)).
 - Slides outside the viewport receive `aria-hidden="true"` and `inert` to remove them from
   the accessibility tree and focus order. The visible set follows the laid-out offset, so
   `align` and `containScroll` decide which slides stay reachable.