forty-cdk 0.39.0 → 0.41.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`, `forty-cdk/core-overlay` and `forty-cdk/core-anchored` resolve too, but none 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 three rather than one for a bundling reason you get for free: a published module is a bundler's chunk-splitting unit, so keeping the overlay machinery in modules of its own means a lazy route that renders no overlay does not load it, and keeping the positioning engine (`@floating-ui/dom` and the anchored overlay shell) apart from the modal shell means an app that opens a dialog from its initial bundle does not load the engine with it. Measured on a seven-lazy-route app, the first split 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 any of them.
 
 ## 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,6 +96,25 @@ 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.

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';
@@ -84,23 +84,7 @@ export class BreadcrumbsDefaultExample {
 
 ### Collapsing a long trail
 
-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.
+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. Expanding removes the button, so focus moves to the first crumb it revealed instead of falling back to the page. The trail stays a single accessible navigation landmark either way.
 
 ## API
 
@@ -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,34 +31,27 @@ 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';
+import { ForVisuallyHidden } from 'forty-cdk/visually-hidden';
 
 type TailwindName = keyof typeof forBreakpointsTailwind;
 
 @Component({
   selector: 'app-breakpoints-active-example',
   changeDetection: ChangeDetectionStrategy.OnPush,
+  imports: [ForVisuallyHidden],
   template: `
     <div class="bp-demo">
       <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">
@@ -61,8 +60,16 @@ type TailwindName = keyof typeof forBreakpointsTailwind;
             <span class="bp-name">{{ row.name }}</span>
             <span class="bp-min">≥ {{ row.min }}px</span>
             <span class="bp-flags">
-              <span class="bp-flag" [class.bp-flag--on]="row.up()">up</span>
-              <span class="bp-flag" [class.bp-flag--on]="row.only()">only</span>
+              <span class="bp-flag" [class.bp-flag--on]="row.up()">
+                <span aria-hidden="true">{{ row.up() ? '✓' : '✕' }}</span>
+                up
+                <span forVisuallyHidden>{{ row.up() ? 'matches' : 'does not match' }}</span>
+              </span>
+              <span class="bp-flag" [class.bp-flag--on]="row.only()">
+                <span aria-hidden="true">{{ row.only() ? '✓' : '✕' }}</span>
+                only
+                <span forVisuallyHidden>{{ row.only() ? 'matches' : 'does not match' }}</span>
+              </span>
             </span>
           </li>
         }
@@ -81,17 +88,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/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
 
@@ -393,7 +393,9 @@ The recommended path is `[forCalendarMonthSelect]` and `[forCalendarYearSelect]`
 
 The default window is **anchored to the current year** (not the visible year), so navigating far away never drops the current year off the list. Out-of-`[min, max]` entries have `disabled: true`, matching the `CalendarYearOption` shape. Both directives set the native `disabled` attribute on the `<select>` itself when the calendar is disabled.
 
-**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.
+**Keep `[forCalendarHeading]` in the DOM.** The grid's `aria-labelledby` points at the heading's id while a heading is mounted. When dropdowns replace the visible heading, keep a visually-hidden `[forCalendarHeading]` so the grid stays named. Without a heading the grids emit no `aria-labelledby` at all, so they are unnamed unless you name them: a static `aria-labelledby` pointing at your own title, or an `aria-label`, written on each grid.
+
+**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.
 
@@ -542,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';
 
@@ -554,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
@@ -576,7 +582,7 @@ Focus that crosses a month boundary re-pages the visible grid and keeps the focu
 Implements the [WAI-ARIA Grid pattern](https://www.w3.org/WAI/ARIA/apg/patterns/grid/).
 
 - **`role="grid"`** on the table, `columnheader` weekday headers and `gridcell` days follow 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-labelledby`** wires the grid to the heading so it names the visible period. It is emitted only while a `[forCalendarHeading]` is mounted, and a static `aria-labelledby` you write on the grid replaces it. 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).
 - **`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.
@@ -598,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

@@ -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.

package/combobox/README.md

@@ -239,6 +239,41 @@ The content anchors to the field box when a `[forComboboxAnchor]` is present; se
 
 Focus stays on the `<input>` the whole time the listbox is open, so options never get `:focus`. `data-highlighted` is the canonical hook for styling the keyboard-active option. A mouse press anywhere on the popup that lands on no focusable element (padding, a group label, an empty or status row) does not move focus either, so typing and the arrow keys keep working after it; the trade-off is that popup text cannot be selected with the mouse, as in a native combobox. A press on a `[forComboboxAction]` still focuses it in every browser. A press on your own `<button>` inside the popup is left to the browser, and macOS Safari and Firefox do not focus a `<button>` on a press.
 
+## Scoped defaults
+
+`provideForComboboxDefaults` configures combobox 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                                                                                                                                                                                         |
+| --------------------- | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `side`                | `'bottom'`                         | Anchor side for comboboxes that don't set `side` themselves.                                                                                                                                    |
+| `align`               | `'start'`                          | Alignment along `side` for comboboxes that don't set `align` themselves. `start` and `end` follow the writing direction.                                                                        |
+| `sideOffset`          | `4`                                | Main-axis gap (px) for comboboxes that don't set `sideOffset` themselves.                                                                                                                       |
+| `collisionPadding`    | `8`                                | Collision-middleware padding (px) for comboboxes that don't set it themselves.                                                                                                                  |
+| `openHighlight`       | `'first'`                          | Where the editable anatomy's highlight lands on open (`'first'` or `'selected'`), for comboboxes that don't set `openHighlight` themselves. See [Open / close behavior](#open--close-behavior). |
+| `restoreQueryOnClose` | `false`                            | Whether a single-select editable combobox writes the selected option's label back into `query` when the listbox closes without a pick, for comboboxes that don't set it themselves.             |
+| `loop`                | `true`                             | Whether arrow navigation wraps past the first / last enabled option, for comboboxes that don't set `loop` themselves.                                                                           |
+| `toggleAriaLabel`     | `'Show options'`                   | Accessible name of a `[forComboboxToggle]` that sets no `[ariaLabel]`.                                                                                                                          |
+| `chipsAriaLabel`      | `'Selected items'`                 | Accessible name of a multi-mode `[forComboboxChips]` group that sets no `[ariaLabel]`.                                                                                                          |
+| `clearAriaLabel`      | `'Clear'`                          | Accessible name of a `[forComboboxClear]` that sets no `[ariaLabel]`.                                                                                                                           |
+| `chipRemoveLabel`     | `` (label) => `Remove ${label}` `` | Builds the accessible name of every `[forComboboxChipRemove]` from its chip's resolved option label. The piece takes no per-instance `[ariaLabel]`, so this key is the only way to change it.   |
+
+Per-instance inputs always win over the scope defaults. `toggleAriaLabel`, `chipsAriaLabel` and `clearAriaLabel` accept a string or a function returning one; the library calls the function each time it renders the name, so a function that reads a language signal keeps the name in the current language. See [Localizing default text](../shared/README.md#localizing-default-text).
+
+```ts
+import { type ApplicationConfig } from '@angular/core';
+import { provideForComboboxDefaults } from 'forty-cdk/defaults';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideForComboboxDefaults({
+      openHighlight: 'selected',
+      clearAriaLabel: 'Clear selection',
+      chipRemoveLabel: (label) => `Remove ${label} from the selection`,
+    }),
+  ],
+};
+```
+
 ## Mount/visibility convention
 
 `[forComboboxContent]` follows the floating-overlay convention: the consumer's signal drives `@if`, the directive emits dismiss events when it wants to be unmounted. No `[hidden]`. The visible input lives outside the overlay; only the listbox surface portals.
@@ -751,7 +786,7 @@ When `[forComboboxVirtualized]` is absent or its `[totalCount]` is omitted, the
 
 ## Writing direction
 
-`[forCombobox]` exposes a `dir: 'ltr' | 'rtl'` input (default `'ltr'`). It drives:
+`[forCombobox]` exposes a `dir: 'ltr' | 'rtl' | null` input (default `null`: inherited from the nearest `[dir]` ancestor or `<html dir>`, falling back to `'ltr'`). It drives:
 
 - **Chip keyboard navigation**: ArrowLeft / ArrowRight roles swap so they follow the visual order of the chip cluster, not the DOM order. See _Chip keyboard_ above.
 - **Default popover placement**: `align` defaults to `'start'` and `side` to `'bottom'`. `start` and `end` resolve against the writing direction, so the default anchors the listbox to the visually-leading edge of the input in both LTR and RTL, and a consumer-provided `[align]` follows the direction the same way. `provideForComboboxDefaults({ align, side })` sets either for a whole scope.
@@ -851,7 +886,7 @@ Implements the [WAI-ARIA Combobox pattern](https://www.w3.org/WAI/ARIA/apg/patte
 - `data-state="checked" | "unchecked"` always reflects membership in `value()`, so consumers can paint a checkmark icon with pure CSS regardless of mode.
 - `data-highlighted=""` marks the option that is the current `aria-activedescendant`. Because focus stays on the `<input>`, there is no `:focus` on the option to style. `data-highlighted` is the canonical CSS hook.
 - Disabled options keep the host `aria-disabled="true"`. Click and hover (activedescendant pinning) are no-ops on disabled options.
-- `[forComboboxSeparator]` never registers with the listbox's option collection, so keyboard navigation skips it automatically. It carries `role="separator"` and emits `aria-orientation` only for `orientation="vertical"`, because `horizontal` is the ARIA default; `data-orientation` is always stamped for styling. Set `decorative` when the surrounding options already convey the split. Setting it switches the line to `role="none"` and drops `aria-orientation`, matching the [shared separator emission policy](../separator/README.md#accessibility).
+- `[forComboboxSeparator]` is skipped by keyboard navigation. It is always presentational: `role="none"` and no `aria-orientation`, because it sits inside the `role="listbox"` (the content in the editable anatomy, the list in the picker anatomy), which may only own `option` / `group` children. `data-orientation` is always stamped for styling. When the split must be announced, wrap the options on each side in a `[forComboboxGroup]` with a `[forComboboxGroupLabel]`.
 - `[forComboboxGroup]` is purely advisory grouping: options inside still register flatly with the root, so navigation flows through groups without interruption.
 - `[forComboboxEmpty]` and `[forComboboxStatus]` carry `role="status"` and nothing else. The role already implies `aria-live="polite"` and `aria-atomic="true"`, so the empty-state message is announced, whole, when filtering removes all matches. The role is the channel they keep (rather than the attribute pair) because `[forComboboxEmpty]` self-hides and comes back with its message already in the DOM: a live _role_ is what screen readers read reliably on insertion.
 - Non-option pieces (`[forComboboxAction]`, and ideally `[forComboboxEmpty]` / `[forComboboxStatus]`) belong inside `[forComboboxContent]` but **outside** `[forComboboxList]`, because `role="listbox"` may only own `option` / `group` children (`aria-required-owned-elements`). Wrapping the options in a `[forComboboxList]` (the "editable + list" shape) makes those pieces siblings of the listbox. `[forComboboxAction]` **requires** a `[forComboboxList]` and throws `[forty-cdk/combobox]` without one; `[forComboboxEmpty]` / `[forComboboxStatus]` stay lenient in the bare editable anatomy (documented compromise, see the [editable-anatomy caveat](#anatomy)).

package/context-menu/README.md

@@ -119,6 +119,30 @@ Same vetoable dismiss API as DropdownMenu. Call `preventDefault()` on the emitte
 | `[forContextMenuTrigger]` | `data-state`    | `open` \| `closed` |
 | `[forContextMenuTrigger]` | `data-disabled` | present \| absent  |
 
+## Scoped defaults
+
+`provideForContextMenuDefaults` configures context-menu 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                                                                                                                                                                                   |
+| --------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `side`                      | `'bottom'`       | Anchor side, relative to the pointer, for context menus that don't set `side` themselves.                                                                                                 |
+| `align`                     | `'start'`        | Alignment along `side` for context menus that don't set `align` themselves.                                                                                                               |
+| `sideOffset`                | `0`              | Main-axis gap (px) between the pointer and the menu for context menus that don't set `sideOffset` themselves.                                                                             |
+| `collisionPadding`          | `8`              | Collision-middleware padding (px) for context menus that don't set it themselves.                                                                                                         |
+| `fallbackAxisSideDirection` | `'none'`         | Perpendicular side `flip` may drop to when both sides of the preferred axis overflow. `'none'` keeps only the opposite same-axis placement. Only consulted while `avoidCollisions` is on. |
+| `loop`                      | `true`           | Whether arrow navigation wraps past the first / last enabled item, for context menus that don't set `loop` themselves.                                                                    |
+
+Per-instance inputs always win over the scope defaults. Submenus inside a context menu take their timings and placement from `provideForMenuDefaults`; see the [Menu README](../menu/README.md#scoped-defaults).
+
+```ts
+import { type ApplicationConfig } from '@angular/core';
+import { provideForContextMenuDefaults } from 'forty-cdk/defaults';
+
+export const appConfig: ApplicationConfig = {
+  providers: [provideForContextMenuDefaults({ sideOffset: 2, fallbackAxisSideDirection: 'end' })],
+};
+```
+
 ## Accessibility
 
 `[forContextMenu]` implements the [WAI-ARIA Menu pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menubar/). The trigger captures `contextmenu`, `Shift+F10`, and the `ContextMenu` key; the menu surface and item roles come from the shared [`menu/`](../menu/README.md) primitives. Pointer activations anchor at the cursor; keyboard activations anchor at the bounding rect of the focused element so keyboard-only users get the menu next to whatever they're working on.
@@ -208,4 +232,4 @@ Both triggers carry `[menuPositioning]`, a partial `{ side, align, sideOffset, a
 
 ## Wrapping in a design system
 
-Subclass the root and re-provide `FOR_MENU_CONTEXT` with `useExisting` pointing at the subclass, since Angular does not inherit a directive's `providers`; [Wrapping non-form roots](../../../docs/wrapping-non-form-roots.md) walks the pattern.
+Subclass the root and re-provide both of its tokens, `FOR_MENU_CONTEXT` and `FOR_CONTEXT_MENU_CONTEXT`, with `useExisting` pointing at the subclass, since Angular does not inherit a directive's `providers`. Leaving out the second one throws `FORCDK-CONTEXT-MENU-001` from the trigger. [Wrapping non-form roots](../../../docs/wrapping-non-form-roots.md) walks the pattern.