@joewinke/jatui 0.26.0 → 0.27.1

package/dist/virtual/rowWindowCore.d.ts

@@ -0,0 +1,202 @@
+/**
+ * rowWindowCore — the framework-free engine behind `createRowWindow`
+ * (jatui-u6d4e.1, spec: jat docs/design/datatable-virtualisation-group-rows.md §3.1).
+ *
+ * Variable-height windowing for SPACER-ROW layouts: the consumer renders
+ * `paddingTop` px of spacer, the rendered slice in document flow, then
+ * `paddingBottom` px of spacer. Nothing is absolutely positioned, so a
+ * `<table>` keeps `table-layout: fixed` widths and native sticky `<thead>`s.
+ *
+ * Layering:
+ *   - Pure helpers (`normalizeStickyLevels`, `activeStickyIndices`,
+ *     `extractWindowIndices`, `layoutWindow`, `findScrollRoot`) hold the
+ *     window policy — threshold, pinned keys, sticky group headers, spacer
+ *     maths. DOM-free, so `npm run test:unit` covers them under node:test.
+ *   - `RowWindowEngine` drives `@tanstack/virtual-core` (an OPTIONAL peer,
+ *     which is why this module only ships behind `@joewinke/jatui/virtual`)
+ *     for measured sizes, scroll-offset tracking and scroll-anchor correction
+ *     when a row above the viewport changes height.
+ *   - `createRowWindow.svelte.ts` is the thin runes wrapper.
+ */
+import { type Range, type VirtualItem } from '@tanstack/virtual-core';
+export type RowWindowAlign = 'auto' | 'start' | 'center' | 'end';
+/** One rendered item of the window. */
+export interface RowWindowItem<K = string> {
+    /** Index in the render list. */
+    index: number;
+    key: K;
+    /** Offset from the top of the anchor, px. */
+    start: number;
+    /** Measured height, or the estimate until the row has been measured. */
+    size: number;
+    /** `start + size`. */
+    end: number;
+    /**
+     * Spacer to render immediately BEFORE this item, px. Always 0 for the
+     * first item (that gap is `paddingTop`) and 0 between neighbours of a
+     * contiguous slice. Non-zero only when a pinned item or an active sticky
+     * header sits outside the visible slice, so the consumer can keep every
+     * item at its true offset.
+     */
+    gapBefore: number;
+    /** The item is one of `stickyIndices` (a group header). */
+    sticky: boolean;
+    /** The item's key is in `pinned`. */
+    pinned: boolean;
+}
+export interface RowWindowSnapshot<K = string> {
+    items: ReadonlyArray<RowWindowItem<K>>;
+    /** Spacer above the first rendered item, px. */
+    paddingTop: number;
+    /** Spacer below the last rendered item, px. */
+    paddingBottom: number;
+    /** Height of the whole list (measured where known, estimated elsewhere), px. */
+    totalSize: number;
+    /** False when `count < threshold` and every item is rendered. */
+    windowed: boolean;
+    /** Number of items in the render list. */
+    count: number;
+}
+export declare const EMPTY_SNAPSHOT: RowWindowSnapshot<never>;
+/**
+ * `stickyIndices` accepts one flat list (one header level) or one list per
+ * level, outermost first (`[projectHeaderIdx[], epicHeaderIdx[]]`). Returns the
+ * per-level form, each level sorted ascending with out-of-range entries dropped.
+ */
+export declare function normalizeStickyLevels(input: readonly number[] | readonly (readonly number[])[] | null | undefined, count: number): number[][];
+/**
+ * The sticky header that is "active" at `startIndex` (the first visible item),
+ * per level. For level n it is the last level-n header at or above
+ * `startIndex` that comes AFTER level n-1's active header, so an epic header
+ * from the previous project never sticks under the current project's header.
+ */
+export declare function activeStickyIndices(levels: readonly (readonly number[])[], startIndex: number): number[];
+export interface WindowPolicy {
+    /** Below this count, render everything. 0 = always window. */
+    threshold: number;
+    /** Indices that must render regardless of scroll position. */
+    pinnedIndices: readonly number[];
+    /** Sticky header indices per level (see `normalizeStickyLevels`). */
+    stickyLevels: readonly (readonly number[])[];
+}
+/**
+ * The rangeExtractor: which indices to render for a visible `range`. The
+ * visible slice plus overscan, every pinned index, and the active sticky
+ * header of each level, sorted and de-duplicated. Below `threshold`, all.
+ */
+export declare function extractWindowIndices(range: Range, policy: WindowPolicy): number[];
+/**
+ * Turn virtual-core's measured items (absolute offsets that include
+ * `scrollMargin`) into the spacer-row snapshot the consumer renders.
+ */
+export declare function layoutWindow<K>(virtualItems: readonly Pick<VirtualItem, 'index' | 'key' | 'start' | 'size'>[], opts: {
+    scrollMargin: number;
+    totalSize: number;
+    count: number;
+    windowed: boolean;
+    stickySet: ReadonlySet<number>;
+    pinnedSet: ReadonlySet<number>;
+}): RowWindowSnapshot<K>;
+/** Cheap structural equality so unchanged layouts don't churn reactive state. */
+export declare function sameSnapshot<K>(a: RowWindowSnapshot<K>, b: RowWindowSnapshot<K>): boolean;
+/** Minimal structural view of an element, so `findScrollRoot` is testable without a DOM. */
+export interface ScrollRootCandidate {
+    parentElement: ScrollRootCandidate | null;
+    scrollHeight: number;
+    clientHeight: number;
+    tagName: string;
+}
+/**
+ * `scrollRoot: 'auto'` — the nearest ancestor that actually scrolls
+ * vertically: `overflow-y` is auto/scroll/overlay AND its content overflows it.
+ * An `overflow-auto` wrapper that grows with its content never scrolls (the
+ * dash TaskTable case), so it is skipped in favour of the real scroller.
+ * Returns `null` for "the window".
+ */
+export declare function findScrollRoot<E extends ScrollRootCandidate>(node: E, overflowY: (el: E) => string): E | null;
+export interface RowWindowEngineOptions {
+    /** Extra items rendered above and below the viewport. */
+    overscan: number;
+    /** Below this count, render everything. 0 = always window. */
+    threshold: number;
+    /** The scroller. `'auto'` resolves on attach (see `findScrollRoot`). */
+    scrollRoot: HTMLElement | Window | 'auto';
+    /** Viewport height assumed before the anchor mounts (SSR / first paint), px. */
+    initialViewportSize: number;
+    /** Space a sticky header covers at the top, honoured by `scrollTo*`. */
+    scrollPaddingStart: number;
+    scrollPaddingEnd: number;
+    /** Called whenever the rendered layout changes. */
+    onChange?: (snapshot: RowWindowSnapshot<unknown>) => void;
+}
+/**
+ * Imperative windowing engine. One per list. Feed it the render list with
+ * `setItems`, mount it with `attach(anchor)`, register each rendered element
+ * with `measure`, and read `snapshot` (or listen via `onChange`).
+ */
+export declare class RowWindowEngine<K = string> {
+    private readonly opts;
+    private readonly v;
+    private keys;
+    private estimates;
+    private keyIndex;
+    private getItemKey;
+    private estimateSize;
+    private pinnedKeys;
+    private pinnedIndices;
+    private pinnedSet;
+    private stickyInput;
+    private stickyLevels;
+    private stickySet;
+    private rangeExtractor;
+    private scrollMargin;
+    private anchorEl;
+    private root;
+    private rootUnsub;
+    private anchorRO;
+    private prevOverflowAnchor;
+    private unmountVirtualizer;
+    private nodes;
+    private pendingScroll;
+    private sweepQueued;
+    private destroyed;
+    snapshot: RowWindowSnapshot<K>;
+    constructor(opts: RowWindowEngineOptions);
+    /** Replace the render list. `keys[i]` must be unique. */
+    setItems(keys: readonly K[], estimates: readonly number[]): void;
+    setPinned(keys: Iterable<K>): void;
+    /** Change the render-everything threshold. */
+    setThreshold(threshold: number): void;
+    setSticky(input: readonly number[] | readonly (readonly number[])[]): void;
+    private resolvePinned;
+    private rebuildRangeExtractor;
+    private buildOptions;
+    /** Push current inputs into virtual-core and recompute the snapshot. */
+    private sync;
+    private emit;
+    /** Mount on the element whose top is item 0's top (a `<tbody>` or list container). */
+    attach(anchor: HTMLElement): void;
+    detach(): void;
+    destroy(): void;
+    private resolveRoot;
+    private bindRoot;
+    /** The anchor or root resized: re-resolve an 'auto' root, refresh the margin. */
+    private onLayoutShift;
+    /** Distance from the scroller's content top to the anchor's top. */
+    private updateScrollMargin;
+    /** Register a rendered item element. Re-measured on every resize. */
+    measure(node: HTMLElement, key: K): void;
+    /** Forget an item element (it unmounted, or its key changed). */
+    unmeasure(node: HTMLElement, key: K): void;
+    private queueSweep;
+    scrollToIndex(index: number, opts?: {
+        align?: RowWindowAlign;
+    }): void;
+    scrollToKey(key: K, opts?: {
+        align?: RowWindowAlign;
+    }): void;
+    /** Index of `key` in the render list, or -1. */
+    indexOf(key: K): number;
+    /** Drop every cached measurement (e.g. after a column-width change). */
+    remeasure(): void;
+}