@ds-mo/ui 14.9.0 → 14.10.0

package/dist/styles/table.css

@@ -242,7 +242,8 @@
 
 :where(.ds-table__table--native-group-sticky .ds-table__group-row),
 :where(.ds-table__table--native-group-sticky .ds-table__state-row),
-:where(.ds-table__table--native-group-sticky .ds-table__load-row) {
+:where(.ds-table__table--native-group-sticky .ds-table__load-row),
+:where(.ds-table__table--native-group-sticky .ds-table__virtual-spacer-row) {
   display: block;
   inline-size: 100%;
 }
@@ -251,7 +252,8 @@
 :where(.ds-table__table--native-group-sticky .ds-table__cell),
 :where(.ds-table__table--native-group-sticky .ds-table__group-cell),
 :where(.ds-table__table--native-group-sticky .ds-table__state-cell),
-:where(.ds-table__table--native-group-sticky .ds-table__load-cell) {
+:where(.ds-table__table--native-group-sticky .ds-table__load-cell),
+:where(.ds-table__table--native-group-sticky .ds-table__virtual-spacer-cell) {
   display: block;
   inline-size: auto;
   width: auto;
@@ -261,11 +263,28 @@
 
 :where(.ds-table__table--native-group-sticky .ds-table__group-cell),
 :where(.ds-table__table--native-group-sticky .ds-table__state-cell),
-:where(.ds-table__table--native-group-sticky .ds-table__load-cell) {
+:where(.ds-table__table--native-group-sticky .ds-table__load-cell),
+:where(.ds-table__table--native-group-sticky .ds-table__virtual-spacer-cell) {
   inline-size: 100%;
   width: 100%;
 }
 
+:where(.ds-table__virtual-spacer-row) {
+  border: 0;
+}
+
+:where(.ds-table__virtual-spacer-cell) {
+  box-sizing: border-box;
+  padding: 0;
+  border: 0;
+  overflow: hidden;
+  line-height: 0;
+  font-size: 0;
+  background: transparent;
+  block-size: var(--_table-virtual-spacer-block-size, 0);
+  min-block-size: var(--_table-virtual-spacer-block-size, 0);
+}
+
 :where(.ds-table__caption-bar),
 :where(.ds-table__footer) {
   box-sizing: border-box;

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

@@ -31,12 +31,15 @@ export declare class Table {
     columnOrder: string[];
     /**
      * Optional result summary footer. When both `displayedCount` and `totalCount`
-     * are finite numbers, the table shows “Displaying {displayed} of {total}”.
+     * are finite numbers, infinite mode shows “Displaying {displayed} of {total}”.
+     * Virtual mode ignores `displayedCount` and shows a total-only summary.
      */
     displayedCount: number | undefined;
     totalCount: number | undefined;
     /** Supports {displayed} and {total} placeholders. */
     resultSummaryLabel: string;
+    /** Supports the {total} placeholder. Used when dataMode is virtual. */
+    resultTotalSummaryLabel: string;
     stickyHeader: boolean;
     /** Maximum scroll-region height. Numbers resolve to CSS pixels. */
     maxHeight: string | number | undefined;
@@ -64,7 +67,7 @@ export declare class Table {
     errorHeading: string;
     errorBody: string;
     emptyCellLabel: string;
-    /** Top-level data-window strategy. Group member loading remains group-owned. */
+    /** Top-level data-window strategy. Virtual mode recycles row DOM only. */
     dataMode: TableDataMode;
     /** Opt in to the table-owned control for choosing between supported data modes. */
     dataModeSwitcher: boolean;
@@ -124,12 +127,15 @@ export declare class Table {
     private columnCustomizerInitialFocusVisible;
     private dataModeSwitcherOpen;
     private dataModeSwitcherInitialFocusVisible;
+    private virtualWindow;
     private readonly actionMenuElementId;
     private readonly columnCustomizerElementId;
     private readonly dataModeSwitcherElementId;
     private truncateTooltipEl?;
     private truncateAnchor;
     private truncateTooltipBound;
+    private focusedRowId;
+    private virtualItems;
     private rootEl;
     private viewportEl;
     private frameEl;
@@ -152,6 +158,7 @@ export declare class Table {
     private readonly layoutController;
     private readonly loadController;
     private readonly groupLoadController;
+    private readonly virtualController;
     private readonly viewportFitController;
     componentWillLoad(): void;
     componentDidLoad(): void;
@@ -167,6 +174,7 @@ export declare class Table {
     handleStructureChange(): void;
     handleDataChange(): void;
     handleLoadIdentityChange(): void;
+    handleVirtualIndexReset(): void;
     handleLazyConfigurationChange(): void;
     handleDataModeChange(): void;
     handlePaginationChange(pagination: TablePaginationState | null, previous: TablePaginationState | null): void;
@@ -193,6 +201,12 @@ export declare class Table {
     private currentLoadedRows;
     private currentLoadedRowCount;
     private createRenderModel;
+    private get virtualizationEnabled();
+    private get virtualViewportMissing();
+    private estimateVirtualViewportSize;
+    private virtualPinnedRowIds;
+    private syncVirtualItems;
+    private shouldVirtualize;
     private get resolvedMaxHeight();
     private get resolvedHeight();
     private warnModelIssues;
@@ -219,6 +233,7 @@ export declare class Table {
     private renderTruncateTooltip;
     private truncateAttr;
     private handleRowKeydown;
+    private onVirtualFocusIn;
     private renderSelectionControl;
     private renderStickyEdge;
     private renderCollapseAllButton;
@@ -236,6 +251,10 @@ export declare class Table {
     private formatGroupLoadLabel;
     private renderGroupLoadRow;
     private renderStickyGroup;
+    private renderVirtualSpacer;
+    private renderVirtualRow;
+    private renderVirtualGroup;
+    private renderVirtualBodies;
     private renderDataBodies;
     private renderSkeletonBody;
     private renderSkeletonCell;

package/dist/types/components/Table/table-data-mode-switcher.d.ts

@@ -1,6 +1,7 @@
 import type { MenuItemData } from '../Menu/menu-types';
 import type { TableDataMode } from './table-types';
 export declare function nextTableDataModeSwitcherElementId(): string;
+/** Menu of supported data-mode choices. Virtual is a controlled prop, not a switcher item. */
 export declare function tableDataModeMenuItems(dataMode: TableDataMode, labels: {
     infinite: string;
     pagination: string;

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

@@ -50,5 +50,7 @@ export declare function tableGroupIntentClass(intent: (typeof TABLE_GROUP_INTENT
 export declare function tableGroupLabelColor(intent: (typeof TABLE_GROUP_INTENTS)[number] | undefined): 'primary' | 'brand' | 'negative' | 'warning' | 'caution' | 'positive' | `var(--${string})`;
 /** Formats the optional table result footer. Returns null when either count is missing. */
 export declare function formatTableResultSummary(displayed: number | null | undefined, total: number | null | undefined, label?: string, locale?: string): string | null;
+/** Formats the virtual-mode total-only result footer. */
+export declare function formatTableTotalSummary(total: number | null | undefined, label?: string, locale?: string): string | null;
 export declare function tableModelIssues(columns: TableColumn[], rows: TableRow[], groups: TableGroup[], grouped: boolean): string[];
 //# sourceMappingURL=table-model.d.ts.map

package/dist/types/components/Table/table-render-model.d.ts

@@ -1,9 +1,11 @@
 import { tableGroupLabelColor, type TableCollapseAllHost, type TableSelectionState } from './table-model';
 import type { TableColumn, TableGroup, TableGroupIntent, TableRow, TableSelectionMode } from './table-types';
+export type TableGroupCountPresentation = 'loaded-progress' | 'total';
 export interface TableGroupRenderModel {
     group: TableGroup;
     count: number;
     loadedCount: number;
+    visibleCountText: string;
     countLabel: string;
     intent: TableGroupIntent | undefined;
     intentClass: string | undefined;
@@ -35,6 +37,7 @@ export interface TableRenderModelInput {
     selectionMode: TableSelectionMode;
     selectedRowIds: string[];
     collapsedGroupIds: string[];
+    groupCountPresentation?: TableGroupCountPresentation;
 }
 /** Create one immutable snapshot of all derived state consumed during a render. */
 export declare function createTableRenderModel(input: TableRenderModelInput): TableRenderModel;

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

@@ -9,7 +9,7 @@ export type TableCellLinkTarget = '_self' | '_blank';
 export type TableColumnSticky = 'start' | 'end';
 export type TableCaptionVisibility = 'visible' | 'hidden';
 export type TableLoadMoreMode = 'auto' | 'manual';
-export type TableDataMode = 'infinite' | 'pagination';
+export type TableDataMode = 'infinite' | 'pagination' | 'virtual';
 export interface TableDataModeChangeDetail {
     dataMode: TableDataMode;
 }

package/dist/types/components/Table/table-virtual-controller.d.ts

@@ -0,0 +1,48 @@
+import { type TableVirtualItem, type TableVirtualPlan } from './table-virtual-model';
+export interface TableVirtualControllerState {
+    enabled: boolean;
+    items: readonly TableVirtualItem[];
+    pinnedRowIds: ReadonlySet<string>;
+    viewport: HTMLElement | null;
+    viewportSize: number;
+}
+export interface TableVirtualControllerOptions {
+    state: () => TableVirtualControllerState;
+    windowChanged: (plan: TableVirtualPlan | null) => void;
+    requestAnimationFrame?: (callback: FrameRequestCallback) => number;
+    cancelAnimationFrame?: (handle: number) => void;
+}
+/** Binds viewport scroll/resize to a recycled row window. Scroll offset stays off render state. */
+export declare class TableVirtualController {
+    private readonly options;
+    private connected;
+    private connectedViewport;
+    private resizeObserver;
+    private frame;
+    private measures;
+    private plan;
+    private scrollOffset;
+    private pendingReset;
+    private readonly raf;
+    private readonly caf;
+    constructor(options: TableVirtualControllerOptions);
+    connect(): void;
+    disconnect(): void;
+    refresh(): void;
+    schedule: () => void;
+    /** Drop cached heights after column, density, or wrap geometry changes. */
+    invalidateMeasures(): void;
+    /** Rebuild from a new index and pin the viewport to the start. */
+    resetToTop(): void;
+    sizeFor(item: TableVirtualItem): number;
+    currentPlan(): TableVirtualPlan | null;
+    /** Measure painted rows and correct scroll when estimates were wrong. */
+    collectMeasurements(root: ParentNode | null): void;
+    private prefixForCurrentItems;
+    private readonly handleScroll;
+    private sync;
+    private emit;
+    private unbindViewport;
+    private cancelFrame;
+}
+//# sourceMappingURL=table-virtual-controller.d.ts.map

package/dist/types/components/Table/table-virtual-model.d.ts

@@ -0,0 +1,77 @@
+import type { TableColumn, TableGroup, TableRow } from './table-types';
+/**
+ * Token-aligned body-row track contracts: 40 / 62 / 84, plus wrapping-secondary
+ * 106. Estimates only; measured heights replace these after paint.
+ */
+export declare const TABLE_VIRTUAL_ROW_TRACK_SIZE: {
+    readonly 1: 40;
+    readonly 2: 62;
+    readonly 3: 84;
+    readonly 4: 106;
+};
+export declare const TABLE_VIRTUAL_GROUP_HEADER_SIZE: 40;
+export declare const TABLE_VIRTUAL_MIN_OVERSCAN_ROWS = 8;
+export declare const TABLE_VIRTUAL_VIEWPORT_REQUIRED_HEADING = "Bounded height required";
+export declare const TABLE_VIRTUAL_VIEWPORT_REQUIRED_BODY = "Virtual mode requires height, maxHeight, or fitViewport.";
+export declare const TABLE_VIRTUAL_TOTAL_SUMMARY_LABEL = "{total} items";
+export type TableVirtualItemKind = 'group' | 'row';
+export interface TableVirtualItem {
+    kind: TableVirtualItemKind;
+    id: string;
+    groupId?: string;
+    rowId?: string;
+    estimatedSize: number;
+}
+export type TableVirtualNode = {
+    kind: 'spacer';
+    size: number;
+    key: string;
+} | {
+    kind: 'row';
+    index: number;
+    item: TableVirtualItem;
+} | {
+    kind: 'group';
+    groupId: string;
+    headerIndex: number;
+    nodes: Array<Extract<TableVirtualNode, {
+        kind: 'spacer' | 'row';
+    }>>;
+};
+export interface TableVirtualPlan {
+    totalSize: number;
+    itemCount: number;
+    start: number;
+    end: number;
+    nodes: TableVirtualNode[];
+    mountedIds: ReadonlySet<string>;
+    mountedIndexes: ReadonlySet<number>;
+}
+export interface FlattenTableVirtualItemsInput {
+    grouped: boolean;
+    rows: TableRow[];
+    groups: TableGroup[];
+    collapsedGroupIds: ReadonlySet<string> | readonly string[];
+    columns: TableColumn[];
+}
+export interface ResolveTableVirtualPlanInput {
+    items: readonly TableVirtualItem[];
+    sizes: readonly number[];
+    scrollOffset: number;
+    viewportSize: number;
+    pinnedRowIds?: ReadonlySet<string>;
+}
+/** Map a cell recipe onto the named track stack used for first-paint estimates. */
+export declare function estimateTableCellTrackCount(value: TableRow['cells'][string], column: TableColumn): number;
+/** Tallest named track stack across the row's visible cells. */
+export declare function estimateTableRowBlockSize(row: TableRow, columns: readonly TableColumn[]): number;
+export declare function flattenTableVirtualItems(input: FlattenTableVirtualItemsInput): TableVirtualItem[];
+export declare function tableVirtualOverscanPx(viewportSize: number): number;
+export declare function buildTableVirtualPrefixSums(sizes: readonly number[]): number[];
+/** Largest item index whose start offset is <= `offset`. */
+export declare function findTableVirtualIndexAtOffset(prefix: readonly number[], offset: number): number;
+export declare function tableVirtualItemSizes(items: readonly TableVirtualItem[], measures: ReadonlyMap<string, number>): number[];
+export declare function sameTableVirtualPlan(left: TableVirtualPlan | null | undefined, right: TableVirtualPlan | null | undefined): boolean;
+/** Resolve the mounted slice, sticky headers, and in-flow spacers for one scroll offset. */
+export declare function resolveTableVirtualPlan(input: ResolveTableVirtualPlanInput): TableVirtualPlan;
+//# sourceMappingURL=table-virtual-model.d.ts.map

package/dist/types/components.d.ts

@@ -2877,7 +2877,7 @@ export namespace Components {
          */
         "columns": TableColumn[];
         /**
-          * Top-level data-window strategy. Group member loading remains group-owned.
+          * Top-level data-window strategy. Virtual mode recycles row DOM only.
           * @default 'infinite'
          */
         "dataMode": TableDataMode;
@@ -2895,7 +2895,7 @@ export namespace Components {
          */
         "dataModeSwitcherLabel": string;
         /**
-          * Optional result summary footer. When both `displayedCount` and `totalCount` are finite numbers, the table shows “Displaying {displayed} of {total}”.
+          * Optional result summary footer. When both `displayedCount` and `totalCount` are finite numbers, infinite mode shows “Displaying {displayed} of {total}”. Virtual mode ignores `displayedCount` and shows a total-only summary.
          */
         "displayedCount": number | undefined;
         /**
@@ -3038,6 +3038,11 @@ export namespace Components {
           * @default 'Displaying {displayed} of {total}'
          */
         "resultSummaryLabel": string;
+        /**
+          * Supports the {total} placeholder. Used when dataMode is virtual.
+          * @default '{total} items'
+         */
+        "resultTotalSummaryLabel": string;
         /**
           * @default 'Retry'
          */
@@ -7794,7 +7799,7 @@ declare namespace LocalJSX {
          */
         "columns"?: TableColumn[];
         /**
-          * Top-level data-window strategy. Group member loading remains group-owned.
+          * Top-level data-window strategy. Virtual mode recycles row DOM only.
           * @default 'infinite'
          */
         "dataMode"?: TableDataMode;
@@ -7812,7 +7817,7 @@ declare namespace LocalJSX {
          */
         "dataModeSwitcherLabel"?: string;
         /**
-          * Optional result summary footer. When both `displayedCount` and `totalCount` are finite numbers, the table shows “Displaying {displayed} of {total}”.
+          * Optional result summary footer. When both `displayedCount` and `totalCount` are finite numbers, infinite mode shows “Displaying {displayed} of {total}”. Virtual mode ignores `displayedCount` and shows a total-only summary.
          */
         "displayedCount"?: number | undefined;
         /**
@@ -7965,6 +7970,11 @@ declare namespace LocalJSX {
           * @default 'Displaying {displayed} of {total}'
          */
         "resultSummaryLabel"?: string;
+        /**
+          * Supports the {total} placeholder. Used when dataMode is virtual.
+          * @default '{total} items'
+         */
+        "resultTotalSummaryLabel"?: string;
         /**
           * @default 'Retry'
          */
@@ -9000,6 +9010,7 @@ declare namespace LocalJSX {
         "displayedCount": number | undefined;
         "totalCount": number | undefined;
         "resultSummaryLabel": string;
+        "resultTotalSummaryLabel": string;
         "stickyHeader": boolean;
         "maxHeight": string;
         "height": string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ds-mo/ui",
-  "version": "14.9.0",
+  "version": "14.10.0",
   "description": "CompoMo — composable web components styled with TokoMo design tokens",
   "keywords": [
     "web-components",