@data-club/ai-hub 0.0.1

package/src/components/SystemNotice/index.tsx

@@ -0,0 +1,151 @@
+/**
+ * `<SystemNotice />` — banner rendered above `messages_area` for non-fatal
+ * system events (TPM wait, recovery resumed, exhausted error). Variants:
+ *
+ * - `--tpm-wait` — provider rate-limited; recovery in progress
+ * - `--resumed` — recovery succeeded; usually auto-dismissed after a brief flash
+ * - `--error` — non-recoverable (e.g. `tpm_exhausted`)
+ *
+ * Pure presentational — the parent (`MessageList` in the monolith) decides
+ * which variant to render, what body text to show, and any auto-dismiss
+ * timer. Tier-3 wrappers can use the primitive directly with their own
+ * content too.
+ *
+ * Exported under `AIHub.SystemNotice`.
+ *
+ * @see SPECIFICATIONS.md §9.4 — system_notice events
+ * @see ui-sketches/03-chat.md — system_notice
+ */
+
+import { type ReactNode } from "react";
+
+/**
+ * BEM class names emitted by `<SystemNotice />`.
+ */
+export interface SystemNoticeClassNames {
+  /** Outer banner element. */
+  root: string;
+  /** Modifier — `--tpm-wait`. */
+  rootTpmWait: string;
+  /** Modifier — `--resumed`. */
+  rootResumed: string;
+  /** Modifier — `--error`. */
+  rootError: string;
+  /** Icon span. */
+  icon: string;
+  /** Body text span. */
+  body: string;
+  /** Action button (e.g. retry on error variant). */
+  action: string;
+}
+
+const DEFAULT_CLASS_NAMES: SystemNoticeClassNames = Object.freeze({
+  root: "data-club-ai-hub__system-notice",
+  rootTpmWait: "data-club-ai-hub__system-notice--tpm-wait",
+  rootResumed: "data-club-ai-hub__system-notice--resumed",
+  rootError: "data-club-ai-hub__system-notice--error",
+  icon: "data-club-ai-hub__system-notice__icon",
+  body: "data-club-ai-hub__system-notice__body",
+  action: "data-club-ai-hub__system-notice__action",
+}) as SystemNoticeClassNames;
+
+/** Props for `<SystemNotice />`. */
+export interface SystemNoticeProps {
+  /** Variant — controls the modifier class + the default icon. */
+  variant: "tpm-wait" | "resumed" | "error";
+  /** Body text (i18n-supplied). */
+  message: string;
+  /** Override the default icon character for the variant. */
+  icon?: string;
+  /** Optional inline action button. */
+  action?: {
+    /** Button label. */
+    label: string;
+    /** Click handler. */
+    onClick: () => void;
+  };
+  /** Extra class merged onto the root. */
+  className?: string;
+  /** Per-element class overrides. */
+  classNames?: Partial<SystemNoticeClassNames>;
+}
+
+/**
+ * Default icon glyph per variant.
+ */
+function defaultIcon(variant: SystemNoticeProps["variant"]): string {
+  switch (variant) {
+    case "tpm-wait":
+      return "⏱";
+    case "resumed":
+      return "✓";
+    case "error":
+      return "⚠";
+  }
+}
+
+/**
+ * Returns the BEM modifier for the variant.
+ */
+function modifierForVariant(
+  variant: SystemNoticeProps["variant"],
+  cls: SystemNoticeClassNames,
+): string {
+  switch (variant) {
+    case "tpm-wait":
+      return cls.rootTpmWait;
+    case "resumed":
+      return cls.rootResumed;
+    case "error":
+      return cls.rootError;
+  }
+}
+
+/**
+ * `role` ARIA value per variant. Error gets `alert` so screen readers
+ * announce; wait/resumed get `status` (polite live region).
+ */
+function roleForVariant(variant: SystemNoticeProps["variant"]): "alert" | "status" {
+  return variant === "error" ? "alert" : "status";
+}
+
+/**
+ * Renders the notice.
+ *
+ * @param props - see `SystemNoticeProps`.
+ * @returns the rendered notice.
+ */
+export function SystemNotice(props: SystemNoticeProps): ReactNode {
+  const cls = { ...DEFAULT_CLASS_NAMES, ...(props.classNames ?? {}) };
+  const icon = props.icon ?? defaultIcon(props.variant);
+  const rootClass = [
+    cls.root,
+    modifierForVariant(props.variant, cls),
+    props.className,
+  ]
+    .filter(Boolean)
+    .join(" ");
+  return (
+    <div
+      className={rootClass}
+      role={roleForVariant(props.variant)}
+      data-testid="system-notice"
+      data-variant={props.variant}
+    >
+      <span className={cls.icon} aria-hidden="true">
+        {icon}
+      </span>
+      <span className={cls.body}>{props.message}</span>
+      {props.action ? (
+        <button
+          type="button"
+          className={cls.action}
+          onClick={props.action.onClick}
+          data-testid="system-notice-action"
+        >
+          {props.action.label}
+        </button>
+      ) : null}
+    </div>
+  );
+}

package/src/components/ThemeSwitcher/index.tsx

@@ -0,0 +1,136 @@
+/**
+ * `<ThemeSwitcher />` — sun/moon toggle that flips the active theme via
+ * `setTheme` from `useAIHub()`.
+ *
+ * Renders **nothing** when `themeSwitcherEnabled === false` (i.e. the
+ * super_admin has disabled the switcher for this deployment per §7.6) —
+ * not a disabled control, not a hidden control, but absent from the DOM
+ * entirely. That's the contract callers — including `UserMenu` —
+ * depend on: a `ThemeSwitcher` inside a conditional is safe to leave in
+ * place; the primitive self-suppresses.
+ *
+ * Optimistic update: clicking the switcher flips the local `theme`
+ * value immediately and posts `PATCH /auth/me/preferences { theme }`.
+ * On a 409 `theme_switcher_disabled` (server-side switcher disabled
+ * mid-call), the provider's `setTheme` reverts the optimistic state and
+ * surfaces the error via `onError`.
+ *
+ * Exported under `AIHub.ThemeSwitcher`.
+ *
+ * @see SPECIFICATIONS.md §7.6 — theme resolution
+ * @see ui-sketches/00-shell.md — `Theme: Light ↔ Dark` item in user menu
+ */
+
+import { type ReactNode } from "react";
+
+import type { AIHubChatTexts } from "../../auth/texts.js";
+import { resolveAIHubTexts, type AIHubTexts, type DeepPartial } from "../../auth/texts.js";
+import { useAIHub } from "../../context/useAIHub.js";
+
+/**
+ * BEM class names emitted by `<ThemeSwitcher />`.
+ */
+export interface ThemeSwitcherClassNames {
+  /** The button element. */
+  root: string;
+  /** Modifier added when the active theme is light. */
+  rootLight: string;
+  /** Modifier added when the active theme is dark. */
+  rootDark: string;
+  /** The icon span. */
+  icon: string;
+  /** The label text span. */
+  label: string;
+}
+
+const DEFAULT_CLASS_NAMES: ThemeSwitcherClassNames = Object.freeze({
+  root: "data-club-ai-hub__theme-switcher",
+  rootLight: "data-club-ai-hub__theme-switcher--light",
+  rootDark: "data-club-ai-hub__theme-switcher--dark",
+  icon: "data-club-ai-hub__theme-switcher__icon",
+  label: "data-club-ai-hub__theme-switcher__label",
+}) as ThemeSwitcherClassNames;
+
+/**
+ * Props for `<ThemeSwitcher />`.
+ */
+export interface ThemeSwitcherProps {
+  /** Whether to render a label next to the icon. Default true. */
+  showLabel?: boolean;
+  /** Wrapper-supplied i18n. */
+  texts?: DeepPartial<AIHubTexts>;
+  /** Extra class merged onto the root. */
+  className?: string;
+  /** Per-element class overrides. */
+  classNames?: Partial<ThemeSwitcherClassNames>;
+  /**
+   * Forwarded to the underlying button — only used by the test harness
+   * + Storybook stories that want to click the switcher without going
+   * through the provider's optimistic-update path.
+   */
+  onClick?: () => void;
+}
+
+/**
+ * Renders the switcher.
+ *
+ * @param props - see `ThemeSwitcherProps`.
+ * @returns the rendered switcher, or `null` when disabled by config.
+ */
+export function ThemeSwitcher(props: ThemeSwitcherProps): ReactNode {
+  const { theme, setTheme, themeSwitcherEnabled } = useAIHub();
+  const texts = resolveAIHubTexts(props.texts);
+  const chatTexts: AIHubChatTexts = texts.chat;
+  const cls = { ...DEFAULT_CLASS_NAMES, ...(props.classNames ?? {}) };
+  const showLabel = props.showLabel ?? true;
+
+  if (!themeSwitcherEnabled) return null;
+
+  const isDark = theme === "dark";
+  // `aria-checked` reflects "is dark on?" so the switcher is a
+  // 2-state switch (light ↔ dark), which matches sketches/00-shell.md.
+  const ariaLabel = isDark
+    ? chatTexts.themeSwitchToLightAriaLabel
+    : chatTexts.themeSwitchToDarkAriaLabel;
+  const visualLabel = isDark ? chatTexts.themeLightLabel : chatTexts.themeDarkLabel;
+  const icon = isDark ? "☀" : "☾";
+  const next: "light" | "dark" = isDark ? "light" : "dark";
+
+  const rootClass = [
+    cls.root,
+    isDark ? cls.rootDark : cls.rootLight,
+    props.className,
+  ]
+    .filter(Boolean)
+    .join(" ");
+
+  function handleClick(): void {
+    if (props.onClick) {
+      props.onClick();
+      return;
+    }
+    void setTheme(next);
+  }
+
+  return (
+    <button
+      type="button"
+      role="switch"
+      aria-checked={isDark}
+      aria-label={ariaLabel}
+      className={rootClass}
+      onClick={handleClick}
+      data-testid="theme-switcher"
+      data-theme-state={theme}
+    >
+      <span className={cls.icon} aria-hidden="true">
+        {icon}
+      </span>
+      {showLabel ? (
+        <span className={cls.label} data-testid="theme-switcher-label">
+          {visualLabel}
+        </span>
+      ) : null}
+    </button>
+  );
+}

package/src/components/ToolCallView/formatContent.ts

@@ -0,0 +1,50 @@
+/**
+ * Default display-side formatter for tool-call input/output text rendered
+ * inside `<ToolCallView />`.
+ *
+ * Tool inputs reach the UI as raw JSON text (assembled from
+ * `tool_call_input_delta` chunks); tool outputs are either a string from
+ * Letta or a `JSON.stringify` of the structured return. In both shapes,
+ * any newline inside a string value is encoded as the two-character
+ * sequence `\n`, which a `<pre>` element renders as the literal text
+ * `\n` instead of an actual line break. Same for `\t` / `\r`. That makes
+ * any multi-line tool payload (file diffs, command output, prompts)
+ * unreadable.
+ *
+ * Strategy:
+ *
+ *   1. Try `JSON.parse(raw)`. If it parses, re-stringify with 2-space
+ *      indent — that pretty-prints the structure.
+ *   2. Whether or not parsing succeeded, replace the whitespace escape
+ *      sequences (`\n`, `\t`, `\r`, including the `\r\n` pair) with
+ *      their literal characters so they render as real layout.
+ *
+ * The output is NOT valid JSON anymore — it's a display form. Other
+ * escapes (`\"`, `\\`, `\uXXXX`) are left alone because they're either
+ * still meaningful for the reader or rare enough that unescaping them
+ * would risk corrupting binary-ish content.
+ *
+ * Implementation projects that need different behavior (e.g. raw view
+ * for debugging) can pass their own `formatContent` to `<ToolCallView />`
+ * or pass identity (`(s) => s`).
+ *
+ * @param raw - the input or output string as carried on
+ *   `AIHubToolCallRecord` / the streaming tool-call accumulator.
+ * @returns the formatted string for display.
+ */
+export function formatToolContentForDisplay(raw: string): string {
+  if (raw === "") return raw;
+  let formatted = raw;
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    formatted = JSON.stringify(parsed, null, 2);
+  } catch {
+    // Not valid JSON (mid-stream chunk, plain text output, etc.) —
+    // fall through to the escape-sequence unwrap on the raw input.
+  }
+  return formatted
+    .replace(/\\r\\n/g, "\n")
+    .replace(/\\n/g, "\n")
+    .replace(/\\t/g, "\t")
+    .replace(/\\r/g, "\r");
+}

package/src/components/ToolCallView/index.tsx

@@ -0,0 +1,274 @@
+/**
+ * `<ToolCallView />` — collapsible tool-call card inside an assistant
+ * bubble.
+ *
+ * Header carries the tool name + status (`running`/`done`/`error`) +
+ * duration. Body shows input + output (or input + error). Default
+ * collapsed; click `[▶]` to expand. Tool errors do NOT fail the turn
+ * — the card stays as evidence of what happened (§10.3).
+ *
+ * Step 10 only renders tool calls when `toolCallsVisible` (resolved) is
+ * true. The decision lives in `MessageList`.
+ *
+ * Exported under `AIHub.ToolCallView`.
+ *
+ * @see SPECIFICATIONS.md §9.3 — tool events
+ * @see SPECIFICATIONS.md §10.3 — tool error vs. agent error
+ * @see ui-sketches/03-chat.md — tool_call_card
+ */
+
+import { useState, type ReactNode } from "react";
+
+import {
+  resolveAIHubTexts,
+  type AIHubTexts,
+  type DeepPartial,
+} from "../../auth/texts.js";
+import { formatToolContentForDisplay } from "./formatContent.js";
+
+/** Status of a tool call. */
+export type ToolCallStatus = "running" | "done" | "error";
+
+/** BEM class names emitted by `<ToolCallView />`. */
+export interface ToolCallViewClassNames {
+  /** Outer card. */
+  root: string;
+  /** Modifier — `--collapsed`. */
+  rootCollapsed: string;
+  /** Modifier — `--expanded`. */
+  rootExpanded: string;
+  /** Status modifier — `--running`. */
+  rootRunning: string;
+  /** Status modifier — `--done`. */
+  rootDone: string;
+  /** Status modifier — `--error`. */
+  rootError: string;
+  /** Header element. */
+  header: string;
+  /** Tool name inside header. */
+  toolName: string;
+  /** Status icon + text inside header. */
+  status: string;
+  /** Duration text inside header. */
+  duration: string;
+  /** Expand/collapse toggle. */
+  toggle: string;
+  /** Body element (mounted only when expanded). */
+  body: string;
+  /** Modifier on the body — `--error`. */
+  bodyError: string;
+  /** Input section. */
+  inputSection: string;
+  /** Output section. */
+  outputSection: string;
+  /** Section label (Input: / Output: / Error:). */
+  sectionLabel: string;
+  /** Section pre/code content. */
+  sectionContent: string;
+}
+
+const DEFAULT_CLASS_NAMES: ToolCallViewClassNames = Object.freeze({
+  root: "data-club-ai-hub__tool-call-card",
+  rootCollapsed: "data-club-ai-hub__tool-call-card--collapsed",
+  rootExpanded: "data-club-ai-hub__tool-call-card--expanded",
+  rootRunning: "data-club-ai-hub__tool-call-card--running",
+  rootDone: "data-club-ai-hub__tool-call-card--done",
+  rootError: "data-club-ai-hub__tool-call-card--error",
+  header: "data-club-ai-hub__tool-call-card__header",
+  toolName: "data-club-ai-hub__tool-call-card__tool-name",
+  status: "data-club-ai-hub__tool-call-card__status",
+  duration: "data-club-ai-hub__tool-call-card__duration",
+  toggle: "data-club-ai-hub__tool-call-card__toggle",
+  body: "data-club-ai-hub__tool-call-card__body",
+  bodyError: "data-club-ai-hub__tool-call-card__body--error",
+  inputSection: "data-club-ai-hub__tool-call-card__input-section",
+  outputSection: "data-club-ai-hub__tool-call-card__output-section",
+  sectionLabel: "data-club-ai-hub__tool-call-card__section-label",
+  sectionContent: "data-club-ai-hub__tool-call-card__section-content",
+}) as ToolCallViewClassNames;
+
+/** Props for `<ToolCallView />`. */
+export interface ToolCallViewProps {
+  /** Tool name (e.g. "search_web"). */
+  toolName: string;
+  /** Current status. Drives the icon + the body's error modifier. */
+  status: ToolCallStatus;
+  /** Tool input — pretty-printed JSON usually. */
+  input: string;
+  /** Tool output (only meaningful when `status === "done"`). */
+  output?: string;
+  /** Error message (only meaningful when `status === "error"`). */
+  error?: string;
+  /** Duration in seconds, when known. */
+  durationSeconds?: number;
+  /**
+   * Override initial expanded state. Default false (collapsed); the
+   * spec's `tool_call_card --collapsed` is the default visual.
+   *
+   * Ignored when `expanded` is passed (controlled mode).
+   */
+  defaultExpanded?: boolean;
+  /**
+   * Controlled expanded state. When set, `<ToolCallView />` defers all
+   * expand/collapse decisions to the parent — `onToggle` fires on the
+   * user's toggle click and the parent computes the next `expanded`.
+   * Used by `<MessageList />` to enforce the accordion +
+   * auto-expand-while-streaming rules across blocks. When omitted, the
+   * component falls back to internal `useState` (default-collapsed,
+   * per-instance toggle) for backward compatibility.
+   */
+  expanded?: boolean;
+  /**
+   * Toggle handler for the controlled mode. Fires on the user's click;
+   * the parent decides what to do with it. Ignored in uncontrolled mode.
+   */
+  onToggle?: () => void;
+  /** Wrapper-supplied i18n. */
+  texts?: DeepPartial<AIHubTexts>;
+  /** Extra class merged onto the root. */
+  className?: string;
+  /** Per-element class overrides. */
+  classNames?: Partial<ToolCallViewClassNames>;
+  /**
+   * Transform applied to the displayed `input` / `output` / `error`
+   * strings. Defaults to [[formatToolContentForDisplay]], which
+   * JSON-pretty-prints the value (when parseable) and unescapes the
+   * whitespace JSON-escape sequences (`\n`, `\t`, `\r`) so they render
+   * as actual layout. Pass `(s) => s` to opt out (e.g. for a raw
+   * debugging view), or supply a custom formatter to reshape the
+   * content (e.g. redact secrets).
+   */
+  formatContent?: (raw: string) => string;
+}
+
+/**
+ * Returns the BEM modifier for the status.
+ */
+function statusModifier(
+  status: ToolCallStatus,
+  cls: ToolCallViewClassNames,
+): string {
+  switch (status) {
+    case "running":
+      return cls.rootRunning;
+    case "done":
+      return cls.rootDone;
+    case "error":
+      return cls.rootError;
+  }
+}
+
+/**
+ * Returns the i18n status text for the header.
+ */
+function statusText(
+  status: ToolCallStatus,
+  chat: AIHubTexts["chat"],
+): string {
+  switch (status) {
+    case "running":
+      return chat.toolCallRunningStatus;
+    case "done":
+      return chat.toolCallDoneStatus;
+    case "error":
+      return chat.toolCallErrorStatus;
+  }
+}
+
+/**
+ * Renders the card.
+ *
+ * @param props - see `ToolCallViewProps`.
+ * @returns the rendered card.
+ */
+export function ToolCallView(props: ToolCallViewProps): ReactNode {
+  const texts = resolveAIHubTexts(props.texts);
+  const cls = { ...DEFAULT_CLASS_NAMES, ...(props.classNames ?? {}) };
+  const [uncontrolledExpanded, setUncontrolledExpanded] = useState(
+    props.defaultExpanded ?? false,
+  );
+  const isControlled = props.expanded !== undefined;
+  const expanded = isControlled ? (props.expanded as boolean) : uncontrolledExpanded;
+  const handleToggle = isControlled
+    ? props.onToggle ?? (() => {})
+    : () => setUncontrolledExpanded((e) => !e);
+
+  const seconds = props.durationSeconds ?? 0;
+  const durationText = seconds > 0 ? `(${seconds.toFixed(1)}s)` : "";
+  const formatContent = props.formatContent ?? formatToolContentForDisplay;
+
+  const rootClass = [
+    cls.root,
+    expanded ? cls.rootExpanded : cls.rootCollapsed,
+    statusModifier(props.status, cls),
+    props.className,
+  ]
+    .filter(Boolean)
+    .join(" ");
+  const bodyClass = [
+    cls.body,
+    props.status === "error" ? cls.bodyError : null,
+  ]
+    .filter(Boolean)
+    .join(" ");
+
+  return (
+    <div
+      className={rootClass}
+      data-testid="tool-call-view"
+      data-status={props.status}
+      data-expanded={expanded ? "true" : "false"}
+    >
+      <div className={cls.header}>
+        <span className={cls.toolName} data-testid="tool-call-view-name">
+          🔧 {props.toolName}
+        </span>
+        <span className={cls.status} data-testid="tool-call-view-status">
+          {statusText(props.status, texts.chat)}
+        </span>
+        {durationText ? (
+          <span className={cls.duration}>{durationText}</span>
+        ) : null}
+        <button
+          type="button"
+          className={cls.toggle}
+          onClick={handleToggle}
+          aria-expanded={expanded}
+          aria-label={
+            expanded
+              ? texts.chat.toolCallCollapseAriaLabel
+              : texts.chat.toolCallExpandAriaLabel
+          }
+          data-testid="tool-call-view-toggle"
+        >
+          {expanded ? "▼" : "▶"}
+        </button>
+      </div>
+      {expanded ? (
+        <div className={bodyClass} data-testid="tool-call-view-body">
+          <div className={cls.inputSection}>
+            <div className={cls.sectionLabel}>
+              {texts.chat.toolCallInputLabel}
+            </div>
+            <pre className={cls.sectionContent}>{formatContent(props.input)}</pre>
+          </div>
+          {props.status === "error" ? (
+            <div className={cls.outputSection}>
+              <div className={cls.sectionLabel}>
+                {texts.chat.toolCallErrorLabel}
+              </div>
+              <pre className={cls.sectionContent}>{formatContent(props.error ?? "")}</pre>
+            </div>
+          ) : props.output !== undefined ? (
+            <div className={cls.outputSection}>
+              <div className={cls.sectionLabel}>
+                {texts.chat.toolCallOutputLabel}
+              </div>
+              <pre className={cls.sectionContent}>{formatContent(props.output)}</pre>
+            </div>
+          ) : null}
+        </div>
+      ) : null}
+    </div>
+  );
+}