@juspay/svelte-ui-components 2.80.9 → 2.81.0

package/dist/Table/cellData.d.ts

@@ -0,0 +1,48 @@
+import type { JSONValue } from 'type-decoder';
+import type { InputDataType } from '../types';
+import type { IconStackItem } from '../IconStack/properties';
+import type { TableActionGroupCellData, TableAvatarStackCellData, TableButtonCellData, TableCompareCellData, TableInputCellData, TableLinkCellData, TablePopupMenuCellData, TableSelectCellData, TableTagArrayCellItem, TableTagCellData, TableCellValue } from './properties';
+/**
+ * Structural narrowing helpers for the built-in cell renderers. Each renderer
+ * accepts an arbitrary `TableCellValue` and renders its structured shape only
+ * when the value actually matches — scalar values fall back to plain text, so
+ * mixed columns (e.g. compare rows next to plain rows) are well-defined.
+ * Shapes are rebuilt field by field from the raw JSON rather than asserted.
+ */
+export declare const asJsonObject: (value: TableCellValue) => {
+    [key: string]: JSONValue;
+} | null;
+export declare const asTagCellData: (value: TableCellValue) => TableTagCellData | null;
+export declare const asTagArrayItems: (value: TableCellValue) => TableTagArrayCellItem[] | null;
+export declare const asAvatarStackData: (value: TableCellValue) => TableAvatarStackCellData | null;
+export declare const asCompareCellData: (value: TableCellValue) => TableCompareCellData | null;
+export declare const asLinkCellData: (value: TableCellValue) => TableLinkCellData | null;
+export declare const asSelectCellData: (value: TableCellValue) => TableSelectCellData | null;
+export declare const asInputCellData: (value: TableCellValue) => TableInputCellData | null;
+/**
+ * Narrows a free-form `dataType` string from cell data to the `Input`
+ * component's `InputDataType` union, falling back to `'text'` for any
+ * unrecognised value.
+ */
+export declare const asInputDataType: (value: string | null) => InputDataType;
+export declare const asButtonCellData: (value: TableCellValue) => TableButtonCellData | null;
+export declare const asActionGroupCellData: (value: TableCellValue) => TableActionGroupCellData | null;
+export declare const asPopupMenuCellData: (value: TableCellValue) => TablePopupMenuCellData | null;
+/** Fallback text rendering for a cell value that failed structural narrowing. */
+export declare const cellValueToText: (value: TableCellValue) => string;
+/**
+ * First display character for an avatar chip. Falls back to the last
+ * alphanumeric character of the id when the label is missing, so each chip
+ * renders a distinct character instead of a row of identical placeholders.
+ * Indexes by codepoint, not UTF-16 unit, so a non-BMP first character (emoji)
+ * renders whole instead of as half a surrogate pair.
+ */
+export declare const avatarInitial: (item: {
+    id: string;
+    label?: string;
+}) => string;
+/** Visible initials chips plus the "+N" overflow count for an avatar stack. */
+export declare const buildAvatarStack: (data: TableAvatarStackCellData) => {
+    icons: IconStackItem[];
+    rest: number;
+};

package/dist/Table/cellData.js

@@ -0,0 +1,292 @@
+/**
+ * Structural narrowing helpers for the built-in cell renderers. Each renderer
+ * accepts an arbitrary `TableCellValue` and renders its structured shape only
+ * when the value actually matches — scalar values fall back to plain text, so
+ * mixed columns (e.g. compare rows next to plain rows) are well-defined.
+ * Shapes are rebuilt field by field from the raw JSON rather than asserted.
+ */
+export const asJsonObject = (value) => {
+    if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+        return value;
+    }
+    return null;
+};
+export const asTagCellData = (value) => {
+    const record = asJsonObject(value);
+    if (record === null || typeof record.text !== 'string') {
+        return null;
+    }
+    const tagData = { text: record.text };
+    if (typeof record.classes === 'string') {
+        tagData.classes = record.classes;
+    }
+    if (typeof record.dismissible === 'boolean') {
+        tagData.dismissible = record.dismissible;
+    }
+    if (typeof record.testId === 'string') {
+        tagData.testId = record.testId;
+    }
+    return tagData;
+};
+export const asTagArrayItems = (value) => {
+    if (!Array.isArray(value)) {
+        return null;
+    }
+    const items = [];
+    for (const rawItem of value) {
+        const record = asJsonObject(rawItem);
+        if (record === null || typeof record.text !== 'string') {
+            return null;
+        }
+        const item = { text: record.text };
+        if (typeof record.classes === 'string') {
+            item.classes = record.classes;
+        }
+        items.push(item);
+    }
+    return items;
+};
+export const asAvatarStackData = (value) => {
+    const record = asJsonObject(value);
+    if (record === null || !Array.isArray(record.items)) {
+        return null;
+    }
+    const items = [];
+    for (const rawItem of record.items) {
+        const itemRecord = asJsonObject(rawItem);
+        if (itemRecord === null || typeof itemRecord.id !== 'string') {
+            return null;
+        }
+        const item = { id: itemRecord.id };
+        if (typeof itemRecord.label === 'string') {
+            item.label = itemRecord.label;
+        }
+        items.push(item);
+    }
+    const stackData = { items };
+    if (typeof record.max === 'number') {
+        stackData.max = record.max;
+    }
+    return stackData;
+};
+export const asCompareCellData = (value) => {
+    const record = asJsonObject(value);
+    if (record === null) {
+        return null;
+    }
+    const compareData = {};
+    if (typeof record.primary === 'string') {
+        compareData.primary = record.primary;
+    }
+    if (typeof record.comparison === 'string') {
+        compareData.comparison = record.comparison;
+    }
+    if (typeof record.trendPercent === 'number') {
+        compareData.trendPercent = record.trendPercent;
+    }
+    if (typeof record.trendLabel === 'string') {
+        compareData.trendLabel = record.trendLabel;
+    }
+    return compareData;
+};
+export const asLinkCellData = (value) => {
+    if (typeof value === 'string' && value.length > 0) {
+        return { url: value };
+    }
+    const record = asJsonObject(value);
+    if (record === null || typeof record.url !== 'string') {
+        return null;
+    }
+    const linkData = { url: record.url };
+    if (typeof record.label === 'string') {
+        linkData.label = record.label;
+    }
+    if (typeof record.copyable === 'boolean') {
+        linkData.copyable = record.copyable;
+    }
+    return linkData;
+};
+export const asSelectCellData = (value) => {
+    const record = asJsonObject(value);
+    if (record === null || !Array.isArray(record.options)) {
+        return null;
+    }
+    const options = [];
+    for (const rawOption of record.options) {
+        const optionRecord = asJsonObject(rawOption);
+        if (optionRecord === null ||
+            typeof optionRecord.id !== 'string' ||
+            typeof optionRecord.label !== 'string') {
+            return null;
+        }
+        options.push({ id: optionRecord.id, label: optionRecord.label });
+    }
+    const selectData = { options };
+    if (typeof record.selectedId === 'string') {
+        selectData.selectedId = record.selectedId;
+    }
+    if (typeof record.placeholder === 'string') {
+        selectData.placeholder = record.placeholder;
+    }
+    if (typeof record.disabled === 'boolean') {
+        selectData.disabled = record.disabled;
+    }
+    if (typeof record.testId === 'string') {
+        selectData.testId = record.testId;
+    }
+    return selectData;
+};
+export const asInputCellData = (value) => {
+    const record = asJsonObject(value);
+    if (record === null) {
+        return null;
+    }
+    const inputData = {};
+    if (typeof record.value === 'string') {
+        inputData.value = record.value;
+    }
+    if (typeof record.placeholder === 'string') {
+        inputData.placeholder = record.placeholder;
+    }
+    if (typeof record.disabled === 'boolean') {
+        inputData.disabled = record.disabled;
+    }
+    if (typeof record.testId === 'string') {
+        inputData.testId = record.testId;
+    }
+    if (typeof record.dataType === 'string') {
+        inputData.dataType = record.dataType;
+    }
+    if (typeof record.validationPattern === 'string') {
+        inputData.validationPattern = record.validationPattern;
+    }
+    if (typeof record.onErrorMessage === 'string') {
+        inputData.onErrorMessage = record.onErrorMessage;
+    }
+    return inputData;
+};
+/**
+ * Narrows a free-form `dataType` string from cell data to the `Input`
+ * component's `InputDataType` union, falling back to `'text'` for any
+ * unrecognised value.
+ */
+export const asInputDataType = (value) => {
+    switch (value) {
+        case 'tel':
+        case 'password':
+        case 'email':
+        case 'number':
+            return value;
+        default:
+            return 'text';
+    }
+};
+export const asButtonCellData = (value) => {
+    const record = asJsonObject(value);
+    if (record === null || typeof record.text !== 'string') {
+        return null;
+    }
+    const buttonData = { text: record.text };
+    if (typeof record.disabled === 'boolean') {
+        buttonData.disabled = record.disabled;
+    }
+    if (typeof record.classes === 'string') {
+        buttonData.classes = record.classes;
+    }
+    if (typeof record.testId === 'string') {
+        buttonData.testId = record.testId;
+    }
+    return buttonData;
+};
+const asMenuItemsData = (rawItems) => {
+    if (!Array.isArray(rawItems)) {
+        return null;
+    }
+    const menuItems = [];
+    for (const rawItem of rawItems) {
+        const record = asJsonObject(rawItem);
+        if (record === null || typeof record.id !== 'string') {
+            return null;
+        }
+        const item = { id: record.id };
+        if (typeof record.label === 'string') {
+            item.label = record.label;
+        }
+        if (typeof record.danger === 'boolean') {
+            item.danger = record.danger;
+        }
+        if (typeof record.separator === 'boolean') {
+            item.separator = record.separator;
+        }
+        menuItems.push(item);
+    }
+    return menuItems;
+};
+export const asActionGroupCellData = (value) => {
+    const record = asJsonObject(value);
+    if (record === null) {
+        return null;
+    }
+    const primaryButton = asButtonCellData(record.primaryButton ?? null);
+    const menuItems = asMenuItemsData(record.menuItems ?? null);
+    if (primaryButton === null && menuItems === null) {
+        return null;
+    }
+    const actionData = {};
+    if (primaryButton !== null) {
+        actionData.primaryButton = primaryButton;
+    }
+    if (menuItems !== null) {
+        actionData.menuItems = menuItems;
+    }
+    return actionData;
+};
+export const asPopupMenuCellData = (value) => {
+    const record = asJsonObject(value);
+    if (record === null) {
+        return null;
+    }
+    const items = asMenuItemsData(record.items ?? null);
+    if (items === null || items.length === 0) {
+        return null;
+    }
+    const popupData = { items };
+    if (typeof record.ariaLabel === 'string') {
+        popupData.ariaLabel = record.ariaLabel;
+    }
+    return popupData;
+};
+/** Fallback text rendering for a cell value that failed structural narrowing. */
+export const cellValueToText = (value) => {
+    if (value === null || typeof value === 'undefined' || value === '') {
+        return '-';
+    }
+    if (typeof value === 'object') {
+        return '-';
+    }
+    return String(value);
+};
+/**
+ * First display character for an avatar chip. Falls back to the last
+ * alphanumeric character of the id when the label is missing, so each chip
+ * renders a distinct character instead of a row of identical placeholders.
+ * Indexes by codepoint, not UTF-16 unit, so a non-BMP first character (emoji)
+ * renders whole instead of as half a surrogate pair.
+ */
+export const avatarInitial = (item) => {
+    if (item.label && Array.from(item.label).length > 0) {
+        return Array.from(item.label)[0].toUpperCase();
+    }
+    const tail = item.id.replace(/[^A-Za-z0-9]/g, '').slice(-1);
+    return tail.toUpperCase() || '#';
+};
+/** Visible initials chips plus the "+N" overflow count for an avatar stack. */
+export const buildAvatarStack = (data) => {
+    const max = data.max ?? 4;
+    const items = data.items ?? [];
+    const visible = items.slice(0, max);
+    return {
+        icons: visible.map((item) => ({ type: 'text', content: avatarInitial(item) })),
+        rest: items.length - visible.length
+    };
+};

package/dist/Table/normalizeColumns.d.ts

@@ -0,0 +1,24 @@
+import type { JSONValue } from 'type-decoder';
+import type { TableColumn, TableRow } from './properties';
+/**
+ * Result of projecting the keyed column model onto Table's positional engine.
+ *
+ * - `tableHeaders` — column labels, in column order.
+ * - `tableData` — one positional array per row, cells in column order; a key
+ *   missing from a row projects to `null` (renders as an empty cell).
+ * - `sortableColumns` — indices of columns whose `sortable` is not `false`,
+ *   or `null` when no column opts out (preserving the table-wide default of
+ *   "all columns sortable").
+ */
+export type NormalizedColumns = {
+    tableHeaders: string[];
+    tableData: Array<JSONValue[]>;
+    sortableColumns: number[] | null;
+};
+/**
+ * Projects the keyed `columns`/`rows` model onto the positional
+ * `tableHeaders`/`tableData` shape that Table's sort/search/selection engine
+ * operates on. Pure and deterministic — exported so consumers can unit-test
+ * their own column/row assembly against the exact projection Table uses.
+ */
+export declare const normalizeColumns: (columns: TableColumn[], rows: TableRow[]) => NormalizedColumns;

package/dist/Table/normalizeColumns.js

@@ -0,0 +1,23 @@
+/**
+ * Projects the keyed `columns`/`rows` model onto the positional
+ * `tableHeaders`/`tableData` shape that Table's sort/search/selection engine
+ * operates on. Pure and deterministic — exported so consumers can unit-test
+ * their own column/row assembly against the exact projection Table uses.
+ */
+export const normalizeColumns = (columns, rows) => {
+    const tableHeaders = columns.map((column) => column.label);
+    const tableData = rows.map((row) => columns.map((column) => {
+        const cellValue = row[column.id];
+        return cellValue ?? null;
+    }));
+    const hasSortOptOut = columns.some((column) => column.sortable === false);
+    const sortableColumns = hasSortOptOut
+        ? columns.reduce((sortableIndices, column, columnIndex) => {
+            if (column.sortable !== false) {
+                sortableIndices.push(columnIndex);
+            }
+            return sortableIndices;
+        }, [])
+        : null;
+    return { tableHeaders, tableData, sortableColumns };
+};

package/dist/Table/properties.d.ts

@@ -1,6 +1,218 @@
 import type { JSONValue } from 'type-decoder';
 import type { Snippet } from 'svelte';
 export type SortDirection = 'asc' | 'desc';
+/**
+ * Built-in cell renderer vocabulary for the keyed column model.
+ *
+ * `'text'` (the default) renders the cell value as plain text through the
+ * existing engine; `'custom'` delegates rendering entirely to the column's
+ * own `cell` snippet. The remaining types are built-in renderers composed
+ * purely from library primitives — each expects its matching `Table*CellData`
+ * shape as the cell value and falls back to plain text for scalar values.
+ */
+export type TableColumnType = 'text' | 'tag' | 'text-tag' | 'two-line-text' | 'icon-label' | 'image-two-line-text' | 'tag-array' | 'avatar-stack' | 'compare' | 'toggle' | 'link' | 'select' | 'input' | 'button' | 'action-group' | 'popup-menu' | 'custom';
+/**
+ * Cell value for the keyed row model: plain JSON. Structured cell shapes
+ * (`TableTagCellData`, `TableCompareCellData`, …) are JSON-compatible
+ * objects, so rows stay serializable; behavior (e.g. a toggle handler)
+ * lives on the column, never in row data.
+ */
+export type TableCellValue = JSONValue;
+/** Cell shape for `type: 'tag'` — a single Pill. */
+export type TableTagCellData = {
+    text: string;
+    /** CSS classes forwarded to the Pill (the consumer owns tone mapping). */
+    classes?: string;
+    dismissible?: boolean;
+    testId?: string;
+};
+/** Cell shape for `type: 'text-tag'` — text with an optional trailing Pill. */
+export type TableTextTagCellData = {
+    text: string;
+    tag?: TableTagCellData;
+};
+/** Cell shape for `type: 'two-line-text'` — primary over secondary line. */
+export type TableTwoLineTextCellData = {
+    text1?: string;
+    text2?: string;
+};
+/** Cell shape for `type: 'icon-label'` — leading image(s) plus a label. */
+export type TableIconLabelCellData = {
+    icons?: string[];
+    label?: string;
+};
+/** Cell shape for `type: 'image-two-line-text'` — thumbnail plus two lines. */
+export type TableImageTwoLineTextCellData = {
+    imageUrl?: string;
+    text1?: string;
+    text2?: string;
+};
+/** One chip of a `type: 'tag-array'` cell. */
+export type TableTagArrayCellItem = {
+    text: string;
+    classes?: string;
+};
+/** Cell shape for `type: 'avatar-stack'` — initials chips with overflow. */
+export type TableAvatarStackCellData = {
+    items: Array<{
+        id: string;
+        label?: string;
+    }>;
+    /** Chips rendered before collapsing into a "+N" overflow. Default 4. */
+    max?: number;
+};
+/**
+ * Cell shape for `type: 'compare'` — a primary value over a comparison value
+ * with an optional trend row (percent with up/down arrow, or a plain label).
+ * Scalar cell values in the same column render as plain text, so compare and
+ * plain rows coexist.
+ */
+export type TableCompareCellData = {
+    primary?: string;
+    comparison?: string;
+    trendPercent?: number;
+    trendLabel?: string;
+};
+/** Cell shape for `type: 'toggle'` — the handler lives on the column. */
+export type TableToggleCellData = {
+    checked?: boolean;
+    ariaLabel?: string;
+    testId?: string;
+};
+/** Cell shape for `type: 'link'` — external link with an optional copy affordance. */
+export type TableLinkCellData = {
+    url: string;
+    /** Visible text; defaults to the url. */
+    label?: string;
+    /** Renders a copy-to-clipboard button next to the link. Default true. */
+    copyable?: boolean;
+};
+/** Cell shape for `type: 'select'` — the handler lives on the column. */
+export type TableSelectCellData = {
+    options: Array<{
+        id: string;
+        label: string;
+    }>;
+    selectedId?: string;
+    placeholder?: string;
+    disabled?: boolean;
+    testId?: string;
+};
+/** Cell shape for `type: 'input'` — the handler lives on the column. */
+export type TableInputCellData = {
+    value?: string;
+    placeholder?: string;
+    disabled?: boolean;
+    testId?: string;
+    /** Input dataType forwarded to the rendered Input ('text' | 'tel' | 'number' | …). */
+    dataType?: string;
+    /**
+     * Live-validation pattern forwarded to the rendered Input. A RegExp SOURCE
+     * string (cell data must stay JSON-safe) — compiled at render time.
+     */
+    validationPattern?: string;
+    /** Inline error message shown when the validation pattern rejects the value. */
+    onErrorMessage?: string;
+};
+/** Cell shape for `type: 'button'` — the handler lives on the column. */
+export type TableButtonCellData = {
+    text: string;
+    disabled?: boolean;
+    /** CSS classes forwarded to the Button (the consumer owns variant mapping). */
+    classes?: string;
+    testId?: string;
+};
+/** One overflow-menu entry for action-group / popup-menu cells (JSON-safe). */
+export type TableMenuItemData = {
+    id: string;
+    /** Visible label; defaults to the id. */
+    label?: string;
+    danger?: boolean;
+    separator?: boolean;
+};
+/** Cell shape for `type: 'action-group'` — primary button plus overflow menu. */
+export type TableActionGroupCellData = {
+    primaryButton?: TableButtonCellData;
+    menuItems?: TableMenuItemData[];
+};
+/** Cell shape for `type: 'popup-menu'` — a kebab-triggered row menu. */
+export type TablePopupMenuCellData = {
+    items: TableMenuItemData[];
+    ariaLabel?: string;
+};
+/**
+ * Per-column header filter dropdown. Table renders the dropdown mechanics
+ * (a Menu beside the header label with the current selection highlighted);
+ * the options, selection state, and filtering itself belong to the consumer.
+ * Selecting the already-selected option clears the filter (emits `null`).
+ */
+export type TableColumnFilterConfig = {
+    options: Array<{
+        label: string;
+        value: string;
+    }>;
+    selectedValue?: string | null;
+    onFilterChange?: (value: string | null) => void;
+};
+/**
+ * Keyed row shape for the keyed column model: cell values addressed by
+ * `TableColumn.id` instead of array position. Keys missing from a row render
+ * as empty cells.
+ */
+export type TableRow = Record<string, TableCellValue>;
+/**
+ * Column definition for the keyed column model.
+ *
+ * - `id` — key into each `TableRow` for this column's cell value.
+ * - `label` — header text (fills the same role as a `tableHeaders` entry).
+ * - `type` — built-in renderer selection; defaults to `'text'`.
+ * - `sortable` — per-column sort opt-out; defaults to the table-wide
+ *   `sortable` prop. Equivalent to listing/omitting the column's index in
+ *   `sortableColumns`.
+ * - `testId` — `data-pw` attribute emitted on this column's header cell.
+ * - `cell` — column-scoped renderer snippet receiving the full keyed row and
+ *   the row index. Takes precedence over the table-wide `cell` snippet for
+ *   this column; required when `type` is `'custom'`.
+ * - `onToggle`/`onSelect`/`onInput`/`onButtonClick`/`onPrimaryAction`/`onMenuAction`
+ *   — change/action handlers for the matching interactive cell types. Behavior
+ *   lives on the column so row data stays plain JSON.
+ */
+export type TableColumn = {
+    id: string;
+    label: string;
+    type?: TableColumnType;
+    sortable?: boolean;
+    testId?: string;
+    cell?: Snippet<[TableRow, number]>;
+    /** Header tooltip text, shown on hover over the column label. */
+    tooltip?: string;
+    /**
+     * Horizontal alignment for this column's header and body cells. When unset,
+     * cells follow the table-wide `--table-text-align` (left by default).
+     */
+    align?: 'left' | 'center' | 'right';
+    /**
+     * Caps the column width (any CSS length). Overflowing scalar cell text
+     * ellipsizes with the full value available on the native title tooltip.
+     */
+    maxWidth?: string;
+    /** Opt-in header filter dropdown (see TableColumnFilterConfig). */
+    filter?: TableColumnFilterConfig;
+    /**
+     * Extracts the comparable value for client-side sorting of this column —
+     * the seam for currency/date/locale-aware sorting without that logic
+     * entering the library. When absent, the built-in comparator is used on
+     * the cell value itself.
+     */
+    getSortValue?: (row: TableRow, rowIndex: number) => string | number | boolean;
+    /** `checked` is the NEW state after the flip, not the pre-click value. */
+    onToggle?: (rowIndex: number, checked: boolean) => void;
+    onSelect?: (rowIndex: number, selectedId: string) => void;
+    onInput?: (rowIndex: number, value: string) => void;
+    onButtonClick?: (rowIndex: number) => void;
+    onPrimaryAction?: (rowIndex: number) => void;
+    onMenuAction?: (rowIndex: number, itemId: string) => void;
+};
 /**
  * Configuration for row checkbox selection (C2-1).
  *
@@ -26,6 +238,47 @@ export type TableCheckboxSelectionConfig = {
     onSelectionChange?: (selectedIds: Set<string>) => void;
     getRowId?: (row: JSONValue[], rowIndex: number) => string;
     disabledRowIds?: Set<string>;
+    /**
+     * Controlled-selection overlay. Omitted: today's uncontrolled behavior via
+     * an internal set, unchanged. Provided: Table renders selection FROM this
+     * set and never mutates it — `onSelectionChange` reports the would-be next
+     * set and the consumer decides. Required for cross-page-persistent
+     * selection under server pagination.
+     */
+    selectedIds?: Set<string>;
+    /**
+     * Generic DOM-attribute spread onto each row checkbox (`rowIndex` is `-1`
+     * for the header select-all). An escape hatch for consumer-specific
+     * attributes (e.g. native test IDs) without the library learning them.
+     */
+    getRowAttributes?: (rowId: string, rowIndex: number) => Record<string, string>;
+};
+/**
+ * Built-in paginator config. `'client'` mode slices rows internally;
+ * `'server'` mode leaves the supplied rows untouched (they are the current
+ * page) and drives the paginator from `page`/`totalItems`/`hasMore`.
+ * A consumer `paginatorSlot` takes precedence over the built-in paginator.
+ */
+export type TablePaginationConfig = {
+    mode?: 'client' | 'server';
+    /** 1-indexed current page. Server mode: controlled by the consumer. */
+    page?: number;
+    /** Rows per page. Default 10. */
+    pageSize?: number;
+    /** Page-size selector options. Default [10, 25, 50, 100]; `[]` hides the selector. */
+    pageSizeOptions?: number[];
+    /** Total row count (server mode). Client mode derives it from the data. */
+    totalItems?: number;
+    /** Cursor-mode hint forwarded to the paginator's load-more affordance. */
+    hasMore?: boolean;
+    /** Disables the paginator and page-size selector during a fetch. */
+    isLoading?: boolean;
+    /** Range text override; default "{from}-{to} of {total}". */
+    rangeLabel?: (from: number, to: number, total: number) => string;
+    onPageChange?: (page: number) => void;
+    onPageSizeChange?: (pageSize: number) => void;
+    onLoadMore?: () => void;
+    testId?: string;
 };
 /**
  * Configuration for the built-in search bar (C2-3).
@@ -45,6 +298,35 @@ export type OptionalTableProperties = {
     tableTitle?: string | null;
     tableHeaders?: string[];
     tableData?: Array<JSONValue[]>;
+    /**
+     * Keyed column model (preferred): column definitions addressed by id.
+     * When provided, `columns`/`rows` are normalized internally into the
+     * positional `tableHeaders`/`tableData` shape and drive the same engine —
+     * the positional props are ignored for that instance. Omit both to keep
+     * the positional API exactly as before.
+     */
+    columns?: TableColumn[];
+    /** Keyed row data, addressed by `TableColumn.id`. Used with `columns`. */
+    rows?: TableRow[];
+    /**
+     * `'client'` (default) sorts rows internally on header click, exactly as
+     * before. `'server'` keeps the header sort UI and `onSort` callback but
+     * skips the internal reorder — the consumer re-orders the data itself
+     * (e.g. via a server query).
+     */
+    sortMode?: 'client' | 'server';
+    /** Built-in paginator (see TablePaginationConfig). */
+    pagination?: TablePaginationConfig;
+    /**
+     * Bulk-action bar rendered above the table while the checkbox selection is
+     * non-empty. The library owns only placement; buttons, labels, and actions
+     * are entirely consumer-rendered content.
+     */
+    toolbarSlot?: Snippet<[{
+        selectedIds: Set<string>;
+    }]>;
+    /** Prepends a sequential row-number column (1-based, pagination-aware). */
+    rowNumberColumn?: boolean;
     sortable?: boolean;
     sortableColumns?: number[];
     stickyHeader?: boolean;