@candor-ui/react 1.1.0 → 1.5.0

package/dist/lib/use-virtual-list.js

@@ -0,0 +1,124 @@
+import * as React from "react";
+const keyAttr = "data-virtual-key";
+/**
+ * Render only the items of a long list that are in or near view, for Thread's and SessionList's `virtualize`.
+ * Items keep their measured heights by key, so a list that grows or reorders keeps its place; unmeasured items count
+ * as `estimate`. Spacers stand in for the rest. `pin` (an item's key) keeps that item rendered (the one holding
+ * focus), on its own if it's far from view, so focus is never lost to an item scrolling away. Until the scroller is
+ * measured (on the server, on the first render in the browser, and while it's hidden) the first or last `initial`
+ * items render, by `anchor`, so server and browser agree.
+ *
+ * Give each rendered item `ref={list.measure}` and `data-virtual-key={key}`.
+ */
+export function useVirtualList({ enabled, count, keyOf, scroller, estimate = 96, overscan = 800, initial = 20, anchor = "end", gap = () => 0, pin, }) {
+    const [heights, setHeights] = React.useState(() => new Map());
+    const [viewport, setViewport] = React.useState(null);
+    const gapOf = React.useRef(gap);
+    React.useLayoutEffect(() => {
+        gapOf.current = gap;
+    });
+    // One observer for the rendered items, made when the first one mounts; a changed height re-renders.
+    const observer = React.useRef(null);
+    React.useEffect(() => () => {
+        observer.current?.disconnect();
+        observer.current = null;
+    }, []);
+    const measure = React.useCallback((el) => {
+        if (!el)
+            return;
+        if (typeof ResizeObserver !== "undefined")
+            observer.current ??= new ResizeObserver((entries) => {
+                const found = entries.flatMap((e) => {
+                    const key = e.target.getAttribute(keyAttr);
+                    const h = e.target.offsetHeight;
+                    return key !== null && h > 0 ? [[key, h]] : [];
+                });
+                if (found.length)
+                    setHeights((prev) => (found.every(([k, h]) => prev.get(k) === h) ? prev : new Map([...prev, ...found])));
+            });
+        const ro = observer.current;
+        ro?.observe(el);
+        const key = el.getAttribute(keyAttr);
+        const h = el.offsetHeight;
+        if (key !== null && h > 0)
+            setHeights((prev) => (prev.get(key) === h ? prev : new Map(prev).set(key, h)));
+        // An item that unmounts stops being observed, so it can be collected.
+        return () => ro?.unobserve(el);
+    }, []);
+    React.useLayoutEffect(() => {
+        const el = scroller.current;
+        if (!enabled || !el)
+            return;
+        const pending = { frame: 0 };
+        const read = () => {
+            pending.frame = 0;
+            const g = gapOf.current();
+            setViewport((v) => (v && v.top === el.scrollTop && v.height === el.clientHeight && v.gap === g ? v : { top: el.scrollTop, height: el.clientHeight, gap: g }));
+        };
+        const later = () => {
+            if (!pending.frame)
+                pending.frame = requestAnimationFrame(read);
+        };
+        read();
+        el.addEventListener("scroll", later, { passive: true });
+        const ro = typeof ResizeObserver === "undefined" ? null : new ResizeObserver(later);
+        ro?.observe(el);
+        return () => {
+            el.removeEventListener("scroll", later);
+            ro?.disconnect();
+            cancelAnimationFrame(pending.frame);
+        };
+    }, [enabled, scroller]);
+    if (!enabled)
+        return { rows: Array.from({ length: count }, (_, index) => ({ index })), measure };
+    const g = viewport?.gap ?? 0;
+    const size = (i) => heights.get(String(keyOf(i))) ?? estimate;
+    const tops = [];
+    let y = 0;
+    for (let i = 0; i < count; i++) {
+        tops.push(y);
+        y += size(i) + g;
+    }
+    const total = Math.max(0, y - g);
+    let start;
+    let end;
+    if (!viewport || viewport.height === 0) {
+        start = anchor === "end" ? Math.max(0, count - initial) : 0;
+        end = anchor === "end" ? count : Math.min(count, initial);
+    }
+    else {
+        const lo = viewport.top - overscan;
+        const hi = viewport.top + viewport.height + overscan;
+        start = 0;
+        while (start < count - 1 && tops[start] + size(start) < lo)
+            start++;
+        end = start;
+        while (end < count && tops[end] <= hi)
+            end++;
+        end = Math.max(end, Math.min(count, start + 1));
+    }
+    // The pinned item and its neighbours (so Tab and Shift+Tab reach the next and previous item) render with the window,
+    // or on their own between spacers when they're far from it.
+    let ranges = [[start, end]];
+    const p = pin == null ? -1 : Array.from({ length: count }, (_, i) => i).find((i) => String(keyOf(i)) === pin) ?? -1;
+    if (p >= 0) {
+        const island = [Math.max(0, p - 1), Math.min(count, p + 2)];
+        ranges = island[1] < start ? [island, [start, end]] : island[0] > end ? [[start, end], island] : [[Math.min(start, island[0]), Math.max(end, island[1])]];
+    }
+    // A spacer stands where its items were; the gaps the layout puts beside it account for theirs.
+    const rows = [];
+    let prevEnd = 0;
+    for (const [a, b] of ranges) {
+        if (a > 0) {
+            const height = prevEnd === 0 ? tops[a] - g : tops[a] - (tops[prevEnd - 1] + size(prevEnd - 1)) - 2 * g;
+            if (a > prevEnd)
+                rows.push({ spacer: Math.max(0, height), key: `spacer-${prevEnd}` });
+        }
+        for (let i = a; i < b; i++)
+            rows.push({ index: i });
+        prevEnd = b;
+    }
+    if (prevEnd < count)
+        rows.push({ spacer: Math.max(0, total - tops[prevEnd]), key: `spacer-${prevEnd}` });
+    return { rows, measure };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@candor-ui/react",
-  "version": "1.1.0",
+  "version": "1.5.0",
   "description": "Candor UI's free tier as an npm package: React components for agents that do real work, on shadcn/ui and Tailwind 4.",
   "license": "MIT",
   "author": "Methodic LLC",