@zeyos/zx 4.1.0 → 4.2.0

package/dist/types/components/kanban-view/kanban-view.d.ts

@@ -0,0 +1,572 @@
+import { RecordView } from '../view/record-view.js';
+export type KanbanRecord = Record<string, any>;
+export type RecordViewOptions = import('../view/record-view.js').RecordViewOptions;
+export type RecordCardPreview = import('../card-view/record-card.js').RecordCardPreview;
+export type RecordCardLink = import('../card-view/record-card.js').RecordCardLink;
+export type RecordCardAction = import('../card-view/record-card.js').RecordCardAction;
+export type KanbanAccessor = string | ((record: KanbanRecord, index: number) => unknown) | null;
+export type KanbanCardField = string | ((record: KanbanRecord, index: number) => unknown) | null;
+export type KanbanMovePoint = {
+    /**
+     * Column id.
+     */
+    column: string;
+    /**
+     * Swim-lane id, or null when lanes are disabled.
+     */
+    lane: string | null;
+    /**
+     * Zero-based position within the destination column and lane.
+     */
+    index: number;
+};
+export type KanbanMoveContext = {
+    /**
+     * Record id.
+     */
+    id: unknown;
+    /**
+     * Original position.
+     */
+    from: KanbanMovePoint;
+    /**
+     * Proposed position.
+     */
+    to: KanbanMovePoint;
+    /**
+     * Destination column.
+     */
+    column: KanbanColumn;
+    /**
+     * Destination lane.
+     */
+    swimlane: KanbanSwimlane | null;
+};
+export type KanbanColumn = {
+    /**
+     * Stable column id.
+     */
+    id: string;
+    /**
+     * Visible column label.
+     */
+    label: string;
+    /**
+     * Value written by local moves; defaults to `id`.
+     */
+    value?: unknown;
+    /**
+     * Advisory work-in-progress limit.
+     */
+    limit?: number | null;
+    /**
+     * Eligibility
+     * predicate. Returning false rejects the move before the cancelable event is emitted.
+     */
+    accept?: (record: KanbanRecord, context: KanbanMoveContext) => boolean;
+};
+export type KanbanSwimlane = {
+    /**
+     * Stable lane id.
+     */
+    id: string;
+    /**
+     * Visible lane label.
+     */
+    label: string;
+    /**
+     * Value written by local moves; defaults to `id`.
+     */
+    value?: unknown;
+    /**
+     * Eligibility
+     * predicate. Returning false rejects the move before the cancelable event is emitted.
+     */
+    accept?: (record: KanbanRecord, context: KanbanMoveContext) => boolean;
+};
+export type KanbanDestination = {
+    /**
+     * Destination column; omitted keeps the current column.
+     */
+    column?: string;
+    /**
+     * Destination lane; omitted keeps the current lane.
+     */
+    lane?: string | null;
+    /**
+     * Zero-based destination position; omitted appends.
+     */
+    index?: number;
+};
+export type KanbanViewState = {
+    /**
+     * State schema version.
+     */
+    version: 1;
+    /**
+     * Shared field order.
+     */
+    fieldOrder: string[];
+    /**
+     * Shared hidden fields.
+     */
+    hiddenFields: string[];
+    /**
+     * Shared sort.
+     */
+    sort: {
+        id: string;
+        dir: 'asc' | 'desc';
+    } | null;
+    /**
+     * Column order.
+     */
+    columnOrder: string[];
+    /**
+     * Swim-lane order.
+     */
+    swimlaneOrder: string[];
+    /**
+     * Collapsed column ids.
+     */
+    collapsedColumns: string[];
+    /**
+     * Collapsed swim-lane ids.
+     */
+    collapsedSwimlanes: string[];
+};
+export type KanbanViewOptions = {
+    /**
+     * Shared field descriptors.
+     */
+    fields?: import('../view/record-view.js').ViewField[];
+    /**
+     * Records.
+     */
+    data?: KanbanRecord[];
+    /**
+     * Stable record id accessor.
+     */
+    recordId?: string | ((record: KanbanRecord) => unknown);
+    /**
+     * Shared initial sort.
+     */
+    sort?: {
+        id: string;
+        dir: 'asc' | 'desc';
+    } | null;
+    /**
+     * Shared sort mode.
+     */
+    sortMode?: 'local' | 'server';
+    /**
+     * Shared selection mode.
+     */
+    selectable?: false | 'single' | 'multi';
+    /**
+     * Initial record ids.
+     */
+    selection?: unknown[];
+    /**
+     * Shared field order.
+     */
+    fieldOrder?: string[];
+    /**
+     * Shared hidden fields.
+     */
+    hiddenFields?: string[];
+    /**
+     * Show shared field controls.
+     */
+    fieldControls?: boolean;
+    /**
+     * Empty-board content.
+     */
+    emptyText?: string | Node | (() => string | Node) | null;
+    /**
+     * Column accessor.
+     */
+    columnBy?: KanbanAccessor;
+    /**
+     * Explicit columns, or null to derive them.
+     */
+    columns?: KanbanColumn[] | null;
+    /**
+     * Optional swim-lane accessor.
+     */
+    swimlaneBy?: KanbanAccessor;
+    /**
+     * Explicit lanes, or null to derive them.
+     */
+    swimlanes?: KanbanSwimlane[] | null;
+    /**
+     * Card title field or reader.
+     */
+    titleField?: KanbanCardField;
+    /**
+     * Card subtitle field or reader.
+     */
+    subtitleField?: KanbanCardField;
+    /**
+     * Preview field or reader.
+     */
+    preview?: string | ((record: KanbanRecord, index: number) => RecordCardPreview) | null;
+    /**
+     * Preview alternative-text field or reader.
+     */
+    previewAlt?: KanbanCardField;
+    /**
+     * Record-card primary link descriptor or reader.
+     */
+    link?: RecordCardLink | ((record: KanbanRecord, index: number) => RecordCardLink) | null;
+    /**
+     * Card actions.
+     */
+    actions?: RecordCardAction[] | ((record: KanbanRecord, index: number) => RecordCardAction[]);
+    /**
+     * Whether accepted moves update local data.
+     */
+    moveMode?: 'local' | 'external';
+    /**
+     * Preferred column order.
+     */
+    columnOrder?: string[];
+    /**
+     * Preferred swim-lane order.
+     */
+    swimlaneOrder?: string[];
+    /**
+     * Initially collapsed columns.
+     */
+    collapsedColumns?: string[];
+    /**
+     * Initially collapsed lanes.
+     */
+    collapsedSwimlanes?: string[];
+    /**
+     * Show record counts and WIP indicators.
+     */
+    showCounts?: boolean;
+    /**
+     * Keep configured empty columns visible.
+     */
+    showEmptyColumns?: boolean;
+    /**
+     * Shared record-card treatment.
+     */
+    variant?: 'outlined' | 'raised' | 'filled';
+    /**
+     * Accessible board label.
+     */
+    label?: string;
+    onrecordmove?: (event: CustomEvent<Record<string, unknown>>) => void;
+    onrecordaction?: (event: CustomEvent<Record<string, unknown>>) => void;
+};
+export type KanbanCardMeta = {
+    record: KanbanRecord;
+    id: unknown;
+    index: number;
+    column: string;
+    lane: string | null;
+};
+export type KanbanSectionMeta = {
+    column: string;
+    lane: string | null;
+    list: HTMLElement;
+};
+export type KanbanKeyboardMove = {
+    id: unknown;
+    from: KanbanMovePoint;
+    to: KanbanMovePoint;
+};
+/**
+ * Configurable record board with semantic columns, optional swim lanes, and equivalent pointer and
+ * keyboard movement. Local moves clone records; callback grouping remains fully usable for display
+ * and external moves but cannot be written safely by local cross-axis moves.
+ * @fires KanbanView#recordmove
+ * @fires KanbanView#recordaction
+ * @extends {RecordView}
+ */
+export declare class KanbanView extends RecordView {
+    _kanbanSnapshot: import("../../core/dom.js").TargetSnapshot;
+    _kanbanDestroyed: boolean;
+    _kanbanColumns: KanbanColumn[];
+    _kanbanSwimlanes: KanbanColumn[];
+    _kanbanColumnOrder: string[];
+    _kanbanSwimlaneOrder: string[];
+    _collapsedColumns: Set<string>;
+    _collapsedSwimlanes: Set<string>;
+    _keyboardMove: KanbanKeyboardMove | {
+        id: unknown;
+        from: {
+            column: string;
+            lane: string | null;
+            index: number;
+        };
+        to: {
+            column: string;
+            lane: string | null;
+            index: number;
+        };
+    };
+    _dragId: unknown;
+    _dragDestination: KanbanMovePoint;
+    _announcementToken: number;
+    _cardMeta: WeakMap<object, any>;
+    _sectionMeta: WeakMap<object, any>;
+    _cardsById: Map<any, any>;
+    _toolbar: HTMLElement;
+    _board: HTMLElement;
+    _live: HTMLElement;
+    static cssName: string;
+    /** @type {Readonly<KanbanViewOptions & RecordViewOptions>} */
+    static defaults: Readonly<KanbanViewOptions & RecordViewOptions>;
+    /**
+     * Creates a Kanban record view.
+     * @param {Element|string|null} [target=null] Existing root, selector, or null.
+     * @param {KanbanViewOptions & RecordViewOptions} [options={}] Kanban and shared record-view options.
+     */
+    constructor(target?: Element | string | null, options?: KanbanViewOptions & RecordViewOptions);
+    /** @returns {HTMLElement} Board root. */
+    render(): HTMLElement;
+    /** Returns resolved columns in visual order. @returns {KanbanColumn[]} */
+    getColumns(): KanbanColumn[];
+    /**
+     * Replaces configured columns. Pass null to derive them from current data.
+     * @param {KanbanColumn[]|null} columns Columns.
+     * @returns {this}
+     */
+    setColumns(columns: KanbanColumn[] | null): this;
+    /** Returns resolved lane descriptors in visual order. @returns {KanbanSwimlane[]} */
+    getSwimlanes(): KanbanSwimlane[];
+    /**
+     * Replaces configured lanes. Pass null to derive them from current data.
+     * @param {KanbanSwimlane[]|null} lanes Lanes.
+     * @returns {this}
+     */
+    setSwimlanes(lanes: KanbanSwimlane[] | null): this;
+    /** Returns the current resolved column order. @returns {string[]} */
+    getColumnOrder(): string[];
+    /**
+     * Reconciles and applies a preferred column order.
+     * @param {string[]} order Preferred ids.
+     * @param {{silent?:boolean}} [options={}] Event behavior.
+     * @returns {this}
+     */
+    setColumnOrder(order: string[], options?: {
+        silent?: boolean;
+    }): this;
+    /**
+     * Moves a column relative to another.
+     * @param {string} id Moving id.
+     * @param {string} targetId Target id.
+     * @param {'before'|'after'} [position='before'] Target edge.
+     * @returns {this}
+     */
+    moveColumn(id: string, targetId: string, position?: 'before' | 'after'): this;
+    /** Returns the current resolved lane order. @returns {string[]} */
+    getSwimlaneOrder(): string[];
+    /**
+     * Reconciles and applies a preferred lane order.
+     * @param {string[]} order Preferred ids.
+     * @param {{silent?:boolean}} [options={}] Event behavior.
+     * @returns {this}
+     */
+    setSwimlaneOrder(order: string[], options?: {
+        silent?: boolean;
+    }): this;
+    /**
+     * Moves a lane relative to another.
+     * @param {string} id Moving id.
+     * @param {string} targetId Target id.
+     * @param {'before'|'after'} [position='before'] Target edge.
+     * @returns {this}
+     */
+    moveSwimlane(id: string, targetId: string, position?: 'before' | 'after'): this;
+    /** Returns collapsed column ids. @returns {string[]} */
+    getCollapsedColumns(): string[];
+    /**
+     * Expands or collapses one column across every lane.
+     * @param {string} id Column id.
+     * @param {boolean} [collapsed=true] Desired state.
+     * @param {{silent?:boolean}} [options={}] Event behavior.
+     * @returns {this}
+     */
+    setColumnCollapsed(id: string, collapsed?: boolean, options?: {
+        silent?: boolean;
+    }): this;
+    /** Toggles a column. @param {string} id Column id. @returns {this} */
+    toggleColumn(id: string): this;
+    /** Returns collapsed lane ids. @returns {string[]} */
+    getCollapsedSwimlanes(): string[];
+    /**
+     * Expands or collapses one lane.
+     * @param {string} id Lane id.
+     * @param {boolean} [collapsed=true] Desired state.
+     * @param {{silent?:boolean}} [options={}] Event behavior.
+     * @returns {this}
+     */
+    setSwimlaneCollapsed(id: string, collapsed?: boolean, options?: {
+        silent?: boolean;
+    }): this;
+    /** Toggles a lane. @param {string} id Lane id. @returns {this} */
+    toggleSwimlane(id: string): this;
+    /**
+     * Proposes and, in local mode, commits a record move. Destination acceptance is checked before
+     * a cancelable `recordmove` event. WIP limits are reported but remain advisory.
+     * @param {unknown} id Record id.
+     * @param {KanbanDestination} destination Destination.
+     * @returns {this}
+     * @fires KanbanView#recordmove
+     * @fires RecordView#datachange
+     */
+    moveRecord(id: unknown, destination: KanbanDestination): this;
+    /** Returns common plus board-specific serializable configuration. @returns {KanbanViewState} */
+    getViewState(): KanbanViewState;
+    /**
+     * Restores common and Kanban configuration. State from another record view is accepted safely.
+     * @param {Partial<KanbanViewState>|null} state Saved state.
+     * @param {{silent?:boolean}} [options={}] Event behavior.
+     * @returns {this}
+     */
+    setViewState(state: Partial<KanbanViewState> | null, options?: {
+        silent?: boolean;
+    }): this;
+    /** Restores enhanced targets after base lifecycle cleanup. @returns {void} */
+    destroy(): void;
+    /** @protected @param {string} _reason Refresh reason. @returns {void} */
+    protected _refreshView(_reason: string): void;
+    /** @param {KanbanSwimlane} lane @param {KanbanColumn[]} columns @returns {HTMLElement} */
+    _renderLane(lane: KanbanSwimlane, columns: KanbanColumn[]): HTMLElement;
+    /** @param {KanbanColumn[]} columns @param {KanbanSwimlane|null} lane @param {boolean} hasLanes @returns {HTMLElement} */
+    _renderColumns(columns: KanbanColumn[], lane: KanbanSwimlane | null, hasLanes: boolean): HTMLElement;
+    /**
+     * @param {KanbanColumn} column
+     * @param {KanbanSwimlane|null} lane
+     * @param {{record:KanbanRecord,index:number}[]} entries
+     * @param {boolean} hasLanes
+     * @returns {HTMLElement}
+     */
+    _renderColumn(column: KanbanColumn, lane: KanbanSwimlane | null, entries: {
+        record: KanbanRecord;
+        index: number;
+    }[], hasLanes: boolean): HTMLElement;
+    /** @param {KanbanRecord} record @param {number} index @param {string} column @param {string|null} lane @param {boolean} hasLanes @returns {HTMLLIElement} */
+    _renderCard(record: KanbanRecord, index: number, column: string, lane: string | null, hasLanes: boolean): HTMLLIElement;
+    /** @returns {HTMLElement} */
+    _emptyContent(): HTMLElement;
+    /** @returns {KanbanColumn[]} */
+    _rawColumns(): KanbanColumn[];
+    /** @returns {KanbanColumn[]} */
+    _resolvedColumns(): KanbanColumn[];
+    /** @returns {KanbanSwimlane[]} */
+    _rawSwimlanes(): KanbanSwimlane[];
+    /** @returns {KanbanSwimlane[]} */
+    _resolvedSwimlanes(): KanbanSwimlane[];
+    /** @param {KanbanAccessor} accessor @param {KanbanRecord} record @param {number} index @returns {unknown} */
+    _readAxis(accessor: KanbanAccessor, record: KanbanRecord, index: number): unknown;
+    /** @param {string} column @param {string|null} lane @returns {{record:KanbanRecord,index:number}[]} */
+    _recordsIn(column: string, lane: string | null): {
+        record: KanbanRecord;
+        index: number;
+    }[];
+    /** @param {unknown} id @returns {KanbanMovePoint|null} */
+    _recordLocation(id: unknown): KanbanMovePoint | null;
+    /**
+     * @param {KanbanRecord} record @param {KanbanMovePoint} from @param {KanbanMovePoint} to
+     * @param {KanbanColumn} column @param {KanbanSwimlane|null} lane @returns {KanbanRecord|null}
+     */
+    _localMovedRecord(record: KanbanRecord, from: KanbanMovePoint, to: KanbanMovePoint, column: KanbanColumn, lane: KanbanSwimlane | null): KanbanRecord | null;
+    /** @param {MouseEvent} event @returns {void} */
+    _handleBoardClick(event: MouseEvent): void;
+    /** @param {MouseEvent} event @returns {void} */
+    _handleBoardDoubleClick(event: MouseEvent): void;
+    /** @param {KeyboardEvent} event @returns {void} */
+    _handleBoardKeydown(event: KeyboardEvent): void;
+    /** @param {KeyboardEvent} event @param {HTMLElement} handle @param {KanbanCardMeta} meta @returns {void} */
+    _handleMoveKeydown(event: KeyboardEvent, handle: HTMLElement, meta: KanbanCardMeta): void;
+    /** @param {Event} event @returns {void} */
+    _handlePreviewError(event: Event): void;
+    /** @param {DragEvent} event @returns {void} */
+    _handleDragStart(event: DragEvent): void;
+    /** @param {DragEvent} event @returns {void} */
+    _handleDragOver(event: DragEvent): void;
+    /** @param {DragEvent} event @returns {void} */
+    _handleDrop(event: DragEvent): void;
+    /** @param {DragEvent} event @param {KanbanSectionMeta} section @returns {KanbanMovePoint} */
+    _pointerDestination(event: DragEvent, section: KanbanSectionMeta): KanbanMovePoint;
+    /** @returns {void} */
+    _clearDrag(): void;
+    /** @returns {void} */
+    _clearDropMarkers(): void;
+    /** @returns {void} */
+    _syncKeyboardTarget(): void;
+    /** @returns {void} */
+    _syncCardSelection(): void;
+    /** @param {EventTarget|null} target @returns {KanbanCardMeta|null} */
+    _metaForTarget(target: EventTarget | null): KanbanCardMeta | null;
+    /** @param {unknown} id @returns {HTMLElement|null} */
+    _moveHandle(id: unknown): HTMLElement | null;
+    /** @param {KanbanRecord} record @param {number} index @returns {string} */
+    _recordName(record: KanbanRecord, index: number): string;
+    /** @param {KanbanMovePoint} point @returns {string} */
+    _targetName(point: KanbanMovePoint): string;
+    /** @param {string} message @returns {void} */
+    _announce(message: string): void;
+    /** @param {string} reason @returns {void} */
+    _emitKanbanState(reason: string): void;
+    /** @returns {Readonly<KanbanViewOptions & RecordViewOptions>} */
+    _kanbanOptions(): Readonly<KanbanViewOptions & RecordViewOptions>;
+}
+/**
+ * Validates and clones configured column or lane descriptors.
+ * @param {unknown} descriptors Descriptors.
+ * @param {'column'|'swimlane'} [axis='column'] Descriptor kind.
+ * @returns {KanbanColumn[]}
+ */
+export declare function normalizeKanbanDescriptors(descriptors: unknown, axis?: 'column' | 'swimlane'): KanbanColumn[];
+/**
+ * Derives stable descriptors from distinct accessor values in first-seen order.
+ * @param {KanbanRecord[]} records Records.
+ * @param {KanbanAccessor} accessor Grouping accessor.
+ * @returns {KanbanColumn[]}
+ */
+export declare function deriveKanbanDescriptors(records: KanbanRecord[], accessor: KanbanAccessor): KanbanColumn[];
+/**
+ * Reconciles a stale or partial order with available descriptors.
+ * @param {{id:string}[]} descriptors Available descriptors.
+ * @param {unknown} order Preferred order.
+ * @returns {string[]}
+ */
+export declare function reconcileKanbanOrder(descriptors: {
+    id: string;
+}[], order: unknown): string[];
+/**
+ * Reorders records around an already-cloned moved record. The input array and every input record
+ * remain untouched; destination index is relative to records in that one column/lane.
+ * @param {KanbanRecord[]} records Records.
+ * @param {unknown} id Moving record id.
+ * @param {KanbanRecord} movedRecord Cloned record carrying its destination axis values.
+ * @param {{recordId:string|((record:KanbanRecord)=>unknown),columnBy:KanbanAccessor,swimlaneBy:KanbanAccessor,destination:KanbanMovePoint}} options Accessors and destination.
+ * @returns {{records:KanbanRecord[],from:KanbanMovePoint,to:KanbanMovePoint}|null}
+ */
+export declare function reorderKanbanData(records: KanbanRecord[], id: unknown, movedRecord: KanbanRecord, options: {
+    recordId: string | ((record: KanbanRecord) => unknown);
+    columnBy: KanbanAccessor;
+    swimlaneBy: KanbanAccessor;
+    destination: KanbanMovePoint;
+}): {
+    records: KanbanRecord[];
+    from: KanbanMovePoint;
+    to: KanbanMovePoint;
+} | null;
+/**
+ * Record movement event emitted before a local commit or external request.
+ * @event KanbanView#recordmove
+ * @type {CustomEvent<{record:KanbanRecord,id:unknown,from:KanbanMovePoint,to:KanbanMovePoint,column:KanbanColumn,swimlane:KanbanSwimlane|null,limitExceeded:boolean}>}
+ */
+/**
+ * Secondary card action event.
+ * @event KanbanView#recordaction
+ * @type {CustomEvent<{record:KanbanRecord,id:unknown,action:unknown,actionId:string|undefined,event:Event}>}
+ */