@djangocfg/widget-chat 0.1.1

package/src/primitives/transcript.tsx

@@ -0,0 +1,285 @@
+import { memo, useCallback, useEffect, useRef, useState, type ReactNode } from "react";
+
+import {
+  useChatSurfaces,
+  useHistoryLoaded,
+  useMessage,
+  useMessageIds,
+  useTurn,
+} from "../store";
+import { useMissedCount } from "./use-missed-count";
+import { useReturnOnSend } from "./use-return-on-send";
+import { useRovingFocus } from "./use-roving-focus";
+import { useStickToBottom } from "./use-stick-to-bottom";
+import { useTurnActivity, type TurnActivity } from "./use-turn-activity";
+
+export interface TranscriptProps {
+  /** Render one message. Called with the id; the row reads the message itself. */
+  readonly children: (id: string) => ReactNode;
+  /** Shown when there are no messages — an empty transcript is a real state. */
+  readonly empty?: ReactNode;
+  readonly className?: string;
+  /**
+   * The accessible name of the log. Copy is the host's — no locales here.
+   *
+   * Without it `role="log"` is an unnamed landmark: a screen reader user moving
+   * between regions hears "log" with nothing to distinguish it.
+   */
+  readonly label?: string;
+  /**
+   * What to say when a reply starts and when it ends — the ONLY two strings a
+   * screen reader hears per turn.
+   *
+   * Absent means no announcements at all, which is the correct default for a
+   * host that already announces elsewhere: a second live region would make
+   * every reply be read twice.
+   */
+  readonly announce?: {
+    readonly streaming: string;
+    readonly complete: string;
+  };
+  /**
+   * Rendered when the user has scrolled away from the bottom, with a callback
+   * that returns them to it.
+   *
+   * A render prop rather than a built-in button, because the control is styled
+   * and worded by the host — and because a transcript that decides its own
+   * chrome is how a primitive turns back into 83 props.
+   *
+   * `missed` is how many replies arrived since the reader left, or **null when
+   * there is nothing honest to show** — a fresh unpin, or a conversation opened
+   * already scrolled up. Null and 0 are different states; only a real arrival
+   * deserves a number, so a host must render no badge rather than an empty one.
+   */
+  readonly jumpToLatest?: (props: {
+    readonly onClick: () => void;
+    readonly missed: number | null;
+  }) => ReactNode;
+  /**
+   * Rendered after the last row for as long as a turn is in flight, given what
+   * that turn is currently doing.
+   *
+   * `waiting` — sent, nothing back yet. `working` — text is arriving. It ends at
+   * turn-end, so a host can carry one indicator across both phases instead of
+   * showing something during the silence and nothing during the answer.
+   *
+   * In the transcript rather than beside the composer because that is where the
+   * answer will appear, so the promise of one belongs there too. It also rides
+   * inside the scroll container, which is what makes the autoscroll treat it as
+   * new content and keep the view pinned to the bottom.
+   *
+   * Never a message: it has no id and never enters the store, so it cannot leak
+   * into stored history as a message nobody sent.
+   *
+   * ONE slot rather than one per phase, and ONE owner rather than a decision
+   * repeated in every row: a message that reports its own completion reports it
+   * forever, so the indicator stacks up once per reply on a single screen.
+   *
+   * A render prop, like `jumpToLatest`, because the copy and the chrome are the
+   * host's — this package carries no locales.
+   */
+  readonly pending?: (activity: TurnActivity) => ReactNode;
+}
+
+/**
+ * The message list.
+ *
+ * Not virtualized, deliberately. Virtualization fights streaming (heights
+ * change on every token), autoscroll, and find-in-page, and the transcripts
+ * a chat room shows are hundreds of messages, not tens of thousands. The
+ * measurement comes first: if a real transcript stutters, that is when this
+ * decision gets revisited — `@rules/architecture.md`.
+ */
+export function Transcript({
+  children,
+  empty,
+  className,
+  label,
+  announce,
+  jumpToLatest,
+  pending,
+}: TranscriptProps) {
+  const ids = useMessageIds();
+  const historyLoaded = useHistoryLoaded();
+  const activity = useTurnActivity();
+  const { ref, contentRef, onScroll, isPinned, scrollToBottom } = useStickToBottom(ids.length);
+  const missed = useMissedCount(ids, isPinned);
+  useReturnOnSend(ids, scrollToBottom);
+  const roving = useRovingFocus(ids.length);
+  const transition = useTurnAnnouncement(announce);
+  const waiting = activity !== null && pending !== undefined ? pending(activity) : null;
+  const surfaces = useChatSurfaces();
+  // Two owners of one node: the scroll machinery needs it, and a host needs it
+  // to scope a selection to the conversation. Both callbacks, so this composes
+  // without either learning about the other.
+  const attach = useCallback(
+    (node: HTMLDivElement | null) => {
+      ref(node);
+      surfaces?.registerTranscript(node);
+    },
+    [ref, surfaces],
+  );
+
+  // Two things suppress the empty state, both because it would be a LIE.
+  //
+  // `waiting`: a first turn sent into a fresh room is not an empty transcript,
+  // and "no messages yet" under a prompt the user just sent says the opposite
+  // of what happened.
+  //
+  // `historyLoaded`: an unanswered fetch is not an empty room. Without it a
+  // conversation with 90 replies opened on "no messages yet" for the duration
+  // of the load.
+  if (ids.length === 0 && empty !== undefined && waiting === null && historyLoaded) {
+    return <div className={className}>{empty}</div>;
+  }
+
+  return (
+    <>
+      {/*
+        Three elements: outer clips, scroller fills it, content grows.
+
+        Merging the outer two paints the scroller from its first frame, which is
+        at the TOP — the library cannot know the bottom before it measures. Cost
+        a ~33ms flash of old history on entering every room.
+      */}
+      <div className={`grid overflow-hidden ${className ?? ""}`}>
+      <div
+        ref={attach}
+        onScroll={onScroll}
+        onKeyDown={roving.onKeyDown}
+        className="h-full overflow-y-auto"
+        // `role="log"` names what this is and implies `aria-relevant="additions"`
+        // — additions only, never text mutations.
+        //
+        // Never spell `aria-relevant="additions text"` here: `text` asks the
+        // screen reader to announce changes to text NODES inside the region,
+        // and a streamed reply rewrites its text node on every delta, so the
+        // whole answer is read out token by token. None of the surveyed
+        // libraries sets `aria-relevant` at all — the announcement belongs on a
+        // separate node, below.
+        role="log"
+        aria-label={label}
+        aria-live="polite"
+      >
+        {/*
+          The measured element, and the one the reading column now caps.
+
+          The library needs a child whose height IS the content's, separate from
+          the scroller whose height is the viewport's — that difference is what
+          it observes. `chat-column` moves here with it: the rule caps direct
+          children, and the rows are this element's children now.
+        */}
+        {/* `pb-10` on the CONTENT, not the scroller: it must be part of the
+            measured height, or the follow stops a gap short of the composer.
+            The right inset keeps text off the scrollbar, which runs at the
+            pane's own edge; the host sizes it, so a phone can widen it to match
+            its other margins. */}
+        {/* The rhythm between messages is declared HERE, on the element that
+            owns the rows. Without it the only thing parting two rows is
+            whatever they happen to render: a speaker line is omitted for a
+            consecutive same-author turn, so those pairs sat flush while their
+            neighbours kept the line's 28px. Spacing that depends on optional
+            content is not spacing. */}
+        <div ref={contentRef} className="chat-column chat-inset-r flex flex-col gap-4 pt-4 pb-10">
+          {ids.map((id, index) => (
+            <div key={id} {...roving.itemProps(index)}>
+              <MessageRow id={id}>{children}</MessageRow>
+            </div>
+          ))}
+          {waiting}
+        </div>
+      </div>
+      </div>
+      {/*
+        Anchored to the SCROLLER's bottom, not the chat's: the chat's last grid
+        row is the composer, so a control positioned against it lands on top of
+        the input. `sticky` inside the scroll container would ride the content;
+        this sits in a zero-height strip at the scroller's own lower edge.
+
+        `pointer-events-none` on the strip so it never eats a click aimed at the
+        last message; the control inside opts back in.
+      */}
+      {!isPinned && jumpToLatest !== undefined && (
+        <div className="pointer-events-none relative h-0 [&>*]:pointer-events-auto">
+          {jumpToLatest({ onClick: scrollToBottom, missed })}
+        </div>
+      )}
+      <TurnAnnouncer text={transition} />
+    </>
+  );
+}
+
+/**
+ * The two words a screen reader hears per turn.
+ *
+ * Only TRANSITIONS — never the streamed content — so this can never spam.
+ * `role="status"` is an implicit polite, atomic live region: atomic means the
+ * whole node is re-read on change, which is right for a one-line status and
+ * wrong for a transcript.
+ *
+ * Always rendered, even when empty: a live region created at the moment of the
+ * event is not announced, because assistive tech must have been observing the
+ * node beforehand.
+ */
+function TurnAnnouncer({ text }: { readonly text: string }) {
+  return (
+    <div
+      role="status"
+      style={{
+        position: "absolute",
+        width: 1,
+        height: 1,
+        margin: -1,
+        padding: 0,
+        overflow: "hidden",
+        // `clip` over `display:none` or `visibility:hidden`: those two remove
+        // the node from the accessibility tree entirely, taking the
+        // announcement with them.
+        clip: "rect(0 0 0 0)",
+        whiteSpace: "nowrap",
+        border: 0,
+      }}
+    >
+      {text}
+    </div>
+  );
+}
+
+/** The transition string for the current turn, or "" when there is nothing to say. */
+function useTurnAnnouncement(announce: TranscriptProps["announce"]): string {
+  const { isStreaming } = useTurn();
+  const [text, setText] = useState("");
+  const wasStreaming = useRef(false);
+
+  useEffect(() => {
+    const was = wasStreaming.current;
+    wasStreaming.current = isStreaming;
+    // Only on a CHANGE. Re-running on every render would re-announce, and an
+    // atomic region re-reads its whole contents each time it is written.
+    if (announce === undefined || was === isStreaming) return;
+    // "complete" is not announced on mount — `was` starts false, so the first
+    // transition it can report is false→true.
+    setText(isStreaming ? announce.streaming : announce.complete);
+  }, [announce, isStreaming]);
+
+  return text;
+}
+
+interface MessageRowProps {
+  readonly id: string;
+  readonly children: (id: string) => ReactNode;
+}
+
+/**
+ * One row, memoized on its id.
+ *
+ * `useMessage(id)` subscribes to that message alone, so a token arriving in the
+ * last row re-renders one component. Without this pair the list re-renders per
+ * token and the cost grows with transcript length — the stutter that reads as
+ * "the chat is laggy" rather than as a rendering bug.
+ */
+const MessageRow = memo(function MessageRow({ id, children }: MessageRowProps) {
+  const message = useMessage(id);
+  if (message === undefined) return null;
+  return <>{children(id)}</>;
+});

package/src/primitives/use-dismiss.ts

@@ -0,0 +1,100 @@
+import { useEffect, useRef, type RefObject } from "react";
+
+export interface UseDismissOptions {
+  /** Nothing is listened for while this is false — a closed surface costs nothing. */
+  readonly open: boolean;
+  readonly onDismiss: () => void;
+  /**
+   * Elements that must NOT count as outside.
+   *
+   * Plural because a popover has at least two: the panel and the trigger that
+   * opened it. Omitting the trigger makes a press on it dismiss and re-open in
+   * the same gesture, so the surface never closes by its own button.
+   */
+  readonly refs: readonly RefObject<HTMLElement | null>[];
+}
+
+/** The smallest shape the rules need. Structural, so a test needs no DOM. */
+interface NodeLike {
+  contains(other: unknown): boolean;
+}
+interface KeyLike {
+  readonly key: string;
+  stopPropagation(): void;
+}
+
+/**
+ * Is this press outside every element that counts as inside?
+ *
+ * Extracted so the rule can be tested without a DOM: the workspace has no
+ * jsdom, and the alternative — a regex over the hook's source — cannot tell
+ * `contains` on two refs from `contains` on one, which is the exact bug that
+ * makes a trigger dismiss and reopen in a single gesture.
+ */
+export function pressIsOutside(
+  target: unknown,
+  refs: readonly { readonly current: NodeLike | null }[],
+): boolean {
+  return !refs.some((ref) => ref.current?.contains(target) === true);
+}
+
+/**
+ * Escape dismisses, and STOPS THERE.
+ *
+ * The `stopPropagation` is the load-bearing half. Chat panes and dialogs close
+ * on Escape too, so without it one press closes the menu AND whatever hosts it
+ * — the menu appears to work while quietly taking the surface behind it down.
+ * Returns whether the key dismissed, so the caller stays a one-liner.
+ */
+export function escapeDismisses(event: KeyLike): boolean {
+  if (event.key !== "Escape") return false;
+  event.stopPropagation();
+  return true;
+}
+
+/**
+ * Outside press and Escape close a floating surface.
+ *
+ * A primitive rather than a per-menu handler: this package carries NO popover
+ * dependency, so every surface that floats has to implement these two rules, and
+ * a hand-written one degrades quietly. That already happened once — the language
+ * picker shipped as a plain element that only its own trigger could close, which
+ * looks identical in a screenshot and behaves like a trap.
+ *
+ * Two details beyond the pure rules above:
+ *
+ *   - **`pointerdown`, not `click`.** A click fires after the press has already
+ *     moved focus and possibly unmounted what was under the pointer, so the
+ *     dismissal lands a frame late and can be swallowed by a re-render.
+ *   - **Capture phase.** A row inside the surface may `stopPropagation` for its
+ *     own reasons; dismissal must not depend on other handlers being polite.
+ */
+export function useDismiss({ open, onDismiss, refs }: UseDismissOptions): void {
+  // Read in the listeners, so a changing callback or ref list never re-binds
+  // them mid-gesture — a re-bind between pointerdown and keydown drops events.
+  const dismiss = useRef(onDismiss);
+  dismiss.current = onDismiss;
+  const inside = useRef(refs);
+  inside.current = refs;
+
+  useEffect(() => {
+    if (!open) return undefined;
+
+    const onPointerDown = (event: PointerEvent): void => {
+      if (!pressIsOutside(event.target, inside.current)) return;
+      dismiss.current();
+    };
+
+    const onKeyDown = (event: KeyboardEvent): void => {
+      if (!escapeDismisses(event)) return;
+      dismiss.current();
+    };
+
+    document.addEventListener("pointerdown", onPointerDown, true);
+    document.addEventListener("keydown", onKeyDown, true);
+    return () => {
+      document.removeEventListener("pointerdown", onPointerDown, true);
+      document.removeEventListener("keydown", onKeyDown, true);
+    };
+  }, [open]);
+}

package/src/primitives/use-missed-count.ts

@@ -0,0 +1,30 @@
+import { useMemo, useRef } from "react";
+
+import { MissedCount, missedRows } from "../core/scroll";
+import { useChatStore } from "../store";
+
+/**
+ * How many replies arrived while the reader was scrolled away.
+ *
+ * Reads roles imperatively off the store instead of subscribing to the message
+ * array. A `useMessages()` selector would re-render the transcript on every
+ * token — the exact cost the `useMessageIds()` / `useMessage(id)` split exists
+ * to avoid (`store/hooks.ts`). Here it is free: the count can only change when
+ * `ids` changes, and the transcript already re-renders then.
+ *
+ * @param ids the transcript's message ids, in order
+ * @param pinned whether the viewport is following the bottom
+ */
+export function useMissedCount(ids: readonly string[], pinned: boolean): number | null {
+  const store = useChatStore();
+  const counter = useRef<MissedCount | null>(null);
+  counter.current ??= new MissedCount();
+
+  return useMemo(() => {
+    const missed = counter.current;
+    if (missed === null) return null;
+    const byId = store.getState().transcript.byId;
+    missed.observe(pinned, missedRows(ids, byId));
+    return missed.value();
+  }, [store, ids, pinned]);
+}

package/src/primitives/use-overflows.ts

@@ -0,0 +1,69 @@
+/**
+ * Does this element have more content than the height it is allowed?
+ *
+ * Answers the question by measuring the thing itself rather than by estimating
+ * from what is inside it. A message is an array of parts, not a string: an image
+ * or a table contributes almost no characters at a large height, and a code
+ * fence keeps its characters while losing its shape. Any character count is
+ * therefore a proxy for a proxy, and the element already knows the answer.
+ *
+ * Reports only. It never writes a height — the clamp is a CSS `max-height` the
+ * caller owns, which is what makes the measurement honest: while collapsed the
+ * element IS clipped, so `scrollHeight > clientHeight` is exactly the question.
+ */
+
+import { useCallback, useLayoutEffect, useState, type RefObject } from "react";
+
+/**
+ * @param ref the clamped element — the one carrying `max-height`.
+ * @param expanded whether the clamp is currently lifted. Load-bearing: see the
+ *   collapse-first note below.
+ * @param deps a value that changes when the content does, so a streamed message
+ *   re-measures as it grows.
+ */
+export function useOverflows(
+  ref: RefObject<HTMLElement | null>,
+  expanded: boolean,
+  deps: unknown,
+): boolean {
+  const [overflows, setOverflows] = useState(false);
+
+  const measure = useCallback(() => {
+    const node = ref.current;
+    if (node === null) return;
+
+    // Collapse first. `scrollHeight` and `clientHeight` are equal while the
+    // clamp is lifted, so measuring in the expanded state reports "fits" for
+    // every message and the control disappears the moment it is used. The
+    // composer's autosize carries the same ordering for the same reason.
+    //
+    // Removing the property rather than setting a value returns the element to
+    // whatever the stylesheet says, so this never has to know the budget.
+    const lifted = expanded;
+    const previous = node.style.maxHeight;
+    if (lifted) node.style.maxHeight = "";
+
+    setOverflows(node.scrollHeight > node.clientHeight);
+
+    if (lifted) node.style.maxHeight = previous;
+  }, [ref, expanded]);
+
+  // A layout effect, not an effect: the trigger must be present in the same
+  // paint as the clipped text, or a long message shows one frame with no way to
+  // open it.
+  useLayoutEffect(measure, [measure, deps]);
+
+  // Content can also change height without the deps changing — a font loads, an
+  // image decodes, the window narrows and the text rewraps. The element itself
+  // is the only reliable signal for those.
+  useLayoutEffect(() => {
+    const node = ref.current;
+    if (node === null) return;
+    if (typeof ResizeObserver === "undefined") return;
+    const observer = new ResizeObserver(measure);
+    observer.observe(node);
+    return () => observer.disconnect();
+  }, [ref, measure]);
+
+  return overflows;
+}

package/src/primitives/use-return-on-send.ts

@@ -0,0 +1,29 @@
+/**
+ * Sending returns the reader to the bottom.
+ *
+ * The React binding only; the decision is `core/scroll`'s `isOwnSend`, tested
+ * without a DOM. What is here is the one thing that cannot be pure — remembering
+ * the previous list across renders.
+ */
+
+import { useEffect, useRef } from "react";
+
+import { isOwnSend } from "../core/scroll";
+import { useChatStore } from "../store";
+
+export function useReturnOnSend(ids: readonly string[], scrollToBottom: () => void): void {
+  const store = useChatStore();
+  // A ref, not state: nothing renders from it, and it must be read and written
+  // inside the same effect pass.
+  const seen = useRef<readonly string[] | null>(null);
+
+  useEffect(() => {
+    const previous = seen.current;
+    seen.current = ids;
+    // Read through the store rather than from a prop: the roles live beside the
+    // ids in one state, so passing them in would let a caller hand over a list
+    // and a role map that disagree.
+    const roleOf = (id: string) => store.getState().transcript.byId[id]?.role;
+    if (isOwnSend(previous, ids, roleOf)) scrollToBottom();
+  }, [ids, store, scrollToBottom]);
+}

package/src/primitives/use-roving-focus.ts

@@ -0,0 +1,69 @@
+/**
+ * The DOM half of roving tabindex. The index arithmetic lives in
+ * `core/focus/roving.ts`, where it is tested.
+ *
+ * Deliberately DOM-driven rather than list-driven: rows are rendered by the
+ * HOST, so this hook cannot know their shape. It reads the elements marked with
+ * `data-chat-item` at the moment a key is pressed, which also keeps it correct
+ * while the transcript streams.
+ */
+
+import { useCallback, useState, type KeyboardEvent } from "react";
+
+import { CHAT_ITEM_ATTR, clampIndex, isRovingKey, nextIndex } from "../core/focus";
+
+export interface RovingFocus {
+  readonly onKeyDown: (event: KeyboardEvent<HTMLElement>) => void;
+  /** Spread onto each row. Only the active row is tabbable. */
+  readonly itemProps: (index: number) => {
+    readonly tabIndex: number;
+    readonly [CHAT_ITEM_ATTR]: string;
+  };
+}
+
+/**
+ * @param count how many rows there are. Needed because messages arrive while
+ *   the user reads: an active index that outlives its row would leave EVERY row
+ *   at `tabIndex={-1}`, so the transcript stops being reachable by Tab and
+ *   nothing about it looks broken.
+ */
+export function useRovingFocus(count: number): RovingFocus {
+  // State, not a ref: `tabIndex` is rendered output, so moving the active row
+  // has to re-render the rows. A ref would move focus once and leave every
+  // row's tabIndex frozen at its initial value.
+  const [active, setActive] = useState(0);
+  const current = clampIndex(active, count);
+
+  const onKeyDown = useCallback(
+    (event: KeyboardEvent<HTMLElement>) => {
+      if (!isRovingKey(event.key)) return;
+
+      const items = Array.from(
+        event.currentTarget.querySelectorAll<HTMLElement>(`[${CHAT_ITEM_ATTR}]`),
+      );
+      const next = nextIndex(event.key, clampIndex(active, items.length), items.length);
+      // `null` means the key moves nowhere — at the last row, ArrowDown must
+      // still scroll the PAGE, so it is left to the browser rather than
+      // swallowed by a preventDefault that changes nothing.
+      if (next === null) return;
+
+      const target = items[next];
+      if (target === undefined) return;
+
+      event.preventDefault();
+      setActive(next);
+      target.focus();
+    },
+    [active],
+  );
+
+  const itemProps = useCallback(
+    (index: number) => ({
+      tabIndex: index === current ? 0 : -1,
+      [CHAT_ITEM_ATTR]: "",
+    }),
+    [current],
+  );
+
+  return { onKeyDown, itemProps };
+}