forty-cdk 0.2.0 → 0.3.0

package/types/forty-cdk-accordion.d.ts

@@ -0,0 +1,242 @@
+import * as _angular_core from '@angular/core';
+import { InjectionToken, Signal, Provider } from '@angular/core';
+import { WritingDirection, ListNavigationAction } from 'forty-cdk/core';
+import * as forty_cdk_accordion from 'forty-cdk/accordion';
+
+/**
+ * Registry entry for one `ForAccordionTrigger`. Triggers register their host
+ * element so the root can drive keyboard navigation over its own triggers
+ * without an unscoped DOM query that would leak into nested accordions.
+ */
+interface ForAccordionTriggerHandle {
+    readonly host: HTMLElement;
+    readonly disabled: Signal<boolean>;
+}
+/**
+ * Coordination contract owned by the `ForAccordion` root.
+ * Items derive their state from this context; triggers route clicks and
+ * keyboard navigation through it.
+ */
+interface ForAccordionContext {
+    readonly multiple: Signal<boolean>;
+    readonly collapsible: Signal<boolean>;
+    readonly orientation: Signal<'horizontal' | 'vertical'>;
+    readonly dir: Signal<WritingDirection>;
+    isExpanded(itemValue: string): boolean;
+    toggle(itemValue: string): void;
+    /** Whether the given item is allowed to collapse right now. */
+    canCollapse(itemValue: string): boolean;
+    /**
+     * Focus a sibling trigger relative to the one currently focused. Disabled
+     * triggers are skipped. `currentTrigger` is the element from which the
+     * keyboard event originated. Navigation stays within this accordion's own
+     * registered triggers, so a nested accordion does not cross-contaminate.
+     */
+    focusByOffset(currentTrigger: HTMLElement, action: ListNavigationAction): void;
+    registerTrigger(handle: ForAccordionTriggerHandle): void;
+    unregisterTrigger(handle: ForAccordionTriggerHandle): void;
+}
+/**
+ * Per-item state contract. Provided by `ForAccordionItem`, consumed by
+ * its `ForAccordionTrigger` and `ForAccordionContent`.
+ */
+interface ForAccordionItemContext {
+    readonly expanded: Signal<boolean>;
+    readonly disabled: Signal<boolean>;
+    readonly value: Signal<string>;
+    readonly triggerId: Signal<string>;
+    readonly contentId: Signal<string>;
+    /** Adopts a consumer-set static `id` on the trigger host into `triggerId`. */
+    adoptTriggerId(el: HTMLElement): void;
+    /** Adopts a consumer-set static `id` on the content host into `contentId`. */
+    adoptContentId(el: HTMLElement): void;
+    toggle(): void;
+}
+declare const FOR_ACCORDION_CONTEXT: InjectionToken<ForAccordionContext>;
+declare const FOR_ACCORDION_ITEM_CONTEXT: InjectionToken<ForAccordionItemContext>;
+
+/**
+ * Root of the Accordion primitive. Holds the open value(s) and orchestrates
+ * single/multiple expansion, collapse rules, and keyboard navigation between
+ * triggers.
+ *
+ * Implements the [WAI-ARIA Accordion pattern](https://www.w3.org/WAI/ARIA/apg/patterns/accordion/).
+ *
+ * State is modeled as `value: readonly string[]` regardless of mode:
+ * - In single mode (`multiple=false`, default), the array has 0 or 1 element.
+ * - In multiple mode, any number of items can be open.
+ *
+ * @example
+ * ```html
+ * <div forAccordion [(value)]="open" collapsible>
+ *   <div forAccordionItem value="a">
+ *     <h3><button type="button" forAccordionTrigger>A</button></h3>
+ *     <section forAccordionContent>...</section>
+ *   </div>
+ *   <div forAccordionItem value="b">...</div>
+ * </div>
+ * ```
+ */
+declare class ForAccordion implements ForAccordionContext {
+    #private;
+    /** When true, multiple items can be expanded simultaneously. */
+    readonly multiple: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * Single mode only: when true, the open item can be collapsed by clicking
+     * its trigger. When false, exactly one item stays open at all times once
+     * any has been opened.
+     */
+    readonly collapsible: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * Layout direction of the trigger list. `'vertical'` (default) maps
+     * ArrowUp/Down to prev/next; `'horizontal'` maps ArrowLeft/Right (with RTL
+     * swap when `dir='rtl'`).
+     */
+    readonly orientation: _angular_core.InputSignal<"horizontal" | "vertical">;
+    /**
+     * Writing direction. Only relevant when `orientation='horizontal'`. When
+     * unset (default `null`), the inherited ambient direction is resolved from
+     * the nearest ancestor carrying a `dir` attribute (or `<html dir>`),
+     * defaulting to `'ltr'`. An explicit `[dir]` always wins. The resolved
+     * value is reflected to the host `dir` attribute and drives arrow-key
+     * semantics.
+     */
+    readonly _dirInput: _angular_core.InputSignal<WritingDirection | null>;
+    readonly dir: _angular_core.Signal<WritingDirection>;
+    /**
+     * When true (default), arrow navigation between triggers wraps at the ends —
+     * moving past the last trigger focuses the first and vice versa. Set `false`
+     * to stop at the boundaries. Mirrors the `loop` input on `ForTabs` and
+     * `ForListbox`.
+     */
+    readonly loop: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * Two-way bindable. List of currently expanded item values. In single
+     * mode the array has 0 or 1 element. The `model()` change emitter
+     * (`(valueChange)`) fires only on internal toggles, never on consumer
+     * writes via `[(value)]` — observe transitions without binding back.
+     */
+    readonly value: _angular_core.ModelSignal<readonly string[]>;
+    isExpanded(itemValue: string): boolean;
+    toggle(itemValue: string): void;
+    canCollapse(_itemValue: string): boolean;
+    focusByOffset(currentTrigger: HTMLElement, action: ListNavigationAction): void;
+    registerTrigger(handle: ForAccordionTriggerHandle): void;
+    unregisterTrigger(handle: ForAccordionTriggerHandle): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForAccordion, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForAccordion, "[forAccordion]", ["forAccordion"], { "multiple": { "alias": "multiple"; "required": false; "isSignal": true; }; "collapsible": { "alias": "collapsible"; "required": false; "isSignal": true; }; "orientation": { "alias": "orientation"; "required": false; "isSignal": true; }; "_dirInput": { "alias": "dir"; "required": false; "isSignal": true; }; "loop": { "alias": "loop"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; }, never, never, true, never>;
+}
+
+/**
+ * One section of a `ForAccordion`. Owns the unique `value` identifying this
+ * item to the root and exposes the per-item context that the trigger and
+ * content read.
+ */
+declare class ForAccordionItem implements ForAccordionItemContext {
+    #private;
+    protected readonly parent: forty_cdk_accordion.ForAccordionContext;
+    /** Unique identifier of this item within the accordion. Required. */
+    readonly value: _angular_core.InputSignal<string>;
+    /**
+     * When true, the trigger ignores clicks and reflects the native `disabled`
+     * attribute (not `aria-disabled`). The trigger is therefore dropped from the
+     * Tab order and skipped by arrow-key navigation, but stays in the
+     * accessibility tree so screen readers still announce it. See
+     * `ForAccordionTrigger` for the rationale (rule #561 D2).
+     */
+    readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    readonly triggerId: _angular_core.Signal<string>;
+    readonly contentId: _angular_core.Signal<string>;
+    readonly expanded: _angular_core.Signal<boolean>;
+    /**
+     * Adopts a consumer-set static `id` on the `[forAccordionTrigger]` host into
+     * `triggerId` (preserving anchors / external `aria-labelledby` references /
+     * label `for`) instead of letting the `[id]` host binding clobber it.
+     */
+    adoptTriggerId(el: HTMLElement): void;
+    /** Adopts a consumer-set static `id` on the content host into `contentId`. */
+    adoptContentId(el: HTMLElement): void;
+    toggle(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForAccordionItem, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForAccordionItem, "[forAccordionItem]", ["forAccordionItem"], { "value": { "alias": "value"; "required": true; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Header button for a `ForAccordionItem`. Apply on a `<button>` wrapped in a
+ * heading element (`<h2>`–`<h6>`) so APG landmark navigation works. The
+ * directive host-binds `type="button"` so a trigger inside a `<form>` never
+ * submits it on toggle.
+ *
+ * Handles ARIA wiring, click-to-toggle, and the recommended keyboard
+ * navigation (ArrowDown / ArrowUp / Home / End).
+ *
+ * `aria-controls` is emitted only while the item is expanded — mirroring the
+ * overlay triggers' open-only gating — so the reference never dangles at an
+ * unmounted panel under the recommended `@if (item.expanded())` mount pattern.
+ */
+declare class ForAccordionTrigger {
+    #private;
+    protected readonly parent: forty_cdk_accordion.ForAccordionContext;
+    protected readonly item: forty_cdk_accordion.ForAccordionItemContext;
+    /**
+     * APG: aria-disabled is true only when the panel is open AND the accordion
+     * disallows collapse. A real `disabled` item is reflected via the native
+     * `disabled` attribute instead — the sanctioned exception in rule #561 (D2):
+     * the trigger is a real single-purpose `<button>`, not a roving collection
+     * item (every trigger stays independently in the Tab order; the arrow-key
+     * navigation is an APG-optional enhancement layered on top, not a
+     * roving-tabindex collection), so native `disabled` is correct here. The
+     * button stays in the accessibility tree — screen readers still announce it
+     * as unavailable in browse mode — while being dropped from the Tab order and
+     * the arrow-key navigation (which `focusByOffset` already skips), keeping
+     * disabled triggers uniformly unreachable. The APG Accordion pattern does not
+     * require disabled headers to remain focusable.
+     */
+    protected readonly ariaDisabled: _angular_core.Signal<boolean>;
+    constructor();
+    protected onKeyDown(event: KeyboardEvent): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForAccordionTrigger, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForAccordionTrigger, "[forAccordionTrigger]", ["forAccordionTrigger"], {}, {}, never, never, true, never>;
+}
+
+/**
+ * Panel revealed by a `ForAccordionTrigger`. The directive does not manage
+ * DOM presence — wrap with `@if (item.expanded())` so panels mount and
+ * unmount with the expanded state and `animate.enter` / `animate.leave`
+ * work natively. If the consumer prefers to keep the panel mounted (for
+ * CSS-only transitions or to preserve internal state), the directive
+ * reflects `aria-hidden="true"` and `inert` while closed so the panel is
+ * removed from the accessibility tree and focus order automatically.
+ *
+ * APG note: `role="region"` adds the panel to the landmark navigation tree.
+ * If the accordion has 6+ simultaneously expandable panels, consider not
+ * using region — the directive will gain an opt-out input when this comes up
+ * in real usage.
+ */
+declare class ForAccordionContent {
+    protected readonly parent: forty_cdk_accordion.ForAccordionContext;
+    protected readonly item: forty_cdk_accordion.ForAccordionItemContext;
+    constructor();
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForAccordionContent, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForAccordionContent, "[forAccordionContent]", ["forAccordionContent"], {}, {}, never, never, true, never>;
+}
+
+/**
+ * Defaults inherited by descendant accordions in the surrounding injector
+ * scope. Configure with `provideForAccordionDefaults`. The shape is a stub
+ * today — present so future per-scope tuning can land without churning the
+ * public surface.
+ */
+interface ForAccordionDefaults {
+}
+/** Token holding the resolved accordion defaults for the current scope. */
+declare const FOR_ACCORDION_DEFAULTS: _angular_core.InjectionToken<ForAccordionDefaults>;
+/**
+ * Configures forty-cdk accordion defaults for this injector scope. Partial
+ * overrides inherit unspecified keys from the parent scope (or library
+ * defaults at the root).
+ */
+declare function provideForAccordionDefaults(defaults?: Partial<ForAccordionDefaults>): Provider[];
+
+export { FOR_ACCORDION_CONTEXT, FOR_ACCORDION_DEFAULTS, FOR_ACCORDION_ITEM_CONTEXT, ForAccordion, ForAccordionContent, ForAccordionItem, ForAccordionTrigger, provideForAccordionDefaults };
+export type { ForAccordionContext, ForAccordionDefaults, ForAccordionItemContext };

package/types/forty-cdk-aspect-ratio.d.ts

@@ -0,0 +1,59 @@
+import * as _angular_core from '@angular/core';
+import { Provider } from '@angular/core';
+
+/**
+ * Headless aspect-ratio container. Locks the host element's box to a fixed
+ * `width / height` ratio via the native CSS `aspect-ratio` property — useful
+ * for media (video, image, iframe) and skeletons that must reserve space
+ * before content loads.
+ *
+ * The directive only writes the `aspect-ratio` style; sizing rules (width,
+ * max-width, background, etc.) stay with the consumer.
+ *
+ * @example
+ * ```html
+ * <div forAspectRatio [ratio]="16 / 9">
+ *   <img src="cover.jpg" alt="" />
+ * </div>
+ *
+ * <div forAspectRatio ratio="1">  <!-- square -->
+ *   <video src="clip.mp4" controls></video>
+ * </div>
+ * ```
+ */
+declare class ForAspectRatio {
+    /**
+     * Width / height ratio, e.g. `16 / 9`, `4 / 3`, `1`. Accepts numeric inputs
+     * (`[ratio]="16 / 9"`) and string attributes (`ratio="1.5"`). Defaults to
+     * `1` (square). Non-positive or non-finite values fall back to `1` so the
+     * host never emits an invalid `aspect-ratio`.
+     */
+    readonly ratio: _angular_core.InputSignalWithTransform<number, unknown>;
+    /**
+     * The host `aspect-ratio` style value, guarded so a `0`, negative, or
+     * non-finite `ratio` never produces invalid CSS — it falls back to `1`.
+     */
+    protected readonly resolvedRatio: _angular_core.Signal<string>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForAspectRatio, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForAspectRatio, "[forAspectRatio]", ["forAspectRatio"], { "ratio": { "alias": "ratio"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Defaults inherited by descendant aspect-ratio containers in the surrounding
+ * injector scope. Configure with `provideForAspectRatioDefaults`. The shape
+ * is a stub today — present so future per-scope tuning can land without
+ * churning the public surface.
+ */
+interface ForAspectRatioDefaults {
+}
+/** Token holding the resolved aspect-ratio defaults for the current scope. */
+declare const FOR_ASPECT_RATIO_DEFAULTS: _angular_core.InjectionToken<ForAspectRatioDefaults>;
+/**
+ * Configures forty-cdk aspect-ratio defaults for this injector scope. Partial
+ * overrides inherit unspecified keys from the parent scope (or library
+ * defaults at the root).
+ */
+declare function provideForAspectRatioDefaults(defaults?: Partial<ForAspectRatioDefaults>): Provider[];
+
+export { FOR_ASPECT_RATIO_DEFAULTS, ForAspectRatio, provideForAspectRatioDefaults };
+export type { ForAspectRatioDefaults };

package/types/forty-cdk-avatar.d.ts

@@ -0,0 +1,133 @@
+import * as i0 from '@angular/core';
+import { InjectionToken, Signal, Provider } from '@angular/core';
+import * as forty_cdk_avatar from 'forty-cdk/avatar';
+
+/**
+ * Lifecycle stages of the avatar's image:
+ * - `idle`: no `src` set yet.
+ * - `loading`: `src` set, waiting for the network.
+ * - `loaded`: image rendered successfully.
+ * - `error`: image failed to load.
+ */
+type ForAvatarStatus = 'idle' | 'loading' | 'loaded' | 'error';
+interface ForAvatarContext {
+    /** Current status of the avatar's image. */
+    readonly status: Signal<ForAvatarStatus>;
+    /**
+     * `true` when the consumer should render the fallback. Drives `@if` in
+     * the consumer's template. Honors `fallbackDelayMs` for `idle` / `loading`
+     * states; `error` flips it to `true` immediately.
+     */
+    readonly shouldShowFallback: Signal<boolean>;
+    /**
+     * Internal — reported by `[forAvatarImage]` so the root can transition
+     * its state machine. Consumers should not call this.
+     */
+    reportStatus(status: ForAvatarStatus): void;
+}
+declare const FOR_AVATAR_CONTEXT: InjectionToken<ForAvatarContext>;
+
+/**
+ * Headless avatar root. Tracks the load lifecycle of an inner
+ * `[forAvatarImage]` and exposes `status` + `shouldShowFallback` so the
+ * consumer can swap the image for fallback content (initials, generic icon)
+ * via `@if`.
+ *
+ * No ARIA role is imposed — avatars are typically presentational. If the
+ * surrounding component conveys identity (a person's name in the header,
+ * a chat bubble), the consumer should provide an `aria-label` on the
+ * relevant ancestor or pair the avatar with visible text.
+ *
+ * @example
+ * ```html
+ * <span forAvatar #a="forAvatar" fallbackDelayMs="500">
+ *   <img forAvatarImage [src]="user.avatarUrl" [alt]="user.name" />
+ *   @if (a.shouldShowFallback()) {
+ *     <span forAvatarFallback>{{ user.initials }}</span>
+ *   }
+ * </span>
+ * ```
+ */
+declare class ForAvatar implements ForAvatarContext {
+    #private;
+    /**
+     * Milliseconds to defer the fallback for fast loads, avoiding a brief
+     * "initials → image" flicker. Set to `0` (default) to show immediately
+     * during `idle` / `loading`, or to e.g. `500` to skip rendering during
+     * quick cached loads. `error` always shows the fallback immediately.
+     * The default is read from `provideForAvatarDefaults` for the
+     * surrounding scope.
+     */
+    readonly fallbackDelayMs: i0.InputSignalWithTransform<number, unknown>;
+    readonly status: i0.Signal<ForAvatarStatus>;
+    readonly shouldShowFallback: i0.Signal<boolean>;
+    constructor();
+    static ɵfac: i0.ɵɵFactoryDeclaration<ForAvatar, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<ForAvatar, "[forAvatar]", ["forAvatar"], { "fallbackDelayMs": { "alias": "fallbackDelayMs"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Wraps an `<img>` and reports its load lifecycle to the surrounding
+ * `[forAvatar]`. The native `src` / `alt` bindings are owned by the
+ * consumer — this directive only observes.
+ *
+ * Reflects `data-status` on the image element so the consumer can hide it
+ * via CSS while loading or after an error (e.g. `img[data-status="error"]
+ * { display: none }`).
+ */
+declare class ForAvatarImage {
+    #private;
+    /**
+     * Emits whenever the image lifecycle transitions to a new state. Useful
+     * if the consumer wants to log analytics, swap to a different src on
+     * error, etc.
+     */
+    readonly loadStatusChanged: i0.OutputEmitterRef<ForAvatarStatus>;
+    constructor();
+    protected status(): ForAvatarStatus;
+    protected onLoad(): void;
+    protected onError(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ForAvatarImage, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<ForAvatarImage, "img[forAvatarImage]", ["forAvatarImage"], {}, { "loadStatusChanged": "loadStatusChanged"; }, never, never, true, never>;
+}
+
+/**
+ * Marker for the avatar's fallback content (initials, generic icon, …).
+ * Reflects `data-status` from the parent `[forAvatar]` so the consumer can
+ * style for the `error` state separately from `idle` / `loading` if needed.
+ *
+ * The decision of *whether* to render the fallback lives on the root —
+ * drive `@if` with `forAvatar.shouldShowFallback()`.
+ */
+declare class ForAvatarFallback {
+    protected readonly parent: forty_cdk_avatar.ForAvatarContext;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ForAvatarFallback, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<ForAvatarFallback, "[forAvatarFallback]", ["forAvatarFallback"], {}, {}, never, never, true, never>;
+}
+
+/**
+ * Defaults inherited by descendant avatars in the surrounding injector
+ * scope. Configure with `provideForAvatarDefaults` either at the
+ * application root or in any component's `providers` array; partial
+ * overrides merge with the parent scope.
+ */
+interface ForAvatarDefaults {
+    /**
+     * Milliseconds to defer the fallback for fast loads, avoiding a brief
+     * "initials → image" flicker. Set to `0` to show immediately during
+     * `idle` / `loading`, or to e.g. `500` to skip rendering during quick
+     * cached loads. `error` always shows the fallback immediately.
+     */
+    fallbackDelayMs: number;
+}
+/** Token holding the resolved avatar defaults for the current scope. */
+declare const FOR_AVATAR_DEFAULTS: i0.InjectionToken<ForAvatarDefaults>;
+/**
+ * Configures forty-cdk avatar defaults for this injector scope. Partial
+ * overrides inherit unspecified keys from the parent scope (or library
+ * defaults at the root).
+ */
+declare function provideForAvatarDefaults(defaults?: Partial<ForAvatarDefaults>): Provider[];
+
+export { FOR_AVATAR_CONTEXT, FOR_AVATAR_DEFAULTS, ForAvatar, ForAvatarFallback, ForAvatarImage, provideForAvatarDefaults };
+export type { ForAvatarContext, ForAvatarDefaults, ForAvatarStatus };

package/types/forty-cdk-breadcrumbs.d.ts

@@ -0,0 +1,92 @@
+import * as i0 from '@angular/core';
+import { Provider } from '@angular/core';
+
+/**
+ * Headless breadcrumb trail implementing the
+ * [WAI-ARIA Breadcrumb pattern](https://www.w3.org/WAI/ARIA/apg/patterns/breadcrumb/):
+ * a `navigation` landmark wrapping a set of links that reveal the page's
+ * position within the site hierarchy.
+ *
+ * The directive contributes only the landmark role + accessible name; the
+ * consumer owns the markup structure (an `<ol>` of `<li>` links is the APG
+ * recommendation) and applies their own styles. Each link decorated with
+ * `[forBreadcrumbItem]` can mark itself the current page via `current`, and
+ * visual dividers decorated with `[forBreadcrumbSeparator]` are hidden from
+ * assistive technology.
+ *
+ * There is no keyboard interaction or focus management beyond what the native
+ * links provide — breadcrumb links are ordinary tab stops.
+ *
+ * @example
+ * ```html
+ * <nav forBreadcrumbs>
+ *   <ol>
+ *     <li><a forBreadcrumbItem href="/">Home</a></li>
+ *     <li forBreadcrumbSeparator aria-hidden="true">/</li>
+ *     <li><a forBreadcrumbItem href="/library">Library</a></li>
+ *     <li forBreadcrumbSeparator aria-hidden="true">/</li>
+ *     <li><a forBreadcrumbItem href="/library/data" current>Data</a></li>
+ *   </ol>
+ * </nav>
+ * ```
+ */
+declare class ForBreadcrumbs {
+    /**
+     * Accessible label for the navigation landmark. Defaults to `'Breadcrumb'`
+     * so a bare `<nav forBreadcrumbs>` is already a correctly labelled landmark —
+     * the conventional name for this pattern. Override it (or point a native
+     * `aria-labelledby` at a visible heading) when the page hosts more than one
+     * breadcrumb trail and they need to be told apart.
+     */
+    readonly ariaLabel: i0.InputSignal<string | null>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ForBreadcrumbs, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<ForBreadcrumbs, "[forBreadcrumbs]", ["forBreadcrumbs"], { "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * A single link within a breadcrumb trail. Apply on an `<a>` so navigation is
+ * native. Set `current` on the link that points to the page the user is on —
+ * it reflects [`aria-current="page"`](https://www.w3.org/TR/wai-aria-1.2/#aria-current)
+ * so assistive technology announces it as the current location.
+ */
+declare class ForBreadcrumbItem {
+    /**
+     * Whether this item represents the page the user is currently on. The
+     * current item reflects `aria-current="page"`; all others emit no
+     * `aria-current` attribute.
+     */
+    readonly current: i0.InputSignalWithTransform<boolean, unknown>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ForBreadcrumbItem, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<ForBreadcrumbItem, "[forBreadcrumbItem]", ["forBreadcrumbItem"], { "current": { "alias": "current"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Decorative divider rendered between breadcrumb items (a `/`, `>`, chevron,
+ * etc.). Reflects `aria-hidden="true"` so assistive technology skips it — the
+ * trail's structure is already conveyed by the list and the links, making the
+ * visual separator redundant in the accessibility tree.
+ */
+declare class ForBreadcrumbSeparator {
+    static ɵfac: i0.ɵɵFactoryDeclaration<ForBreadcrumbSeparator, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<ForBreadcrumbSeparator, "[forBreadcrumbSeparator]", ["forBreadcrumbSeparator"], {}, {}, never, never, true, never>;
+}
+
+/**
+ * Defaults inherited by descendant breadcrumbs in the surrounding injector
+ * scope. Configure with `provideForBreadcrumbsDefaults`. The shape is a stub
+ * today — present so future per-scope tuning can land without churning the
+ * public surface.
+ */
+interface ForBreadcrumbsDefaults {
+}
+/** Token holding the resolved breadcrumbs defaults for the current scope. */
+declare const FOR_BREADCRUMBS_DEFAULTS: i0.InjectionToken<ForBreadcrumbsDefaults>;
+/**
+ * Configures forty-cdk breadcrumbs defaults for this injector scope. Partial
+ * overrides inherit unspecified keys from the parent scope (or library
+ * defaults at the root).
+ */
+declare function provideForBreadcrumbsDefaults(defaults?: Partial<ForBreadcrumbsDefaults>): Provider[];
+
+export { FOR_BREADCRUMBS_DEFAULTS, ForBreadcrumbItem, ForBreadcrumbSeparator, ForBreadcrumbs, provideForBreadcrumbsDefaults };
+export type { ForBreadcrumbsDefaults };

package/types/forty-cdk-breakpoints.d.ts

@@ -0,0 +1,141 @@
+import * as _angular_core from '@angular/core';
+import { Provider, Signal } from '@angular/core';
+
+/**
+ * A breakpoint map: each named breakpoint paired with its `min-width`
+ * threshold in CSS pixels. Names are arbitrary — `injectBreakpoints` derives
+ * its query methods (`up`, `down`, `between`, `only`) from whatever keys this
+ * map declares, sorted ascending by threshold.
+ */
+type BreakpointMap = Record<string, number>;
+/**
+ * The default breakpoint map, mirroring Tailwind CSS's `sm`–`2xl` scale. Used
+ * as the library fallback when no `provideForBreakpoints` is in scope, and the
+ * source of the typed breakpoint names when the consumer has not augmented
+ * {@link BreakpointRegistry}.
+ */
+declare const breakpointsTailwind: {
+    readonly sm: 640;
+    readonly md: 768;
+    readonly lg: 1024;
+    readonly xl: 1280;
+    readonly '2xl': 1536;
+};
+/** The breakpoint names from the default Tailwind scale. */
+type TailwindBreakpointName = keyof typeof breakpointsTailwind;
+/** Resolved shape stored against {@link FOR_BREAKPOINTS}. */
+interface ForBreakpointsDefaults {
+    /** The active breakpoint map for the current injector scope. */
+    breakpoints: BreakpointMap;
+}
+/**
+ * Token holding the resolved breakpoint map for the current injector scope.
+ * The library always provides a fully-populated value (the Tailwind fallback
+ * at the root, or the map from the nearest `provideForBreakpoints`).
+ */
+declare const FOR_BREAKPOINTS: _angular_core.InjectionToken<ForBreakpointsDefaults>;
+/**
+ * Configures the breakpoint map for this injector scope so `injectBreakpoints`
+ * can be called with no arguments. Provide it once in your application config:
+ *
+ * ```ts
+ * providers: [
+ *   provideForBreakpoints({ mobile: 0, tablet: 640, laptop: 1024, desktop: 1280 }),
+ * ]
+ * ```
+ *
+ * Providing it again on a component injector replaces the map for that subtree
+ * only (the nearest scope wins; the map is replaced wholesale, never merged
+ * key-by-key). Omit it entirely to use {@link breakpointsTailwind}.
+ */
+declare function provideForBreakpoints(breakpoints: BreakpointMap): Provider[];
+
+/**
+ * Extension point for typing custom breakpoint names. Augment it via module
+ * declaration merging so `injectBreakpoints` autocompletes your own names
+ * instead of the default Tailwind scale:
+ *
+ * ```ts
+ * import type { appBreakpoints } from './breakpoints';
+ *
+ * declare module 'forty-cdk' {
+ *   interface BreakpointRegistry extends Record<keyof typeof appBreakpoints, true> {}
+ * }
+ * ```
+ *
+ * When left empty (no augmentation), {@link BreakpointName} falls back to the
+ * keys of {@link breakpointsTailwind}.
+ */
+interface BreakpointRegistry {
+}
+/**
+ * The set of valid breakpoint names. Resolves to the augmented
+ * {@link BreakpointRegistry} keys when present, otherwise the Tailwind scale
+ * (`'sm' | 'md' | 'lg' | 'xl' | '2xl'`).
+ */
+type BreakpointName = [keyof BreakpointRegistry] extends [never] ? TailwindBreakpointName : keyof BreakpointRegistry & string;
+/** Reactive handle returned by {@link injectBreakpoints}. */
+interface ForBreakpoints<K extends string = BreakpointName> {
+    /**
+     * Matches the named breakpoint and wider — `(min-width: <threshold>px)`.
+     * @param name A breakpoint declared in the active map.
+     */
+    up(name: K): Signal<boolean>;
+    /**
+     * Matches narrower than the named breakpoint —
+     * `(max-width: <threshold - 0.02>px)`. The 0.02px back-off keeps `up(name)`
+     * and `down(name)` from both matching at the exact threshold.
+     * @param name A breakpoint declared in the active map.
+     */
+    down(name: K): Signal<boolean>;
+    /**
+     * Matches from `min` (inclusive) up to but not including `max`.
+     * @param min Lower breakpoint, inclusive.
+     * @param max Upper breakpoint, exclusive.
+     */
+    between(min: K, max: K): Signal<boolean>;
+    /**
+     * Matches only the named breakpoint's own band — from its threshold up to
+     * but not including the next-larger breakpoint (open-ended for the largest).
+     * @param name A breakpoint declared in the active map.
+     */
+    only(name: K): Signal<boolean>;
+    /**
+     * The largest breakpoint whose `min-width` currently matches, or `null` when
+     * the viewport is narrower than the smallest breakpoint (and on the server).
+     */
+    readonly active: Signal<K | null>;
+    /**
+     * Escape hatch for an arbitrary media query string (orientation, pointer,
+     * `prefers-color-scheme`, …) that the named helpers don't cover.
+     * @param query Any valid media query.
+     */
+    matches(query: string): Signal<boolean>;
+}
+/**
+ * A signal-first, zoneless, SSR-safe viewport breakpoint observer. Reads the
+ * breakpoint map from the ambient {@link FOR_BREAKPOINTS} token (configured
+ * with `provideForBreakpoints`, or the Tailwind fallback), so call sites never
+ * repeat the breakpoint set:
+ *
+ * ```ts
+ * private bp = injectBreakpoints();
+ * protected isDesktop = this.bp.up('desktop');
+ * protected active = this.bp.active;
+ * ```
+ *
+ * Each query method returns a `Signal<boolean>` backed by a cached
+ * `MediaQueryList`. The returned handle captures the calling injection
+ * context, so its methods can be invoked lazily from `computed()` or a
+ * template — not only during construction. Listeners are torn down with the
+ * injector. On the server (or where `matchMedia` is unavailable) every signal
+ * reads `false` and `active` reads `null`.
+ *
+ * Must be called from an injection context.
+ *
+ * @returns A {@link ForBreakpoints} handle of reactive query methods.
+ */
+declare function injectBreakpoints(): ForBreakpoints;
+
+export { FOR_BREAKPOINTS, breakpointsTailwind, injectBreakpoints, provideForBreakpoints };
+export type { BreakpointMap, BreakpointName, BreakpointRegistry, ForBreakpoints, ForBreakpointsDefaults };