simple-table-core 3.9.8 → 4.0.0

package/dist/src/core/SimpleTableVanilla.d.ts

@@ -83,6 +83,7 @@ export declare class SimpleTableVanilla {
     private sectionScrollController;
     private sortManager;
     private filterManager;
+    private pivotManager;
     private selectionManager;
     private rowSelectionManager;
     private windowResizeManager;
@@ -290,6 +291,13 @@ export declare class SimpleTableVanilla {
     private handleScroll;
     private clearHoveredRows;
     private updateAriaLiveRegion;
+    /** Row grouping used for flatten/expand while pivot is active (overrides consumer). */
+    private getEffectiveRowGrouping;
+    /**
+     * Recompute pivot from filtered source rows and feed sort/selection managers.
+     * When pivot is inactive, sort sees the filtered source rows directly.
+     */
+    private syncPivotPipeline;
     private getRenderContext;
     private getRenderState;
     /** A leaf column that should size to content (declared with width:"auto"). */

package/dist/src/core/api/TableAPIImpl.d.ts

@@ -1,6 +1,6 @@
 import { TableAPI } from "../../types/TableAPI";
 import { SimpleTableConfig } from "../../types/SimpleTableConfig";
-import HeaderObject from "../../types/HeaderObject";
+import HeaderObject, { Accessor } from "../../types/HeaderObject";
 import Row from "../../types/Row";
 import { CustomTheme } from "../../types/CustomTheme";
 import RowState from "../../types/RowState";
@@ -10,6 +10,7 @@ import { SortManager } from "../../managers/SortManager";
 import { FilterManager } from "../../managers/FilterManager";
 import { FlattenRowsResult } from "../../utils/rowFlattening";
 import { ProcessRowsResult } from "../../utils/rowProcessing";
+import type { PivotConfig } from "../../types/PivotTypes";
 export interface TableAPIContext {
     config: SimpleTableConfig;
     localRows: Row[];
@@ -66,6 +67,11 @@ export interface TableAPIContext {
     setHeaders: (headers: HeaderObject[]) => void;
     setCurrentPage: (page: number) => void;
     setColumnEditorOpen: (open: boolean) => void;
+    getEffectiveRowGrouping: () => Accessor[] | undefined;
+    setPivot: (config: PivotConfig | null) => void;
+    getPivot: () => PivotConfig | null;
+    getPivotHeaders: () => HeaderObject[];
+    getPivotedRows: () => Row[];
 }
 export declare class TableAPIImpl {
     static createAPI(context: TableAPIContext): TableAPI;

package/dist/src/index.d.ts

@@ -8,6 +8,9 @@ import type EnumOption from "./types/EnumOption";
 import type HeaderObject from "./types/HeaderObject";
 import type { Accessor, ChartOptions, ColumnType, Comparator, ComparatorProps, ExportValueGetter, ExportValueProps, ShowWhen, ValueFormatter, ValueFormatterProps, ValueGetter, ValueGetterProps } from "./types/HeaderObject";
 import type { AggregationConfig, AggregationType } from "./types/AggregationTypes";
+import type { PivotConfig, PivotValueConfig, PivotResult } from "./types/PivotTypes";
+import { PIVOT_CHILDREN_KEY, PIVOT_IS_TOTAL_KEY, PIVOT_ACCESSOR_PREFIX, PIVOT_BLANK_LABEL } from "./types/PivotTypes";
+import { pivotRows, buildPivotAccessor, buildPivotRowTotalAccessor } from "./utils/pivot/pivotRows";
 import type OnSortProps from "./types/OnSortProps";
 import type OnRowGroupExpandProps from "./types/OnRowGroupExpandProps";
 import type Row from "./types/Row";
@@ -49,6 +52,7 @@ import type { RowId } from "./types/RowId";
 import type { PinnedSectionsState } from "./types/PinnedSectionsState";
 export { SimpleTableVanilla };
 export { asRows } from "./utils/asRows";
+export { pivotRows, buildPivotAccessor, buildPivotRowTotalAccessor, PIVOT_CHILDREN_KEY, PIVOT_IS_TOTAL_KEY, PIVOT_ACCESSOR_PREFIX, PIVOT_BLANK_LABEL, };
 export { headersStructurallyEqual, collectHeaderAccessors, rowsShallowUnchanged, shallowEqualRow, SHALLOW_ROW_COMPARE_MAX, } from "./utils/propSyncEqual";
 export type { HeaderStructureLike, GetRowIdLike } from "./utils/propSyncEqual";
-export type { Accessor, AggregationConfig, AggregationType, AnimationsConfig, BoundingBox, Cell, CellChangeProps, CellClickProps, CellRenderer, CellRendererProps, CellValue, ChartOptions, ColumnEditorConfig, ColumnEditorCustomRenderer, ColumnEditorCustomRendererProps, ColumnEditorRowRenderer, ColumnEditorRowRendererComponents, ColumnEditorRowRendererProps, ColumnEditorSearchFunction, ColumnType, ColumnVisibilityState, Comparator, ComparatorProps, CustomTheme, CustomThemeProps, DragHandlerProps, EmptyStateRenderer, EmptyStateRendererProps, EnumOption, ErrorStateRenderer, ErrorStateRendererProps, ExportToCSVProps, ExportValueGetter, ExportValueProps, FilterCondition, FilterOperator, StringFilterOperator, NumberFilterOperator, BooleanFilterOperator, DateFilterOperator, EnumFilterOperator, FooterRendererProps, FooterPosition, GetRowId, GetRowIdParams, IconsConfig, LoadingStateRenderer, LoadingStateRendererProps, HeaderDropdown, HeaderDropdownProps, HeaderObject, HeaderRenderer, HeaderRendererProps, HeaderRendererComponents, OnRowGroupExpandProps, OnSortProps, QuickFilterConfig, QuickFilterGetter, QuickFilterGetterProps, QuickFilterMode, Row, RowButtonProps, RowId, RowSelectionChangeProps, RowSelectionMode, RowState, SetHeaderRenameProps, SharedTableProps, ShowWhen, SimpleTableConfig, SimpleTableProps, SortColumn, TableAPI, TableFilterState, TableHeaderProps, TableRowProps, Theme, PinnedSectionsState, UpdateDataProps, ValueFormatter, ValueFormatterProps, ValueGetter, ValueGetterProps, };
+export type { Accessor, AggregationConfig, AggregationType, AnimationsConfig, BoundingBox, Cell, CellChangeProps, CellClickProps, CellRenderer, CellRendererProps, CellValue, ChartOptions, ColumnEditorConfig, ColumnEditorCustomRenderer, ColumnEditorCustomRendererProps, ColumnEditorRowRenderer, ColumnEditorRowRendererComponents, ColumnEditorRowRendererProps, ColumnEditorSearchFunction, ColumnType, ColumnVisibilityState, Comparator, ComparatorProps, CustomTheme, CustomThemeProps, DragHandlerProps, EmptyStateRenderer, EmptyStateRendererProps, EnumOption, ErrorStateRenderer, ErrorStateRendererProps, ExportToCSVProps, ExportValueGetter, ExportValueProps, FilterCondition, FilterOperator, StringFilterOperator, NumberFilterOperator, BooleanFilterOperator, DateFilterOperator, EnumFilterOperator, FooterRendererProps, FooterPosition, GetRowId, GetRowIdParams, IconsConfig, LoadingStateRenderer, LoadingStateRendererProps, HeaderDropdown, HeaderDropdownProps, HeaderObject, HeaderRenderer, HeaderRendererProps, HeaderRendererComponents, OnRowGroupExpandProps, OnSortProps, PivotConfig, PivotValueConfig, PivotResult, QuickFilterConfig, QuickFilterGetter, QuickFilterGetterProps, QuickFilterMode, Row, RowButtonProps, RowId, RowSelectionChangeProps, RowSelectionMode, RowState, SetHeaderRenameProps, SharedTableProps, ShowWhen, SimpleTableConfig, SimpleTableProps, SortColumn, TableAPI, TableFilterState, TableHeaderProps, TableRowProps, Theme, PinnedSectionsState, UpdateDataProps, ValueFormatter, ValueFormatterProps, ValueGetter, ValueGetterProps, };

package/dist/src/managers/PivotManager.d.ts

@@ -0,0 +1,35 @@
+import type HeaderObject from "../types/HeaderObject";
+import type { Accessor } from "../types/HeaderObject";
+import type Row from "../types/Row";
+import type { PivotConfig } from "../types/PivotTypes";
+export interface PivotManagerConfig {
+    sourceRows: Row[];
+    fieldHeaders: HeaderObject[];
+    pivot: PivotConfig | null;
+}
+export interface PivotManagerState {
+    active: boolean;
+    pivotedRows: Row[];
+    headers: HeaderObject[];
+    rowGrouping?: Accessor[];
+    pivot: PivotConfig | null;
+}
+type StateChangeCallback = (state: PivotManagerState) => void;
+export declare class PivotManager {
+    private config;
+    private state;
+    private subscribers;
+    private cacheKey;
+    constructor(config: PivotManagerConfig);
+    private buildCacheKey;
+    private computeState;
+    getState(): PivotManagerState;
+    isActive(): boolean;
+    getPivot(): PivotConfig | null;
+    updateConfig(partial: Partial<PivotManagerConfig>): void;
+    setPivot(pivot: PivotConfig | null): void;
+    subscribe(callback: StateChangeCallback): () => void;
+    private notifySubscribers;
+    destroy(): void;
+}
+export {};

package/dist/src/types/GetRowId.d.ts

@@ -7,4 +7,10 @@ export interface GetRowIdParams {
     rowIndexPath: number[];
     groupingKey?: string;
 }
-export type GetRowId = (params: GetRowIdParams) => string | number;
+/**
+ * Return a stable business id for the row, or `undefined` / `null` when the row
+ * has no id yet (e.g. loading placeholders, pivot aggregates). Nullish returns
+ * fall back to reference-based identity so cell keys never collide on
+ * `String(undefined)`.
+ */
+export type GetRowId = (params: GetRowIdParams) => string | number | null | undefined;

package/dist/src/types/PivotTypes.d.ts

@@ -0,0 +1,37 @@
+import { Accessor } from "./HeaderObject";
+import { AggregationConfig } from "./AggregationTypes";
+import HeaderObject from "./HeaderObject";
+import Row from "./Row";
+export type PivotValueConfig = {
+    accessor: Accessor;
+    aggregation: AggregationConfig;
+    label?: string;
+};
+export type PivotConfig = {
+    /** Row dimension accessors (0+). Multi-level dims become an expandable tree. */
+    rows: Accessor[];
+    /** Column dimension accessors (0+). Distinct values become dynamic header groups. */
+    columns: Accessor[];
+    /** Value/measure configs (required, length >= 1). */
+    values: PivotValueConfig[];
+    /** Total column(s) aggregating across column dimensions. Default true. */
+    showRowTotals?: boolean;
+    /** Total row aggregating across row dimensions. Default true. */
+    showColumnTotals?: boolean;
+    /** Grand-total cell(s) on the totals row/column. Default true. */
+    showGrandTotal?: boolean;
+};
+/** Synthetic child-array key used for multi-level pivot row trees. */
+export declare const PIVOT_CHILDREN_KEY = "__pivotChildren";
+/** Marker on total rows for styling / identification. */
+export declare const PIVOT_IS_TOTAL_KEY = "__pivotIsTotal";
+/** Prefix for generated pivot measure accessors. */
+export declare const PIVOT_ACCESSOR_PREFIX = "__pivot:";
+/** Label used when a dimension value is null/undefined. */
+export declare const PIVOT_BLANK_LABEL = "(blank)";
+export type PivotResult = {
+    rows: Row[];
+    headers: HeaderObject[];
+    /** Internal rowGrouping to use while pivot is active (undefined when flat). */
+    rowGrouping?: Accessor[];
+};

package/dist/src/types/SimpleTableConfig.d.ts

@@ -21,6 +21,7 @@ import { VanillaIconsConfig } from "./IconsConfig";
 import { QuickFilterConfig } from "./QuickFilterTypes";
 import { AnimationsConfig } from "./AnimationsConfig";
 import type { FooterPosition } from "./FooterPosition";
+import type { PivotConfig } from "./PivotTypes";
 export interface SimpleTableConfig {
     animations?: AnimationsConfig;
     /**
@@ -53,6 +54,8 @@ export interface SimpleTableConfig {
     /** @see SimpleTableProps.showRowSelectionColumn */
     showRowSelectionColumn?: boolean;
     enableStickyParents?: boolean;
+    /** @see SimpleTableProps.enableVirtualization */
+    enableVirtualization?: boolean;
     errorStateRenderer?: VanillaErrorStateRenderer;
     expandAll?: boolean;
     externalFilterHandling?: boolean;
@@ -97,6 +100,10 @@ export interface SimpleTableConfig {
      */
     onRendererHostDiscard?: (host: HTMLElement) => void;
     onSortChange?: (sort: SortColumn | null) => void;
+    /** @see SimpleTableProps.pivot */
+    pivot?: PivotConfig | null;
+    /** @see SimpleTableProps.onPivotChange */
+    onPivotChange?: (pivot: PivotConfig | null) => void;
     quickFilter?: QuickFilterConfig;
     rowButtons?: RowButton[];
     rowGrouping?: Accessor[];

package/dist/src/types/SimpleTableProps.d.ts

@@ -21,6 +21,7 @@ import { IconsConfig } from "./IconsConfig";
 import { QuickFilterConfig } from "./QuickFilterTypes";
 import { AnimationsConfig } from "./AnimationsConfig";
 import type { FooterPosition } from "./FooterPosition";
+import type { PivotConfig } from "./PivotTypes";
 export interface SimpleTableProps {
     animations?: AnimationsConfig;
     autoExpandColumns?: boolean;
@@ -57,6 +58,13 @@ export interface SimpleTableProps {
      */
     showRowSelectionColumn?: boolean;
     enableStickyParents?: boolean;
+    /**
+     * When false, disables both row and column virtualization so every row and
+     * column is rendered in the DOM. Useful for print, a11y tooling, or small
+     * datasets that still need a fixed `height` / `maxHeight` for layout.
+     * Default true.
+     */
+    enableVirtualization?: boolean;
     errorStateRenderer?: ErrorStateRenderer;
     expandAll?: boolean;
     externalFilterHandling?: boolean;
@@ -90,6 +98,13 @@ export interface SimpleTableProps {
     onRowGroupExpand?: (props: OnRowGroupExpandProps) => void | Promise<void>;
     onRowSelectionChange?: (props: RowSelectionChangeProps) => void;
     onSortChange?: (sort: SortColumn | null) => void;
+    /**
+     * Declarative matrix pivot. When set, flat `rows` are reshaped into a
+     * pivoted grid with dynamic columns. Ignores consumer `rowGrouping` while active.
+     */
+    pivot?: PivotConfig | null;
+    /** Fired when pivot config changes via TableAPI.setPivot. */
+    onPivotChange?: (pivot: PivotConfig | null) => void;
     quickFilter?: QuickFilterConfig;
     rowButtons?: RowButton[];
     rowGrouping?: Accessor[];

package/dist/src/types/TableAPI.d.ts

@@ -6,6 +6,7 @@ import SortColumn, { SortDirection } from "./SortColumn";
 import { TableFilterState, FilterCondition } from "./FilterTypes";
 import Cell from "./Cell";
 import type { PinnedSectionsState } from "./PinnedSectionsState";
+import type { PivotConfig } from "./PivotTypes";
 export interface SetHeaderRenameProps {
     accessor: Accessor;
 }
@@ -71,4 +72,11 @@ export type TableAPI = {
     toggleRowSelection: (rowId: string) => void;
     /** Clears row selection only (does not clear cell selection). */
     clearRowSelection: () => void;
+    /** Enable, update, or clear matrix pivot (`null` disables). */
+    setPivot: (config: PivotConfig | null) => void;
+    getPivot: () => PivotConfig | null;
+    /** Generated headers while pivot is active; otherwise current headers. */
+    getPivotHeaders: () => HeaderObject[];
+    /** Post-pivot rows (pre-flatten) while pivot is active; otherwise source rows. */
+    getPivotedRows: () => Row[];
 };

package/dist/src/utils/aggregationUtils.d.ts

@@ -0,0 +1,7 @@
+import type CellValue from "../types/CellValue";
+import type { AggregationConfig } from "../types/AggregationTypes";
+/**
+ * Aggregate a flat list of cell values using the given AggregationConfig.
+ * Shared by row-grouping rollups and matrix pivot.
+ */
+export declare const aggregateValues: (allValues: CellValue[], config: AggregationConfig) => number | string | undefined;

package/dist/src/utils/bodyCell/types.d.ts

@@ -108,6 +108,11 @@ export interface CellRenderContext {
      * here makes every column count as visible, disabling virtualization.
      */
     mainSectionViewportWidth?: number;
+    /**
+     * When false, skip column virtualization and render every body cell in the
+     * main section. Default true. Mirrors {@link SimpleTableProps.enableVirtualization}.
+     */
+    enableVirtualization?: boolean;
     onCellEdit?: (params: CellEditParams) => void;
     onCellClick?: (params: CellClickParams) => void;
     onRowGroupExpand?: (props: OnRowGroupExpandProps) => void | Promise<void>;

package/dist/src/utils/headerCell/types.d.ts

@@ -60,6 +60,8 @@ export interface HeaderRenderContext {
     mainBodyRef: RefObject<HTMLDivElement>;
     mainSectionContainerWidth?: number; /** Main section *content* width (sum of all non-pinned column widths). NOT the virtualization viewport. */
     mainSectionViewportWidth?: number; /** Main section *visible* viewport width (container minus pinned); use for getVisibleCells when !pinned */
+    /** When false, skip column virtualization and render every header cell in the main section. Default true. */
+    enableVirtualization?: boolean;
     onColumnOrderChange?: (headers: HeaderObject[]) => void;
     onColumnSelect?: (header: HeaderObject) => void;
     onColumnWidthChange?: (headers: HeaderObject[]) => void;

package/dist/src/utils/pivot/pivotRows.d.ts

@@ -0,0 +1,16 @@
+import type HeaderObject from "../../types/HeaderObject";
+import type { Accessor } from "../../types/HeaderObject";
+import type Row from "../../types/Row";
+import type { PivotConfig, PivotResult } from "../../types/PivotTypes";
+export type PivotRowsProps = {
+    rows: Row[];
+    pivot: PivotConfig;
+    /** Field catalog (`defaultHeaders`) for labels, types, widths, formatters. */
+    fieldHeaders: HeaderObject[];
+};
+export declare const buildPivotAccessor: (colKey: string, valueAccessor: Accessor) => string;
+export declare const buildPivotRowTotalAccessor: (valueAccessor: Accessor) => string;
+/**
+ * Pure transform: flat source rows + pivot config → pivoted rows and generated headers.
+ */
+export declare const pivotRows: ({ rows, pivot, fieldHeaders }: PivotRowsProps) => PivotResult;

package/dist/src/utils/propSyncEqual.d.ts

@@ -3,6 +3,7 @@
  * Used to skip no-op `defaultHeaders` / `rows` updates when consumers rebuild
  * column configs or shallow-clone rows every render.
  */
+import type { GetRowIdParams } from "../types/GetRowId";
 /** Minimal header shape for structural comparison (renderers ignored). */
 export type HeaderStructureLike = {
     accessor: string | number | symbol;
@@ -43,14 +44,8 @@ export declare function collectHeaderAccessors(headers: ReadonlyArray<HeaderStru
  * invisible — callers must pass new object identities when data changes.
  */
 export declare function shallowEqualRow(a: object, b: object): boolean;
-export type GetRowIdLike = (params: {
-    row: unknown;
-    depth?: number;
-    index?: number;
-    rowPath?: (string | number)[];
-    rowIndexPath?: number[];
-    groupingKey?: string;
-}) => string | number | undefined;
+/** Compatible with `GetRowId`; return may be undefined for sync helpers. */
+export type GetRowIdLike = (params: GetRowIdParams) => string | number | undefined;
 /**
  * Above this length, skip per-field shallow compares when row object identity
  * differs. Same-array-ref and same-row-object cases stay O(1) / O(n) pointer

package/dist/stories/docs/Features.stories.d.ts

@@ -38,6 +38,7 @@ export declare const NestedAccessor: StoryObj;
 export declare const NestedGrid: StoryObj;
 export declare const Pagination: StoryObj;
 export declare const PaginationAPI: StoryObj;
+export declare const Pivot: StoryObj;
 export declare const PinnedColumns: StoryObj;
 export declare const ProgrammaticFilter: StoryObj;
 export declare const ProgrammaticSort: StoryObj;

package/dist/stories/docs/storyArgs.d.ts

@@ -16,6 +16,7 @@ export declare const storyArgs: (exampleDefaults?: Partial<UniversalVanillaArgs>
         externalSortHandling?: boolean | undefined;
         height?: string | undefined;
         hideFooter?: boolean | undefined;
+        pivot?: import("../../src").PivotConfig | null | undefined;
         rowsPerPage?: number | undefined;
         selectableCells?: boolean | undefined;
         selectableColumns?: boolean | undefined;

package/dist/stories/examples/PivotExample.d.ts

@@ -0,0 +1,16 @@
+/**
+ * PivotExample – interactive playground for declarative matrix pivot.
+ */
+import type { PivotConfig } from "../../src/index";
+import { type UniversalVanillaArgs } from "../vanillaStoryConfig";
+export declare const pivotExampleDefaults: {
+    columnResizing: boolean;
+    height: string;
+    expandAll: boolean;
+    columnBorders: boolean;
+    pivot: PivotConfig | null;
+};
+/**
+ * Interactive pivot feature demo: configure rows / columns / values / totals live.
+ */
+export declare function renderPivotExample(args?: Partial<UniversalVanillaArgs>): HTMLElement;

package/dist/stories/tests/45-PivotTests.stories.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Interaction tests for declarative matrix pivot.
+ */
+import type { Meta, StoryObj } from "@storybook/html";
+declare const meta: Meta;
+export default meta;
+type Story = StoryObj;
+export declare const PivotRendersDynamicColumns: Story;

package/dist/stories/vanillaStoryConfig.d.ts

@@ -2,7 +2,7 @@
  * Shared default args and argTypes for vanilla Docs & Examples stories.
  * Mirrors the React StoryWrapper pattern so Controls (theme, height, etc.) are consistent.
  */
-import type { Theme, CustomThemeProps } from "../src/index";
+import type { Theme, CustomThemeProps, PivotConfig } from "../src/index";
 export interface UniversalVanillaArgs {
     autoExpandColumns?: boolean;
     cellUpdateFlash?: boolean;
@@ -16,6 +16,8 @@ export interface UniversalVanillaArgs {
     externalSortHandling?: boolean;
     height?: string;
     hideFooter?: boolean;
+    /** Declarative matrix pivot (passed through to SimpleTableConfig). */
+    pivot?: PivotConfig | null;
     rowsPerPage?: number;
     selectableCells?: boolean;
     selectableColumns?: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "simple-table-core",
-  "version": "3.9.8",
+  "version": "4.0.0",
   "main": "dist/cjs/index.js",
   "module": "dist/index.es.js",
   "types": "dist/src/index.d.ts",