xv-webcomponents 2.0.0-beta.2 → 2.0.0-beta.28

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

@@ -1,15 +1,304 @@
+import { EventEmitter } from '../../stencil-public-runtime';
 import { SIZE_VAR_STR } from '../../types/enum';
-import { SelectRowDto } from './_vars';
+import { XvTableColumn, XvTableExpandMode, XvTableExpandedDetail, XvTableLayout, XvTableMode, XvTablePage, XvTableRowClickDetail, XvTableRowOrder, XvTableSelectionDetail, XvTableSelectionMode, XvTableSort } from './xv-table.model';
+/**
+ * A data table built on CSS grid with `subgrid` rows, so a row keeps its own box while its cells
+ * stay aligned to the table's columns and an expanded panel can span the full width.
+ *
+ * `columns` always describes the structure — widths, order, sorting, resizing, hiding and the
+ * stored layout all read from it. Rows come either from `rows` as data, or as slotted
+ * `xv-table-row` children when the cells hold arbitrary markup.
+ *
+ * @slot - Slotted `xv-table-row` children, used instead of the `rows` prop.
+ * @slot toolbar - Controls above the table. Slotted content spans the bar; `flex: 0 0 auto` opts out.
+ * @slot batch - Actions shown in the bar that replaces the toolbar while rows are selected.
+ * @slot footer - Rows rendered after the body, for subtotals.
+ * @slot empty - Shown instead of the body when there is nothing to render.
+ * @slot label - Replaces the `label` prop with markup.
+ * @slot description - Replaces the `description` prop with markup.
+ * @part heading - The title block.
+ * @part title - The title text.
+ * @part description - The description text.
+ * @part bar - The toolbar and batch bar wrapper.
+ * @part toolbar - The toolbar.
+ * @part batch - The batch actions bar.
+ * @part scroll - The horizontal scroll container.
+ * @part grid - The grid itself.
+ * @part head - The header row.
+ * @part header-cell - One header cell.
+ * @part body - The body wrapper.
+ * @part pagination - The pagination block.
+ * @part column-picker - The menu that hides and shows columns.
+ * @part empty - The empty state.
+ * @part loading - The loading overlay.
+ */
 export declare class XvTable {
     el: HTMLElement;
+    /** Column definitions. Accepts its JSON string form so it is settable from plain markup. */
+    columns: string | XvTableColumn[];
+    /** Row data. Ignored when `xv-table-row` children are slotted. */
+    rows: string | any[];
+    /** Property of a row object that identifies it in selection and expansion payloads. */
+    rowKey: string;
+    /** Row height ladder. */
     size: SIZE_VAR_STR;
-    hover?: boolean;
-    loading?: boolean;
-    colsSize?: (string | null)[];
-    selected: Map<string, SelectRowDto>;
-    selectedCount: number;
-    handleCheckedChange({ detail }: CustomEvent<SelectRowDto>): void;
-    private setColsSizeTemplate;
-    render(): any;
+    /** Stretches the table to the full width of its container. */
+    block: boolean;
+    /** Covers the body with a loading state. */
+    loading: boolean;
+    /** Placeholder rows drawn while `loading`. Zero draws a spinner instead. */
+    skeletonRows: number;
+    /** Highlights a row on pointer hover. */
+    hover: boolean;
+    /** Emits `rowClick` when a row is clicked outside an interactive element. */
+    rowClickable: boolean;
+    /** Title above the table. */
+    label: string;
+    /** Supporting text under the title. */
+    description: string;
+    /** Shown when there are no rows. */
+    emptyLabel: string;
+    /** Text of the batch bar counter. `{count}` is replaced with the number of selected rows. */
+    selectedLabel: string;
+    /** Tooltip on the column picker trigger. */
+    columnsLabel: string;
+    /** Text of the button that restores the declared column layout. */
+    resetLabel: string;
+    /** Accessible name of a row's expand toggle. */
+    expandLabel: string;
+    /** Accessible name of a row's drag grip. */
+    reorderLabel: string;
+    /**
+     * `none` makes headers inert whatever the column says; `client` sorts the `rows` prop itself;
+     * `server` offers the affordance and only emits `sortChange` for the consumer to reload.
+     */
+    sortMode: XvTableMode;
+    /** Active sort, as `asc(field)` / `desc(field)` or an object. */
+    sortBy: string | XvTableSort;
+    /** `multiple` renders checkboxes, `single` renders radios. */
+    selection: XvTableSelectionMode;
+    /** Values of the selected rows. */
+    selected: string | unknown[];
+    /** Whether rows expand, and whether more than one may be open. */
+    expandMode: XvTableExpandMode;
+    /** Values of the expanded rows. */
+    expanded: string | unknown[];
+    /** `client` slices the `rows` prop; `server` only emits `pageChange`. */
+    paginationMode: XvTableMode;
+    /** Current page, 1-based. */
+    page: number;
+    /** Rows per page. */
+    pageSize: number;
+    /** Total row count, for `server` pagination. */
+    total: number;
+    /** Page size choices. Accepts a comma-separated attribute. */
+    pageSizeOptions: string | number[];
+    /**
+     * Allows dragging column edges. Off by default: no handle is rendered and nothing is bound
+     * until it is switched on. A column may switch itself off, never on.
+     */
+    resizable: boolean;
+    /** Allows dragging column headers into a new order. Off by default, like `resizable`. */
+    reorderable: boolean;
+    /**
+     * Allows dragging rows into a new order. Off by default: nothing is bound and no handle is
+     * rendered until it is switched on.
+     */
+    rowReorderable: boolean;
+    /** Whether the whole row drags, or only a grip in a leading control cell. */
+    rowReorderHandle: 'icon' | 'row';
+    /** Keeps the header visible while the body scrolls. */
+    stickyHeader: boolean;
+    /**
+     * Width below which the table scrolls instead of squeezing, at any viewport. Left unset, a table
+     * only stops squeezing below 1180px, where it scrolls at the width its columns declared.
+     */
+    minWidth: number;
+    /** Persists the column layout under this key. Empty means the layout is not remembered. */
+    storageKey: string;
+    /** Scopes the stored layout to a user. */
+    storageOwner: string;
+    /** Controlled column layout. Overrides whatever is stored. */
+    layout: string | XvTableLayout;
+    /** Locale used for sorting and cell formatting. Falls back to the nearest `[lang]` ancestor. */
+    locale: string;
+    /** Emitted when a sortable header is activated. */
+    sortChange: EventEmitter<XvTableSort>;
+    /**
+     * Emitted when the set of selected rows changes. Named after the `selected` prop it reports:
+     * `selectionChange` is refused by Stencil as a native DOM event name.
+     */
+    selectedChange: EventEmitter<XvTableSelectionDetail>;
+    /** Emitted when the set of expanded rows changes. */
+    expandedChange: EventEmitter<XvTableExpandedDetail>;
+    /** Emitted when the page or the page size changes. */
+    pageChange: EventEmitter<XvTablePage>;
+    /** Emitted after a column is resized, reordered, hidden or reset. */
+    layoutChange: EventEmitter<XvTableLayout>;
+    /** Emitted when a row is clicked, while `rowClickable` is set. */
+    rowClick: EventEmitter<XvTableRowClickDetail>;
+    /**
+     * Emitted when a row is dropped in a new position. The table does not move the row itself —
+     * reorder the data and it re-renders, which keeps the DOM and the data from drifting apart.
+     */
+    rowOrderChange: EventEmitter<XvTableRowOrder>;
+    columnState: XvTableColumn[];
+    sortState: XvTableSort | null;
+    selectedValues: unknown[];
+    expandedValues: unknown[];
+    layoutPending: boolean;
+    columnDragging: boolean;
+    dragOverId: string;
+    dropRowIndex: number;
+    slottedRowCount: number;
+    derivedTracks: string[];
+    hasSlottedHeader: boolean;
+    hasSlottedHeading: boolean;
+    hasSlottedEmpty: boolean;
+    overflowing: boolean;
+    private declared;
+    private declaredSignature;
+    /** Whether the columns came from a slotted header rather than the `columns` prop. */
+    private fromMarkup;
+    private rowData;
+    private seededExpanded;
+    private collapsed;
+    private dragRowIndex;
+    private gridEl?;
+    private scrollEl?;
+    private rowObserver?;
+    private sizeObserver?;
+    private layoutToken;
+    private dragColumnId;
     componentWillLoad(): void;
+    componentDidLoad(): void;
+    componentDidRender(): void;
+    disconnectedCallback(): void;
+    /**
+     * A declared width is a floor, so columns that cannot fit overflow rather than squeeze. The table
+     * scrolls them into reach instead of letting them hang outside the block they were given.
+     */
+    private measureOverflow;
+    columnsChanged(): void;
+    layoutInputChanged(): void;
+    sortByChanged(): void;
+    selectedChanged(): void;
+    expandedChanged(): void;
+    rowsChanged(): void;
+    /** Selects every selectable row. */
+    selectAll(): Promise<void>;
+    /** Clears the selection. */
+    clearSelection(): Promise<void>;
+    /** Drops the stored layout and returns to the declared columns. */
+    resetLayout(): Promise<void>;
+    /** The layout as it would be stored: only the deviations from the declared columns. */
+    getLayout(): Promise<XvTableLayout>;
+    private restoreLayout;
+    private commitLayout;
+    private get localeTag();
+    private get visible();
+    private get hasSelection();
+    private get hasExpand();
+    private get template();
+    /** Grip, then the expand toggle, then selection — one track each, in render order. */
+    private get leadingTracks();
+    private get trailingTracks();
+    private get dataRows();
+    private get rowTotal();
+    private get isEmpty();
+    private columnBySortName;
+    private touchesStructure;
+    private isBodyRow;
+    /** Body rows only — these are the ones selection and expansion count. */
+    private slottedRows;
+    /** A page is counted in top-level rows: a group and its children travel together. */
+    private topRows;
+    /** Every slotted row, footer included: they all need the column tracks lined up. */
+    private slottedRowsAll;
+    /** Every row on screen, whichever mode produced it. */
+    private renderedRows;
+    private rowValues;
+    /** A disabled row is not selectable, so it stays out of every selection set. */
+    private isDisabled;
+    /** `parent` may arrive as an attribute or as a property, depending on the consumer. */
+    private parentOf;
+    private parentValues;
+    private childValuesOf;
+    /** One walk of the rows answers every parent/child question asked during a sync. */
+    private buildTree;
+    /**
+     * Child rows declare their parent by value. They stay siblings in the grid — that is what keeps
+     * them in the table's columns, rather than a nested table inside a panel.
+     */
+    private syncRowTree;
+    /** Only rows this table hid are shown again, so a consumer's own `hidden` survives a sync. */
+    private showRow;
+    /** The rows of the current page, or null while the table is not the one paging. */
+    private pageWindow;
+    /** Cells are written in declared order; hiding and reordering only move them visually. */
+    private syncCells;
+    /** Structure writes @State, so it runs outside the render cycle: on load and on childList. */
+    private syncStructure;
+    /**
+     * A row may declare itself open in markup. Read once, before the table starts writing the
+     * attribute itself — after that there is no telling a declared value from a toggled one.
+     */
+    private seedExpanded;
+    /** Pushing props onto children is safe during render; nothing here touches @State. */
+    private syncRows;
+    /** Sorting is offered only when a mode asks for it, so `none` and `server` cannot look alike. */
+    private isSortable;
+    /**
+     * A slotted header is the consumer's markup, so the table pushes the column state onto its cells
+     * rather than rendering a second header of its own.
+     */
+    private syncHeaderCells;
+    /** Reads the column shape out of the markup when no `columns` prop was given. */
+    private syncDerivedTracks;
+    /**
+     * With no `columns` prop the header cells are the declaration: their attributes carry the id,
+     * width and switches, so a markup-only table still resizes, reorders and remembers its layout.
+     */
+    private deriveColumns;
+    private toggleSort;
+    private resizeStart;
+    private resizeReset;
+    /** Every header cell on screen, whether the table rendered it or the consumer slotted it. */
+    private headerCells;
+    /** A header cell knows its column by id, or failing that by its position in the row. */
+    private columnOf;
+    private headerCellFrom;
+    private headPointerDown;
+    private headKeyDown;
+    private headDblClick;
+    private headDragStart;
+    private headDragOver;
+    private headDrop;
+    private dragStart;
+    private dragOver;
+    private drop;
+    private clearDragOver;
+    private dragEnd;
+    private setSelection;
+    private toggleRowSelection;
+    private toggleSelectAll;
+    private toggleExpanded;
+    private toggleColumn;
+    private bodyRows;
+    private rowFrom;
+    private rowDragStart;
+    private rowDragOver;
+    private rowDrop;
+    private rowDragEnd;
+    /** One listener for the whole body instead of a child event per row. */
+    private bodyChange;
+    private gridClick;
+    private bodyClick;
+    private paginationChanged;
+    /** The same row and cell components the consumer would write by hand. */
+    private renderHead;
+    private renderDataRow;
+    private renderSkeleton;
+    private renderColumnPicker;
+    render(): any;
 }

package/dist/types/components/xv-table/xv-table.model.d.ts

@@ -0,0 +1,78 @@
+import { SIZE_VAR_STR, XV_SORT_DIR } from '../../types/enum';
+export type XvTableSize = SIZE_VAR_STR;
+export type XvTableSelectionMode = 'none' | 'single' | 'multiple';
+export type XvTableExpandMode = 'none' | 'single' | 'multiple';
+export type XvTableMode = 'none' | 'client' | 'server';
+export type XvCellAlign = 'start' | 'center' | 'end';
+export type XvCellOverflow = 'ellipsis' | 'clamp' | 'wrap';
+export type XvCellFormat = 'text' | 'number' | 'currency' | 'date' | 'period' | 'list';
+export interface XvTableColumn {
+    id: string;
+    label?: string;
+    sortable?: boolean;
+    sortName?: string;
+    align?: XvCellAlign;
+    /** Header alignment. Headers read left unless this says otherwise, whatever `align` does. */
+    headerAlign?: XvCellAlign;
+    overflow?: XvCellOverflow;
+    clampLines?: number;
+    /** A number is pixels. A CSS length — `25%`, `auto`, `12rem` — is written into the track as is. */
+    width?: number | string;
+    minWidth?: number;
+    maxWidth?: number;
+    resizable?: boolean;
+    reorderable?: boolean;
+    hideable?: boolean;
+    hidden?: boolean;
+    headerTooltip?: string;
+    value?: string | ((row: any) => unknown);
+    format?: XvCellFormat;
+    formatArg?: string;
+}
+export interface XvTableLayout {
+    v: number;
+    order: string[];
+    widths: Record<string, number>;
+    hidden: Record<string, boolean>;
+}
+export interface XvTableLayoutRecord {
+    id: string;
+    owner: string;
+    storageKey: string;
+    layout: XvTableLayout;
+    updatedAt: number;
+}
+export interface XvTableSort {
+    name: string;
+    direction: XV_SORT_DIR;
+}
+export interface XvTableSelectionDetail {
+    values: unknown[];
+    all: boolean;
+    partial: boolean;
+}
+export interface XvTablePage {
+    page: number;
+    pageSize: number;
+}
+export interface XvTableExpandedDetail {
+    values: unknown[];
+}
+export interface XvTableRowOrder {
+    from: number;
+    to: number;
+}
+export interface XvTableRowClickDetail {
+    value: unknown;
+    index: number;
+}
+export declare const XV_TABLE_TAG = "xv-table";
+export declare const XV_TABLE_ROW_TAG = "xv-table-row";
+export declare const XV_TABLE_CELL_TAG = "xv-table-cell";
+export declare const XV_TABLE_LAYOUT_VERSION = 1;
+/** The floor a resize drag may not cross, when the column names no minWidth. */
+export declare const XV_TABLE_MIN_COLUMN_WIDTH = 64;
+/** Per visible column, the width below which the table scrolls instead of squeezing. */
+export declare const XV_TABLE_SCROLL_COLUMN_WIDTH = 120;
+export declare const XV_TABLE_CONTROL_WIDTH = 48;
+export declare const XV_TABLE_DEFAULT_PAGE_SIZES: number[];

package/dist/types/components/xv-table/xv-table.utils.d.ts

@@ -0,0 +1,47 @@
+import { XV_SORT_DIR } from '../../types/enum';
+import { XvTableColumn, XvTableLayout, XvTableSort } from './xv-table.model';
+/** Array and object props accept their JSON string form so they stay settable from plain markup. */
+export declare const parseProp: <T>(value: string | T, fallback: T) => T;
+export declare const parsePageSizes: (value: string | number[]) => number[];
+export declare const parseSortBy: (value: string | XvTableSort) => XvTableSort | null;
+/** The `asc(field)` shape ListStateService already speaks, so an Angular binding needs no adapter. */
+export declare const formatSortBy: (sort: XvTableSort | null) => string;
+export declare const nextSortDirection: (current: XV_SORT_DIR | null) => XV_SORT_DIR;
+export declare const sortName: (column: XvTableColumn) => string;
+export declare const cellValue: (row: any, column: XvTableColumn) => unknown;
+/** Empty values sort last in both directions — a blank cell is not "smallest", it is missing. */
+export declare const compareValues: (a: unknown, b: unknown, locale: string) => number;
+export declare const sortRows: <T>(rows: T[], column: XvTableColumn | null, direction: XV_SORT_DIR, locale: string) => T[];
+export declare const totalPages: (total: number, pageSize: number) => number;
+export declare const clampPage: (page: number, pages: number) => number;
+export declare const pageSlice: <T>(rows: T[], page: number, pageSize: number) => T[];
+export declare const visibleColumns: (columns: XvTableColumn[]) => XvTableColumn[];
+export declare const hideableColumns: (columns: XvTableColumn[]) => XvTableColumn[];
+/** A column may narrow a table-level switch, never widen it. */
+export declare const columnAllows: (column: XvTableColumn, table: boolean, key: "resizable" | "reorderable") => boolean;
+export declare const clampWidth: (width: number, column: XvTableColumn) => number;
+/**
+ * What the rigid parts of the table actually need. A pixel column needs its width; a percentage
+ * column squeezes by definition and asks for nothing; a column that named no width gets the
+ * scroll-width guess. Guessing for all of them made a table of narrow columns scroll for nothing.
+ */
+export declare const tableMinWidth: (columns: XvTableColumn[], minWidth?: number, controls?: number) => number;
+/**
+ * The grid track list. Resize rewrites this one string on the host, which is a single DOM write
+ * per pointermove — a colgroup would need one per `<col>`. One track per control column: a grip
+ * and a checkbox are separate cells, so they need separate tracks.
+ */
+export declare const buildColumnTracks: (columns: XvTableColumn[], leading?: number[], trailing?: number[]) => string[];
+export declare const buildColumnTemplate: (columns: XvTableColumn[], leading?: number[], trailing?: number[]) => string;
+export declare const moveItem: <T>(items: T[], from: number, to: number) => T[];
+/** Hidden columns keep their absolute slot while the visible ones move around them. */
+export declare const mergeVisibleOrder: (columns: XvTableColumn[], ordered: XvTableColumn[]) => XvTableColumn[];
+/**
+ * Only the deviations from the declared columns are stored. An untouched column follows the code,
+ * so a later default still reaches everyone who once dragged a column edge.
+ */
+export declare const diffLayout: (columns: XvTableColumn[], declared: XvTableColumn[]) => XvTableLayout;
+export declare const isLayoutChanged: (layout: XvTableLayout | null) => boolean;
+/** Merges onto clones, so a stored width never writes back into the page's declared preset. */
+export declare const applyLayout: (declared: XvTableColumn[], layout: XvTableLayout | null) => XvTableColumn[];
+export declare const formatCell: (value: unknown, column: XvTableColumn, locale: string) => string;