simple-table-core 3.5.2 → 3.6.2

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

@@ -54,6 +54,34 @@ export declare class SimpleTableVanilla {
     private scrollEndTimeoutId;
     private lastScrollTop;
     private isUpdating;
+    /** 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. */
+    private externalScrollListener;
+    /** Bound resize handler attached to window when scrollParent is "window". */
+    private externalWindowResizeListener;
+    /** ResizeObserver watching the external scroll parent element. */
+    private externalParentResizeObserver;
+    /** Cached visible viewport height of the table inside the external parent. Fed into virtualization. */
+    private externalViewportHeight;
+    /** True iff the body-container scroll listener is currently attached. */
+    private bodyScrollListenerAttached;
+    /** Bound mouseleave handler on the body container. */
+    private bodyContainerMouseLeaveListener;
+    /** Bound scroll handler attached to the body container (internal scroll mode). */
+    private bodyContainerScrollListener;
+    /**
+     * When external scroll mode is active we briefly take control of the scroll
+     * parent's `overscroll-behavior-y` to neutralize the browser's rubber-band /
+     * scroll-chaining at the boundaries. Without this, pulling past the top or
+     * bottom of the scroll parent visually translates the entire scroll content
+     * layer (including the CSS-sticky header), causing the header to "disappear"
+     * during overscroll bounces even though its layout position is unchanged.
+     * We record the previous inline value so {@link detachExternalScrollWiring}
+     * can restore it cleanly.
+     */
+    private overscrollBehaviorTarget;
+    private overscrollBehaviorPrev;
     /**
      * Active accordion axis for the next render. Set by row/column collapse-
      * expand mutators (see {@link beginAccordionAnimation}) and consumed by the
@@ -139,6 +167,49 @@ export declare class SimpleTableVanilla {
     mount(): void;
     private setupManagers;
     private setupEventListeners;
+    /**
+     * Reconciles which element owns the vertical scroll listener based on the
+     * current `scrollParent` config. Called on mount and whenever `update()`
+     * could have changed the relevant inputs (`scrollParent` / `height` /
+     * `maxHeight`). Idempotent — safe to call repeatedly.
+     */
+    private syncExternalScrollWiring;
+    private ensureBodyScrollListenerAttached;
+    private ensureBodyScrollListenerDetached;
+    private attachExternalScrollWiring;
+    private detachExternalScrollWiring;
+    /**
+     * Set `overscroll-behavior-y: none` on the resolved scroll parent (or
+     * `document.documentElement` for `scrollParent: "window"`). This neutralizes
+     * the browser's elastic rubber-band at the scroll boundaries, which would
+     * otherwise translate the entire scroll content layer (including our
+     * `position: sticky` header) during overscroll bounces — making the header
+     * visually disappear off the top of the parent. `contain` only stops scroll
+     * chaining; we need `none` to actually disable the elastic bounce on the
+     * scroll container itself. Previous inline value is captured so we can
+     * restore it on detach.
+     */
+    private applyOverscrollContainment;
+    private restoreOverscrollBehavior;
+    /**
+     * Read the resolved scroll parent's computed `padding-top` and publish it
+     * as `--st-external-scroll-padding-top` on the table root. The sticky
+     * header CSS uses `top: calc(-1 * var(...))` so the header pins flush to
+     * the parent's outer top edge instead of the padding edge, eliminating the
+     * visible gap that CSS sticky would otherwise produce when the consumer
+     * gives the scroll parent any top padding. Re-run on layout changes via
+     * ResizeObserver / window resize.
+     */
+    private recomputeExternalScrollPaddingTop;
+    /**
+     * Recompute the visible portion of the table inside the external scroll
+     * parent and push it into the DimensionManager so virtualization math
+     * picks it up. Cheap; called on scroll, on parent/window resize, and on
+     * every re-render where the resolved parent may have moved.
+     */
+    private recomputeExternalViewportHeight;
+    private handleExternalResize;
+    private handleExternalScroll;
     private handleScroll;
     private clearHoveredRows;
     private updateAriaLiveRegion;

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

@@ -88,6 +88,13 @@ export interface RenderContext {
     sortManager: SortManager | null;
     /** When true, body cells that stay visible get only position updates (no content/selection recalc). Used during vertical scroll for performance. */
     positionOnlyBody?: boolean;
+    /**
+     * Visible portion of the table inside an external scroll parent (in pixels).
+     * Set by {@link SimpleTableVanilla} per render when `config.scrollParent` is
+     * active and no explicit `height`/`maxHeight` is set. Drives virtualization
+     * the same way an explicit `height` does, but the scroll source is external.
+     */
+    externalViewportHeight?: number;
 }
 export interface RenderState {
     currentPage: number;

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

@@ -13,6 +13,15 @@ export interface TableRendererDeps {
     /** Accordion animation axis for the in-flight collapse/expand. See {@link RenderContext.accordionAxis}. */
     accordionAxis?: AccordionAxis;
     animationCoordinator?: AnimationCoordinator;
+    /**
+     * True when the table is using an external `scrollParent` (no `height`/`maxHeight`).
+     * In this mode the main body container does not scroll — the parent does — so
+     * the sticky-parents container reads its scrollTop from `stickyParentsScrollTop`
+     * (sourced from the table's external-aware state) instead of `mainBodyRef.scrollTop`.
+     */
+    externalScrollActive?: boolean;
+    /** Externally-tracked scrollTop (already translated into table coordinates). */
+    stickyParentsScrollTop?: number;
     cellRegistry: Map<string, any>;
     collapsedHeaders: Set<Accessor>;
     collapsedRows: Map<string, number>;

package/dist/src/hooks/contentHeight.d.ts

@@ -7,6 +7,12 @@ export interface ContentHeightConfig {
     totalRowCount: number;
     headerHeight?: number;
     footerHeight?: number;
+    /**
+     * Visible portion of the table inside an external scroll parent (in pixels).
+     * Only consulted when neither `height` nor `maxHeight` is set; enables
+     * virtualization driven by a window- or element-level scroller.
+     */
+    externalViewportHeight?: number;
 }
 /**
  * Converts a height value (string or number) to pixels
@@ -19,5 +25,5 @@ export declare const convertHeightToPixels: (heightValue: string | number) => nu
  * @param config - Configuration for content height calculation
  * @returns The calculated content height in pixels, or undefined to disable virtualization
  */
-export declare const calculateContentHeight: ({ height, maxHeight, rowHeight, shouldPaginate, rowsPerPage, totalRowCount, headerHeight, footerHeight, }: ContentHeightConfig) => number | undefined;
+export declare const calculateContentHeight: ({ height, maxHeight, rowHeight, shouldPaginate, rowsPerPage, totalRowCount, headerHeight, footerHeight, externalViewportHeight, }: ContentHeightConfig) => number | undefined;
 export default calculateContentHeight;

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

@@ -8,6 +8,11 @@ export interface DimensionManagerConfig {
     totalRowCount: number;
     footerHeight?: number;
     containerElement?: HTMLElement;
+    /**
+     * Visible portion of the table inside an external scroll parent (in pixels).
+     * Drives virtualization when neither `height` nor `maxHeight` is set.
+     */
+    externalViewportHeight?: number;
 }
 export interface DimensionManagerState {
     containerWidth: number;

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

@@ -2,7 +2,7 @@ import HeaderObject, { Accessor } from "../types/HeaderObject";
 export declare const getHeaderIndexPath: (headers: HeaderObject[], targetAccessor: Accessor, currentPath?: number[]) => number[] | null;
 export declare const getSiblingArray: (headers: HeaderObject[], indexPath: number[]) => HeaderObject[];
 export declare const setSiblingArray: (headers: HeaderObject[], indexPath: number[], newSiblings: HeaderObject[]) => HeaderObject[];
-export declare const getHeaderSection: (header: HeaderObject) => "left" | "main" | "right";
+export declare const getHeaderSection: (header: HeaderObject, rootHeaders: HeaderObject[]) => "left" | "main" | "right";
 export declare const updateHeaderPinnedProperty: (header: HeaderObject, targetSection: "left" | "main" | "right") => HeaderObject;
 export declare function swapHeaders(headers: HeaderObject[], draggedPath: number[], hoveredPath: number[]): {
     newHeaders: HeaderObject[];

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

@@ -63,6 +63,7 @@ export interface SimpleTableConfig {
     onFilterChange?: (filters: TableFilterState) => void;
     onGridReady?: () => void;
     onHeaderEdit?: (header: HeaderObject, newLabel: string) => void;
+    infiniteScrollThreshold?: number;
     onLoadMore?: () => void;
     onNextPage?: OnNextPage;
     onPageChange?: (page: number) => void | Promise<void>;
@@ -75,6 +76,7 @@ export interface SimpleTableConfig {
     getRowId?: GetRowId;
     rows: Row[];
     rowsPerPage?: number;
+    scrollParent?: HTMLElement | "window" | (() => HTMLElement | null);
     selectableCells?: boolean;
     selectableColumns?: boolean;
     serverSidePagination?: boolean;

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

@@ -63,6 +63,7 @@ export interface SimpleTableProps {
     onFilterChange?: (filters: TableFilterState) => void;
     onGridReady?: () => void;
     onHeaderEdit?: (header: HeaderObject, newLabel: string) => void;
+    infiniteScrollThreshold?: number;
     onLoadMore?: () => void;
     onNextPage?: OnNextPage;
     onPageChange?: (page: number) => void | Promise<void>;
@@ -75,6 +76,7 @@ export interface SimpleTableProps {
     getRowId?: GetRowId;
     rows: Row[];
     rowsPerPage?: number;
+    scrollParent?: HTMLElement | "window" | (() => HTMLElement | null);
     selectableCells?: boolean;
     selectableColumns?: boolean;
     serverSidePagination?: boolean;

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

@@ -0,0 +1,47 @@
+/**
+ * Helpers for the "external scroll parent" virtualization mode.
+ *
+ * When a consumer supplies `scrollParent` and the table has neither `height`
+ * nor `maxHeight`, the table grows to its natural height inside the parent
+ * and we look at the parent's scroll position / viewport to drive
+ * virtualization and `onLoadMore`.
+ */
+export type ScrollParentValue = HTMLElement | "window" | (() => HTMLElement | null) | undefined | null;
+export type ResolvedScrollParent = HTMLElement | Window | null;
+export interface ExternalScrollMetrics {
+    /** Scroll offset translated into the table's own coordinate space, clamped to [0, tableTotalHeight]. */
+    relativeScrollTop: number;
+    /** Height of the table portion that is actually visible inside the parent viewport, in pixels. */
+    visibleViewportHeight: number;
+    /** Distance in pixels from the current visible-bottom edge to the table's bottom edge. */
+    distanceFromTableBottom: number;
+    /** Full pixel height of the table root element. */
+    tableTotalHeight: number;
+    /** Width of the parent viewport, in pixels. */
+    viewportWidth: number;
+}
+/**
+ * Resolve a `scrollParent` config value to a usable element or window reference.
+ * Returns `null` if the value cannot be resolved this tick (e.g. a ref that
+ * has not yet been attached). Never throws.
+ */
+export declare const resolveScrollParent: (value: ScrollParentValue) => ResolvedScrollParent;
+/**
+ * Returns true if external scroll mode should be active for the given props.
+ * External mode is only enabled when no explicit height constraint is set;
+ * `height` / `maxHeight` always win.
+ */
+export declare const isExternalScrollActive: (scrollParent: ScrollParentValue, height: string | number | undefined, maxHeight: string | number | undefined) => boolean;
+/**
+ * Compute scroll metrics translated into the table's coordinate space.
+ *
+ * The math: position the table's bounding rect within the parent's viewport rect,
+ * then intersect with the visible band of the parent. The intersection's top edge
+ * (relative to the table) is the effective `scrollTop` for virtualization, and the
+ * intersection's height is the effective `clientHeight`.
+ */
+export declare const getExternalScrollMetrics: (parent: ResolvedScrollParent, tableRoot: HTMLElement | null) => ExternalScrollMetrics | null;
+/**
+ * Returns the raw scroll-top of the parent (used for direction tracking only).
+ */
+export declare const getParentScrollTop: (parent: ResolvedScrollParent) => number;

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

@@ -4,7 +4,7 @@ import type { Pinned } from "../../types/Pinned";
  * Handle resize with autoExpandColumns enabled
  * Columns to the right (or left for right-pinned) shrink proportionally
  */
-export declare const handleResizeWithAutoExpand: ({ childrenToResize, collapsedHeaders, containerWidth, delta, headers, initialWidthsMap, isParentResize, resizedHeader, reverse, rootPinned, sectionHeaders, sectionWidth, startWidth, }: {
+export declare const handleResizeWithAutoExpand: ({ childrenToResize, collapsedHeaders, containerWidth, delta, headers, initialWidthsMap, isParentResize, pinnedBodyViewportWidth, resizedHeader, reverse, rootPinned, sectionHeaders, sectionWidth, startWidth, }: {
     childrenToResize?: HeaderObject[] | undefined;
     collapsedHeaders?: Set<string> | undefined;
     containerWidth: number;
@@ -12,6 +12,8 @@ export declare const handleResizeWithAutoExpand: ({ childrenToResize, collapsedH
     headers: HeaderObject[];
     initialWidthsMap: Map<string, number>;
     isParentResize?: boolean | undefined;
+    /** When set, caps pinned growth so column sums do not exceed this scrollport (policy max can be wider). */
+    pinnedBodyViewportWidth?: number | undefined;
     resizedHeader: HeaderObject;
     reverse: boolean;
     rootPinned: Pinned | undefined;

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

@@ -29,6 +29,14 @@ export interface StickyParentsContainerProps {
      * for the current `rowsToRender` band, so selection matches virtualized body cells.
      */
     stickyBodyRowIndexByRowKey: Map<string, number>;
+    /**
+     * When true, the table is in external-scroll mode (scrollParent in use, no
+     * fixed height). The overlay uses native CSS `position: sticky` (handled by
+     * a stylesheet rule) so the browser composites it on the same paint as the
+     * parent scroll. The renderer only needs this flag to neutralize the
+     * overlay's flex column flow contribution via a negative bottom margin.
+     */
+    externalScrollActive?: boolean;
 }
 export interface StickyParentsRenderContext {
     collapsedHeaders: Set<string>;

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

@@ -37,6 +37,7 @@ export declare const FinanceExample: StoryObj;
 export declare const HeaderInclusion: StoryObj;
 export declare const HiddenColumns: StoryObj;
 export declare const InfiniteScroll: StoryObj;
+export declare const WindowInfiniteScroll: StoryObj;
 export declare const InfrastructureExample: StoryObj;
 export declare const LeadsExample: StoryObj;
 export declare const LiveUpdates: StoryObj;

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

@@ -0,0 +1,3 @@
+import { type UniversalVanillaArgs } from "../vanillaStoryConfig";
+export declare const windowInfiniteScrollExampleDefaults: Partial<UniversalVanillaArgs>;
+export declare function renderWindowInfiniteScrollExample(args?: Partial<UniversalVanillaArgs>): HTMLElement;

package/dist/stories/examples/sales-example/SalesExample.d.ts

@@ -1,14 +1,11 @@
 import { type UniversalVanillaArgs } from "../../vanillaStoryConfig";
 export declare const salesExampleDefaults: {
-    animations: {
-        enabled: boolean;
-    };
     columnResizing: boolean;
     columnReordering: boolean;
     selectableCells: boolean;
     autoExpandColumns: boolean;
-    enableRowSelection: boolean;
     theme: "modern-dark";
     height: string;
+    editColumns: boolean;
 };
 export declare function renderSalesExample(args?: Partial<UniversalVanillaArgs>): HTMLElement;

package/dist/stories/tests/44-ExternalScrollTests.stories.d.ts

@@ -0,0 +1,53 @@
+/**
+ * EXTERNAL SCROLL TESTS
+ *
+ * Tests for the `scrollParent` prop which lets a consumer point the table at
+ * an external scroll container (HTMLElement or window). When active and
+ * neither height nor maxHeight is set, the external parent's scroll drives
+ * row virtualization and onLoadMore.
+ */
+import type { Meta } from "@storybook/html";
+declare const meta: Meta;
+export default meta;
+export declare const ExternalElementVirtualizes: {
+    tags: string[];
+    render: () => HTMLDivElement;
+    play: ({ canvasElement }: {
+        canvasElement: HTMLElement;
+    }) => Promise<void>;
+};
+export declare const ExternalScrollFiresOnLoadMore: {
+    tags: string[];
+    render: () => HTMLDivElement;
+    play: ({ canvasElement }: {
+        canvasElement: HTMLElement;
+    }) => Promise<void>;
+};
+export declare const NoScrollParentRendersAll: {
+    tags: string[];
+    render: () => HTMLDivElement;
+    play: ({ canvasElement }: {
+        canvasElement: HTMLElement;
+    }) => Promise<void>;
+};
+export declare const HeightOverridesScrollParent: {
+    tags: string[];
+    render: () => HTMLDivElement;
+    play: ({ canvasElement }: {
+        canvasElement: HTMLElement;
+    }) => Promise<void>;
+};
+export declare const StickyHeaderInExternalScroll: {
+    tags: string[];
+    render: () => HTMLDivElement;
+    play: ({ canvasElement }: {
+        canvasElement: HTMLElement;
+    }) => Promise<void>;
+};
+export declare const RowGroupingInExternalScroll: {
+    tags: string[];
+    render: () => HTMLDivElement;
+    play: ({ canvasElement }: {
+        canvasElement: HTMLElement;
+    }) => Promise<void>;
+};