@mk-kit/ui 0.34.1 → 0.36.0

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

@@ -26,6 +26,65 @@ declare class MkTableRowDetail<T = unknown> {
     static ɵdir: _angular_core.ɵɵDirectiveDeclaration<MkTableRowDetail<any>, "[mkTableRowDetail]", never, {}, {}, never, never, true, never>;
 }
 
+/**
+ * CSV export — turn rows into RFC 4180 text and hand it to the browser as a
+ * download. Framework-free so it also serves data that never touched a table.
+ */
+/** A column to export: the row property, its header, and an optional formatter. */
+interface MkCsvColumn<T = Record<string, unknown>> {
+    /** Property key on each row object supplying the cell value. */
+    key: string;
+    /** Header text; defaults to `key`. */
+    header?: string;
+    /** Formatter turning the raw value into cell text (same shape as `MkTableColumn.format`). */
+    format?: (value: unknown, row: T) => string;
+}
+interface MkCsvOptions {
+    /** Field separator (default `,`; use `;` for locales whose Excel expects it). */
+    delimiter?: string;
+    /** Emit the header row first (default `true`). */
+    header?: boolean;
+    /** Line terminator (default `\r\n`, per RFC 4180). */
+    newline?: string;
+    /**
+     * Prefix a UTF-8 byte-order mark (default `true`) so Excel reads accented
+     * characters correctly. Only affects the downloaded file / returned text.
+     */
+    bom?: boolean;
+    /**
+     * Neutralise spreadsheet formula injection (default `true`): a text cell
+     * starting with `=`, `+`, `-`, `@`, tab or CR is prefixed with `'` so a
+     * malicious value cannot execute when opened in Excel / Sheets. Numbers
+     * are never touched, so `-5` stays `-5`.
+     */
+    sanitize?: boolean;
+    /** Property holding child rows; when set, trees are flattened depth-first. */
+    childrenKey?: string;
+}
+/** Options for {@link mkExportCsv}. */
+interface MkCsvExportOptions extends MkCsvOptions {
+    /** File name for the download (default `export.csv`; `.csv` is appended if missing). */
+    filename?: string;
+}
+/**
+ * Serialise `rows` as CSV text.
+ *
+ * Without `columns` every key of the first row is exported in its own order.
+ * Column formatters are applied, so what the user saw in the table is what
+ * lands in the file.
+ */
+declare function mkToCsv<T>(rows: readonly T[], columns?: readonly MkCsvColumn<T>[], options?: MkCsvOptions): string;
+/**
+ * Trigger a browser download of `text` as a file. No-op outside a DOM
+ * (server-side rendering); returns whether a download was started.
+ */
+declare function mkDownloadText(text: string, filename: string, type?: string): boolean;
+/**
+ * Serialise `rows` as CSV and download it. Returns the CSV text so callers
+ * can also keep it (tests, previews, uploads).
+ */
+declare function mkExportCsv<T>(rows: readonly T[], columns?: readonly MkCsvColumn<T>[], options?: MkCsvExportOptions): string;
+
 /** Horizontal text alignment for a table column. */
 type MkTableAlign = 'start' | 'center' | 'end';
 /** Sort direction; `none` means unsorted. */
@@ -105,12 +164,28 @@ interface MkTableGroup<T = Record<string, unknown>> {
     rows: T[];
 }
 /** Payload emitted by {@link MkTable.groupToggle}. */
+/** Payload of `(treeToggle)`: a parent row was expanded or collapsed. */
+interface MkTreeToggle<T = Record<string, unknown>> {
+    /** The parent row. */
+    row: T;
+    /** Whether its child rows are now shown. */
+    expanded: boolean;
+}
 interface MkGroupToggle {
     /** The toggled group's value. */
     key: unknown;
     /** Whether the group is now collapsed. */
     collapsed: boolean;
 }
+/** Options for {@link MkTable.exportCsv}. */
+interface MkTableExportOptions extends MkCsvExportOptions {
+    /** Export only the selected rows (default: every row). */
+    selectedOnly?: boolean;
+    /** Restrict to these column keys, in table order (default: every column). */
+    columns?: readonly string[];
+    /** Start the browser download (default `true`); `false` just returns the text. */
+    download?: boolean;
+}
 /** One rendered tbody entry: either a group header or a data row. */
 type MkTableItem<T> = {
     kind: 'group';
@@ -118,6 +193,12 @@ type MkTableItem<T> = {
 } | {
     kind: 'row';
     row: T;
+    /** Nesting depth in tree mode (0 for roots and for flat tables). */
+    depth: number;
+    /** Whether the row has child rows (tree mode). */
+    hasChildren: boolean;
+    /** Whether its children are currently shown (tree mode). */
+    expanded: boolean;
 };
 /**
  * Table — a themed data table built on a native `<table>` for accessibility.
@@ -242,6 +323,15 @@ declare class MkTable<T = Record<string, unknown>> {
     readonly cellEdit: _angular_core.OutputEmitterRef<MkCellEdit<T>>;
     /** Emitted when a group header is expanded or collapsed. */
     readonly groupToggle: _angular_core.OutputEmitterRef<MkGroupToggle>;
+    /**
+     * Tree rows: the property on each row holding its child rows (`T[]`). When
+     * set, the table renders a tree grid — child rows are indented under their
+     * parent behind an expand toggle in the first column, sorting applies per
+     * sibling group, and ArrowRight / ArrowLeft on a row open / close it.
+     */
+    readonly childrenKey: _angular_core.InputSignal<string | null>;
+    /** Emitted when a parent row is expanded or collapsed (tree mode). */
+    readonly treeToggle: _angular_core.OutputEmitterRef<MkTreeToggle<T>>;
     /** User-set column widths (px), keyed by column key. */
     private readonly colWidths;
     /** User-set column order (keys); `null` = the input order. */
@@ -343,6 +433,8 @@ declare class MkTable<T = Record<string, unknown>> {
     private static readonly sortCollator;
     /** Data sorted by the active column, or the input order when unsorted. */
     protected readonly sortedData: _angular_core.Signal<T[]>;
+    /** Sort one sibling group by the active column (input order when unsorted). */
+    private sortRows;
     /** `aria-sort` value for a header cell. */
     protected ariaSort(col: MkTableColumn<T>): string | null;
     /** Glyph indicating a column's sort state. */
@@ -353,7 +445,7 @@ declare class MkTable<T = Record<string, unknown>> {
     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). */
+    /** Keyboard activation for clickable rows (Enter / Space) and tree keys. */
     protected onRowKeydown(event: KeyboardEvent, row: T): void;
     /** Stable row identity for `@for` tracking (trackKey when set, else the row). */
     protected trackRow: (row: T) => unknown;
@@ -364,6 +456,12 @@ declare class MkTable<T = Record<string, unknown>> {
     private readonly selectedKeys;
     /** Whether `row` is currently selected. */
     protected isSelected(row: T): boolean;
+    /**
+     * Every data row, in display order, ignoring tree expansion — what
+     * "select all" and the header checkbox reason about. Equals `sortedData`
+     * for flat tables.
+     */
+    private readonly allRows;
     /** True when every visible row is selected. */
     protected readonly allSelected: _angular_core.Signal<boolean>;
     /** True when some — but not all — visible rows are selected. */
@@ -371,7 +469,7 @@ declare class MkTable<T = Record<string, unknown>> {
     private commitSelection;
     /** Toggle a single row's selection without triggering `rowClick`. */
     protected toggleRow(row: T): void;
-    /** Select or deselect all visible rows. */
+    /** Select or deselect all rows (every tree row, expanded or not). */
     protected toggleAll(): void;
     /** Group values currently collapsed. */
     private readonly collapsedGroups;
@@ -382,6 +480,36 @@ declare class MkTable<T = Record<string, unknown>> {
      * rows when grouping is on, else just the sorted rows.
      */
     protected readonly displayItems: _angular_core.Signal<MkTableItem<T>[]>;
+    /**
+     * Append `rows` as render items. In tree mode each row is followed by its
+     * (sorted) children while it is expanded, one level deeper.
+     */
+    private pushRows;
+    /** The child rows of `row` (tree mode), or an empty list. */
+    private childrenOf;
+    /** Keys of parent rows whose children are shown. */
+    private readonly treeExpanded;
+    /** Whether a parent row's children are currently shown (tree mode). */
+    isTreeExpanded(row: T): boolean;
+    /** Show or hide a parent row's children (tree mode). */
+    toggleTreeRow(row: T, event?: Event): void;
+    /** Expand every parent row (tree mode). */
+    expandAllRows(): void;
+    /** Collapse every parent row (tree mode). */
+    collapseAllRows(): void;
+    /**
+     * The table's rows as CSV: current column order, column formatters applied,
+     * sorted the way they are shown, tree children flattened under their parent
+     * whether or not they are expanded. Downloads the file (default name
+     * `table.csv`) and returns the text.
+     */
+    exportCsv(options?: MkTableExportOptions): string;
+    private setTreeExpanded;
+    /**
+     * ArrowRight opens and ArrowLeft closes a parent row's children (swapped in
+     * RTL). Handled for keys pressed on the row itself or on its tree toggle.
+     */
+    protected onTreeKeydown(event: KeyboardEvent, row: T): boolean;
     /** `@for` identity: group headers by value, rows by {@link trackRow}. */
     protected trackItem: (item: MkTableItem<T>) => unknown;
     /** Whether a group is currently collapsed. */
@@ -400,7 +528,7 @@ declare class MkTable<T = Record<string, unknown>> {
     /** 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>;
+    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; }; "childrenKey": { "alias": "childrenKey"; "required": false; "isSignal": true; }; }, { "selected": "selectedChange"; "sortChange": "sortChange"; "rowClick": "rowClick"; "selectionChange": "selectionChange"; "expandedChange": "expandedChange"; "columnResize": "columnResize"; "columnReorder": "columnReorder"; "cellEdit": "cellEdit"; "groupToggle": "groupToggle"; "treeToggle": "treeToggle"; }, ["rowDetail", "cellTemplates"], ["[mkTableEmpty]"], true, never>;
 }
 
 /** Context handed to an `[mkTableCell]` template. */
@@ -735,5 +863,5 @@ declare class MkTableDataSource<T> {
     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 };
+export { MkSort, MkSortHeader, MkTable, MkTableCell, MkTableDataSource, MkTableRowDetail, mkDownloadText, mkExportCsv, mkToCsv };
+export type { MkCellEdit, MkColumnResize, MkCsvColumn, MkCsvExportOptions, MkCsvOptions, MkDataFetcher, MkDataPage, MkDataRequest, MkGroupToggle, MkSortChange, MkSortDirection, MkSortState, MkSortable, MkTableAlign, MkTableCellContext, MkTableColumn, MkTableDataSourceOptions, MkTableDensity, MkTableExportOptions, MkTableGroup, MkTreeToggle };

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

@@ -14,4 +14,5 @@ export * from '@mk-kit/ui/feedback';
 export * from '@mk-kit/ui/rich-text';
 export * from '@mk-kit/ui/block-editor';
 export * from '@mk-kit/ui/context-menu';
+export * from '@mk-kit/ui/layout';
 export * from '@mk-kit/ui/media';