forty-cdk 0.2.0 → 0.3.0

package/types/forty-cdk-dropdown-menu.d.ts

@@ -0,0 +1,242 @@
+import * as forty_cdk_core from 'forty-cdk/core';
+import { MenuOverlayHost, ForMenuContext, FloatingSide, FloatingAlign, WritingDirection, VetoableNativeEvent, VetoableEvent } from 'forty-cdk/core';
+import * as _angular_core from '@angular/core';
+import { Signal, Provider } from '@angular/core';
+import { ReferenceElement } from '@floating-ui/dom';
+
+/**
+ * Headless implementation of the [WAI-ARIA Menu Button pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/).
+ * Apply on a wrapper that contains the trigger and the `@if`-mounted
+ * `[forMenuContent]`. The directive owns open state, ids, and the registries
+ * that wire trigger / content / items together.
+ *
+ * Mount/unmount of the visible menu is the consumer's responsibility — wrap
+ * `[forMenuContent]` with `@if (open())` so `animate.enter` / `animate.leave`
+ * fire on the natural mount cycle:
+ *
+ * ```html
+ * <div forDropdownMenu [(open)]="open">
+ *   <button forDropdownMenuTrigger>Options</button>
+ *   @if (open()) {
+ *     <div forMenuContent>…</div>
+ *   }
+ * </div>
+ * ```
+ *
+ * Selecting a `[forMenuItem]` closes the menu (call `event.preventDefault()`
+ * on the item's `(activate)` event to keep it open). Escape, pointer-down
+ * outside, and focus-outside also close — each emits a vetoable event.
+ *
+ * Most of the directive's body (id generation, item collection, typeahead,
+ * navigate / focus helpers, escape / outside-click veto plumbing) is owned
+ * by the shared `_internal/menu-overlay` helper. The directive contributes
+ * the inputs / outputs / model that make up the public surface, the
+ * trigger-anchored `anchor` and `dismissableExemptions`, and the
+ * `aria-haspopup="menu"` / return-focus semantics specific to the
+ * Menu Button pattern.
+ */
+declare class ForDropdownMenu extends MenuOverlayHost implements ForMenuContext {
+    #private;
+    /**
+     * Two-way bindable. Whether the menu is currently shown. The `model()`
+     * change emitter (`(openChange)`) fires only on internal transitions
+     * (trigger toggle, Escape, outside dismissal, item selection), never on
+     * consumer writes via `[(open)]`.
+     */
+    readonly open: _angular_core.ModelSignal<boolean>;
+    /**
+     * Side the menu is anchored to. Defaults to `'bottom'`. Pair with
+     * `align` for the full positioning API.
+     *
+     * One of the floating-ui positioning inputs shared verbatim across the
+     * three menu roots — their non-seed defaults come from the single
+     * `MENU_POSITIONING_DEFAULTS` source and `menu-positioning-inputs.spec.ts`
+     * guards the three roots against drift.
+     */
+    readonly side: _angular_core.InputSignal<FloatingSide | undefined>;
+    /** Alignment along the chosen `side`. Defaults to `'start'`. */
+    readonly align: _angular_core.InputSignal<FloatingAlign | undefined>;
+    /**
+     * Gap (px) between trigger and menu along the main axis. Default `4`.
+     * The default is read from
+     * `provideForDropdownMenuDefaults` for the surrounding scope.
+     */
+    readonly sideOffset: _angular_core.InputSignalWithTransform<number, unknown>;
+    /** Gap (px) along the cross axis. Default `0`. */
+    readonly alignOffset: _angular_core.InputSignalWithTransform<number, unknown>;
+    /** When `true` (default), `flip` and `shift` keep the menu inside the viewport. */
+    readonly avoidCollisions: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * Padding (px) applied uniformly to flip / shift / size. Default `8`.
+     * The default is read from `provideForDropdownMenuDefaults` for the
+     * surrounding scope.
+     */
+    readonly collisionPadding: _angular_core.InputSignalWithTransform<number, unknown>;
+    /** Padding (px) for the `arrow` middleware. Default `0`. */
+    readonly arrowPadding: _angular_core.InputSignalWithTransform<number, unknown>;
+    /** Stickiness behaviour for `shift`. Default `'partial'`. */
+    readonly sticky: _angular_core.InputSignal<false | "partial" | "always">;
+    /** When `true`, sets `data-detached=""` while the trigger is scrolled off-screen. */
+    readonly hideWhenDetached: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * When `true` (default), the menu is clipped until floating-ui resolves
+     * its first position, preventing a flash at the viewport corner. Set to
+     * `false` so a dramatic `animate.enter` plays from its first frame.
+     */
+    readonly clipUntilPositioned: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * When `true` (default), arrow-key navigation wraps from the last enabled
+     * item back to the first (and vice versa). When `false`, navigation stops
+     * at the ends.
+     */
+    readonly loop: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * Writing direction. Drives ArrowLeft / ArrowRight semantics on submenu
+     * triggers and items underneath this menu (in RTL, ArrowLeft opens a submenu
+     * and ArrowRight closes it back). 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 it is inherited by descendant submenus.
+     */
+    readonly _dirInput: _angular_core.InputSignal<WritingDirection | null>;
+    readonly dir: _angular_core.Signal<WritingDirection>;
+    /**
+     * When true, trigger interaction is ignored and any open menu stays open
+     * until the consumer flips `open` themselves. The trigger reflects
+     * `data-disabled`; the items keep their per-item disabled semantics.
+     */
+    readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** When true (default), Escape, pointer-down outside, and focus outside close the menu. */
+    readonly dismissible: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** When true (default), focus returns to the trigger on close. */
+    readonly returnFocus: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Manual `aria-label` on `[forMenuContent]`. Use when the trigger isn't a meaningful name. */
+    readonly ariaLabel: _angular_core.InputSignal<string | null>;
+    /**
+     * Fires when Escape is pressed while the menu is open, just before it
+     * closes. Call `preventDefault()` on the emitted veto to keep the menu
+     * open and suppress the Escape-driven close.
+     */
+    readonly escapeKeyDown: _angular_core.OutputEmitterRef<VetoableNativeEvent<KeyboardEvent>>;
+    /**
+     * Fires on a pointer-down outside the menu (and outside the exempt
+     * trigger), just before it closes. Call `preventDefault()` on the veto to
+     * keep the menu open.
+     */
+    readonly pointerDownOutside: _angular_core.OutputEmitterRef<VetoableNativeEvent<PointerEvent>>;
+    /**
+     * Fires when focus moves outside the menu, just before it closes. Call
+     * `preventDefault()` on the veto to keep the menu open.
+     */
+    readonly focusOutside: _angular_core.OutputEmitterRef<VetoableNativeEvent<FocusEvent>>;
+    /**
+     * Composite outside-interaction channel: fires for either a
+     * pointer-down-outside or a focus-outside, just before the menu closes.
+     * Call `preventDefault()` on the veto to keep the menu open regardless of
+     * which interaction triggered it.
+     */
+    readonly interactOutside: _angular_core.OutputEmitterRef<VetoableNativeEvent<PointerEvent | FocusEvent>>;
+    /**
+     * Fires just before the menu sends focus to its first / last enabled
+     * item on mount. Call `preventDefault()` on the emitted veto to skip
+     * the imperative focus move — useful when opening a menu from an
+     * input you want to keep focused.
+     */
+    readonly autoFocusOnOpen: _angular_core.OutputEmitterRef<VetoableEvent>;
+    /**
+     * Fires just before focus returns to the trigger on unmount. Call
+     * `preventDefault()` on the veto to suppress the return-focus.
+     */
+    readonly autoFocusOnClose: _angular_core.OutputEmitterRef<VetoableEvent>;
+    protected readonly _overlay: forty_cdk_core.MenuOverlay<forty_cdk_core.MenuItemHandle>;
+    readonly anchor: _angular_core.Signal<ReferenceElement | null>;
+    readonly dismissableExemptions: _angular_core.Signal<readonly HTMLElement[]>;
+    /** Top-level: no parent menu. */
+    readonly parentMenu: null;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForDropdownMenu, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForDropdownMenu, "[forDropdownMenu]", ["forDropdownMenu"], { "open": { "alias": "open"; "required": false; "isSignal": true; }; "side": { "alias": "side"; "required": false; "isSignal": true; }; "align": { "alias": "align"; "required": false; "isSignal": true; }; "sideOffset": { "alias": "sideOffset"; "required": false; "isSignal": true; }; "alignOffset": { "alias": "alignOffset"; "required": false; "isSignal": true; }; "avoidCollisions": { "alias": "avoidCollisions"; "required": false; "isSignal": true; }; "collisionPadding": { "alias": "collisionPadding"; "required": false; "isSignal": true; }; "arrowPadding": { "alias": "arrowPadding"; "required": false; "isSignal": true; }; "sticky": { "alias": "sticky"; "required": false; "isSignal": true; }; "hideWhenDetached": { "alias": "hideWhenDetached"; "required": false; "isSignal": true; }; "clipUntilPositioned": { "alias": "clipUntilPositioned"; "required": false; "isSignal": true; }; "loop": { "alias": "loop"; "required": false; "isSignal": true; }; "_dirInput": { "alias": "dir"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "dismissible": { "alias": "dismissible"; "required": false; "isSignal": true; }; "returnFocus": { "alias": "returnFocus"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; }, { "open": "openChange"; "escapeKeyDown": "escapeKeyDown"; "pointerDownOutside": "pointerDownOutside"; "focusOutside": "focusOutside"; "interactOutside": "interactOutside"; "autoFocusOnOpen": "autoFocusOnOpen"; "autoFocusOnClose": "autoFocusOnClose"; }, never, never, true, never>;
+}
+
+/**
+ * Button that toggles the dropdown menu when clicked, opens via ArrowDown
+ * (focus first item) or ArrowUp (focus last item).
+ *
+ * Apply on a `<button>` so Space / Enter dispatch native click events
+ * automatically — those open the menu via `(click)`. Wires `aria-haspopup`,
+ * `aria-expanded`, and `aria-controls` per the menu-button pattern.
+ *
+ * The trigger distinguishes pointer from keyboard activation (a `pointerdown`
+ * preceding the click marks it pointer-driven): both move focus to the first
+ * item, but only a keyboard open highlights it — a mouse-opened menu carries
+ * no `data-highlighted` until keyboard navigation.
+ *
+ * Disabling: the trigger merges its own `disabled` input OR the root's
+ * `disabled`. The native `disabled` attribute is reflected imperatively and
+ * non-destructively — the directive only removes the attribute when it set it
+ * itself, so a consumer-set `disabled` on the same button always survives an
+ * enabled menu context.
+ *
+ * The root is normally resolved via DI from the enclosing `[forDropdownMenu]`.
+ * When the trigger is declared inside an `ng-template` stamped into the root
+ * (e.g. via `ngTemplateOutlet`), DI resolves at the template's declaration
+ * site and misses the root — pass it explicitly through the selector input,
+ * `routerLink`-style: `[forDropdownMenuTrigger]="root"` with
+ * `#root="forDropdownMenu"`.
+ */
+declare class ForDropdownMenuTrigger {
+    #private;
+    /**
+     * Optional explicit reference to the `[forDropdownMenu]` root, named after
+     * the selector `routerLink`-style. The bare valueless attribute keeps
+     * resolving the enclosing root via DI; pass the root explicitly
+     * (`[forDropdownMenuTrigger]="root"`, with `#root="forDropdownMenu"`) when
+     * the trigger is declared in an `ng-template` stamped inside the root — DI
+     * resolves at the template's declaration site, so the enclosing root is
+     * invisible there. The empty string (what the valueless attribute yields)
+     * is treated as unset.
+     */
+    readonly forDropdownMenuTrigger: _angular_core.InputSignal<"" | ForMenuContext>;
+    protected readonly ctx: Signal<ForMenuContext>;
+    /** Disables this trigger only, in addition to the root's `disabled`. */
+    readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Whether the trigger is disabled — its own `disabled` input OR the root's. */
+    readonly effectiveDisabled: Signal<boolean>;
+    constructor();
+    protected onPointerDown(): void;
+    protected onClick(): void;
+    protected onKeyDown(event: KeyboardEvent): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForDropdownMenuTrigger, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForDropdownMenuTrigger, "[forDropdownMenuTrigger]", ["forDropdownMenuTrigger"], { "forDropdownMenuTrigger": { "alias": "forDropdownMenuTrigger"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Defaults inherited by descendant dropdown menus in the surrounding
+ * injector scope. Configure with `provideForDropdownMenuDefaults` either
+ * at the application root or in any component's `providers` array; partial
+ * overrides merge with the parent scope.
+ */
+interface ForDropdownMenuDefaults {
+    /**
+     * Distance (px) between the dropdown trigger and the floating content
+     * along the resolved `side` axis.
+     */
+    sideOffset: number;
+    /**
+     * Padding (px) added to the viewport edges for collision-aware
+     * positioning. Higher values keep the floating content further from
+     * the edge when `flip` / `shift` runs.
+     */
+    collisionPadding: number;
+}
+/** Token holding the resolved dropdown-menu defaults for the current scope. */
+declare const FOR_DROPDOWN_MENU_DEFAULTS: _angular_core.InjectionToken<ForDropdownMenuDefaults>;
+/**
+ * Configures forty-cdk dropdown-menu defaults for this injector scope.
+ * Partial overrides inherit unspecified keys from the parent scope (or
+ * library defaults at the root).
+ */
+declare function provideForDropdownMenuDefaults(defaults?: Partial<ForDropdownMenuDefaults>): Provider[];
+
+export { FOR_DROPDOWN_MENU_DEFAULTS, ForDropdownMenu, ForDropdownMenuTrigger, provideForDropdownMenuDefaults };
+export type { ForDropdownMenuDefaults };

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

@@ -0,0 +1,236 @@
+import * as _angular_core from '@angular/core';
+import { Provider } from '@angular/core';
+import * as forty_cdk_core from 'forty-cdk/core';
+import { ForFieldContext, FieldControlHandle } from 'forty-cdk/core';
+export { FOR_FIELD_CONTEXT, FieldControlHandle, ForFieldContext, injectFieldWiring } from 'forty-cdk/core';
+import { ValidationError } from '@angular/forms/signals';
+
+/**
+ * Headless form-field container that wires accessible labelling, description,
+ * and error association for a single control. It renders nothing and imposes no
+ * layout: its only job is to connect a `[forLabel]`, `[forFieldDescription]`,
+ * and `[forFieldError]` to the control via `id` / `aria-labelledby` /
+ * `aria-describedby` / `aria-errormessage`, and to reflect the control's
+ * validation state as `data-*` hooks for styling.
+ *
+ * Any forty-cdk form control (every `FormValueControl` / `FormCheckboxControl`
+ * primitive) auto-associates when wrapped — no extra markup. A plain native
+ * `<input>` opts in with `[forFieldControl]`.
+ *
+ * Host reflects `data-invalid` / `data-disabled` / `data-required` /
+ * `data-touched` from the registered control.
+ *
+ * @example
+ * ```html
+ * <div forField>
+ *   <label forLabel>Notifications</label>
+ *   <button forSwitch [formField]="settings.notify"></button>
+ *   <p forFieldDescription>We'll only email you about security.</p>
+ *   @if (settings.notify().invalid()) {
+ *     <p forFieldError #err="forFieldError">{{ err.messages().join(', ') }}</p>
+ *   }
+ * </div>
+ * ```
+ */
+declare class ForField implements ForFieldContext {
+    #private;
+    /**
+     * Id assigned to the control; a label's `for` points here. Adopts a
+     * nominated control's own id (`labelledElementId`) when present so the label
+     * and the primitive's internal `aria-labelledby` resolve to the same
+     * focusable element; otherwise the field's owned/host-adopted id.
+     */
+    readonly controlId: _angular_core.Signal<string>;
+    /** Id of the label element. */
+    readonly labelId: _angular_core.WritableSignal<string>;
+    /** Id of the description element. */
+    readonly descriptionId: _angular_core.WritableSignal<string>;
+    /** Id of the error element. */
+    readonly errorId: _angular_core.WritableSignal<string>;
+    /** The currently registered control handle, or null. */
+    readonly control: _angular_core.Signal<FieldControlHandle | null>;
+    /** Whether the registered control is currently invalid. */
+    readonly invalid: _angular_core.Signal<boolean>;
+    /** Whether the registered control is required. */
+    readonly required: _angular_core.Signal<boolean>;
+    /**
+     * Whether the field is disabled: the registered control's own disabled state
+     * OR'd with a surrounding `[forFieldset]`'s `disabled` (so a disabled group
+     * reaches custom-role controls a native `<fieldset disabled>` can't).
+     */
+    readonly disabled: _angular_core.Signal<boolean>;
+    /** Whether the registered control has been touched. */
+    readonly touched: _angular_core.Signal<boolean>;
+    /** Resolved `aria-labelledby` for the control (label id, or null). */
+    readonly labelledBy: _angular_core.Signal<string | null>;
+    /**
+     * Resolved `aria-describedby`: the description id always, plus the error id
+     * when the control is invalid. The error id is included here (in addition to
+     * `aria-errormessage`) because assistive-tech support for `aria-errormessage`
+     * is uneven; doubling it up is the widely-used robust pattern.
+     */
+    readonly describedBy: _angular_core.Signal<string | null>;
+    /** Resolved `aria-errormessage`: the error id when present and invalid, else null. */
+    readonly errorMessageId: _angular_core.Signal<string | null>;
+    /** Register the control whose state the field reflects. */
+    registerControl(handle: FieldControlHandle): void;
+    /** Remove a previously registered control. */
+    unregisterControl(handle: FieldControlHandle): void;
+    /**
+     * Mark the label slot present; returns an unregister callback. The field
+     * targets a single label per slot — its `labelId` / `descriptionId` /
+     * `errorId` are single ids, not id lists — so one `[forLabel]`,
+     * `[forFieldDescription]`, and `[forFieldError]` per field is the supported
+     * shape. Presence is a boolean, not a count.
+     */
+    registerLabel(): () => void;
+    /** Mark the description slot present; returns an unregister callback. See {@link registerLabel} for the single-instance-per-slot contract. */
+    registerDescription(): () => void;
+    /** Mark the error slot present; returns an unregister callback. See {@link registerLabel} for the single-instance-per-slot contract. */
+    registerError(): () => void;
+    /**
+     * Forward a click to the control's focusable element and focus it — matching
+     * the activation a native `<label for>` triggers via the browser, so a
+     * non-`<label>` `[forLabel]` toggles a custom-role control instead of only
+     * focusing it.
+     */
+    clickControl(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForField, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForField, "[forField]", ["forField"], {}, {}, never, never, true, never>;
+}
+
+/**
+ * Accessible label for a form control. Inside a `[forField]` it auto-wires:
+ * it adopts the field's `labelId` and registers itself so the control gains
+ * `aria-labelledby`.
+ *
+ * Click-to-activate is consistent across both host shapes: a native `<label>`
+ * emits `for` and the browser forwards the click to the control (toggling a
+ * checkbox / switch, activating a button); a non-`<label>` host has no native
+ * `for` forwarding, so the directive forwards the click itself — clicking the
+ * label activates the control either way, not just focuses it. A click that
+ * originated on the control (when the control is nested inside the label host)
+ * is not re-forwarded, so a label-wrapping layout toggles once, matching native
+ * `<label>` semantics.
+ *
+ * Usable standalone outside a field — there it is an inert
+ * marker and the consumer wires native `for` themselves.
+ *
+ * @example
+ * ```html
+ * <div forField>
+ *   <label forLabel>Email</label>
+ *   <input forFieldControl type="email" />
+ * </div>
+ * ```
+ */
+declare class ForLabel {
+    #private;
+    protected readonly ctx: forty_cdk_core.ForFieldContext | null;
+    /** The label's id when inside a field, else null. */
+    protected readonly labelId: _angular_core.Signal<string | null>;
+    /** `for` is only meaningful on a native `<label>`; null otherwise. */
+    protected readonly forAttr: _angular_core.Signal<string | null>;
+    constructor();
+    protected onClick(event: MouseEvent): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForLabel, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForLabel, "[forLabel]", ["forLabel"], {}, {}, never, never, true, never>;
+}
+
+/**
+ * Supplementary description / hint for a form control. Adopts the field's
+ * `descriptionId` and registers itself so the control gains
+ * `aria-describedby`. Apply on a `<p>` / `<span>` inside a `[forField]`.
+ */
+declare class ForFieldDescription {
+    protected readonly ctx: forty_cdk_core.ForFieldContext;
+    constructor();
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForFieldDescription, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForFieldDescription, "[forFieldDescription]", ["forFieldDescription"], {}, {}, never, never, true, never>;
+}
+
+/**
+ * Error region for a form control. Adopts the field's `errorId`, registers
+ * itself so the control gains `aria-errormessage` (and the id is folded into
+ * `aria-describedby`) while invalid, and **reads the control's Signal Forms
+ * validation errors automatically** — the consumer renders `messages()` (or
+ * the raw `errors()`) without any manual plumbing.
+ *
+ * Carries `role="alert"`. Drive its presence with `@if (err.shown())` (or the
+ * field's own `invalid()`); when unmounted the control's `aria-errormessage`
+ * drops automatically.
+ *
+ * @example
+ * ```html
+ * @if (err.shown()) {
+ *   <p forFieldError #err="forFieldError">{{ err.messages().join(', ') }}</p>
+ * }
+ * ```
+ */
+declare class ForFieldError {
+    protected readonly ctx: forty_cdk_core.ForFieldContext;
+    /** The control's current validation errors (Signal Forms). */
+    readonly errors: _angular_core.Signal<readonly ValidationError.WithOptionalFieldTree[]>;
+    /** Human-readable messages derived from {@link errors}. */
+    readonly messages: _angular_core.Signal<readonly string[]>;
+    /** Whether the control currently has at least one error. */
+    readonly hasErrors: _angular_core.Signal<boolean>;
+    /** Whether the error region should be shown (control invalid and has errors). */
+    readonly shown: _angular_core.Signal<boolean>;
+    constructor();
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForFieldError, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForFieldError, "[forFieldError]", ["forFieldError"], {}, {}, never, never, true, never>;
+}
+
+/**
+ * Opt-in marker that wires a non-forty-cdk control — a native `<input>`,
+ * `<textarea>`, `<select>`, or any custom element — into its surrounding
+ * `[forField]`. forty-cdk form primitives (which extend the shared form base)
+ * auto-wire and do **not** need this; it exists for plain native controls that
+ * have no primitive of their own.
+ *
+ * Validation state is consumer-driven via the `invalid` / `required` /
+ * `disabled` / `touched` inputs (native controls have no Signal Forms errors
+ * to surface). Reflects `aria-invalid` on the host.
+ *
+ * @example
+ * ```html
+ * <div forField>
+ *   <label forLabel>Email</label>
+ *   <input forFieldControl type="email" [invalid]="emailInvalid()" />
+ * </div>
+ * ```
+ */
+declare class ForFieldControl {
+    /** Marks the control invalid — drives the field's error region and `aria-invalid`. */
+    readonly invalid: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Marks the control required — reflected by the field as `data-required`. */
+    readonly required: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Marks the control disabled — reflected by the field as `data-disabled`. */
+    readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Marks the control touched — reflected by the field as `data-touched`. */
+    readonly touched: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    constructor();
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForFieldControl, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForFieldControl, "[forFieldControl]", ["forFieldControl"], { "invalid": { "alias": "invalid"; "required": false; "isSignal": true; }; "required": { "alias": "required"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "touched": { "alias": "touched"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Defaults inherited by descendant fields in the surrounding injector scope.
+ * Configure with `provideForFieldDefaults`. The shape is a stub today —
+ * present so future per-scope tuning can land without churning the public
+ * surface.
+ */
+interface ForFieldDefaults {
+}
+/** Token holding the resolved field defaults for the current scope. */
+declare const FOR_FIELD_DEFAULTS: _angular_core.InjectionToken<ForFieldDefaults>;
+/**
+ * Configures forty-cdk field defaults for this injector scope. Partial
+ * overrides inherit unspecified keys from the parent scope (or library
+ * defaults at the root).
+ */
+declare function provideForFieldDefaults(defaults?: Partial<ForFieldDefaults>): Provider[];
+
+export { FOR_FIELD_DEFAULTS, ForField, ForFieldControl, ForFieldDescription, ForFieldError, ForLabel, provideForFieldDefaults };
+export type { ForFieldDefaults };

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

@@ -0,0 +1,119 @@
+import * as _angular_core from '@angular/core';
+import { Provider } from '@angular/core';
+import * as forty_cdk_core from 'forty-cdk/core';
+import { ForFieldsetContext } from 'forty-cdk/core';
+export { FOR_FIELDSET_CONTEXT, ForFieldsetContext } from 'forty-cdk/core';
+
+/**
+ * Headless grouping container that gives a set of related fields a shared
+ * accessible name — the styleless counterpart to a native `<fieldset>` +
+ * `<legend>`, and the grouping companion to `ForField`.
+ *
+ * On a native `<fieldset>` it relies on the implicit grouping and emits no
+ * role; on any other element it emits `role="group"` + `aria-labelledby`
+ * pointing at the `[forFieldsetLegend]` (same host-tag detection idiom as
+ * `ForLabel`'s `<label>` check).
+ *
+ * The `disabled` input reflects `data-disabled` and is provided via context so
+ * descendant `ForField` controls OR it into their own disabled state — native
+ * `<fieldset disabled>` does not reach custom-role controls like `forSwitch`.
+ *
+ * @example
+ * ```html
+ * <fieldset forFieldset [disabled]="locked()">
+ *   <legend forFieldsetLegend>Shipping address</legend>
+ *   <div forField>
+ *     <label forLabel>Street</label>
+ *     <input forFieldControl />
+ *   </div>
+ * </fieldset>
+ * ```
+ */
+declare class ForFieldset implements ForFieldsetContext {
+    #private;
+    /**
+     * Whether the group is disabled, as bound by the consumer via `[disabled]`.
+     * The host reflection and descendant controls read the composed
+     * {@link disabled} signal below, which also folds in an enclosing disabled
+     * `[forFieldset]`.
+     */
+    readonly disabledInput: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * Effective disabled: the group's own `[disabled]` OR'd with an enclosing
+     * disabled `[forFieldset]`. Reflects `data-disabled`, emits the native
+     * `disabled` attribute on a `<fieldset>` (or `aria-disabled` elsewhere), and
+     * propagates to descendant controls via context — so a disabled fieldset
+     * reaches custom-role controls (`forSwitch`, `forCheckbox`, …) a native
+     * `<fieldset disabled>` can't, and nesting composes like native fieldsets
+     * (a disabled outer group cannot be re-enabled by an inner one).
+     */
+    readonly disabled: _angular_core.Signal<boolean>;
+    /** Id of the legend element; the group's `aria-labelledby` resolves here. */
+    readonly legendId: _angular_core.WritableSignal<string>;
+    /** Whether the host element is a native `<fieldset>` (no role/labelledby needed). */
+    protected readonly isNativeFieldset: _angular_core.Signal<boolean>;
+    /**
+     * Native `disabled` is reflected only on a real `<fieldset>` (where it
+     * natively disables descendant controls); a non-`<fieldset>` host advertises
+     * its disabled state via `aria-disabled` instead.
+     */
+    protected readonly nativeDisabled: _angular_core.Signal<boolean>;
+    constructor();
+    /** `role="group"` on a non-`<fieldset>` element, else null. */
+    protected readonly roleAttr: _angular_core.Signal<"group" | null>;
+    /**
+     * Resolved `aria-labelledby`: the legend id on a non-`<fieldset>` element when
+     * a legend is registered, else null (a native `<fieldset>`/`<legend>` groups
+     * implicitly and needs none).
+     */
+    protected readonly labelledBy: _angular_core.Signal<string | null>;
+    /** Mark a legend present; returns an unregister callback. */
+    registerLegend(): () => void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForFieldset, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForFieldset, "[forFieldset]", ["forFieldset"], { "disabledInput": { "alias": "disabled"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Accessible group label for a `[forFieldset]`. Inside a fieldset it adopts the
+ * fieldset's `legendId` and registers itself so the group's `aria-labelledby`
+ * resolves; on a native `<fieldset>`/`<legend>` the id is harmless extra wiring
+ * (the browser groups implicitly).
+ *
+ * Usable standalone outside a fieldset — there it is an inert marker.
+ *
+ * @example
+ * ```html
+ * <div forFieldset>
+ *   <span forFieldsetLegend>Notification preferences</span>
+ *   <!-- … fields … -->
+ * </div>
+ * ```
+ */
+declare class ForFieldsetLegend {
+    protected readonly ctx: forty_cdk_core.ForFieldsetContext | null;
+    /** The legend's id when inside a fieldset, else null. */
+    protected readonly legendId: _angular_core.Signal<string | null>;
+    constructor();
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForFieldsetLegend, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForFieldsetLegend, "[forFieldsetLegend]", ["forFieldsetLegend"], {}, {}, never, never, true, never>;
+}
+
+/**
+ * Defaults inherited by descendant fieldsets in the surrounding injector scope.
+ * Configure with `provideForFieldsetDefaults`. The shape is a stub today —
+ * present so future per-scope tuning can land without churning the public
+ * surface.
+ */
+interface ForFieldsetDefaults {
+}
+/** Token holding the resolved fieldset defaults for the current scope. */
+declare const FOR_FIELDSET_DEFAULTS: _angular_core.InjectionToken<ForFieldsetDefaults>;
+/**
+ * Configures forty-cdk fieldset defaults for this injector scope. Partial
+ * overrides inherit unspecified keys from the parent scope (or library
+ * defaults at the root).
+ */
+declare function provideForFieldsetDefaults(defaults?: Partial<ForFieldsetDefaults>): Provider[];
+
+export { FOR_FIELDSET_DEFAULTS, ForFieldset, ForFieldsetLegend, provideForFieldsetDefaults };
+export type { ForFieldsetDefaults };