simple-table-core 3.8.4 → 3.8.6

package/dist/cjs/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/cjs/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. */
@@ -164,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
@@ -177,6 +188,14 @@ export declare class SimpleTableVanilla {
      * No-op when animations are disabled (which already includes the
      * prefers-reduced-motion check via {@link AnimationCoordinator.isEnabled}).
      */
+    /**
+     * Walk the CURRENT (pre-change) header tree and collect every accessor that
+     * is renderable as a header cell given the current collapsed/hidden state —
+     * group headers plus the leaf columns visible under them (honoring
+     * `showWhen` and the collapsed set). Used by {@link beginAccordionAnimation}
+     * to seed the animation coordinator's re-entry guard.
+     */
+    private collectAccordionRenderableAccessors;
     private beginAccordionAnimation;
     private initializeManagers;
     mount(): void;
@@ -267,6 +286,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/cjs/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/cjs/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;
     };
@@ -122,6 +125,7 @@ export declare class RenderOrchestrator {
     getLastProcessedResult(): ProcessRowsResult | null;
     /** See {@link TableRenderer.getCurrentBodyLayouts}. */
     getCurrentBodyLayouts(): Map<HTMLElement, Map<string, CellPosition>>;
+    setOnRendererHostDiscard(cb: ((host: HTMLElement) => void) | undefined): void;
     invalidateCache(type?: "body" | "header" | "context" | "all"): void;
     computeEffectiveHeaders(headers: HeaderObject[], config: SimpleTableConfig, customTheme: CustomTheme, containerWidth?: number): HeaderObject[];
     /**

package/dist/cjs/src/core/rendering/SectionRenderer.d.ts

@@ -44,6 +44,13 @@ export interface BodySectionParams {
 export declare class SectionRenderer {
     private headerSections;
     private bodySections;
+    /**
+     * Callback fired before a body cell host element is permanently removed in
+     * the {@link invalidateCache} "all" path (which wipes every rendered cell).
+     * Threaded down from the table config so framework adapters can tear down
+     * renderer subtrees (React portals, etc.) before the nodes are discarded.
+     */
+    private onRendererHostDiscard?;
     private bodyCellsCache;
     private headerCellsCache;
     private contextCache;
@@ -64,6 +71,7 @@ export declare class SectionRenderer {
     private getCachedBodyCells;
     private getCachedHeaderCells;
     private getCachedContext;
+    setOnRendererHostDiscard(cb: ((host: HTMLElement) => void) | undefined): void;
     invalidateCache(type?: "body" | "header" | "context" | "all"): void;
     /**
      * Get the next colIndex after rendering a section

package/dist/cjs/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;
@@ -96,6 +99,7 @@ export declare class TableRenderer {
     private pendingRenderCallback;
     constructor();
     private scheduleRender;
+    setOnRendererHostDiscard(cb: ((host: HTMLElement) => void) | undefined): void;
     invalidateCache(type?: "body" | "header" | "context" | "all"): void;
     /** See {@link SectionRenderer.getCurrentBodyLayouts}. */
     getCurrentBodyLayouts(): Map<HTMLElement, Map<string, CellPosition>>;

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

@@ -41,6 +41,21 @@ export declare class AnimationCoordinator {
      * rather than appearing in place. Cleared at the end of {@link play}.
      */
     private incomingOrigins;
+    /**
+     * Accessors that were already renderable (visible leaf/group columns) in the
+     * pre-change layout for an in-flight accordion-horizontal toggle. Set once
+     * per collapse/expand render and consumed by the renderers' grow-from-zero
+     * gate so a column that merely re-enters the virtualization band (because the
+     * collapsed group shrank the content width and clamped scrollLeft) is NOT
+     * mistaken for a freshly-expanded column and animated from width 0.
+     *
+     * Header cells have no full pre-change conceptual layout the way body cells do
+     * (see SectionRenderer.getCurrentBodyLayouts), so `hasSnapshotEntry` alone
+     * can't tell "newly visible" apart from "scrolled back into view". This set
+     * supplies the missing pre-change visibility signal. Cleared at the end of
+     * {@link play}.
+     */
+    private accordionPreVisibleAccessors;
     private inFlight;
     /** Outgoing cells the renderer handed off; keyed per container so play() finds them. */
     private retainedCells;
@@ -57,7 +72,46 @@ 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;
+    /**
+     * Invoked immediately BEFORE a retained/ghost element is permanently removed
+     * from the DOM (FLIP/shrink/cancel/destroy teardown). Lets framework adapters
+     * tear down renderer subtrees (React portals, etc.) mounted into the element
+     * before it's discarded. NOT called on reuse/reparent paths
+     * ({@link claimRetainedForReuse} success), so a reclaimed ghost keeps its
+     * content.
+     */
+    private onHostDiscard?;
     constructor(opts?: AnimationCoordinatorOptions);
+    /**
+     * Register the callback fired before a ghost/retained element is permanently
+     * removed (see {@link onHostDiscard}). Additive: passing `undefined` disables it.
+     */
+    setOnHostDiscard(cb: ((host: HTMLElement) => void) | undefined): void;
     setEnabled(enabled: boolean): void;
     setDuration(duration: number): void;
     setEasing(easing: string): void;
@@ -76,6 +130,21 @@ export declare class AnimationCoordinator {
      * the corresponding cells.
      */
     setIncomingOrigins(origins: Map<string, CellPosition> | null): void;
+    /**
+     * Register the set of accessors that were renderable in the pre-change layout
+     * of an accordion-horizontal toggle. Must be set after `captureSnapshot` and
+     * before the render that creates cells. Consumed and cleared by the next
+     * {@link play}. Pass `null` (e.g. for vertical/row accordions) to disable the
+     * re-entry guard so behavior is unchanged.
+     */
+    setAccordionPreVisibleAccessors(accessors: Set<string> | null): void;
+    /**
+     * True when `accessor` was already a renderable column before the current
+     * accordion-horizontal toggle. Renderers use this to skip the grow-from-zero
+     * animation for columns that only re-entered the virtualization band rather
+     * than genuinely becoming visible from an expand.
+     */
+    wasRenderableBeforeAccordion(accessor: string): boolean;
     /**
      * Read scroller layout metrics for `container`, caching the result for the
      * remainder of the current render cycle. Subsequent calls in the same
@@ -84,6 +153,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/cjs/src/types/SimpleTableConfig.d.ts

@@ -72,6 +72,16 @@ export interface SimpleTableConfig {
     onPageChange?: (page: number) => void | Promise<void>;
     onRowGroupExpand?: (props: OnRowGroupExpandProps) => void | Promise<void>;
     onRowSelectionChange?: (props: RowSelectionChangeProps) => void;
+    /**
+     * Called by the renderer immediately BEFORE it permanently discards a host
+     * element that may contain async-framework renderer output (e.g. React
+     * portals): innerHTML clears on cell rebuild/edit, plain cell removal, and
+     * the animation coordinator's ghost/FLIP/shrink teardown paths. Framework
+     * adapters use this to tear down the renderer subtree mounted into `host`
+     * (or any descendant) so it isn't orphaned. Reuse/reparent paths never fire
+     * it, so a reused node keeps its renderer content.
+     */
+    onRendererHostDiscard?: (host: HTMLElement) => void;
     onSortChange?: (sort: SortColumn | null) => void;
     quickFilter?: QuickFilterConfig;
     rowButtons?: RowButton[];

package/dist/cjs/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/cjs/src/utils/bodyCell/eventTracking.d.ts

@@ -1,3 +1,3 @@
 export declare const addTrackedEventListener: (element: HTMLElement, event: string, handler: EventListener, options?: AddEventListenerOptions) => void;
 export declare const getRenderedCells: (container: HTMLElement) => Map<string, HTMLElement>;
-export declare const cleanupBodyCellRendering: (container?: HTMLElement) => void;
+export declare const cleanupBodyCellRendering: (container?: HTMLElement, onHostDiscard?: ((host: HTMLElement) => void) | undefined) => void;

package/dist/cjs/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/cjs/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 {
@@ -103,6 +104,14 @@ export interface CellRenderContext {
     handleRowSelect?: (rowId: string, checked: boolean) => void;
     handleMouseDown: (cell: CellData) => void;
     handleMouseOver: (cell: CellData, clientX: number, clientY: number) => void;
+    /**
+     * Called immediately BEFORE the renderer permanently discards a host element
+     * (e.g. `innerHTML = ""` on cell rebuild/edit, or a plain `element.remove()`).
+     * Framework adapters use this to tear down any renderer subtree (React
+     * portal, etc.) mounted into `host` or one of its descendants. Reuse paths
+     * never call it, so a reused node keeps its content.
+     */
+    onRendererHostDiscard?: (host: HTMLElement) => void;
     cellRegistry?: Map<string, CellRegistryEntry>;
     setCollapsedRows: Dispatch<SetStateAction<Map<string, number>>>;
     setExpandedRows: Dispatch<SetStateAction<Map<string, number>>>;
@@ -115,6 +124,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/cjs/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"