@mk-kit/ui 0.34.0

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

@@ -0,0 +1,739 @@
+import * as _mk_kit_ui_table from '@mk-kit/ui/table';
+import * as _angular_core from '@angular/core';
+import { TemplateRef, Signal } from '@angular/core';
+import * as _mk_kit_ui_core from '@mk-kit/ui/core';
+import { Observable } from 'rxjs';
+
+/**
+ * Marks an `<ng-template>` as the expandable detail content for {@link MkTable}
+ * rows. The template's implicit context is the row object, so consumers can
+ * destructure it with `let-row`:
+ *
+ * ```html
+ * <mk-table [columns]="cols" [data]="rows()" expandable>
+ *   <ng-template mkTableRowDetail let-row>
+ *     <dl>… {{ row.notes }} …</dl>
+ *   </ng-template>
+ * </mk-table>
+ * ```
+ */
+declare class MkTableRowDetail<T = unknown> {
+    /** The projected detail template, rendered once per expanded row. */
+    readonly template: TemplateRef<{
+        $implicit: T;
+    }>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MkTableRowDetail<any>, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<MkTableRowDetail<any>, "[mkTableRowDetail]", never, {}, {}, never, never, true, never>;
+}
+
+/** Horizontal text alignment for a table column. */
+type MkTableAlign = 'start' | 'center' | 'end';
+/** Sort direction; `none` means unsorted. */
+type MkSortDirection = 'asc' | 'desc' | 'none';
+/** Row vertical density. */
+type MkTableDensity = 'comfortable' | 'compact';
+/** Column definition for {@link MkTable}. */
+interface MkTableColumn<T = Record<string, unknown>> {
+    /** Property key on each row object supplying the cell value. */
+    key: string;
+    /** Visible column header text. */
+    header: string;
+    /** Allow sorting by this column. */
+    sortable?: boolean;
+    /** Cell/header alignment (default `start`). */
+    align?: MkTableAlign;
+    /** Fixed column width (any CSS length). */
+    width?: string;
+    /** Optional formatter turning the raw value into display text. */
+    format?: (value: unknown, row: T) => string;
+    /** Allow the user to drag-resize this column (needs `resizableColumns`). */
+    resizable?: boolean;
+    /** Make this column's cells inline-editable (double-click / Enter). */
+    editable?: boolean;
+    /** Pin (freeze) this column to a side while the body scrolls horizontally. */
+    pinned?: 'left' | 'right';
+    /** Minimum width in px when resizing (default 60). */
+    minWidth?: number;
+    /**
+     * What becomes of this column when the table stacks into cards
+     * (see {@link MkTable.stackAt}). Omitted, the column renders as a labelled
+     * field: its `header` on one side, its value on the other.
+     *
+     * - `'title'` — the card's heading. No label; the value identifies the
+     *   record at a glance (an order number, a product name). Mark one, or two
+     *   if something short belongs beside it such as a status or a total.
+     * - `'footer'` — pinned to the bottom of the card, full width and unlabelled.
+     *   Where an actions cell belongs: buttons read as buttons, rather than as
+     *   the answer to a label.
+     * - `'hide'` — not rendered at all. Not merely invisible: the cell is never
+     *   created, so a screen reader does not read it either. For columns that
+     *   only earn their place while scanning a grid, and especially for anything
+     *   an expandable row detail already repeats.
+     */
+    stack?: 'title' | 'footer' | 'hide';
+}
+/** Payload emitted by {@link MkTable.sortChange}. */
+interface MkSortChange {
+    /** Column key sorted by. */
+    key: string;
+    /** Resulting direction (`none` when sorting was cleared). */
+    direction: MkSortDirection;
+}
+/** Payload emitted by {@link MkTable.columnResize} after a column resize. */
+interface MkColumnResize {
+    /** The resized column's key. */
+    key: string;
+    /** The new width in pixels. */
+    width: number;
+}
+/** Payload emitted by {@link MkTable.cellEdit} when an editable cell is saved. */
+interface MkCellEdit<T = Record<string, unknown>> {
+    /** The edited row. */
+    row: T;
+    /** The column key that was edited. */
+    key: string;
+    /** The new (string) value the user entered. */
+    value: string;
+}
+/** A group of rows produced by {@link MkTable.groupBy}. */
+interface MkTableGroup<T = Record<string, unknown>> {
+    /** The shared group value. */
+    key: unknown;
+    /** Display label for the group header. */
+    label: string;
+    /** The rows in this group, in display (sorted) order. */
+    rows: T[];
+}
+/** Payload emitted by {@link MkTable.groupToggle}. */
+interface MkGroupToggle {
+    /** The toggled group's value. */
+    key: unknown;
+    /** Whether the group is now collapsed. */
+    collapsed: boolean;
+}
+/** One rendered tbody entry: either a group header or a data row. */
+type MkTableItem<T> = {
+    kind: 'group';
+    group: MkTableGroup<T>;
+} | {
+    kind: 'row';
+    row: T;
+};
+/**
+ * Table — a themed data table built on a native `<table>` for accessibility.
+ * Supply `columns` and `data`; opt into sortable columns, sticky header,
+ * zebra striping, hover and density. Sorting is fully keyboard operable
+ * (Enter/Space on a header) and announces changes via {@link MkLiveAnnouncer}.
+ *
+ * ```html
+ * <mk-table
+ *   [columns]="columns"
+ *   [data]="rows()"
+ *   stickyHeader
+ *   zebra
+ *   (sortChange)="onSort($event)"
+ *   (rowClick)="open($event)" />
+ * ```
+ */
+declare class MkTable<T = Record<string, unknown>> {
+    private readonly announcer;
+    protected readonly i18n: _mk_kit_ui_core.MkI18nStrings;
+    private readonly document;
+    private readonly host;
+    private readonly injector;
+    private readonly isBrowser;
+    private readonly destroyRef;
+    /**
+     * True while the table is narrower than {@link stackAt} and rendering cards.
+     *
+     * Driven by the element's own width rather than the viewport's: the question
+     * "do these columns fit" is about the space the table HAS, not the size of
+     * the screen. A table in a sidebar or a dialog should stack while the window
+     * around it is enormous.
+     */
+    protected readonly stacked: _angular_core.WritableSignal<boolean>;
+    constructor();
+    /** Measures the thead and exposes it as the group rows' sticky offset. */
+    private applyGroupTop;
+    /** Column definitions (order = display order). */
+    readonly columns: _angular_core.InputSignal<MkTableColumn<T>[]>;
+    /** Row objects to render. */
+    readonly data: _angular_core.InputSignal<T[]>;
+    /** Pin the header to the top of the scroll container. */
+    readonly stickyHeader: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Alternate row background for readability. */
+    readonly zebra: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Highlight rows on hover. */
+    readonly hover: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Row density. */
+    readonly density: _angular_core.InputSignal<MkTableDensity>;
+    /**
+     * Width in px below which each row renders as a CARD instead of a table row.
+     * `0` (default) never stacks.
+     *
+     * Measured on the table's own container, not the viewport — a table in a
+     * narrow sidebar should stack on a desktop, and a table on a tablet in
+     * landscape should not. Per-column behaviour is set with
+     * {@link MkTableColumn.stack}.
+     *
+     * A grid cannot survive a phone: eight columns become eight unreadable
+     * slivers, and horizontal scrolling loses the row you were reading. Cards
+     * keep one record together and put its header beside each value.
+     */
+    readonly stackAt: _angular_core.InputSignalWithTransform<number, unknown>;
+    /** Style rows as clickable and emit `rowClick`. */
+    readonly clickableRows: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Message shown when there are no rows. */
+    readonly emptyMessage: _angular_core.InputSignal<string>;
+    /** Render a leading checkbox column for row selection. */
+    readonly selectable: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * Two-way bound array of selected rows. Use `[(selected)]` to bind, or read
+     * `selectionChange`. Rows are compared by {@link trackKey} when set, else by
+     * referential identity.
+     */
+    readonly selected: _angular_core.ModelSignal<T[]>;
+    /**
+     * Property name identifying a row for selection equality. When omitted rows
+     * are matched by reference.
+     */
+    readonly trackKey: _angular_core.InputSignal<string | undefined>;
+    /**
+     * Optional per-row CSS class: called with each row, the returned string is
+     * appended to the row's class list (falsy → none). For state the consumer
+     * owns — an "active in the side panel" highlight, an unread accent — that
+     * `selectable`'s own selected style doesn't cover.
+     */
+    readonly rowClass: _angular_core.InputSignal<((row: T) => string | null | undefined) | null>;
+    /** Resolved class for a row (empty string when no `rowClass` is set). */
+    protected rowClassFor(row: T): string;
+    /**
+     * Render a leading expander column. Each row can reveal a detail panel
+     * supplied via an `<ng-template mkTableRowDetail let-row>`.
+     */
+    readonly expandable: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Allow only one row expanded at a time (accordion). */
+    readonly singleExpand: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Enable drag-to-resize on columns marked `resizable` (data-grid pro). */
+    readonly resizableColumns: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Enable drag-to-reorder of column headers (data-grid pro). */
+    readonly reorderableColumns: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * Group rows by a column key or an accessor. Renders a collapsible group
+     * header row (sticky, with a row count) above each group. Sorting still
+     * applies within groups; groups follow their first row's sorted position.
+     */
+    readonly groupBy: _angular_core.InputSignal<string | ((row: T) => unknown) | null>;
+    /** Formats a group header label; defaults to `String(value)`. */
+    readonly groupLabel: _angular_core.InputSignal<((value: unknown, rows: T[]) => string) | null>;
+    /** Emitted when the sort column/direction changes. */
+    readonly sortChange: _angular_core.OutputEmitterRef<MkSortChange>;
+    /** Emitted when a row is clicked (enable via `clickableRows`). */
+    readonly rowClick: _angular_core.OutputEmitterRef<T>;
+    /** Emitted with the new selection whenever it changes (enable via `selectable`). */
+    readonly selectionChange: _angular_core.OutputEmitterRef<T[]>;
+    /** Emitted with the currently expanded rows whenever they change. */
+    readonly expandedChange: _angular_core.OutputEmitterRef<T[]>;
+    /** Emitted when a column is resized (px). */
+    readonly columnResize: _angular_core.OutputEmitterRef<MkColumnResize>;
+    /** Emitted with the new column key order after a reorder. */
+    readonly columnReorder: _angular_core.OutputEmitterRef<string[]>;
+    /** Emitted when an inline-editable cell is saved. */
+    readonly cellEdit: _angular_core.OutputEmitterRef<MkCellEdit<T>>;
+    /** Emitted when a group header is expanded or collapsed. */
+    readonly groupToggle: _angular_core.OutputEmitterRef<MkGroupToggle>;
+    /** User-set column widths (px), keyed by column key. */
+    private readonly colWidths;
+    /** User-set column order (keys); `null` = the input order. */
+    private readonly colOrder;
+    /** The cell currently being inline-edited. */
+    protected readonly editing: _angular_core.WritableSignal<{
+        index: number;
+        key: string;
+    } | null>;
+    /** Columns in display order, honouring any user reordering. */
+    protected readonly orderedColumns: _angular_core.Signal<MkTableColumn<T>[]>;
+    /** Columns forming the card's heading line. */
+    protected readonly stackTitleColumns: _angular_core.Signal<MkTableColumn<T>[]>;
+    /** Columns rendered as `label / value` rows in the card body. */
+    protected readonly stackFieldColumns: _angular_core.Signal<MkTableColumn<T>[]>;
+    /** Columns pinned to the bottom of the card, unlabelled. */
+    protected readonly stackFooterColumns: _angular_core.Signal<MkTableColumn<T>[]>;
+    /**
+     * Whether a stacked cell should show its column header as a label.
+     *
+     * An empty header means the column never had a name to show — an actions or
+     * chevron column — and an empty label box would just be a gap the reader has
+     * to account for.
+     */
+    protected hasStackLabel(col: MkTableColumn<T>): boolean;
+    /** The rendered width for a column, if the user resized it. */
+    protected colStyleWidth(col: MkTableColumn<T>): string | null;
+    /** Sticky offsets for every pinned column, computed once per layout change. */
+    private readonly pinnedOffsets;
+    /** Sticky offset (px) for a pinned column. */
+    protected pinnedOffset(col: MkTableColumn<T>): number;
+    /** Pinning freezes a column against horizontal scroll. Cards do not scroll
+     *  sideways, so both the class and its inline offset are suppressed. */
+    protected isPinned(col: MkTableColumn<T>, side: 'left' | 'right'): boolean;
+    private numericWidth;
+    private resizeKey;
+    private resizeStartX;
+    private resizeStartW;
+    private resizeMin;
+    /** +1 in LTR, -1 in RTL — dragging toward the inline-end always widens. */
+    private resizeSign;
+    /** Whether the table currently renders right-to-left (SSR-safe). */
+    private isRtl;
+    private resizeRaf;
+    private pendingResizeX;
+    /** Begin a drag-resize from a header handle. */
+    protected startResize(event: PointerEvent, col: MkTableColumn<T>): void;
+    /** rAF-coalesced: at most one width write (and CD pass) per frame. */
+    private readonly onResizeMove;
+    private applyPendingResize;
+    private readonly onResizeEnd;
+    /** Keyboard column resize on the focused separator (APG window splitter). */
+    protected onResizeKeydown(event: KeyboardEvent, col: MkTableColumn<T>): void;
+    /** The current width of a column, for the separator's aria-valuenow. */
+    protected resizeValueNow(col: MkTableColumn<T>): number;
+    /** The resize floor for a column, for the separator's aria-valuemin. */
+    protected resizeValueMin(col: MkTableColumn<T>): number;
+    /** Advertised resize ceiling (aria-valuemax) — a sane constant bound. */
+    protected readonly resizeValueMax = 2000;
+    ngOnDestroy(): void;
+    protected readonly dragKey: _angular_core.WritableSignal<string | null>;
+    protected onColDragStart(event: DragEvent, col: MkTableColumn<T>): void;
+    protected onColDragOver(event: DragEvent): void;
+    protected onColDrop(event: DragEvent, target: MkTableColumn<T>): void;
+    protected onColDragEnd(): void;
+    /** Move a column to `toIdx` in the display order and announce it. */
+    private moveColumn;
+    /** Keyboard column reorder: Alt+Arrow moves the focused header. */
+    protected onReorderKeydown(event: KeyboardEvent, col: MkTableColumn<T>): void;
+    protected isEditing(index: number, col: MkTableColumn<T>): boolean;
+    /** The cell element being edited, so focus can be restored after. */
+    private editingCell;
+    /** The inline-edit input, focused once it renders. */
+    private readonly editInput;
+    protected startEdit(index: number, col: MkTableColumn<T>, event?: Event): void;
+    /** Keyboard path into edit mode (Enter / F2 on a focused editable cell). */
+    protected onCellKeydown(event: KeyboardEvent, index: number, col: MkTableColumn<T>): void;
+    protected commitEdit(row: T, col: MkTableColumn<T>, value: string, restoreFocus?: boolean): void;
+    protected cancelEdit(restoreFocus?: boolean): void;
+    protected onEditKeydown(event: KeyboardEvent, row: T, col: MkTableColumn<T>): void;
+    /** The projected row-detail template (enable via `expandable`). */
+    protected readonly rowDetail: _angular_core.Signal<MkTableRowDetail<any> | undefined>;
+    /** Per-column cell templates, projected as `<ng-template mkTableCell="key">`. */
+    private readonly cellTemplates;
+    private readonly cellTemplateByKey;
+    /** The template registered for a column, or null to fall back to text. */
+    protected cellTemplateFor(key: string): _angular_core.TemplateRef<_mk_kit_ui_table.MkTableCellContext<unknown>> | null;
+    private readonly sortKey;
+    private readonly sortDir;
+    /** Stable id prefix so each detail row can be referenced by aria-controls. */
+    private readonly detailIdBase;
+    /** Total rendered columns, including the select and expander columns. */
+    protected readonly totalColumns: _angular_core.Signal<number>;
+    /**
+     * Shared locale-sensitive collator for string sorting. `localeCompare`
+     * re-resolves locale data on every call; one cached `Intl.Collator` makes
+     * large-table sorts several-fold faster with the same default-locale order.
+     */
+    private static readonly sortCollator;
+    /** Data sorted by the active column, or the input order when unsorted. */
+    protected readonly sortedData: _angular_core.Signal<T[]>;
+    /** `aria-sort` value for a header cell. */
+    protected ariaSort(col: MkTableColumn<T>): string | null;
+    /** Glyph indicating a column's sort state. */
+    protected sortGlyph(col: MkTableColumn<T>): string;
+    /** Raw cell value, handed to an `[mkTableCell]` template unformatted. */
+    protected cellValue(row: T, col: MkTableColumn<T>): unknown;
+    /** Rendered text for a cell, applying the column formatter if present. */
+    protected cellText(row: T, col: MkTableColumn<T>): string;
+    protected onSort(col: MkTableColumn<T>): void;
+    protected onRowClick(row: T): void;
+    /** Keyboard activation for clickable rows (Enter / Space). */
+    protected onRowKeydown(event: KeyboardEvent, row: T): void;
+    /** Stable row identity for `@for` tracking (trackKey when set, else the row). */
+    protected trackRow: (row: T) => unknown;
+    /** Leading cell text used to label per-row controls for screen readers. */
+    protected rowLabel(row: T): string;
+    private rowKey;
+    /** Selected row keys as a Set — O(1) membership per cell per CD pass. */
+    private readonly selectedKeys;
+    /** Whether `row` is currently selected. */
+    protected isSelected(row: T): boolean;
+    /** True when every visible row is selected. */
+    protected readonly allSelected: _angular_core.Signal<boolean>;
+    /** True when some — but not all — visible rows are selected. */
+    protected readonly someSelected: _angular_core.Signal<boolean>;
+    private commitSelection;
+    /** Toggle a single row's selection without triggering `rowClick`. */
+    protected toggleRow(row: T): void;
+    /** Select or deselect all visible rows. */
+    protected toggleAll(): void;
+    /** Group values currently collapsed. */
+    private readonly collapsedGroups;
+    /** Rows grouped by {@link groupBy}, or `null` when grouping is off. */
+    protected readonly groups: _angular_core.Signal<MkTableGroup<T>[] | null>;
+    /**
+     * The tbody render list: group headers interleaved with their (expanded)
+     * rows when grouping is on, else just the sorted rows.
+     */
+    protected readonly displayItems: _angular_core.Signal<MkTableItem<T>[]>;
+    /** `@for` identity: group headers by value, rows by {@link trackRow}. */
+    protected trackItem: (item: MkTableItem<T>) => unknown;
+    /** Whether a group is currently collapsed. */
+    protected isGroupCollapsed(key: unknown): boolean;
+    /** Collapse or expand a group header. */
+    protected onGroupToggle(group: MkTableGroup<T>): void;
+    /** Collapse every group. */
+    collapseAllGroups(): void;
+    /** Expand every group. */
+    expandAllGroups(): void;
+    private readonly expandedKeys;
+    /** Whether `row`'s detail panel is currently expanded. */
+    protected isExpanded(row: T): boolean;
+    /** The DOM id of a row's detail panel (for `aria-controls`). */
+    protected detailId(index: number): string;
+    /** Toggle a row's detail panel, honouring `singleExpand`. */
+    protected toggleExpand(row: T, event?: Event): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MkTable<any>, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MkTable<any>, "mk-table", never, { "columns": { "alias": "columns"; "required": true; "isSignal": true; }; "data": { "alias": "data"; "required": false; "isSignal": true; }; "stickyHeader": { "alias": "stickyHeader"; "required": false; "isSignal": true; }; "zebra": { "alias": "zebra"; "required": false; "isSignal": true; }; "hover": { "alias": "hover"; "required": false; "isSignal": true; }; "density": { "alias": "density"; "required": false; "isSignal": true; }; "stackAt": { "alias": "stackAt"; "required": false; "isSignal": true; }; "clickableRows": { "alias": "clickableRows"; "required": false; "isSignal": true; }; "emptyMessage": { "alias": "emptyMessage"; "required": false; "isSignal": true; }; "selectable": { "alias": "selectable"; "required": false; "isSignal": true; }; "selected": { "alias": "selected"; "required": false; "isSignal": true; }; "trackKey": { "alias": "trackKey"; "required": false; "isSignal": true; }; "rowClass": { "alias": "rowClass"; "required": false; "isSignal": true; }; "expandable": { "alias": "expandable"; "required": false; "isSignal": true; }; "singleExpand": { "alias": "singleExpand"; "required": false; "isSignal": true; }; "resizableColumns": { "alias": "resizableColumns"; "required": false; "isSignal": true; }; "reorderableColumns": { "alias": "reorderableColumns"; "required": false; "isSignal": true; }; "groupBy": { "alias": "groupBy"; "required": false; "isSignal": true; }; "groupLabel": { "alias": "groupLabel"; "required": false; "isSignal": true; }; }, { "selected": "selectedChange"; "sortChange": "sortChange"; "rowClick": "rowClick"; "selectionChange": "selectionChange"; "expandedChange": "expandedChange"; "columnResize": "columnResize"; "columnReorder": "columnReorder"; "cellEdit": "cellEdit"; "groupToggle": "groupToggle"; }, ["rowDetail", "cellTemplates"], ["[mkTableEmpty]"], true, never>;
+}
+
+/** Context handed to an `[mkTableCell]` template. */
+interface MkTableCellContext<T = unknown> {
+    /** The cell's raw value (the row's property named by the column key). */
+    $implicit: unknown;
+    /** The whole row, for cells that need more than one field. */
+    row: T;
+}
+/**
+ * Marks an `<ng-template>` as the renderer for one column's cells, named by the
+ * column `key`. Without it a cell can only be text — `MkTableColumn.format`
+ * returns a string — so anything richer (a status tag, an avatar, a progress
+ * bar, an action button) meant abandoning `mk-table` for a hand-rolled
+ * `<table>`.
+ *
+ * The value is the template's implicit context and the row is available as
+ * `let-row`:
+ *
+ * ```html
+ * <mk-table [columns]="cols" [data]="rows()">
+ *   <ng-template mkTableCell="status" let-value let-row="row">
+ *     <mk-tag [tone]="toneFor(value)">{{ label(value) }}</mk-tag>
+ *   </ng-template>
+ * </mk-table>
+ * ```
+ *
+ * A column with both a template and a `format` uses the template; `format`
+ * still applies to sorting/export paths that need a string.
+ */
+declare class MkTableCell<T = unknown> {
+    /** Column key whose cells this template renders. */
+    readonly mkTableCell: _angular_core.InputSignal<string>;
+    /** The projected template, rendered once per cell in that column. */
+    readonly template: TemplateRef<MkTableCellContext<T>>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MkTableCell<any>, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<MkTableCell<any>, "[mkTableCell]", never, { "mkTableCell": { "alias": "mkTableCell"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/** Current sort state emitted by {@link MkSort.mkSortChange}. */
+interface MkSortState {
+    /** Id of the column being sorted by (empty when cleared). */
+    active: string;
+    /** Sort direction (`none` when cleared). */
+    direction: MkSortDirection;
+}
+/**
+ * The minimal shape {@link MkSort} needs from a header. Implemented by
+ * {@link MkSortHeader}; declared separately so the coordinator does not depend
+ * on the header's concrete type (avoids a circular import).
+ */
+interface MkSortable {
+    id(): string;
+    start(): 'asc' | 'desc' | undefined;
+    disabled(): boolean;
+    sortLabel(): string;
+}
+/**
+ * Sort coordinator — apply `mkSort` to a table (or any container) to track
+ * which column is sorted and in which direction. It holds no data: register
+ * headers with `mkSortHeader`, then re-sort your rows in the
+ * `(mkSortChange)` handler. Mirrors the Angular Material `matSort` model but
+ * signal-based.
+ *
+ * Clicking a header cycles asc → desc → unsorted (set `mkSortDisableClear` to
+ * cycle asc ↔ desc only). `mkSortStart` flips the initial direction.
+ *
+ * ```html
+ * <table mkSort mkSortActive="name" mkSortDirection="asc"
+ *        (mkSortChange)="sortData($event)">
+ *   <thead><tr>
+ *     <th mkSortHeader="name">Name</th>
+ *     <th mkSortHeader="size" mkSortHeaderStart="desc">Size</th>
+ *   </tr></thead>
+ *   …
+ * </table>
+ * ```
+ */
+declare class MkSort {
+    private readonly announcer;
+    private readonly i18n;
+    /** Id of the currently sorted column (two-way; empty when unsorted). */
+    readonly active: _angular_core.ModelSignal<string>;
+    /** Current sort direction (two-way). */
+    readonly direction: _angular_core.ModelSignal<MkSortDirection>;
+    /** Direction the first click on a header applies. Default `asc`. */
+    readonly start: _angular_core.InputSignal<"asc" | "desc">;
+    /** Disable sorting for every header. */
+    readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Remove the "unsorted" step so headers cycle asc ↔ desc only. */
+    readonly disableClear: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Emits the new sort state whenever a header is activated. */
+    readonly sortChange: _angular_core.OutputEmitterRef<MkSortState>;
+    /** Advance the sort state for the given header (called on click/keyboard). */
+    sort(header: MkSortable): void;
+    /** Whether the given column id is the active, non-cleared sort. */
+    isActive(id: string): boolean;
+    private startFor;
+    private nextDirection;
+    private announce;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MkSort, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<MkSort, "[mkSort]", ["mkSort"], { "active": { "alias": "mkSortActive"; "required": false; "isSignal": true; }; "direction": { "alias": "mkSortDirection"; "required": false; "isSignal": true; }; "start": { "alias": "mkSortStart"; "required": false; "isSignal": true; }; "disabled": { "alias": "mkSortDisabled"; "required": false; "isSignal": true; }; "disableClear": { "alias": "mkSortDisableClear"; "required": false; "isSignal": true; }; }, { "active": "mkSortActiveChange"; "direction": "mkSortDirectionChange"; "sortChange": "mkSortChange"; }, never, never, true, never>;
+}
+
+/**
+ * Sort header — attach `mkSortHeader` to a header cell (`<th>`) inside an
+ * element carrying `mkSort`. It wraps the projected header text in a real
+ * `<button>` (so assistive tech hears an operable control), adds a directional
+ * arrow (faint on hover, solid when active), reflects `aria-sort` on the cell,
+ * and toggles the sort on click or Enter/Space.
+ *
+ * ```html
+ * <th mkSortHeader="email" mkSortHeaderLabel="Email address">Email</th>
+ * ```
+ */
+declare class MkSortHeader implements MkSortable {
+    private readonly sort;
+    /** Column id this header sorts by (the `mkSortHeader` value). */
+    readonly id: _angular_core.InputSignal<string>;
+    /** Per-header override for the initial sort direction. */
+    readonly start: _angular_core.InputSignal<"asc" | "desc" | undefined>;
+    /** Disable sorting for just this header. */
+    readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Accessible label used in sort announcements (defaults to the id). */
+    readonly sortLabel: _angular_core.InputSignal<string>;
+    /** Disabled if this header or the whole `mkSort` is disabled. */
+    readonly isDisabled: _angular_core.Signal<boolean>;
+    /** Whether this header is the active, non-cleared sort. */
+    readonly isActive: _angular_core.Signal<boolean>;
+    /** Active direction, or `none` when this header is not the active sort. */
+    readonly direction: _angular_core.Signal<MkSortDirection>;
+    /** `aria-sort` value for the header cell. */
+    protected readonly ariaSort: _angular_core.Signal<"none" | "ascending" | "descending">;
+    protected toggle(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MkSortHeader, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MkSortHeader, "[mkSortHeader]", never, { "id": { "alias": "mkSortHeader"; "required": false; "isSignal": true; }; "start": { "alias": "mkSortHeaderStart"; "required": false; "isSignal": true; }; "disabled": { "alias": "mkSortHeaderDisabled"; "required": false; "isSignal": true; }; "sortLabel": { "alias": "mkSortHeaderLabel"; "required": false; "isSignal": true; }; }, {}, never, ["*"], true, never>;
+}
+
+/** The request handed to a {@link MkDataFetcher} on every load. */
+interface MkDataRequest {
+    /** 1-based page index, matching `mk-pagination`. */
+    page: number;
+    /** Number of rows per page. */
+    pageSize: number;
+    /** Active sort, or `null` when unsorted (cleared sorts normalise to `null`). */
+    sort: MkSortState | null;
+    /** Free-text filter query (`''` = none). */
+    filter: string;
+}
+/** One page of server data returned by a {@link MkDataFetcher}. */
+interface MkDataPage<T> {
+    /** The rows for the requested page. */
+    rows: T[];
+    /** Total number of rows across ALL pages (drives the pager). */
+    total: number;
+}
+/**
+ * Loads one page of data for a {@link MkDataRequest}. May return a `Promise`
+ * (e.g. `fetch`) or an `Observable` (e.g. `HttpClient`); an Observable is
+ * treated as single-shot — the first emission wins and the subscription is
+ * released.
+ */
+type MkDataFetcher<T> = (req: MkDataRequest) => Promise<MkDataPage<T>> | Observable<MkDataPage<T>>;
+/** Construction options for {@link MkTableDataSource}. */
+interface MkTableDataSourceOptions {
+    /** Initial rows per page (default 10, matching `mk-pagination`). */
+    pageSize?: number;
+    /** Debounce for {@link MkTableDataSource.setFilter} in ms (default 300). */
+    filterDebounce?: number;
+}
+/**
+ * Server-side data adapter for `mk-table` — the page/sort/filter plumbing every
+ * admin screen otherwise hand-rolls. A plain class (no component, no injection
+ * required): give it a fetcher and bind its signals; every setter re-queries
+ * the server and **stale responses never overwrite newer state** (latest-wins).
+ *
+ * - `setFilter` is debounced (default 300 ms); page, sort and page size load
+ *   immediately. Sort, filter and page-size changes reset to page 1.
+ * - `rows` keeps its previous value while loading and on error, so the table
+ *   never blanks mid-transition; `error` is cleared by the next successful
+ *   load.
+ * - Created in an injection context (a component field initialiser) it hooks
+ *   `DestroyRef` and cleans up automatically; anywhere else, call
+ *   {@link destroy} yourself.
+ *
+ * ```ts
+ * interface User { id: number; name: string; email: string; }
+ *
+ * @Component({
+ *   imports: [MkTable, MkPagination, MkInput],
+ *   template: `
+ *     <input
+ *       mkInput
+ *       type="search"
+ *       placeholder="Search users…"
+ *       (input)="ds.setFilter($any($event.target).value)"
+ *     />
+ *
+ *     <mk-table
+ *       [columns]="columns"
+ *       [data]="ds.rows()"
+ *       (sortChange)="ds.setSort($event)"
+ *     />
+ *     @if (ds.error()) { <p role="alert">Failed to load.</p> }
+ *     @if (ds.empty()) { <p>No users match.</p> }
+ *
+ *     <mk-pagination
+ *       [total]="ds.total()"
+ *       [pageSize]="ds.pageSize()"
+ *       [page]="ds.page()"
+ *       (pageChange)="ds.setPage($event)"
+ *     />
+ *   `,
+ * })
+ * export class UsersPage {
+ *   private readonly http = inject(HttpClient);
+ *
+ *   readonly columns: MkTableColumn<User>[] = [
+ *     { key: 'name', header: 'Name', sortable: true },
+ *     { key: 'email', header: 'Email', sortable: true },
+ *   ];
+ *
+ *   // Field initialiser = injection context, so cleanup is automatic.
+ *   readonly ds = new MkTableDataSource<User>(
+ *     (req) =>
+ *       this.http.get<MkDataPage<User>>('/api/users', {
+ *         params: {
+ *           page: req.page,
+ *           size: req.pageSize,
+ *           q: req.filter,
+ *           ...(req.sort && {
+ *             sort: `${req.sort.active},${req.sort.direction}`,
+ *           }),
+ *         },
+ *       }),
+ *     { pageSize: 20 },
+ *   );
+ * }
+ * ```
+ *
+ * With a custom `mkSort` table, forward the directive instead of binding:
+ *
+ * ```ts
+ * private readonly sort = viewChild.required(MkSort);
+ * constructor() {
+ *   afterNextRender(() => this.ds.connectSort(this.sort()));
+ * }
+ * ```
+ */
+declare class MkTableDataSource<T> {
+    private readonly fetcher;
+    private readonly debounceMs;
+    private readonly _rows;
+    private readonly _total;
+    private readonly _loading;
+    private readonly _error;
+    private readonly _page;
+    private readonly _pageSize;
+    private readonly _sort;
+    private readonly _filter;
+    /** Rows of the current page (`[]` until the first load lands). */
+    readonly rows: Signal<T[]>;
+    /** Total row count across all pages (feed to `mk-pagination`'s `total`). */
+    readonly total: Signal<number>;
+    /** True while the LATEST request is in flight. */
+    readonly loading: Signal<boolean>;
+    /** The last load's error, or `null`; cleared by the next successful load. */
+    readonly error: Signal<unknown>;
+    /** Current 1-based page. */
+    readonly page: Signal<number>;
+    /** Current page size. */
+    readonly pageSize: Signal<number>;
+    /** Current sort, or `null` when unsorted. */
+    readonly sort: Signal<MkSortState | null>;
+    /** Current filter query (updates immediately, even while debouncing). */
+    readonly filter: Signal<string>;
+    /** True when a settled load reported no rows at all. */
+    readonly empty: Signal<boolean>;
+    /** Monotonic request id — settles from older epochs are discarded. */
+    private epoch;
+    /** Subscription to an in-flight Observable fetch, if any. */
+    private activeSub;
+    /** Pending filter-debounce timer. */
+    private filterTimer;
+    /** Subscriptions created by {@link connectSort}, keyed for idempotence. */
+    private readonly sortSubs;
+    private destroyed;
+    constructor(fetcher: MkDataFetcher<T>, opts?: MkTableDataSourceOptions);
+    /** Jump to a 1-based page and load it immediately. */
+    setPage(page: number): void;
+    /** Change the page size; resets to page 1 and loads immediately. */
+    setPageSize(size: number): void;
+    /**
+     * Change the sort; resets to page 1 and loads immediately. Accepts either
+     * the `mkSort` directive's {@link MkSortState} or `mk-table`'s
+     * {@link MkSortChange} payload; a cleared sort (`direction: 'none'` or an
+     * empty column id) normalises to `null`. A no-op when the sort is unchanged.
+     */
+    setSort(sort: MkSortState | MkSortChange | null): void;
+    /**
+     * Change the free-text filter. The `filter` signal updates (and the page
+     * resets to 1) immediately, but the request is debounced — `refresh()`
+     * flushes it early. A no-op when the query is unchanged.
+     */
+    setFilter(query: string): void;
+    /**
+     * Re-run the current request immediately (e.g. after a mutation). Flushes a
+     * pending debounced filter, since the request reads the live filter value.
+     */
+    refresh(): void;
+    /**
+     * Pipe an `mkSort` directive's changes into {@link setSort}. Idempotent per
+     * directive instance; all subscriptions are released by {@link destroy}.
+     */
+    connectSort(sort: MkSort): void;
+    /**
+     * Cancel pending work: the debounce timer, any in-flight Observable fetch,
+     * and `connectSort` subscriptions. In-flight Promise settles are discarded.
+     * Called automatically on host destroy when created in an injection context.
+     */
+    destroy(): void;
+    /** Start a load for the current request state; supersedes any in flight. */
+    private load;
+    /** Subscribe single-shot: first emission (or error) settles, then release. */
+    private runObservable;
+    /** Apply a successful settle, unless a newer request superseded it. */
+    private settleSuccess;
+    /** Record a failed settle (rows/total untouched), unless superseded. */
+    private settleError;
+    private cancelDebounce;
+    private unsubscribeActive;
+    private clearSub;
+}
+
+export { MkSort, MkSortHeader, MkTable, MkTableCell, MkTableDataSource, MkTableRowDetail };
+export type { MkCellEdit, MkColumnResize, MkDataFetcher, MkDataPage, MkDataRequest, MkGroupToggle, MkSortChange, MkSortDirection, MkSortState, MkSortable, MkTableAlign, MkTableCellContext, MkTableColumn, MkTableDataSourceOptions, MkTableDensity, MkTableGroup };