@particle-academy/react-fancy 5.33.0 → 5.34.0

package/dist/virtual-list.d.ts

@@ -0,0 +1,125 @@
+import * as react from 'react';
+import { HTMLAttributes, ReactNode, Ref } from 'react';
+
+/**
+ * The one thing `VirtualList` requires of a row: a stable id.
+ *
+ * It is required rather than derived from the array index because every feature
+ * here outlives a reindex — `scrollToId` resolves a deep link after rows have
+ * been prepended, and a measured height must follow its row rather than its
+ * position.
+ */
+interface VirtualListRow {
+    id: string;
+}
+interface VirtualListProps<T extends VirtualListRow> extends Omit<HTMLAttributes<HTMLDivElement>, "children" | "onScroll"> {
+    /** The full list. Only the visible window is ever rendered. */
+    items: readonly T[];
+    /** Render one row. Called only for rows inside the window. */
+    renderRow: (item: T, index: number) => ReactNode;
+    /**
+     * Height of the scroll viewport. A number is also used as the viewport height
+     * for windowing before the element has been measured, so prefer one when you
+     * know it — `"100%"` works, it just renders a conservative first window.
+     */
+    height?: number | string;
+    /**
+     * Seed height for rows that have not been measured yet. Only affects rows
+     * never rendered: a row's real height replaces it the moment it is on screen.
+     * Pick the common case, not the average.
+     */
+    estimateRowHeight?: number;
+    /** Rows to render beyond each edge of the viewport. */
+    overscan?: number;
+    /**
+     * Stick to the bottom as rows arrive. **Controlled** — this component never
+     * flips it on its own, so an agent can read and write the follow state
+     * through a bridge. Pair it with {@link onFollowChange}.
+     */
+    followTail?: boolean;
+    /**
+     * The list asking to change {@link followTail}: `false` the instant the human
+     * scrolls up, `true` when they return to the bottom. Honour it by updating
+     * your own state — until you do, nothing changes.
+     */
+    onFollowChange?: (following: boolean) => void;
+    /**
+     * How many rows have arrived since tail-following stopped. Drives a
+     * `↓ n new` pill, which is yours to render. Always `0` while following.
+     */
+    onUnseenChange?: (count: number) => void;
+    /**
+     * Put the row with this id at the top of the viewport — the `?at=<rowId>`
+     * deep link. Resolution is not instant for a row far down an unmeasured list:
+     * the target settles as the rows above it are measured. See
+     * {@link onScrollToIdResolved}.
+     */
+    scrollToId?: string | null;
+    /**
+     * Fired once the component has stopped moving for a given `scrollToId`.
+     * `landed` is `false` when the id is not in `items` — a deep link to a pruned
+     * row, which must be distinguishable from a successful scroll to the top.
+     */
+    onScrollToIdResolved?: (id: string, landed: boolean) => void;
+    /** The scroll viewport element. */
+    ref?: Ref<HTMLDivElement>;
+}
+
+/**
+ * A windowed list for ledgers that run to tens of thousands of rows — only the
+ * visible slice is in the DOM, with **measured** variable row heights, deep
+ * links by row id, and sticky-bottom tail-following.
+ *
+ * Built for an agent event stream, where every one of those three is load
+ * bearing at once: message rows wrap and event rows do not, a link carries
+ * `?at=<rowId>` to the exact row under discussion, and new rows arrive while
+ * the human is reading older ones.
+ *
+ * ## Heights are measured, never predicted
+ *
+ * `estimateRowHeight` only seeds rows that have never been on screen. The
+ * moment a row renders, its real height is measured and replaces the estimate,
+ * and every offset after it moves. The alternative — a `rowHeight(item)`
+ * callback — is a prediction about text wrapping, font loading and container
+ * width, and when it is wrong the error accumulates down the list: rows draw in
+ * the wrong place and `scrollToId` lands on a neighbour. Measuring is slower to
+ * settle and correct when it does.
+ *
+ * ## Tail-follow breaks on INTENT, not on position
+ *
+ * Any upward gesture — wheel, drag, PageUp, Home — stops following
+ * immediately, even when the list is still pinned to the bottom and
+ * `scrollTop` has not changed yet. Position cannot tell "the human scrolled
+ * up" from "content grew downward", so a position-only implementation keeps
+ * following through a wheel-up and yanks the reader back on the next append.
+ *
+ * ## It is controlled
+ *
+ * `followTail` is the consumer's state. This component only ever *asks* via
+ * `onFollowChange`, so the follow state is readable and writable by an agent
+ * over a bridge, as the Human+ component contract requires. The `↓ n new` pill
+ * is the consumer's to render, from `onUnseenChange`.
+ *
+ * @example
+ * ```tsx
+ * const [following, setFollowing] = useState(true);
+ * const [unseen, setUnseen] = useState(0);
+ *
+ * <VirtualList
+ *   items={events}
+ *   renderRow={(e) => <StreamRow event={e} />}
+ *   height="100%"
+ *   estimateRowHeight={28}
+ *   followTail={following}
+ *   onFollowChange={setFollowing}
+ *   onUnseenChange={setUnseen}
+ *   scrollToId={params.at}
+ * />
+ * {!following && unseen > 0 && (
+ *   <Button onClick={() => setFollowing(true)}>↓ {unseen} new</Button>
+ * )}
+ * ```
+ */
+declare function VirtualList<T extends VirtualListRow>({ items, renderRow, height, estimateRowHeight, overscan, followTail, onFollowChange, onUnseenChange, scrollToId, onScrollToIdResolved, className, ref, ...props }: VirtualListProps<T>): react.JSX.Element;
+
+export { VirtualList, type VirtualListProps, type VirtualListRow };

package/dist/virtual-list.js

@@ -0,0 +1,4 @@
+export { VirtualList } from './chunk-Z4CW3U6C.js';
+import './chunk-MMW2JGKZ.js';
+//# sourceMappingURL=virtual-list.js.map
+//# sourceMappingURL=virtual-list.js.map

package/dist/virtual-list.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"virtual-list.js"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@particle-academy/react-fancy",
-  "version": "5.33.0",
+  "version": "5.34.0",
   "description": "React UI component library for Human+ UX — controlled, agent-bridgeable primitives",
   "repository": {
     "type": "git",
@@ -423,6 +423,26 @@
         "default": "./dist/image-viewer.cjs"
       }
     },
+    "./activity-light": {
+      "import": {
+        "types": "./dist/activity-light.d.ts",
+        "default": "./dist/activity-light.js"
+      },
+      "require": {
+        "types": "./dist/activity-light.d.cts",
+        "default": "./dist/activity-light.cjs"
+      }
+    },
+    "./virtual-list": {
+      "import": {
+        "types": "./dist/virtual-list.d.ts",
+        "default": "./dist/virtual-list.js"
+      },
+      "require": {
+        "types": "./dist/virtual-list.d.cts",
+        "default": "./dist/virtual-list.cjs"
+      }
+    },
     "./index-list": {
       "import": {
         "types": "./dist/index-list.d.ts",
@@ -982,7 +1002,8 @@
   "overrides": {
     "esbuild": "^0.28.1",
     "brace-expansion": "^5.0.12",
-    "undici": "^7.29.1"
+    "undici": "^7.29.1",
+    "source-map-js": "^1.2.2"
   },
   "engines": {
     "node": ">=22"