@digithings-ai/ui 0.0.0-stage → 0.1.0

package/src/components/chat/trace-grouping/chain-group-by.ts

@@ -0,0 +1,44 @@
+import { groupPartByType } from "@assistant-ui/react";
+
+/**
+ * The chain grouping every first-party trace uses (the digichat skin's
+ * gallery thread, the base skins and the stock thread).
+ *
+ * Reasoning and tool calls nest under one `group-chainOfThought`, and inside
+ * it adjacent reasoning parts coalesce into `group-reasoning` and adjacent
+ * tool calls into `group-tool`.
+ *
+ * A source or a status part between two work runs must not split the chain:
+ * only text ends a work run, so two runs with nothing but a source between
+ * them are one chain, not two. The library's helper covers the part types it
+ * knows; the status parts (`data-*`) are matched here, and the memo
+ * fingerprint is kept so the tree is not rebuilt on every render.
+ */
+export const chainGroupBy = (() => {
+  const base = groupPartByType({
+    reasoning: ["group-chainOfThought", "group-reasoning"],
+    "tool-call": ["group-chainOfThought", "group-tool"],
+    "standalone-tool-call": [],
+    source: ["group-chainOfThought", "group-tool"],
+  });
+  const fn = (part: { type: string; name?: string }, context?: unknown) => {
+    const dataName =
+      part.type === "data"
+        ? part.name
+        : part.type.startsWith("data-")
+          ? part.type.slice("data-".length)
+          : undefined;
+    // A data-notice (a rate-limit wait, and any other status notice) stays
+    // outside the chain. The chain folds once the answer arrives, which would
+    // hide the notice inside the collapsed work block.
+    if (dataName === "notice") return base(part as never, context as never);
+    if (part.type === "data" || part.type.startsWith("data-")) {
+      return ["group-chainOfThought", "group-tool"] as const;
+    }
+    return base(part as never, context as never);
+  };
+  (fn as unknown as Record<symbol, string>)[
+    Symbol.for("@assistant-ui/groupBy.memoKey")
+  ] = "digichat:chain-v3";
+  return fn;
+})();

package/src/components/chat/trace-grouping/chain-state.ts

@@ -0,0 +1,141 @@
+/**
+ * The trace grouping rules, as pure functions of the message parts and the
+ * disclosure policy. The digichat skin's gallery thread and the base skins
+ * both read them, so the two traces fold, open and count the same way and
+ * differ only in how they look.
+ *
+ * Kept free of React so a test can call every rule with plain objects.
+ */
+import type { WorkDisclosure } from "../stock/skin-types";
+
+/** The part fields the rules need. */
+export type ChainPartLike = {
+  readonly type: string;
+  readonly text?: unknown;
+};
+
+/**
+ * Disclosure behaviour for one kind of row inside the chain. `off` hides it,
+ * `collapsed` renders it closed, `balanced` opens it while it streams,
+ * `expanded` starts open and `locked_open` pins it open.
+ */
+export type ChainRowMode =
+  | "off"
+  | "collapsed"
+  | "balanced"
+  | "expanded"
+  | "locked_open";
+
+const isWork = (part: ChainPartLike | undefined) =>
+  part?.type === "reasoning" || part?.type === "tool-call";
+
+/** The message holds reasoning or a tool call somewhere. */
+export function messageHasWork(parts: readonly (ChainPartLike | undefined)[]): boolean {
+  return parts.some(isWork);
+}
+
+/**
+ * Anything real arrived from the agent: reasoning, a tool call, the answer.
+ * A status part (the connection state) is not content; it is the
+ * pre-response phase, which is when the loading row belongs.
+ */
+export function messageHasContent(parts: readonly (ChainPartLike | undefined)[]): boolean {
+  return parts.some((part) => part !== undefined && part.type !== "data");
+}
+
+/**
+ * The chain holds real work. The grouping puts status and source parts into
+ * the chain too; a chain of only those draws no header (the loading row
+ * covers that phase).
+ */
+export function chainHoldsWork(
+  parts: readonly (ChainPartLike | undefined)[],
+  indices: readonly number[],
+): boolean {
+  return indices.some((index) => isWork(parts[index]));
+}
+
+/**
+ * Only text ends a work run: a chain with non-empty text after it has
+ * answered, so its work is over. A chain without one is still the agent's
+ * current work, even if the model streams another run of tool calls.
+ */
+export function chainFollowedByText(
+  parts: readonly (ChainPartLike | undefined)[],
+  indices: readonly number[],
+): boolean {
+  const last = indices.length > 0 ? indices[indices.length - 1]! : -1;
+  return parts.some((part, index) => {
+    if (index <= last || part?.type !== "text") return false;
+    return typeof part.text === "string" && part.text.trim() !== "";
+  });
+}
+
+/** The tool calls in a tool group; sources and status parts do not count. */
+export function chainToolCount(
+  parts: readonly (ChainPartLike | undefined)[],
+  indices: readonly number[],
+): number {
+  return indices.filter((index) => parts[index]?.type === "tool-call").length;
+}
+
+/** How long the chain waits before it folds away once its work is over. */
+export const CHAIN_SETTLE_MS = 600;
+
+/**
+ * Whether the whole chain is open. The first manual toggle wins; otherwise
+ * the verbose level keeps it open, the quiet level folds it as soon as the
+ * answer starts, and the balanced level folds it once the work has settled.
+ */
+export function chainOpen({
+  userOpen,
+  openAtRest,
+  foldOnAnswer,
+  working,
+  settled,
+}: {
+  userOpen: boolean | null;
+  openAtRest: boolean;
+  foldOnAnswer: boolean;
+  working: boolean;
+  settled: boolean;
+}): boolean {
+  return userOpen ?? (openAtRest ? true : foldOnAnswer ? working : !settled && working);
+}
+
+export type ChainGroupDisclosure = {
+  /** Open on mount. */
+  defaultOpen: boolean;
+  /** Open while the group streams, folded again once it completes. */
+  streamingOpen: boolean;
+  /** Pinned open: the trigger does nothing. */
+  locked: boolean;
+};
+
+/** The `N tool calls` group inside the chain. */
+export function toolGroupDisclosure(
+  disclosure: Pick<WorkDisclosure, "openAtRest" | "openWhileRunning">,
+  mode: ChainRowMode,
+  live: boolean,
+): ChainGroupDisclosure {
+  const locked = mode === "locked_open";
+  return {
+    locked,
+    defaultOpen: disclosure.openAtRest || mode === "expanded" || locked,
+    streamingOpen: (disclosure.openWhileRunning || mode === "balanced") && live,
+  };
+}
+
+/** The reasoning box inside the chain. */
+export function reasoningGroupDisclosure(
+  disclosure: Pick<WorkDisclosure, "openAtRest" | "openWhileRunning">,
+  mode: ChainRowMode,
+  live: boolean,
+): ChainGroupDisclosure {
+  const locked = mode === "locked_open";
+  return {
+    locked,
+    defaultOpen: disclosure.openAtRest || mode === "expanded" || locked,
+    streamingOpen: live && (disclosure.openWhileRunning || mode === "balanced"),
+  };
+}

package/src/components/chat/trace-grouping/index.ts

@@ -0,0 +1,32 @@
+export { chainGroupBy } from "./chain-group-by";
+export {
+  CHAIN_SETTLE_MS,
+  chainFollowedByText,
+  chainHoldsWork,
+  chainOpen,
+  chainToolCount,
+  messageHasContent,
+  messageHasWork,
+  reasoningGroupDisclosure,
+  toolGroupDisclosure,
+  type ChainGroupDisclosure,
+  type ChainPartLike,
+  type ChainRowMode,
+} from "./chain-state";
+export {
+  useWorkChain,
+  type WorkChainMarker,
+  type WorkChainOptions,
+  type WorkChainState,
+} from "./use-work-chain";
+export {
+  effectiveToolStatus,
+  resolveToolStatus,
+  toolRowStatus,
+  type ToolRowStatus,
+} from "./tool-row";
+export {
+  useDeployWorkDisclosure,
+  useToolRowOpenWhileRunning,
+  type DeployWorkDisclosure,
+} from "./use-deploy-work-disclosure";

package/src/components/chat/trace-grouping/tool-row.ts

@@ -0,0 +1,74 @@
+/**
+ * What a tool-call row says about its call, shared by every first-party
+ * trace so the digichat skin and the base skins word a row the same way.
+ * Pure: no React, callable from a test with plain objects.
+ */
+import type { ToolCallMessagePartStatus } from "@assistant-ui/react";
+import { EN_TRACE_T, type TraceT } from "../trace-i18n/core";
+import type { TurnOutcome } from "../turn-outcome";
+
+/**
+ * assistant-ui's `toMessagePartStatus` returns `{ type: "complete" }` for any
+ * tool-call part with a defined `result` — even when `isError` is set, because
+ * an `output-error` part carries `result = { error }`. Derive the error state
+ * from `isError` so a failed or orphaned row does not render as success.
+ */
+export function resolveToolStatus(
+  status: ToolCallMessagePartStatus | undefined,
+  isError: boolean | undefined,
+  result: unknown,
+): ToolCallMessagePartStatus | undefined {
+  if (!isError || status?.type === "incomplete") return status;
+  const error =
+    result && typeof result === "object" && "error" in result
+      ? (result as { error?: unknown }).error
+      : undefined;
+  return { type: "incomplete", reason: "error", error };
+}
+
+/**
+ * A call still waiting on a result when the turn was stopped will never get
+ * one: it reads cancelled, not "Waiting on tool". A call that waits on the
+ * visitor (approval, interrupt) keeps its controls.
+ */
+export function effectiveToolStatus(
+  resolved: ToolCallMessagePartStatus | undefined,
+  outcome: TurnOutcome,
+  offersVisitorAction: boolean,
+): ToolCallMessagePartStatus | undefined {
+  return outcome === "stopped" &&
+    resolved?.type === "requires-action" &&
+    !offersVisitorAction
+    ? { type: "incomplete", reason: "cancelled" }
+    : resolved;
+}
+
+export type ToolRowStatus = {
+  label: string;
+  statusType: ToolCallMessagePartStatus["type"];
+  isRunning: boolean;
+  isCancelled: boolean;
+  isError: boolean;
+};
+
+/** The row's words for a tool status: one word per state, upstream wording. */
+export function toolRowStatus(
+  status: ToolCallMessagePartStatus | undefined,
+  tr: TraceT = EN_TRACE_T,
+): ToolRowStatus {
+  const statusType = status?.type ?? "complete";
+  const isRunning = statusType === "running";
+  const isCancelled =
+    status?.type === "incomplete" && status.reason === "cancelled";
+  const isError = status?.type === "incomplete" && status.reason === "error";
+  const label = isCancelled
+    ? tr.t("cancelledTool")
+    : isError
+      ? tr.t("failedTool")
+      : statusType === "running"
+        ? tr.t("runningTool")
+        : statusType === "requires-action"
+          ? tr.t("waitingOnTool")
+          : tr.t("usedTool");
+  return { label, statusType, isRunning, isCancelled, isError };
+}

package/src/components/chat/trace-grouping/use-deploy-work-disclosure.ts

@@ -0,0 +1,35 @@
+"use client";
+
+import { useDeployUi } from "../stock/deploy-ui-context";
+import {
+  resolveWorkDisclosure,
+  workVisibilityForView,
+  type WorkDisclosure,
+} from "../stock/skin-types";
+import type { ChainRowMode } from "./chain-state";
+
+export type DeployWorkDisclosure = {
+  reasoningMode: ChainRowMode;
+  toolCallsMode: ChainRowMode;
+  disclosure: WorkDisclosure;
+};
+
+/**
+ * The deploy's view level and row modes, resolved the way the digichat skin
+ * resolves them before handing them to its thread (`skins/digichat.tsx`), for
+ * skins that read them from context instead of props.
+ */
+export function useDeployWorkDisclosure(): DeployWorkDisclosure {
+  const ui = useDeployUi();
+  return {
+    reasoningMode: ui.reasoning,
+    toolCallsMode: ui.toolCalls,
+    disclosure: resolveWorkDisclosure(workVisibilityForView(ui.view)),
+  };
+}
+
+/** Base skins: a tool card shows its arguments while its call runs. */
+export function useToolRowOpenWhileRunning(): boolean {
+  const { toolCallsMode, disclosure } = useDeployWorkDisclosure();
+  return toolCallsMode !== "off" && disclosure.openWhileRunning;
+}

package/src/components/chat/trace-grouping/use-work-chain.ts

@@ -0,0 +1,103 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { useAuiState } from "@assistant-ui/react";
+import { workStatusText } from "../gallery-thread/work-status";
+import { useTraceT } from "../trace-i18n";
+import { turnCutShort, useTurnOutcome, type TurnOutcome } from "../turn-outcome";
+import { CHAIN_SETTLE_MS, chainOpen } from "./chain-state";
+
+/** The header marker: what the chain is doing, or how it ended. */
+export type WorkChainMarker = "loading" | "idle" | "error" | "stop";
+
+export type WorkChainOptions = {
+  /**
+   * The message-part indices this chain holds. The folded header describes
+   * them ("Working — digisearch", "Used 3 tools"); without them the header
+   * keeps the plain title.
+   */
+  indices?: readonly number[] | undefined;
+  /** Nothing ever folds (the verbose level). */
+  openAtRest?: boolean | undefined;
+  /** Fold as soon as the answer starts, not when the work settles (quiet). */
+  foldOnAnswer?: boolean | undefined;
+  /** A text part follows this chain: its work is over. */
+  followedByText?: boolean | undefined;
+};
+
+export type WorkChainState = {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  /** The header text. */
+  title: string;
+  marker: WorkChainMarker;
+  /** `running`, `done`, or how a cut-short turn ended. */
+  outcome: "running" | "done" | Exclude<TurnOutcome, "running" | "done">;
+};
+
+/**
+ * The whole chain of reasoning and tool calls under one header: when it is
+ * open, what the header says and which marker it shows.
+ *
+ * The header stays open for the whole run of work (not only while a group
+ * happens to be running) so the block never flickers shut between two tool
+ * calls, and folds `CHAIN_SETTLE_MS` after the answer starts. Folded, the
+ * header is a live status line ("Working — web_search", "Used 3 tools");
+ * open, it is the plain "Working" / "Worked" title, because the rows are
+ * right underneath. The first manual toggle wins.
+ *
+ * A turn that was stopped or failed before any text is over too: the marker
+ * stops and the title says how it ended.
+ */
+export function useWorkChain({
+  indices,
+  openAtRest = false,
+  foldOnAnswer = false,
+  followedByText = false,
+}: WorkChainOptions): WorkChainState {
+  const [userOpen, setUserOpen] = useState<boolean | null>(null);
+  const [settled, setSettled] = useState(false);
+
+  const outcome = useTurnOutcome();
+  const cutShort = !followedByText && turnCutShort(outcome);
+  const working = !followedByText && !cutShort;
+
+  useEffect(() => {
+    if (working) {
+      setSettled(false);
+      return;
+    }
+    const id = setTimeout(() => setSettled(true), CHAIN_SETTLE_MS);
+    return () => clearTimeout(id);
+  }, [working]);
+
+  const open = chainOpen({ userOpen, openAtRest, foldOnAnswer, working, settled });
+
+  const parts = useAuiState((s) => s.message.parts);
+  const tr = useTraceT();
+  const status = !open && indices ? workStatusText(parts, indices, tr) : undefined;
+  const endedTitle = outcome === "failed" ? tr.t("failed") : tr.t("stopped");
+  const title = cutShort
+    ? endedTitle
+    : status
+      ? status.label
+      : working
+        ? tr.t("working")
+        : tr.t("worked");
+  const markerRunning = !cutShort && (status ? status.running : working);
+  const marker: WorkChainMarker = cutShort
+    ? outcome === "failed"
+      ? "error"
+      : "stop"
+    : markerRunning
+      ? "loading"
+      : "idle";
+
+  return {
+    open,
+    onOpenChange: setUserOpen,
+    title,
+    marker,
+    outcome: cutShort ? (outcome as "stopped" | "failed") : working ? "running" : "done",
+  };
+}

package/src/components/chat/trace-i18n/core.ts

@@ -0,0 +1,48 @@
+/** Pure trace i18n core: tables, plural rules, no React. */
+import { en } from "./locales/en";
+import { fr } from "./locales/fr";
+import type { TracePluralKey, TraceStringKey, TraceStrings } from "./types";
+
+/** Registered trace tables. A language without a table falls back to English. */
+export const TRACE_LOCALES: Readonly<Record<string, TraceStrings>> = { en, fr };
+
+export const DEFAULT_TRACE_LOCALE = "en";
+
+function primary(locale: string | null | undefined): string {
+  return (locale ?? "").split(/[-_]/)[0]?.toLowerCase() ?? "";
+}
+
+export function resolveTraceLocale(locale: string | null | undefined): string {
+  const code = primary(locale);
+  return TRACE_LOCALES[code] ? code : DEFAULT_TRACE_LOCALE;
+}
+
+export type TraceT = {
+  locale: string;
+  t: (key: TraceStringKey, vars?: Record<string, string>) => string;
+  plural: (key: TracePluralKey, count: number) => string;
+};
+
+function fill(text: string, vars?: Record<string, string>): string {
+  if (!vars) return text;
+  return text.replace(/\{(\w+)\}/g, (m, k: string) => vars[k] ?? m);
+}
+
+export function createTraceT(locale: string | null | undefined): TraceT {
+  const code = resolveTraceLocale(locale);
+  const table = TRACE_LOCALES[code] ?? en;
+  const rules = new Intl.PluralRules(code);
+  const num = new Intl.NumberFormat(code);
+  return {
+    locale: code,
+    t: (key, vars) => fill(table[key] ?? en[key], vars),
+    plural: (key, count) => {
+      const msg = table[key] ?? en[key];
+      const text = msg[rules.select(count)] ?? msg.other;
+      return fill(text, { count: num.format(count) });
+    },
+  };
+}
+
+/** Default English helper for pure functions called without a hook. */
+export const EN_TRACE_T: TraceT = createTraceT(DEFAULT_TRACE_LOCALE);

package/src/components/chat/trace-i18n/index.tsx

@@ -0,0 +1,23 @@
+"use client";
+
+import { createContext, useContext, useMemo, type ReactNode } from "react";
+import { useEmbedChatPrefsOptional } from "../stock/embed-chat-prefs";
+import { DEFAULT_TRACE_LOCALE, createTraceT, type TraceT } from "./core";
+
+export * from "./core";
+export type { TraceStrings, PluralMessage } from "./types";
+
+const TraceLocaleContext = createContext<string | null>(null);
+
+/** Pins the trace language below it (tests, hosts without chat prefs). */
+export function TraceLocaleProvider({ locale, children }: { locale: string; children: ReactNode }) {
+  return <TraceLocaleContext.Provider value={locale}>{children}</TraceLocaleContext.Provider>;
+}
+
+/** Trace strings in the session language: the provider, else the chat prefs `/language`, else English. */
+export function useTraceT(): TraceT {
+  const pinned = useContext(TraceLocaleContext);
+  const prefs = useEmbedChatPrefsOptional();
+  const locale = pinned ?? prefs?.prefs.language ?? DEFAULT_TRACE_LOCALE;
+  return useMemo(() => createTraceT(locale), [locale]);
+}

package/src/components/chat/trace-i18n/locales/en.ts

@@ -0,0 +1,24 @@
+import type { TraceStrings } from "../types";
+
+export const en: TraceStrings = {
+  reasoning: "Reasoning",
+  thinking: "Thinking",
+  thought: "Thought",
+  working: "Working",
+  worked: "Worked",
+  workingOn: "Working — {tool}",
+  toolFallbackName: "tool",
+  needsInput: "Needs your input",
+  stopped: "Stopped",
+  failed: "Failed",
+  usedTools: { one: "Used {count} tool", other: "Used {count} tools" },
+  thoughtAndUsedTools: { one: "Thought and used {count} tool", other: "Thought and used {count} tools" },
+  toolCalls: { one: "{count} tool call", other: "{count} tool calls" },
+  usedTool: "Used tool",
+  cancelledTool: "Cancelled tool",
+  failedTool: "Failed tool",
+  runningTool: "Running tool",
+  waitingOnTool: "Waiting on tool",
+  errorPrefix: "Error:",
+  cancelledPrefix: "Cancelled:",
+};

package/src/components/chat/trace-i18n/locales/fr.ts

@@ -0,0 +1,28 @@
+import type { TraceStrings } from "../types";
+
+export const fr: TraceStrings = {
+  reasoning: "Raisonnement",
+  thinking: "Réflexion en cours",
+  thought: "Réflexion terminée",
+  working: "En cours",
+  worked: "Terminé",
+  workingOn: "En cours — {tool}",
+  toolFallbackName: "outil",
+  needsInput: "Votre réponse est requise",
+  stopped: "Arrêté",
+  failed: "Échec",
+  usedTools: { one: "{count} outil utilisé", many: "{count} d’outils utilisés", other: "{count} outils utilisés" },
+  thoughtAndUsedTools: {
+    one: "Réflexion et {count} outil utilisé",
+    many: "Réflexion et {count} d’outils utilisés",
+    other: "Réflexion et {count} outils utilisés",
+  },
+  toolCalls: { one: "{count} appel d’outil", many: "{count} d’appels d’outils", other: "{count} appels d’outils" },
+  usedTool: "Outil utilisé",
+  cancelledTool: "Outil annulé",
+  failedTool: "Échec de l’outil",
+  runningTool: "Outil en cours",
+  waitingOnTool: "En attente de l’outil",
+  errorPrefix: "Erreur :",
+  cancelledPrefix: "Annulé :",
+};

package/src/components/chat/trace-i18n/types.ts

@@ -0,0 +1,35 @@
+/** One plural message: `{count}` is replaced by the formatted number. */
+export type PluralMessage = Partial<Record<Intl.LDMLPluralRule, string>> & { other: string };
+
+/**
+ * Every static string the chat trace (reasoning, tool calls, the grouped
+ * summary line, status tags) shows. One table per language under `locales/`;
+ * adding a language means adding one table and registering it in `index.tsx`.
+ * Tool names and model text are not here: they stay as they come.
+ */
+export type TraceStrings = {
+  reasoning: string;
+  thinking: string;
+  thought: string;
+  working: string;
+  worked: string;
+  /** `{tool}` is the running tool's name. */
+  workingOn: string;
+  toolFallbackName: string;
+  needsInput: string;
+  stopped: string;
+  failed: string;
+  usedTools: PluralMessage;
+  thoughtAndUsedTools: PluralMessage;
+  toolCalls: PluralMessage;
+  usedTool: string;
+  cancelledTool: string;
+  failedTool: string;
+  runningTool: string;
+  waitingOnTool: string;
+  errorPrefix: string;
+  cancelledPrefix: string;
+};
+
+export type TraceStringKey = { [K in keyof TraceStrings]: TraceStrings[K] extends string ? K : never }[keyof TraceStrings];
+export type TracePluralKey = { [K in keyof TraceStrings]: TraceStrings[K] extends PluralMessage ? K : never }[keyof TraceStrings];