forty-cdk 0.2.0 → 0.3.0

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

@@ -0,0 +1,509 @@
+import * as _angular_core from '@angular/core';
+import { InjectionToken, ModelSignal, Signal, Provider } from '@angular/core';
+import { AnchoredPositioningContext, VetoableNativeEvent, FloatingSide, FloatingAlign, VetoableEvent } from 'forty-cdk/core';
+import * as forty_cdk_popover from 'forty-cdk/popover';
+
+/**
+ * Coordination contract owned by `ForPopover`. Trigger / Content register
+ * their elements (for floating-ui positioning, dismissable-layer exemptions,
+ * and focus return). Title / Description register their generated ids so
+ * the content wires `aria-labelledby` / `aria-describedby` reactively.
+ *
+ * The popover's "openness" lives on the root directive (`open` model) and
+ * is published here so descendant pieces can react without each subscribing
+ * to the directive instance directly.
+ */
+interface ForPopoverContext extends AnchoredPositioningContext {
+    readonly open: ModelSignal<boolean>;
+    readonly disabled: Signal<boolean>;
+    readonly dismissible: Signal<boolean>;
+    readonly returnFocus: Signal<boolean>;
+    readonly initialFocus: Signal<'first' | 'container'>;
+    readonly triggerId: Signal<string>;
+    readonly contentId: Signal<string>;
+    readonly ariaLabel: Signal<string | null>;
+    /** Whether `prefers-reduced-motion: reduce` is active — reflected as `data-reduced-motion`. */
+    readonly reducedMotion: Signal<boolean>;
+    readonly labelledBy: Signal<string | null>;
+    readonly describedBy: Signal<string | null>;
+    readonly trigger: Signal<HTMLElement | null>;
+    readonly anchor: Signal<HTMLElement | null>;
+    /**
+     * Element used as the floating-ui reference. When `[forPopoverAnchor]`
+     * is registered, this is the anchor; otherwise it falls back to the
+     * trigger. Decoupled from `trigger` so the trigger can keep driving
+     * `aria-controls`, click toggle, and focus return regardless of where
+     * the popover paints.
+     */
+    readonly reference: Signal<HTMLElement | null>;
+    registerTrigger(el: HTMLElement): void;
+    unregisterTrigger(el: HTMLElement): void;
+    /** Adopts a consumer-set static `id` on the content host into `contentId`. */
+    adoptContentId(el: HTMLElement): void;
+    registerAnchor(el: HTMLElement): void;
+    unregisterAnchor(el: HTMLElement): void;
+    registerArrow(el: HTMLElement): void;
+    unregisterArrow(el: HTMLElement): void;
+    registerLabel(id: string): void;
+    unregisterLabel(id: string): void;
+    registerDescription(id: string): void;
+    unregisterDescription(id: string): void;
+    /** Toggle from a trigger click. Honours `disabled`. */
+    toggle(): void;
+    /**
+     * Escape is consumer-owned (its close differs per primitive); Content
+     * forwards the raw `KeyboardEvent` so the root emits `(escapeKeyDown)` and
+     * runs its own close decision.
+     */
+    emitEscapeKeyDown(event: KeyboardEvent): void;
+    /**
+     * Outside-interaction emit forwarders. `injectOverlayShell` builds and
+     * reuses one `VetoableNativeEvent` across the specific and composite
+     * channels, then hands it to these forwarders to fire the matching output
+     * and calls `requestClose` when un-vetoed.
+     */
+    emitPointerDownOutside(veto: VetoableNativeEvent<PointerEvent>): void;
+    emitFocusOutside(veto: VetoableNativeEvent<FocusEvent>): void;
+    emitInteractOutside(veto: VetoableNativeEvent<PointerEvent | FocusEvent>): void;
+    /** Implicit close requested by the shell after an un-vetoed outside interaction. */
+    requestClose(): void;
+    /**
+     * Hooks into the auto-focus pipeline. Content fires these just before
+     * its imperative `.focus()` (open) or the trigger return-focus (close);
+     * `event.preventDefault()` skips the move. Returns `true` when the
+     * consumer vetoed.
+     */
+    emitAutoFocusOnOpen(): boolean;
+    emitAutoFocusOnClose(): boolean;
+}
+declare const FOR_POPOVER_CONTEXT: InjectionToken<ForPopoverContext>;
+
+/**
+ * Headless implementation of the [WAI-ARIA Modeless Dialog pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/),
+ * positioned against an internal trigger via `@floating-ui/dom`.
+ *
+ * Apply `[forPopover]` on a wrapper (the trigger and the content's `@if`
+ * live inside it). The directive owns open state, ids, and the registries
+ * that wire trigger / content / title / description / arrow together.
+ *
+ * Mount/unmount of the visible content is the consumer's responsibility —
+ * wrap `[forPopoverContent]` with `@if (open())` and let `animate.enter` /
+ * `animate.leave` handle transitions:
+ *
+ * ```html
+ * <div forPopover [(open)]="isOpen">
+ *   <button forPopoverTrigger>Open</button>
+ *   @if (isOpen()) {
+ *     <div forPopoverContent animate.leave="fade-out">…</div>
+ *   }
+ * </div>
+ * ```
+ *
+ * Non-modal: focus is sent into the popover on open and returned to the
+ * trigger on close, but Tab is allowed to leave the surface (use Dialog
+ * if you need a focus trap).
+ */
+declare class ForPopover implements ForPopoverContext {
+    #private;
+    /**
+     * Two-way bindable. Whether the popover is currently shown. The `model()`
+     * change emitter (`(openChange)`) fires only on internal transitions
+     * (trigger click, Escape, outside dismissal), never on consumer writes
+     * via `[(open)]` — observe state changes without binding back.
+     */
+    readonly open: _angular_core.ModelSignal<boolean>;
+    /**
+     * Per-popover override for the side the popover is anchored to. Pair with
+     * `align` for the full positioning API (`side="bottom" align="start"`).
+     * When `undefined` (default), falls back to `ForPopoverDefaults.side` from
+     * the surrounding `provideForPopoverDefaults` scope (`'bottom'` unless
+     * configured).
+     *
+     * The input is aliased to `side`; consumers bind `[side]="..."` and read
+     * the effective value via the public `side` computed below.
+     */
+    readonly _sideInput: _angular_core.InputSignal<FloatingSide | undefined>;
+    /** Effective anchor side: the `side` input when set, else the scope default. */
+    readonly side: _angular_core.Signal<FloatingSide>;
+    /**
+     * Per-popover override for the alignment along the chosen `side`. When
+     * `undefined` (default), falls back to `ForPopoverDefaults.align` from the
+     * surrounding `provideForPopoverDefaults` scope (`'center'` unless
+     * configured).
+     *
+     * The input is aliased to `align`; consumers bind `[align]="..."` and read
+     * the effective value via the public `align` computed below.
+     */
+    readonly _alignInput: _angular_core.InputSignal<FloatingAlign | undefined>;
+    /** Effective alignment: the `align` input when set, else the scope default. */
+    readonly align: _angular_core.Signal<FloatingAlign>;
+    /**
+     * Per-popover override for the gap (px) between trigger and content along
+     * the *main* axis (perpendicular to `side`). Forwarded to floating-ui's
+     * `offset` middleware. When `undefined`
+     * (default), falls back to `ForPopoverDefaults.sideOffset` from the
+     * surrounding `provideForPopoverDefaults` scope (`8` unless configured).
+     *
+     * The input is aliased to `sideOffset`; consumers bind `[sideOffset]="..."`
+     * and read the effective value via the public `sideOffset` computed below.
+     */
+    readonly _sideOffsetInput: _angular_core.InputSignalWithTransform<number | undefined, unknown>;
+    /** Effective main-axis gap (px): the `sideOffset` input when set, else the scope default. */
+    readonly sideOffset: _angular_core.Signal<number>;
+    /** Gap (px) along the cross axis (parallel to `side`). Default `0`. */
+    readonly alignOffset: _angular_core.InputSignalWithTransform<number, unknown>;
+    /**
+     * When `true` (default), `flip` and `shift` keep the popover inside the
+     * viewport. Disable for strict positioning where overflow is acceptable.
+     */
+    readonly avoidCollisions: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * Per-popover override for the padding (px) applied uniformly to the
+     * `flip`, `shift`, and `size` middlewares. When `undefined` (default),
+     * falls back to
+     * `ForPopoverDefaults.collisionPadding` from the surrounding
+     * `provideForPopoverDefaults` scope (`8` unless configured).
+     *
+     * The input is aliased to `collisionPadding`; consumers bind
+     * `[collisionPadding]="..."` and read the effective value via the public
+     * `collisionPadding` computed below.
+     */
+    readonly _collisionPaddingInput: _angular_core.InputSignalWithTransform<number | undefined, unknown>;
+    /** Effective collision padding (px): the `collisionPadding` input when set, else the scope default. */
+    readonly collisionPadding: _angular_core.Signal<number>;
+    /**
+     * Padding (px) for the `arrow` middleware so the arrow stays inside any
+     * rounded corners on the popover content. Default `0`.
+     */
+    readonly arrowPadding: _angular_core.InputSignalWithTransform<number, unknown>;
+    /**
+     * Stickiness behaviour for `shift`. `'partial'` (default) lets the
+     * popover shift to stay visible. `'always'` disables `shift` so the
+     * popover keeps its requested placement even off-screen. `false`
+     * is treated as `'partial'`.
+     */
+    readonly sticky: _angular_core.InputSignal<false | "partial" | "always">;
+    /**
+     * When `true`, sets `data-detached=""` on the content while the trigger
+     * has scrolled off all clipping ancestors. Use to fade out popovers
+     * tied to scrolled-away triggers.
+     */
+    readonly hideWhenDetached: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * When `true` (default), the content 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 (the
+     * surface may flash briefly at the unresolved position while positioning
+     * computes).
+     */
+    readonly clipUntilPositioned: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * When true, trigger interaction is ignored and any open popover stays
+     * open until the consumer flips `open` themselves. Disable on the trigger
+     * side; the content side keeps its dismissable behavior unaffected.
+     */
+    readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * When true (default), Escape, pointer-down outside, and focus outside
+     * close the popover. Disable for confirm flows that must be answered
+     * via `[forPopoverClose]` (or by setting `open` programmatically).
+     */
+    readonly dismissible: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** When true (default), focus returns to the trigger on close. */
+    readonly returnFocus: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * Where to send focus when content mounts. `'first'` (default) finds
+     * the first focusable descendant; `'container'` focuses the content
+     * box itself (useful when there's nothing focusable inside).
+     */
+    readonly initialFocus: _angular_core.InputSignal<"first" | "container">;
+    /** Manual `aria-label` on the content. Use this when no visible title element exists. */
+    readonly ariaLabel: _angular_core.InputSignal<string | null>;
+    /**
+     * Whether the user has requested reduced motion via the OS
+     * `prefers-reduced-motion: reduce` media query. Reflected as the boolean
+     * `data-reduced-motion` attribute on the root and content so consumers can
+     * disable their own `animate.enter` / `animate.leave` and CSS transitions
+     * without re-deriving the media query. The popover toggles open / closed
+     * synchronously on trigger click, so it has no JS-coordinated timing to skip.
+     */
+    readonly reducedMotion: _angular_core.Signal<boolean>;
+    /**
+     * Fires when the user presses Escape while this popover is the topmost
+     * dismissable layer. Call `preventDefault()` on the emitted veto to
+     * suppress the automatic close. The native `KeyboardEvent` is
+     * available on `.event`.
+     */
+    readonly escapeKeyDown: _angular_core.OutputEmitterRef<VetoableNativeEvent<KeyboardEvent>>;
+    /**
+     * Fires when a pointer goes down outside the popover (and outside the
+     * trigger). Call `preventDefault()` on the veto to suppress the
+     * automatic close. The native `PointerEvent` is on `.event`.
+     */
+    readonly pointerDownOutside: _angular_core.OutputEmitterRef<VetoableNativeEvent<PointerEvent>>;
+    /**
+     * Fires when focus moves outside the popover and trigger. Call
+     * `preventDefault()` on the veto to suppress the automatic close.
+     */
+    readonly focusOutside: _angular_core.OutputEmitterRef<VetoableNativeEvent<FocusEvent>>;
+    /**
+     * Composite event: fires alongside `pointerDownOutside` and
+     * `focusOutside` and shares their veto state — `preventDefault()` on
+     * either one suppresses the automatic close.
+     */
+    readonly interactOutside: _angular_core.OutputEmitterRef<VetoableNativeEvent<PointerEvent | FocusEvent>>;
+    /**
+     * Fires just before the popover sends focus into itself on mount.
+     * Call `preventDefault()` on the veto to skip the imperative focus
+     * move — useful when opening a popover 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>;
+    readonly triggerId: _angular_core.WritableSignal<string>;
+    readonly contentId: _angular_core.WritableSignal<string>;
+    readonly trigger: _angular_core.Signal<HTMLElement | null>;
+    readonly anchor: _angular_core.Signal<HTMLElement | null>;
+    /**
+     * The element floating-ui anchors against. Prefers `[forPopoverAnchor]`
+     * when registered, otherwise falls back to the trigger so existing
+     * popovers without an anchor keep their behavior.
+     */
+    readonly reference: _angular_core.Signal<HTMLElement | null>;
+    readonly arrow: _angular_core.Signal<HTMLElement | null>;
+    readonly labelledBy: _angular_core.Signal<string | null>;
+    readonly describedBy: _angular_core.Signal<string | null>;
+    registerTrigger(el: HTMLElement): void;
+    unregisterTrigger(el: HTMLElement): void;
+    /**
+     * Adopts a consumer-set static `id` on the `[forPopoverContent]` host into
+     * `contentId` (preserving anchors / external `aria-labelledby` references)
+     * instead of letting the `[id]` host binding clobber it.
+     */
+    adoptContentId(el: HTMLElement): void;
+    registerAnchor(el: HTMLElement): void;
+    unregisterAnchor(el: HTMLElement): void;
+    registerArrow(el: HTMLElement): void;
+    unregisterArrow(el: HTMLElement): void;
+    registerLabel(id: string): void;
+    unregisterLabel(id: string): void;
+    registerDescription(id: string): void;
+    unregisterDescription(id: string): void;
+    toggle(): void;
+    emitEscapeKeyDown(event: KeyboardEvent): void;
+    /**
+     * Outside-interaction emit forwarders. The shared `#pendingOutsideVeto`
+     * reuse between the specific outside channels and the composite
+     * `interactOutside` lives in `injectOverlayShell`; these only fire the
+     * matching output with the veto the shell built.
+     */
+    emitPointerDownOutside(veto: VetoableNativeEvent<PointerEvent>): void;
+    emitFocusOutside(veto: VetoableNativeEvent<FocusEvent>): void;
+    emitInteractOutside(veto: VetoableNativeEvent<PointerEvent | FocusEvent>): void;
+    /**
+     * Implicit close requested by the shell after an un-vetoed outside
+     * interaction. The directive only owns the close itself.
+     */
+    requestClose(): void;
+    emitAutoFocusOnOpen(): boolean;
+    emitAutoFocusOnClose(): boolean;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForPopover, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForPopover, "[forPopover]", ["forPopover"], { "open": { "alias": "open"; "required": false; "isSignal": true; }; "_sideInput": { "alias": "side"; "required": false; "isSignal": true; }; "_alignInput": { "alias": "align"; "required": false; "isSignal": true; }; "_sideOffsetInput": { "alias": "sideOffset"; "required": false; "isSignal": true; }; "alignOffset": { "alias": "alignOffset"; "required": false; "isSignal": true; }; "avoidCollisions": { "alias": "avoidCollisions"; "required": false; "isSignal": true; }; "_collisionPaddingInput": { "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; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "dismissible": { "alias": "dismissible"; "required": false; "isSignal": true; }; "returnFocus": { "alias": "returnFocus"; "required": false; "isSignal": true; }; "initialFocus": { "alias": "initialFocus"; "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 popover when clicked. Apply on a focusable
+ * element — preferably a `<button>` — so keyboard users can reach it.
+ *
+ * Wires `aria-expanded`, `aria-controls`, and `aria-haspopup="dialog"`,
+ * registers the host as the floating-ui anchor, and toggles the open
+ * state on click. The trigger is exempt from the dismissable layer's
+ * outside-pointer / outside-focus checks so its own click never
+ * spuriously closes the popover.
+ *
+ * Disabling: the trigger merges its own `disabled` input OR the root's
+ * `disabled` into `effectiveDisabled`, which drives the native `disabled`
+ * attribute, `aria-disabled`, `data-disabled`, and the click guard.
+ *
+ * The root is normally resolved via DI from the enclosing `[forPopover]`.
+ * 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: `[forPopoverTrigger]="root"` with `#root="forPopover"`.
+ */
+declare class ForPopoverTrigger {
+    #private;
+    /**
+     * Optional explicit reference to the `[forPopover]` root, named after the
+     * selector `routerLink`-style. The bare valueless attribute keeps resolving
+     * the enclosing root via DI; pass the root explicitly
+     * (`[forPopoverTrigger]="root"`, with `#root="forPopover"`) 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 forPopoverTrigger: _angular_core.InputSignal<"" | ForPopoverContext>;
+    protected readonly ctx: _angular_core.Signal<ForPopoverContext>;
+    /** 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: _angular_core.Signal<boolean>;
+    constructor();
+    protected onClick(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForPopoverTrigger, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForPopoverTrigger, "[forPopoverTrigger]", ["forPopoverTrigger"], { "forPopoverTrigger": { "alias": "forPopoverTrigger"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Optional positioning anchor. When present, the popover is positioned
+ * against this element instead of `[forPopoverTrigger]` — useful when
+ * "what opens it" and "where it appears" are different elements (a button
+ * opens the popover but it's anchored to a row, a text-selection range,
+ * a cursor follower, etc.).
+ *
+ * Only positioning changes: the trigger still owns `aria-controls`,
+ * `aria-expanded`, the click toggle, and focus return on close. If no
+ * anchor is registered the popover falls back to anchoring against the
+ * trigger, so existing usages are unaffected.
+ *
+ * ```html
+ * <div forPopover [(open)]="open">
+ *   <button forPopoverTrigger>Help</button>
+ *   <span [forPopoverAnchor]>Anchored phrase</span>
+ *   @if (open()) {
+ *     <div forPopoverContent>…</div>
+ *   }
+ * </div>
+ * ```
+ */
+declare class ForPopoverAnchor {
+    #private;
+    constructor();
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForPopoverAnchor, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForPopoverAnchor, "[forPopoverAnchor]", ["forPopoverAnchor"], {}, {}, never, never, true, never>;
+}
+
+/**
+ * The popover surface. Carries `role="dialog"` (non-modal — `aria-modal` is absent per APG), is
+ * portaled to `document.body`, and is positioned by `@floating-ui/dom`
+ * against the registered `[forPopoverTrigger]`.
+ *
+ * The directive does not manage DOM presence — wrap with
+ * `@if (popoverOpen())` so `animate.enter` / `animate.leave` fire on
+ * the natural mount / unmount cycle. While mounted the directive
+ * activates a `DismissableLayer` (Escape, pointer-down outside, focus
+ * outside) and sends focus to the configured `initialFocus` target;
+ * on unmount it returns focus to the trigger if `returnFocus` is on.
+ *
+ * The trigger is exempt from the layer's outside checks, so clicking
+ * it again just toggles via the trigger directive — no double-close
+ * race.
+ *
+ * The lifecycle (positioner + dismissable layer + initial focus + return
+ * focus) is owned by the shared `injectOverlayShell` helper. The shell's
+ * `'first'` mode routes through the same `findFirstFocusable` helper used
+ * by `FocusTrap`, dropping the local focusable-selector copy that this
+ * directive carried before (see #107).
+ */
+declare class ForPopoverContent {
+    protected readonly ctx: forty_cdk_popover.ForPopoverContext;
+    constructor();
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForPopoverContent, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForPopoverContent, "[forPopoverContent]", ["forPopoverContent"], {}, {}, never, never, true, never>;
+}
+
+/**
+ * Convenience: gives the host element a stable id and registers it as the
+ * popover's accessible name (`aria-labelledby`). Apply on a heading element
+ * (`<h2>`, `<h3>`...) inside `[forPopoverContent]`.
+ *
+ * If you don't render a visible title, omit this and pass `ariaLabel` on
+ * the popover root instead.
+ */
+declare class ForPopoverTitle {
+    protected readonly id: _angular_core.Signal<string>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForPopoverTitle, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForPopoverTitle, "[forPopoverTitle]", ["forPopoverTitle"], {}, {}, never, never, true, never>;
+}
+
+/**
+ * Convenience: gives the host element a stable id and registers it as the
+ * popover's accessible description (`aria-describedby`). Apply on a paragraph
+ * or similar text element inside `[forPopoverContent]`.
+ */
+declare class ForPopoverDescription {
+    protected readonly id: _angular_core.Signal<string>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForPopoverDescription, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForPopoverDescription, "[forPopoverDescription]", ["forPopoverDescription"], {}, {}, never, never, true, never>;
+}
+
+/**
+ * Button that closes the surrounding popover when clicked. Apply on a
+ * `<button>` inside `[forPopoverContent]`. Bypasses `dismissible` — an
+ * explicit close button is always honored.
+ */
+declare class ForPopoverClose {
+    #private;
+    protected onClick(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForPopoverClose, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForPopoverClose, "[forPopoverClose]", ["forPopoverClose"], {}, {}, never, never, true, never>;
+}
+
+/**
+ * Optional visual arrow inside `ForPopoverContent`. Registers itself with
+ * the popover context so floating-ui's `arrow` middleware can position it
+ * along the surface edge that points at the trigger. Style size and color
+ * yourself — the directive only sets `position`, `left`/`top`, and the
+ * opposite-side offset.
+ */
+declare class ForPopoverArrow {
+    #private;
+    constructor();
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForPopoverArrow, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForPopoverArrow, "[forPopoverArrow]", ["forPopoverArrow"], {}, {}, never, never, true, never>;
+}
+
+/**
+ * Defaults inherited by descendant popovers in the surrounding injector
+ * scope. Configure with `provideForPopoverDefaults` at the app root or in
+ * any component's `providers`; partial overrides merge with the parent scope.
+ */
+interface ForPopoverDefaults {
+    /**
+     * Side the popover is anchored to for popovers that don't override `side`
+     * locally. Library fallback `'bottom'`.
+     */
+    side: FloatingSide;
+    /**
+     * Alignment along the chosen `side` for popovers that don't override
+     * `align` locally. Library fallback `'center'`.
+     */
+    align: FloatingAlign;
+    /**
+     * Gap (px) between trigger and content along the main axis for popovers
+     * that don't override `sideOffset` locally.
+     * Library fallback `8`.
+     */
+    sideOffset: number;
+    /**
+     * Padding (px) applied uniformly to the `flip`, `shift`, and `size`
+     * middlewares for popovers that don't override `collisionPadding` locally.
+     * Library fallback `8`.
+     */
+    collisionPadding: number;
+}
+/** Token holding the resolved popover defaults for the current scope. */
+declare const FOR_POPOVER_DEFAULTS: _angular_core.InjectionToken<ForPopoverDefaults>;
+/**
+ * Configures forty-cdk popover defaults for this injector scope. Partial
+ * overrides inherit unspecified keys from the parent scope (or library
+ * defaults at the root).
+ */
+declare function provideForPopoverDefaults(defaults?: Partial<ForPopoverDefaults>): Provider[];
+
+export { FOR_POPOVER_CONTEXT, FOR_POPOVER_DEFAULTS, ForPopover, ForPopoverAnchor, ForPopoverArrow, ForPopoverClose, ForPopoverContent, ForPopoverDescription, ForPopoverTitle, ForPopoverTrigger, provideForPopoverDefaults };
+export type { ForPopoverContext, ForPopoverDefaults };

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

@@ -0,0 +1,143 @@
+import * as _angular_core from '@angular/core';
+import { InjectionToken, Signal, Provider } from '@angular/core';
+import * as forty_cdk_progress from 'forty-cdk/progress';
+
+/** State of a progress bar reflected on `data-state`. */
+type ForProgressState = 'indeterminate' | 'loading' | 'complete';
+/** Shape exposed to descendant pieces (the indicator). */
+interface ForProgressContext {
+    /** Raw value as written by the consumer, or `null` when indeterminate. */
+    readonly value: Signal<number | null>;
+    /** Value clamped to `[0, max]`, or `null` when indeterminate. Use this for any visual / ARIA reflection. */
+    readonly clampedValue: Signal<number | null>;
+    /** Current max. */
+    readonly max: Signal<number>;
+    /** `null` when indeterminate; otherwise `0..100`. */
+    readonly percentage: Signal<number | null>;
+    /**
+     * {@link percentage} rounded to two decimals for the `data-percentage`
+     * reflection, or `null` when indeterminate. Owned by the root so the
+     * indicator mirrors it instead of re-implementing the rounding.
+     */
+    readonly percentageAttr: Signal<number | null>;
+    /** Logical state, mirrored on `data-state`. */
+    readonly state: Signal<ForProgressState>;
+}
+declare const FOR_PROGRESS_CONTEXT: InjectionToken<ForProgressContext>;
+
+/**
+ * Headless progress bar. Implements the
+ * [WAI-ARIA progressbar role](https://www.w3.org/TR/wai-aria-1.2/#progressbar)
+ * for tasks whose completion is communicated visually.
+ *
+ * `value === null` puts the bar in **indeterminate** mode (no `aria-valuenow`).
+ * Use it for "loading…" states whose duration cannot be predicted. Otherwise
+ * pass a number in `[0, max]`; values outside the range are clamped before
+ * being reflected.
+ *
+ * The directive only handles state and ARIA. The visual fill is up to the
+ * consumer — see `ForProgressIndicator`.
+ *
+ * @example
+ * ```html
+ * <div forProgress [value]="uploaded()" [max]="total()">
+ *   <div forProgressIndicator></div>
+ * </div>
+ *
+ * <div forProgress [value]="null">  <!-- indeterminate -->
+ *   <div forProgressIndicator></div>
+ * </div>
+ * ```
+ */
+declare class ForProgress implements ForProgressContext {
+    #private;
+    /**
+     * Two-way bindable. Current progress in `[0, max]`, or `null` for the
+     * indeterminate state. Values outside the range are clamped for ARIA but
+     * the model retains what the consumer wrote.
+     */
+    readonly value: _angular_core.ModelSignal<number | null>;
+    /** Maximum value. Defaults to `100` (so a raw value reads as a percentage). */
+    readonly max: _angular_core.InputSignal<number>;
+    /**
+     * `max` clamped to a strictly positive value. `progressbar` requires
+     * `aria-valuemax` to exceed `aria-valuemin` (which is fixed at `0` here), so a
+     * non-positive `max` would reflect invalid ARIA. Mirrors the way `ForMeter`
+     * keeps `max >= min`; here the floor is `1` so the reflected range is always
+     * valid and the percentage math has a non-zero denominator.
+     */
+    readonly effectiveMax: _angular_core.Signal<number>;
+    /**
+     * Optional override for `aria-valuetext`. Useful for non-percentage
+     * progress (e.g. `"Step 3 of 5"`, `"42 MB of 200 MB"`). Receives the
+     * clamped value and current max.
+     */
+    readonly getValueLabel: _angular_core.InputSignal<((value: number, max: number) => string) | null>;
+    /**
+     * When true, transitions to `value === max` are announced once via the
+     * live announcer using the current `aria-valuetext` (or `"Complete"` if
+     * none). Repeated transitions to the same complete state do not re-fire.
+     * The default is read from `provideForProgressDefaults` for the
+     * surrounding scope.
+     */
+    readonly announceCompletion: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    readonly clampedValue: _angular_core.Signal<number | null>;
+    readonly percentage: _angular_core.Signal<number | null>;
+    readonly state: _angular_core.Signal<ForProgressState>;
+    readonly ariaValueText: _angular_core.Signal<string | null>;
+    readonly percentageAttr: _angular_core.Signal<number | null>;
+    constructor();
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForProgress, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForProgress, "[forProgress]", ["forProgress"], { "value": { "alias": "value"; "required": false; "isSignal": true; }; "max": { "alias": "max"; "required": false; "isSignal": true; }; "getValueLabel": { "alias": "getValueLabel"; "required": false; "isSignal": true; }; "announceCompletion": { "alias": "announceCompletion"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; }, never, never, true, never>;
+}
+
+/**
+ * Visual fill paired with `[forProgress]`. Reflects `data-state` and
+ * `data-percentage` so the consumer can drive width / transform from CSS.
+ *
+ * The directive does NOT set any visual style itself. Typical usage:
+ *
+ * ```css
+ * [forProgressIndicator] {
+ *   width: 100%;
+ *   transform: translateX(calc(-100% + var(--for-progress-percentage, 0%)));
+ * }
+ * [forProgressIndicator][data-state="indeterminate"] {
+ *   animation: stripes 1s infinite linear;
+ * }
+ * ```
+ *
+ * with the `--for-progress-percentage` custom property fed from `data-percentage`.
+ */
+declare class ForProgressIndicator {
+    protected readonly context: forty_cdk_progress.ForProgressContext;
+    protected percentageStyle(): string | null;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForProgressIndicator, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForProgressIndicator, "[forProgressIndicator]", ["forProgressIndicator"], {}, {}, never, never, true, never>;
+}
+
+/**
+ * Defaults inherited by descendant progress bars in the surrounding injector
+ * scope. Configure with `provideForProgressDefaults` either at the
+ * application root or in any component's `providers` array; partial
+ * overrides merge with the parent scope.
+ */
+interface ForProgressDefaults {
+    /**
+     * Whether to announce `Complete` (or the label) once via `aria-live` on
+     * the loading→complete transition. Opt-in — useful on flows where the
+     * user explicitly waits for completion (uploads, submissions).
+     */
+    announceCompletion: boolean;
+}
+/** Token holding the resolved progress defaults for the current scope. */
+declare const FOR_PROGRESS_DEFAULTS: _angular_core.InjectionToken<ForProgressDefaults>;
+/**
+ * Configures forty-cdk progress defaults for this injector scope. Partial
+ * overrides inherit unspecified keys from the parent scope (or library
+ * defaults at the root).
+ */
+declare function provideForProgressDefaults(defaults?: Partial<ForProgressDefaults>): Provider[];
+
+export { FOR_PROGRESS_CONTEXT, FOR_PROGRESS_DEFAULTS, ForProgress, ForProgressIndicator, provideForProgressDefaults };
+export type { ForProgressContext, ForProgressDefaults, ForProgressState };