forty-cdk 0.2.0 → 0.3.0

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

@@ -0,0 +1,871 @@
+import * as _angular_core from '@angular/core';
+import { InjectionToken, Signal, Type, Injector, Provider } from '@angular/core';
+import { ForDrawerSide, VetoableEvent, VetoableNativeEvent, OverlayRef, OverlayManagerEntry, OverlayManagerCore } from 'forty-cdk/core';
+export { ForDrawerSide } from 'forty-cdk/core';
+import * as forty_cdk_drawer from 'forty-cdk/drawer';
+
+/**
+ * A snap point. Three accepted shapes:
+ *
+ * - `number ∈ [0, 1]` — fraction of the dimension along the dismissal axis.
+ * - `'NN%'` — equivalent to a fraction, e.g. `'50%' === 0.5`.
+ * - `'NNpx'` — absolute pixel size measured from the anchored edge.
+ */
+type ForDrawerSnapPoint = number | `${number}%` | `${number}px`;
+/**
+ * Reasons emitted via the `(dismiss)` output. A single drawer instance can
+ * cycle through any of these — the consumer typically just flips its
+ * `@if`-gating signal off, but may choose to skip the unmount on specific
+ * reasons (e.g. ignore `'pointerDownOutside'` for a sticky drawer).
+ */
+type ForDrawerCloseReason = 'escape' | 'backdrop' | 'pointerDownOutside' | 'focusOutside' | 'closeButton' | 'swipe' | 'programmatic';
+/**
+ * Coordination contract owned by `ForDrawer` (declarative) or by the
+ * `ForDrawerManager.open()` machinery (programmatic). Title / Description
+ * register their generated ids so the drawer wires `aria-labelledby` /
+ * `aria-describedby` reactively. Backdrop, Close button and Handle hook
+ * into the same surface to request close / register themselves.
+ *
+ * The drawer's "openness" isn't part of this contract: the directive is
+ * mounted iff the drawer is open, so descendants don't need an open
+ * signal to coordinate.
+ */
+interface ForDrawerContext {
+    readonly dismissible: Signal<boolean>;
+    readonly modal: Signal<boolean>;
+    readonly alert: Signal<boolean>;
+    readonly side: Signal<ForDrawerSide>;
+    readonly activeSnapPoint: Signal<ForDrawerSnapPoint | null>;
+    /**
+     * Whether the backdrop should reflect `data-fade-from-active`. True
+     * when `fadeFromIndex` is set and the active snap point is at or past
+     * that index. Computed by the root.
+     */
+    readonly fadeFromActive: Signal<boolean>;
+    /**
+     * `true` while a pointer drag gesture is in flight. Mirrors the host's
+     * `data-dragging` attribute so pieces portaled away from the surface
+     * (the backdrop) can suppress their own transitions during the gesture.
+     */
+    readonly dragging: Signal<boolean>;
+    /**
+     * Progress of the current drag *toward the anchored edge* (dismiss
+     * direction), as a fraction `∈ [0, 1]` of the drawer's dimension along
+     * the dismissal axis. `0` at rest and while growing away from the edge
+     * (with snap points). The backdrop publishes this as the
+     * `--for-drawer-drag-progress` custom property so consumers can fade it
+     * out as the surface is dragged off-screen — `opacity: calc(1 - var(--for-drawer-drag-progress))`.
+     */
+    readonly dragProgress: Signal<number>;
+    readonly labelledBy: Signal<string | null>;
+    readonly describedBy: Signal<string | null>;
+    /**
+     * Portal target shared with the backdrop so both resolve the same
+     * container. `null` ⇒ `document.body`. Set via the drawer's `container`
+     * input; read once per mount.
+     */
+    readonly container: Signal<HTMLElement | null>;
+    /**
+     * Host element of the drawer surface. Exposed so a nested child can
+     * register its parent topology with `ForDrawerStack` without piercing
+     * Angular DI to fetch the parent's `ElementRef`. Read-only — pieces
+     * never mutate the host directly.
+     */
+    readonly hostElement: HTMLElement;
+    registerLabel(id: string): void;
+    unregisterLabel(id: string): void;
+    registerDescription(id: string): void;
+    unregisterDescription(id: string): void;
+    /**
+     * Register the visual handle element so that `handleOnly === true`
+     * gates the swipe gesture to gestures starting on this element. Pass
+     * `null` to unregister.
+     */
+    registerHandle(el: HTMLElement | null): void;
+    /**
+     * Register the backdrop element so the dismissable layer treats it as
+     * part of the drawer surface (`exemptElements`) — without this, a
+     * `pointerdown` on the portaled backdrop would fire `pointerDownOutside`
+     * before the backdrop's `click` handler runs, so the consumer would see
+     * close-reason `'pointerDownOutside'` instead of `'backdrop'` (WebKit
+     * was the first to surface this; Chromium happened to dispatch the
+     * events in an order that masked it). Pass `null` to unregister.
+     */
+    registerBackdrop(el: HTMLElement | null): void;
+    /**
+     * Request that the drawer close. Reasons:
+     * - `'escape'` / `'backdrop'` / `'pointerDownOutside'` / `'focusOutside'` /
+     *   `'swipe'`: honored only when `dismissible()` is true.
+     * - `'closeButton'`: always honored.
+     * - `'programmatic'`: always honored, used by `ForDrawerManager.open()`
+     *   consumers that drive close imperatively from a child component.
+     *
+     * `value` is the close result, propagated to `ForDrawerRef.close(value)`
+     * in programmatic mode. Ignored in declarative mode.
+     */
+    requestClose(reason: ForDrawerCloseReason, value?: unknown): void;
+}
+declare const FOR_DRAWER_CONTEXT: InjectionToken<ForDrawerContext>;
+/**
+ * Drag/release event payloads. Surfaced through `(dragMove)` / `(release)`
+ * so consumers can drive bespoke visualizations (e.g. a separate "scaled
+ * background" effect, a debug HUD); the directive itself owns transform
+ * application and snap resolution.
+ */
+interface ForDrawerDragEvent {
+    readonly percentageDragged: number;
+    readonly originalEvent: PointerEvent;
+}
+interface ForDrawerReleaseEvent {
+    readonly willClose: boolean;
+    readonly nextSnapPoint: ForDrawerSnapPoint | null;
+    readonly originalEvent: PointerEvent;
+}
+
+/**
+ * Headless implementation of the [WAI-ARIA Modal Dialog pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/),
+ * specialised as a side / bottom-sheet drawer with optional swipe-to-dismiss
+ * and snap points.
+ *
+ * Apply `[forDrawer]` on the drawer surface itself — not on a wrapper. The
+ * directive moves the host to `document.body` (portal), traps focus, locks
+ * body scroll, listens for Escape, and (when `swipeToDismiss` is on) attaches
+ * pointer-based swipe handlers that translate the surface and resolve to the
+ * nearest snap point or a dismiss on release. `aria-labelledby` and
+ * `aria-describedby` wire automatically via `[forDrawerTitle]` /
+ * `[forDrawerDescription]`; pass `ariaLabel` instead if you don't render
+ * a visible title.
+ *
+ * Mount/unmount is the consumer's responsibility — the directive does not
+ * manage `[hidden]`. Wrap with `@if (open())` and let `animate.enter` /
+ * `animate.leave` handle transitions.
+ *
+ * For programmatic use (open arbitrary components imperatively, manage
+ * lifecycle externally), see `ForDrawerManager.open()`.
+ */
+declare class ForDrawer implements ForDrawerContext {
+    #private;
+    /**
+     * Edge the drawer is anchored to. Default `'bottom'` — the most common
+     * mobile-first pattern. The keyboard navigation axis (for swipe direction)
+     * derives from this, as does the `data-side` attribute on the host.
+     */
+    readonly side: _angular_core.InputSignal<ForDrawerSide>;
+    /**
+     * When true (default), Escape, backdrop click, pointer-down outside,
+     * focus outside, and a swipe past the close threshold all emit `(dismiss)`.
+     * Disable for confirm flows that must be answered explicitly.
+     */
+    readonly dismissible: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * When true (default), sets `aria-modal="true"`, locks body scroll, traps
+     * focus, and inerts body siblings. Set to `false` for a non-modal
+     * navigation drawer that coexists with the rest of the page.
+     */
+    readonly modal: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** When true, role becomes `alertdialog` (interrupts assistive tech). */
+    readonly alert: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** When true (default), focus returns to the previously focused element on close. */
+    readonly returnFocus: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * Where to send focus on mount. `'first'` (default) finds the first
+     * focusable descendant; `'container'` focuses the drawer surface itself
+     * (useful when there's nothing focusable inside).
+     */
+    readonly initialFocus: _angular_core.InputSignal<"first" | "container">;
+    /** Manual `aria-label`. Use this when no visible title element exists. */
+    readonly ariaLabel: _angular_core.InputSignal<string | null>;
+    /**
+     * Portal target for the surface. Defaults to `document.body`. Pass a
+     * positioned (`position: relative`) container — paired with
+     * `[modal]="false"` — for a drawer scoped to a region instead of the
+     * viewport. Read once at mount (the portal moves the host once); changing
+     * it after open has no effect. The backdrop portals to the same container.
+     */
+    readonly container: _angular_core.InputSignal<HTMLElement | null>;
+    /**
+     * Callback invoked just before focus moves into the drawer on mount.
+     * `event.preventDefault()` skips the imperative move (Tab cycling and
+     * return-focus capture still wire up). See Dialog for the same shape and
+     * the rationale for `input<>` rather than `output<>` on free-floating
+     * overlays.
+     */
+    readonly autoFocusOnOpen: _angular_core.InputSignal<((event: VetoableEvent) => void) | undefined>;
+    /**
+     * Callback invoked just before focus returns to the previously focused
+     * element on unmount. `event.preventDefault()` skips the return-focus.
+     */
+    readonly autoFocusOnClose: _angular_core.InputSignal<((event: VetoableEvent) => void) | undefined>;
+    /** When true (default), swipe toward the anchored edge dismisses past `closeThreshold`. */
+    readonly swipeToDismiss: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * Fraction past which a release dismisses instead of snapping back.
+     * Default `0.25`. Without `snapPoints` it is a fraction of the
+     * full drawer dimension along the dismissal axis (dragged > 25% of the
+     * surface size toward the edge dismisses); with `snapPoints` it is a
+     * fraction of the **lowest snap's** extent, so a small "peek" snap stays
+     * dismissable without dragging it entirely off-screen.
+     */
+    readonly closeThreshold: _angular_core.InputSignal<number>;
+    /**
+     * When true, the swipe gesture only arms on a pointerdown that started on
+     * the registered `[forDrawerHandle]` element. Useful when the surface
+     * contains scrollable content that should keep its scroll gesture.
+     */
+    readonly handleOnly: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * When true, asks the registered `[forDrawerWrapper]` to scale and
+     * translate behind this drawer (the "scale background" effect). No
+     * effect under `prefers-reduced-motion: reduce`, and a no-op if no
+     * wrapper is mounted. Default `false` so existing consumers are
+     * untouched.
+     */
+    readonly scaleBackground: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * When true (default) and `scaleBackground` is active, paints
+     * `<body>` with `scaleBackgroundColor` so the gap between the scaled
+     * wrapper and the viewport edge does not show through. Only applies
+     * when `scaleBackground` is `true`.
+     */
+    readonly setBackgroundColorOnScale: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * Snap points: each entry is a `number ∈ [0, 1]`,
+     * a `'NN%'` string, or a `'NNpx'` string. Strictly increasing
+     * (closest-to-edge first). The surface settles at the nearest snap on
+     * release; dragging past the lowest snap by `closeThreshold` of that
+     * snap's own extent dismisses.
+     */
+    readonly snapPoints: _angular_core.InputSignal<readonly ForDrawerSnapPoint[] | undefined>;
+    /**
+     * Active snap point. Two-way bindable: write via `[(activeSnapPoint)]`
+     * to drive the surface programmatically, or just read for analytics.
+     * Initialised to `snapPoints?.[0]` on mount when the consumer left it
+     * `null`. The implicit `(activeSnapPointChange)` emitter fires on
+     * internal transitions (mount-time default and drag release), and
+     * stays silent on consumer writes through `[(activeSnapPoint)]`.
+     */
+    readonly activeSnapPoint: _angular_core.ModelSignal<ForDrawerSnapPoint | null>;
+    /**
+     * First index of `snapPoints` from which the backdrop should reflect
+     * `data-fade-from-active`. Consumers tie a CSS opacity transition to
+     * that attribute. Out-of-range values throw on mount.
+     */
+    readonly fadeFromIndex: _angular_core.InputSignal<number | undefined>;
+    /**
+     * Emitted when the drawer wants to close. Consumer wires this to flip
+     * the signal that gates the surrounding `@if`.
+     */
+    readonly dismiss: _angular_core.OutputEmitterRef<ForDrawerCloseReason>;
+    /** Vetoable Escape. `preventDefault()` suppresses the auto `(dismiss)`. */
+    readonly escapeKeyDown: _angular_core.OutputEmitterRef<VetoableNativeEvent<KeyboardEvent>>;
+    /** Vetoable pointer-down outside. `preventDefault()` suppresses the auto `(dismiss)`. */
+    readonly pointerDownOutside: _angular_core.OutputEmitterRef<VetoableNativeEvent<PointerEvent>>;
+    /** Vetoable focus-outside. `preventDefault()` suppresses the auto `(dismiss)`. */
+    readonly focusOutside: _angular_core.OutputEmitterRef<VetoableNativeEvent<FocusEvent>>;
+    /**
+     * Composite event: fires alongside `pointerDownOutside` and `focusOutside`
+     * and shares their veto state — `preventDefault()` on either suppresses
+     * the auto `(dismiss)`.
+     */
+    readonly interactOutside: _angular_core.OutputEmitterRef<VetoableNativeEvent<PointerEvent | FocusEvent>>;
+    /** Drag stream. `percentageDragged` ∈ `[0, 1]`. */
+    readonly dragMove: _angular_core.OutputEmitterRef<ForDrawerDragEvent>;
+    /** Release event. The directive has already updated `activeSnapPoint` / requested close. */
+    readonly release: _angular_core.OutputEmitterRef<ForDrawerReleaseEvent>;
+    readonly labelledBy: _angular_core.Signal<string | null>;
+    readonly describedBy: _angular_core.Signal<string | null>;
+    readonly activeSnapPointAttr: _angular_core.Signal<string | null>;
+    readonly fadeFromActive: _angular_core.Signal<boolean>;
+    /**
+     * `true` while a pointer drag gesture is in flight. Mirrors the host's
+     * `data-dragging` attribute; surfaced through `ForDrawerContext` so pieces
+     * portaled away from the surface (the backdrop) can suppress their own
+     * transitions during the gesture.
+     */
+    readonly dragging: _angular_core.Signal<boolean>;
+    /**
+     * Progress of the current drag toward the anchored edge, `∈ [0, 1]`.
+     * Surfaced through `ForDrawerContext` so the backdrop can publish it as the
+     * `--for-drawer-drag-progress` custom property.
+     */
+    readonly dragProgress: _angular_core.Signal<number>;
+    /**
+     * Live drag displacement as a CSS `translate` value (`"<x> <y>"`),
+     * published on the host as the `--for-drawer-translate` custom property by
+     * the gesture engine. The consumer composes it on the surface with
+     * `translate: var(--for-drawer-translate, 0px 0px)`.
+     *
+     * A **custom property** is used (rather than writing `translate` /
+     * `transform` directly) because `transform` is reserved for
+     * `ForDrawerScaleCoordinator` and a directly-written inline `translate` is
+     * dropped by Angular when the consumer also binds a template `[style.*]` on
+     * the same host. `"0px 0px"` at rest; the write rides the same change-
+     * detection pass as the `data-dragging` / `data-active-snap-point` changes
+     * on release so the consumer's `transition: translate` animates back in
+     * lockstep with the snap transition rather than jumping to the old rest
+     * position first.
+     */
+    readonly dragTranslate: _angular_core.Signal<string>;
+    /** Host element of this drawer surface — exposed via `ForDrawerContext`. */
+    get hostElement(): HTMLElement;
+    readonly depthAttr: _angular_core.Signal<string>;
+    /**
+     * `true` while at least one descendant `[forDrawer]` is registered with
+     * `ForDrawerStack` underneath this one — reflected as
+     * `data-state-nested="true"`. The actual nested-visual transform
+     * (`scale + translate3d`) on the parent surface is owned by
+     * `ForDrawerScaleCoordinator`, which subscribes to the same stack
+     * signal and applies the inline `style.transform` once per affected
+     * host. The check is one-level (direct child) because the visual
+     * contract only cares about whether *some* child is currently covering
+     * this drawer; deeper descendants cascade naturally through their own
+     * ancestor chain.
+     */
+    readonly hasChild: _angular_core.Signal<boolean>;
+    /**
+     * Reflected as `data-scale-background` on the host: `true` when the
+     * directive opted into the effect AND the coordinator is currently
+     * applying it (wrapper registered, not under reduced-motion). Lets
+     * consumers style the drawer differently in scale mode (e.g. larger
+     * corner radii) without polling the coordinator.
+     */
+    readonly scaleBackgroundActive: _angular_core.Signal<boolean>;
+    constructor();
+    registerLabel(id: string): void;
+    unregisterLabel(id: string): void;
+    registerDescription(id: string): void;
+    unregisterDescription(id: string): void;
+    registerHandle(el: HTMLElement | null): void;
+    registerBackdrop(el: HTMLElement | null): void;
+    requestClose(reason: ForDrawerCloseReason, value?: unknown): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForDrawer, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForDrawer, "[forDrawer]", ["forDrawer"], { "side": { "alias": "side"; "required": false; "isSignal": true; }; "dismissible": { "alias": "dismissible"; "required": false; "isSignal": true; }; "modal": { "alias": "modal"; "required": false; "isSignal": true; }; "alert": { "alias": "alert"; "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; }; "container": { "alias": "container"; "required": false; "isSignal": true; }; "autoFocusOnOpen": { "alias": "autoFocusOnOpen"; "required": false; "isSignal": true; }; "autoFocusOnClose": { "alias": "autoFocusOnClose"; "required": false; "isSignal": true; }; "swipeToDismiss": { "alias": "swipeToDismiss"; "required": false; "isSignal": true; }; "closeThreshold": { "alias": "closeThreshold"; "required": false; "isSignal": true; }; "handleOnly": { "alias": "handleOnly"; "required": false; "isSignal": true; }; "scaleBackground": { "alias": "scaleBackground"; "required": false; "isSignal": true; }; "setBackgroundColorOnScale": { "alias": "setBackgroundColorOnScale"; "required": false; "isSignal": true; }; "snapPoints": { "alias": "snapPoints"; "required": false; "isSignal": true; }; "activeSnapPoint": { "alias": "activeSnapPoint"; "required": false; "isSignal": true; }; "fadeFromIndex": { "alias": "fadeFromIndex"; "required": false; "isSignal": true; }; }, { "activeSnapPoint": "activeSnapPointChange"; "dismiss": "dismiss"; "escapeKeyDown": "escapeKeyDown"; "pointerDownOutside": "pointerDownOutside"; "focusOutside": "focusOutside"; "interactOutside": "interactOutside"; "dragMove": "dragMove"; "release": "release"; }, never, never, true, never>;
+}
+
+/**
+ * Button that toggles the drawer when clicked. Apply on a focusable element —
+ * preferably a `<button>` — so keyboard users can reach it.
+ *
+ * Wires `aria-haspopup="dialog"`, `aria-expanded`, `aria-controls`, and
+ * `data-state` on the host. Two-way bind `[(open)]` to the same signal that
+ * gates the surrounding `@if` around `[forDrawer]`. Focus return is owned
+ * by `[forDrawer]` (modal mode captures the previously-focused element on
+ * mount and restores it on destroy).
+ *
+ * ```html
+ * <button forDrawerTrigger [(open)]="drawerOpen" controls="my-drawer">Open</button>
+ * @if (drawerOpen()) {
+ *   <div forDrawer id="my-drawer" (dismiss)="drawerOpen.set(false)">…</div>
+ * }
+ * ```
+ */
+declare class ForDrawerTrigger {
+    #private;
+    /**
+     * Two-way bindable. Bind to the same signal that gates the surrounding
+     * `@if` around `[forDrawer]`. The `model()` change emitter
+     * (`(openChange)`) fires only on internal transitions (trigger click).
+     */
+    readonly open: _angular_core.ModelSignal<boolean>;
+    /**
+     * Id of the controlled drawer surface. Mirrored to `aria-controls` while
+     * the drawer is open. The consumer is responsible for setting the same
+     * `id` on `[forDrawer]`.
+     */
+    readonly controls: _angular_core.InputSignal<string | null>;
+    /**
+     * When true, click is ignored and the host reflects `data-disabled=""`,
+     * `aria-disabled="true"`, and the native `disabled` attribute so the
+     * trigger is announced as disabled by assistive tech and dropped from
+     * the tab order.
+     */
+    readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    constructor();
+    protected onClick(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForDrawerTrigger, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForDrawerTrigger, "[forDrawerTrigger]", ["forDrawerTrigger"], { "open": { "alias": "open"; "required": false; "isSignal": true; }; "controls": { "alias": "controls"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; }, { "open": "openChange"; }, never, never, true, never>;
+}
+
+/**
+ * Optional backdrop overlay. Portaled to `document.body` so it sits
+ * underneath the drawer regardless of where it's declared. While mounted
+ * the backdrop is visible; mount/unmount it alongside the drawer with the
+ * same `@if` so `animate.enter` / `animate.leave` works on both.
+ *
+ * Reflects `data-fade-from-active` when `fadeFromIndex` on the drawer root
+ * is set and the active snap point is at or past that index — consumers
+ * tie this to a CSS opacity transition for the "backdrop fades
+ * in once you snap up past N" effect.
+ *
+ * Publishes the live drag progress toward the anchored edge as the
+ * `--for-drawer-drag-progress` custom property (`0` at rest → `1` fully
+ * dragged off-screen) and mirrors the surface's `data-dragging` attribute.
+ * Together these drive the "backdrop fades out as you swipe to
+ * dismiss" effect with pure CSS:
+ *
+ * ```css
+ * [forDrawerBackdrop] {
+ *   opacity: calc(1 - var(--for-drawer-drag-progress, 0));
+ *   transition: opacity 0.3s ease;
+ * }
+ * [forDrawerBackdrop][data-dragging] {
+ *   transition: none; \/* track the pointer 1:1 *\/
+ * }
+ * ```
+ *
+ * The directive applies no visual styles itself.
+ */
+declare class ForDrawerBackdrop {
+    #private;
+    protected readonly ctx: forty_cdk_drawer.ForDrawerContext;
+    /**
+     * Per-instance drawer id when opened through `ForDrawerManager` (reflected
+     * as `data-for-drawer-id` so the manager can pair this portaled backdrop
+     * with its drawer and drive its exit animation). `null` in the declarative
+     * path, where the host binding emits no attribute.
+     */
+    protected readonly instanceId: string | null;
+    constructor();
+    protected onClick(event: MouseEvent): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForDrawerBackdrop, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForDrawerBackdrop, "[forDrawerBackdrop]", ["forDrawerBackdrop"], {}, {}, never, never, true, never>;
+}
+
+/**
+ * Visual swipe handle (the "grabber" pill at the top of a bottom sheet).
+ * Registers itself with the drawer so that `[handleOnly]="true"` can scope
+ * the swipe gesture to gestures starting on this element. Reflects
+ * `aria-hidden="true"` because the handle is a decorative styling target —
+ * keyboard users dismiss via Escape / a `[forDrawerClose]` button.
+ *
+ * Apply on the visual handle element. Applies no styles itself; the
+ * consumer is responsible for sizing, positioning, and color.
+ */
+declare class ForDrawerHandle {
+    #private;
+    constructor();
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForDrawerHandle, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForDrawerHandle, "[forDrawerHandle]", ["forDrawerHandle"], {}, {}, never, never, true, never>;
+}
+
+/**
+ * Convenience: gives the host element a stable id and registers it as the
+ * drawer's accessible name (`aria-labelledby`). Apply on a heading element
+ * (`<h2>`, `<h3>`...) inside `[forDrawer]`.
+ *
+ * If you don't render visible title text, omit this and pass `ariaLabel`
+ * on the drawer root instead.
+ */
+declare class ForDrawerTitle {
+    protected readonly id: _angular_core.Signal<string>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForDrawerTitle, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForDrawerTitle, "[forDrawerTitle]", ["forDrawerTitle"], {}, {}, never, never, true, never>;
+}
+
+/**
+ * Convenience: gives the host element a stable id and registers it as the
+ * drawer's accessible description (`aria-describedby`). Apply on a `<p>` or
+ * other element inside `[forDrawer]`. Optional — only use when there's
+ * non-title supporting copy.
+ */
+declare class ForDrawerDescription {
+    protected readonly id: _angular_core.Signal<string>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForDrawerDescription, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForDrawerDescription, "[forDrawerDescription]", ["forDrawerDescription"], {}, {}, never, never, true, never>;
+}
+
+/**
+ * Button that closes the surrounding drawer when clicked. Apply on a
+ * `<button>` inside `[forDrawer]`. Pass `[closeWith]` to propagate a return
+ * value to `ForDrawerRef.close()` in programmatic usage; ignored in
+ * declarative usage.
+ */
+declare class ForDrawerClose {
+    #private;
+    /** Optional value passed to `ForDrawerRef.close()` (programmatic mode). */
+    readonly closeWith: _angular_core.InputSignal<unknown>;
+    protected onClick(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForDrawerClose, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForDrawerClose, "[forDrawerClose]", ["forDrawerClose"], { "closeWith": { "alias": "closeWith"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Marks the consumer's app-shell wrapper so {@link ForDrawer}'s
+ * `scaleBackground` effect can transform the rest of the page when a
+ * drawer opens — applied through Angular DI rather than a global selector.
+ *
+ * Apply on the element that contains everything the drawer should appear
+ * to recede behind (typically the root shell). Reflects
+ * `data-state="scaled"` while the effect is active and `"idle"` at rest
+ * — useful for layering CSS styling without re-querying the coordinator.
+ *
+ * Only one wrapper may be registered at a time; mounting a second
+ * `[forDrawerWrapper]` while another is alive throws. Drawers that opt
+ * into `scaleBackground` without a registered wrapper are a no-op (no
+ * effect applied) so test composition and partial consumer adoption
+ * remain safe.
+ */
+declare class ForDrawerWrapper {
+    #private;
+    /** `'scaled'` while the coordinator is applying the effect, otherwise `'idle'`. */
+    readonly state: _angular_core.Signal<"scaled" | "idle">;
+    constructor();
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForDrawerWrapper, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForDrawerWrapper, "[forDrawerWrapper]", ["forDrawerWrapper"], {}, {}, never, never, true, never>;
+}
+
+/**
+ * Handle returned by `ForDrawerManager.open()`. Inject inside the opened
+ * component to drive close imperatively. Both reactive (`isClosed`, `result`)
+ * and awaitable (`closed`) APIs are exposed — pick what fits the call site.
+ *
+ * `R` is the close-result type. Default `unknown`; specify it on
+ * `manager.open<C, R>(...)` to get type safety.
+ */
+declare class ForDrawerRef<R = unknown> extends OverlayRef<R> {
+}
+
+/**
+ * Shape of a single open drawer entry stored in the manager.
+ *
+ * Internal — not re-exported from `public-api.ts`.
+ */
+interface ForDrawerEntry extends OverlayManagerEntry {
+    readonly component: Type<unknown>;
+    readonly hostClass: string;
+    readonly side: ForDrawerSide | undefined;
+    readonly dismissible: boolean | undefined;
+    readonly modal: boolean | undefined;
+    readonly alert: boolean | undefined;
+    readonly returnFocus: boolean | undefined;
+    readonly initialFocus: 'first' | 'container' | undefined;
+    readonly ariaLabel: string | undefined;
+    readonly container: HTMLElement | null | undefined;
+    readonly animateEnter: string | undefined;
+    readonly autoFocusOnOpen: ((e: VetoableEvent) => void) | undefined;
+    readonly autoFocusOnClose: ((e: VetoableEvent) => void) | undefined;
+    readonly swipeToDismiss: boolean | undefined;
+    readonly closeThreshold: number | undefined;
+    readonly handleOnly: boolean | undefined;
+    readonly scaleBackground: boolean | undefined;
+    readonly setBackgroundColorOnScale: boolean | undefined;
+    readonly snapPoints: ReadonlyArray<ForDrawerSnapPoint> | undefined;
+    readonly activeSnapPoint: ForDrawerSnapPoint | undefined;
+    readonly fadeFromIndex: number | undefined;
+    readonly escapeKeyDown: ((e: VetoableNativeEvent<KeyboardEvent>) => void) | undefined;
+    readonly pointerDownOutside: ((e: VetoableNativeEvent<PointerEvent>) => void) | undefined;
+    readonly focusOutside: ((e: VetoableNativeEvent<FocusEvent>) => void) | undefined;
+    readonly interactOutside: ((e: VetoableNativeEvent<PointerEvent | FocusEvent>) => void) | undefined;
+    readonly onDrag: ((e: ForDrawerDragEvent) => void) | undefined;
+    readonly onRelease: ((e: ForDrawerReleaseEvent) => void) | undefined;
+    readonly onActiveSnapPointChange: ((snap: ForDrawerSnapPoint | null) => void) | undefined;
+    handleClose(value: unknown): void;
+    injectorFor(parent: Injector): Injector;
+}
+
+/**
+ * Injection token for the `data` payload passed to `ForDrawerManager.open(component, { data })`.
+ * Inject inside the opened component:
+ *
+ * ```ts
+ * readonly data = inject(FOR_DRAWER_DATA) as MyShape;
+ * ```
+ *
+ * Prefer `injectDrawerData<T>()` for typed access without manual casts.
+ */
+declare const FOR_DRAWER_DATA: InjectionToken<unknown>;
+/** Typed accessor for the `data` payload. Equivalent to `inject(FOR_DRAWER_DATA) as T`. */
+declare function injectDrawerData<T = unknown>(): T;
+interface ForDrawerOpenConfig<D = unknown> {
+    /** Payload available inside the drawer component via `injectDrawerData<T>()`. */
+    data?: D;
+    /** Edge the drawer is anchored to. Default `'bottom'`. */
+    side?: ForDrawerSide;
+    /** When true (default), Escape / backdrop / pointer-down outside / swipe close the drawer. */
+    dismissible?: boolean;
+    /** When true (default), set `aria-modal`, lock body scroll, trap focus. */
+    modal?: boolean;
+    /** When true, role becomes `alertdialog` instead of `dialog`. Default `false`. */
+    alert?: boolean;
+    /** When true (default), focus returns to the previously focused element on close. */
+    returnFocus?: boolean;
+    /** Where to send focus on open. Default `'first'`. */
+    initialFocus?: 'first' | 'container';
+    /** Manual `aria-label`. Use when no visible title element is rendered. */
+    ariaLabel?: string;
+    /**
+     * Portal target for the surface + backdrop. Defaults to `document.body`.
+     * Pair with `modal: false` for a drawer scoped to a positioned region
+     * instead of the viewport.
+     */
+    container?: HTMLElement | null;
+    /**
+     * CSS class applied (via `animate.enter`) to the overlay root the moment it
+     * mounts, so a programmatic drawer plays an enter animation just like a
+     * declarative `<div forDrawer animate.enter="…">`. The class lands on the
+     * same `[forDrawer]` host as {@link class}. Falls back to
+     * `provideForDrawerDefaults({ animateEnter })`.
+     */
+    animateEnter?: string;
+    /**
+     * CSS class applied to the overlay root when `close()` is called. The manager
+     * keeps the host mounted with this class until its CSS animations /
+     * transitions finish, then tears the drawer down — so a programmatic drawer
+     * plays an exit animation. `close()` still resolves its promise and flips
+     * `isClosed()` immediately; only the visual teardown waits. With no class (or
+     * no animation, or under `prefers-reduced-motion`), close is immediate. Falls
+     * back to `provideForDrawerDefaults({ animateLeave })`.
+     */
+    animateLeave?: string;
+    /**
+     * Exit-animation class for the portaled `[forDrawerBackdrop]`: the manager
+     * adds it when `close()` is called and keeps the backdrop mounted until the
+     * animation finishes, so the backdrop fades out in lockstep with the host.
+     *
+     * The split with the enter animation is intentional, not an oversight.
+     * Declare the backdrop's **enter** with `animate.enter="…"` on the element
+     * itself — it fires on mount, which Angular runs normally even inside the
+     * manager's `ngComponentOutlet` — and declare only its **leave** here. A
+     * template `animate.leave` on the backdrop never fires under the manager:
+     * Angular does not run leave animations across the `ngComponentOutlet` the
+     * opened component is mounted through. (The host sheet is symmetric — both
+     * `animateEnter` and `animateLeave` are config, since the manager owns that
+     * element.) Falls back to `provideForDrawerDefaults({ backdropAnimateLeave })`.
+     */
+    backdropAnimateLeave?: string;
+    /** When true (default), pointer drag past `closeThreshold` dismisses. */
+    swipeToDismiss?: boolean;
+    /** Fraction of dimension past which a release dismisses. Default `0.25`. */
+    closeThreshold?: number;
+    /** When true, swipe only arms on a registered handle element. Default `false`. */
+    handleOnly?: boolean;
+    /**
+     * When true, asks the registered `[forDrawerWrapper]` to scale and translate
+     * behind this drawer (the "scale background" effect). No effect under
+     * `prefers-reduced-motion: reduce`, and a no-op if no wrapper is mounted.
+     */
+    scaleBackground?: boolean;
+    /**
+     * When true (default) and `scaleBackground` is active, paints `<body>` with
+     * `scaleBackgroundColor` so the gap between the scaled wrapper and the
+     * viewport edge does not show through.
+     */
+    setBackgroundColorOnScale?: boolean;
+    /** Snap points. Optional. */
+    snapPoints?: ReadonlyArray<ForDrawerSnapPoint>;
+    /** Initial snap point at open time. Defaults to `snapPoints?.[0]`. */
+    defaultSnapPoint?: ForDrawerSnapPoint;
+    /** First snap-point index from which the backdrop reflects `data-fade-from-active`. */
+    fadeFromIndex?: number;
+    /**
+     * Consumer CSS class(es) applied to the overlay root (the `[forDrawer]`
+     * host). Pass a single class (`'my-drawer'`) or a space-separated string.
+     * Merged with the directive's own host attributes — it never clobbers
+     * `data-side` / `data-state` / the `--for-drawer-translate` custom property.
+     *
+     * Use this to carry design-system classes onto a programmatic drawer,
+     * including positioning CSS keyed on `data-side` (e.g.
+     * `.my-drawer[data-side='bottom']`). It replaces the
+     * `inject(FOR_DRAWER_CONTEXT).hostElement.classList.add(...)` workaround.
+     * For multiple classes as an array, prefer {@link classList}.
+     */
+    class?: string;
+    /**
+     * Consumer CSS class(es) applied to the overlay root, as an array
+     * (`['my-drawer', 'my-drawer--lg']`) or a space-separated string. Merged
+     * with {@link class} and with the directive's own host attributes.
+     */
+    classList?: string | readonly string[];
+    /** Extra providers for the opened component's injector. */
+    providers?: Provider[];
+    /**
+     * Fires just before the drawer moves focus into itself on mount.
+     * Call `event.preventDefault()` to skip the imperative focus move.
+     */
+    autoFocusOnOpen?: (event: VetoableEvent) => void;
+    /**
+     * Fires just before focus returns to the previously focused element
+     * on unmount. Call `event.preventDefault()` to skip the return-focus.
+     */
+    autoFocusOnClose?: (event: VetoableEvent) => void;
+    /**
+     * Per-channel dismiss hook mirroring the declarative `(escapeKeyDown)`
+     * output. Fires when Escape is pressed while this drawer is the topmost
+     * dismissable layer. Call `event.preventDefault()` on the veto to suppress
+     * the implicit close while keeping the other dismiss channels live. The
+     * original `KeyboardEvent` is on `.event`.
+     */
+    escapeKeyDown?: (event: VetoableNativeEvent<KeyboardEvent>) => void;
+    /**
+     * Per-channel dismiss hook mirroring the declarative `(pointerDownOutside)`
+     * output. Fires when a pointer goes down outside the drawer. Call
+     * `event.preventDefault()` on the veto to suppress the implicit close. The
+     * native `PointerEvent` is on `.event`.
+     */
+    pointerDownOutside?: (event: VetoableNativeEvent<PointerEvent>) => void;
+    /**
+     * Per-channel dismiss hook mirroring the declarative `(focusOutside)`
+     * output. Fires when focus moves outside the drawer. Call
+     * `event.preventDefault()` on the veto to suppress the implicit close. The
+     * native `FocusEvent` is on `.event`.
+     */
+    focusOutside?: (event: VetoableNativeEvent<FocusEvent>) => void;
+    /**
+     * Composite dismiss hook mirroring the declarative `(interactOutside)`
+     * output. Fires alongside `pointerDownOutside` / `focusOutside` and shares
+     * their veto state — `event.preventDefault()` on either suppresses the
+     * implicit close. Use this to keep a programmatic floater open on outside
+     * interaction while leaving Escape live (set `dismissible: true` and veto
+     * here). The native `PointerEvent | FocusEvent` is on `.event`.
+     */
+    interactOutside?: (event: VetoableNativeEvent<PointerEvent | FocusEvent>) => void;
+    /**
+     * Mirrors the declarative `(dragMove)` output: invoked on every pointer-move
+     * frame of a swipe gesture with `percentageDragged` ∈ `[0, 1]`. Lets a
+     * programmatic consumer drive bespoke drag visualizations the way the
+     * directive consumer can.
+     */
+    onDrag?: (event: ForDrawerDragEvent) => void;
+    /**
+     * Mirrors the declarative `(release)` output: invoked once the pointer is
+     * released, after the directive has resolved the next snap point / close
+     * decision. Read `willClose` and `nextSnapPoint` from the payload.
+     */
+    onRelease?: (event: ForDrawerReleaseEvent) => void;
+    /**
+     * Mirrors the declarative `(activeSnapPointChange)` output: invoked with
+     * the landed snap point whenever the drawer transitions internally
+     * (mount-time default and drag release). Use this to read back the active
+     * snap that the declarative API exposes via `[(activeSnapPoint)]`.
+     */
+    onActiveSnapPointChange?: (snapPoint: ForDrawerSnapPoint | null) => void;
+}
+/**
+ * Programmatic drawer opener — symmetric with `ForDialogManager`. Inject
+ * anywhere, call `open(MyComponent, { data, side, ... })` and get a
+ * `ForDrawerRef<R>` back. Internally the manager renders the user component
+ * inside a manager-owned `@for` outlet, so Angular's control-flow unmount
+ * fires `animate.leave` before the node leaves the DOM — identical to the
+ * declarative `@if (open()) { <div forDrawer animate.leave="…"> }` path.
+ *
+ * Inside the opened component the usual drawer pieces work without any extra
+ * wiring: `[forDrawerTitle]`, `[forDrawerDescription]`, `[forDrawerBackdrop]`,
+ * `[forDrawerHandle]`, `[forDrawerClose]`. `[forDrawerClose] [closeWith]`
+ * propagates through to `ForDrawerRef.close(value)`.
+ *
+ * Inject `ForDrawerRef` to drive close imperatively and `FOR_DRAWER_DATA` (or
+ * `injectDrawerData<T>()`) for the payload.
+ */
+declare class ForDrawerManager extends OverlayManagerCore<ForDrawerEntry> {
+    #private;
+    constructor();
+    open<C, R = unknown, D = unknown>(component: Type<C>, config?: ForDrawerOpenConfig<D>): ForDrawerRef<R>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForDrawerManager, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<ForDrawerManager>;
+}
+
+/**
+ * Defaults inherited by descendant drawers in the surrounding injector
+ * scope. Configure with `provideForDrawerDefaults`. Keys map 1:1 to the
+ * directive inputs of the same name; the directive picks
+ * `consumerInput ?? defaults[key] ?? hardcoded fallback` per key.
+ */
+interface ForDrawerDefaults {
+    /** Default `'bottom'`. */
+    side?: ForDrawerSide;
+    /** Default `true`. Modal locks scroll, traps focus, applies `aria-modal`. */
+    modal?: boolean;
+    /** Default `true`. Whether dismiss interactions (Escape, backdrop, swipe) close. */
+    dismissible?: boolean;
+    /** Default `true`. Pointer drag gesture toward the anchored edge dismisses. */
+    swipeToDismiss?: boolean;
+    /**
+     * Default `0.25`. Fraction past which a release dismisses instead of
+     * snapping back: of the full dimension without snap points, of the lowest
+     * snap's extent with them (see
+     * `_internal/snap-points/resolveSnapTarget`).
+     */
+    closeThreshold?: number;
+    /** Default `'first'`. Where to send focus on mount. */
+    initialFocus?: 'first' | 'container';
+    /** Default `true`. Restore focus to the previously focused element on close. */
+    returnFocus?: boolean;
+    /**
+     * Default `false`. When `true` the swipe gesture only arms on the
+     * registered `[forDrawerHandle]` element instead of the whole surface.
+     */
+    handleOnly?: boolean;
+    /**
+     * Default `false`. When `true`, an open drawer asks
+     * `[forDrawerWrapper]` to scale + translate behind it (the "scale
+     * background" effect). Suppressed under
+     * `prefers-reduced-motion: reduce`.
+     */
+    scaleBackground?: boolean;
+    /**
+     * Default `true`. When `scaleBackground` is active, paints the body
+     * with `scaleBackgroundColor` so the sliver of viewport between the
+     * scaled wrapper and the screen edge does not show through.
+     */
+    setBackgroundColorOnScale?: boolean;
+    /** Default `0.95`. Scale factor applied to the wrapper. */
+    scaleAmount?: number;
+    /**
+     * Default `14`. Vertical translation (in CSS pixels) added to
+     * `env(safe-area-inset-top)` while the wrapper is scaled.
+     */
+    scaleTranslateYpx?: number;
+    /** Default `8`. Border radius applied to the wrapper while scaled. */
+    scaleBorderRadiusPx?: number;
+    /**
+     * Default `'black'`. Body background colour applied while
+     * `setBackgroundColorOnScale` is active.
+     */
+    scaleBackgroundColor?: string;
+    /**
+     * Default `0.93`. Scale factor applied to a parent drawer while a
+     * nested child drawer is active. Composes with the wrapper-level
+     * `scaleBackground` effect when both opt in. Suppressed under
+     * `prefers-reduced-motion: reduce`.
+     */
+    nestedScaleAmount?: number;
+    /**
+     * Default `8`. Pixels of additional translation applied to a parent
+     * drawer while a nested child is active, in the direction *away* from
+     * the parent's anchored edge (so a `bottom` drawer slides up by this
+     * amount when its child opens).
+     */
+    nestedTranslateYpx?: number;
+    /**
+     * CSS class applied (via `animate.enter`) to the programmatic overlay host
+     * when it mounts, so it plays an enter animation. The class lands on the
+     * `[forDrawer]` host that also carries the consumer `class`. No default.
+     */
+    animateEnter?: string;
+    /**
+     * CSS class applied to the programmatic overlay host when `close()` is
+     * called, kept on the still-mounted host until its CSS animations finish so
+     * an exit transition plays before teardown. No default (close is immediate).
+     */
+    animateLeave?: string;
+    /**
+     * CSS class applied to the portaled `[forDrawerBackdrop]` when `close()` is
+     * called, so the backdrop plays an exit animation in lockstep with the
+     * host. Needed because a backdrop declared inside the opened component plays
+     * its `animate.enter` on mount but cannot run its template `animate.leave` —
+     * Angular does not process leave animations across the `ngComponentOutlet`
+     * boundary the manager mounts the component through. No default.
+     */
+    backdropAnimateLeave?: string;
+}
+/** Token holding the resolved drawer defaults for the current scope. */
+declare const FOR_DRAWER_DEFAULTS: _angular_core.InjectionToken<ForDrawerDefaults>;
+/**
+ * Configures forty-cdk drawer defaults for this injector scope. Partial
+ * overrides inherit unspecified keys from the parent scope (or library
+ * defaults at the root).
+ */
+declare function provideForDrawerDefaults(defaults?: Partial<ForDrawerDefaults>): Provider[];
+
+export { FOR_DRAWER_CONTEXT, FOR_DRAWER_DATA, FOR_DRAWER_DEFAULTS, ForDrawer, ForDrawerBackdrop, ForDrawerClose, ForDrawerDescription, ForDrawerHandle, ForDrawerManager, ForDrawerRef, ForDrawerTitle, ForDrawerTrigger, ForDrawerWrapper, injectDrawerData, provideForDrawerDefaults };
+export type { ForDrawerCloseReason, ForDrawerContext, ForDrawerDefaults, ForDrawerDragEvent, ForDrawerOpenConfig, ForDrawerReleaseEvent, ForDrawerSnapPoint };