forty-cdk 0.27.0 → 0.28.0

package/accordion/README.md

@@ -175,7 +175,7 @@ A disabled item cannot be toggled and is skipped by the arrow keys, while stayin
 
 ## Styling
 
-forty-cdk ships no styles. Add your own class to each piece. The `for*` selectors are the behavior API, not a styling contract (see [Styling forty-cdk](../../../docs/styling.md)). Key your CSS off the reflected `data-*` attributes listed per piece in the [API](#api) section.
+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).
 
 ```css
 .chevron {
@@ -189,4 +189,4 @@ forty-cdk ships no styles. Add your own class to each piece. The `for*` selector
 
 ## Wrapping in a design system
 
-Subclassing the root is the supported pattern; the subclass must re-provide `FOR_ACCORDION_CONTEXT` with `useExisting` pointing at itself, because Angular does not inherit a directive's `providers` and every projected piece resolves its context through that token. See [Wrapping non-form roots](../../../docs/wrapping-non-form-roots.md).
+Subclass the root and re-provide `FOR_ACCORDION_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.

package/aspect-ratio/README.md

@@ -76,7 +76,7 @@ Set `ratio` to `1` to keep a box perfectly square at any width. That is handy fo
 
 ## Styling
 
-forty-cdk ships no styles. Add your own class to each piece. The `for*` selectors are the behavior API, not a styling contract (see [Styling forty-cdk](../../../docs/styling.md)). This primitive is purely structural: its only host effect is the native `aspect-ratio` style, so it reflects no `data-*` attributes and writes no CSS custom properties. Style the host through your own class on `[forAspectRatio]`.
+forty-cdk ships no styles: put your own class on the host rather than styling the `for*` selector ([Styling forty-cdk](../../../docs/styling.md) explains why). This primitive is purely structural: its only host effect is the native `aspect-ratio` style, so it reflects no `data-*` attributes and writes no CSS custom properties.
 
 ## Behavior notes
 

package/avatar/README.md

@@ -102,7 +102,7 @@ The directive does not impose a `role`. Pair the avatar with visible name text o
 
 ## Styling
 
-forty-cdk ships no styles. Add your own class to each piece. The `for*` selectors are the behavior API, not a styling contract (see [Styling forty-cdk](../../../docs/styling.md)). Key your CSS off the reflected `data-*` attributes listed per piece in the [API](#api) section.
+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).
 
 ```css
 .avatar-image:not([data-status='loaded']) {
@@ -122,4 +122,4 @@ forty-cdk ships no styles. Add your own class to each piece. The `for*` selector
 
 ## Wrapping in a design system
 
-Subclassing the root is the supported pattern; the subclass must re-provide `FOR_AVATAR_CONTEXT` because Angular does not inherit a directive's `providers`, and every projected piece resolves its context through it. See [Wrapping non-form roots](../../../docs/wrapping-non-form-roots.md).
+Subclass the root and re-provide `FOR_AVATAR_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.

package/breadcrumbs/README.md

@@ -100,6 +100,8 @@ bootstrapApplication(App, {
 });
 ```
 
+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`

package/button/README.md

@@ -115,7 +115,7 @@ Implements the [WAI-ARIA Button pattern](https://www.w3.org/WAI/ARIA/apg/pattern
 
 ## Styling
 
-forty-cdk ships no styles. Add your own class to each piece. The `for*` selectors are the behavior API, not a styling contract (see [Styling forty-cdk](../../../docs/styling.md)). Key your CSS off the reflected `data-*` attributes listed per piece in the [API](#api) section.
+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).
 
 ```css
 [forButton][data-disabled] {

package/calendar/README.md

@@ -220,7 +220,7 @@ Click the heading button to cycle from day → month → year view. Click a mont
 | `min`               | `input<D \| null>`                     | Minimum selectable date (inclusive). Earlier dates are unavailable.<br>**Default:** `null`                                                                                                   |
 | `max`               | `input<D \| null>`                     | Maximum selectable date (inclusive). Later dates are unavailable.<br>**Default:** `null`                                                                                                     |
 | `isDateUnavailable` | `input<(date: D) => boolean>`          | Per-date predicate marking a date unavailable (present but not selectable).<br>**Default:** `() => false`                                                                                    |
-| `dateLabel`         | `input<CalendarDateLabelFormatter<D>>` | Formats each gridcell's `aria-label` (full accessible date).<br>**Default:** localized full date, outside-month days suffixed                                                                |
+| `dateLabel`         | `input<CalendarDateLabelFormatter<D>>` | Formats each gridcell's `aria-label` (full accessible date).<br>**Default:** localized full date, outside-month days through the scope's `outsideMonthLabel`                                 |
 | `disabled`          | `input<boolean>`                       | Disables the whole calendar (no focus movement, no selection). Reflected as `data-disabled`.<br>**Default:** —                                                                               |
 | `readonly`          | `input<boolean>`                       | Read-only: dates stay focusable, selection is blocked. Reflected as `data-readonly`.<br>**Default:** —                                                                                       |
 | `firstDayOfWeek`    | `input<number \| null>`                | First column's weekday, **0-6** (`0` = Sunday).<br>**Default:** `null` → the adapter's value (or `provideForCalendarDefaults`)                                                               |
@@ -538,9 +538,16 @@ Auto-disabled when the entire previous / next page would be outside `[min, max]`
 import { provideForCalendarDefaults } from 'forty-cdk/calendar';
 
 // app config or a component's providers — Monday-first weeks for this scope
-providers: [provideForCalendarDefaults({ firstDayOfWeek: 1 })];
+providers: [
+  provideForCalendarDefaults({
+    firstDayOfWeek: 1,
+    outsideMonthLabel: (formattedDate) => `${formattedDate} (fuera del mes)`,
+  }),
+];
 ```
 
+`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
 
 LTR (horizontal arrows mirror under `dir="rtl"`):
@@ -569,7 +576,7 @@ Implements the [WAI-ARIA Grid pattern](https://www.w3.org/WAI/ARIA/apg/patterns/
 
 ## Styling
 
-forty-cdk ships no styles. Add your own class to each piece. The `forCalendar*` selectors are the behavior API, not a styling contract (see [Styling forty-cdk](../../../docs/styling.md)). Key your CSS off the reflected `data-*` attributes listed under [Data attributes](#data-attributes).
+forty-cdk ships no styles: put your own class on each piece and key your CSS off the `data-*` attributes listed under [Data attributes](#data-attributes), not off the `forCalendar*` selectors ([Styling forty-cdk](../../../docs/styling.md) explains why).
 
 ```css
 .calendar-cell {
@@ -615,4 +622,4 @@ export class DatePage {
 
 ## Wrapping in a design system
 
-Subclassing the root is the supported pattern; the subclass must re-provide `FOR_CALENDAR_CONTEXT` because Angular does not inherit a directive's `providers`, and every projected piece resolves its context through it. See [Wrapping non-form roots](../../../docs/wrapping-non-form-roots.md).
+Subclass the root and re-provide `FOR_CALENDAR_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.

package/carousel/README.md

@@ -74,7 +74,8 @@ import {
 
 interface Slide {
   readonly id: number;
-  readonly label: string;
+  readonly title: string;
+  readonly summary: string;
 }
 
 @Component({
@@ -98,7 +99,7 @@ interface Slide {
       loop
       orientation="horizontal"
       align="start"
-      ariaLabel="Featured slides"
+      ariaLabel="Featured stories"
     >
       <div class="car-controls-row">
         <button forCarouselPrevious class="car-btn" aria-label="Previous slide">
@@ -131,7 +132,8 @@ interface Slide {
         <div forCarouselTrack class="car-track">
           @for (slide of slides; track slide.id; let i = $index) {
             <div forCarouselSlide class="car-slide" [class]="'car-slide--' + (i + 1)">
-              <span class="car-slide-label">{{ slide.label }}</span>
+              <p class="car-slide-title">{{ slide.title }}</p>
+              <p class="car-slide-summary">{{ slide.summary }}</p>
             </div>
           }
         </div>
@@ -151,11 +153,27 @@ interface Slide {
 })
 export class CarouselDefaultExample {
   protected readonly slides: readonly Slide[] = [
-    { id: 1, label: 'Slide 1' },
-    { id: 2, label: 'Slide 2' },
-    { id: 3, label: 'Slide 3' },
-    { id: 4, label: 'Slide 4' },
-    { id: 5, label: 'Slide 5' },
+    {
+      id: 1,
+      title: 'The coast road north',
+      summary: 'Four days, three ferries and one small car.',
+    },
+    {
+      id: 2,
+      title: 'Markets before dawn',
+      summary: 'Where the city buys its fish, flowers and coffee.',
+    },
+    {
+      id: 3,
+      title: 'A week without screens',
+      summary: 'What changed, and the one habit that stuck.',
+    },
+    { id: 4, title: 'Bread, slowly', summary: 'A starter, a schedule and a forgiving first loaf.' },
+    {
+      id: 5,
+      title: 'Mapping the old river',
+      summary: 'Tracing a buried stream through five neighbourhoods.',
+    },
   ];
 
   protected readonly activeIndex = signal(0);
@@ -339,9 +357,11 @@ captured, so page scrolling on the perpendicular axis is unaffected.
 
 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"`. Localize them
-all centrally with `provideForCarouselDefaults` instead of setting `ariaLabel` on
-every slide and indicator:
+`"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:
 
 <!-- snippet: fragment -->
 
@@ -352,6 +372,8 @@ providers: [
     indicatorLabel: (position) => `Ir a la diapositiva ${position}`,
     rotationStartLabel: 'Iniciar la presentación',
     rotationStopLabel: 'Detener la presentación',
+    roleDescription: 'carrusel',
+    slideRoleDescription: 'diapositiva',
   }),
 ];
 ```
@@ -360,7 +382,10 @@ providers: [
 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]`.
+`[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
 
@@ -455,7 +480,8 @@ Implements the [WAI-ARIA Carousel pattern](https://www.w3.org/WAI/ARIA/apg/patte
   should describe the carousel's purpose without using the word "carousel" (APG guidance).
 - Each slide carries `role="group"`, `aria-roledescription="slide"`, and
   `aria-label="N of M"` by default. Override per slide with the `ariaLabel` input,
-  or localize the default format app-wide with `provideForCarouselDefaults` (see
+  or localize the default format and both role descriptions app-wide with
+  `provideForCarouselDefaults` (see
   [Localizing the default labels](#localizing-the-default-labels)).
 - Off-view slides receive `aria-hidden="true"` and `inert` to remove them from the
   accessibility tree and focus order.
@@ -473,7 +499,7 @@ Implements the [WAI-ARIA Carousel pattern](https://www.w3.org/WAI/ARIA/apg/patte
 
 ## Styling
 
-forty-cdk ships no styles. Add your own class to each piece. The `for*` selectors are the behavior API, not a styling contract (see [Styling forty-cdk](../../../docs/styling.md)). The directive publishes geometry as CSS custom properties on the root element so they cascade to the track. The consumer applies the transform and transition.
+forty-cdk ships no styles: put your own class on each piece rather than styling the `for*` selectors ([Styling forty-cdk](../../../docs/styling.md) explains why). The directive publishes geometry as CSS custom properties on the root element so they cascade to the track. The consumer applies the transform and transition.
 
 ```css
 [forCarouselViewport] {
@@ -577,4 +603,4 @@ The example CSS above is LTR-only by default.
 
 ## Wrapping in a design system
 
-Subclassing the root is the supported pattern; the subclass must re-provide `FOR_CAROUSEL_CONTEXT` with `useExisting` pointing at itself, because Angular does not inherit a directive's `providers` and every projected piece resolves its context through that token. See [Wrapping non-form roots](../../../docs/wrapping-non-form-roots.md).
+Subclass the root and re-provide `FOR_CAROUSEL_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.

package/checkbox/README.md

@@ -188,7 +188,7 @@ Implements the [WAI-ARIA Checkbox pattern](https://www.w3.org/WAI/ARIA/apg/patte
 
 ## Styling
 
-forty-cdk ships no styles. Add your own class to each piece. The for\* selectors are the behavior API, not a styling contract (see [Styling forty-cdk](../../../docs/styling.md)). Key your CSS off the reflected data-\* attributes listed per piece in the [API](#api) section.
+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).
 
 ```css
 .cb-check {
@@ -213,4 +213,4 @@ forty-cdk ships no styles. Add your own class to each piece. The for\* selectors
 
 ## Wrapping in a design system
 
-Both supported wrapper patterns are documented in [Wrapping form primitives](../../../docs/wrapping-form-primitives.md): `hostDirectives` with the exported `FOR_CHECKBOX_HOST_DIRECTIVE_INPUTS` / `FOR_CHECKBOX_HOST_DIRECTIVE_OUTPUTS` name tuples, and subclassing.
+[Wrapping form primitives](../../../docs/wrapping-form-primitives.md) documents both supported wrapper patterns: `hostDirectives` with the exported `FOR_CHECKBOX_HOST_DIRECTIVE_INPUTS` / `FOR_CHECKBOX_HOST_DIRECTIVE_OUTPUTS` name tuples, and subclassing.

package/combobox/README.md

@@ -772,7 +772,7 @@ Implements the [WAI-ARIA Combobox pattern](https://www.w3.org/WAI/ARIA/apg/patte
 
 ## Styling
 
-forty-cdk ships no styles. Add your own class to each piece. The for\* selectors are the behavior API, not a styling contract (see [Styling forty-cdk](../../../docs/styling.md)). Key your CSS off the reflected data-\* attributes listed under [Data attributes](#data-attributes).
+forty-cdk ships no styles: put your own class on each piece and key your CSS off the `data-*` attributes listed under [Data attributes](#data-attributes), not off the `for*` selectors ([Styling forty-cdk](../../../docs/styling.md) explains why).
 
 ### CSS custom properties
 

package/context-menu/README.md

@@ -122,7 +122,7 @@ Same vetoable dismiss API as DropdownMenu. Call `preventDefault()` on the emitte
 
 ## Styling
 
-forty-cdk ships no styles. Add your own class to each piece. The for\* selectors are the behavior API, not a styling contract (see [Styling forty-cdk](../../../docs/styling.md)). Key your CSS off the reflected data-\* attributes listed under [Data attributes](#data-attributes).
+forty-cdk ships no styles: put your own class on each piece and key your CSS off the `data-*` attributes listed under [Data attributes](#data-attributes), not off the `for*` selectors ([Styling forty-cdk](../../../docs/styling.md) explains why).
 
 > The menu content (`[forMenuContent]`, from the [`menu/`](../menu/README.md) folder) portals to `document.body`, so it sits outside the trigger's DOM subtree and descendant selectors won't reach it. Style it with **global CSS** or a class on the content element. The content host also exposes the shared positioner custom properties (`--for-floating-anchor-width` / `--for-floating-anchor-height`, `--for-floating-available-width` / `--for-floating-available-height`, `--for-floating-content-transform-origin`); see [Styling floating content](../../../docs/styling-floating-content.md) for the full list and the animation rules.
 
@@ -138,6 +138,7 @@ forty-cdk ships no styles. Add your own class to each piece. The for\* selectors
 - **Virtual anchor.** Right-click captures a 0×0 rect at the pointer location. `Shift+F10` and `ContextMenu` snapshot the bounding rect of the focused element (or the trigger if focus is on it directly), so the menu floats off the element under attention. Both forms feed floating-ui's `flip` and `shift` middleware, so corners and screen edges work without special-casing.
 - **Keyboard activators only fire while focus is inside the trigger.** Keyboard events dispatch to the focused element, so `Shift+F10` / `ContextMenu` anywhere outside the trigger goes to the browser default. The trigger is focusable by default (host-bound `tabindex="-1"`), so this works out of the box and focus can return to it programmatically when the menu closes. Your own `tabindex` wins over that default: use `tabindex="0"` if you want the region itself reachable via Tab.
 - **Native menu suppressed.** The trigger calls `event.preventDefault()` on `contextmenu` and on the keyboard activators. Set `disabled` to let the browser's native menu surface for that region.
+- **An open that renders nothing closes again.** When a right-click, `Shift+F10`, the `ContextMenu` key or a long-press opens a menu whose template renders no `[forMenuContent]`, the trigger closes it after the next render with reason `'programmatic'`, and dev mode logs `FORCDK-CONTEXT-MENU-002` once. The native menu cannot come back for that gesture, because it was already suppressed, so bind `[disabled]` to the same condition that renders the content: `[disabled]="!hasActions(col)"` beside `@if (hasActions(col))`.
 - **Touch long-press.** The trigger runs its own long-press timer (a `touch` `pointerdown` held ~500 ms, without lifting or moving past a small tolerance, opens the menu at the touch point). This is required because iOS Safari never fires the `contextmenu` event a long-press synthesizes elsewhere; where the browser does synthesize it (Android, desktop touch emulation) the two paths stay mutually exclusive, so the menu opens exactly once. For the press to survive on iOS, suppress the native callout / text-selection on the trigger with CSS, since otherwise the OS gesture cancels the press:
 
 ```css
@@ -201,4 +202,4 @@ Both triggers carry `[menuPositioning]`, a partial `{ side, align, sideOffset, a
 
 ## Wrapping in a design system
 
-Subclassing the root is the supported pattern; the subclass must re-provide `FOR_MENU_CONTEXT` because Angular does not inherit a directive's `providers`, and every projected piece resolves its context through it. See [Wrapping non-form roots](../../../docs/wrapping-non-form-roots.md).
+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.

package/date-field/README.md

@@ -149,17 +149,17 @@ With a time-capable adapter, a `granularity` coarser than `'day'` appends time s
 
 ### `ForDateField`
 
-| Property      | Type                                             | Description                                                                                                                                |
-| ------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
-| `value`       | `model<D \| null>`                               | Two-way bindable entered date, or `null` while any segment is empty. The `FormValueControl` backing.<br>**Default:** `null`                |
-| `minDate`     | `input<D \| null>`                               | Minimum date (inclusive). A composed value below it is clamped up. Named `minDate` (see note below).<br>**Default:** `null`                |
-| `maxDate`     | `input<D \| null>`                               | Maximum date (inclusive). A composed value above it is clamped down.<br>**Default:** `null`                                                |
-| `granularity` | `input<'day' \| 'hour' \| 'minute' \| 'second'>` | Date-time precision. `'day'` is date-only; coarser-than-day appends time segments. See below.<br>**Default:** `'day'`                      |
-| `hourCycle`   | `input<12 \| 24 \| null>`                        | 12/24-hour cycle for the time segments. `null` → locale. 12-hour adds the AM/PM segment.<br>**Default:** `null`                            |
-| `locale`      | `input<string \| null>`                          | BCP 47 locale driving segment order, separators, and month name. `null` → runtime locale.<br>**Default:** `null`                           |
-| `placeholder` | `input<Partial<Record<SegmentType, string>>>`    | Per-segment placeholder while empty. Unspecified parts fall back to `dd` / `mm` / `yyyy` / `hh` / `mm` / `ss` / `--`.<br>**Default:** `{}` |
-| `ariaLabel`   | `input<string \| null>`                          | Accessible name for the group. Emits no `aria-label` while `null`.<br>**Default:** `null`                                                  |
-| `dir`         | `input<'ltr' \| 'rtl' \| null>`                  | Writing direction. `null` resolves the ambient direction; mirrors ArrowLeft / ArrowRight segment navigation.<br>**Default:** `null`        |
+| Property      | Type                                             | Description                                                                                                                                                                   |
+| ------------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `value`       | `model<D \| null>`                               | Two-way bindable entered date, or `null` while any segment is empty. The `FormValueControl` backing.<br>**Default:** `null`                                                   |
+| `minDate`     | `input<D \| null>`                               | Minimum date (inclusive). A composed value below it is clamped up. Named `minDate` (see note below).<br>**Default:** `null`                                                   |
+| `maxDate`     | `input<D \| null>`                               | Maximum date (inclusive). A composed value above it is clamped down.<br>**Default:** `null`                                                                                   |
+| `granularity` | `input<'day' \| 'hour' \| 'minute' \| 'second'>` | Date-time precision. `'day'` is date-only; coarser-than-day appends time segments. See below.<br>**Default:** `'day'`                                                         |
+| `hourCycle`   | `input<12 \| 24 \| null>`                        | 12/24-hour cycle for the time segments. `null` → locale. 12-hour adds the AM/PM segment.<br>**Default:** `null`                                                               |
+| `locale`      | `input<string \| null>`                          | BCP 47 locale driving segment order, separators, and month name. `null` → runtime locale.<br>**Default:** `null`                                                              |
+| `placeholder` | `input<Partial<Record<SegmentType, string>>>`    | Per-segment placeholder while empty. Unspecified parts fall back to the scope's `placeholder`, then to `dd` / `mm` / `yyyy` / `hh` / `mm` / `ss` / `--`.<br>**Default:** `{}` |
+| `ariaLabel`   | `input<string \| null>`                          | Accessible name for the group. Emits no `aria-label` while `null`.<br>**Default:** `null`                                                                                     |
+| `dir`         | `input<'ltr' \| 'rtl' \| null>`                  | Writing direction. `null` resolves the ambient direction; mirrors ArrowLeft / ArrowRight segment navigation.<br>**Default:** `null`                                           |
 
 Plus the shared `FormUiControl` members from `@angular/forms/signals`: `disabled`, `readonly`, `required`, `invalid`, `name`, `errors`, `touched` (bound automatically by `[formField]`).
 
@@ -207,18 +207,23 @@ On the AM/PM segment, `a` / `p` set the period and ArrowUp / ArrowDown toggle it
 ```ts
 import { provideForDateFieldDefaults } from 'forty-cdk/date-field';
 
-// app config or a component's providers — localize segment labels and the
-// empty-segment announcement for every nested [forDateField].
+// app config or a component's providers — localize segment labels, the
+// empty-segment announcement and the placeholders for every nested [forDateField].
 providers: [
   provideForDateFieldDefaults({
     emptySegmentText: 'Vacío',
     segmentLabels: { day: 'día', month: 'mes', year: 'año', dayPeriod: 'AM/PM' },
+    placeholder: { day: 'dd', month: 'mm', year: 'aaaa' },
   }),
 ];
 ```
 
 `segmentLabels` supplies each segment's default `aria-label`, keyed by part type. Unset keys keep the library default (the part name, and `'AM/PM'` for the `dayPeriod` segment), so overriding a single key never wipes the rest. A segment's own `[ariaLabel]` still wins over the scope default.
 
+`placeholder` is the text an empty segment shows, keyed the same way. A field's own `[placeholder]` wins for the parts it names and only those, and a part neither names keeps the letter-repeat default. `provideForDateRangeFieldDefaults` takes the same three keys for `[forDateRangeField]`.
+
+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.
+
 ## Range selection — `ForDateRangeField`
 
 For a date range use the dedicated `ForDateRangeField` root (selector `[forDateRangeField]`), shipped from this same entry point. It is the keyboard-first, form-capable counterpart to [DateRangePicker](../date-picker/README.md): two labelled `role="group"` endpoints (start / end) nested inside one outer `role="group"`. Each endpoint holds a row of spinbutton segments built on the same machinery as `ForDateField`. It implements `FormValueControl<DateRange<D> | null>`, the **same** contract as `ForDateRangePicker`, so the committed range auto-wires with `[formField]`. The value stays `null` until **both** endpoints are fully entered and ordered (`start <= end`).
@@ -271,7 +276,7 @@ readonly booking = form(this.model);
 | `granularity` | `input<'day' \| 'hour' \| 'minute' \| 'second'>` | Date-time precision shared by both endpoints. `'day'` is date-only; coarser-than-day appends time segments.<br>**Default:** `'day'`               |
 | `hourCycle`   | `input<12 \| 24 \| null>`                        | 12/24-hour cycle for the time segments. `null` → locale. 12-hour adds the AM/PM segment.<br>**Default:** `null`                                   |
 | `locale`      | `input<string \| null>`                          | BCP 47 locale driving segment order, separators, and month name. `null` → runtime locale.<br>**Default:** `null`                                  |
-| `placeholder` | `input<Partial<Record<SegmentType, string>>>`    | Per-segment placeholder while empty, applied to both endpoints.<br>**Default:** `{}`                                                              |
+| `placeholder` | `input<Partial<Record<SegmentType, string>>>`    | Per-segment placeholder while empty, applied to both endpoints. Unspecified parts fall back to the scope's `placeholder`.<br>**Default:** `{}`    |
 | `ariaLabel`   | `input<string \| null>`                          | Accessible name for the whole range field group. Emits no `aria-label` while `null`.<br>**Default:** `null`                                       |
 | `dir`         | `input<'ltr' \| 'rtl' \| null>`                  | Writing direction. `null` resolves the ambient direction; mirrors ArrowLeft / ArrowRight segment navigation.<br>**Default:** `null`               |
 
@@ -323,7 +328,7 @@ Composes the [WAI-ARIA Spinbutton pattern](https://www.w3.org/WAI/ARIA/apg/patte
 
 The library is styleless, so style the boolean `data-*` hooks yourself: `[data-highlighted]` (the focused/roving segment), `[data-placeholder]` (empty), `[data-disabled]` and `[data-readonly]` on the segments, and `[data-empty]` / `[data-disabled]` / `[data-readonly]` on the root group.
 
-forty-cdk ships no styles. Add your own class to each piece. The for\* selectors are the behavior API, not a styling contract (see [Styling forty-cdk](../../../docs/styling.md)). Key your CSS off the reflected data-\* attributes listed under [Data attributes](#data-attributes).
+forty-cdk ships no styles: put your own class on each piece and key your CSS off the `data-*` attributes listed under [Data attributes](#data-attributes), not off the `for*` selectors ([Styling forty-cdk](../../../docs/styling.md) explains why).
 
 ```css
 .date-field-segment[data-placeholder] {

package/date-picker/README.md

@@ -288,6 +288,8 @@ Set `granularity` to `'hour'`, `'minute'`, or `'second'` to turn the picker into
 
 Bind the calendar **and** the time field **one-way** to `picker.value()` (not `[(value)]`). The picker is the single source of truth: when one-way bound to a timed value the calendar preserves the time-of-day on its own selection, and the picker re-grafts the previously entered time as a defensive fallback for the case where the calendar value was null or midnight (reading its own value, which the one-way children never clobber); a time-field edit emits a full date-time the picker mirrors in. A date-time picker never closes on a calendar selection, so the user can go on to set the time.
 
+The content is a field boundary. Inside a [`[forField]`](../field/README.md#how-the-control-connects) the time field does not register with the field, which keeps reflecting the picker (its label target, `invalid` state and errors) while the panel is open.
+
 ```html
 <div
   forDatePicker
@@ -403,7 +405,7 @@ Implements the [WAI-ARIA Date Picker Dialog pattern](https://www.w3.org/WAI/ARIA
 
 ## Styling
 
-forty-cdk ships no styles. Add your own class to each piece. The `for*` selectors are the behavior API, not a styling contract (see [Styling forty-cdk](../../../docs/styling.md)). Key your CSS off the reflected `data-*` attributes listed under [Data attributes](#data-attributes).
+forty-cdk ships no styles: put your own class on each piece and key your CSS off the `data-*` attributes listed under [Data attributes](#data-attributes), not off the `for*` selectors ([Styling forty-cdk](../../../docs/styling.md) explains why).
 
 > `[forDatePickerContent]` is portaled to `document.body`, so it lives outside your component's view-encapsulated styles. Style it with **global CSS** (or a class you pass through) rather than component-scoped rules. See [Styling floating content](../../../docs/styling-floating-content.md). In non-modal (anchored) mode the surface also exposes the shared positioner custom properties (`--for-floating-anchor-width` / `--for-floating-anchor-height`, `--for-floating-available-width` / `--for-floating-available-height`, `--for-floating-content-transform-origin`); that same guide tabulates the full set.
 

package/dialog/README.md

@@ -168,9 +168,10 @@ Open a component imperatively and await its result. The manager mounts it under
 | `focusOutside`       | `OutputEmitterRef<VetoableNativeEvent<FocusEvent>>`                 | Output. Focus moves outside the dialog.<br>**Default:** —                                                                                                                                                                                                         |
 | `interactOutside`    | `OutputEmitterRef<VetoableNativeEvent<PointerEvent \| FocusEvent>>` | Output. Composite: fires alongside both of the above (and shares their veto state).<br>**Default:** —                                                                                                                                                             |
 
-| Data attribute | Values                                                                        |
-| -------------- | ----------------------------------------------------------------------------- |
-| `data-state`   | `open` (always: the host is only mounted while open, so it is never `closed`) |
+| Data attribute | Values                                                                                                                  |
+| -------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `data-state`   | `open` (always: the host is only mounted while open, so it is never `closed`)                                           |
+| `data-depth`   | `0` for the first mounted dialog, one above the deepest dialog still mounted otherwise. Fixed for the dialog's lifetime |
 
 ### Inputs — focus callbacks
 
@@ -194,6 +195,7 @@ The auto-focus pair is bound as **function references** (input callbacks), not a
 | -------------------------- | ---------------------------------------------------------------------------------------- |
 | `data-state`               | `open` (always, since it is mounted alongside the dialog)                                |
 | `data-for-dialog-backdrop` | present (stable marker; portaled alongside the dialog, so use it to select the backdrop) |
+| `data-depth`               | its dialog's `data-depth`                                                                |
 
 ### `ForDialogClose`
 
@@ -201,6 +203,20 @@ The auto-focus pair is bound as **function references** (input callbacks), not a
 | -------------- | --------------------------------------------------------- |
 | `data-state`   | `open` (always, since it is mounted alongside the dialog) |
 
+### `ForDialogInitialFocus`
+
+`[forDialogInitialFocus]` marks the element that receives focus when the enclosing dialog opens, in place of the one `initialFocus` picks. It takes no inputs, and it works inside a component opened with `ForDialogManager.open()` as well, since the marker lives in the content rather than in the caller. When the marked element is missing, disabled or hidden at mount, focus falls back to `initialFocus`; a vetoed `autoFocusOnOpen` still skips the move. Mark one element per dialog: a second marker warns in dev mode and only the newest is used.
+
+```html
+<div forDialog (dismiss)="open.set(false)">
+  <h2 forDialogTitle>Delete view</h2>
+  <button forDialogClose aria-label="Close">×</button>
+  <p>This cannot be undone.</p>
+  <button forDialogClose forDialogInitialFocus>Cancel</button>
+  <button (click)="deleteView()">Delete</button>
+</div>
+```
+
 ## Programmatic API
 
 ```ts
@@ -284,12 +300,12 @@ this.dialogs.open(ConfirmDialog, {
 
 Set them once for a scope with `provideForDialogDefaults({ animateEnter, animateLeave })`; a per-`open()` value always wins over the scope default.
 
-| Symbol                  | Description                                                                                                                                                   |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `ForDialogManager`      | Injectable. `open(component, config?)` returns a `ForDialogRef<R>`.                                                                                           |
-| `ForDialogRef<R>`       | `close(result?)`, `closed: Promise<{ reason: ForDialogCloseReason; result: R \| undefined }>`, `result: Signal<R \| undefined>`, `isClosed: Signal<boolean>`. |
-| `FOR_DIALOG_DATA`       | Token for the `data` payload. Inject in the opened component.                                                                                                 |
-| `injectDialogData<T>()` | Typed accessor for `FOR_DIALOG_DATA`. Returns `T \| null` (`null` when `open()` got no `data`).                                                               |
+| Symbol                  | Description                                                                                                                                                                                                                                                                                                                                                        |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `ForDialogManager`      | Injectable. `open(component, config?)` returns a `ForDialogRef<R>`. `closeAll(result?)` closes every open dialog, topmost first, with reason `'programmatic'`; exit animations still play and focus ends where the bottom dialog returns it. `openCount` is a `Signal<number>` of the dialogs still open, counting a closed one until its exit animation finishes. |
+| `ForDialogRef<R>`       | `close(result?)`, `closed: Promise<{ reason: ForDialogCloseReason; result: R \| undefined }>`, `result: Signal<R \| undefined>`, `isClosed: Signal<boolean>`.                                                                                                                                                                                                      |
+| `FOR_DIALOG_DATA`       | Token for the `data` payload. Inject in the opened component.                                                                                                                                                                                                                                                                                                      |
+| `injectDialogData<T>()` | Typed accessor for `FOR_DIALOG_DATA`. Returns `T \| null` (`null` when `open()` got no `data`).                                                                                                                                                                                                                                                                    |
 
 ### `ForDialogOpenConfig`
 
@@ -326,14 +342,15 @@ The four dismiss callbacks mirror the declarative `(escapeKeyDown)` / `(pointerD
 
 Implements the [WAI-ARIA Modal Dialog pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/).
 
-- Always provide an accessible name: render a `[forDialogTitle]` (sets `aria-labelledby`) or pass `ariaLabel`.
+- Always provide an accessible name: render a `[forDialogTitle]` (sets `aria-labelledby`) or pass `ariaLabel`. A dialog that mounts with neither logs a dev-mode warning (`FORCDK-CORE-011`) after its first render, because a WCAG-tagged audit does not report the missing name.
+- Initial focus follows the APG guidance by default (the first focusable element). When the step is hard to undo, or focusing the first control would scroll the start of the content out of view, mark the least destructive action or a static heading carrying `tabindex="-1"` with [`[forDialogInitialFocus]`](#fordialoginitialfocus).
 - `[forDialogDescription]` is optional. Use it for non-title supporting copy (the question of a confirm, the rationale of an alert).
 - `alert: true` interrupts assistive tech aggressively, so use it only for genuine alerts (lost connection, unsaved changes warning), not for general confirms.
 - Don't put interactive overlays (popovers, menus) outside the focus trap while a modal dialog is open, because they won't be reachable. For a non-modal floating surface anchored to a trigger, use `[forPopover]` instead.
 
 ## Styling
 
-forty-cdk ships no styles. Add your own class to each piece. The `for*` selectors are the behavior API, not a styling contract (see [Styling forty-cdk](../../../docs/styling.md)). Key your CSS off the reflected `data-*` attributes listed per piece in the [API](#api) section.
+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).
 
 > **This dialog portals to `document.body`.** CSS scoped to ancestors of `[forDialog]` (or `[forDialogBackdrop]`) will not apply once the surface is moved to the body. Style it with **global CSS** or a class. Declaratively you write the surface yourself, so add the class directly (`<div forDialog class="my-dialog">`); for programmatically opened instances pass `class` / `classList` on the `ForDialogManager.open()` config. They land on the same `[forDialog]` host that carries `data-state` / `role` / `aria-modal`, merged and never clobbering them.
 
@@ -355,6 +372,24 @@ forty-cdk ships no styles. Add your own class to each piece. The `for*` selector
 }
 ```
 
+**Stacked dialogs.** Each surface and its backdrop publish their stacking position as `data-depth` and `--for-dialog-depth` (`0` for the first dialog, `1` above it, …), shared by declarative and managed dialogs. One rule then covers every level, with each backdrop one step below its own dialog and above every dialog underneath it:
+
+```css
+.my-dialog {
+  z-index: calc(1010 + var(--for-dialog-depth) * 10);
+}
+
+.my-backdrop {
+  z-index: calc(1009 + var(--for-dialog-depth) * 10);
+}
+```
+
+### CSS custom properties
+
+| Property             | Meaning                                                                                                                                                                                                  |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--for-dialog-depth` | Written on `[forDialog]` and `[forDialogBackdrop]`. The dialog's stacking position as a unitless integer, `0` for the first mounted dialog. Fixed for the dialog's lifetime, so a level is never reused. |
+
 ## Behavior notes
 
 - **The `(dismiss)` contract: the consumer owns unmount.** `(dismiss)` reports the dialog's **intent** to be unmounted; it does not flip the consumer's signal. The consumer must call `open.set(false)` (or equivalent) inside the handler. If the handler is omitted or does not update the signal, Escape, backdrop-click, and outside-pointer-down all emit `(dismiss)` but the dialog stays mounted.
@@ -471,4 +506,4 @@ Pass `[container]` to portal the dialog surface into a specific element instead
 
 ## Wrapping in a design system
 
-Subclassing the root is the supported pattern; the subclass must re-provide `FOR_DIALOG_CONTEXT` because Angular does not inherit a directive's `providers`, and every projected piece resolves its context through it. See [Wrapping non-form roots](../../../docs/wrapping-non-form-roots.md).
+Subclass the root and re-provide `FOR_DIALOG_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.

package/disclosure/README.md

@@ -120,7 +120,7 @@ Implements the [WAI-ARIA Disclosure pattern](https://www.w3.org/WAI/ARIA/apg/pat
 
 ## Styling
 
-forty-cdk ships no styles. Add your own class to each piece. The `for*` selectors are the behavior API, not a styling contract (see [Styling forty-cdk](../../../docs/styling.md)). Key your CSS off the reflected `data-*` attributes listed per piece in the [API](#api) section.
+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).
 
 ```css
 .dis-trigger .chevron {
@@ -133,4 +133,4 @@ forty-cdk ships no styles. Add your own class to each piece. The `for*` selector
 
 ## Wrapping in a design system
 
-Subclassing the root is the supported pattern; the subclass must re-provide `FOR_DISCLOSURE_CONTEXT` because Angular does not inherit a directive's `providers`, and every projected piece resolves its context through it. See [Wrapping non-form roots](../../../docs/wrapping-non-form-roots.md).
+Subclass the root and re-provide `FOR_DISCLOSURE_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.

package/drag-drop/README.md

@@ -178,6 +178,23 @@ Arrow direction follows the list's `orientation` and respects RTL via `dir`. In
 
 Keyboard lifting, stepping, dropping, and cancellation are announced via ARIA live regions. Override the default messages at any injector scope via `provideForDragDropDefaults` (see Announcement customisation below). Free-drag is pointer-only. There is no WAI-ARIA pattern for "reposition an element", so `[forFreeDrag]` owns no role or ARIA state; the consumer is responsible for keeping the moved element fully usable at its default position.
 
+### Role description
+
+Each `[forDraggable]` that can be lifted carries `aria-roledescription`, `"sortable"` by default.
+An item that cannot be lifted, through `[dragDisabled]` or a disabled `[forDropList]`, emits none.
+A screen reader that honors the attribute speaks it in place of the element's role name, so
+change it, or turn it off with an empty string, through `itemRoleDescription` at any injector
+scope:
+
+<!-- snippet: fragment -->
+
+```ts
+providers: [provideForDragDropDefaults({ itemRoleDescription: 'movable item' })];
+```
+
+`[forTableColumnReorder]` turns it off for its header cells, which keep the `columnheader` role
+name and leave "sortable" to `aria-sort`.
+
 ### Focus after a keyboard drop
 
 Applying the move in `(dragDrop)` destroys or re-inserts the lifted element, which would otherwise
@@ -244,6 +261,29 @@ unaffected.
 </li>
 ```
 
+### Nested controls
+
+A control inside a draggable item keeps its press from starting a drag by calling
+`preventDefault()` on its own `pointerdown`. The item stands down on the first pointer move, so
+the press stays with the control; lifting with the keyboard is unaffected.
+
+```html
+<li forDraggable [dragData]="item">
+  {{ item.label }}
+  <button type="button" (pointerdown)="$event.preventDefault()" (click)="remove(item)">
+    Remove
+  </button>
+</li>
+```
+
+- The check lives in the pointer session every drag surface shares, so it holds for
+  `[forDraggable]`, `[forFreeDrag]`, `[forListboxReorder]`, `[forTableRowReorder]`,
+  `[forTreeNodeDrag]` and `[forVirtualReorder]` alike.
+- A nested control that runs a drag of its own still starts it: the item around it is what
+  stands down. That is how a `[forTableColumnResizer]` resizes inside a reorderable header cell.
+- A canceled `pointerdown` suppresses the compatibility mouse events of that press (`mousedown`,
+  `mouseup`), so the control must not rely on them. `click` still fires.
+
 ### Custom preview & placeholder
 
 Place `<ng-template forDragPreview>` and/or `<ng-template forDragPlaceholder>` as direct
@@ -591,4 +631,4 @@ append gap counts).
 
 ## Wrapping in a design system
 
-Subclassing the root is the supported pattern; the subclass must re-provide `FOR_DROP_LIST_CONTEXT` because Angular does not inherit a directive's `providers`, and every projected piece resolves its context through it. See [Wrapping non-form roots](../../../docs/wrapping-non-form-roots.md).
+Subclass the root and re-provide `FOR_DROP_LIST_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.