@mk-kit/ui 0.34.0

package/types/mk-kit-ui-directives.d.ts

@@ -0,0 +1,807 @@
+import * as _angular_core from '@angular/core';
+import { Signal, TemplateRef } from '@angular/core';
+
+/**
+ * Emits when a pointer press lands outside the host element — the building block
+ * for dismissing menus, popovers and custom dropdowns. Listens on the document
+ * in the capture phase so it fires before the target handles the event.
+ *
+ * ```html
+ * <div class="panel" (mkClickOutside)="close()">…</div>
+ * ```
+ */
+declare class MkClickOutside {
+    private readonly host;
+    private readonly document;
+    private readonly isBrowser;
+    /** Disable the listener without removing the directive. */
+    readonly enabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Emits the originating event when a pointerdown occurs outside the host. */
+    readonly mkClickOutside: _angular_core.OutputEmitterRef<PointerEvent>;
+    private readonly onPointerdown;
+    constructor();
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MkClickOutside, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<MkClickOutside, "[mkClickOutside]", ["mkClickOutside"], { "enabled": { "alias": "mkClickOutsideEnabled"; "required": false; "isSignal": true; }; }, { "mkClickOutside": "mkClickOutside"; }, never, never, true, never>;
+}
+
+/**
+ * Copies text to the clipboard when the host is clicked. Emits `(copied)` on
+ * success and `(copyFailed)` on error, and exposes a transient `copied` signal
+ * (via `exportAs`) so a template can show a "Copied!" state without extra code.
+ *
+ * ```html
+ * <button mkButton [mkCopyToClipboard]="token" #c="mkCopyToClipboard">
+ *   {{ c.justCopied() ? 'Copied!' : 'Copy' }}
+ * </button>
+ * ```
+ */
+declare class MkCopyToClipboard {
+    private readonly document;
+    private readonly isBrowser;
+    /** The text to copy. */
+    readonly text: _angular_core.InputSignal<string>;
+    /** How long (ms) the `copied` signal stays true after a successful copy. */
+    readonly feedbackDuration: _angular_core.InputSignalWithTransform<number, unknown>;
+    /** Emits the copied text on success. */
+    readonly copied: _angular_core.OutputEmitterRef<string>;
+    /** Emits the error on failure. */
+    readonly copyFailed: _angular_core.OutputEmitterRef<unknown>;
+    private readonly _copied;
+    /** True for `feedbackDuration` ms after a successful copy. */
+    readonly justCopied: _angular_core.Signal<boolean>;
+    private resetTimer?;
+    /** Copy the text now. Bound to the host click, but callable directly too. */
+    copy(): Promise<void>;
+    private write;
+    private flagCopied;
+    ngOnDestroy(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MkCopyToClipboard, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<MkCopyToClipboard, "[mkCopyToClipboard]", ["mkCopyToClipboard"], { "text": { "alias": "mkCopyToClipboard"; "required": true; "isSignal": true; }; "feedbackDuration": { "alias": "mkCopyFeedbackDuration"; "required": false; "isSignal": true; }; }, { "copied": "copiedText"; "copyFailed": "copyFailed"; }, never, never, true, never>;
+}
+
+/**
+ * Grows a `<textarea>` to fit its content, between `minRows` and `maxRows`
+ * (0 = unbounded). Resizes on input and when the bound value changes.
+ *
+ * ```html
+ * <textarea mkInput mkAutosize [mkAutosizeMaxRows]="8" [(ngModel)]="note"></textarea>
+ * ```
+ */
+declare class MkAutosize {
+    private readonly el;
+    private readonly document;
+    private readonly isBrowser;
+    /** Minimum height in rows. */
+    readonly minRows: _angular_core.InputSignalWithTransform<number, unknown>;
+    /** Maximum height in rows before scrolling (0 = unbounded). */
+    readonly maxRows: _angular_core.InputSignalWithTransform<number, unknown>;
+    /** Bind the textarea's value so programmatic changes trigger a resize. */
+    readonly value: _angular_core.InputSignal<unknown>;
+    constructor();
+    /** Recompute the textarea height from its content. */
+    resize(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MkAutosize, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<MkAutosize, "textarea[mkAutosize]", never, { "minRows": { "alias": "mkAutosizeMinRows"; "required": false; "isSignal": true; }; "maxRows": { "alias": "mkAutosizeMaxRows"; "required": false; "isSignal": true; }; "value": { "alias": "mkAutosizeValue"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Focuses the host element once it renders. Handy for dialogs, drawers and
+ * newly-revealed forms. Disable conditionally with `[mkAutofocus]="cond"`.
+ *
+ * ```html
+ * <input mkInput mkAutofocus />
+ * <input mkInput [mkAutofocus]="isEditing()" [mkAutofocusDelay]="100" />
+ * ```
+ */
+declare class MkAutofocus {
+    private readonly el;
+    private readonly document;
+    private readonly isBrowser;
+    /** Whether to focus. Bare `mkAutofocus` = true. */
+    readonly enabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Delay before focusing, in ms (e.g. to wait out an entrance animation). */
+    readonly delay: _angular_core.InputSignalWithTransform<number, unknown>;
+    private timeoutId?;
+    constructor();
+    private focus;
+    ngOnDestroy(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MkAutofocus, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<MkAutofocus, "[mkAutofocus]", never, { "enabled": { "alias": "mkAutofocus"; "required": false; "isSignal": true; }; "delay": { "alias": "mkAutofocusDelay"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Scrollspy — tracks which section is currently in view and exposes its `id`,
+ * so a table of contents / "on this page" nav can highlight the active link.
+ *
+ * Apply it to any element (typically the nav) and point `mkScrollspy` at a CSS
+ * selector matching the section elements to watch (each needs an `id`). Read the
+ * active id via the exported instance, or bind `(activeChange)`:
+ *
+ * ```html
+ * <nav mkScrollspy="main :is(h2, h3)[id]" #spy="mkScrollspy">
+ *   <a href="#intro" [class.is-active]="spy.activeId() === 'intro'">Intro</a>
+ *   …
+ * </nav>
+ * ```
+ *
+ * A section activates once its top passes `offset` px below the top of the
+ * scroll root (default the viewport). When scrolling through a gap between
+ * sections the previous one stays active until the next crosses the line.
+ */
+declare class MkScrollspy {
+    private readonly document;
+    private readonly isBrowser;
+    /** CSS selector for the section elements to track (queried within `root`). */
+    readonly sections: _angular_core.InputSignal<string>;
+    /**
+     * Scroll container. Sections are queried inside it and its top edge is the
+     * activation reference. Defaults to the whole document / viewport.
+     */
+    readonly root: _angular_core.InputSignal<HTMLElement | null>;
+    /**
+     * Distance (px) below the scroll root's top at which a section becomes
+     * active. Raise it to account for a sticky header.
+     */
+    readonly offset: _angular_core.InputSignal<number>;
+    /** The id of the currently active section (`null` before the first one). */
+    readonly activeId: _angular_core.WritableSignal<string | null>;
+    /** Emitted whenever the active section changes. */
+    readonly activeChange: _angular_core.OutputEmitterRef<string | null>;
+    private scrollSource?;
+    constructor();
+    /** Re-evaluate the active section (call after sections change). */
+    refresh(): void;
+    private querySections;
+    private computeRaf;
+    /** rAF-coalesced — several scroll ticks per frame trigger one layout read. */
+    private readonly onScroll;
+    private compute;
+    /** Whether the scroll root is scrolled to (or within 1px of) its bottom. */
+    private atBottom;
+    private setActive;
+    ngOnDestroy(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MkScrollspy, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<MkScrollspy, "[mkScrollspy]", ["mkScrollspy"], { "sections": { "alias": "mkScrollspy"; "required": true; "isSignal": true; }; "root": { "alias": "root"; "required": false; "isSignal": true; }; "offset": { "alias": "offset"; "required": false; "isSignal": true; }; }, { "activeChange": "activeChange"; }, never, never, true, never>;
+}
+
+/**
+ * Intersect — a thin `IntersectionObserver` wrapper. Emits `(mkIntersect)` with
+ * the host's visibility whenever it enters or leaves the viewport (or `root`),
+ * and exposes an `intersecting` signal via `exportAs`. Set `once` to fire a
+ * single time and disconnect — the primitive for reveal-on-scroll animations
+ * and lazy loading.
+ *
+ * ```html
+ * <img [attr.src]="loaded() ? src : null" mkIntersect once
+ *      (mkIntersect)="loaded.set(true)" />
+ *
+ * <div mkIntersect #io="mkIntersect" [class.in-view]="io.intersecting()">…</div>
+ * ```
+ */
+declare class MkIntersect {
+    private readonly host;
+    private readonly document;
+    private readonly injector;
+    private readonly isBrowser;
+    /** Element used as the viewport for the check (defaults to the browser one). */
+    readonly root: _angular_core.InputSignal<HTMLElement | null>;
+    /** Margin grown/shrunk around the root before computing intersection. */
+    readonly rootMargin: _angular_core.InputSignal<string>;
+    /** Visibility ratio(s) at which the observer fires. */
+    readonly threshold: _angular_core.InputSignal<number | number[]>;
+    /** Emit the first time the host becomes visible, then disconnect. */
+    readonly once: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Emits the host's `isIntersecting` state on every change. */
+    readonly mkIntersect: _angular_core.OutputEmitterRef<boolean>;
+    /** The current visibility, also readable via `exportAs`. */
+    readonly intersecting: _angular_core.WritableSignal<boolean>;
+    private observer?;
+    constructor();
+    private onEntries;
+    private disconnect;
+    ngOnDestroy(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MkIntersect, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<MkIntersect, "[mkIntersect]", ["mkIntersect"], { "root": { "alias": "root"; "required": false; "isSignal": true; }; "rootMargin": { "alias": "rootMargin"; "required": false; "isSignal": true; }; "threshold": { "alias": "threshold"; "required": false; "isSignal": true; }; "once": { "alias": "once"; "required": false; "isSignal": true; }; }, { "mkIntersect": "mkIntersect"; }, never, never, true, never>;
+}
+
+/**
+ * InfiniteScroll — emits `(mkInfiniteScroll)` when the host scroll container is
+ * scrolled within `distance` px of its bottom, so a list can load its next
+ * page. Apply it to the scrollable element (`overflow: auto`). It fires once per
+ * approach and re-arms after you scroll back up past the threshold, so a single
+ * gesture never triggers repeated loads. Set `disabled` while a page is loading
+ * or once everything is loaded.
+ *
+ * ```html
+ * <div class="feed" mkInfiniteScroll [disabled]="loading() || done()"
+ *      (mkInfiniteScroll)="loadMore()">
+ *   @for (item of items(); track item.id) { … }
+ * </div>
+ * ```
+ */
+declare class MkInfiniteScroll {
+    private readonly host;
+    private readonly isBrowser;
+    /** Distance (px) from the bottom at which the output fires. */
+    readonly distance: _angular_core.InputSignalWithTransform<number, unknown>;
+    /** Pause firing (e.g. while a page is loading or all items are loaded). */
+    readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Emitted when the host is scrolled near its bottom. */
+    readonly mkInfiniteScroll: _angular_core.OutputEmitterRef<void>;
+    /** Whether the next bottom-approach is allowed to fire. */
+    private armed;
+    constructor();
+    private readonly onScroll;
+    private check;
+    ngOnDestroy(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MkInfiniteScroll, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<MkInfiniteScroll, "[mkInfiniteScroll]", ["mkInfiniteScroll"], { "distance": { "alias": "distance"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; }, { "mkInfiniteScroll": "mkInfiniteScroll"; }, never, never, true, never>;
+}
+
+/**
+ * Ripple — a Material-style touch ripple that expands from the pointer on press.
+ * Apply it to any pressable surface (button, list item, card). The directive
+ * makes the host a positioned, clipping container and paints a short-lived wave;
+ * it respects `prefers-reduced-motion`.
+ *
+ * ```html
+ * <button mkRipple>Save</button>
+ * <li mkRipple mkRippleColor="var(--mk-primary)">Item</li>
+ * ```
+ */
+declare class MkRipple {
+    private readonly host;
+    private readonly document;
+    private readonly isBrowser;
+    /** Wave colour (any CSS colour). Defaults to the host's `currentColor`. */
+    readonly color: _angular_core.InputSignal<string>;
+    /** Start every ripple from the centre instead of the pointer. */
+    readonly centered: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Turn the effect off. */
+    readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    protected spawn(event: PointerEvent): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MkRipple, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<MkRipple, "[mkRipple]", never, { "color": { "alias": "mkRippleColor"; "required": false; "isSignal": true; }; "centered": { "alias": "mkRippleCentered"; "required": false; "isSignal": true; }; "disabled": { "alias": "mkRippleDisabled"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/** Result of applying a mask: the formatted string and its raw token chars. */
+interface MkMaskResult {
+    masked: string;
+    unmasked: string;
+}
+/**
+ * Format `value` against a mask `pattern`. Pattern tokens: `0` = digit,
+ * `A` = letter, `*` = alphanumeric; any other character is a literal that is
+ * inserted automatically. Characters that don't fit the current token are
+ * skipped, so pasted / mistyped input is coerced into shape.
+ *
+ * Returns the `masked` (display) string and the `unmasked` string (only the
+ * token characters — the value you usually store).
+ */
+declare function mkApplyMask(value: string, pattern: string): MkMaskResult;
+/**
+ * Compute where the caret belongs after re-masking: after the same number of
+ * value (alphanumeric) characters the caret used to sit behind, absorbing any
+ * literal(s) that immediately follow — so typing "1" in "(0)" lands the caret
+ * after the "(". Shared by {@link MkMask} and the masked form controls.
+ */
+declare function mkMaskCaret(oldValue: string, oldCaret: number, masked: string): number;
+/**
+ * Mask — formats an `<input>` as the user types against a token pattern
+ * (phone, card, date, custom). Apply it to any text input; read the raw value
+ * via `(unmaskedChange)` (or the exported `unmasked` getter) and the formatted
+ * value via `(maskedChange)`.
+ *
+ * ```html
+ * <input mkInput mkMask="(000) 000-0000" (unmaskedChange)="phone.set($event)" />
+ * <input mkInput mkMask="0000 0000 0000 0000" />
+ * ```
+ */
+declare class MkMask {
+    private readonly host;
+    /** The mask pattern (token string). */
+    readonly pattern: _angular_core.InputSignal<string>;
+    /** Override the derived `inputmode` (`numeric` for digit-only masks). */
+    readonly maskInputmode: _angular_core.InputSignal<string | null>;
+    /** Mobile keyboard hint: numeric for digit-only patterns unless overridden. */
+    protected readonly inputMode: _angular_core.Signal<string>;
+    /** The formatted value, on every change. */
+    readonly maskedChange: _angular_core.OutputEmitterRef<string>;
+    /** The raw value (token characters only), on every change. */
+    readonly unmaskedChange: _angular_core.OutputEmitterRef<string>;
+    private _masked;
+    private _unmasked;
+    /** The current formatted value. */
+    get value(): string;
+    /** The current raw value (token characters only). */
+    get unmasked(): string;
+    protected onInput(): void;
+    /** Position the caret after the same number of value chars as before. */
+    private setCaret;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MkMask, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<MkMask, "[mkMask]", ["mkMask"], { "pattern": { "alias": "mkMask"; "required": true; "isSignal": true; }; "maskInputmode": { "alias": "mkMaskInputmode"; "required": false; "isSignal": true; }; }, { "maskedChange": "maskedChange"; "unmaskedChange": "unmaskedChange"; }, never, never, true, never>;
+}
+
+/** The attributes a field preset can control. */
+declare const MK_FIELD_ATTRS: readonly ["type", "inputmode", "autocomplete", "autocapitalize", "autocorrect", "spellcheck", "enterkeyhint"];
+type MkFieldAttr = (typeof MK_FIELD_ATTRS)[number];
+/** The attribute bundle applied for one `MkFieldKind`. Omitted = not set. */
+type MkFieldPreset = Partial<Record<MkFieldAttr, string>>;
+/** Semantic field kinds understood by {@link MkField}. */
+type MkFieldKind = 'email' | 'tel' | 'url' | 'search' | 'numeric' | 'given-name' | 'family-name' | 'name' | 'organization' | 'street' | 'address-line1' | 'address-line2' | 'city' | 'region' | 'country' | 'postal-code' | 'username' | 'one-time-code';
+/**
+ * The attribute bundle per field kind. Exported so hosts can inspect what a
+ * kind resolves to, or spread an entry into their own preset table.
+ *
+ * `autocorrect` (non-standard, honoured by iOS Safari) is set to `off`
+ * wherever `spellcheck` is `false`.
+ */
+declare const MK_FIELD_PRESETS: Readonly<Record<MkFieldKind, MkFieldPreset>>;
+/**
+ * Field — applies the semantic mobile-keyboard and autofill attribute bundle
+ * for a kind of field, so you never again ship an email input that iOS
+ * capitalises or an address input the browser can't autofill.
+ *
+ * It sets `type`, `inputmode`, `autocomplete`, `autocapitalize`, `autocorrect`,
+ * `spellcheck` and `enterkeyhint` (see {@link MK_FIELD_PRESETS}) and nothing
+ * else — no styling, no value handling — so it composes with `mkInput`,
+ * `mk-form-field`, `[(ngModel)]` and reactive forms untouched.
+ *
+ * ```html
+ * <input mkInput mkField="email" formControlName="email" />
+ * <input mkInput mkField="street" formControlName="street" />
+ * <input mkInput [mkField]="isCompany() ? 'organization' : 'name'" />
+ * ```
+ *
+ * ## Precedence
+ *
+ * A **static** attribute you write on the element wins: the directive reads the
+ * seven attributes once at construction (before any host binding has run) and
+ * keeps whatever was already there, filling in only what you left out. So
+ * `<input mkField="username" type="password" />` stays a password field but
+ * still gets `autocomplete="username"`, `autocapitalize="off"`, …
+ *
+ * A **template binding** for the same attribute (`[attr.autocomplete]="…"`)
+ * does *not* win — Angular applies directive host bindings after template
+ * bindings, so the preset overwrites it. Use a static attribute to override, or
+ * drop `mkField` and set the bundle yourself.
+ */
+declare class MkField {
+    private readonly el;
+    /** Which kind of field this is. */
+    readonly kind: _angular_core.InputSignal<MkFieldKind>;
+    /**
+     * Attributes the consumer put on the element themselves, read once before
+     * any host binding has run — these always win over the preset.
+     */
+    private readonly authored;
+    /** The resolved attribute bundle: authored value, else preset, else unset. */
+    protected readonly attrs: _angular_core.Signal<Record<"type" | "inputmode" | "autocomplete" | "autocapitalize" | "autocorrect" | "spellcheck" | "enterkeyhint", string | null>>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MkField, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<MkField, "[mkField]", never, { "kind": { "alias": "mkField"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * A single undoable step recorded in an {@link MkHistoryStack}.
+ *
+ * The **first** execution of an action is the caller's job — `push()` records
+ * an action that has *already happened*. `undo()` reverts it; `redo()` applies
+ * it again after an undo.
+ */
+interface MkHistoryEntry {
+    /** Human label for menus/tooltips ("Delete row", "Move card"). */
+    label: string;
+    /** Revert the action. */
+    undo(): void;
+    /** Re-apply the action after an undo. */
+    redo(): void;
+}
+/**
+ * MkHistoryStack — a pure, signal-based, linear undo/redo command stack with
+ * no Angular DI involved. Instantiate it directly for a local editing session
+ * (a dialog, a canvas, a form wizard), or use the app-wide singleton
+ * {@link MkHistoryService}.
+ *
+ * ```ts
+ * const stack = new MkHistoryStack();
+ * deleteRow(row);                                  // 1. do the work yourself
+ * stack.push({                                     // 2. record how to revert/redo it
+ *   label: 'Delete row',
+ *   undo: () => insertRow(row),
+ *   redo: () => deleteRow(row),
+ * });
+ * stack.undo();                                    // row is back
+ * ```
+ *
+ * ### Linear history
+ * `push()` clears the redo branch — after undoing twice and pushing a new
+ * entry, the two undone entries are gone (the standard editor model).
+ *
+ * ### ⚠️ Re-entrancy guard — the classic footgun
+ * Pushes made **while** `undo()` or `redo()` is executing are **silently
+ * ignored**. Naive consumers often record history from a generic change
+ * handler (`(cellEdit)`, `valueChanges`, …); when an undo replays the old
+ * value, that same handler fires again and would push a mirror entry,
+ * corrupting the stack into an undo/redo ping-pong. The guard makes that
+ * pattern safe by construction. If you need to record something new in
+ * response to an undo, do it after `undo()` returns.
+ */
+declare class MkHistoryStack {
+    private readonly undoStack;
+    private readonly redoStack;
+    /** True while an entry's `undo()`/`redo()` is running (re-entrancy guard). */
+    private replaying;
+    /** Depth of nested `batch()` calls; > 0 while a batch is collecting. */
+    private batchDepth;
+    private batchLabel;
+    private batchBuffer;
+    private maxSize;
+    /** True when at least one entry can be undone. */
+    readonly canUndo: Signal<boolean>;
+    /** True when at least one undone entry can be redone. */
+    readonly canRedo: Signal<boolean>;
+    /** Label of the entry `undo()` would revert, or `null` ("Undo *Delete row*"). */
+    readonly undoLabel: Signal<string | null>;
+    /** Label of the entry `redo()` would re-apply, or `null`. */
+    readonly redoLabel: Signal<string | null>;
+    /** Number of undoable entries currently on the stack. */
+    readonly size: Signal<number>;
+    /**
+     * Maximum number of undoable entries kept (default `100`). When exceeded the
+     * **oldest** entries are dropped. Settable at any time; lowering it trims
+     * the stack immediately. Values below 1 are clamped to 1.
+     */
+    get limit(): number;
+    set limit(value: number);
+    /**
+     * Record an already-performed action. Clears the redo branch and evicts the
+     * oldest entry beyond {@link limit}. Ignored while `undo()`/`redo()` is
+     * executing (see the re-entrancy note on the class) — inside a `batch()` the
+     * entry is collected into the composite instead.
+     */
+    push(entry: MkHistoryEntry): void;
+    /** Undo the most recent entry. Returns `false` when there is nothing to undo. */
+    undo(): boolean;
+    /** Redo the most recently undone entry. Returns `false` when there is nothing to redo. */
+    redo(): boolean;
+    /** Drop all entries (both branches) and any in-flight batch collection. */
+    clear(): void;
+    /**
+     * Group every `push()` made during `work()` into **one** undoable step.
+     * Undo runs the children in reverse order; redo runs them forward. Nested
+     * `batch()` calls flatten into the outermost batch (its label wins). An
+     * empty batch records nothing. Returns `work()`'s result; if `work()`
+     * throws, entries pushed before the throw are still committed.
+     */
+    batch<T>(label: string, work: () => T): T;
+    /**
+     * Create an **independent** stack with the same API — e.g. for a dialog's
+     * local editing session that should not pollute the app-wide history.
+     * Discard it (or `clear()` it) when the session ends.
+     */
+    createScope(): MkHistoryStack;
+    /** Append to the undo stack: clear the redo branch, evict beyond the limit. */
+    private commit;
+}
+/**
+ * MkHistoryService — the app-wide {@link MkHistoryStack} singleton. Inject it
+ * anywhere; call {@link MkHistoryStack.createScope} for an isolated local
+ * stack, or wire `mod+z` / `mod+shift+z` / `mod+y` with
+ * {@link registerHistoryHotkeys}.
+ *
+ * ### Recipe — undoable `mk-table` cell edits
+ * Wire the table's `(cellEdit)` output so each saved cell becomes one
+ * undoable step. Apply the edit yourself first (`push()` records an action
+ * that already happened), and match rows by a stable id — the row object is
+ * replaced by the immutable update:
+ *
+ * ```ts
+ * // <mk-table [rows]="rows()" [columns]="columns" (cellEdit)="onCellEdit($event)" />
+ * private readonly history = inject(MkHistoryService);
+ * readonly rows = signal<Order[]>([...]);
+ *
+ * onCellEdit(edit: MkCellEdit<Order>): void {
+ *   const previous = edit.row[edit.key as keyof Order];
+ *   const apply = (value: unknown) =>
+ *     this.rows.update((rows) =>
+ *       rows.map((r) => (r.id === edit.row.id ? { ...r, [edit.key]: value } : r)),
+ *     );
+ *   apply(edit.value); // first execution is the caller's job
+ *   this.history.push({
+ *     label: `Edit ${edit.key}`,
+ *     undo: () => apply(previous),
+ *     redo: () => apply(edit.value),
+ *   });
+ * }
+ * ```
+ *
+ * Undoing replays the old value through the same `apply` function; if your
+ * change pipeline re-emits into `onCellEdit` during that replay, the
+ * re-entrancy guard drops the spurious `push()` (see {@link MkHistoryStack}).
+ */
+declare class MkHistoryService extends MkHistoryStack {
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MkHistoryService, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<MkHistoryService>;
+}
+
+/**
+ * Opt-in helper wiring the standard editor shortcuts to a history stack
+ * through {@link MkHotkeysService}:
+ *
+ * - `mod+z` → `undo()`
+ * - `mod+shift+z` **and** `mod+y` → `redo()`
+ *
+ * Must be called in an **injection context** (constructor, field initializer,
+ * or `runInInjectionContext`). Nothing is registered automatically — apps own
+ * their shortcuts and call this where (and if) they want them:
+ *
+ * ```ts
+ * export class AppShell {
+ *   private readonly disposeHistoryKeys = registerHistoryHotkeys();
+ * }
+ * ```
+ *
+ * Pass a specific stack (e.g. a `createScope()` stack for a dialog) to bind
+ * the shortcuts to it instead of the app-wide {@link MkHistoryService}.
+ *
+ * Returns a dispose function that unregisters all three shortcuts; it is also
+ * called automatically when the current injection context is destroyed.
+ *
+ * Notes:
+ * - `MkHotkeysService` ignores keydowns while an editable element
+ *   (input/textarea/select/contentEditable) is focused, so native text-field
+ *   undo keeps working — no extra handling needed here.
+ * - The shortcuts register with `preventDefault` so the browser's own
+ *   history/document undo does not fire alongside yours.
+ */
+declare function registerHistoryHotkeys(history?: MkHistoryStack): () => void;
+
+/**
+ * A single hotkey combo parsed into a normalized key + modifier flags.
+ * Produced by {@link mkParseHotkey}; consumed by {@link mkMatchesHotkey}.
+ */
+interface MkParsedHotkey {
+    /** The non-modifier key, lowercased and alias-normalized (e.g. `k`, `escape`, `?`). */
+    key: string;
+    /** `mod` — Cmd on macOS, Ctrl elsewhere. */
+    mod: boolean;
+    /** The Control key. */
+    ctrl: boolean;
+    /** The Meta / Command / Windows key. */
+    meta: boolean;
+    /** The Alt / Option key. */
+    alt: boolean;
+    /** The Shift key. */
+    shift: boolean;
+}
+/** Options accepted by {@link MkHotkeysService.register}. */
+interface MkHotkeyOptions {
+    /** Call `preventDefault()` on the event when the hotkey fires. Default `false`. */
+    preventDefault?: boolean;
+    /** Also fire while an editable field (input/textarea/select/contentEditable) is focused. Default `false`. */
+    allowInInput?: boolean;
+}
+/**
+ * Parse a single hotkey combo (e.g. `'mod+k'`, `'ctrl+shift+p'`, `'?'`) into a
+ * structured {@link MkParsedHotkey}. Tokens are joined by `+`; the last
+ * non-modifier token is the trigger key. Pure and SSR-safe.
+ *
+ * For a chord (space-separated sequence like `'g i'`), split on whitespace and
+ * parse each step — {@link MkHotkeysService} does this for you.
+ */
+declare function mkParseHotkey(combo: string): MkParsedHotkey;
+/**
+ * Does a `keydown` event satisfy a hotkey? `combo` may be a raw string (parsed
+ * on the fly) or an already-parsed {@link MkParsedHotkey}.
+ *
+ * The key is compared case-insensitively; modifier flags must match exactly.
+ * `mod` resolves to Meta on macOS and Ctrl elsewhere. Shift is not enforced for
+ * symbol keys (e.g. `'?'`), whose shifted state varies by keyboard layout.
+ */
+declare function mkMatchesHotkey(event: KeyboardEvent, combo: string | MkParsedHotkey): boolean;
+/**
+ * MkHotkeysService — app-wide keyboard shortcuts. Register a combo string and a
+ * handler; a single `keydown` listener (attached lazily on the first
+ * registration, browser only) dispatches to every match.
+ *
+ * Supports single combos (`'mod+k'`, `'ctrl+shift+p'`, `'?'`) and simple
+ * two-step chords (`'g i'`). By default hotkeys are ignored while an editable
+ * field is focused — pass `allowInInput` to opt in per registration.
+ *
+ * ```ts
+ * const off = hotkeys.register('mod+k', (e) => openPalette(), { preventDefault: true });
+ * // …later
+ * off();
+ * ```
+ */
+declare class MkHotkeysService {
+    private readonly document;
+    private readonly isBrowser;
+    private readonly registrations;
+    private attached;
+    /** The first key of an in-progress chord, awaiting its second key. */
+    private pendingEvent;
+    private pendingTimer?;
+    /**
+     * Register `combo` → `handler`. Returns a disposer that unregisters it.
+     * `combo` may be a single combo or a space-separated two-step chord.
+     */
+    register(combo: string, handler: (e: KeyboardEvent) => void, options?: MkHotkeyOptions): () => void;
+    /** Remove every registration and detach the listener. */
+    unregisterAll(): void;
+    private ensureAttached;
+    private detach;
+    private readonly onKeydown;
+    private trigger;
+    private clearPending;
+    private isEditable;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MkHotkeysService, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<MkHotkeysService>;
+}
+
+/**
+ * `[mkHotkey]` — declaratively bind a keyboard shortcut to a host element.
+ *
+ * When the combo fires, a `<button>` or `<a>` host is `click()`ed; any other
+ * host emits `(mkHotkeyPressed)`. Registration is scoped to the element's
+ * lifetime (auto-unregistered on destroy) via {@link MkHotkeysService}.
+ *
+ * ```html
+ * <button mkHotkey="mod+s" (click)="save()">Save</button>
+ * <div mkHotkey="?" (mkHotkeyPressed)="showHelp()">…</div>
+ * ```
+ */
+declare class MkHotkey {
+    private readonly host;
+    private readonly hotkeys;
+    /** The combo (or space-separated chord) to bind, e.g. `mod+k`, `g i`, `?`. */
+    readonly mkHotkey: _angular_core.InputSignal<string>;
+    /** Fire even while an editable field is focused. */
+    readonly mkHotkeyAllowInInput: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Call `preventDefault()` when the hotkey fires. Defaults to `true`. */
+    readonly mkHotkeyPreventDefault: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Emitted when the hotkey fires and the host is not a button/link. */
+    readonly mkHotkeyPressed: _angular_core.OutputEmitterRef<KeyboardEvent>;
+    /**
+     * The combo in `aria-keyshortcuts` syntax — per-step tokens `+`-joined
+     * (`Control+K`), chord steps space-separated (`G I`). Exposed on the host.
+     */
+    protected readonly ariaKeyshortcuts: _angular_core.Signal<string | null>;
+    private dispose?;
+    constructor();
+    private onTrigger;
+    ngOnDestroy(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MkHotkey, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<MkHotkey, "[mkHotkey]", ["mkHotkey"], { "mkHotkey": { "alias": "mkHotkey"; "required": true; "isSignal": true; }; "mkHotkeyAllowInInput": { "alias": "mkHotkeyAllowInInput"; "required": false; "isSignal": true; }; "mkHotkeyPreventDefault": { "alias": "mkHotkeyPreventDefault"; "required": false; "isSignal": true; }; }, { "mkHotkeyPressed": "mkHotkeyPressed"; }, never, never, true, never>;
+}
+
+/**
+ * Permission policy — the contract the permission directives (`*mkCan`,
+ * `*mkCannot`, `[mkCanDisable]`) check against. Provide an implementation
+ * once at bootstrap; the directives inject it optionally and, when no policy
+ * is provided at all, treat every permission as **granted** — an app that
+ * never wires permissions must not have its whole UI hidden.
+ *
+ * `can` may return a plain `boolean` (static role checks) or a
+ * `Signal<boolean>` (live permissions). The directives normalise both, and a
+ * signal-returning policy re-evaluates reactively: views appear/disappear and
+ * controls enable/disable the moment the underlying permissions change.
+ *
+ * ```ts
+ * // A signal-based policy fed from an auth service:
+ * @Injectable()
+ * export class AppPermissionPolicy extends MkPermissionPolicy {
+ *   private readonly auth = inject(AuthService);
+ *
+ *   can(permission: string): Signal<boolean> {
+ *     // auth.permissions is a Signal<string[]> that updates on login/logout.
+ *     return computed(() => this.auth.permissions().includes(permission));
+ *   }
+ * }
+ *
+ * bootstrapApplication(App, {
+ *   providers: [
+ *     { provide: MkPermissionPolicy, useClass: AppPermissionPolicy },
+ *   ],
+ * });
+ * ```
+ *
+ * A static policy is just as valid:
+ *
+ * ```ts
+ * class StaticPolicy extends MkPermissionPolicy {
+ *   can(permission: string): boolean {
+ *     return CURRENT_USER.permissions.includes(permission);
+ *   }
+ * }
+ * ```
+ */
+declare abstract class MkPermissionPolicy {
+    /**
+     * Whether the current user holds `permission`. Return a `Signal<boolean>`
+     * to make the verdict live; a plain boolean is treated as static.
+     */
+    abstract can(permission: string): boolean | Signal<boolean>;
+}
+/**
+ * Resolve a policy verdict to a boolean, unwrapping signal-based results.
+ * Call it inside a reactive context (`computed` / `effect`) so a
+ * signal-returning policy stays live. A missing policy grants everything.
+ */
+declare function mkPermissionGranted(policy: MkPermissionPolicy | null, permission: string): boolean;
+
+/**
+ * Structural directive that renders its template only while the app's
+ * {@link MkPermissionPolicy} grants the given permission. With a
+ * signal-based policy the check is live — the view is created and destroyed
+ * as permissions change. When no policy is provided, everything is granted.
+ *
+ * ```html
+ * <button *mkCan="'posts.delete'" (click)="remove()">Delete</button>
+ *
+ * <!-- With a fallback template, like *ngIf's else: -->
+ * <section *mkCan="'billing.view'; else locked">…</section>
+ * <ng-template #locked><mk-empty-state title="No access" /></ng-template>
+ * ```
+ */
+declare class MkCan {
+    /** The permission key to check, e.g. `'posts.delete'`. */
+    readonly permission: _angular_core.InputSignal<string>;
+    /** Template rendered while the permission is denied (`; else ref`). */
+    readonly elseTemplate: _angular_core.InputSignal<TemplateRef<unknown> | null>;
+    constructor();
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MkCan, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<MkCan, "[mkCan]", never, { "permission": { "alias": "mkCan"; "required": true; "isSignal": true; }; "elseTemplate": { "alias": "mkCanElse"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+/**
+ * The negation of {@link MkCan}: renders its template only while the
+ * permission is **denied** — for upsell hints, "ask an admin" notes and the
+ * like. With no policy provided everything is granted, so `*mkCannot`
+ * renders nothing.
+ *
+ * ```html
+ * <p *mkCannot="'reports.export'">Exporting requires an admin role.</p>
+ * ```
+ */
+declare class MkCannot {
+    /** The permission key to check. */
+    readonly permission: _angular_core.InputSignal<string>;
+    /** Template rendered while the permission is granted (`; else ref`). */
+    readonly elseTemplate: _angular_core.InputSignal<TemplateRef<unknown> | null>;
+    constructor();
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MkCannot, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<MkCannot, "[mkCannot]", never, { "permission": { "alias": "mkCannot"; "required": true; "isSignal": true; }; "elseTemplate": { "alias": "mkCannotElse"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Disables the host while the app's {@link MkPermissionPolicy} denies the
+ * given permission — the "keep it visible but inert" alternative to `*mkCan`
+ * for buttons, inputs and menu items.
+ *
+ * While denied, the host gets `aria-disabled="true"`, and — when the element
+ * supports it (button, input, select, textarea, fieldset…) — its native
+ * `disabled` property is set too. Non-disableable elements (links, custom
+ * menu items) get `aria-disabled` only; pair it with CSS / a click guard as
+ * needed. The directive owns the disabled state: it also re-enables the host
+ * when the permission is granted. With a signal-based policy the state flips
+ * live; with no policy provided, everything is granted.
+ *
+ * ```html
+ * <button [mkCanDisable]="'posts.delete'" (click)="remove()">Delete</button>
+ * <a [mkCanDisable]="'billing.view'" routerLink="/billing">Billing</a>
+ * ```
+ */
+declare class MkCanDisable {
+    private readonly policy;
+    private readonly host;
+    /** The permission key to check, e.g. `'posts.delete'`. */
+    readonly permission: _angular_core.InputSignal<string>;
+    /** Whether the permission is currently denied. */
+    protected readonly denied: _angular_core.Signal<boolean>;
+    constructor();
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MkCanDisable, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<MkCanDisable, "[mkCanDisable]", never, { "permission": { "alias": "mkCanDisable"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+export { MK_FIELD_PRESETS, MkAutofocus, MkAutosize, MkCan, MkCanDisable, MkCannot, MkClickOutside, MkCopyToClipboard, MkField, MkHistoryService, MkHistoryStack, MkHotkey, MkHotkeysService, MkInfiniteScroll, MkIntersect, MkMask, MkPermissionPolicy, MkRipple, MkScrollspy, mkApplyMask, mkMaskCaret, mkMatchesHotkey, mkParseHotkey, mkPermissionGranted, registerHistoryHotkeys };
+export type { MkFieldKind, MkFieldPreset, MkHistoryEntry, MkHotkeyOptions, MkMaskResult, MkParsedHotkey };