impact-nova 2.6.3 → 3.0.0-alpha.1

package/dist/lib/virtualized/directional-range-extractor.d.ts

@@ -0,0 +1,26 @@
+import { Range } from '@tanstack/virtual-core';
+export type VirtualScrollDirection = "forward" | "backward" | null;
+export type DirectionalRangeExtractorOptions = {
+    /** Extra strips kept above and below the viewport so travel is already painted. */
+    travelExtra?: number;
+    /**
+     * How close the visible range may get to the sticky window edge before the
+     * window is remapped. Larger values mean more compositor-only scrolling
+     * (Google Sheets / Instagram) and fewer React remounts.
+     */
+    hysteresis?: number;
+};
+/**
+ * Spreadsheet-style virtual window:
+ * 1. Keep extra rows above so scrolling up is already painted.
+ * 2. Hold a **sticky** index range (hysteresis) so pixel scrolling does not
+ *    remount rows — the native scroller just slides over already-painted DOM.
+ * 3. Remap only when the visible range nears the sticky edge.
+ */
+export declare function createDirectionalRangeExtractor(options?: number | DirectionalRangeExtractorOptions): (range: Range) => number[];
+/**
+ * Sticky painted window for strip grids. `travelExtra` stays 0 so TanStack
+ * `overscan` remains the only buffer; hysteresis is below typical grid overscan
+ * (6–12) so the window actually sticks instead of remapping every scroll.
+ */
+export declare function createStickyStripRangeExtractor(options?: DirectionalRangeExtractorOptions): (range: Range) => number[];

package/dist/lib/virtualized/directional-range-extractor.js

@@ -0,0 +1,39 @@
+function m(e = {}) {
+  return typeof e == "number" ? { travelExtra: e, hysteresis: 8 } : {
+    travelExtra: e.travelExtra ?? 8,
+    hysteresis: e.hysteresis ?? 8
+  };
+}
+function y(e, c) {
+  const s = [];
+  for (let t = e; t <= c; t += 1)
+    s.push(t);
+  return s;
+}
+function f(e = {}) {
+  const { travelExtra: c, hysteresis: s } = m(e);
+  let t = 0, r = -1, i = -1, a = -1, o = [];
+  return (n) => {
+    const d = Math.max(
+      0,
+      n.startIndex - n.overscan - c
+    ), x = Math.min(
+      n.count - 1,
+      n.endIndex + n.overscan + c
+    ), l = r < 0, u = n.startIndex - t, h = r - n.endIndex, v = t > 0 && u < s, E = r < n.count - 1 && h < s, I = r > n.count - 1;
+    return (l || v || E || I) && (t = d, r = x), t = Math.max(0, Math.min(t, n.count - 1)), r = Math.max(
+      t,
+      Math.min(r, n.count - 1)
+    ), (t !== i || r !== a) && (i = t, a = r, o = y(t, r)), o;
+  };
+}
+function M(e = {}) {
+  return f({
+    travelExtra: e.travelExtra ?? 0,
+    hysteresis: e.hysteresis ?? 4
+  });
+}
+export {
+  f as createDirectionalRangeExtractor,
+  M as createStickyStripRangeExtractor
+};

package/dist/lib/virtualized/index.d.ts

@@ -6,6 +6,9 @@ export { useVirtualizedRows, type UseVirtualizedRowsOptions } from './useVirtual
 export { useVirtualizedList, type UseVirtualizedListOptions, type UseVirtualizedListResult, } from './useVirtualizedList';
 export { buildSectionedFlatList, type DataSectionBlock, type HeaderSectionBlock, type SectionBlock, type SectionedFlatList, type SectionedFlatRow, } from './sectioned';
 export { useDebouncedValue } from './useDebouncedValue';
+export { createDirectionalRangeExtractor, createStickyStripRangeExtractor, type DirectionalRangeExtractorOptions, type VirtualScrollDirection, } from './directional-range-extractor';
+export { useScrollSeekPaintedRange } from './useScrollSeekPaintedRange';
+export { getResponsiveColumnCount, useResponsiveColumnCount, type ResponsiveColumnCountInput, type UseResponsiveColumnCountOptions, } from './useResponsiveColumnCount';
 export { useDataGridVirtualRows, type DataGridVirtualRowsResult, } from './useDataGrid';
 export { VirtualizedListProvider, useVirtualizedListContext, type VirtualizedListContextValue, } from './virtualized-list-context';
 export { getVisibleReadyRowIds } from './virtualized-list-utils';

package/dist/lib/virtualized/index.js

@@ -1,35 +1,43 @@
-import { getSelectionCountsFromState as i } from "./selection-counts.js";
+import { getSelectionCountsFromState as r } from "./selection-counts.js";
 import { useDataSource as o } from "./useDataSource.js";
 import { useRowState as s } from "./useRowState.js";
 import { useVirtualizedRows as l } from "./useVirtualizedRows.js";
-import { useVirtualizedList as V } from "./useVirtualizedList.js";
-import { buildSectionedFlatList as L } from "./sectioned.js";
-import { useDebouncedValue as p } from "./useDebouncedValue.js";
-import { useDataGridVirtualRows as f } from "./useDataGrid.js";
-import { VirtualizedListProvider as S, useVirtualizedListContext as c } from "./virtualized-list-context.js";
-import { getVisibleReadyRowIds as R } from "./virtualized-list-utils.js";
-import { VirtualizedList as C, VirtualizedListContent as D, VirtualizedListFooter as F, VirtualizedListHeader as I, VirtualizedListHeaderActions as g, VirtualizedListItem as h, VirtualizedListItemSkeleton as A, VirtualizedListSearch as H, VirtualizedListSelectAll as k, VirtualizedListShell as v, VirtualizedListViewport as y } from "./virtualized-list-parts.js";
+import { useVirtualizedList as n } from "./useVirtualizedList.js";
+import { buildSectionedFlatList as V } from "./sectioned.js";
+import { useDebouncedValue as x } from "./useDebouncedValue.js";
+import { createDirectionalRangeExtractor as L, createStickyStripRangeExtractor as c } from "./directional-range-extractor.js";
+import { useScrollSeekPaintedRange as S } from "./useScrollSeekPaintedRange.js";
+import { getResponsiveColumnCount as C, useResponsiveColumnCount as g } from "./useResponsiveColumnCount.js";
+import { useDataGridVirtualRows as D } from "./useDataGrid.js";
+import { VirtualizedListProvider as k, useVirtualizedListContext as v } from "./virtualized-list-context.js";
+import { getVisibleReadyRowIds as I } from "./virtualized-list-utils.js";
+import { VirtualizedList as y, VirtualizedListContent as A, VirtualizedListFooter as E, VirtualizedListHeader as H, VirtualizedListHeaderActions as P, VirtualizedListItem as G, VirtualizedListItemSkeleton as j, VirtualizedListSearch as q, VirtualizedListSelectAll as B, VirtualizedListShell as J, VirtualizedListViewport as K } from "./virtualized-list-parts.js";
 export {
-  C as VirtualizedList,
-  D as VirtualizedListContent,
-  F as VirtualizedListFooter,
-  I as VirtualizedListHeader,
-  g as VirtualizedListHeaderActions,
-  h as VirtualizedListItem,
-  A as VirtualizedListItemSkeleton,
-  S as VirtualizedListProvider,
-  H as VirtualizedListSearch,
-  k as VirtualizedListSelectAll,
-  v as VirtualizedListShell,
-  y as VirtualizedListViewport,
-  L as buildSectionedFlatList,
-  i as getSelectionCountsFromState,
-  R as getVisibleReadyRowIds,
-  f as useDataGridVirtualRows,
+  y as VirtualizedList,
+  A as VirtualizedListContent,
+  E as VirtualizedListFooter,
+  H as VirtualizedListHeader,
+  P as VirtualizedListHeaderActions,
+  G as VirtualizedListItem,
+  j as VirtualizedListItemSkeleton,
+  k as VirtualizedListProvider,
+  q as VirtualizedListSearch,
+  B as VirtualizedListSelectAll,
+  J as VirtualizedListShell,
+  K as VirtualizedListViewport,
+  V as buildSectionedFlatList,
+  L as createDirectionalRangeExtractor,
+  c as createStickyStripRangeExtractor,
+  C as getResponsiveColumnCount,
+  r as getSelectionCountsFromState,
+  I as getVisibleReadyRowIds,
+  D as useDataGridVirtualRows,
   o as useDataSource,
-  p as useDebouncedValue,
+  x as useDebouncedValue,
+  g as useResponsiveColumnCount,
   s as useRowState,
-  V as useVirtualizedList,
-  c as useVirtualizedListContext,
+  S as useScrollSeekPaintedRange,
+  n as useVirtualizedList,
+  v as useVirtualizedListContext,
   l as useVirtualizedRows
 };

package/dist/lib/virtualized/scroll-seek.d.ts

@@ -0,0 +1,61 @@
+export type ScrollSeekSample = {
+    scrollOffset: number;
+    isScrolling: boolean;
+    /** Milliseconds timestamp. Defaults to `performance.now()`. */
+    nowMs?: number;
+};
+/**
+ * react-virtuoso scroll-seek:
+ * a fast flick renders cheap placeholders instead of heavy cells, then the
+ * real cells paint once scrolling stops. Slow wheel ticks stay on real cells.
+ */
+export declare function createScrollSeekTracker(): {
+    /** Exponential moving average, px/ms. Zero while the scroller is idle. */
+    readonly smoothedVelocityPxPerMs: number;
+    update(sample: ScrollSeekSample): boolean;
+};
+declare const OVERSCAN_REVEAL_STRIPS_PER_FRAME = 2;
+export type StripWindow = {
+    scrollOffset: number | null;
+    isScrolling?: boolean;
+    scrollRect: {
+        height: number;
+    } | null;
+    getVirtualItems: () => ReadonlyArray<{
+        index: number;
+        start: number;
+        end: number;
+    }>;
+    getVirtualIndexes: () => number[];
+};
+export type PaintedRangeSeekController = {
+    scrollSeekRef: {
+        current: boolean;
+    };
+    warmedStripIndexesRef: {
+        current: Set<number>;
+    };
+    revealFrameRef: {
+        current: number;
+    };
+    scrollSeekTracker: ReturnType<typeof createScrollSeekTracker>;
+    scheduleOverscanReveal: (instance: StripWindow) => void;
+};
+/**
+ * Shared flick → placeholder → staged overscan warmup used by SKU strips and By Item.
+ * Returns true when seek state flips so the painted-range virtualizer can commit.
+ */
+export declare function syncPaintedRangeSeek(controller: PaintedRangeSeekController, instance: StripWindow): boolean;
+/** Strips that intersect the viewport. Overscan stays out of the first card commit. */
+export declare function visibleVirtualIndexes(instance: StripWindow): Set<number>;
+export declare function mergeWarmedStripIndexes(options: {
+    previous: ReadonlySet<number>;
+    visible: ReadonlySet<number>;
+    virtualIndexes: readonly number[];
+}): Set<number>;
+export declare function nextOverscanStripIndexes(options: {
+    warmed: ReadonlySet<number>;
+    virtualIndexes: readonly number[];
+    limit: number;
+}): number[];
+export { OVERSCAN_REVEAL_STRIPS_PER_FRAME };

package/dist/lib/virtualized/scroll-seek.js

@@ -0,0 +1,61 @@
+function l() {
+  let e = 0, t = -1, r = !1, s = 0;
+  return {
+    /** Exponential moving average, px/ms. Zero while the scroller is idle. */
+    get smoothedVelocityPxPerMs() {
+      return s;
+    },
+    update(n) {
+      const i = n.nowMs ?? performance.now(), a = Math.abs(n.scrollOffset - e), f = t < 0 ? 0 : i - t, d = f > 0 && f < 100 ? a / f : 0;
+      return f > 0 && f < 100 && (s = s * 0.65 + d * 0.35), e = n.scrollOffset, t = i, n.isScrolling ? f === 0 || f > 100 ? a >= 180 && (r = !0) : (a >= 180 || d >= 2.5) && (r = !0) : (r = !1, s = 0), r;
+    }
+  };
+}
+const o = 2;
+function _(e, t) {
+  const r = e.scrollSeekTracker.update({
+    scrollOffset: t.scrollOffset ?? 0,
+    isScrolling: t.isScrolling ?? !1
+  }), s = e.scrollSeekRef.current;
+  r ? (e.revealFrameRef.current && cancelAnimationFrame(e.revealFrameRef.current), e.revealFrameRef.current = 0) : s ? (e.warmedStripIndexesRef.current = c(t), e.scheduleOverscanReveal(t)) : e.warmedStripIndexesRef.current.size === 0 ? e.warmedStripIndexesRef.current = new Set(t.getVirtualIndexes()) : (e.warmedStripIndexesRef.current = u({
+    previous: e.warmedStripIndexesRef.current,
+    visible: c(t),
+    virtualIndexes: t.getVirtualIndexes()
+  }), S({
+    warmed: e.warmedStripIndexesRef.current,
+    virtualIndexes: t.getVirtualIndexes(),
+    limit: 1
+  }).length > 0 && e.scheduleOverscanReveal(t));
+  const n = r !== s;
+  return e.scrollSeekRef.current = r, n;
+}
+function c(e) {
+  const t = e.scrollRect?.height ?? 0;
+  if (t <= 0) return new Set(e.getVirtualIndexes());
+  const r = e.scrollOffset ?? 0, s = r + t, n = /* @__PURE__ */ new Set();
+  for (const i of e.getVirtualItems())
+    i.start < s && i.end > r && n.add(i.index);
+  return n;
+}
+function u(e) {
+  const t = new Set(e.virtualIndexes), r = /* @__PURE__ */ new Set();
+  for (const s of e.previous)
+    t.has(s) && r.add(s);
+  for (const s of e.visible) r.add(s);
+  return r;
+}
+function S(e) {
+  const t = [];
+  for (const r of e.virtualIndexes)
+    if (!e.warmed.has(r) && (t.push(r), t.length >= e.limit))
+      break;
+  return t;
+}
+export {
+  o as OVERSCAN_REVEAL_STRIPS_PER_FRAME,
+  l as createScrollSeekTracker,
+  u as mergeWarmedStripIndexes,
+  S as nextOverscanStripIndexes,
+  _ as syncPaintedRangeSeek,
+  c as visibleVirtualIndexes
+};

package/dist/lib/virtualized/usePaintedRangeVirtualizer.d.ts

@@ -0,0 +1,19 @@
+import { Virtualizer } from '@tanstack/virtual-core';
+import { ReactVirtualizerOptions } from '@tanstack/react-virtual';
+export type PaintedRangeVirtualizerOptions<TScrollElement extends Element, TItemElement extends Element> = Omit<ReactVirtualizerOptions<TScrollElement, TItemElement>, "observeElementRect" | "observeElementOffset" | "scrollToFn"> & Partial<Pick<ReactVirtualizerOptions<TScrollElement, TItemElement>, "observeElementRect" | "observeElementOffset" | "scrollToFn">> & {
+    /**
+     * When true, React commits when the painted index window changes.
+     * Pixel scrolling inside that window stays on the compositor.
+     */
+    rerenderWhenPaintedRangeChanges?: boolean;
+    /**
+     * Runs before the React commit. Return true to commit even when the
+     * index window is unchanged (scroll-seek placeholders).
+     */
+    onBeforeRender?: (instance: Virtualizer<TScrollElement, TItemElement>) => boolean | void;
+};
+/**
+ * TanStack Virtual adapter that can skip React commits while a sticky
+ * range-extractor window is unchanged.
+ */
+export declare function usePaintedRangeVirtualizer<TScrollElement extends Element, TItemElement extends Element>(options: PaintedRangeVirtualizerOptions<TScrollElement, TItemElement>): Virtualizer<TScrollElement, TItemElement>;

package/dist/lib/virtualized/usePaintedRangeVirtualizer.js

@@ -0,0 +1,30 @@
+import { elementScroll as p, observeElementOffset as R, observeElementRect as h, Virtualizer as v } from "@tanstack/virtual-core";
+import { useReducer as E, useRef as S, useState as b, useLayoutEffect as f } from "react";
+import { flushSync as O } from "react-dom";
+function $(t) {
+  const e = t.getVirtualIndexes();
+  return e.length === 0 ? `empty:${t.options.count}` : `${e[0]}:${e[e.length - 1]}:${e.length}:${t.options.count}`;
+}
+function z(t) {
+  const {
+    useFlushSync: e = !0,
+    rerenderWhenPaintedRangeChanges: a = !1,
+    onBeforeRender: g,
+    ...n
+  } = t, s = E(() => ({}), {})[1], u = S(""), l = {
+    ...n,
+    observeElementRect: n.observeElementRect ?? h,
+    observeElementOffset: n.observeElementOffset ?? R,
+    scrollToFn: n.scrollToFn ?? p,
+    onChange: (o, i) => {
+      const m = g?.(o) === !0, c = $(o), d = c !== u.current;
+      d && (u.current = c), (!a || d || m) && (e && i ? O(s) : s()), n.onChange?.(o, i);
+    }
+  }, [r] = b(
+    () => new v(l)
+  );
+  return r.setOptions(l), f(() => r._didMount(), [r]), f(() => r._willUpdate()), r;
+}
+export {
+  z as usePaintedRangeVirtualizer
+};

package/dist/lib/virtualized/useResponsiveColumnCount.d.ts

@@ -0,0 +1,35 @@
+import { RefObject } from 'react';
+export type ResponsiveColumnCountInput = {
+    containerWidth: number;
+    minimumColumnWidth: number;
+    columnGap?: number;
+    maximumColumnCount?: number;
+    minimumColumnCount?: number;
+};
+/**
+ * How many equal columns fit in `containerWidth` given a minimum card width and gutter.
+ *
+ * `floor((width + gap) / (minimumColumnWidth + gap))` — the extra gap term lets the last
+ * column sit flush without requiring a trailing gutter.
+ */
+export declare function getResponsiveColumnCount(input: ResponsiveColumnCountInput): number;
+export type UseResponsiveColumnCountOptions = {
+    containerRef: RefObject<Element | null>;
+    minimumColumnWidth: number;
+    columnGap?: number;
+    maximumColumnCount?: number;
+    minimumColumnCount?: number;
+    /**
+     * Changes when the measured element may be replaced, for example a view
+     * toggle that unmounts the scroller. A detached element reports width 0;
+     * that reading is ignored so the last real column count stays in place
+     * until the new element is measured.
+     */
+    observationKey?: string | number | boolean;
+};
+/**
+ * Measures `containerRef` with ResizeObserver and returns how many columns currently fit.
+ * Pair with {@link useVirtualizedList} by virtualizing **strips**:
+ * `rowCount = ceil(itemCount / columnCount)`.
+ */
+export declare function useResponsiveColumnCount(options: UseResponsiveColumnCountOptions): number;

package/dist/lib/virtualized/useResponsiveColumnCount.js

@@ -0,0 +1,51 @@
+import { useState as l, useLayoutEffect as a } from "react";
+function C(m) {
+  const o = Math.max(0, m.columnGap ?? 0), n = Math.max(1, Math.floor(m.minimumColumnCount ?? 1)), u = m.maximumColumnCount === void 0 ? Number.POSITIVE_INFINITY : Math.max(n, Math.floor(m.maximumColumnCount));
+  if (m.containerWidth <= 0 || m.minimumColumnWidth <= 0)
+    return n;
+  const t = Math.floor(
+    (m.containerWidth + o) / (m.minimumColumnWidth + o)
+  );
+  return Math.min(u, Math.max(n, t));
+}
+function c(m) {
+  const [o, n] = l(
+    () => C({
+      containerWidth: m.containerRef.current?.clientWidth ?? 0,
+      minimumColumnWidth: m.minimumColumnWidth,
+      columnGap: m.columnGap,
+      maximumColumnCount: m.maximumColumnCount,
+      minimumColumnCount: m.minimumColumnCount
+    })
+  );
+  return a(() => {
+    const u = m.containerRef.current;
+    if (!u) return;
+    const t = () => {
+      const i = u.clientWidth;
+      i <= 0 || n(
+        C({
+          containerWidth: i,
+          minimumColumnWidth: m.minimumColumnWidth,
+          columnGap: m.columnGap,
+          maximumColumnCount: m.maximumColumnCount,
+          minimumColumnCount: m.minimumColumnCount
+        })
+      );
+    };
+    t();
+    const e = new ResizeObserver(t);
+    return e.observe(u), () => e.disconnect();
+  }, [
+    m.containerRef,
+    m.minimumColumnWidth,
+    m.columnGap,
+    m.maximumColumnCount,
+    m.minimumColumnCount,
+    m.observationKey
+  ]), o;
+}
+export {
+  C as getResponsiveColumnCount,
+  c as useResponsiveColumnCount
+};

package/dist/lib/virtualized/useScrollSeekPaintedRange.d.ts

@@ -0,0 +1,13 @@
+import { StripWindow } from './scroll-seek';
+/**
+ * Owns flick placeholders and staged overscan warmup for a painted-range virtualizer.
+ */
+export declare function useScrollSeekPaintedRange(): {
+    scrollSeekRef: import('react').RefObject<boolean>;
+    warmedStripIndexesRef: import('react').RefObject<Set<number>>;
+    scrollSeekTracker: {
+        readonly smoothedVelocityPxPerMs: number;
+        update(sample: import('./scroll-seek').ScrollSeekSample): boolean;
+    };
+    applyPaintedRangeSeek: (instance: StripWindow) => boolean;
+};

package/dist/lib/virtualized/useScrollSeekPaintedRange.js

@@ -0,0 +1,45 @@
+import { useRef as s, useMemo as d, useState as R, useCallback as m, useEffect as k } from "react";
+import { createScrollSeekTracker as p, syncPaintedRangeSeek as x, nextOverscanStripIndexes as v, OVERSCAN_REVEAL_STRIPS_PER_FRAME as A } from "./scroll-seek.js";
+function I() {
+  const n = s(!1), r = s(/* @__PURE__ */ new Set()), e = s(0), t = d(() => p(), []), [, f] = R(0), o = m((c) => {
+    e.current && cancelAnimationFrame(e.current);
+    const u = () => {
+      if (e.current = 0, n.current) return;
+      const i = v({
+        warmed: r.current,
+        virtualIndexes: c.getVirtualIndexes(),
+        limit: A
+      });
+      if (i.length === 0) return;
+      const l = new Set(r.current);
+      for (const a of i) l.add(a);
+      r.current = l, f((a) => a + 1), e.current = requestAnimationFrame(u);
+    };
+    e.current = requestAnimationFrame(u);
+  }, []);
+  k(() => () => {
+    e.current && cancelAnimationFrame(e.current);
+  }, []);
+  const S = m(
+    (c) => x(
+      {
+        scrollSeekRef: n,
+        warmedStripIndexesRef: r,
+        revealFrameRef: e,
+        scrollSeekTracker: t,
+        scheduleOverscanReveal: o
+      },
+      c
+    ),
+    [o, t]
+  );
+  return {
+    scrollSeekRef: n,
+    warmedStripIndexesRef: r,
+    scrollSeekTracker: t,
+    applyPaintedRangeSeek: S
+  };
+}
+export {
+  I as useScrollSeekPaintedRange
+};

package/dist/lib/virtualized/useVirtualizedList.d.ts

@@ -14,6 +14,13 @@ export type UseVirtualizedListOptions<TData, TScrollElement extends Element = HT
     onEndReached?: () => void;
     /** When false, `onEndReached` is not invoked (e.g. no further pages). */
     hasMore?: boolean;
+    /**
+     * When true, React only commits when the painted index window changes.
+     * Pixel scrolling stays on the compositor until the sticky window remaps.
+     */
+    rerenderWhenPaintedRangeChanges?: boolean;
+    /** Runs before the React commit. Return true to commit anyway. */
+    onBeforeRender?: (instance: Virtualizer<TScrollElement, TItemElement>) => boolean | void;
 } & Omit<Partial<ReactVirtualizerOptions<TScrollElement, TItemElement>>, "count" | "getScrollElement" | "estimateSize" | "overscan" | "getItemKey" | "onChange"> & {
     /** Merged with the internal handler that powers `onEndReached`. */
     onChange?: ReactVirtualizerOptions<TScrollElement, TItemElement>["onChange"];