@data-club/ai-hub 0.0.1

package/src/components/TpmBanner/index.tsx

@@ -0,0 +1,172 @@
+/**
+ * `<TpmBanner />` — TPM-recovery banner with countdown.
+ *
+ * Specialization of `<SystemNotice />` that:
+ *
+ * 1. Reads the active turn's `tpm_retry_at` from `useAIHub().state` and
+ *    computes the remaining seconds at ~1Hz.
+ * 2. Switches variant based on §10.4: `tpm-wait` while `phase ===
+ *    waiting_provider`, transient `resumed` flash on the `running →
+ *    running(model_*)` recovery transition, and `error` when the
+ *    `lastTurnError` is `tpm_exhausted`.
+ * 3. Renders nothing when none of the conditions apply — components can
+ *    mount it unconditionally without flicker.
+ *
+ * The provider's reducer already clears `tpm_retry_at` on the `resumed`
+ * notice; the banner observes that change and shows the brief "Resumed."
+ * flash for 2s. The exhausted-error path renders a Retry button that
+ * re-issues the last user message (delegated to the parent via
+ * `onRetry`).
+ *
+ * @see SPECIFICATIONS.md §6.5 — TPM recovery
+ * @see SPECIFICATIONS.md §10.4 — predicates bound to (status, phase)
+ * @see ui-sketches/03-chat.md — system_notice variants
+ */
+
+import { useEffect, useState, type ReactNode } from "react";
+
+import {
+  resolveAIHubTexts,
+  type AIHubTexts,
+  type DeepPartial,
+} from "../../auth/texts.js";
+import { useAIHub } from "../../context/useAIHub.js";
+
+import { SystemNotice } from "../SystemNotice/index.js";
+
+/** Duration of the post-recovery "Resumed." flash, in milliseconds. */
+const RESUMED_FLASH_MS = 2000;
+
+/**
+ * Renders the countdown text by replacing `{seconds}` in the template.
+ *
+ * @param template - i18n template with `{seconds}` placeholder.
+ * @param seconds - integer seconds remaining; floors at 0.
+ * @returns the resolved text.
+ */
+function renderCountdown(template: string, seconds: number): string {
+  const safe = Math.max(0, Math.floor(seconds));
+  return template.replace("{seconds}", String(safe));
+}
+
+/**
+ * Computes seconds-until against an ISO timestamp.
+ *
+ * @param retryAt - ISO timestamp from `tpm_retry_at`.
+ * @param now - epoch ms (test injection point).
+ * @returns seconds remaining (>= 0). Returns 0 when `retryAt` is invalid.
+ */
+function secondsUntil(retryAt: string, now: number): number {
+  const target = Date.parse(retryAt);
+  if (!Number.isFinite(target)) return 0;
+  return Math.max(0, (target - now) / 1000);
+}
+
+/** Props for `<TpmBanner />`. */
+export interface TpmBannerProps {
+  /**
+   * Called when the user clicks the Retry button on the `--error`
+   * variant. Wraps `sendMessage` of the last user message; the parent
+   * decides what "last user message" means (the monolith threads its
+   * own ref through).
+   */
+  onRetry?: () => void;
+  /** Wrapper-supplied i18n. */
+  texts?: DeepPartial<AIHubTexts>;
+  /** Extra class merged onto the root. */
+  className?: string;
+  /**
+   * Override the resolved "now" — test injection point. Production code
+   * leaves this unset (defaults to `Date.now()` at each tick).
+   */
+  nowProvider?: () => number;
+}
+
+/**
+ * Renders the banner.
+ *
+ * @param props - see `TpmBannerProps`.
+ * @returns the rendered banner, or `null` when nothing should render.
+ */
+export function TpmBanner(props: TpmBannerProps): ReactNode {
+  const { state, lastTurnError } = useAIHub();
+  const texts = resolveAIHubTexts(props.texts);
+
+  // Tick at 1Hz while we're in the wait phase. The interval is
+  // re-installed when the deadline changes (new wait) or removed when
+  // we leave the wait phase.
+  const [, forceTick] = useState(0);
+  useEffect(() => {
+    if (state.phase !== "waiting_provider") return;
+    const tick = setInterval(() => {
+      forceTick((n) => n + 1);
+    }, 1000);
+    return () => clearInterval(tick);
+  }, [state.phase, state.tpm_retry_at]);
+
+  // Track the *previous* phase so the `running(waiting_provider) →
+  // running(model_*)` transition triggers the "Resumed." flash. We hold
+  // the flash on the screen for RESUMED_FLASH_MS, then clear.
+  const [showResumed, setShowResumed] = useState(false);
+  const [prevPhase, setPrevPhase] = useState(state.phase);
+  useEffect(() => {
+    if (
+      prevPhase === "waiting_provider" &&
+      state.phase !== "waiting_provider" &&
+      state.status === "running"
+    ) {
+      setShowResumed(true);
+      const t = setTimeout(() => setShowResumed(false), RESUMED_FLASH_MS);
+      setPrevPhase(state.phase);
+      return () => clearTimeout(t);
+    }
+    setPrevPhase(state.phase);
+    return undefined;
+  }, [state.phase, state.status]);
+
+  // Wait phase: render `--tpm-wait` with countdown.
+  if (state.phase === "waiting_provider" && state.tpm_retry_at) {
+    const now = (props.nowProvider ?? Date.now)();
+    const remaining = secondsUntil(state.tpm_retry_at, now);
+    return (
+      <SystemNotice
+        variant="tpm-wait"
+        message={renderCountdown(texts.chat.tpmWaitText, remaining)}
+        {...(props.className !== undefined ? { className: props.className } : {})}
+      />
+    );
+  }
+
+  // Brief "Resumed." flash right after a successful recovery.
+  if (showResumed) {
+    return (
+      <SystemNotice
+        variant="resumed"
+        message={texts.chat.systemResumedText}
+        {...(props.className !== undefined ? { className: props.className } : {})}
+      />
+    );
+  }
+
+  // Exhausted-error path — the provider sets `lastTurnError` on
+  // `error{tpm_exhausted}` + `stream_end{error}`. The retry button only
+  // surfaces here (the generic `--failed` Retry button on the message
+  // bubble is the equivalent for non-TPM failures).
+  if (
+    lastTurnError &&
+    lastTurnError.toLowerCase().includes("rate")
+  ) {
+    return (
+      <SystemNotice
+        variant="error"
+        message={texts.chat.tpmExhaustedText}
+        {...(props.onRetry !== undefined
+          ? { action: { label: texts.chat.tpmRetryButton, onClick: props.onRetry } }
+          : {})}
+        {...(props.className !== undefined ? { className: props.className } : {})}
+      />
+    );
+  }
+
+  return null;
+}

package/src/components/TurnStatusIndicator/index.tsx

@@ -0,0 +1,203 @@
+/**
+ * `<TurnStatusIndicator />` — a small `●` dot + short label reflecting the
+ * active turn's `(status, phase)`.
+ *
+ * Pure function of state (via `turnStatusVisual` in `state/affordances.ts`).
+ * Two soft-state behaviors are local to the component:
+ *
+ * 1. **`done` flash.** On the transition `running → done`, the indicator
+ *    briefly shows "Done" (~2s) and then settles to "Ready" — this is the
+ *    visual "the turn finished" affordance the predicate table calls for.
+ * 2. **`cancelled` auto-clear.** After ~3s the indicator clears back to
+ *    "Ready" so the cancelled stamp doesn't sit forever in the header.
+ *
+ * Both timers respect `prefers-reduced-motion` by skipping the pulse
+ * animation; the timer logic still runs, but the dot stays static.
+ *
+ * Rendering is gated by:
+ *
+ * - the `showTurnStatus` React prop (default true) AND
+ * - the `turn_status_visible` server toggle (§8.4) — precedence: server > prop.
+ *
+ * Both gates are AND-combined in `useAffordanceFlags` upstream so the
+ * primitive itself only checks `if (!visible) return null`.
+ *
+ * Exported under `AIHub.TurnStatusIndicator`.
+ *
+ * @see SPECIFICATIONS.md §10.4 — predicate table + label map
+ * @see ui-sketches/03-chat.md — turn_status_indicator
+ */
+
+import { useEffect, useRef, useState, type ReactNode } from "react";
+
+import { useAIHub } from "../../context/useAIHub.js";
+import { turnStatusVisual } from "../../state/affordances.js";
+import type {
+  AIHubState,
+  RunningPhase,
+  TurnStatus,
+} from "../../types.js";
+
+/**
+ * BEM class names emitted by `<TurnStatusIndicator />`.
+ */
+export interface TurnStatusIndicatorClassNames {
+  /** Outer wrapper. */
+  root: string;
+  /** Dot element — pulse animation hooks here. */
+  dot: string;
+  /** Modifier on the dot — `--idle` (gray static). */
+  dotIdle: string;
+  /** Modifier on the dot — `--running` (accent pulsing). */
+  dotRunning: string;
+  /** Modifier on the dot — `--warning` (yellow pulsing). */
+  dotWarning: string;
+  /** Modifier on the dot — `--error` (red static). */
+  dotError: string;
+  /** Modifier added when pulsing is allowed (drops under reduced-motion). */
+  dotPulse: string;
+  /** Label text. */
+  label: string;
+}
+
+const DEFAULT_CLASS_NAMES: TurnStatusIndicatorClassNames = Object.freeze({
+  root: "data-club-ai-hub__turn-status",
+  dot: "data-club-ai-hub__turn-status__dot",
+  dotIdle: "data-club-ai-hub__turn-status__dot--idle",
+  dotRunning: "data-club-ai-hub__turn-status__dot--running",
+  dotWarning: "data-club-ai-hub__turn-status__dot--warning",
+  dotError: "data-club-ai-hub__turn-status__dot--error",
+  dotPulse: "data-club-ai-hub__turn-status__dot--pulse",
+  label: "data-club-ai-hub__turn-status__label",
+}) as TurnStatusIndicatorClassNames;
+
+/**
+ * Maps the visual variant to its modifier class.
+ */
+function dotModifier(
+  variant: "idle" | "running" | "warning" | "error",
+  cls: TurnStatusIndicatorClassNames,
+): string {
+  switch (variant) {
+    case "running":
+      return cls.dotRunning;
+    case "warning":
+      return cls.dotWarning;
+    case "error":
+      return cls.dotError;
+    case "idle":
+      return cls.dotIdle;
+  }
+}
+
+/**
+ * Props for `<TurnStatusIndicator />`.
+ *
+ * `state` is optional — when omitted the component reads it from the
+ * provider via `useAIHub()`. Passing it explicitly is useful for the
+ * Storybook stories (Step 10 ships them for every cell of the §10.4
+ * table) and for the test harness, both of which render the indicator
+ * in isolation without a real reducer in scope.
+ */
+export interface TurnStatusIndicatorProps {
+  /** Override the state read from context (used by stories + tests). */
+  state?: AIHubState;
+  /** Extra class merged onto the root. */
+  className?: string;
+  /** Per-element class overrides. */
+  classNames?: Partial<TurnStatusIndicatorClassNames>;
+}
+
+/**
+ * Duration of the post-done "Done" flash, in milliseconds. After this
+ * expires the indicator settles back to "Ready" (`idle` dot).
+ */
+const DONE_FLASH_MS = 2000;
+
+/**
+ * Duration of the post-cancel "Cancelled" stamp, in milliseconds.
+ */
+const CANCELLED_CLEAR_MS = 3000;
+
+/**
+ * Renders the indicator.
+ *
+ * @param props - see `TurnStatusIndicatorProps`.
+ * @returns the rendered indicator.
+ */
+export function TurnStatusIndicator(
+  props: TurnStatusIndicatorProps,
+): ReactNode {
+  const ctx = useAIHub();
+  const state = props.state ?? ctx.state;
+  const cls = { ...DEFAULT_CLASS_NAMES, ...(props.classNames ?? {}) };
+
+  // Capture the *effective* status / phase for rendering. After done /
+  // cancelled clear timers expire we treat the state as `idle` so the
+  // dot doesn't sit on "Done" forever.
+  const [effective, setEffective] = useState<{
+    status: TurnStatus;
+    phase: RunningPhase | null;
+  }>({ status: state.status, phase: state.phase });
+
+  // Track the previous status so we know when to start the
+  // done/cancelled clear timer (state only updates on transitions).
+  const prevStatusRef = useRef<TurnStatus>(state.status);
+
+  useEffect(() => {
+    const prev = prevStatusRef.current;
+    prevStatusRef.current = state.status;
+
+    // No timer needed when the status is steady at running or idle.
+    if (state.status === prev) {
+      setEffective({ status: state.status, phase: state.phase });
+      return;
+    }
+
+    // Fresh state — lift it.
+    setEffective({ status: state.status, phase: state.phase });
+
+    if (state.status === "done") {
+      const t = setTimeout(() => {
+        setEffective({ status: "idle", phase: null });
+      }, DONE_FLASH_MS);
+      return () => clearTimeout(t);
+    }
+    if (state.status === "cancelled") {
+      const t = setTimeout(() => {
+        setEffective({ status: "idle", phase: null });
+      }, CANCELLED_CLEAR_MS);
+      return () => clearTimeout(t);
+    }
+    return undefined;
+  }, [state.status, state.phase]);
+
+  const visual = turnStatusVisual(effective.status, effective.phase);
+  const rootClass = props.className
+    ? `${cls.root} ${props.className}`
+    : cls.root;
+  const dotClass = [
+    cls.dot,
+    dotModifier(visual.dot, cls),
+    visual.pulse ? cls.dotPulse : null,
+  ]
+    .filter(Boolean)
+    .join(" ");
+
+  return (
+    <div
+      className={rootClass}
+      data-testid="turn-status-indicator"
+      data-status={effective.status}
+      data-phase={effective.phase ?? "none"}
+      data-variant={visual.dot}
+      role="status"
+      aria-live="polite"
+    >
+      <span className={dotClass} aria-hidden="true" />
+      <span className={cls.label} data-testid="turn-status-label">
+        {visual.label}
+      </span>
+    </div>
+  );
+}

package/src/components/internal/PasswordInput.tsx

@@ -0,0 +1,145 @@
+/**
+ * `<PasswordInput>` — internal helper used by `<DataClubAIHubLogin />` and
+ * `<DataClubAIHubChangePassword />` to render a password field with its own
+ * show/hide eye-icon toggle.
+ *
+ * The toggle is **per-field** (each input owns its own state) so a user
+ * can reveal one field while keeping another masked — useful for visually
+ * verifying a match between New and Confirm without exposing both at once.
+ *
+ * Not exported from the package (no JSDoc-required interface surfaces here);
+ * lives under `components/internal/` to make that explicit.
+ *
+ * @see ui-sketches/01-login.md — show_password_toggle
+ * @see ui-sketches/02-change-password.md — per-field toggle
+ */
+
+import { useState, type ReactNode } from "react";
+
+/**
+ * Props for the internal `<PasswordInput>` helper.
+ */
+export interface PasswordInputProps {
+  /** Stable DOM id used by the label + `aria-describedby` if any. */
+  id: string;
+  /** Input value. */
+  value: string;
+  /** Change handler — receives the next plaintext value. */
+  onChange: (next: string) => void;
+  /** Native `name` attribute for autofill / form submission. */
+  name: string;
+  /** Native `autoComplete` value — caller picks per field. */
+  autoComplete?: string;
+  /** Placeholder text. Defaults to "••••••••". */
+  placeholder?: string;
+  /** Whether the input is disabled (e.g. during submit). */
+  disabled?: boolean;
+  /** Whether to autofocus on mount. */
+  autoFocus?: boolean;
+  /** Required field — mirrors HTML `required` for browser-side validation. */
+  required?: boolean;
+  /** `aria-label` for the toggle when the password is currently hidden. */
+  showAriaLabel: string;
+  /** `aria-label` for the toggle when the password is currently shown. */
+  hideAriaLabel: string;
+  /** BEM class for the wrapper `<div>` that holds the input + toggle. */
+  wrapperClassName: string;
+  /** BEM class for the `<input>` itself. */
+  inputClassName: string;
+  /** BEM class for the toggle `<button>`. */
+  toggleClassName: string;
+  /** Optional `data-testid` on the wrapper — used by RTL tests. */
+  testId?: string;
+}
+
+/**
+ * Renders a password field with a show/hide eye-icon toggle.
+ *
+ * The toggle is `type="button"` (not submit) and keyboard-accessible
+ * (Enter / Space activate without submitting the surrounding form).
+ *
+ * @param props - the input props.
+ * @returns the input + toggle pair.
+ */
+export function PasswordInput(props: PasswordInputProps): ReactNode {
+  const {
+    id,
+    value,
+    onChange,
+    name,
+    autoComplete,
+    placeholder = "••••••••",
+    disabled,
+    autoFocus,
+    required,
+    showAriaLabel,
+    hideAriaLabel,
+    wrapperClassName,
+    inputClassName,
+    toggleClassName,
+    testId,
+  } = props;
+
+  const [revealed, setRevealed] = useState(false);
+
+  return (
+    <div
+      className={wrapperClassName}
+      {...(testId !== undefined ? { "data-testid": testId } : {})}
+    >
+      <input
+        id={id}
+        type={revealed ? "text" : "password"}
+        value={value}
+        onChange={(e) => onChange(e.target.value)}
+        name={name}
+        {...(autoComplete !== undefined ? { autoComplete } : {})}
+        placeholder={placeholder}
+        disabled={disabled}
+        autoFocus={autoFocus}
+        required={required}
+        className={inputClassName}
+      />
+      <button
+        type="button"
+        className={toggleClassName}
+        aria-label={revealed ? hideAriaLabel : showAriaLabel}
+        aria-pressed={revealed}
+        onClick={() => setRevealed((r) => !r)}
+        tabIndex={0}
+      >
+        {/* Inline SVG — sized via CSS, color follows currentColor. */}
+        <EyeIcon open={revealed} />
+      </button>
+    </div>
+  );
+}
+
+/**
+ * Inline eye icon. Two paths so the open / closed variants share weight
+ * and stroke caps without two `<svg>` trees.
+ *
+ * @param props - icon props.
+ * @param props.open - true → "show" (eye), false → "hide" (eye with slash).
+ */
+function EyeIcon(props: { open: boolean }): ReactNode {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      viewBox="0 0 24 24"
+      width="18"
+      height="18"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+      focusable="false"
+    >
+      <path d="M2 12s3.5-7 10-7 10 7 10 7-3.5 7-10 7S2 12 2 12z" />
+      <circle cx="12" cy="12" r="3" />
+      {!props.open ? <path d="M3 3l18 18" /> : null}
+    </svg>
+  );
+}