@particle-academy/react-fancy 5.70.1 → 5.71.1

package/docs/ChatThread.md

@@ -0,0 +1,318 @@
+# ChatThread
+
+A controlled message list for agent and support conversations: chat with an
+agent in a side panel, a ticket thread with internal notes, an admin chat whose
+agent drafts proposals for a human to approve. `ChatMessage` is the single
+message, usable on its own.
+
+Added in `5.71.0`.
+
+## Import
+
+```tsx
+import { ChatThread, ChatMessage } from "@particle-academy/react-fancy";
+// or the subpath
+import { ChatThread } from "@particle-academy/react-fancy/chat-thread";
+```
+
+## Basic usage
+
+```tsx
+const [messages, setMessages] = useState<ChatMessageData[]>([]);
+
+<ChatThread
+  className="h-full"
+  messages={messages}
+  composer={
+    <Composer
+      onSubmit={async (text) => {
+        const res = await send(text); // the server appends the message
+        if (!res.ok) return { ok: false, error: res.error };
+      }}
+    />
+  }
+/>
+```
+
+The thread renders exactly `messages`, oldest first. It owns no message state.
+It does not ship an input: put `Composer` or `PromptInput` in the `composer`
+slot. Both have acknowledged send (5.70.0), so the draft stays until your
+`onSubmit` Promise resolves.
+
+## Messages are JSON
+
+```ts
+interface ChatMessageData {
+  id: string;                      // data-chat-message
+  role: "user" | "assistant" | "system" | "agent" | "staff" | "customer" | string;
+  author?: { name: string; avatar?: string };
+  content: string;                 // markdown, always sanitised
+  format?: "markdown" | "text";    // "text" renders literally
+  createdAt: string | number;      // ISO 8601 or epoch ms
+  status?: "pending" | "streaming" | "sent" | "failed";   // default "sent"
+  visibility?: "public" | "internal";                      // default "public"
+  attachments?: { id: string; name: string; url?: string; mimeType?: string; size?: number }[];
+  proposal?: { id: string; title?: string; state?: "pending" | "accepted" | "rejected" | "withdrawn";
+               acceptLabel?: string; rejectLabel?: string };
+  own?: boolean;                   // default: ownRoles.includes(role)
+  meta?: Record<string, unknown>;  // carried, never rendered
+}
+```
+
+- **Content** goes through `ContentRenderer` with sanitisation on. There is no
+  `unsafe` prop on the thread, on purpose: message bodies are text the host did
+  not author. `contentOptions` passes `extensions`, `copyButtons`, `onCopy`,
+  `clipboardWriter` and `lineSpacing` through.
+- **Streaming.** A message with `status: "streaming"` renders with
+  `ContentRenderer`'s `streaming`: by default an unfinished code fence or tag is
+  held back until it closes. `streaming="progressive"` on the thread shows it
+  as it fills. The message is `aria-busy` while it streams, so screen readers
+  are not read every token. Set the status to `"sent"` when the stream ends.
+- **Roles.** The six named roles get default labels. Any other string is
+  carried verbatim on `data-chat-role` and rendered neutrally. `system` renders
+  as a centred line.
+- **Own messages** align to the end. `ownRoles` (default `["user"]`) decides
+  which; `own` on a message overrides it. A support staff view passes
+  `ownRoles={["staff"]}`, or sets `own` per message to distinguish colleagues.
+- **Attachments** render as links (unsafe schemes render the name without a
+  link). They are never loaded inline. `renderAttachment` replaces one.
+
+## Internal notes
+
+`visibility: "internal"` renders a dashed amber bubble with a visible
+"Internal note" label (`[data-chat-internal-label]`) on every internal message.
+
+**The thread never decides visibility.** It renders exactly what it is given.
+Filter on the server (and in the transformer) and pass only what this viewer
+may see. A component that hid internal notes itself would be a second policy
+nobody tests.
+
+## Proposals (approval cards)
+
+A message with a `proposal` is an agent's suggested action awaiting a human: a
+drafted reply, a field change, a page edit. Its `content` is the draft.
+
+```tsx
+<ChatThread
+  messages={messages}
+  onProposalAccept={(m) => api.decide(m.proposal!.id, "accept", m.meta?.version)}
+  onProposalReject={(m) => openRejectReasonDialog(m)}
+/>
+```
+
+- Stable handle `[data-chat-proposal="<proposal id>"]` with
+  `data-chat-proposal-state`; buttons are
+  `[data-chat-proposal-action="accept" | "reject"]`.
+- **It never acts on its own.** Nothing is called on render. The state is the
+  host's: buttons show only while `state` is `"pending"` (the default) and only
+  for the callbacks you pass. When the host moves the card to `accepted`,
+  `rejected` or `withdrawn`, the buttons are replaced by a status badge.
+- **Acknowledged.** Return a Promise and both buttons are disabled
+  (`aria-busy`) until it settles; a second decision is refused even within the
+  same event batch. A rejection goes to `onActionError(error, action)`; without
+  it the rejection is left unhandled so it still reaches the console.
+- "Edit then approve" and "reject with a reason" are host UI: open your editor
+  or dialog from the callback, or from the actions slot.
+
+## Scrolling: stick to the bottom without yanking
+
+- The thread starts at the bottom and follows new messages, and a streaming
+  message as it grows, **only while the reader is at the bottom**
+  (`bottomThreshold`, default 48px).
+- A reader who scrolled up stays exactly where they are. An
+  "N new messages" control (`[data-react-fancy-chat-thread-jump]`,
+  `data-unseen`) appears; it jumps to the latest and moves focus to the log.
+- The viewer's own new message (see `ownRoles`) always scrolls into view.
+- Prepending earlier messages keeps the message under the reader in place.
+- **Only the log's own `scrollTop` is ever set.** The thread never calls
+  `scrollIntoView`, and it focuses with `{ preventScroll: true }`, so no
+  ancestor and never the page scrolls (the rule `PromptInput` adopted in 5.69.0
+  for genie#1290).
+- `stickToBottom={false}` turns following off entirely.
+- `onAtBottomChange(atBottom)` reports the reader arriving at or leaving the
+  bottom.
+
+### Imperative handle
+
+```tsx
+const thread = useRef<ChatThreadHandle>(null);
+<ChatThread ref={thread} messages={messages} />;
+
+thread.current?.scrollToLatest();
+thread.current?.scrollToMessage("msg_42"); // false if not rendered
+thread.current?.element;                   // the log element
+```
+
+## Load earlier
+
+```tsx
+<ChatThread
+  messages={messages}
+  hasEarlier={cursor !== null}
+  onLoadEarlier={async () => {
+    const page = await api.history(cursor);
+    setMessages((m) => [...page.items, ...m]);
+    setCursor(page.next);
+  }}
+/>
+```
+
+The control shows while `onLoadEarlier` is set and `hasEarlier` is not
+`false`. A returned Promise disables it until it settles; `loadingEarlier`
+drives the same state from the host.
+
+## Day separators and grouping
+
+```tsx
+<ChatThread messages={messages} separators="day" groupConsecutive />
+```
+
+- `separators="day"` inserts `[data-chat-day-separator="YYYY-MM-DD"]` at each
+  local calendar-day change. `formatDay` formats the label.
+- `groupConsecutive` merges consecutive messages from the same role and author
+  within 5 minutes (or pass a window in ms): the header and avatar show once
+  and later messages carry `data-chat-grouped`. Internal and public messages
+  never merge, and neither do proposals or system lines.
+
+## Per-message actions
+
+```tsx
+<ChatThread
+  messages={messages}
+  renderActions={(m) =>
+    m.role === "assistant" ? (
+      <Button size="xs" variant="ghost" icon="copy" onClick={() => copy(m.content)}>Copy</Button>
+    ) : m.status === "failed" ? (
+      <Button size="xs" variant="ghost" onClick={() => retry(m)}>Retry</Button>
+    ) : null
+  }
+/>
+```
+
+The slot renders in `[data-chat-message-actions]`; return `null` for none.
+
+## Human+
+
+- **Controlled.** `messages` is the state. Loading history and deciding a
+  proposal are callbacks; the thread holds only view state (scroll position,
+  the unseen count).
+- **Stable handles.** `data-react-fancy-chat-thread`,
+  `data-chat-message="<id>"` with `data-chat-role`, `data-chat-status`,
+  `data-chat-visibility`, and `data-chat-proposal="<id>"`.
+- **Observable activity.** `onActivity` receives every interaction:
+
+  ```ts
+  type ChatThreadActivity =
+    | { type: "load-earlier" }
+    | { type: "proposal-accept"; messageId: string; proposalId: string }
+    | { type: "proposal-reject"; messageId: string; proposalId: string }
+    | { type: "jump-to-latest"; unseen: number };
+  ```
+
+  Map it onto fancy-auto-common's `AutoActivityEvent` in the host, as with
+  `JsonEditor`'s `onActivity`.
+- **Trust but verify.** Proposals are the staged-write affordance: the agent
+  proposes, the human decides.
+- **Bridgeable.** A bridge reads and writes the same JSON the host renders
+  (`messages`, proposal decisions). The thread itself adds nothing an agent
+  has to scrape.
+
+## Accessibility
+
+- The log is `role="log"`, `aria-live="polite"`, `aria-relevant="additions"`,
+  focusable (`tabIndex=0`) so it can be scrolled from the keyboard.
+- It is labelled by `heading` (rendered as `h2`, or `headingLevel`), or by
+  `labels.log` ("Conversation") when there is no heading.
+- Every string is in `labels` for translation, including role names and the
+  "N new messages" text.
+
+## Layouts
+
+### Side panel (Charlotte)
+
+```tsx
+<ResizablePanels defaultValue={68} label="Resize the chat panel">
+  <Editor value={session.state.doc} onOp={session.applyHuman} />
+  <ChatThread
+    className="h-full"
+    heading="Charlotte"
+    headingLevel={2}
+    messages={session.messages}           // reduced from the event log
+    streaming="progressive"
+    ownRoles={["user"]}
+    groupConsecutive
+    onProposalAccept={(m) => session.accept(m.proposal!.id)}
+    onProposalReject={(m) => session.reject(m.proposal!.id)}
+    onActivity={(e) => activity.emit(toAutoActivity(e))}
+    renderActions={(m) => m.role === "assistant" && m.status === "sent" ? <CopyButton text={m.content} /> : null}
+    composer={
+      <PromptInput
+        placeholder="Ask Charlotte to change the page..."
+        sendDisabled={session.running}
+        onSubmit={(text) => session.send(text)}
+      />
+    }
+  />
+</ResizablePanels>
+```
+
+### Ticket thread (support)
+
+```tsx
+<ChatThread
+  className="h-full"
+  heading={`${ticket.reference}: ${ticket.subject}`}
+  messages={ticket.messages}              // the server already filtered internal notes for customers
+  ownRoles={["staff"]}
+  separators="day"
+  hasEarlier={ticket.hasEarlier}
+  onLoadEarlier={() => loadEarlier(ticket.reference)}
+  onProposalAccept={(m) => cards.approve(m.proposal!.id, m.meta?.version as number)}
+  onProposalReject={(m) => cards.openReject(m.proposal!.id)}
+  onActionError={(err) => toast.error(String(err))}
+  composer={
+    <Composer
+      actions={<MultiSwitch value={mode} onValueChange={setMode} list={[{ value: "public", label: "Reply" }, { value: "internal", label: "Internal note" }]} />}
+      onSubmit={(text) => postMessage(ticket.reference, { text, visibility: mode })}
+    />
+  }
+/>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| messages | `ChatMessageData[]` | - | The messages, oldest first. Required |
+| heading | `ReactNode` | - | Visible title; the log is labelled by it |
+| headingLevel | `2 \| 3 \| 4 \| 5 \| 6` | `2` | Heading element |
+| composer | `ReactNode` | - | Rendered below the log (`Composer` / `PromptInput`) |
+| renderActions | `(m) => ReactNode` | - | Per-message actions slot |
+| onLoadEarlier | `() => void \| Promise` | - | Shows the load-earlier control |
+| hasEarlier | `boolean` | `true` with `onLoadEarlier` | Hide the control when there is nothing earlier |
+| loadingEarlier | `boolean` | `false` | Host-driven busy state for the control |
+| onProposalAccept / onProposalReject | `(m) => void \| Promise` | - | Proposal decisions |
+| onActionError | `(error, action) => void` | - | A returned Promise rejected |
+| onActivity | `(e: ChatThreadActivity) => void` | - | Every interaction |
+| stickToBottom | `boolean` | `true` | Follow new messages while at the bottom |
+| bottomThreshold | `number` | `48` | Pixels from the bottom that count as "at the bottom" |
+| onAtBottomChange | `(atBottom) => void` | - | The reader arrived at / left the bottom |
+| separators | `"none" \| "day"` | `"none"` | Day separators |
+| formatDay / formatTime | `(d: Date) => string` | locale | Date and time labels |
+| groupConsecutive | `boolean \| number` | `false` | Merge consecutive messages (5 min, or ms) |
+| ownRoles | `string[]` | `["user"]` | Roles aligned as the viewer's own |
+| streaming | `true \| "progressive"` | `true` | How a streaming message renders its tail |
+| contentOptions | `ChatContentOptions` | - | Passed to every `ContentRenderer` (no `unsafe`) |
+| renderAttachment | `(a, m) => ReactNode` | - | Replace one attachment's rendering |
+| empty | `ReactNode` | - | Shown when there are no messages |
+| labels | `Partial<ChatThreadLabels>` | English | Every visible string |
+| classNames | `ChatThreadClassNames` | - | `root`, `heading`, `log`, `composer`, `separator`, `jump`, `message`, `bubble`, `header`, `actions`, `proposal` |
+| ref | `Ref<ChatThreadHandle>` | - | `scrollToLatest`, `scrollToMessage`, `element` |
+
+Other HTML attributes (including `data-*`) go on the root; `onScroll` is
+forwarded from the log, which is the element that scrolls.
+
+`ChatMessage` takes `message`, `actions`, `grouped` and the same display props
+(`ownRoles`, `streaming`, `contentOptions`, `labels`, `formatTime`,
+`renderAttachment`, the proposal callbacks, `onActivity`, `onActionError`,
+`classNames`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@particle-academy/react-fancy",
-  "version": "5.70.1",
+  "version": "5.71.1",
   "description": "React UI component library for Human+ UX — controlled, agent-bridgeable primitives",
   "repository": {
     "type": "git",
@@ -173,6 +173,16 @@
         "default": "./dist/chat-drawer.cjs"
       }
     },
+    "./chat-thread": {
+      "import": {
+        "types": "./dist/chat-thread.d.ts",
+        "default": "./dist/chat-thread.js"
+      },
+      "require": {
+        "types": "./dist/chat-thread.d.cts",
+        "default": "./dist/chat-thread.cjs"
+      }
+    },
     "./checkbox": {
       "import": {
         "types": "./dist/checkbox.d.ts",

package/dist/chunk-IR6JSQ4O.cjs.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/components/VirtualList/VirtualList.tsx"],"names":["useRef","useState","useCallback","useMemo","useEffect","useLayoutEffect","jsx","cn"],"mappings":"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","file":"chunk-IR6JSQ4O.cjs","sourcesContent":["import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from \"react\";\nimport type { KeyboardEvent, TouchEvent, WheelEvent } from \"react\";\nimport { cn } from \"../../utils/cn\";\nimport type { VirtualListProps, VirtualListRow } from \"./VirtualList.types\";\n\n/**\n * A windowed list for ledgers that run to tens of thousands of rows — only the\n * visible slice is in the DOM, with **measured** variable row heights, deep\n * links by row id, and sticky-bottom tail-following.\n *\n * Built for an agent event stream, where every one of those three is load\n * bearing at once: message rows wrap and event rows do not, a link carries\n * `?at=<rowId>` to the exact row under discussion, and new rows arrive while\n * the human is reading older ones.\n *\n * ## Heights are measured, never predicted\n *\n * `estimateRowHeight` only seeds rows that have never been on screen. The\n * moment a row renders, its real height is measured and replaces the estimate,\n * and every offset after it moves. The alternative — a `rowHeight(item)`\n * callback — is a prediction about text wrapping, font loading and container\n * width, and when it is wrong the error accumulates down the list: rows draw in\n * the wrong place and `scrollToId` lands on a neighbour. Measuring is slower to\n * settle and correct when it does.\n *\n * ## Tail-follow breaks on INTENT, not on position\n *\n * Any upward gesture — wheel, drag, PageUp, Home — stops following\n * immediately, even when the list is still pinned to the bottom and\n * `scrollTop` has not changed yet. Position cannot tell \"the human scrolled\n * up\" from \"content grew downward\", so a position-only implementation keeps\n * following through a wheel-up and yanks the reader back on the next append.\n *\n * ## It is controlled\n *\n * `followTail` is the consumer's state. This component only ever *asks* via\n * `onFollowChange`, so the follow state is readable and writable by an agent\n * over a bridge, as the Human+ component contract requires. The `↓ n new` pill\n * is the consumer's to render, from `onUnseenChange`.\n *\n * @example\n * ```tsx\n * const [following, setFollowing] = useState(true);\n * const [unseen, setUnseen] = useState(0);\n *\n * <VirtualList\n *   items={events}\n *   renderRow={(e) => <StreamRow event={e} />}\n *   height=\"100%\"\n *   estimateRowHeight={28}\n *   followTail={following}\n *   onFollowChange={setFollowing}\n *   onUnseenChange={setUnseen}\n *   scrollToId={params.at}\n * />\n * {!following && unseen > 0 && (\n *   <Button onClick={() => setFollowing(true)}>↓ {unseen} new</Button>\n * )}\n * ```\n */\nexport function VirtualList<T extends VirtualListRow>({\n  items,\n  renderRow,\n  height = \"100%\",\n  estimateRowHeight = 32,\n  overscan = 6,\n  followTail = false,\n  onFollowChange,\n  onUnseenChange,\n  scrollToId = null,\n  onScrollToIdResolved,\n  className,\n  ref,\n  ...props\n}: VirtualListProps<T>) {\n  const viewportRef = useRef<HTMLDivElement | null>(null);\n  const windowRef = useRef<HTMLDivElement | null>(null);\n\n  /** Measured heights by row id, so a height follows its row across a reindex. */\n  const heights = useRef(new Map<string, number>());\n  /** Bumped when a measurement actually changed, to recompute offsets. */\n  const [measured, setMeasured] = useState(0);\n\n  const [scrollTop, setScrollTop] = useState(0);\n  const [clientHeight, setClientHeight] = useState(0);\n\n  const attachViewport = useCallback(\n    (el: HTMLDivElement | null) => {\n      viewportRef.current = el;\n      if (typeof ref === \"function\") ref(el);\n      else if (ref) (ref as { current: HTMLDivElement | null }).current = el;\n    },\n    [ref],\n  );\n\n  // A number `height` IS the viewport height, and is usable before the element\n  // has been measured. Without one, render a conservative first window so there\n  // is something on screen for the measurement pass to work from.\n  const viewport =\n    clientHeight > 0 ? clientHeight : typeof height === \"number\" ? height : estimateRowHeight * 20;\n\n  /**\n   * Prefix sums of row heights: `offsets[i]` is where row `i` starts, and the\n   * last entry is the total. Rebuilt whenever rows or measurements change —\n   * O(n) once per change, against O(log n) per scroll from the binary search,\n   * rather than O(n) on every scroll frame.\n   */\n  const { offsets, total } = useMemo(() => {\n    const offs = new Float64Array(items.length + 1);\n    for (let i = 0; i < items.length; i += 1) {\n      offs[i + 1] = offs[i] + (heights.current.get(items[i].id) ?? estimateRowHeight);\n    }\n\n    return { offsets: offs, total: items.length === 0 ? 0 : offs[items.length] };\n  }, [items, measured, estimateRowHeight]);\n\n  /** First row whose span contains `y`. */\n  const indexAt = useCallback(\n    (y: number): number => {\n      let lo = 0;\n      let hi = items.length - 1;\n      while (lo < hi) {\n        const mid = (lo + hi + 1) >> 1;\n        if (offsets[mid] <= y) lo = mid;\n        else hi = mid - 1;\n      }\n\n      return Math.max(0, lo);\n    },\n    [items.length, offsets],\n  );\n\n  const start = Math.max(0, indexAt(scrollTop) - overscan);\n  const end = Math.min(items.length, indexAt(scrollTop + viewport) + 1 + overscan);\n  const visible = useMemo(() => items.slice(start, end), [items, start, end]);\n\n  // ---------------------------------------------------------------- measuring\n\n  const observer = useRef<ResizeObserver | null>(null);\n\n  useEffect(() => {\n    // Absent in jsdom and in older runtimes. Without it the list still measures\n    // on every render; it just does not notice a row reflowing in place.\n    if (typeof ResizeObserver === \"undefined\") return;\n\n    const ro = new ResizeObserver(() => setMeasured((v) => v + 1));\n    observer.current = ro;\n\n    return () => {\n      ro.disconnect();\n      observer.current = null;\n    };\n  }, []);\n\n  // No dependency array on purpose: every render re-measures what is on screen,\n  // and the `changed` guard is what stops it looping. A render that learns\n  // nothing new sets no state.\n  useLayoutEffect(() => {\n    const win = windowRef.current;\n    if (!win) return;\n\n    let changed = false;\n    for (const el of Array.from(win.children) as HTMLElement[]) {\n      const id = el.getAttribute(ROW_ID_ATTR);\n      if (id === null) continue;\n\n      observer.current?.observe(el);\n\n      const h = el.getBoundingClientRect().height;\n      // A zero height is \"not laid out yet\", not a 0px row. Recording it would\n      // collapse the list and make every offset after it wrong.\n      if (h > 0 && heights.current.get(id) !== h) {\n        heights.current.set(id, h);\n        changed = true;\n      }\n    }\n\n    const vp = viewportRef.current;\n    if (vp && vp.clientHeight > 0 && vp.clientHeight !== clientHeight) setClientHeight(vp.clientHeight);\n\n    if (changed) setMeasured((v) => v + 1);\n  });\n\n  // ------------------------------------------------------------- deep linking\n\n  /** The target this component last moved to, to detect that it has settled. */\n  const anchored = useRef<number | null>(null);\n  const resolved = useRef<string | null>(null);\n\n  useEffect(() => {\n    // A new id is a new request, even if the old one had resolved.\n    anchored.current = null;\n    resolved.current = null;\n  }, [scrollToId]);\n\n  useLayoutEffect(() => {\n    if (scrollToId === null || resolved.current === scrollToId) return;\n\n    const index = items.findIndex((item) => item.id === scrollToId);\n    if (index < 0) {\n      // A link to a row that is no longer in the list. Leaving the viewport\n      // where it is and SAYING SO is the only honest outcome — scrolling to the\n      // top would be indistinguishable from a successful landing.\n      resolved.current = scrollToId;\n      onScrollToIdResolved?.(scrollToId, false);\n\n      return;\n    }\n\n    const vp = viewportRef.current;\n    if (!vp) return;\n\n    // Clamped the way the browser clamps: a row inside the final viewport-height\n    // of the list cannot be brought to the top, and pretending otherwise would\n    // leave this waiting for a position that can never be reached.\n    const target = Math.max(0, Math.min(offsets[index], Math.max(0, total - viewport)));\n\n    if (anchored.current !== target) {\n      anchored.current = target;\n      vp.scrollTop = target;\n      setScrollTop(target);\n\n      return;\n    }\n\n    // The target stopped moving as rows above it were measured, and we are on\n    // it. Only now is the deep link actually honoured.\n    if (Math.abs(vp.scrollTop - target) <= 1) {\n      resolved.current = scrollToId;\n      onScrollToIdResolved?.(scrollToId, true);\n    }\n  });\n\n  // ------------------------------------------------------------- tail-follow\n\n  const reportedFollow = useRef(followTail);\n  const programmatic = useRef(false);\n\n  useEffect(() => {\n    // The prop is the truth, so adopt it rather than remembering what we asked\n    // for. Otherwise a consumer that declines an `onFollowChange(false)` would\n    // never be asked again.\n    reportedFollow.current = followTail;\n  }, [followTail]);\n\n  const askFollow = useCallback(\n    (next: boolean) => {\n      if (reportedFollow.current === next) return;\n      reportedFollow.current = next;\n      onFollowChange?.(next);\n    },\n    [onFollowChange],\n  );\n\n  useLayoutEffect(() => {\n    if (!followTail) return;\n    // A pending deep link wins while it resolves; otherwise the two would fight\n    // over the same scrollTop and the link would lose.\n    if (scrollToId !== null && resolved.current !== scrollToId) return;\n\n    const vp = viewportRef.current;\n    if (!vp) return;\n\n    const bottom = Math.max(0, total - viewport);\n    if (Math.abs(vp.scrollTop - bottom) > 0.5) {\n      programmatic.current = true;\n      vp.scrollTop = bottom;\n      setScrollTop(bottom);\n    }\n  });\n\n  const onScroll = useCallback(() => {\n    const vp = viewportRef.current;\n    if (!vp) return;\n\n    const next = vp.scrollTop;\n    const previous = scrollTop;\n    setScrollTop(next);\n\n    const bottom = Math.max(0, total - viewport);\n    const wasProgrammatic = programmatic.current;\n    programmatic.current = false;\n\n    if (next <= bottom - BOTTOM_SLACK) {\n      // Moved up, and not because we moved it.\n      if (!wasProgrammatic && next < previous) askFollow(false);\n    } else {\n      askFollow(true);\n    }\n  }, [scrollTop, total, viewport, askFollow]);\n\n  /** Any upward gesture is a statement of intent, whatever scrollTop says. */\n  const onWheel = useCallback(\n    (e: WheelEvent<HTMLDivElement>) => {\n      if (e.deltaY < 0) askFollow(false);\n    },\n    [askFollow],\n  );\n\n  const onKeyDown = useCallback(\n    (e: KeyboardEvent<HTMLDivElement>) => {\n      if (UPWARD_KEYS.has(e.key)) askFollow(false);\n    },\n    [askFollow],\n  );\n\n  const touchStart = useRef<number | null>(null);\n\n  const onTouchStart = useCallback((e: TouchEvent<HTMLDivElement>) => {\n    touchStart.current = e.touches[0]?.clientY ?? null;\n  }, []);\n\n  const onTouchMove = useCallback(\n    (e: TouchEvent<HTMLDivElement>) => {\n      const from = touchStart.current;\n      const y = e.touches[0]?.clientY;\n      // Finger travelling DOWN drags the content down, which scrolls up.\n      if (from !== null && y !== undefined && y - from > TOUCH_SLOP) askFollow(false);\n    },\n    [askFollow],\n  );\n\n  // ------------------------------------------------------------ unseen count\n\n  const seen = useRef(items.length);\n  const reportedUnseen = useRef<number | null>(null);\n\n  useEffect(() => {\n    const unseen = followTail ? 0 : Math.max(0, items.length - seen.current);\n    if (followTail) seen.current = items.length;\n\n    if (reportedUnseen.current === unseen) return;\n    reportedUnseen.current = unseen;\n    onUnseenChange?.(unseen);\n  }, [items.length, followTail, onUnseenChange]);\n\n  // ------------------------------------------------------------------ render\n\n  return (\n    <div\n      ref={attachViewport}\n      data-react-fancy-virtual-list=\"\"\n      data-react-fancy-virtual-list-following={followTail ? \"true\" : \"false\"}\n      data-react-fancy-virtual-list-rows={items.length}\n      role=\"log\"\n      tabIndex={0}\n      className={cn(\"relative overflow-y-auto overflow-x-hidden outline-none\", className)}\n      style={{ height }}\n      onScroll={onScroll}\n      onWheel={onWheel}\n      onKeyDown={onKeyDown}\n      onTouchStart={onTouchStart}\n      onTouchMove={onTouchMove}\n      {...props}\n    >\n      {/* Holds the full scroll range so the scrollbar is honest from the first\n          paint, instead of growing as rows are discovered. */}\n      <div\n        data-react-fancy-virtual-list-sizer=\"\"\n        style={{ height: `${total}px`, position: \"relative\" }}\n      >\n        <div\n          ref={windowRef}\n          data-react-fancy-virtual-list-window=\"\"\n          data-react-fancy-virtual-list-start={start}\n          style={{ transform: `translateY(${offsets[start] ?? 0}px)` }}\n        >\n          {visible.map((item, i) => (\n            <div key={item.id} data-react-fancy-virtual-row-id={item.id}>\n              {renderRow(item, start + i)}\n            </div>\n          ))}\n        </div>\n      </div>\n    </div>\n  );\n}\n\nconst ROW_ID_ATTR = \"data-react-fancy-virtual-row-id\";\n/** Within this many px of the bottom counts as \"at the bottom\". */\nconst BOTTOM_SLACK = 4;\n/** Ignore a touch jitter smaller than this before calling it an upward drag. */\nconst TOUCH_SLOP = 4;\nconst UPWARD_KEYS = new Set([\"ArrowUp\", \"PageUp\", \"Home\"]);\n"]}

package/dist/chunk-Z4CW3U6C.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/components/VirtualList/VirtualList.tsx"],"names":[],"mappings":"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","file":"chunk-Z4CW3U6C.js","sourcesContent":["import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from \"react\";\nimport type { KeyboardEvent, TouchEvent, WheelEvent } from \"react\";\nimport { cn } from \"../../utils/cn\";\nimport type { VirtualListProps, VirtualListRow } from \"./VirtualList.types\";\n\n/**\n * A windowed list for ledgers that run to tens of thousands of rows — only the\n * visible slice is in the DOM, with **measured** variable row heights, deep\n * links by row id, and sticky-bottom tail-following.\n *\n * Built for an agent event stream, where every one of those three is load\n * bearing at once: message rows wrap and event rows do not, a link carries\n * `?at=<rowId>` to the exact row under discussion, and new rows arrive while\n * the human is reading older ones.\n *\n * ## Heights are measured, never predicted\n *\n * `estimateRowHeight` only seeds rows that have never been on screen. The\n * moment a row renders, its real height is measured and replaces the estimate,\n * and every offset after it moves. The alternative — a `rowHeight(item)`\n * callback — is a prediction about text wrapping, font loading and container\n * width, and when it is wrong the error accumulates down the list: rows draw in\n * the wrong place and `scrollToId` lands on a neighbour. Measuring is slower to\n * settle and correct when it does.\n *\n * ## Tail-follow breaks on INTENT, not on position\n *\n * Any upward gesture — wheel, drag, PageUp, Home — stops following\n * immediately, even when the list is still pinned to the bottom and\n * `scrollTop` has not changed yet. Position cannot tell \"the human scrolled\n * up\" from \"content grew downward\", so a position-only implementation keeps\n * following through a wheel-up and yanks the reader back on the next append.\n *\n * ## It is controlled\n *\n * `followTail` is the consumer's state. This component only ever *asks* via\n * `onFollowChange`, so the follow state is readable and writable by an agent\n * over a bridge, as the Human+ component contract requires. The `↓ n new` pill\n * is the consumer's to render, from `onUnseenChange`.\n *\n * @example\n * ```tsx\n * const [following, setFollowing] = useState(true);\n * const [unseen, setUnseen] = useState(0);\n *\n * <VirtualList\n *   items={events}\n *   renderRow={(e) => <StreamRow event={e} />}\n *   height=\"100%\"\n *   estimateRowHeight={28}\n *   followTail={following}\n *   onFollowChange={setFollowing}\n *   onUnseenChange={setUnseen}\n *   scrollToId={params.at}\n * />\n * {!following && unseen > 0 && (\n *   <Button onClick={() => setFollowing(true)}>↓ {unseen} new</Button>\n * )}\n * ```\n */\nexport function VirtualList<T extends VirtualListRow>({\n  items,\n  renderRow,\n  height = \"100%\",\n  estimateRowHeight = 32,\n  overscan = 6,\n  followTail = false,\n  onFollowChange,\n  onUnseenChange,\n  scrollToId = null,\n  onScrollToIdResolved,\n  className,\n  ref,\n  ...props\n}: VirtualListProps<T>) {\n  const viewportRef = useRef<HTMLDivElement | null>(null);\n  const windowRef = useRef<HTMLDivElement | null>(null);\n\n  /** Measured heights by row id, so a height follows its row across a reindex. */\n  const heights = useRef(new Map<string, number>());\n  /** Bumped when a measurement actually changed, to recompute offsets. */\n  const [measured, setMeasured] = useState(0);\n\n  const [scrollTop, setScrollTop] = useState(0);\n  const [clientHeight, setClientHeight] = useState(0);\n\n  const attachViewport = useCallback(\n    (el: HTMLDivElement | null) => {\n      viewportRef.current = el;\n      if (typeof ref === \"function\") ref(el);\n      else if (ref) (ref as { current: HTMLDivElement | null }).current = el;\n    },\n    [ref],\n  );\n\n  // A number `height` IS the viewport height, and is usable before the element\n  // has been measured. Without one, render a conservative first window so there\n  // is something on screen for the measurement pass to work from.\n  const viewport =\n    clientHeight > 0 ? clientHeight : typeof height === \"number\" ? height : estimateRowHeight * 20;\n\n  /**\n   * Prefix sums of row heights: `offsets[i]` is where row `i` starts, and the\n   * last entry is the total. Rebuilt whenever rows or measurements change —\n   * O(n) once per change, against O(log n) per scroll from the binary search,\n   * rather than O(n) on every scroll frame.\n   */\n  const { offsets, total } = useMemo(() => {\n    const offs = new Float64Array(items.length + 1);\n    for (let i = 0; i < items.length; i += 1) {\n      offs[i + 1] = offs[i] + (heights.current.get(items[i].id) ?? estimateRowHeight);\n    }\n\n    return { offsets: offs, total: items.length === 0 ? 0 : offs[items.length] };\n  }, [items, measured, estimateRowHeight]);\n\n  /** First row whose span contains `y`. */\n  const indexAt = useCallback(\n    (y: number): number => {\n      let lo = 0;\n      let hi = items.length - 1;\n      while (lo < hi) {\n        const mid = (lo + hi + 1) >> 1;\n        if (offsets[mid] <= y) lo = mid;\n        else hi = mid - 1;\n      }\n\n      return Math.max(0, lo);\n    },\n    [items.length, offsets],\n  );\n\n  const start = Math.max(0, indexAt(scrollTop) - overscan);\n  const end = Math.min(items.length, indexAt(scrollTop + viewport) + 1 + overscan);\n  const visible = useMemo(() => items.slice(start, end), [items, start, end]);\n\n  // ---------------------------------------------------------------- measuring\n\n  const observer = useRef<ResizeObserver | null>(null);\n\n  useEffect(() => {\n    // Absent in jsdom and in older runtimes. Without it the list still measures\n    // on every render; it just does not notice a row reflowing in place.\n    if (typeof ResizeObserver === \"undefined\") return;\n\n    const ro = new ResizeObserver(() => setMeasured((v) => v + 1));\n    observer.current = ro;\n\n    return () => {\n      ro.disconnect();\n      observer.current = null;\n    };\n  }, []);\n\n  // No dependency array on purpose: every render re-measures what is on screen,\n  // and the `changed` guard is what stops it looping. A render that learns\n  // nothing new sets no state.\n  useLayoutEffect(() => {\n    const win = windowRef.current;\n    if (!win) return;\n\n    let changed = false;\n    for (const el of Array.from(win.children) as HTMLElement[]) {\n      const id = el.getAttribute(ROW_ID_ATTR);\n      if (id === null) continue;\n\n      observer.current?.observe(el);\n\n      const h = el.getBoundingClientRect().height;\n      // A zero height is \"not laid out yet\", not a 0px row. Recording it would\n      // collapse the list and make every offset after it wrong.\n      if (h > 0 && heights.current.get(id) !== h) {\n        heights.current.set(id, h);\n        changed = true;\n      }\n    }\n\n    const vp = viewportRef.current;\n    if (vp && vp.clientHeight > 0 && vp.clientHeight !== clientHeight) setClientHeight(vp.clientHeight);\n\n    if (changed) setMeasured((v) => v + 1);\n  });\n\n  // ------------------------------------------------------------- deep linking\n\n  /** The target this component last moved to, to detect that it has settled. */\n  const anchored = useRef<number | null>(null);\n  const resolved = useRef<string | null>(null);\n\n  useEffect(() => {\n    // A new id is a new request, even if the old one had resolved.\n    anchored.current = null;\n    resolved.current = null;\n  }, [scrollToId]);\n\n  useLayoutEffect(() => {\n    if (scrollToId === null || resolved.current === scrollToId) return;\n\n    const index = items.findIndex((item) => item.id === scrollToId);\n    if (index < 0) {\n      // A link to a row that is no longer in the list. Leaving the viewport\n      // where it is and SAYING SO is the only honest outcome — scrolling to the\n      // top would be indistinguishable from a successful landing.\n      resolved.current = scrollToId;\n      onScrollToIdResolved?.(scrollToId, false);\n\n      return;\n    }\n\n    const vp = viewportRef.current;\n    if (!vp) return;\n\n    // Clamped the way the browser clamps: a row inside the final viewport-height\n    // of the list cannot be brought to the top, and pretending otherwise would\n    // leave this waiting for a position that can never be reached.\n    const target = Math.max(0, Math.min(offsets[index], Math.max(0, total - viewport)));\n\n    if (anchored.current !== target) {\n      anchored.current = target;\n      vp.scrollTop = target;\n      setScrollTop(target);\n\n      return;\n    }\n\n    // The target stopped moving as rows above it were measured, and we are on\n    // it. Only now is the deep link actually honoured.\n    if (Math.abs(vp.scrollTop - target) <= 1) {\n      resolved.current = scrollToId;\n      onScrollToIdResolved?.(scrollToId, true);\n    }\n  });\n\n  // ------------------------------------------------------------- tail-follow\n\n  const reportedFollow = useRef(followTail);\n  const programmatic = useRef(false);\n\n  useEffect(() => {\n    // The prop is the truth, so adopt it rather than remembering what we asked\n    // for. Otherwise a consumer that declines an `onFollowChange(false)` would\n    // never be asked again.\n    reportedFollow.current = followTail;\n  }, [followTail]);\n\n  const askFollow = useCallback(\n    (next: boolean) => {\n      if (reportedFollow.current === next) return;\n      reportedFollow.current = next;\n      onFollowChange?.(next);\n    },\n    [onFollowChange],\n  );\n\n  useLayoutEffect(() => {\n    if (!followTail) return;\n    // A pending deep link wins while it resolves; otherwise the two would fight\n    // over the same scrollTop and the link would lose.\n    if (scrollToId !== null && resolved.current !== scrollToId) return;\n\n    const vp = viewportRef.current;\n    if (!vp) return;\n\n    const bottom = Math.max(0, total - viewport);\n    if (Math.abs(vp.scrollTop - bottom) > 0.5) {\n      programmatic.current = true;\n      vp.scrollTop = bottom;\n      setScrollTop(bottom);\n    }\n  });\n\n  const onScroll = useCallback(() => {\n    const vp = viewportRef.current;\n    if (!vp) return;\n\n    const next = vp.scrollTop;\n    const previous = scrollTop;\n    setScrollTop(next);\n\n    const bottom = Math.max(0, total - viewport);\n    const wasProgrammatic = programmatic.current;\n    programmatic.current = false;\n\n    if (next <= bottom - BOTTOM_SLACK) {\n      // Moved up, and not because we moved it.\n      if (!wasProgrammatic && next < previous) askFollow(false);\n    } else {\n      askFollow(true);\n    }\n  }, [scrollTop, total, viewport, askFollow]);\n\n  /** Any upward gesture is a statement of intent, whatever scrollTop says. */\n  const onWheel = useCallback(\n    (e: WheelEvent<HTMLDivElement>) => {\n      if (e.deltaY < 0) askFollow(false);\n    },\n    [askFollow],\n  );\n\n  const onKeyDown = useCallback(\n    (e: KeyboardEvent<HTMLDivElement>) => {\n      if (UPWARD_KEYS.has(e.key)) askFollow(false);\n    },\n    [askFollow],\n  );\n\n  const touchStart = useRef<number | null>(null);\n\n  const onTouchStart = useCallback((e: TouchEvent<HTMLDivElement>) => {\n    touchStart.current = e.touches[0]?.clientY ?? null;\n  }, []);\n\n  const onTouchMove = useCallback(\n    (e: TouchEvent<HTMLDivElement>) => {\n      const from = touchStart.current;\n      const y = e.touches[0]?.clientY;\n      // Finger travelling DOWN drags the content down, which scrolls up.\n      if (from !== null && y !== undefined && y - from > TOUCH_SLOP) askFollow(false);\n    },\n    [askFollow],\n  );\n\n  // ------------------------------------------------------------ unseen count\n\n  const seen = useRef(items.length);\n  const reportedUnseen = useRef<number | null>(null);\n\n  useEffect(() => {\n    const unseen = followTail ? 0 : Math.max(0, items.length - seen.current);\n    if (followTail) seen.current = items.length;\n\n    if (reportedUnseen.current === unseen) return;\n    reportedUnseen.current = unseen;\n    onUnseenChange?.(unseen);\n  }, [items.length, followTail, onUnseenChange]);\n\n  // ------------------------------------------------------------------ render\n\n  return (\n    <div\n      ref={attachViewport}\n      data-react-fancy-virtual-list=\"\"\n      data-react-fancy-virtual-list-following={followTail ? \"true\" : \"false\"}\n      data-react-fancy-virtual-list-rows={items.length}\n      role=\"log\"\n      tabIndex={0}\n      className={cn(\"relative overflow-y-auto overflow-x-hidden outline-none\", className)}\n      style={{ height }}\n      onScroll={onScroll}\n      onWheel={onWheel}\n      onKeyDown={onKeyDown}\n      onTouchStart={onTouchStart}\n      onTouchMove={onTouchMove}\n      {...props}\n    >\n      {/* Holds the full scroll range so the scrollbar is honest from the first\n          paint, instead of growing as rows are discovered. */}\n      <div\n        data-react-fancy-virtual-list-sizer=\"\"\n        style={{ height: `${total}px`, position: \"relative\" }}\n      >\n        <div\n          ref={windowRef}\n          data-react-fancy-virtual-list-window=\"\"\n          data-react-fancy-virtual-list-start={start}\n          style={{ transform: `translateY(${offsets[start] ?? 0}px)` }}\n        >\n          {visible.map((item, i) => (\n            <div key={item.id} data-react-fancy-virtual-row-id={item.id}>\n              {renderRow(item, start + i)}\n            </div>\n          ))}\n        </div>\n      </div>\n    </div>\n  );\n}\n\nconst ROW_ID_ATTR = \"data-react-fancy-virtual-row-id\";\n/** Within this many px of the bottom counts as \"at the bottom\". */\nconst BOTTOM_SLACK = 4;\n/** Ignore a touch jitter smaller than this before calling it an upward drag. */\nconst TOUCH_SLOP = 4;\nconst UPWARD_KEYS = new Set([\"ArrowUp\", \"PageUp\", \"Home\"]);\n"]}