@mk-kit/ui 0.34.0

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

@@ -0,0 +1,423 @@
+import * as _angular_core from '@angular/core';
+import { TemplateRef } from '@angular/core';
+
+/**
+ * Optional grip that restricts where a pointer drag of the enclosing
+ * `[mkDrag]` may begin. Place it on the element the user should press to drag;
+ * without any handle the whole item is draggable.
+ *
+ * A directive (not a component), so it composes onto anything — a `<span>`,
+ * a `<button>`, or another component's host such as `<mk-icon mkDragHandle />`.
+ * Its look (grab cursor, muted colour, `touch-action: none`) ships as the
+ * global `.mk-drag-handle` class in the theme stylesheet.
+ *
+ * ```html
+ * <div mkDrag [mkDragData]="row">
+ *   <span mkDragHandle aria-hidden="true">⠿</span>
+ *   {{ row.name }}
+ * </div>
+ * ```
+ */
+declare class MkDragHandle {
+    /** The handle's host element. */
+    readonly element: HTMLElement;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MkDragHandle, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<MkDragHandle, "[mkDragHandle]", ["mkDragHandle"], {}, {}, never, never, true, never>;
+}
+
+/**
+ * Makes an item inside a `[mkDropList]` draggable — by pointer (mouse / touch /
+ * pen) **and** by keyboard (WCAG 2.1.1). The item is focusable, exposes
+ * `role="button"` + `aria-roledescription="Draggable item"`, and every move is
+ * announced via {@link MkLiveAnnouncer}.
+ *
+ * Keyboard: focus an item and press **Space/Enter** to pick it up, **Arrow**
+ * keys to move it (crossing into connected lists at the ends / across the
+ * perpendicular axis), **Space/Enter** to drop, **Escape** to cancel.
+ *
+ * Touch: a swipe scrolls the page as usual — the drag only arms after a
+ * long-press ({@link mkDragTouchDelay}, default 300 ms). While armed the item
+ * gets the `mk-drag--armed` class so consumers can style the lift moment.
+ * Mouse and pen drags start immediately, as before.
+ *
+ * Performance: pointer moves are rAF-coalesced (one hit-test + one set of
+ * style/DOM writes per frame) against list/item rects snapshotted when the
+ * drag lifts, so a move never forces layout. The pending frame is flushed
+ * synchronously on release so drops land exactly where the pointer ended.
+ *
+ * ```html
+ * <li mkDrag [mkDragData]="row" [mkDragDisabled]="row.locked">
+ *   <span mkDragHandle aria-hidden="true">⠿</span> {{ row.title }}
+ * </li>
+ * ```
+ *
+ * @typeParam T item data type.
+ */
+declare class MkDrag<T = unknown> {
+    private readonly doc;
+    private readonly registry;
+    private readonly announcer;
+    private readonly i18n;
+    private readonly home;
+    /** The item's host element. */
+    readonly element: HTMLElement;
+    /** Arbitrary payload associated with this item. */
+    readonly mkDragData: _angular_core.InputSignal<T | undefined>;
+    /** Disable dragging this specific item. */
+    readonly mkDragDisabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * Long-press delay (ms) before a *touch* pointer arms the drag. Until it
+     * elapses a swipe scrolls natively; moving more than {@link TOUCH_SLOP}
+     * pixels abandons the pending drag. `0` arms immediately (legacy behavior).
+     * Mouse and pen are never delayed.
+     */
+    readonly mkDragTouchDelay: _angular_core.InputSignalWithTransform<number, unknown>;
+    /** Every handle in the projected subtree, including those of nested drags. */
+    private readonly handles;
+    /**
+     * Handles that belong to *this* drag — i.e. whose nearest `[mkDrag]` ancestor
+     * is this item, not a nested one. A nested `[mkDropList]`/`[mkDrag]` (a
+     * product list inside a draggable category, say) would otherwise have its
+     * handles captured by the outer item via `descendants: true`, so pressing an
+     * inner handle would start the outer drag and inner dnd would never work.
+     */
+    protected readonly ownHandles: _angular_core.Signal<MkDragHandle[]>;
+    /** True while a pointer drag is in progress. */
+    protected readonly dragging: _angular_core.WritableSignal<boolean>;
+    /** True while the item is "picked up" for keyboard movement. */
+    protected readonly lifted: _angular_core.WritableSignal<boolean>;
+    /** True from the moment a touch long-press arms the drag until release. */
+    protected readonly armed: _angular_core.WritableSignal<boolean>;
+    /** Whether the home list lays items out horizontally (scopes touch-action). */
+    protected readonly inHorizontalList: _angular_core.Signal<boolean>;
+    /** Effective disabled state (item- or list-level). */
+    readonly disabled: _angular_core.Signal<boolean>;
+    private targetList;
+    private targetIndex;
+    private homeIndex;
+    private placeholder;
+    private pointerId;
+    private started;
+    private startX;
+    private startY;
+    private offsetX;
+    private offsetY;
+    private originLeft;
+    private originTop;
+    private preview;
+    private readonly moveHandler;
+    private readonly upHandler;
+    private readonly cancelHandler;
+    /** Gate for the move handler: mouse/pen arm on pointerdown, touch on timer. */
+    private pointerArmed;
+    private touchTimer;
+    /** Inline `touch-action` to restore after a drag locked it (null = not locked). */
+    private savedTouchAction;
+    /**
+     * `touch-action: pan-y` (see drag.scss) keeps native scrolling alive while
+     * the long-press is pending, but that also means the browser may still start
+     * a scroll once we *are* dragging — so the armed drag must eat `touchmove`.
+     * Registered with `passive: false` for `preventDefault` to register.
+     */
+    private readonly touchMoveHandler;
+    /** Android fires `contextmenu` on long-press — keep it off the gesture. */
+    private readonly contextMenuHandler;
+    /** Pending rAF id for the coalesced move pass, if any. */
+    private moveRaf;
+    private pendingX;
+    private pendingY;
+    private hasPendingMove;
+    /** Connected lists resolved once at lift (stable for the drag's duration). */
+    private cachedGroup;
+    /** List bounds snapshotted at lift / after invalidation. */
+    private readonly listRects;
+    /** Item bounds per list, aligned with `itemElementsExcept(this)`. */
+    private readonly itemRects;
+    /** Lists whose snapshots a placeholder move invalidated (re-measured next frame). */
+    private readonly dirtyLists;
+    /** Any scroll moves everything — re-snapshot every list on the next frame. */
+    private scrollDirty;
+    private readonly scrollHandler;
+    /** Last placeholder sync target — makes `syncPlaceholder` idempotent. */
+    private lastSyncList;
+    private lastSyncIndex;
+    protected onPointerDown(event: Event): void;
+    private onPointerMove;
+    /** The long-press delay elapsed with the finger still down — lift. */
+    private armTouch;
+    private lockTouchAction;
+    private unlockTouchAction;
+    /** Undo everything the touch path set up (timer, listeners, lock, class). */
+    private clearTouchState;
+    private onPointerUp;
+    private beginPointer;
+    /** Coalesce move handling to at most one layout pass per animation frame. */
+    private scheduleMoveFrame;
+    /**
+     * Cancel the scheduled frame; when `apply` is set, process the pending
+     * coordinates synchronously (flush-on-end, like the table column resize) so
+     * a drop lands exactly where the pointer stopped.
+     */
+    private flushMoveFrame;
+    /**
+     * The per-frame move pass. Ordered reads → writes: refresh invalidated
+     * snapshots first, resolve the hovered list/index from the cache, then do
+     * all style/DOM writes — no read ever follows a write within the frame.
+     */
+    private applyPendingMove;
+    private finishPointer;
+    private commitPointer;
+    protected onKeyDown(event: Event): void;
+    protected onBlur(): void;
+    private pickUp;
+    private stepPrimary;
+    private stepList;
+    private moveToList;
+    private dropKeyboard;
+    private cancelKeyboard;
+    /** "Picked up…" instructions when a keyboard drag starts. */
+    private announcePickedUp;
+    /** Position update after each keyboard step (names the list when crossing). */
+    private announceMove;
+    /** Confirmation after a successful drop (pointer: polite; keyboard: assertive). */
+    private announceDropped;
+    /** The drag was cancelled and the item snapped back. */
+    private announceCancelled;
+    /** Highest valid target index for `list` given the item is being removed. */
+    private maxIndex;
+    private adjacentList;
+    /** Snapshot every connected list's bounds + item bounds (at lift / scroll). */
+    private snapshotRects;
+    /** (Re)measure one list's bounds and item bounds into the cache. */
+    private measureList;
+    /**
+     * Which connected list (if any) the pointer is currently over. Pointer path
+     * only — reads the rects snapshotted at lift, not live layout.
+     */
+    private listUnderPoint;
+    /**
+     * Insertion index for the pointer position within `list`. Pointer path only
+     * — reads the cached item rects (live measurement is the fallback for a
+     * list that somehow joined the group mid-drag).
+     */
+    private indexInList;
+    private syncPlaceholder;
+    private createPlaceholder;
+    private createPreview;
+    /** Remove the body-level preview + placeholder if destroyed mid-drag. */
+    ngOnDestroy(): void;
+    private destroyed;
+    private cleanupDom;
+    private emit;
+    private isHandleTarget;
+    private prefersReducedMotion;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MkDrag<any>, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MkDrag<any>, "[mkDrag]", ["mkDrag"], { "mkDragData": { "alias": "mkDragData"; "required": false; "isSignal": true; }; "mkDragDisabled": { "alias": "mkDragDisabled"; "required": false; "isSignal": true; }; "mkDragTouchDelay": { "alias": "mkDragTouchDelay"; "required": false; "isSignal": true; }; }, {}, ["handles"], ["*"], true, never>;
+}
+
+/**
+ * A drop container for reorderable `[mkDrag]` items.
+ *
+ * - **Sort list:** a single `[mkDropList]` over an array — items reorder within it.
+ * - **Buckets / kanban:** several `[mkDropList]`s wired together with
+ *   `mkDropListConnectedTo` so items transfer between them (both by pointer and
+ *   by keyboard at the ends of a list).
+ *
+ * The array bound to `mkDropListData` is **not** mutated for you — handle
+ * `mkDropListDropped` and call {@link mkMoveItemInArray} / {@link mkTransferArrayItem}.
+ *
+ * ```html
+ * <ul mkDropList [mkDropListData]="todo()"
+ *     mkDropListId="todo" [mkDropListConnectedTo]="['done']"
+ *     (mkDropListDropped)="drop($event)">
+ *   @for (t of todo(); track t.id) {
+ *     <li mkDrag [mkDragData]="t">{{ t.title }}</li>
+ *   }
+ * </ul>
+ * ```
+ *
+ * @typeParam T item data type.
+ */
+declare class MkDropList<T = unknown> {
+    private readonly registry;
+    /** The list's host element (drop target bounds). */
+    readonly element: HTMLElement;
+    /** The array backing the list. Bound, never mutated by the directive. */
+    readonly mkDropListData: _angular_core.InputSignal<readonly T[]>;
+    /** Stable id used to connect lists. Auto-generated when omitted. */
+    readonly mkDropListId: _angular_core.InputSignal<string | undefined>;
+    /** Ids of other lists items may be transferred into. */
+    readonly mkDropListConnectedTo: _angular_core.InputSignal<readonly string[]>;
+    /**
+     * Human-readable name used in screen-reader announcements when an item is
+     * moved into this list (e.g. `"In progress"`). Falls back to the list `id`
+     * — which may be auto-generated gibberish — so set it wherever users can
+     * move items across lists by keyboard.
+     */
+    readonly mkDropListLabel: _angular_core.InputSignal<string>;
+    /** Layout axis; controls pointer hit-testing and arrow-key direction. */
+    readonly mkDropListOrientation: _angular_core.InputSignal<MkDropListOrientation>;
+    /** Disable dropping into (and dragging out of) this list. */
+    readonly mkDropListDisabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Fires when an item is dropped into this list (pointer or keyboard). */
+    readonly mkDropListDropped: _angular_core.OutputEmitterRef<MkDropEvent<T>>;
+    /** Resolved id (input or generated). */
+    readonly id: _angular_core.Signal<string>;
+    private readonly autoId;
+    /** Announceable name: the label when set, otherwise the resolved id. */
+    readonly label: _angular_core.Signal<string>;
+    /** Connected-list ids, normalised to a plain array. */
+    readonly connectedTo: _angular_core.Signal<readonly string[]>;
+    /** The `mkDrag` items projected into this list, in DOM order. */
+    private readonly drags;
+    /** Highlight while a drag is hovering this list. */
+    protected readonly _receiving: _angular_core.WritableSignal<boolean>;
+    constructor();
+    /** Number of drag items currently in the list. */
+    size(): number;
+    /** Index of `drag` among this list's items, or -1. */
+    indexOf(drag: MkDrag<any>): number;
+    /** Host elements of this list's items, excluding `exclude`, in DOM order. */
+    itemElementsExcept(exclude: MkDrag<any>): HTMLElement[];
+    /** Toggle the "receiving" highlight (called by the active drag). */
+    setReceiving(value: boolean): void;
+    /** Emit a drop into this list. Called by the active `MkDrag`. */
+    emitDrop(event: MkDropEvent<any>): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MkDropList<any>, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MkDropList<any>, "[mkDropList]", ["mkDropList"], { "mkDropListData": { "alias": "mkDropListData"; "required": false; "isSignal": true; }; "mkDropListId": { "alias": "mkDropListId"; "required": false; "isSignal": true; }; "mkDropListConnectedTo": { "alias": "mkDropListConnectedTo"; "required": false; "isSignal": true; }; "mkDropListLabel": { "alias": "mkDropListLabel"; "required": false; "isSignal": true; }; "mkDropListOrientation": { "alias": "mkDropListOrientation"; "required": false; "isSignal": true; }; "mkDropListDisabled": { "alias": "mkDropListDisabled"; "required": false; "isSignal": true; }; }, { "mkDropListDropped": "mkDropListDropped"; }, ["drags"], ["*"], true, never>;
+}
+
+/** Layout axis a drop list lays its items along. */
+type MkDropListOrientation = 'vertical' | 'horizontal';
+/**
+ * Emitted by `[mkDropList]` (`mkDropListDropped`) when an item is dropped.
+ *
+ * Mirrors the shape of Angular CDK's `CdkDragDrop` so the exported
+ * {@link mkMoveItemInArray} / {@link mkTransferArrayItem} helpers can be used
+ * exactly as their CDK counterparts:
+ *
+ * ```ts
+ * onDrop(e: MkDropEvent) {
+ *   if (e.previousContainer === e.container) {
+ *     mkMoveItemInArray(e.container.mkDropListData(), e.previousIndex, e.currentIndex);
+ *   } else {
+ *     mkTransferArrayItem(
+ *       e.previousContainer.mkDropListData(),
+ *       e.container.mkDropListData(),
+ *       e.previousIndex, e.currentIndex,
+ *     );
+ *   }
+ * }
+ * ```
+ *
+ * @typeParam T item data type.
+ */
+interface MkDropEvent<T = unknown> {
+    /** Index of the item within `previousContainer`'s data before the drop. */
+    previousIndex: number;
+    /** Index the item should occupy within `container`'s data after the drop. */
+    currentIndex: number;
+    /** The `MkDrag` directive instance that was moved. */
+    item: MkDrag<T>;
+    /** The list the item came from. */
+    previousContainer: MkDropList<T>;
+    /** The list the item was dropped into (same as `previousContainer` for a re-sort). */
+    container: MkDropList<T>;
+    /** `true` for pointer (mouse/touch/pen) drops, `false` for keyboard drops. */
+    isPointerEvent: boolean;
+}
+
+/**
+ * Pure array helpers for applying an {@link MkDropEvent}. They mutate the passed
+ * array(s) in place and also return the (target) array, mirroring the behaviour
+ * of Angular CDK's `moveItemInArray` / `transferArrayItem`.
+ */
+/**
+ * Move an item within a single array from `fromIndex` to `toIndex`.
+ * Mutates and returns `array`.
+ *
+ * ```ts
+ * mkMoveItemInArray(rows, e.previousIndex, e.currentIndex);
+ * ```
+ */
+declare function mkMoveItemInArray<T>(array: T[], fromIndex: number, toIndex: number): T[];
+/**
+ * Move an item from one array (`from`) to another (`to`), removing it from
+ * `from[fromIndex]` and inserting it at `to[toIndex]`. Mutates both arrays and
+ * returns the target (`to`) array.
+ *
+ * ```ts
+ * mkTransferArrayItem(todo, done, e.previousIndex, e.currentIndex);
+ * ```
+ */
+declare function mkTransferArrayItem<T>(from: T[], to: T[], fromIndex: number, toIndex: number): T[];
+
+/**
+ * Central registry of every live `[mkDropList]` on the page, keyed by id.
+ *
+ * Connected lists (kanban "buckets") use it to resolve the sibling lists named
+ * in `mkDropListConnectedTo`, and both pointer and keyboard dragging use it to
+ * find the group of lists an item may travel between.
+ *
+ * Registration is automatic — you never call this service directly; it is
+ * documented so tooling/tests can inspect the wiring.
+ */
+declare class MkDragDropRegistry {
+    private readonly lists;
+    /** Register (or replace) the list published under `id`. */
+    register(id: string, list: MkDropList<any>): void;
+    /** Remove `list` from the registry if it is still the holder of `id`. */
+    unregister(id: string, list: MkDropList<any>): void;
+    /** Look up a list by its `mkDropListId`. */
+    get(id: string): MkDropList<any> | undefined;
+    /** All registered lists, in registration order. */
+    all(): MkDropList<any>[];
+    /**
+     * The ordered travel group for `list`: `list` itself plus every enabled list
+     * it is `mkDropListConnectedTo`, in registration (roughly DOM) order. Used to
+     * resolve "adjacent" lists for keyboard column-to-column movement and to
+     * hit-test the pointer against candidate targets.
+     */
+    connectedGroup(list: MkDropList<any>): MkDropList<any>[];
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MkDragDropRegistry, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<MkDragDropRegistry>;
+}
+
+/**
+ * Thin convenience wrapper over a single `[mkDropList]` for the common
+ * "reorderable list" case. Bind `items` two-way and provide an `<ng-template>`
+ * to render each row; drops are applied to the model for you (via
+ * {@link mkMoveItemInArray}).
+ *
+ * For connected buckets / kanban, use `[mkDropList]` + `[mkDrag]` directly.
+ *
+ * ```html
+ * <mk-sortable-list [(items)]="rows">
+ *   <ng-template let-row let-i="index">
+ *     <span mkDragHandle aria-hidden="true">⠿</span> {{ i + 1 }}. {{ row.name }}
+ *   </ng-template>
+ * </mk-sortable-list>
+ * ```
+ *
+ * @typeParam T item data type.
+ */
+declare class MkSortableList<T = unknown> {
+    /** The ordered items (two-way). Reordered in place on drop. */
+    readonly items: _angular_core.ModelSignal<T[]>;
+    /** Layout axis of the list. */
+    readonly orientation: _angular_core.InputSignal<MkDropListOrientation>;
+    /** Disable reordering. */
+    readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** `@for` tracking function. Defaults to identity (track by item). */
+    readonly trackBy: _angular_core.InputSignal<(index: number, item: T) => unknown>;
+    /** Emitted after the model has been reordered. */
+    readonly sorted: _angular_core.OutputEmitterRef<MkDropEvent<T>>;
+    /** The row template projected as `<ng-template>`. */
+    protected readonly itemTemplate: _angular_core.Signal<TemplateRef<any>>;
+    protected onDrop(event: MkDropEvent<T>): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MkSortableList<any>, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MkSortableList<any>, "mk-sortable-list", never, { "items": { "alias": "items"; "required": false; "isSignal": true; }; "orientation": { "alias": "orientation"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "trackBy": { "alias": "trackBy"; "required": false; "isSignal": true; }; }, { "items": "itemsChange"; "sorted": "sorted"; }, ["itemTemplate"], never, true, never>;
+}
+
+export { MkDrag, MkDragDropRegistry, MkDragHandle, MkDropList, MkSortableList, mkMoveItemInArray, mkTransferArrayItem };
+export type { MkDropEvent, MkDropListOrientation };