@zeyos/zx 4.1.0 → 4.2.0

package/dist/types/components/table/table.d.ts

@@ -229,6 +229,11 @@ export type TableOptions = {
      * Whether a column visibility chooser is rendered.
      */
     columnVisibility?: boolean;
+    /**
+     * Whether the column chooser also exposes accessible
+     * earlier/later controls. Column headers never become draggable.
+     */
+    columnReorder?: boolean;
     /**
      * Initially hidden column IDs; at least one stays visible.
      */
@@ -268,6 +273,9 @@ export type TableOptions = {
         visible: string[];
         hidden: string[];
     }>) => void;
+    oncolumnorderchange?: (event: CustomEvent<{
+        order: string[];
+    }>) => void;
 };
 export type TableRowClickDetail = {
     row: TableRow;
@@ -276,8 +284,8 @@ export type TableRowClickDetail = {
     event: Event;
 };
 export type TableSortDetail = {
-    id: string;
-    dir: TableSortDirection;
+    id: string | null;
+    dir: TableSortDirection | null;
 };
 export type TableSelectionDetail = {
     rows: TableRow[];
@@ -471,37 +479,13 @@ export type TableEditorEntry = {
  * @fires Table#grow
  * @fires Table#rowmove
  * @fires Table#columnvisibilitychange
+ * @fires Table#columnorderchange
  * @extends {Component<TableOptions>}
  */
 export declare class Table extends Component<TableOptions> {
     _createdRoot: boolean;
     _original: import("../../core/dom.js").TargetSnapshot;
-    _columns: {
-        id: string;
-        label: string;
-        sortable?: boolean;
-        width?: string;
-        align?: 'start' | 'center' | 'end' | 'left' | 'right';
-        render?: (row: TableRow, rowIndex: number) => Node | string | number | null | undefined;
-        sortValue?: (row: TableRow) => unknown;
-        headerTitle?: string;
-        type?: TableColumnType;
-        locale?: string | ((row: TableRow) => string | null | undefined);
-        decimals?: number | ((row: TableRow) => number | null | undefined);
-        currency?: string | ((row: TableRow) => string | null | undefined);
-        unit?: string | ((row: TableRow) => string | null | undefined);
-        popin?: boolean;
-        editable?: boolean | TableEditorType | ((row: TableRow) => boolean | TableEditorType);
-        options?: TableEditorOption[] | Record<string, string> | ((row: TableRow) => TableEditorOption[] | Record<string, string>);
-        editorProps?: Record<string, unknown>;
-        editor?: (row: TableRow, api: TableEditorApi) => Node | {
-            toElement: () => Node;
-            destroy?: () => void;
-        };
-        parse?: (raw: unknown, row: TableRow) => unknown;
-        format?: (value: unknown, row: TableRow) => string;
-        validate?: (value: unknown, row: TableRow) => true | string;
-    }[];
+    _columns: any[] | TableColumn[];
     _data: any[] | TableRow[];
     _selected: Set<any>;
     _selectionAnchorId: any;
@@ -513,7 +497,7 @@ export declare class Table extends Component<TableOptions> {
     _editTrigger: string;
     _edit: {
         id: unknown;
-        columnId: string;
+        columnId: any;
         row: any;
         cells: Map<string, TableEditorEntry>;
         tr: any;
@@ -536,6 +520,8 @@ export declare class Table extends Component<TableOptions> {
     _hiddenColumns: Set<string>;
     _dragId: any;
     _grabbedId: any;
+    _columnControlIds: Map<any, any>;
+    _columnStatus: HTMLElement;
     _expanded: Set<unknown>;
     _table: HTMLElement;
     _colgroup: HTMLElement;
@@ -612,6 +598,48 @@ export declare class Table extends Component<TableOptions> {
      * @returns {TableRow[]} Current table rows.
      */
     getData(): TableRow[];
+    /**
+     * Returns shallow-cloned column descriptors in their current display order.
+     * @returns {TableColumn[]} Current columns.
+     */
+    getColumns(): TableColumn[];
+    /**
+     * Replaces all column descriptors. Hidden state and the active sort follow retained stable IDs;
+     * an edit is canceled before cells are rebuilt.
+     * @param {TableColumn[]} columns New column descriptors.
+     * @param {{silent?:boolean}} [options={}] Event behavior.
+     * @returns {this}
+     * @fires Table#columnvisibilitychange
+     * @fires Table#columnorderchange
+     * @fires Table#editcancel
+     */
+    setColumns(columns: TableColumn[], options?: {
+        silent?: boolean;
+    }): this;
+    /** Returns every stable column ID in current display order. @returns {string[]} */
+    getColumnOrder(): string[];
+    /**
+     * Reconciles a partial or stale preferred order with every current column.
+     * @param {string[]} order Preferred stable IDs.
+     * @param {{silent?:boolean}} [options={}] Event behavior.
+     * @returns {this}
+     * @fires Table#columnorderchange
+     * @fires Table#editcancel
+     */
+    setColumnOrder(order: string[], options?: {
+        silent?: boolean;
+    }): this;
+    /**
+     * Moves one column to an edge of another column. Unknown IDs are a safe no-op.
+     * @param {string} id Moving stable ID.
+     * @param {string} targetId Target stable ID.
+     * @param {'before'|'after'} [position='before'] Target edge.
+     * @param {{silent?:boolean}} [options={}] Event behavior.
+     * @returns {this}
+     */
+    moveColumn(id: string, targetId: string, position?: 'before' | 'after', options?: {
+        silent?: boolean;
+    }): this;
     /** Returns visible column IDs in caller order. @returns {string[]} */
     getVisibleColumns(): string[];
     /** Returns hidden column IDs in caller order. @returns {string[]} */
@@ -660,6 +688,22 @@ export declare class Table extends Component<TableOptions> {
     setSort(id: string, dir?: TableSortDirection, options?: {
         silent?: boolean;
     }): this;
+    /** Returns a defensive copy of the active sort. @returns {{id:string,dir:TableSortDirection}|null} */
+    getSort(): {
+        id: string;
+        dir: TableSortDirection;
+    } | null;
+    /**
+     * Clears the active sort indicator without attempting to reconstruct the caller's original row
+     * order. The current display order becomes the unsorted order until data is replaced.
+     * @param {{silent?:boolean}} [options={}] Event behavior.
+     * @returns {this}
+     * @fires Table#sort
+     * @fires Table#editcancel
+     */
+    clearSort(options?: {
+        silent?: boolean;
+    }): this;
     /**
      * Returns selected rows in current display order.
      * @returns {TableRow[]} Selected rows.
@@ -854,8 +898,28 @@ export declare class Table extends Component<TableOptions> {
     _visibleColumns(): TableColumn[];
     /** @returns {HTMLElement} */
     _createColumnControls(): HTMLElement;
-    /** @param {string|null} [focusColumn=null] Column checkbox that keeps focus. @returns {void} */
-    _renderColumnControls(focusColumn?: string | null): void;
+    /**
+     * @param {{id:string,action:string}|null} [focusControl=null] Control that keeps focus.
+     * @returns {void}
+     */
+    _renderColumnControls(focusControl?: {
+        id: string;
+        action: string;
+    } | null): void;
+    /** @returns {{id:string,action:string}|null} */
+    _activeColumnControl(): {
+        id: string;
+        action: string;
+    } | null;
+    /** @param {Event} event @returns {void} */
+    _handleColumnControlClick(event: Event): void;
+    /**
+     * Adds Arrow/Home/End movement to the reorder buttons; Enter and Space retain native button
+     * activation. Focus follows the stable column id across the cancel-safe row/header rebuild.
+     * @param {KeyboardEvent} event Keyboard event.
+     * @returns {void}
+     */
+    _handleColumnControlKeydown(event: KeyboardEvent): void;
     /** @param {DragEvent} event @returns {void} */
     _handleRowDragStart(event: DragEvent): void;
     /** @param {DragEvent} event @returns {void} */
@@ -1052,6 +1116,9 @@ export declare class Table extends Component<TableOptions> {
 /** @event Table#rowtoggle @type {CustomEvent<TableRowToggleDetail>} */
 /** @event Table#stackedchange @type {CustomEvent<{stacked: boolean}>} */
 /** @event Table#grow @type {CustomEvent<{rendered: number, total: number}>} */
+/** @event Table#rowmove @type {CustomEvent<TableRowMoveDetail>} */
+/** @event Table#columnvisibilitychange @type {CustomEvent<{visible:string[],hidden:string[]}>} */
+/** @event Table#columnorderchange @type {CustomEvent<{order:string[]}>} */
 /**
  * Editor opened for a cell (or, in row mode, for the row).
  * @event Table#editstart
@@ -1181,3 +1248,25 @@ export declare function firstValidationError(values: Record<string, unknown>, co
     columnId: string;
     message: string;
 } | null;
+/**
+ * Validates and shallow-clones table columns so stable-id APIs never mutate caller descriptors.
+ * @param {unknown} columns Column descriptors.
+ * @returns {TableColumn[]} Normalized descriptors.
+ */
+export declare function normalizeTableColumns(columns: unknown): TableColumn[];
+/**
+ * Reconciles saved or partial column IDs with every current column.
+ * @param {TableColumn[]} columns Current columns.
+ * @param {unknown} order Preferred IDs.
+ * @returns {string[]} Complete stable order.
+ */
+export declare function reconcileTableColumnOrder(columns: TableColumn[], order: unknown): string[];
+/**
+ * Moves one stable column ID without changing the supplied order.
+ * @param {string[]} order Current IDs.
+ * @param {string} id Moving ID.
+ * @param {string} targetId Target ID.
+ * @param {'before'|'after'} [position='before'] Target edge.
+ * @returns {string[]} Reordered copy, or an unchanged copy for unknown/same IDs.
+ */
+export declare function moveTableColumn(order: string[], id: string, targetId: string, position?: 'before' | 'after'): string[];

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

@@ -0,0 +1,192 @@
+import { Table } from '../table/table.js';
+import { RecordView } from '../view/record-view.js';
+export type TableViewRecord = Record<string, any>;
+export type ViewField = import('../view/record-view.js').ViewField;
+export type ViewSort = import('../view/record-view.js').ViewSort;
+export type TableColumn = import('../table/table.js').TableColumn;
+export type TableOptions = import('../table/table.js').TableOptions;
+export type TableViewOptions = {
+    /**
+     * Shared ordered field descriptors. These win over `table.columns`.
+     */
+    fields?: ViewField[];
+    /**
+     * Initial records. These win over `table.data`.
+     */
+    data?: TableViewRecord[];
+    /**
+     * Stable record id accessor.
+     */
+    recordId?: string | ((record: TableViewRecord) => unknown);
+    /**
+     * Initial shared sort.
+     */
+    sort?: ViewSort | null;
+    /**
+     * Local or server-controlled sorting.
+     */
+    sortMode?: 'local' | 'server';
+    /**
+     * Shared selection behavior.
+     */
+    selectable?: false | 'single' | 'multi';
+    /**
+     * Initially selected record ids.
+     */
+    selection?: unknown[];
+    /**
+     * Preferred stable field order.
+     */
+    fieldOrder?: string[];
+    /**
+     * Initially hidden field ids.
+     */
+    hiddenFields?: string[];
+    /**
+     * Show the accessible visibility and reorder disclosure.
+     */
+    fieldControls?: boolean;
+    /**
+     * Empty-result content.
+     */
+    emptyText?: string | Node | (() => string | Node) | null;
+    /**
+     * Advanced low-level Table options. Shared options win where
+     * their contracts overlap; all other options and callbacks are forwarded unchanged.
+     */
+    table?: TableOptions;
+    onrecordclick?: (event: CustomEvent<Record<string, unknown>>) => void;
+    onrecorddblclick?: (event: CustomEvent<Record<string, unknown>>) => void;
+    ondatachange?: (event: CustomEvent<{
+        records: TableViewRecord[];
+    }>) => void;
+    onselectionchange?: (event: CustomEvent<{
+        records: TableViewRecord[];
+        ids: unknown[];
+    }>) => void;
+    onsortchange?: (event: CustomEvent<{
+        id: string | null;
+        dir: 'asc' | 'desc' | null;
+    }>) => void;
+    onfieldvisibilitychange?: (event: CustomEvent<{
+        visible: string[];
+        hidden: string[];
+    }>) => void;
+    onfieldorderchange?: (event: CustomEvent<{
+        order: string[];
+    }>) => void;
+    onstatechange?: (event: CustomEvent<Record<string, unknown>>) => void;
+};
+/** @typedef {Record<string, any>} TableViewRecord */
+/** @typedef {import('../view/record-view.js').ViewField} ViewField */
+/** @typedef {import('../view/record-view.js').ViewSort} ViewSort */
+/** @typedef {import('../table/table.js').TableColumn} TableColumn */
+/** @typedef {import('../table/table.js').TableOptions} TableOptions */
+/**
+ * @typedef {Object} TableViewOptions
+ * @property {ViewField[]} [fields=[]] Shared ordered field descriptors. These win over `table.columns`.
+ * @property {TableViewRecord[]} [data=[]] Initial records. These win over `table.data`.
+ * @property {string|((record:TableViewRecord)=>unknown)} [recordId='ID'] Stable record id accessor.
+ * @property {ViewSort|null} [sort=null] Initial shared sort.
+ * @property {'local'|'server'} [sortMode='local'] Local or server-controlled sorting.
+ * @property {false|'single'|'multi'} [selectable=false] Shared selection behavior.
+ * @property {unknown[]} [selection=[]] Initially selected record ids.
+ * @property {string[]} [fieldOrder=[]] Preferred stable field order.
+ * @property {string[]} [hiddenFields=[]] Initially hidden field ids.
+ * @property {boolean} [fieldControls=true] Show the accessible visibility and reorder disclosure.
+ * @property {string|Node|(()=>string|Node)|null} [emptyText=null] Empty-result content.
+ * @property {TableOptions} [table={}] Advanced low-level Table options. Shared options win where
+ * their contracts overlap; all other options and callbacks are forwarded unchanged.
+ * @property {(event:CustomEvent<Record<string,unknown>>)=>void} [onrecordclick]
+ * @property {(event:CustomEvent<Record<string,unknown>>)=>void} [onrecorddblclick]
+ * @property {(event:CustomEvent<{records:TableViewRecord[]}> )=>void} [ondatachange]
+ * @property {(event:CustomEvent<{records:TableViewRecord[],ids:unknown[]}> )=>void} [onselectionchange]
+ * @property {(event:CustomEvent<{id:string|null,dir:'asc'|'desc'|null}>)=>void} [onsortchange]
+ * @property {(event:CustomEvent<{visible:string[],hidden:string[]}> )=>void} [onfieldvisibilitychange]
+ * @property {(event:CustomEvent<{order:string[]}> )=>void} [onfieldorderchange]
+ * @property {(event:CustomEvent<Record<string,unknown>>)=>void} [onstatechange]
+ */
+/**
+ * Record-oriented table view. Shared record state stays in RecordView while the composed `table`
+ * instance retains Table's editing, hierarchy, growth, movement, responsive, and loading behavior.
+ * @fires TableView#recordclick
+ * @fires TableView#recorddblclick
+ * @fires TableView#datachange
+ * @fires TableView#selectionchange
+ * @fires TableView#sortchange
+ * @fires TableView#fieldvisibilitychange
+ * @fires TableView#fieldorderchange
+ * @fires TableView#statechange
+ * @extends {RecordView}
+ */
+export declare class TableView extends RecordView {
+    _createdTableViewRoot: boolean;
+    _tableViewOriginal: import("../../core/dom.js").TargetSnapshot;
+    _tableViewRestored: boolean;
+    _tableSyncDepth: number;
+    _tableViewDestroyed: boolean;
+    _tableHost: HTMLElement;
+    table: Table;
+    static cssName: string;
+    /** @type {Readonly<TableViewOptions>} */
+    static defaults: Readonly<TableViewOptions>;
+    /**
+     * Creates or enhances a record table view.
+     * @param {Element|string|null} [target=null] Existing root, selector, or null.
+     * @param {TableViewOptions} [options={}] Shared and table-specific options.
+     */
+    constructor(target?: Element | string | null, options?: TableViewOptions);
+    /** @returns {HTMLElement} Table view root. */
+    render(): HTMLElement;
+    /** Returns the composed Table for advanced methods and Table-specific events. @returns {Table} */
+    getTable(): Table;
+    /** @protected @param {string} reason Shared refresh reason. @returns {void} */
+    protected _refreshView(reason: string): void;
+    /** Destroys the inner Table and restores an enhanced target exactly once. @returns {void} */
+    destroy(): void;
+    /** @private @param {()=>void} callback Guarded synchronization. @returns {void} */
+    private _withTableSync;
+    /** @private @returns {void} */
+    private _syncTableFieldState;
+    /** @private @returns {void} */
+    private _bridgeTableEvents;
+    /** @private @param {{id:string|null,dir:'asc'|'desc'|null}} detail Sort detail. @returns {void} */
+    private _tableSortChanged;
+    /** @private @param {{rows:TableViewRecord[],ids:unknown[]}} detail Selection detail. @returns {void} */
+    private _tableSelectionChanged;
+    /** @private @returns {void} */
+    private _tableDataChanged;
+    /** @private @param {{visible:string[],hidden:string[]}} detail Visibility detail. @returns {void} */
+    private _tableVisibilityChanged;
+    /** @private @param {{order:string[]}} detail Order detail. @returns {void} */
+    private _tableOrderChanged;
+    /** @private @returns {void} */
+    private _emitTableViewSelection;
+    /** @private @param {string} reason State-change reason. @returns {void} */
+    private _emitTableViewState;
+}
+/**
+ * Maps common fields to Table columns without mutating descriptors. Shared get/render/sortValue
+ * semantics win; `field.view.table` may provide the remaining advanced TableColumn properties.
+ * @param {ViewField[]} fields Shared fields in display order.
+ * @returns {TableColumn[]} Table columns.
+ */
+export declare function fieldsToTableColumns(fields: ViewField[]): TableColumn[];
+/**
+ * Builds the composed Table configuration. Shared options deliberately overwrite overlapping
+ * low-level options; every advanced option remains untouched.
+ * @param {TableOptions|undefined} table Advanced Table options.
+ * @param {{fields:ViewField[],data:TableViewRecord[],recordId:string|((record:TableViewRecord)=>unknown),sort:ViewSort|null,sortMode:'local'|'server',selectable:false|'single'|'multi',hiddenFields:string[],fieldControls:boolean,emptyText:string|Node|(()=>string|Node)|null}} shared Shared state.
+ * @returns {TableOptions} Table configuration.
+ */
+export declare function tableOptionsForView(table: TableOptions | undefined, shared: {
+    fields: ViewField[];
+    data: TableViewRecord[];
+    recordId: string | ((record: TableViewRecord) => unknown);
+    sort: ViewSort | null;
+    sortMode: 'local' | 'server';
+    selectable: false | 'single' | 'multi';
+    hiddenFields: string[];
+    fieldControls: boolean;
+    emptyText: string | Node | (() => string | Node) | null;
+}): TableOptions;