forty-cdk 0.24.0 → 0.25.0

package/accordion/README.md

@@ -1,3 +1,10 @@
+---
+title: Accordion
+group: primitives
+archetype: [composable-ui]
+apgUrl: https://www.w3.org/WAI/ARIA/apg/patterns/accordion/
+---
+
 # Accordion
 
 A stack of collapsible sections, optionally allowing multiple panels open at once.

package/aspect-ratio/README.md

@@ -1,3 +1,9 @@
+---
+title: Aspect Ratio
+group: primitives
+archetype: [composable-ui]
+---
+
 # AspectRatio
 
 A container that keeps its content at a fixed width-to-height ratio.

package/avatar/README.md

@@ -1,3 +1,9 @@
+---
+title: Avatar
+group: primitives
+archetype: [composable-ui]
+---
+
 # Avatar
 
 A user image with a graceful fallback across its loading lifecycle.

package/breadcrumbs/README.md

@@ -1,3 +1,10 @@
+---
+title: Breadcrumbs
+group: primitives
+archetype: [composable-ui]
+apgUrl: https://www.w3.org/WAI/ARIA/apg/patterns/breadcrumb/
+---
+
 # Breadcrumbs
 
 A labelled navigation landmark for a breadcrumb trail: links with aria-current='page' on the current page and decorative separators hidden from assistive technology.

package/breakpoints/README.md

@@ -1,3 +1,9 @@
+---
+title: Breakpoints
+group: utilities
+archetype: [headless-utility]
+---
+
 # Breakpoints
 
 A signal-first, zoneless, SSR-safe viewport breakpoint observer (injectBreakpoints). Configure the breakpoint map once via provideForBreakpointsDefaults — or use the Tailwind scale by default — then read up / down / between / only / active or any arbitrary media query, each as a live Signal<boolean>.

package/button/README.md

@@ -1,6 +1,13 @@
+---
+title: Button
+group: primitives
+archetype: [composable-ui]
+apgUrl: https://www.w3.org/WAI/ARIA/apg/patterns/button/
+---
+
 # ForButton
 
-Turns any element — a native <button> or a custom host like <div> / <span> — into an accessible button with keyboard activation. Disabled stays focusable (aria-disabled, never the native attribute) and pressed / hovered / focus-visible are reflected as data-\* hooks.
+Turns any element — a native `<button>` or a custom host like `<div>` / `<span>` — into an accessible button with keyboard activation. Disabled stays focusable (aria-disabled, never the native attribute) and pressed / hovered / focus-visible are reflected as data-\* hooks.
 
 A single `[forButton]` directive does all of this. On a native `<button>` host the platform owns Enter/Space activation and `type` handling; on any non-button host the directive adds `role="button"`, `tabindex="0"`, and keyboard activation so the contract matches.
 

package/calendar/README.md

@@ -1,3 +1,10 @@
+---
+title: Calendar
+group: primitives
+archetype: [composable-ui, form-control]
+apgUrl: https://www.w3.org/WAI/ARIA/apg/patterns/grid/
+---
+
 # Calendar
 
 A single-date calendar grid implementing the APG Grid pattern over a pluggable date adapter: roving-tabindex day navigation, month / year paging, and min / max / per-date availability.
@@ -26,6 +33,8 @@ bootstrapApplication(App, {
 
 `@internationalized/date` is a widely-used immutable date primitive; it works in every browser today with no polyfill, and its reference-equality-on-mutation makes it signal-friendly.
 
+→ **[Date adapters](../../../docs/date-adapters.md)** — picking one, the optional peer dependency, and writing your own.
+
 **Calendar system (Gregorian).** The adapter seam abstracts the date _library_ and locale-aware _formatting_, not the calendar _system_'s month structure. Both `@internationalized/date` adapters build Gregorian dates, so the grid stays Gregorian regardless of the runtime locale, and the grid, the month picker and the date field all assume a Gregorian-structured year — exactly twelve months, `month` **1-12**, the year ending at month 12. Adapters over calendars with a different month structure (e.g. a 13-month year) are not supported. The optional `compareDate` hook overrides day-only _ordering_ only — it does not make the grid non-Gregorian.
 
 ## Anatomy
@@ -401,7 +410,7 @@ Auto-disabled when the entire previous / next page would be outside `[min, max]`
 | `[forCalendarYearCell]`  | `data-highlighted` | present \| absent                |
 | `[forCalendarYearCell]`  | `data-disabled`    | present \| absent                |
 
-## Scope defaults
+## Scoped defaults
 
 ```ts
 import { provideForCalendarDefaults } from 'forty-cdk/calendar';

package/carousel/README.md

@@ -1,3 +1,10 @@
+---
+title: Carousel
+group: primitives
+archetype: [composable-ui]
+apgUrl: https://www.w3.org/WAI/ARIA/apg/patterns/carousel/
+---
+
 # ForCarousel
 
 A slideshow of content panels with previous / next controls, an indicator group, optional looping and multi-slide views, and an accessible autoplay mode with a pause control.

package/checkbox/README.md

@@ -1,3 +1,10 @@
+---
+title: Checkbox
+group: primitives
+archetype: [form-control]
+apgUrl: https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/
+---
+
 # Checkbox
 
 A checkbox supporting the three states checked, unchecked and indeterminate.

package/combobox/README.md

@@ -1,3 +1,10 @@
+---
+title: Combobox
+group: primitives
+archetype: [overlay, form-control]
+apgUrl: https://www.w3.org/WAI/ARIA/apg/patterns/combobox/
+---
+
 # Combobox
 
 An editable input paired with a filterable listbox popup, supporting single or multi selection with chips.
@@ -259,7 +266,7 @@ An action:
 
 Use `[forComboboxAction]` for a pinned side-effect. For an entry that _does_
 select (an "Add new" row that adds an item and commits it to `value`), use a
-plain `[forComboboxOption]` — see [Static options alongside the `@for`](#static-options-alongside-the-for).
+plain `[forComboboxOption]` — see the static options under [Examples](#examples).
 
 ### Focus & keyboard (model A)
 

package/context-menu/README.md

@@ -1,3 +1,10 @@
+---
+title: Context Menu
+group: primitives
+archetype: [overlay]
+apgUrl: https://www.w3.org/WAI/ARIA/apg/patterns/menu/
+---
+
 # ContextMenu
 
 A menu opened by right-click or long-press, anchored to the pointer position.
@@ -140,7 +147,7 @@ Both triggers carry `[menuPositioning]`, a partial `{ side, align, sideOffset, a
 
 Same vetoable dismiss API as DropdownMenu. Call `preventDefault()` on the emitted veto to suppress the directive's default action; the original DOM event, when present, is on `.event`.
 
-`(autoFocusOnOpen)` / `(autoFocusOnClose)` are output-shape because ContextMenu always routes close transitions through `[(open)]` (via the implicit `openChange` emitter). See [Conventions › Auto-focus hook shape](../../../.claude/rules/conventions.md#auto-focus-hook-shape) for why Dialog uses callback-shape inputs instead.
+`(autoFocusOnOpen)` / `(autoFocusOnClose)` are output-shape because ContextMenu always routes close transitions through `[(open)]` (via the implicit `openChange` emitter). Dialog and Drawer take callback-shape inputs for the same pair instead: either can be closed by a direct `open.set(false)` that bypasses the `(dismiss)` output entirely, so their close hook has to be a stored function reference that still runs during teardown.
 
 ### Data attributes
 

package/date-field/README.md

@@ -1,3 +1,10 @@
+---
+title: Date Field
+group: primitives
+archetype: [form-control]
+apgUrl: https://www.w3.org/WAI/ARIA/apg/patterns/spinbutton/
+---
+
 # DateField
 
 A segmented date (and optional time) input over a pluggable date adapter — each part a spinbutton with keyboard stepping, locale-driven segment order and min / max clamping.
@@ -171,7 +178,7 @@ Set `granularity` to `'hour'`, `'minute'`, or `'second'` (`granularity > 'day'`)
 
 On the AM/PM segment, `a` / `p` set the period and ArrowUp / ArrowDown toggle it; the period is derived from the entered hour, so clearing it is a no-op (clear or step the hour instead). The value stays `null` until every visible segment — date **and** time — is filled.
 
-## Scope defaults
+## Scoped defaults
 
 ```ts
 import { provideForDateFieldDefaults } from 'forty-cdk/date-field';
@@ -256,7 +263,7 @@ The two endpoints are typed independently, so order is not guaranteed by constru
 
 Each endpoint is its own tab stop, so `Tab` moves start group → end group → next control; arrows move between segments **within** an endpoint. Every other key behaves as in the [Keyboard](#keyboard) table below. Roving tabindex is per endpoint, and `aria-invalid="true"` is reflected on the root when the form marks it invalid **or** when two complete endpoints are out of order; everything else matches the [Accessibility](#accessibility) notes below.
 
-### Range scope defaults
+### Range scoped defaults
 
 `provideForDateRangeFieldDefaults` mirrors `provideForDateFieldDefaults` and adds `startLabel` / `endLabel` for the two endpoint group `aria-label`s (`'Start date'` / `'End date'` by default). Both wrapper patterns work via `FOR_DATE_RANGE_FIELD_HOST_DIRECTIVE_INPUTS` / `FOR_DATE_RANGE_FIELD_HOST_DIRECTIVE_OUTPUTS` — see [Wrapping form primitives](../../../docs/wrapping-form-primitives.md).
 

package/date-picker/README.md

@@ -1,3 +1,10 @@
+---
+title: Date Picker
+group: primitives
+archetype: [overlay, form-control]
+apgUrl: https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/examples/datepicker-dialog/
+---
+
 # DatePicker
 
 A trigger that opens a floating calendar to pick a date, composing ForCalendar inside a dismissible popover with min / max bounds and per-date availability.

package/dialog/README.md

@@ -1,3 +1,10 @@
+---
+title: Dialog
+group: primitives
+archetype: [overlay]
+apgUrl: https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/
+---
+
 # Dialog
 
 A modal window overlaid on the page, with a focus trap, scroll lock and Escape / dismiss handling. Also openable imperatively through ForDialogManager.
@@ -249,7 +256,7 @@ Keep `dismissible: true` (the default) so Escape still closes, and veto only the
 
 ### Inputs — focus callbacks
 
-The auto-focus pair is bound as **function references** (input callbacks), not as event listeners. Each callback receives a `VetoableEvent` whose `preventDefault()` suppresses the directive's default focus action. This shape mirrors `ForDialogManager`'s `config.autoFocusOn*` callbacks and guarantees the `autoFocusOnClose` callback fires reliably on every close path — including a direct `open.set(false)` that bypasses the `(dismiss)` output. See [Conventions › Auto-focus hook shape](../../../.claude/rules/conventions.md#auto-focus-hook-shape) for why the free-floating overlays (Dialog, Drawer) use callback-shape inputs while the trigger-anchored ones use output-shape.
+The auto-focus pair is bound as **function references** (input callbacks), not as event listeners. Each callback receives a `VetoableEvent` whose `preventDefault()` suppresses the directive's default focus action. This shape mirrors `ForDialogManager`'s `config.autoFocusOn*` callbacks and guarantees the `autoFocusOnClose` callback fires reliably on every close path — including a direct `open.set(false)` that bypasses the `(dismiss)` output. The trigger-anchored overlays (Popover, DropdownMenu, Select, …) expose the same pair as **outputs** instead, because every close transition there runs through their own `[(open)]` model, so no path can bypass the emitter.
 
 | Property           | Type                             | Description                                                                                                                                                                                                                                                          |
 | ------------------ | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

package/disclosure/README.md

@@ -1,3 +1,10 @@
+---
+title: Disclosure
+group: primitives
+archetype: [composable-ui]
+apgUrl: https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/
+---
+
 # Disclosure
 
 A single trigger that shows or hides a related region of content.

package/drag-drop/README.md

@@ -1,3 +1,9 @@
+---
+title: Drag & Drop
+group: utilities
+archetype: [headless-utility]
+---
+
 # Drag & Drop
 
 Headless, accessible drag-and-drop for sortable lists and cross-list transfers, driven by both keyboard and pointer. Ships drag handles, custom preview / placeholder templates, live-sort, FLIP reorder animations, auto-scroll, and boundary / axis-lock constraints.
@@ -369,8 +375,9 @@ A custom integration that cannot use either companion must supply the same three
 mechanisms itself: map window-relative to absolute indices with the reusable
 `translateWindowReorder` helper (`forty-cdk/core`), keep the lifted row mounted
 for the duration of the drag, and step the keyboard target over the true total
-count. See [`docs/drag-in-virtualized-list-spike.md`](../../../docs/drag-in-virtualized-list-spike.md)
-for the full analysis.
+count. Miss any one of the three and the failure is silent — an index that
+addresses the wrong row, a lifted row recycled mid-drag, or a keyboard move that
+stops at the window edge.
 
 ## Data attributes
 

package/drawer/README.md

@@ -1,3 +1,10 @@
+---
+title: Drawer
+group: primitives
+archetype: [overlay]
+apgUrl: https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/
+---
+
 # Drawer
 
 A side or bottom sheet built on the modal dialog pattern, adding pointer-driven swipe-to-dismiss and snap points.

package/dropdown-menu/README.md

@@ -1,3 +1,10 @@
+---
+title: Dropdown Menu
+group: primitives
+archetype: [overlay]
+apgUrl: https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/
+---
+
 # DropdownMenu
 
 A button that opens a menu of actions, with full keyboard navigation, typeahead and submenus.
@@ -156,7 +163,7 @@ Angular resolves `ng-template` DI at the template's **declaration** site, not wh
 
 Every output above is vetoable — each handler receives a `VetoableEvent` (or `VetoableNativeEvent<E>` when there is a native DOM event). Call `preventDefault()` on the emitted veto to suppress the directive's default action; the original DOM event, when present, is on `.event`.
 
-`(autoFocusOnOpen)` / `(autoFocusOnClose)` are output-shape because DropdownMenu always routes close transitions through `[(open)]` (via the implicit `openChange` emitter). See [Conventions › Auto-focus hook shape](../../../.claude/rules/conventions.md#auto-focus-hook-shape) for why Dialog uses callback-shape inputs instead.
+`(autoFocusOnOpen)` / `(autoFocusOnClose)` are output-shape because DropdownMenu always routes close transitions through `[(open)]` (via the implicit `openChange` emitter). Dialog and Drawer take callback-shape inputs for the same pair instead: either can be closed by a direct `open.set(false)` that bypasses the `(dismiss)` output entirely, so their close hook has to be a stored function reference that still runs during teardown.
 
 ### Data attributes
 

package/fesm2022/forty-cdk-listbox.mjs

@@ -628,8 +628,11 @@ class ForListbox extends FormUiControlBase {
         }
         this.markTouched();
     }
+    onPointerLeave() {
+        this.#pointerHost.set(null);
+    }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: ForListbox, deps: [], target: i0.ɵɵFactoryTarget.Directive });
-    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "22.0.2", type: ForListbox, isStandalone: true, selector: "[forListbox]", inputs: { value: { classPropertyName: "value", publicName: "value", isSignal: true, isRequired: false, transformFunction: null }, compareWith: { classPropertyName: "compareWith", publicName: "compareWith", isSignal: true, isRequired: false, transformFunction: null }, itemToFormValue: { classPropertyName: "itemToFormValue", publicName: "itemToFormValue", isSignal: true, isRequired: false, transformFunction: null }, multiple: { classPropertyName: "multiple", publicName: "multiple", isSignal: true, isRequired: false, transformFunction: null }, ariaLabel: { classPropertyName: "ariaLabel", publicName: "ariaLabel", isSignal: true, isRequired: false, transformFunction: null }, orientation: { classPropertyName: "orientation", publicName: "orientation", isSignal: true, isRequired: false, transformFunction: null }, loop: { classPropertyName: "loop", publicName: "loop", isSignal: true, isRequired: false, transformFunction: null }, totalCount: { classPropertyName: "totalCount", publicName: "totalCount", isSignal: true, isRequired: false, transformFunction: null }, visibleRange: { classPropertyName: "visibleRange", publicName: "visibleRange", isSignal: true, isRequired: false, transformFunction: null }, dataVersion: { classPropertyName: "dataVersion", publicName: "dataVersion", isSignal: true, isRequired: false, transformFunction: null }, _dirInput: { classPropertyName: "_dirInput", publicName: "dir", isSignal: true, isRequired: false, transformFunction: null }, selectionFollowsFocus: { classPropertyName: "selectionFollowsFocus", publicName: "selectionFollowsFocus", isSignal: true, isRequired: false, transformFunction: null } }, outputs: { value: "valueChange", scrollToIndex: "scrollToIndex" }, host: { attributes: { "role": "listbox" }, listeners: { "keydown": "onHostKeyDown($event)", "focusin": "onHostFocusIn()", "focusout": "onFocusOut($event)" }, properties: { "attr.aria-label": "resolvedAriaLabel()", "attr.aria-orientation": "orientation()", "attr.aria-multiselectable": "multiple() ? \"true\" : null", "attr.aria-disabled": "effectiveDisabled() ? \"true\" : null", "attr.aria-readonly": "readonly() ? \"true\" : null", "attr.aria-required": "required() ? \"true\" : null", "attr.aria-invalid": "invalid() ? \"true\" : null", "attr.aria-busy": "pending() ? \"true\" : null", "attr.aria-activedescendant": "activeDescendantId()", "attr.tabindex": "hostTabindex()", "attr.data-orientation": "orientation()", "attr.data-disabled": "effectiveDisabled() ? \"\" : null", "attr.data-readonly": "readonly() ? \"\" : null", "attr.dir": "dir()" } }, providers: [{ provide: FOR_LISTBOX_CONTEXT, useExisting: ForListbox }], exportAs: ["forListbox"], usesInheritance: true, ngImport: i0 });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "22.0.2", type: ForListbox, isStandalone: true, selector: "[forListbox]", inputs: { value: { classPropertyName: "value", publicName: "value", isSignal: true, isRequired: false, transformFunction: null }, compareWith: { classPropertyName: "compareWith", publicName: "compareWith", isSignal: true, isRequired: false, transformFunction: null }, itemToFormValue: { classPropertyName: "itemToFormValue", publicName: "itemToFormValue", isSignal: true, isRequired: false, transformFunction: null }, multiple: { classPropertyName: "multiple", publicName: "multiple", isSignal: true, isRequired: false, transformFunction: null }, ariaLabel: { classPropertyName: "ariaLabel", publicName: "ariaLabel", isSignal: true, isRequired: false, transformFunction: null }, orientation: { classPropertyName: "orientation", publicName: "orientation", isSignal: true, isRequired: false, transformFunction: null }, loop: { classPropertyName: "loop", publicName: "loop", isSignal: true, isRequired: false, transformFunction: null }, totalCount: { classPropertyName: "totalCount", publicName: "totalCount", isSignal: true, isRequired: false, transformFunction: null }, visibleRange: { classPropertyName: "visibleRange", publicName: "visibleRange", isSignal: true, isRequired: false, transformFunction: null }, dataVersion: { classPropertyName: "dataVersion", publicName: "dataVersion", isSignal: true, isRequired: false, transformFunction: null }, _dirInput: { classPropertyName: "_dirInput", publicName: "dir", isSignal: true, isRequired: false, transformFunction: null }, selectionFollowsFocus: { classPropertyName: "selectionFollowsFocus", publicName: "selectionFollowsFocus", isSignal: true, isRequired: false, transformFunction: null } }, outputs: { value: "valueChange", scrollToIndex: "scrollToIndex" }, host: { attributes: { "role": "listbox" }, listeners: { "keydown": "onHostKeyDown($event)", "focusin": "onHostFocusIn()", "focusout": "onFocusOut($event)", "pointerleave": "onPointerLeave()" }, properties: { "attr.aria-label": "resolvedAriaLabel()", "attr.aria-orientation": "orientation()", "attr.aria-multiselectable": "multiple() ? \"true\" : null", "attr.aria-disabled": "effectiveDisabled() ? \"true\" : null", "attr.aria-readonly": "readonly() ? \"true\" : null", "attr.aria-required": "required() ? \"true\" : null", "attr.aria-invalid": "invalid() ? \"true\" : null", "attr.aria-busy": "pending() ? \"true\" : null", "attr.aria-activedescendant": "activeDescendantId()", "attr.tabindex": "hostTabindex()", "attr.data-orientation": "orientation()", "attr.data-disabled": "effectiveDisabled() ? \"\" : null", "attr.data-readonly": "readonly() ? \"\" : null", "attr.dir": "dir()" } }, providers: [{ provide: FOR_LISTBOX_CONTEXT, useExisting: ForListbox }], exportAs: ["forListbox"], usesInheritance: true, ngImport: i0 });
 }
 i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: ForListbox, decorators: [{
             type: Directive,
@@ -655,6 +658,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.2", ngImpor
                         '(keydown)': 'onHostKeyDown($event)',
                         '(focusin)': 'onHostFocusIn()',
                         '(focusout)': 'onFocusOut($event)',
+                        '(pointerleave)': 'onPointerLeave()',
                     },
                     providers: [{ provide: FOR_LISTBOX_CONTEXT, useExisting: ForListbox }],
                 }]
@@ -685,6 +689,8 @@ const FOR_LISTBOX_OPTION = new InjectionToken('FOR_LISTBOX_OPTION');
 
 
 
+
+
 class ForListboxOption {
     buttonType = hostButtonType();
     #group = injectListboxContext('ForListboxOption');