forty-cdk 0.40.0 → 0.41.0

package/README.md

@@ -54,7 +54,7 @@ Two packages are regular dependencies, installed automatically and never declare
 | [`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 seven 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
 

package/breadcrumbs/README.md

@@ -84,7 +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.
+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
 

package/breakpoints/README.md

@@ -38,12 +38,14 @@ Resize the browser window and watch the matched breakpoint change: the breakpoin
 ```ts
 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">
@@ -58,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>
         }

package/calendar/README.md

@@ -393,7 +393,7 @@ 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>`.
 
@@ -582,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.

package/dialog/README.md

@@ -221,7 +221,19 @@ The auto-focus pair is bound as **function references** (input callbacks), not a
 
 ```ts
 import { Component, inject } from '@angular/core';
-import { ForDialogManager, ForDialogRef, injectDialogData } from 'forty-cdk/dialog';
+import {
+  FOR_DIALOG_CONTRACT,
+  type ForDialogContract,
+  ForDialogManager,
+  ForDialogRef,
+  injectDialogData,
+} from 'forty-cdk/dialog';
+
+interface ConfirmData {
+  message: string;
+}
+
+type ConfirmResult = 'confirm' | 'cancel';
 
 @Component({
   template: `
@@ -231,8 +243,9 @@ import { ForDialogManager, ForDialogRef, injectDialogData } from 'forty-cdk/dial
   `,
 })
 class ConfirmDialog {
-  readonly data = injectDialogData<{ message: string }>();
-  readonly ref = inject(ForDialogRef) as ForDialogRef<'confirm' | 'cancel'>;
+  declare readonly [FOR_DIALOG_CONTRACT]: ForDialogContract<ConfirmData, ConfirmResult>;
+  readonly data = injectDialogData<ConfirmDialog>();
+  readonly ref = inject(ForDialogRef<ConfirmResult>);
 }
 
 @Component({
@@ -243,10 +256,7 @@ export class DemoHost {
   readonly dialogs = inject(ForDialogManager);
 
   async askToDelete() {
-    const ref = this.dialogs.open<ConfirmDialog, 'confirm' | 'cancel', { message: string }>(
-      ConfirmDialog,
-      { data: { message: 'Are you sure?' } },
-    );
+    const ref = this.dialogs.open(ConfirmDialog, { data: { message: 'Are you sure?' } });
     const { result } = await ref.closed; // result: 'confirm' | 'cancel' | undefined
     if (result === 'confirm') {
       /* ... */
@@ -255,7 +265,9 @@ export class DemoHost {
 }
 ```
 
-`injectDialogData<T>()` is typed `T | null`: the manager provides `null` when `open()` is called without `data`, so guard (`data?.message`) before dereferencing the payload.
+**Typing the payload and the result.** The `[FOR_DIALOG_CONTRACT]` member states, once, the data a dialog component reads and the result it closes with. Declare it with `declare` and no initializer, and keep it public. `open()` then infers both from the component: a `data` of any other shape fails to compile, and the returned ref is a `ForDialogRef<ConfirmResult>`. `injectDialogData<ConfirmDialog>()` reads the payload at the type the contract names, so the component and every caller share one definition. A component without the member keeps an unchecked `data` and an `unknown` result, and `injectDialogData<T>()` with a plain type still types the payload as `T`. Explicit type arguments (`open<ConfirmDialog, ConfirmResult>`) override what the contract supplies.
+
+`injectDialogData()` returns `null` too: the manager provides `null` when `open()` is called without `data`, so guard (`data?.message`) before dereferencing the payload.
 
 **Styling the programmatic overlay root.** Declaratively you write the surface yourself (`<div forDialog class="my-dialog">`), so the class lands on the same element that carries `data-state` / `role`. The manager creates that host for you and it is class-less, so pass `class` / `classList` to style it.
 
@@ -320,7 +332,8 @@ class ScopedHost {
 | `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`).                                                                                                                                                                                                                                                                    |
+| `injectDialogData<T>()` | Typed accessor for `FOR_DIALOG_DATA`. Returns `T \| null` (`null` when `open()` got no `data`), or the data type the contract names when `T` is a component declaring `FOR_DIALOG_CONTRACT`.                                                                                                                                                                       |
+| `FOR_DIALOG_CONTRACT`   | Key of the member a dialog component declares as `ForDialogContract<D, R>` so `open()` checks `data` against `D` and returns a `ForDialogRef<R>`. `ForDialogDataOf<C>` / `ForDialogResultOf<C>` read the two types off a component.                                                                                                                                |
 
 ### `ForDialogOpenConfig`
 

package/drawer/README.md

@@ -100,9 +100,17 @@ import {
   ForDrawerManager,
   ForDrawerRef,
   ForDrawerTitle,
+  FOR_DRAWER_CONTRACT,
+  type ForDrawerContract,
   injectDrawerData,
 } from 'forty-cdk/drawer';
 
+interface ConfirmData {
+  message: string;
+}
+
+type ConfirmResult = 'confirm' | 'cancel';
+
 @Component({
   imports: [
     ForDrawerBackdrop,
@@ -126,8 +134,9 @@ import {
   `,
 })
 class ConfirmDrawer {
-  readonly data = injectDrawerData<{ message: string }>();
-  readonly ref = inject(ForDrawerRef) as ForDrawerRef<'confirm' | 'cancel'>;
+  declare readonly [FOR_DRAWER_CONTRACT]: ForDrawerContract<ConfirmData, ConfirmResult>;
+  readonly data = injectDrawerData<ConfirmDrawer>();
+  readonly ref = inject(ForDrawerRef<ConfirmResult>);
 }
 
 @Component({
@@ -138,7 +147,7 @@ class DemoHost {
   readonly #drawers = inject(ForDrawerManager);
 
   async askToDelete(): Promise<void> {
-    const ref = this.#drawers.open<ConfirmDrawer, 'confirm' | 'cancel'>(ConfirmDrawer, {
+    const ref = this.#drawers.open(ConfirmDrawer, {
       data: { message: 'This action cannot be undone.' },
       side: 'bottom',
       snapPoints: ['148px', 1],
@@ -151,7 +160,7 @@ class DemoHost {
 }
 ```
 
-`injectDrawerData<T>()` is typed `T | null`: the manager provides `null` when `open()` is called without `data`, so guard (`data?.message`) before dereferencing the payload. `await ref.closed` resolves `{ reason, result }`, whose `reason` (a `ForDrawerCloseReason`) tells apart an imperative `close()` (`'programmatic'`) from Escape / backdrop / outside / swipe / close-button dismissals.
+The `[FOR_DRAWER_CONTRACT]` member states, once, the data a drawer component reads and the result it closes with: `open()` infers both from the component, so a `data` of any other shape fails to compile and the ref is a `ForDrawerRef<ConfirmResult>`, and `injectDrawerData<ConfirmDrawer>()` reads the payload at that type. Declare it with `declare`, no initializer, and keep it public. Without the member `data` is unchecked, the result is `unknown`, and `injectDrawerData<T>()` with a plain type still types the payload as `T`; explicit type arguments override the contract. `injectDrawerData()` returns `null` too, because the manager provides `null` when `open()` is called without `data`, so guard (`data?.message`) before dereferencing the payload. `await ref.closed` resolves `{ reason, result }`, whose `reason` (a `ForDrawerCloseReason`) tells apart an imperative `close()` (`'programmatic'`) from Escape / backdrop / outside / swipe / close-button dismissals.
 
 Drawers opened by the manager share the LIFO dismissible layer with declarative ones, so Escape closes the topmost drawer first whichever API opened it. Nesting is resolved from where a drawer is declared, not from the order drawers open in: a declarative `[forDrawer]` inside a programmatic drawer's component is its child (`data-depth="1"`, and the programmatic parent reflects `data-state-nested`), but a drawer the manager opens over a declarative one is a root, so it reflects `data-depth="0"` and its declarative neighbour gets no `data-state-nested`.
 
@@ -262,7 +271,7 @@ Declaratively the same recipe is the four vetoable outputs on `[forDrawer]`: `(i
 
 ## Examples
 
-Open the drawer, drag it by its edge and let go past the threshold. `data-state` drives the transition, and `data-dragging` is set for the gesture itself.
+Open the drawer, drag it by its edge and let go past the threshold. `animate.enter` / `animate.leave` drive the enter and exit, and `data-dragging` marks the gesture, so a release short of the threshold springs back through the surface's `translate` transition.
 
 ```ts
 import { ChangeDetectionStrategy, Component, computed, signal } from '@angular/core';
@@ -454,13 +463,13 @@ Pass them in **strictly increasing** order (closest-to-edge first); in dev mode
 <div
   forDrawer
   class="sheet"
-  [snapPoints]="['148px', '50%', 1]"
+  [snapPoints]="['25%', '50%', 1]"
   [(activeSnapPoint)]="snap"
   [fadeFromIndex]="1"
 ></div>
 ```
 
-The three snaps read peek → mid → full; `snap` is the current one, written on every release that changes the snap; the backdrop fades once the active snap reaches the second index.
+The three snaps read peek → mid → full; `snap` is the current one, written on every release that changes the snap; the backdrop fades once the active snap reaches the second index. All three are fractions of the sheet, so their order holds at any viewport height. A `'148px'` peek beside `'50%'` would only stay below the mid snap while the sheet is taller than 296px, so the `80vh` sheet below would throw `FORCDK-DRAWER-010` on a viewport shorter than 370px.
 
 The `model<>()` change emitter (`(activeSnapPointChange)`) fires on internal transitions (the mount-time default and every release that changes the snap), and stays silent on consumer writes through `[(activeSnapPoint)]`.
 
@@ -486,8 +495,8 @@ For a seamless release, transition **both** `translate` and your snap-position p
 .sheet[data-active-snap-point][data-dragging] {
   transition: none; /* the drag follows the pointer 1:1 */
 }
-.sheet[data-active-snap-point='148px'] {
-  bottom: calc(148px - 80vh);
+.sheet[data-active-snap-point='25%'] {
+  bottom: -60vh;
 }
 .sheet[data-active-snap-point='50%'] {
   bottom: -40vh;

package/fesm2022/forty-cdk-calendar.mjs

@@ -1,5 +1,5 @@
 import * as i0 from "@angular/core";
-import { Directive, ElementRef, InjectionToken, Injector, afterNextRender, booleanAttribute, computed, effect, inject, input, linkedSignal, model, numberAttribute, signal } from "@angular/core";
+import { DestroyRef, Directive, ElementRef, InjectionToken, Injector, afterNextRender, booleanAttribute, computed, effect, inject, input, linkedSignal, model, numberAttribute, signal } from "@angular/core";
 import { Collection, FOR_PICKER_SOURCE_HOST, IdGenerator, LiveAnnouncer, adoptHostId, assertInputBound, assertRootContext, clampToBounds, compareDateOf, hostAriaLabel, hostButtonType, hostLabelledBy, injectDateAdapter, injectTextDirection, isUnset, orphanContextError, registerHandle, unsetInput } from "forty-cdk/core";
 import { FOR_CALENDAR_DEFAULTS, FOR_CALENDAR_DEFAULTS as FOR_CALENDAR_DEFAULTS$1, provideForCalendarDefaults } from "forty-cdk/defaults";
 import { NativeDateAdapter, provideNativeDateAdapter } from "forty-cdk/date-adapter";
@@ -766,6 +766,14 @@ var ForCalendar = class ForCalendar {
 	}, ...ngDevMode ? [{ debugName: "visibleMonth" }] : /* istanbul ignore next */ []);
 	#headingId = signal(this.#idGen.next("for-calendar-heading"), ...ngDevMode ? [{ debugName: "#headingId" }] : /* istanbul ignore next */ []);
 	headingId = this.#headingId.asReadonly();
+	#headingCount = signal(0, ...ngDevMode ? [{ debugName: "#headingCount" }] : /* istanbul ignore next */ []);
+	hasHeading = computed(() => this.#headingCount() > 0, ...ngDevMode ? [{ debugName: "hasHeading" }] : /* istanbul ignore next */ []);
+	registerHeading() {
+		this.#headingCount.update((count) => count + 1);
+	}
+	unregisterHeading() {
+		this.#headingCount.update((count) => count - 1);
+	}
 	adoptHeadingId(el) {
 		adoptHostId(el, this.#headingId);
 	}
@@ -1251,7 +1259,7 @@ i0.ɵɵngDeclareClassMetadata({
 });
 var ForCalendarGrid = class ForCalendarGrid {
 	ctx = injectCalendarContext("ForCalendarGrid");
-	labelledBy = hostLabelledBy(() => this.ctx.headingId());
+	labelledBy = hostLabelledBy(() => this.ctx.hasHeading() ? this.ctx.headingId() : null);
 	weekDays = this.ctx.weekDays;
 	weeks = this.ctx.weeks;
 	static ɵfac = i0.ɵɵngDeclareFactory({
@@ -1471,6 +1479,8 @@ var ForCalendarHeading = class ForCalendarHeading {
 	label = this.ctx.viewTriggerLabel;
 	constructor() {
 		this.ctx.adoptHeadingId(inject(ElementRef).nativeElement);
+		this.ctx.registerHeading();
+		inject(DestroyRef).onDestroy(() => this.ctx.unregisterHeading());
 	}
 	static ɵfac = i0.ɵɵngDeclareFactory({
 		minVersion: "12.0.0",
@@ -1652,7 +1662,7 @@ i0.ɵɵngDeclareClassMetadata({
 });
 var ForCalendarMonthGrid = class ForCalendarMonthGrid {
 	ctx = injectCalendarContext("ForCalendarMonthGrid");
-	labelledBy = hostLabelledBy(() => this.ctx.headingId());
+	labelledBy = hostLabelledBy(() => this.ctx.hasHeading() ? this.ctx.headingId() : null);
 	rows = this.ctx.monthRows;
 	static ɵfac = i0.ɵɵngDeclareFactory({
 		minVersion: "12.0.0",
@@ -1804,7 +1814,7 @@ i0.ɵɵngDeclareClassMetadata({
 });
 var ForCalendarYearGrid = class ForCalendarYearGrid {
 	ctx = injectCalendarContext("ForCalendarYearGrid");
-	labelledBy = hostLabelledBy(() => this.ctx.headingId());
+	labelledBy = hostLabelledBy(() => this.ctx.hasHeading() ? this.ctx.headingId() : null);
 	rows = this.ctx.yearRows;
 	static ɵfac = i0.ɵɵngDeclareFactory({
 		minVersion: "12.0.0",