@teaflask/assistant 0.0.0 → 0.3.0

package/src/components/use-perch-clearance.ts

@@ -0,0 +1,191 @@
+"use client";
+
+import { useEffect, type RefObject } from "react";
+
+import {
+  firstClearLiftFor,
+  INTERACTIVE_OBSTRUCTION_SELECTOR,
+  type ClearancePoint,
+  type ClearanceRect,
+} from "../core/perch-clearance.js";
+
+/**
+ * Collision awareness for the fixed corner perch: a page that already
+ * owns the corner — a composer's send button, a copy control — must keep
+ * its clicks. The hook probes what the page stacks beneath the perch's
+ * hit box (document.elementsFromPoint sees through the top layer) and
+ * lifts the dock by the smallest clear step (core/perch-clearance owns
+ * the verdict). Re-measured on resize, any scroll, and DOM mutations —
+ * route swaps included — all coalesced to one measurement per frame.
+ * Browsers without elementsFromPoint keep the unlifted corner; the
+ * transparent dock itself never obstructs anything (pointer-events:
+ * none).
+ */
+// How long the settle fallback waits out the dock's 180ms bottom glide
+// when transitionend cannot fire, with room for a busy frame.
+const LIFT_SETTLE_FALLBACK_MS = 400;
+
+// When the dock lives inside a shadow root (the script-tag custom
+// element), document.elementsFromPoint retargets in-shadow hits to the
+// shadow host — an element the dock neither contains nor shares a tree
+// with, so the self-exclusion checks below can't recognize it and the
+// dock would read itself as an obstruction.
+function _shadowHostChainOf(node: Node): readonly Element[] {
+  const hosts: Element[] = [];
+  let root = node.getRootNode();
+  while (root instanceof ShadowRoot) {
+    hosts.push(root.host);
+    root = root.host.getRootNode();
+  }
+  return hosts;
+}
+
+export function usePerchClearance(
+  dockRef: RefObject<HTMLDivElement | null>,
+  active: boolean,
+): void {
+  useEffect(() => {
+    const dock = dockRef.current;
+    if (!active || dock === null) {
+      return;
+    }
+    return _watchPerchClearance(dock);
+  }, [dockRef, active]);
+}
+
+/** Whether the PAGE stacks an interactive control under a point: the
+ *  dock's own elements, its shadow hosts and every other assistant
+ *  surface are never obstructions. */
+function _hostObstructionProbeFor(
+  dock: HTMLDivElement,
+): (point: ClearancePoint) => boolean {
+  const doc = dock.ownerDocument;
+  const shadowHostsOfDock = _shadowHostChainOf(dock);
+  return (point) =>
+    doc
+      .elementsFromPoint(point.x, point.y)
+      .some(
+        (element) =>
+          !dock.contains(element) &&
+          !shadowHostsOfDock.includes(element) &&
+          element.closest("[data-tf-assistant]") === null &&
+          element.closest(INTERACTIVE_OBSTRUCTION_SELECTOR) !== null,
+      );
+}
+
+// The dock's one click target: the mark's hit box.
+// The rect is re-based to lift 0 (the natural corner) so the verdict is
+// absolute, not relative to wherever the dock sits right now — valid
+// because a settled dock sits exactly at appliedLift. Null while the
+// box has no size (unmounted, or a dock the browser never showed).
+function _hitBoxRectOf(
+  dock: HTMLDivElement,
+  appliedLift: number,
+): ClearanceRect | null {
+  const body = dock.querySelector<HTMLElement>("[data-tf-companion-body]");
+  if (body === null) {
+    return null;
+  }
+  const rect = body.getBoundingClientRect();
+  if (rect.width === 0 || rect.height === 0) {
+    return null;
+  }
+  return {
+    left: rect.left,
+    top: rect.top + appliedLift,
+    width: rect.width,
+    height: rect.height,
+  };
+}
+
+/** Measures, lifts and re-measures the dock for as long as it is shown;
+ *  returns the teardown. */
+function _watchPerchClearance(dock: HTMLDivElement): (() => void) | undefined {
+  const doc = dock.ownerDocument;
+  if (typeof doc.elementsFromPoint !== "function") {
+    return;
+  }
+  const view = doc.defaultView ?? window;
+
+  let frame: number | null = null;
+  let appliedLift = 0;
+  // A lift change glides there over the dock's bottom transition, and
+  // getBoundingClientRect reads the in-flight position — re-basing with
+  // appliedLift is only exact once the glide lands. While settling,
+  // every trigger defers to the single post-settle measure.
+  let settling = false;
+  let settleTimer: number | null = null;
+
+  const hostObstructionAt = _hostObstructionProbeFor(dock);
+
+  const measure = () => {
+    frame = null;
+    if (settling) {
+      return;
+    }
+    const rect = _hitBoxRectOf(dock, appliedLift);
+    if (rect === null) {
+      return;
+    }
+    const lift = firstClearLiftFor({ rect, probe: hostObstructionAt });
+    if (lift !== appliedLift) {
+      appliedLift = lift;
+      settling = true;
+      dock.style.setProperty("--_tf-companion-lift", `${String(lift)}px`);
+      // Belt-and-braces settle: transitionend is the precise clock, but
+      // it never fires when the transition doesn't run (a hidden dock,
+      // a browser without the property) — the timer outlasts the 180ms
+      // glide either way.
+      settleTimer = view.setTimeout(settle, LIFT_SETTLE_FALLBACK_MS);
+    }
+  };
+  const scheduleMeasure = () => {
+    if (settling) {
+      return;
+    }
+    frame ??= view.requestAnimationFrame(measure);
+  };
+  // Landing re-measures once: anything the page did mid-glide was
+  // deferred, and the verdict must be re-checked from exact geometry.
+  const settle = () => {
+    if (!settling) {
+      return;
+    }
+    settling = false;
+    if (settleTimer !== null) {
+      view.clearTimeout(settleTimer);
+      settleTimer = null;
+    }
+    scheduleMeasure();
+  };
+  const settleOnBottomTransition = (event: TransitionEvent) => {
+    if (event.target === dock && event.propertyName === "bottom") {
+      settle();
+    }
+  };
+
+  scheduleMeasure();
+  view.addEventListener("resize", scheduleMeasure);
+  doc.addEventListener("scroll", scheduleMeasure, {
+    capture: true,
+    passive: true,
+  });
+  dock.addEventListener("transitionend", settleOnBottomTransition);
+  dock.addEventListener("transitioncancel", settleOnBottomTransition);
+  const observer = new MutationObserver(scheduleMeasure);
+  observer.observe(doc.body, { childList: true, subtree: true });
+  return () => {
+    if (frame !== null) {
+      view.cancelAnimationFrame(frame);
+    }
+    if (settleTimer !== null) {
+      view.clearTimeout(settleTimer);
+    }
+    view.removeEventListener("resize", scheduleMeasure);
+    doc.removeEventListener("scroll", scheduleMeasure, { capture: true });
+    dock.removeEventListener("transitionend", settleOnBottomTransition);
+    dock.removeEventListener("transitioncancel", settleOnBottomTransition);
+    observer.disconnect();
+    dock.style.removeProperty("--_tf-companion-lift");
+  };
+}

package/src/components/use-question-panel-keys.ts

@@ -0,0 +1,316 @@
+"use client";
+
+import {
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  type KeyboardEvent,
+  type RefObject,
+} from "react";
+
+import type { QuestionSetCardModel } from "../core/elicitation-cards.js";
+import type { QuestionModel } from "../core/elicitation-pickers.js";
+import {
+  answersOf,
+  firstUnansweredIndexOf,
+  MAX_ANSWER_TEXT_CHARS,
+  overLimitOf,
+  type QuestionAnswerDraft,
+  type QuestionDraftStore,
+} from "../core/question-drafts.js";
+import type { ElicitationSurface } from "./elicitation-context.js";
+
+// Keyboard (the a11y bar of the decision-surface coverage record):
+// the suggestions are a radiogroup with APG roving focus — arrows move
+// focus and selection, Space selects, Enter selects and continues; the
+// custom textarea takes Enter as a newline (never a send) and ⌘/Ctrl+Enter
+// to continue, ↑ at its start returns to the last suggestion, and its
+// row wears the focus ring while the caret is inside (focus is always
+// visible, even before the row is the active choice). The panel never
+// steals focus on arrival (the suspension surface's premise); after the
+// member pages, focus follows to the shown question's row.
+
+const CUSTOM_TEXTAREA_MAX_HEIGHT_PX = 192;
+
+type ActiveChoice = QuestionAnswerDraft["active"];
+
+interface QuestionPanelKeysInput {
+  card: QuestionSetCardModel;
+  drafts: QuestionDraftStore;
+  submitQuestionAnswers: ElicitationSurface["submitQuestionAnswers"];
+  cursor: number;
+  question: QuestionModel;
+  active: ActiveChoice;
+  customText: string;
+  answerable: boolean;
+  /** Paging closes any open suggestion description. */
+  closeDescription: () => void;
+}
+
+/** The draft writes the rows make: an option chosen, the custom row
+ *  re-activated, the custom text typed. */
+interface ActiveChoiceWriters {
+  selectOption: (text: string) => void;
+  activateCustomIfDrafted: () => void;
+  setCustomText: (text: string) => void;
+}
+
+interface QuestionPanelKeys extends ActiveChoiceWriters {
+  rowsRef: RefObject<HTMLDivElement | null>;
+  customRef: RefObject<HTMLTextAreaElement | null>;
+  goTo: (next: number) => void;
+  proceed: () => void;
+  optionKeys: (index: number) => (event: KeyboardEvent<HTMLElement>) => void;
+  customKeys: (event: KeyboardEvent<HTMLTextAreaElement>) => void;
+}
+
+export function useQuestionPanelKeys(
+  input: QuestionPanelKeysInput,
+): QuestionPanelKeys {
+  const { card, drafts, cursor, active, customText, closeDescription } = input;
+  const rowsRef = useRef<HTMLDivElement>(null);
+  const customRef = useRef<HTMLTextAreaElement>(null);
+  // Focus follows a member's own paging, never an arrival: the flag is
+  // set by the Prev/Next handlers alone and consumed once.
+  const focusAfterPageRef = useRef(false);
+
+  useEffect(() => {
+    if (!focusAfterPageRef.current) {
+      return;
+    }
+    focusAfterPageRef.current = false;
+    if (active?.kind === "custom") {
+      customRef.current?.focus();
+      return;
+    }
+    const rows = rowsRef.current?.querySelectorAll<HTMLElement>("[role=radio]");
+    if (rows === undefined || rows.length === 0) {
+      customRef.current?.focus();
+      return;
+    }
+    const checked = [...rows].find(
+      (row) => row.getAttribute("aria-checked") === "true",
+    );
+    (checked ?? rows[0]).focus();
+  }, [cursor, active]);
+
+  // Autosize the custom row: one line at rest, growing with a pasted
+  // paragraph to a cap, then scrolling inside (the composer's own
+  // pattern). Layout-effect timing keeps it in step with the keystroke.
+  useLayoutEffect(() => {
+    const textarea = customRef.current;
+    if (textarea === null) {
+      return;
+    }
+    textarea.style.height = "auto";
+    if (textarea.scrollHeight === 0) {
+      return;
+    }
+    textarea.style.height = `${String(
+      Math.min(textarea.scrollHeight, CUSTOM_TEXTAREA_MAX_HEIGHT_PX),
+    )}px`;
+  }, [customText, cursor]);
+
+  const goTo = (next: number) => {
+    if (next < 0 || next >= card.questions.length) {
+      return;
+    }
+    focusAfterPageRef.current = true;
+    closeDescription();
+    drafts.setCursor(card.interruptId, next);
+  };
+
+  const writers = activeChoiceWritersOf(input);
+
+  const focusRow = (index: number) => {
+    const rows = rowsRef.current?.querySelectorAll<HTMLElement>("[role=radio]");
+    if (rows === undefined) {
+      return;
+    }
+    if (index >= rows.length) {
+      writers.activateCustomIfDrafted();
+      customRef.current?.focus();
+      return;
+    }
+    rows[Math.max(index, 0)].focus();
+  };
+
+  const proceed = () => {
+    proceedFrom(input, goTo);
+  };
+
+  const gestures: RowGestures = {
+    question: input.question,
+    selectOption: writers.selectOption,
+    focusRow,
+    proceed,
+  };
+
+  return {
+    rowsRef,
+    customRef,
+    goTo,
+    proceed,
+    ...writers,
+    optionKeys: (index) => (event) => {
+      optionRowKey(gestures, index, event);
+    },
+    customKeys: (event) => {
+      customRowKey(gestures, event);
+    },
+  };
+}
+
+// "Continue" — the footer primary and the Enter/⌘Enter gesture share
+// one meaning: advance locally; from the last question, submit the
+// complete set — or, when a question is still open, go to it.
+function proceedFrom(
+  input: QuestionPanelKeysInput,
+  goTo: (next: number) => void,
+): void {
+  const { card, drafts, cursor, answerable, submitQuestionAnswers } = input;
+  if (cursor !== card.questions.length - 1) {
+    goTo(cursor + 1);
+    return;
+  }
+  const current = drafts.get(card.interruptId);
+  const over = overLimitOf(card.questions, current, MAX_ANSWER_TEXT_CHARS);
+  if (over.length > 0) {
+    // Never a silent no-op: go to the over-bound question so the member
+    // can shorten it.
+    const at = card.questions.findIndex((entry) => entry.id === over[0]);
+    if (at >= 0 && at !== cursor) {
+      goTo(at);
+    }
+    return;
+  }
+  const complete = answersOf(card.questions, current);
+  if (complete === null) {
+    const open = firstUnansweredIndexOf(card.questions, current);
+    if (open >= 0 && open !== cursor) {
+      goTo(open);
+    }
+    return;
+  }
+  if (!answerable) {
+    return;
+  }
+  void submitQuestionAnswers(card, complete);
+}
+
+// THE ACTIVE CHOICE, EVERY WAY IT CAN CHANGE — pointer and keyboard
+// agree at every row:
+//   pointer down on an option row / Space / Enter on it → that option;
+//     the custom text is kept.
+//   ↑ / ↓ between option rows → the row arrived at; text kept.
+//   ↓ from the last option onto the custom row, or pointer down on the
+//     custom row or its textarea → custom ONLY IF it already holds a
+//     usable (non-blank) answer; an EMPTY custom row is not an answer,
+//     so reaching it never un-answers the question — focus moves, the
+//     option stays chosen. (The defect this closes: a click on the empty
+//     row flipped the question to unanswered while ↓ did not.)
+//   ↑ from the custom row's start → the last option, chosen (an arrow
+//     always chooses the row it lands on); text kept.
+//   Tab / focus arriving from the pager or a remount → focus only,
+//     never a choice: navigation is not intent.
+//   typing or pasting in the custom row → custom (the one implicit
+//     switch, and it is the member's own content).
+//   Nothing in this table ever discards custom text or a chosen option:
+//   both live in the draft until the member changes them.
+function activeChoiceWritersOf(
+  input: QuestionPanelKeysInput,
+): ActiveChoiceWriters {
+  const { card, drafts, question, customText, answerable } = input;
+  const customIsDrafted = customText.trim() !== "";
+  return {
+    selectOption: (text) => {
+      if (!answerable) {
+        return;
+      }
+      drafts.selectOption(card.interruptId, question.id, text);
+    },
+    activateCustomIfDrafted: () => {
+      if (answerable && customIsDrafted) {
+        drafts.selectCustom(card.interruptId, question.id);
+      }
+    },
+    setCustomText: (text) => {
+      drafts.setCustomText(card.interruptId, question.id, text);
+    },
+  };
+}
+
+/** What a row's key handler reaches: the shown question's options, the
+ *  choice writer, roving focus, and the continue gesture. */
+interface RowGestures {
+  question: QuestionModel;
+  selectOption: (text: string) => void;
+  focusRow: (index: number) => void;
+  proceed: () => void;
+}
+
+function optionRowKey(
+  { question, selectOption, focusRow, proceed }: RowGestures,
+  index: number,
+  event: KeyboardEvent<HTMLElement>,
+): void {
+  switch (event.key) {
+    case "ArrowDown":
+    case "ArrowRight": {
+      event.preventDefault();
+      const next = index + 1;
+      if (next < question.options.length) {
+        selectOption(question.options[next].text);
+      }
+      focusRow(next);
+      return;
+    }
+    case "ArrowUp":
+    case "ArrowLeft": {
+      event.preventDefault();
+      const previous = index - 1;
+      if (previous >= 0) {
+        selectOption(question.options[previous].text);
+        focusRow(previous);
+      }
+      return;
+    }
+    case " ":
+      event.preventDefault();
+      selectOption(question.options[index].text);
+      return;
+    case "Enter":
+      event.preventDefault();
+      // The selection lands in the store synchronously; the continue
+      // reads the updated draft itself.
+      selectOption(question.options[index].text);
+      proceed();
+      return;
+    default:
+      return;
+  }
+}
+
+function customRowKey(
+  { question, selectOption, focusRow, proceed }: RowGestures,
+  event: KeyboardEvent<HTMLTextAreaElement>,
+): void {
+  if (event.key === "Enter" && (event.metaKey || event.ctrlKey)) {
+    event.preventDefault();
+    proceed();
+    return;
+  }
+  if (
+    event.key === "ArrowUp" &&
+    event.currentTarget.selectionStart === 0 &&
+    event.currentTarget.selectionEnd === 0 &&
+    question.options.length > 0
+  ) {
+    event.preventDefault();
+    // An arrow chooses the row it lands on, as between option rows.
+    selectOption(question.options[question.options.length - 1].text);
+    focusRow(question.options.length - 1);
+  }
+  // A plain Enter stays a newline — a pasted explanation is multi-line
+  // by nature and must never send by accident.
+}

package/src/components/use-register-assistant-surface.ts

@@ -0,0 +1,27 @@
+"use client";
+
+import { useEffect } from "react";
+
+import {
+  assistantSurfaceRegistry,
+  type AssistantSurfaceKind,
+} from "../core/surface-registry.js";
+
+/**
+ * Announces a mounted chrome to the page-wide surface registry while
+ * `active` — the signal the companion yields to. A plain effect (not a
+ * layout effect) means the announcement lands one frame after paint;
+ * whether that frame matters for companion flicker is the companion's
+ * call to make, beside its consumer.
+ */
+export function useRegisterAssistantSurface(
+  kind: AssistantSurfaceKind,
+  active = true,
+): void {
+  useEffect(() => {
+    if (!active) {
+      return;
+    }
+    return assistantSurfaceRegistry.register(kind);
+  }, [kind, active]);
+}

package/src/components/use-resolved-theme-mode.ts

@@ -0,0 +1,113 @@
+"use client";
+
+import { useEffect, useLayoutEffect, useState, type RefObject } from "react";
+
+import type { ToolViewThemeMode } from "../core/tool-view.js";
+
+// The runtime answer to "which palette is painted here?" for the
+// tool-view props' `themeMode`. The stylesheet is the ground truth; its
+// theme grammar is three rules computed AT THE WIDGET ROOT
+// (`[data-tf-assistant]`): (1) an ancestor's or the root's own
+// `data-tf-theme="dark"` paints dark; (2) the root's OWN "light"/"auto"
+// re-pin light at equal specificity, out-cascading an ancestor's dark —
+// root level ONLY; (3) prefers-color-scheme upgrades "auto" to dark at
+// root level only. Resolution mirrors that exactly, never a nearest-
+// carrier walk: carriers inside the root are inert, and no carrier
+// paints light — reporting the OS preference would lie about the pixels.
+
+const DARK_SCHEME_QUERY = "(prefers-color-scheme: dark)";
+
+export function useResolvedThemeMode(
+  ref: RefObject<HTMLElement | null>,
+): ToolViewThemeMode {
+  // "light" before the first resolution: SSR-safe (no window at module
+  // scope or render time) and the honest default for the no-carrier
+  // case.
+  const [mode, setMode] = useState<ToolViewThemeMode>("light");
+  // The initial resolution is a LAYOUT effect on purpose: a passive
+  // effect runs after paint and would hand every renderer one painted
+  // light frame per mount in a dark-pinned host — every mid-stream row,
+  // not an SSR-only artifact.
+  useLayoutEffect(() => {
+    setMode(_resolvedThemeModeFor(ref.current));
+  }, [ref]);
+  useEffect(() => {
+    // The ref is read at decision time, never captured. This value has no
+    // CSS backstop — it is handed to host code as the only channel — so
+    // BOTH change paths re-resolve live: the attribute can flip on any
+    // ancestor, written by anyone (a host theme library writing <html>
+    // imperatively), hence a document-wide observer, not a render-time
+    // read; and a slot whose root node is a shadow root watches that root
+    // too — a set `mode` prop lands `data-tf-theme` INSIDE it. One
+    // observer pair per mounted slot: linear in custom-rendered rows, and
+    // `attributeFilter` keeps each dispatch cheap.
+    const resolve = () => {
+      setMode(_resolvedThemeModeFor(ref.current));
+    };
+    resolve();
+    const observer = new MutationObserver(resolve);
+    observer.observe(document.documentElement, {
+      attributes: true,
+      attributeFilter: ["data-tf-theme"],
+      subtree: true,
+    });
+    const rootNode = ref.current?.getRootNode();
+    let shadowObserver: MutationObserver | null = null;
+    if (rootNode instanceof ShadowRoot) {
+      shadowObserver = new MutationObserver(resolve);
+      shadowObserver.observe(rootNode, {
+        attributes: true,
+        attributeFilter: ["data-tf-theme"],
+        subtree: true,
+      });
+    }
+    // jsdom ships no matchMedia; a host page always has one. Without
+    // it, "auto" and the OS flip degrade to light rather than throwing.
+    if (typeof window.matchMedia !== "function") {
+      return () => {
+        observer.disconnect();
+        shadowObserver?.disconnect();
+      };
+    }
+    const media = window.matchMedia(DARK_SCHEME_QUERY);
+    media.addEventListener("change", resolve);
+    return () => {
+      observer.disconnect();
+      shadowObserver?.disconnect();
+      media.removeEventListener("change", resolve);
+    };
+  }, [ref]);
+  return mode;
+}
+
+function _resolvedThemeModeFor(element: HTMLElement | null): ToolViewThemeMode {
+  if (element === null) {
+    return "light";
+  }
+  // The stylesheet computes the palette at the widget root; a bare test
+  // or fixture mount with no root falls back to the slot element itself,
+  // which the same rules then treat as the root.
+  const root = element.closest<HTMLElement>("[data-tf-assistant]") ?? element;
+  const own = root.getAttribute("data-tf-theme");
+  if (own === "dark") {
+    return "dark";
+  }
+  if (own === "light") {
+    return "light";
+  }
+  if (own === "auto") {
+    return _prefersDark() ? "dark" : "light";
+  }
+  // A bare root: any strict ancestor's "dark" paints dark (rule 1's
+  // descendant combinator); ancestor "light"/"auto" match no rule.
+  const ancestorDark =
+    root.parentElement?.closest('[data-tf-theme="dark"]') ?? null;
+  return ancestorDark === null ? "light" : "dark";
+}
+
+function _prefersDark(): boolean {
+  return (
+    typeof window.matchMedia === "function" &&
+    window.matchMedia(DARK_SCHEME_QUERY).matches
+  );
+}