simple-table-core 3.8.2 → 3.8.4

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

@@ -70,6 +70,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. */
@@ -180,6 +189,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;

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/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/types.d.ts

@@ -83,8 +83,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>;

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/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.2",
+  "version": "3.8.4",
   "main": "dist/cjs/index.js",
   "module": "dist/index.es.js",
   "types": "dist/src/index.d.ts",