simple-table-core 3.8.3 → 3.8.5

package/dist/src/consts/general-consts.d.ts

@@ -4,6 +4,7 @@ export declare const PAGE_SIZE = 20;
 export declare const CSS_VAR_BORDER_WIDTH = "--st-border-width";
 export declare const DEFAULT_BORDER_WIDTH = 1;
 export declare const VIRTUALIZATION_THRESHOLD = 20;
+export declare const UNVIRTUALIZED_ROW_WARNING_THRESHOLD = 500;
 export declare const OVERSCAN_PIXELS = 800;
 export declare const calculateBufferRowCount: (rowHeight: number) => number;
 export declare const COLUMN_EDIT_WIDTH = 29.5;

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

@@ -60,6 +60,10 @@ export declare class SimpleTableVanilla {
     private scrollEndTimeoutId;
     private lastScrollTop;
     private isUpdating;
+    /** Set once the dev-only "too many unvirtualized rows" warning has fired, so it never repeats. */
+    private hasWarnedUnvirtualizedRows;
+    /** Pending deferred check for the unvirtualized-rows warning (lets external-scroll seeding settle first). */
+    private unvirtualizedRowsCheckTimeoutId;
     /** Currently resolved external scroll parent (HTMLElement or window). Null when external scroll mode is inactive. */
     private resolvedScrollParent;
     /** Bound scroll handler attached to the external scroll parent. */
@@ -70,6 +74,15 @@ export declare class SimpleTableVanilla {
     private externalParentResizeObserver;
     /** Cached visible viewport height of the table inside the external parent. Fed into virtualization. */
     private externalViewportHeight;
+    /**
+     * rAF handle for retrying resolution of a configured-but-not-yet-resolvable
+     * `scrollParent` (e.g. a getter pointing at a ref attached on a later commit
+     * than this table's mount). Null when no retry is pending.
+     */
+    private externalScrollRetryRaf;
+    /** Number of resolution retries attempted; bounded so we don't spin forever. */
+    private externalScrollRetryCount;
+    private static readonly EXTERNAL_SCROLL_MAX_RETRIES;
     /** True iff the body-container scroll listener is currently attached. */
     private bodyScrollListenerAttached;
     /** Bound mouseleave handler on the body container. */
@@ -155,6 +168,13 @@ export declare class SimpleTableVanilla {
      */
     private didColumnVisibilityChange;
     private captureAnimationSnapshot;
+    /**
+     * Push the visible vertical viewport into the animation coordinator when
+     * external/page scroll is active (or clear it otherwise). Keeps the FLIP
+     * distance-scaling viewport-relative so cells don't slide the full
+     * conceptual distance when the table grows to its natural height.
+     */
+    private updateAnimationVerticalScroll;
     /**
      * Open the accordion animation window for the next render: capture a FLIP
      * snapshot, mark the active axis so cell renderers initialize incoming
@@ -180,6 +200,14 @@ export declare class SimpleTableVanilla {
      * `maxHeight`). Idempotent — safe to call repeatedly.
      */
     private syncExternalScrollWiring;
+    /**
+     * Retry resolving a configured `scrollParent` on the next animation frame.
+     * Used when the parent (typically a getter pointing at a ref) was not yet
+     * resolvable when external wiring last ran. Bounded by
+     * {@link SimpleTableVanilla.EXTERNAL_SCROLL_MAX_RETRIES} so a permanently
+     * unresolvable parent doesn't spin forever.
+     */
+    private scheduleExternalScrollParentRetry;
     private ensureBodyScrollListenerAttached;
     private ensureBodyScrollListenerDetached;
     private attachExternalScrollWiring;
@@ -250,6 +278,17 @@ export declare class SimpleTableVanilla {
      */
     refitAutoSizeColumns(): void;
     private render;
+    /**
+     * Dev-only safeguard. Schedules a one-shot, deferred check that warns when the
+     * table is about to render a very large number of rows with no virtualization
+     * active (no `height` / `maxHeight` and no bounded `scrollParent`). The check
+     * is deferred so external-scroll viewport seeding (which can momentarily leave
+     * `contentHeight` undefined on the first paint) has time to settle and we
+     * don't cry wolf for a correctly-configured table. Compiled out of production
+     * via the NODE_ENV guard. Never throws.
+     */
+    private maybeScheduleUnvirtualizedRowsWarning;
+    private evaluateUnvirtualizedRowsWarning;
     update(config: Partial<SimpleTableConfig>): void;
     /** @deprecated Use {@link update} — same behavior. */
     updateConfig(config: Partial<SimpleTableConfig>): void;

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

@@ -29,6 +29,15 @@ export interface TableAPIContext {
     cellRegistry?: Map<string, {
         updateContent: (value: any) => void;
     }>;
+    /**
+     * Whether a cell (by its `getCellId` key) is currently mid-FLIP-animation.
+     * Live `updateData` content writes are skipped for animating cells so a
+     * data tick doesn't re-render / mutate a cell that is sliding to a new
+     * position (which causes visible jank). The underlying row data is still
+     * updated; only the in-place DOM refresh is deferred to the next tick or
+     * re-render once the animation settles.
+     */
+    isCellAnimating?: (cellId: string) => boolean;
     columnEditorOpen: boolean;
     expandedDepthsManager: any;
     selectionManager: SelectionManager | null;

package/dist/src/core/rendering/RenderOrchestrator.d.ts

@@ -12,6 +12,7 @@ import { SelectionManager } from "../../managers/SelectionManager";
 import { RowSelectionManager } from "../../managers/RowSelectionManager";
 import type { AnimationCoordinator, CellPosition } from "../../managers/AnimationCoordinator";
 import type { AccordionAxis } from "../../utils/accordionAnimation";
+import type { NestedTableFactory } from "../../utils/nestedGridRowRenderer";
 import { FlattenRowsResult } from "../../utils/rowFlattening";
 import { ProcessRowsResult } from "../../utils/rowProcessing";
 import { MergedColumnEditorConfig, ResolvedIcons } from "../initialization/TableInitializer";
@@ -52,6 +53,8 @@ export interface RenderContext {
     internalIsLoading: boolean;
     isResizing: boolean;
     localRows: Row[];
+    /** Injected factory for nested grid tables (breaks the SimpleTableVanilla import cycle). */
+    createNestedTable?: NestedTableFactory;
     mainBodyRef: {
         current: HTMLDivElement | null;
     };

package/dist/src/core/rendering/TableRenderer.d.ts

@@ -9,6 +9,7 @@ import { SelectionManager } from "../../managers/SelectionManager";
 import { RowSelectionManager } from "../../managers/RowSelectionManager";
 import type { AnimationCoordinator, CellPosition } from "../../managers/AnimationCoordinator";
 import type { AccordionAxis } from "../../utils/accordionAnimation";
+import type { NestedTableFactory } from "../../utils/nestedGridRowRenderer";
 export interface TableRendererDeps {
     /** Accordion animation axis for the in-flight collapse/expand. See {@link RenderContext.accordionAxis}. */
     accordionAxis?: AccordionAxis;
@@ -81,6 +82,8 @@ export interface TableRendererDeps {
     setIsResizing: (value: boolean) => void;
     setRowStateMap: (map: Map<string | number, any>) => void;
     sortManager: SortManager | null;
+    /** Injected factory for nested grid tables (breaks the SimpleTableVanilla import cycle). */
+    createNestedTable?: NestedTableFactory;
 }
 export declare class TableRenderer {
     private sectionRenderer;

package/dist/src/index.d.ts

@@ -19,7 +19,7 @@ import type { TableAPI, SetHeaderRenameProps, ExportToCSVProps } from "./types/T
 import type TableRowProps from "./types/TableRowProps";
 import type Theme from "./types/Theme";
 import type UpdateDataProps from "./types/UpdateCellProps";
-import type { FilterCondition, TableFilterState } from "./types/FilterTypes";
+import type { FilterCondition, TableFilterState, FilterOperator, StringFilterOperator, NumberFilterOperator, BooleanFilterOperator, DateFilterOperator, EnumFilterOperator } from "./types/FilterTypes";
 import type { QuickFilterConfig, QuickFilterGetter, QuickFilterGetterProps, QuickFilterMode } from "./types/QuickFilterTypes";
 import type { ColumnVisibilityState } from "./types/ColumnVisibilityTypes";
 import type RowSelectionChangeProps from "./types/RowSelectionChangeProps";
@@ -48,4 +48,4 @@ import type { RowId } from "./types/RowId";
 import type { PinnedSectionsState } from "./types/PinnedSectionsState";
 export { SimpleTableVanilla };
 export { asRows } from "./utils/asRows";
-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, FooterRendererProps, FooterPosition, GetRowId, GetRowIdParams, IconsConfig, LoadingStateRenderer, LoadingStateRendererProps, HeaderDropdown, HeaderDropdownProps, HeaderObject, HeaderRenderer, HeaderRendererProps, HeaderRendererComponents, OnRowGroupExpandProps, OnSortProps, QuickFilterConfig, QuickFilterGetter, QuickFilterGetterProps, QuickFilterMode, Row, RowButtonProps, RowId, RowSelectionChangeProps, 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, QuickFilterConfig, QuickFilterGetter, QuickFilterGetterProps, QuickFilterMode, Row, RowButtonProps, RowId, RowSelectionChangeProps, RowState, SetHeaderRenameProps, SharedTableProps, ShowWhen, SimpleTableConfig, SimpleTableProps, SortColumn, TableAPI, TableFilterState, TableHeaderProps, TableRowProps, Theme, PinnedSectionsState, UpdateDataProps, ValueFormatter, ValueFormatterProps, ValueGetter, ValueGetterProps, };

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

@@ -57,6 +57,31 @@ export declare class AnimationCoordinator {
      * stable within a single sort.
      */
     private scrollerMetricsCache;
+    /**
+     * Vertical scroller metrics override for external/page-scroll mode. When the
+     * table has no internal vertical overflow (it grows to its natural height and
+     * a parent element / the window scrolls), the body container's own
+     * clientHeight/scrollHeight no longer describe the visible viewport, so
+     * {@link scaleFlipDistance} can't bound the FLIP journey and sort cells slide
+     * the full conceptual distance. The vanilla table pushes the real visible
+     * viewport here (from the same `getExternalScrollMetrics` the virtualizer
+     * uses) so the y-axis FLIP scaling matches the on-screen viewport. `null`
+     * when external scroll is inactive — internal scroller metrics are used as-is.
+     */
+    private externalVerticalScroll;
+    /**
+     * The currently-scheduled (not-yet-started) FLIP frame. play() defers the
+     * transition start by two animation frames so the inverted "First" frame
+     * gets painted before the transition fires. Spam-clicking sort triggers a
+     * full re-render + play() inside that two-frame window: without coalescing,
+     * the stale chain's startTransition zeroes the transforms the newer cycle
+     * just inverted (a frame early), so the final transition animates
+     * identity→identity and nothing visibly moves — and many captured nodes are
+     * detached by the intervening render before they ever transition. Tracking
+     *     the pending frame lets a new play() cancel the prior cycle and reset the
+     * transforms it left behind, so only the latest sort animates.
+     */
+    private scheduledFlip;
     constructor(opts?: AnimationCoordinatorOptions);
     setEnabled(enabled: boolean): void;
     setDuration(duration: number): void;
@@ -84,6 +109,18 @@ export declare class AnimationCoordinator {
      * mutation in the loop.
      */
     private getScrollerMetrics;
+    /**
+     * Supply (or clear) the vertical scroller metrics override used by
+     * {@link scaleFlipDistance} in external/page-scroll mode. Must be set before
+     * `captureSnapshot`/`retainCell`/`play` so the whole FLIP cycle scales
+     * against the real visible viewport. Pass `null` to fall back to the body
+     * container's own metrics (internal scroll).
+     */
+    setExternalVerticalScroll(metrics: {
+        clientHeight: number;
+        scrollHeight: number;
+        scrollTop: number;
+    } | null): void;
     private clearScrollerMetricsCache;
     /**
      * Capture pre-change positions for cells we may want to animate.

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

@@ -16,7 +16,16 @@ export interface TableFilterState {
     [accessor: Accessor]: FilterCondition;
 }
 export declare const FILTER_OPERATOR_LABELS: Record<FilterOperator, string>;
-export declare const getAvailableOperators: (columnType: "string" | "number" | "boolean" | "date" | "enum") => FilterOperator[];
+/**
+ * Returns the list of operators a column should expose in its filter UI.
+ *
+ * When `allowedOperators` is provided, the result is restricted to that list,
+ * preserving the consumer-specified order. Operators that aren't valid for the
+ * given column type are ignored. If the restriction would leave no valid
+ * operators (e.g. a misconfiguration), the full default list for the column
+ * type is returned so the filter UI never renders an empty dropdown.
+ */
+export declare const getAvailableOperators: (columnType: "string" | "number" | "boolean" | "date" | "enum", allowedOperators?: FilterOperator[]) => FilterOperator[];
 export declare const requiresSingleValue: (operator: FilterOperator) => boolean;
 export declare const requiresMultipleValues: (operator: FilterOperator) => boolean;
 export declare const requiresNoValue: (operator: FilterOperator) => boolean;

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

@@ -7,6 +7,7 @@ import { HeaderRenderer } from "./HeaderRendererProps";
 import CellValue from "./CellValue";
 import { SimpleTableProps } from "./SimpleTableProps";
 import { QuickFilterGetter } from "./QuickFilterTypes";
+import type { FilterOperator } from "./FilterTypes";
 export type Accessor = keyof Row | string;
 export type ColumnType = "string" | "number" | "boolean" | "date" | "enum" | "lineAreaChart" | "barChart" | "other";
 export type ShowWhen = "parentCollapsed" | "parentExpanded" | "always";
@@ -81,6 +82,19 @@ type HeaderObject = {
     expandable?: boolean;
     exportValueGetter?: ExportValueGetter;
     filterable?: boolean;
+    /**
+     * Restricts which filter operators are shown in this column's filter dropdown.
+     * Only operators valid for the column's `type` are honored, and they appear in
+     * the order provided here. When omitted, all operators for the column type are
+     * shown. Has no effect on `enum` columns (which use a checkbox value picker
+     * instead of an operator dropdown).
+     *
+     * @example
+     * // String column limited to "contains" and "equals"
+     * { accessor: "name", type: "string", filterable: true,
+     *   filterOperators: ["contains", "equals"] }
+     */
+    filterOperators?: FilterOperator[];
     headerRenderer?: HeaderRenderer;
     hide?: boolean;
     isEditable?: boolean;

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

@@ -0,0 +1,9 @@
+import type Row from "../../types/Row";
+import type TableRow from "../../types/TableRow";
+import { CellRenderContext } from "./types";
+export interface CellLiveRef {
+    row: Row;
+    tableRow: TableRow;
+    context: CellRenderContext;
+}
+export declare const cellLiveRefMap: WeakMap<HTMLElement, CellLiveRef>;

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

@@ -1,12 +1,7 @@
-import type Row from "../../types/Row";
-import type TableRow from "../../types/TableRow";
 import { AbsoluteBodyCell, CellRegistryEntry, CellRenderContext } from "./types";
-export interface CellLiveRef {
-    row: Row;
-    tableRow: TableRow;
-    context: CellRenderContext;
-}
-export declare const cellLiveRefMap: WeakMap<HTMLElement, CellLiveRef>;
+import { CellLiveRef, cellLiveRefMap } from "./cellLiveRef";
+export { cellLiveRefMap };
+export type { CellLiveRef };
 export declare const untrackCellByRow: (rowId: string, cellElement: HTMLElement) => void;
 export declare const unregisterCellFromRegistry: (cellElement: HTMLElement, cellRegistry?: Map<string, CellRegistryEntry>) => void;
 export declare const createBodyCellElement: (cell: AbsoluteBodyCell, context: CellRenderContext) => HTMLElement;

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

@@ -10,6 +10,7 @@ import type { CustomTheme } from "../../types/CustomTheme";
 import type { HeightOffsets } from "../infiniteScrollUtils";
 import type { AccordionAxis } from "../accordionAnimation";
 import type { VanillaEmptyStateRenderer, VanillaErrorStateRenderer, VanillaLoadingStateRenderer } from "../../types/RowStateRendererProps";
+import type { NestedTableFactory } from "../nestedGridRowRenderer";
 type SetStateAction<T> = T | ((prevState: T) => T);
 type Dispatch<A> = (value: A) => void;
 export interface AbsoluteBodyCell {
@@ -83,8 +84,20 @@ export interface CellRenderContext {
     heightOffsets?: HeightOffsets;
     customTheme?: CustomTheme;
     containerWidth?: number;
-    /** Main section viewport width (avoids clientWidth read when set); use for getVisibleBodyCells when !pinned */
+    /**
+     * Main section *content* width (sum of all non-pinned column widths). Drives
+     * the body section / row-separator width so the body is as wide as its
+     * content and scrolls horizontally. NOT the virtualization viewport — use
+     * `mainSectionViewportWidth` for getVisibleBodyCells.
+     */
     mainSectionContainerWidth?: number;
+    /**
+     * Main section *visible* viewport width (container minus pinned sections).
+     * Used by getVisibleBodyCells to decide which cells intersect the viewport
+     * (column virtualization). NOT the content width — using the content width
+     * here makes every column count as visible, disabling virtualization.
+     */
+    mainSectionViewportWidth?: number;
     onCellEdit?: (params: CellEditParams) => void;
     onCellClick?: (params: CellClickParams) => void;
     onRowGroupExpand?: (props: OnRowGroupExpandProps) => void | Promise<void>;
@@ -103,6 +116,12 @@ export interface CellRenderContext {
     loadingStateRenderer?: VanillaLoadingStateRenderer;
     errorStateRenderer?: VanillaErrorStateRenderer;
     emptyStateRenderer?: VanillaEmptyStateRenderer;
+    /**
+     * Factory used to instantiate nested grid tables. Injected by the host table
+     * so {@link nestedGridRowRenderer} never has to import the concrete
+     * `SimpleTableVanilla` class (which would create a render-module import cycle).
+     */
+    createNestedTable?: NestedTableFactory;
     getBorderClass: (cell: CellData) => string;
     isSelected: (cell: CellData) => boolean;
     isInitialFocusedCell: (cell: CellData) => boolean;

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

@@ -45,3 +45,14 @@ export declare const getExternalScrollMetrics: (parent: ResolvedScrollParent, ta
  * Returns the raw scroll-top of the parent (used for direction tracking only).
  */
 export declare const getParentScrollTop: (parent: ResolvedScrollParent) => number;
+/**
+ * Height of the parent's own viewport (window.innerHeight, or the element's
+ * border-box height), independent of where the table sits inside it.
+ *
+ * Used as a provisional virtualization viewport before the table has been laid
+ * out: at that point the table∩viewport intersection is 0, which would disable
+ * virtualization and render every row at once. Seeding with the parent viewport
+ * keeps virtualization active on the first paint; a later precise recompute
+ * refines it. Returns 0 when the parent can't be measured.
+ */
+export declare const getParentViewportHeight: (parent: ResolvedScrollParent) => number;

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

@@ -52,7 +52,8 @@ export interface HeaderRenderContext {
     icons: IconsConfig;
     lastHeaderIndex: number;
     mainBodyRef: RefObject<HTMLDivElement>;
-    mainSectionContainerWidth?: number; /** Main section viewport width (avoids clientWidth read when set); use for getVisibleCells when !pinned */
+    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 */
     onColumnOrderChange?: (headers: HeaderObject[]) => void;
     onColumnSelect?: (header: HeaderObject) => void;
     onColumnWidthChange?: (headers: HeaderObject[]) => void;

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

@@ -6,6 +6,20 @@ import type TableRow from "../types/TableRow";
 import type { CustomTheme } from "../types/CustomTheme";
 import type { SimpleTableConfig } from "../types/SimpleTableConfig";
 import { type HeightOffsets } from "./infiniteScrollUtils";
+/**
+ * Minimal surface of a table instance this renderer drives. Declared
+ * structurally so this module never has to statically import the concrete
+ * `SimpleTableVanilla` class — that import would close a cycle
+ * (SimpleTableVanilla → RenderOrchestrator → TableRenderer → SectionRenderer →
+ * nestedGridRowRenderer → SimpleTableVanilla). The class is injected at render
+ * time via {@link NestedTableFactory} instead.
+ */
+export interface NestedTableInstance {
+    mount: () => void;
+    destroy: () => void;
+}
+/** Factory injected by the host table to instantiate a nested table. */
+export type NestedTableFactory = (container: HTMLElement, config: SimpleTableConfig) => NestedTableInstance;
 export interface NestedGridRowRenderContext {
     rowHeight: number;
     heightOffsets: HeightOffsets | undefined;
@@ -17,6 +31,8 @@ export interface NestedGridRowRenderContext {
     errorStateRenderer?: SimpleTableConfig["errorStateRenderer"];
     emptyStateRenderer?: SimpleTableConfig["emptyStateRenderer"];
     icons?: SimpleTableConfig["icons"];
+    /** Injected constructor for nested tables (breaks the import cycle). */
+    createNestedTable?: NestedTableFactory;
 }
 /**
  * Creates a nested grid row element: a div with class "st-row st-nested-grid-row"

package/dist/src/utils/resizeUtils/sectionWidths.d.ts

@@ -1,4 +1,24 @@
 import type HeaderObject from "../../types/HeaderObject";
+/**
+ * Width of the *visible* portion of the main (non-pinned) section: the container
+ * width minus the pinned section widths.
+ *
+ * This is the viewport used for column virtualization (getVisibleBodyCells /
+ * getVisibleCells) — NOT `mainWidth` from {@link recalculateAllSectionWidths},
+ * which is the full *content* width (sum of all main column widths). Passing the
+ * content width here makes every column count as "in viewport", disabling column
+ * virtualization (all columns render). See the column-virtualization regression
+ * tests.
+ *
+ * Returns `undefined` when the container has not been measured yet
+ * (`containerWidth` 0) so callers fall back to a live `clientWidth` read instead
+ * of virtualizing against a 0px viewport.
+ */
+export declare const getMainSectionViewportWidth: ({ containerWidth, leftWidth, rightWidth, }: {
+    containerWidth: number;
+    leftWidth: number;
+    rightWidth: number;
+}) => number | undefined;
 /**
  * Recalculate widths for all sections (left, right, main)
  * Returns both constrained widths (for display) and raw content widths (for scrolling)

package/dist/stories/SimpleTable.stories.d.ts

@@ -44,6 +44,7 @@ export declare const LiveUpdates: StoryObj;
 export declare const LoadingState: StoryObj;
 export declare const ManufacturingExample: StoryObj;
 export declare const MusicExample: StoryObj;
+export declare const MusicWindowScroll: StoryObj;
 export declare const NestedGrid: StoryObj;
 export declare const NestedAccessor: StoryObj;
 export declare const Pagination: StoryObj;

package/dist/stories/examples/music/MusicWindowScrollExample.d.ts

@@ -0,0 +1,5 @@
+import { type UniversalVanillaArgs } from "../../vanillaStoryConfig";
+import { METRICS } from "./music-window.data";
+export declare const musicWindowScrollExampleDefaults: Partial<UniversalVanillaArgs>;
+export declare function renderMusicWindowScrollExample(args?: Partial<UniversalVanillaArgs>): HTMLElement;
+export { METRICS };

package/dist/stories/examples/music/music-window.data.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Self-contained demo data for the wide window-scroll Music example.
+ *
+ * Vanilla port of the React `music.demo-data.ts`: a wide, real-world-shaped
+ * artist analytics dataset (~60 columns) generated at runtime via a
+ * deterministic PRNG so rows stay stable across reloads.
+ */
+export interface MusicArtist {
+    id: string;
+    rank: number;
+    rankChange: number;
+    artistName: string;
+    artistType: string;
+    pronouns: string;
+    recordLabel: string;
+    genre: string;
+    country: string;
+    countryFlag: string;
+    continent: string;
+    score: number;
+    scoreChange: number;
+    earliestAlbumReleaseDate: string;
+    latestAlbumReleaseDate: string;
+    audienceAge: Record<string, number>;
+    audienceGender: {
+        f: number;
+        m: number;
+    };
+    spotifyPopularity: number;
+    spotifyPopularityChangePercent: number;
+    spotifyFollowersToListenersRatio: number;
+    spotifyReachFollowersRatio: number;
+    youtubeEngagementRate: number;
+    instagramEngagementRate: number;
+    tiktokEngagementRate: number;
+    tiktokEngagementRateChange: number;
+    [key: string]: string | number | Record<string, number> | {
+        f: number;
+        m: number;
+    } | undefined;
+}
+export declare const METRICS: [string, number][];
+export declare function generateMusicData(count?: number): MusicArtist[];
+export declare function getMusicThemeColors(theme?: string): {
+    text: string;
+    muted: string;
+};

package/dist/stories/tests/03-ColumnFilteringTests.stories.d.ts

@@ -68,3 +68,19 @@ export declare const EnumFilterMoreThan10OptionsShowsSearch: {
         canvasElement: HTMLElement;
     }) => Promise<void>;
 };
+export declare const LimitFilterOperators: {
+    render: () => HTMLDivElement & {
+        _table?: SimpleTableVanilla | undefined;
+    };
+    play: ({ canvasElement }: {
+        canvasElement: HTMLElement;
+    }) => Promise<void>;
+};
+export declare const LimitFilterOperatorsFallbackDefault: {
+    render: () => HTMLDivElement & {
+        _table?: SimpleTableVanilla | undefined;
+    };
+    play: ({ canvasElement }: {
+        canvasElement: HTMLElement;
+    }) => Promise<void>;
+};

package/dist/stories/tests/37-TableRefMethodsTests.stories.d.ts

@@ -58,6 +58,14 @@ export declare const ToggleColumnEditorApplyColumnVisibility: {
         canvasElement: HTMLElement;
     }) => Promise<void>;
 };
+export declare const ToggleColumnEditorNoArgsRepeated: {
+    render: () => HTMLDivElement & {
+        _table?: SimpleTableVanilla | undefined;
+    };
+    play: ({ canvasElement }: {
+        canvasElement: HTMLElement;
+    }) => Promise<void>;
+};
 export declare const ExpandAllCollapseAllGetExpandedDepths: {
     render: () => HTMLDivElement & {
         _table?: SimpleTableVanilla | undefined;

package/dist/stories/tests/48-ExternalScrollLateParentTests.stories.d.ts

@@ -0,0 +1,45 @@
+/**
+ * EXTERNAL SCROLL — LATE-RESOLVING PARENT TESTS
+ *
+ * Regression tests for the three fixes that make external scroll mode robust
+ * when `scrollParent` is a getter that is not resolvable at mount time (the
+ * common React case: `scrollParent={() => ref.current?.parentElement}` where
+ * `ref` is on an ancestor that React attaches *after* the table's mount effect).
+ *
+ * Fix 1 — the table retries resolving the parent on later frames, so a getter
+ *         that returns null at mount still wires up once it resolves.
+ * Fix 2 — while the parent is unresolved, a provisional viewport keeps row
+ *         virtualization ON, so the table never renders every row at once
+ *         (the original symptom was a multi-second freeze + collapsed table).
+ * Fix 3 — that provisional viewport feeds the render-window math (it is not
+ *         gated on a resolved parent), so the very first render is virtualized
+ *         and external-scroll mode (sticky header) engages immediately.
+ *
+ * These run in a real browser via the Storybook test-runner, so layout
+ * (getBoundingClientRect / scrollHeight / clientHeight) is real — which the
+ * external-scroll virtualization math depends on.
+ */
+import type { Meta } from "@storybook/html";
+declare const meta: Meta;
+export default meta;
+export declare const LateResolvingParentGetsWired: {
+    tags: string[];
+    render: () => HTMLDivElement;
+    play: ({ canvasElement }: {
+        canvasElement: HTMLElement;
+    }) => Promise<void>;
+};
+export declare const UnresolvedParentStaysVirtualized: {
+    tags: string[];
+    render: () => HTMLDivElement;
+    play: ({ canvasElement }: {
+        canvasElement: HTMLElement;
+    }) => Promise<void>;
+};
+export declare const ProvisionalViewportFeedsRenderWindow: {
+    tags: string[];
+    render: () => HTMLDivElement;
+    play: ({ canvasElement }: {
+        canvasElement: HTMLElement;
+    }) => Promise<void>;
+};

package/package.json

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