@data-club/ai-hub 0.0.1

package/src/stories/MarkdownRenderer.stories.tsx

@@ -0,0 +1,201 @@
+/**
+ * Stories for `<MarkdownRenderer />` — the assistant-bubble body
+ * renderer that turns GFM markdown (+ LaTeX-style math) into themed HTML.
+ *
+ * Each story feeds a curated chunk of markdown so designers can eyeball
+ * one feature at a time (paragraphs, tables, code blocks, math…) without
+ * having to spin up a real chat turn. The "Showcase" story stitches all
+ * of them together — that's the one to load when checking the renderer
+ * end-to-end after a CSS-token tweak.
+ *
+ * @see docs/react/markdown-rendering.md
+ */
+import type { Meta, StoryObj } from "@storybook/react-vite";
+
+import { MarkdownRenderer } from "../components/MarkdownRenderer/index.js";
+
+const meta: Meta<typeof MarkdownRenderer> = {
+  title: "Affordances/MarkdownRenderer",
+  component: MarkdownRenderer,
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Renders assistant-bubble bodies as GitHub-flavored Markdown with KaTeX math. Per-customer wrappers theme it via the `--dc-aih-markdown-*` custom properties (default mappings live in `src/styles/default.css`).",
+      },
+    },
+  },
+};
+export default meta;
+type Story = StoryObj<typeof MarkdownRenderer>;
+
+export const Paragraphs: Story = {
+  args: {
+    content: [
+      "This is a **bold** statement with some *emphasis*, an [inline link](https://example.com), and ~~strikethrough~~ for good measure.",
+      "",
+      "Second paragraph — separated by a blank line. Inline code looks like `const x = 42;`.",
+    ].join("\n"),
+  },
+};
+
+export const HeadingsAndLists: Story = {
+  args: {
+    content: [
+      "# Heading 1",
+      "## Heading 2",
+      "### Heading 3",
+      "",
+      "Unordered list:",
+      "- First item",
+      "- Second item",
+      "  - Nested item",
+      "- Third item",
+      "",
+      "Ordered list:",
+      "1. Step one",
+      "2. Step two",
+      "3. Step three",
+    ].join("\n"),
+  },
+};
+
+export const Tables: Story = {
+  args: {
+    content: [
+      "| Plan | Monthly | Annual |",
+      "|------|---------|--------|",
+      "| Starter | $9 | $90 |",
+      "| Pro | $29 | $290 |",
+      "| Enterprise | Contact us | Contact us |",
+      "",
+      "Wide tables are horizontally scrollable, so the bubble keeps its `max-width: 80%` even when the table doesn't fit:",
+      "",
+      "| Region | Q1 | Q2 | Q3 | Q4 | Total | YoY % | Notes |",
+      "|--------|----|----|----|----|-------|-------|-------|",
+      "| EMEA | 120 | 134 | 142 | 158 | 554 | +18% | Growth driven by DACH region |",
+      "| APAC | 87 | 95 | 110 | 121 | 413 | +24% | Strong tailwind from JP launches |",
+      "| Americas | 210 | 215 | 219 | 240 | 884 | +6% | Mature market, steady |",
+    ].join("\n"),
+  },
+};
+
+export const CodeBlocks: Story = {
+  args: {
+    content: [
+      "Here's a TypeScript snippet:",
+      "",
+      "```ts",
+      "function greet(name: string): string {",
+      "  return `Hello, ${name}!`;",
+      "}",
+      "",
+      "const message = greet('world');",
+      "console.log(message);",
+      "```",
+      "",
+      "And a Python one:",
+      "",
+      "```python",
+      "def fibonacci(n: int) -> int:",
+      "    if n < 2:",
+      "        return n",
+      "    return fibonacci(n - 1) + fibonacci(n - 2)",
+      "```",
+    ].join("\n"),
+  },
+};
+
+export const MathEquations: Story = {
+  args: {
+    content: [
+      "Inline math: the Pythagorean identity is $a^2 + b^2 = c^2$.",
+      "",
+      "Block math:",
+      "",
+      "$$",
+      "\\int_0^\\infty e^{-x^2} \\, dx = \\frac{\\sqrt{\\pi}}{2}",
+      "$$",
+      "",
+      "The quadratic formula:",
+      "",
+      "$$",
+      "x = \\frac{-b \\pm \\sqrt{b^2 - 4ac}}{2a}",
+      "$$",
+      "",
+      "Euler's identity, $e^{i\\pi} + 1 = 0$, links five fundamental constants.",
+    ].join("\n"),
+  },
+};
+
+export const Blockquotes: Story = {
+  args: {
+    content: [
+      "> This is a blockquote. It's typically used to highlight a quote, an aside, or a callout from another source.",
+      ">",
+      "> Multi-paragraph quotes work too.",
+      "",
+      "Back to regular text.",
+    ].join("\n"),
+  },
+};
+
+export const Showcase: Story = {
+  args: {
+    content: [
+      "# Markdown showcase",
+      "",
+      "This story renders every feature the chat supports — use it as a regression sanity-check after touching `--dc-aih-markdown-*` tokens.",
+      "",
+      "## Inline formatting",
+      "",
+      "Mix of **bold**, *italic*, `inline code`, [a link](https://example.com), and ~~strikethrough~~.",
+      "",
+      "## Lists",
+      "",
+      "- Apples",
+      "- Oranges",
+      "  - Mandarins",
+      "  - Clementines",
+      "- Bananas",
+      "",
+      "1. Mise en place",
+      "2. Sauté the aromatics",
+      "3. Simmer until thickened",
+      "",
+      "## Tables",
+      "",
+      "| Customer | MRR | Tier |",
+      "|----------|-----|------|",
+      "| Acme Co. | $9,400 | Enterprise |",
+      "| Globex   | $2,100 | Pro |",
+      "| Initech  |   $290 | Starter |",
+      "",
+      "## Code",
+      "",
+      "```ts",
+      "export function sum(xs: number[]): number {",
+      "  return xs.reduce((a, b) => a + b, 0);",
+      "}",
+      "```",
+      "",
+      "## Math",
+      "",
+      "The sum of the first $n$ natural numbers is",
+      "",
+      "$$",
+      "\\sum_{k=1}^{n} k = \\frac{n(n+1)}{2}.",
+      "$$",
+      "",
+      "## Blockquote",
+      "",
+      "> The best way to predict the future is to invent it.",
+      ">",
+      "> — Alan Kay",
+      "",
+      "---",
+      "",
+      "End of showcase.",
+    ].join("\n"),
+  },
+};

package/src/stories/MessageBubble.stories.tsx

@@ -0,0 +1,101 @@
+/**
+ * Stories for the message-bubble variants emitted by `<MessageList />`.
+ *
+ * The bubble is not a separate primitive — it's the inner element of
+ * `MessageList`. Each story mounts a full `<MessageList />` under a
+ * `MockProvider` whose `messages` array + reducer `state` produces the
+ * variant under inspection (user / assistant / system / tool / failed
+ * assistant / cancelled assistant).
+ *
+ * @see SPECIFICATIONS.md §7.3 — message bubble variants
+ * @see ui-sketches/03-chat.md
+ */
+import type { Meta, StoryObj } from "@storybook/react-vite";
+
+import { MessageList } from "../components/MessageList/index.js";
+import type { AIHubMessage } from "../types.js";
+
+import { MockProvider, type MockProviderOpts } from "./_mockProvider.js";
+
+function msg(
+  id: string,
+  role: AIHubMessage["role"],
+  content: string,
+): AIHubMessage {
+  return {
+    id,
+    role,
+    content,
+    created_at: "2026-05-13T12:00:00.000Z",
+  };
+}
+
+function withProvider(opts: MockProviderOpts) {
+  return (Story: () => React.ReactNode) => (
+    <MockProvider opts={{ activeSessionId: "s-mock", ...opts }}>
+      <div style={{ height: "32rem", display: "flex" }}>
+        <Story />
+      </div>
+    </MockProvider>
+  );
+}
+
+const HISTORY: AIHubMessage[] = [
+  msg("m1", "user", "Why did my last turn fail?"),
+  msg(
+    "m2",
+    "assistant",
+    "Looking at the logs, the upstream provider returned a 429 and we exhausted the retry budget.",
+  ),
+  msg(
+    "m3",
+    "system",
+    "Notice: deployment-wide TPM recovery is configured for 5 retries with 30s backoff.",
+  ),
+  msg("m4", "tool", "search_docs → 3 results returned"),
+];
+
+const meta: Meta<typeof MessageList> = {
+  title: "Affordances/MessageBubble",
+  component: MessageList,
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Each story mounts `<MessageList />` with a curated `messages` array + reducer state so the resulting DOM shows one of the six bubble variants (user / assistant / system / tool / failed assistant / cancelled assistant).",
+      },
+    },
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof MessageList>;
+
+export const Mixed_AllVariants: Story = {
+  decorators: [withProvider({ status: "idle", messages: HISTORY })],
+};
+
+export const FailedAssistant: Story = {
+  decorators: [
+    withProvider({
+      status: "failed",
+      lastTurnError: "Stream failed: upstream provider unavailable.",
+      messages: [
+        msg("m1", "user", "Summarize the last release."),
+        msg("m2", "assistant", "Sure, here's what I have so far —"),
+      ],
+    }),
+  ],
+};
+
+export const CancelledAssistant: Story = {
+  decorators: [
+    withProvider({
+      status: "cancelled",
+      messages: [
+        msg("m1", "user", "Run a long simulation."),
+        msg("m2", "assistant", "Starting the simulation now…"),
+      ],
+    }),
+  ],
+};

package/src/stories/ReasoningView.stories.tsx

@@ -0,0 +1,81 @@
+/**
+ * Stories for `<ReasoningView />` — collapsible reasoning block inside
+ * an assistant bubble.
+ *
+ * Pure presentational primitive (no context needed).
+ *
+ * @see SPECIFICATIONS.md §7.3 — showReasoning prop
+ */
+import type { Meta, StoryObj } from "@storybook/react-vite";
+
+import { ReasoningView } from "../components/ReasoningView/index.js";
+
+const SAMPLE_REASONING = [
+  "The user is asking about the difference between a tool error and an",
+  "agent error. The §10.3 rule states that tool errors do NOT fail the",
+  "turn — phase reverts to model_text and the model gets a chance to",
+  "react. Only agent errors transition the turn to failed.",
+].join(" ");
+
+const meta: Meta<typeof ReasoningView> = {
+  title: "Affordances/ReasoningView",
+  component: ReasoningView,
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Collapsible reasoning block. Default-collapsed; the header shows duration once known. Streaming mode replaces the body with a placeholder until deltas arrive.",
+      },
+    },
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof ReasoningView>;
+
+export const Collapsed: Story = {
+  args: {
+    content: SAMPLE_REASONING,
+    durationSeconds: 2.4,
+    defaultExpanded: false,
+  },
+};
+
+export const Expanded: Story = {
+  args: {
+    content: SAMPLE_REASONING,
+    durationSeconds: 2.4,
+    defaultExpanded: true,
+  },
+};
+
+export const Streaming: Story = {
+  args: {
+    content: "",
+    streaming: true,
+    defaultExpanded: true,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "While reasoning deltas are arriving, the duration is unknown and the body shows a placeholder until the first chunks land.",
+      },
+    },
+  },
+};
+
+export const WithDuration: Story = {
+  args: {
+    content: SAMPLE_REASONING,
+    durationSeconds: 12.7,
+    defaultExpanded: true,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: "Longer reasoning — the header surfaces the wall-clock duration.",
+      },
+    },
+  },
+};

package/src/stories/ScrollToPresentButton.stories.tsx

@@ -0,0 +1,52 @@
+/**
+ * Stories for `<ScrollToPresentButton />` — floating "↓ Jump to latest"
+ * button.
+ *
+ * The §10.4 predicate (`status === "running" && userScrolledAwayFromBottom`)
+ * is computed by the parent; the primitive itself only checks the
+ * `visible` prop.
+ *
+ * @see SPECIFICATIONS.md §10.4
+ */
+import type { Meta, StoryObj } from "@storybook/react-vite";
+
+import { ScrollToPresentButton } from "../components/ScrollToPresentButton/index.js";
+
+const meta: Meta<typeof ScrollToPresentButton> = {
+  title: "Affordances/ScrollToPresentButton",
+  component: ScrollToPresentButton,
+  parameters: {
+    layout: "centered",
+    docs: {
+      description: {
+        component:
+          "Floating button that appears when the user has scrolled away from the bottom during a running turn. The parent computes the predicate; the primitive only respects `visible`.",
+      },
+    },
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof ScrollToPresentButton>;
+
+export const Visible: Story = {
+  args: {
+    visible: true,
+    onClick: () => undefined,
+  },
+};
+
+export const Hidden: Story = {
+  args: {
+    visible: false,
+    onClick: () => undefined,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "When `visible` is false the primitive returns `null` — there is no DOM element to inspect, but the story documents the contract.",
+      },
+    },
+  },
+};

package/src/stories/SystemNotice.stories.tsx

@@ -0,0 +1,59 @@
+/**
+ * Stories for `<SystemNotice />` — TPM wait / resumed / error banners.
+ *
+ * Pure presentational primitive — no context needed.
+ *
+ * @see SPECIFICATIONS.md §9.4 — system_notice events
+ */
+import type { Meta, StoryObj } from "@storybook/react-vite";
+
+import { SystemNotice } from "../components/SystemNotice/index.js";
+
+const meta: Meta<typeof SystemNotice> = {
+  title: "Affordances/SystemNotice",
+  component: SystemNotice,
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Banner for TPM-recovery + non-fatal errors. Variants: `tpm-wait` (countdown), `resumed` (transient flash), `error` (with optional retry button).",
+      },
+    },
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof SystemNotice>;
+
+export const TpmWait: Story = {
+  args: {
+    variant: "tpm-wait",
+    message: "Provider rate-limited — retrying in 47s",
+  },
+};
+
+export const Resumed: Story = {
+  args: {
+    variant: "resumed",
+    message: "Resumed.",
+  },
+};
+
+export const ErrorWithAction: Story = {
+  args: {
+    variant: "error",
+    message:
+      "Recovery exhausted — the model is unavailable. Try again in a moment.",
+    action: {
+      label: "Retry",
+      onClick: () => undefined,
+    },
+  },
+};
+
+export const ErrorNoAction: Story = {
+  args: {
+    variant: "error",
+    message: "Something went wrong on the server. Contact your administrator.",
+  },
+};

package/src/stories/ThemeSwitcher.stories.tsx

@@ -0,0 +1,55 @@
+/**
+ * Stories for `<ThemeSwitcher />` — sun/moon toggle, also renders
+ * nothing when the deployment has the switcher disabled.
+ *
+ * @see SPECIFICATIONS.md §7.6 — theme resolution
+ */
+import type { Meta, StoryObj } from "@storybook/react-vite";
+
+import { ThemeSwitcher } from "../components/ThemeSwitcher/index.js";
+
+import { MockProvider, type MockProviderOpts } from "./_mockProvider.js";
+
+function withProvider(opts: MockProviderOpts) {
+  return (Story: () => React.ReactNode) => (
+    <MockProvider opts={opts}>
+      <Story />
+    </MockProvider>
+  );
+}
+
+const meta: Meta<typeof ThemeSwitcher> = {
+  title: "Affordances/ThemeSwitcher",
+  component: ThemeSwitcher,
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Sun/moon switch that calls `setTheme()` on the provider. Renders nothing when `themeSwitcherEnabled === false`.",
+      },
+    },
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof ThemeSwitcher>;
+
+export const LightActive: Story = {
+  decorators: [withProvider({ theme: "light", themeSwitcherEnabled: true })],
+};
+
+export const DarkActive: Story = {
+  decorators: [withProvider({ theme: "dark", themeSwitcherEnabled: true })],
+};
+
+export const SwitcherDisabled: Story = {
+  decorators: [withProvider({ theme: "light", themeSwitcherEnabled: false })],
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "When the super_admin has disabled the switcher, the primitive renders `null` — there is nothing to inspect in the DOM.",
+      },
+    },
+  },
+};

package/src/stories/ToolCallView.stories.tsx

@@ -0,0 +1,95 @@
+/**
+ * Stories for `<ToolCallView />` — collapsible tool-call card.
+ *
+ * Per §10.3 a tool error does NOT fail the turn — the card stays as
+ * evidence of what happened. Stories cover running / done / error
+ * variants in both collapsed + expanded states.
+ *
+ * @see SPECIFICATIONS.md §9.3 — tool events
+ * @see SPECIFICATIONS.md §10.3 — tool error vs. agent error
+ */
+import type { Meta, StoryObj } from "@storybook/react-vite";
+
+import { ToolCallView } from "../components/ToolCallView/index.js";
+
+const SAMPLE_INPUT = JSON.stringify(
+  { query: "wire protocol §9.3", max_results: 5 },
+  null,
+  2,
+);
+
+const SAMPLE_OUTPUT = JSON.stringify(
+  {
+    results: [
+      { title: "9.3 — Tool events", url: "/docs/SPECIFICATIONS.md#tool-events" },
+    ],
+  },
+  null,
+  2,
+);
+
+const meta: Meta<typeof ToolCallView> = {
+  title: "Affordances/ToolCallView",
+  component: ToolCallView,
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Tool-call card showing name, status (running/done/error), and duration. Body holds input + output (or input + error). Default collapsed.",
+      },
+    },
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof ToolCallView>;
+
+export const RunningCollapsed: Story = {
+  args: {
+    toolName: "search_docs",
+    status: "running",
+    input: SAMPLE_INPUT,
+    defaultExpanded: false,
+  },
+};
+
+export const DoneCollapsed: Story = {
+  args: {
+    toolName: "search_docs",
+    status: "done",
+    input: SAMPLE_INPUT,
+    output: SAMPLE_OUTPUT,
+    durationSeconds: 1.8,
+    defaultExpanded: false,
+  },
+};
+
+export const DoneExpanded: Story = {
+  args: {
+    toolName: "search_docs",
+    status: "done",
+    input: SAMPLE_INPUT,
+    output: SAMPLE_OUTPUT,
+    durationSeconds: 1.8,
+    defaultExpanded: true,
+  },
+};
+
+export const ErrorExpanded: Story = {
+  args: {
+    toolName: "search_docs",
+    status: "error",
+    input: SAMPLE_INPUT,
+    error: "TimeoutError: upstream search took longer than 10s",
+    durationSeconds: 10.0,
+    defaultExpanded: true,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "A tool-side failure surfaces in the card body. Per §10.3 the turn stays running — the model gets `tool_call_result {error}` and decides what to do next.",
+      },
+    },
+  },
+};