@luzmo/lucero 2.4.1 → 2.5.0

package/components/table/table-templates.d.ts

@@ -0,0 +1,41 @@
+import { TemplateResult } from 'lit';
+import type { ElementSize } from '../../utils/sized-mixin';
+import { TableRecord, TableSort } from './table-model';
+import { TableColumn, TableItemLabel, TableRenderDetails, TableRenderItem, TableSelects } from './types';
+export declare const columnSortKey: (column: TableColumn) => string;
+export declare const renderDataHead: (columns: TableColumn[], sort: TableSort | undefined, options: {
+    expandable: boolean;
+    resizeLabel: (header: string) => string;
+}) => TemplateResult;
+export interface DataRowsOptions {
+    rows: {
+        record: TableRecord;
+        position: number;
+    }[];
+    /** Number of data rows, including rows the virtualizer has not mounted. */
+    rowCount: number;
+    columns: TableColumn[];
+    renderItem?: TableRenderItem;
+    itemLabel?: TableItemLabel;
+    selectRowLabel: string;
+    selects?: TableSelects;
+    isSelected: (value: string) => boolean;
+    emphasized: boolean;
+    checkboxSize: ElementSize;
+    /** `aria-rowindex` of the first data row, or `undefined` when not virtualized. */
+    rowIndexOffset?: number;
+    paddingStart: number;
+    paddingEnd: number;
+    expandable: boolean;
+    isExpanded: (value: string) => boolean;
+    expandLabel: (record: TableRecord, position: number) => string;
+    renderDetails?: TableRenderDetails;
+    /** Data-row indexes whose details are playing their close animation. */
+    closing: ReadonlySet<string>;
+    /** Virtualized tables pass explicit row and details indexes. */
+    ariaIndexes?: Map<string, {
+        row: number;
+        details?: number;
+    }>;
+}
+export declare const renderDataBody: (options: DataRowsOptions) => TemplateResult;

package/components/table/table.d.ts

@@ -0,0 +1,197 @@
+import { CSSResultArray, PropertyValues, TemplateResult } from 'lit';
+import { LuzmoElement } from '../../utils/base';
+import './table-row-details';
+import { TableColumn, TableDensity, TableItem, TableItemLabel, TableItemValue, TableLabels, TableRenderDetails, TableRenderItem, TableSelects } from './types';
+declare const LuzmoTable_base: typeof LuzmoElement & {
+    new (...args: any[]): import("../..").SizedElementInterface;
+    prototype: import("../..").SizedElementInterface;
+};
+/**
+ * @element luzmo-table
+ *
+ * A grid of rows and columns. Slot `luzmo-table-head` and `luzmo-table-body`
+ * for declarative markup, or set `items` to render rows from data, sorted
+ * by TanStack Table and optionally virtualized with TanStack Virtual.
+ *
+ * @slot - `luzmo-table-head` and `luzmo-table-body`.
+ *
+ * @fires change - `selected` changed. Cancel it to keep the previous selection.
+ * @fires luzmo-table-sorted - A sortable header was activated. `detail` is `{ sortKey, sortDirection }`. Cancel it in data mode to skip the client sort.
+ * @fires luzmo-table-row-toggle - A row's details were expanded or collapsed. `detail` is `{ value, expanded }`. Cancel it to keep the previous state.
+ * @fires luzmo-column-resized - A column resize committed. `detail` is `{ columnId, width, columnWidths }`.
+ * @fires luzmo-range-changed - The mounted window of a virtualized table changed. `detail` is `{ first, last }`.
+ *
+ * @attr select-all-label - Accessible name of the select-all checkbox.
+ *
+ * @cssprop --luzmo-table-background-color - Background of the table.
+ * @cssprop --luzmo-table-border-color - Border and row divider color.
+ * @cssprop --luzmo-table-border-radius - Corner radius of the table.
+ * @cssprop --luzmo-table-column-divider-width - Width of the divider between columns.
+ * @cssprop --luzmo-table-column-divider-color - Color of the divider between columns.
+ * @cssprop --luzmo-table-row-min-block-size - Minimum block size of rows.
+ * @cssprop --luzmo-table-cell-padding-inline - Inline padding of cells.
+ * @cssprop --luzmo-table-row-selected-background-color - Background of selected rows.
+ * @cssprop --luzmo-table-scrollbar-width - Scrollbar size of a scrolling body.
+ * @cssprop --luzmo-table-scrollbar-track-background - Scrollbar track background.
+ * @cssprop --luzmo-table-scrollbar-track-border-radius - Scrollbar track radius.
+ * @cssprop --luzmo-table-scrollbar-thumb-background - Scrollbar thumb background.
+ * @cssprop --luzmo-table-scrollbar-thumb-border-radius - Scrollbar thumb radius.
+ * @cssprop --luzmo-table-scrollbar-thumb-hover-background - Scrollbar thumb background on hover.
+ */
+export declare class LuzmoTable extends LuzmoTable_base {
+    static get styles(): CSSResultArray;
+    role: string;
+    /**
+     * Row density. Unset is regular.
+     */
+    density: TableDensity | undefined;
+    /**
+     * Use the accent color for selected rows and checkboxes.
+     */
+    emphasized: boolean;
+    /**
+     * Remove the outer border and background.
+     */
+    quiet: boolean;
+    /**
+     * Scroll the body inside the table's block size, keeping the head in view.
+     */
+    scroller: boolean;
+    /**
+     * Row selection mode. Unset disables selection.
+     */
+    selects: TableSelects | undefined;
+    /**
+     * Selected row values.
+     */
+    selected: string[];
+    /**
+     * Accessible name of the select-all checkbox. Overrides `labels.selectAll`.
+     */
+    selectAllLabel: string | undefined;
+    /**
+     * Row records. Setting an array switches the table to data mode.
+     */
+    items: TableItem[] | undefined;
+    /**
+     * Stable, unique selection value of a data-mode row. Defaults to the item
+     * index.
+     */
+    itemValue: TableItemValue | undefined;
+    /**
+     * Accessible name of a data-mode row checkbox. Defaults to the first
+     * column's text, then `labels.selectRow`.
+     */
+    itemLabel: TableItemLabel | undefined;
+    /**
+     * Cell content of a data-mode row. Return `luzmo-table-cell` elements.
+     */
+    renderItem: TableRenderItem | undefined;
+    /**
+     * Expanded row values. Setting `renderDetails` enables data-mode
+     * disclosure.
+     */
+    expanded: string[];
+    /**
+     * Details content of a data-mode row. Its presence enables row disclosure
+     * for every non-information row.
+     */
+    renderDetails: TableRenderDetails | undefined;
+    /**
+     * Resized column widths, in pixels, keyed by column id. A resize updates
+     * this map without changing `columns`.
+     */
+    columnWidths: Record<string, number>;
+    /**
+     * Data-mode columns, used when no `luzmo-table-head` is slotted.
+     */
+    columns: TableColumn[];
+    /**
+     * Mount only the visible rows. Data mode only; needs a bounded block size.
+     */
+    virtualized: boolean;
+    /**
+     * Translatable copy.
+     */
+    labels: TableLabels;
+    private _sort;
+    private _clientSort;
+    private _mode;
+    private _rows;
+    private _rowKeys;
+    private _activeCell?;
+    private _warnedSlottedRows;
+    private readonly model;
+    private readonly language;
+    private readonly announcer;
+    private readonly layout;
+    private readonly resize;
+    private readonly expansion;
+    private _lightDomVersion;
+    private _modelSynced;
+    private readonly lightObserver;
+    private readonly directionManaged;
+    private readonly directionObserver;
+    private readonly navigation;
+    private readonly virtualizer;
+    constructor();
+    private get _isDataMode();
+    /**
+     * Moves focus to the grid's current cell.
+     */
+    focus(options?: FocusOptions): void;
+    /**
+     * Scrolls the row at `index` in the current order into view.
+     */
+    scrollToIndex(index: number): void;
+    /**
+     * Child elements take the table's direction, so `dir` on the table applies
+     * to its rows and cells as well.
+     * @internal
+     */
+    startManagingContentDirection(element: HTMLElement): void;
+    /** @internal */
+    stopManagingContentDirection(element: HTMLElement): void;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    protected willUpdate(changes: PropertyValues<this>): void;
+    protected render(): TemplateResult;
+    protected updated(changes: PropertyValues<this>): void;
+    private _renderData;
+    private _syncDirection;
+    private _rowLabel;
+    private _ariaIndexes;
+    private _owns;
+    private _initialSort;
+    private _createRecords;
+    private _slottedHead;
+    private _declarativeRows;
+    private _head;
+    private _rowElements;
+    private _gridRows;
+    private _gridEntryIndex;
+    private _virtualNavigationTarget;
+    private _virtualDataIndex;
+    private _focusVirtualCell;
+    private _mountedVirtualRow;
+    /**
+     * Header cells and their resize separators stay outside the body grid, so
+     * each one keeps its own tab stop. Arrow, Home, and End movement in the
+     * body belongs to the grid navigation controller.
+     */
+    private _gridCells;
+    private _warnSlottedRows;
+    private _refreshNavigation;
+    private _commitSelection;
+    private _toggleRow;
+    private _toggleAll;
+    private _activateCell;
+    private _cellFromPath;
+    private handleChange;
+    private handleClick;
+    private handleFocusin;
+    private handleKeydown;
+    private _gridElementFromPath;
+    private handleSorted;
+}
+export {};

package/components/table/types.d.ts

@@ -0,0 +1,81 @@
+export type TableItem = Record<string, unknown>;
+export type TableSelects = 'single' | 'multiple';
+export type TableDensity = 'compact' | 'spacious';
+export type TableSortDirection = 'asc' | 'desc';
+/**
+ * Row type brand for data-mode items. Spectrum's numeric `_$rowType$` brand
+ * (`1` for information) is accepted as well.
+ */
+export type TableRowType = 'item' | 'information';
+export interface TableColumn<T extends TableItem = TableItem> {
+    /** Stable column identifier. */
+    id: string;
+    /** Header content. */
+    header: unknown;
+    /** Item key rendered as plain text when `cell` is not provided. */
+    accessorKey?: string;
+    /** Cell content for this column. */
+    cell?: (item: T, index: number) => unknown;
+    /** Whether the column header sorts the table. */
+    sortable?: boolean;
+    /** Item key the column sorts by. Defaults to `accessorKey`, then `id`. */
+    sortKey?: string;
+    /** Initial sort direction. */
+    sortDirection?: TableSortDirection;
+    /** Fixed column width, in pixels. */
+    width?: number;
+    /** Minimum column width, in pixels. */
+    minWidth?: number;
+    /** Maximum column width, in pixels. */
+    maxWidth?: number;
+    /**
+     * Whether the column header exposes a resize handle. Defaults to true,
+     * including for the last column. Set false to opt out.
+     */
+    resizable?: boolean;
+    /**
+     * Maximum number of text lines before the header and cells truncate.
+     * Unset wraps. A cell `lineClamp` overrides this default.
+     */
+    lineClamp?: number;
+}
+export type TableRenderItem<T extends TableItem = TableItem> = (item: T, index: number) => unknown;
+export type TableItemValue<T extends TableItem = TableItem> = (item: T, index: number) => string;
+export type TableItemLabel<T extends TableItem = TableItem> = (item: T, index: number) => string;
+export type TableRenderDetails<T extends TableItem = TableItem> = (item: T, index: number) => unknown;
+export interface TableSortedDetail {
+    sortKey: string;
+    sortDirection: TableSortDirection;
+}
+export interface TableRangeChangedDetail {
+    first: number;
+    last: number;
+}
+export interface TableRowToggleDetail {
+    value: string;
+    expanded: boolean;
+}
+export interface TableColumnResizedDetail {
+    columnId: string;
+    width: number;
+    columnWidths: Record<string, number>;
+}
+export type TableLabels = {
+    /** Accessible name of the select-all checkbox. */
+    selectAll?: string;
+    /** Fallback accessible name of a data-mode row checkbox. `{index}` is the 1-based row number. */
+    selectRow?: string;
+    /** Announced after an ascending sort. `{column}` is the header text. */
+    sortAscending?: string;
+    /** Announced after a descending sort. `{column}` is the header text. */
+    sortDescending?: string;
+    /** Accessible name of a row disclosure button. `{label}` is the row name and `{index}` is the 1-based row number. */
+    expandRow?: string;
+    /** Accessible name of a row disclosure button while the row is expanded. `{label}` is the row name and `{index}` is the 1-based row number. */
+    collapseRow?: string;
+    /** Accessible name of a column resize handle. `{column}` is the header text. */
+    resizeColumn?: string;
+    /** Announced after a column resize. `{column}` is the header text and `{width}` is the pixel width. */
+    columnWidth?: string;
+};
+export declare const DEFAULT_TABLE_LABELS: Required<TableLabels>;