hazo_ui 3.2.1 → 3.3.0

package/CHANGE_LOG.md

@@ -5,6 +5,42 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## v3.3.0 — 2026-06-11
+
+**New:** Required `doc` field on `Case` + per-case documentation accordion in `AutoTestRunner`.
+
+Every test case registered via `registerScenario` must now declare a `doc: CaseDoc` with four
+required string fields: `description`, `inputs`, `expectedOutputs`, and `caveats`. The field is
+enforced at the type level — a case without `doc` fails `tsc`. All 20 existing scenario files
+across the hazo workspace have been backfilled in this release.
+
+The `AutoTestRunner` renders a `▸/▾` caret toggle next to each case name. Clicking it expands a
+doc panel showing the four fields as labeled sections (Description / Inputs / Expected outputs /
+Caveats). Failed-case error output and "Copy prompt" behaviour are unchanged.
+
+**Exports added:** `CaseDoc` is now part of the public `hazo_ui/test-harness` surface.
+
+```ts
+import { registerScenario, type CaseDoc } from "hazo_ui/test-harness";
+
+registerScenario("my-pkg", {
+  name: "My Package",
+  pkg: "my-pkg",
+  cases: [
+    {
+      name: "creates a record",
+      doc: {
+        description: "Verifies that createRecord() inserts a row and returns the new ID.",
+        inputs: "A mock DB adapter seeded with an empty table; payload { title: 'hello' }.",
+        expectedOutputs: "Resolved string ID, table row count increases to 1.",
+        caveats: "None",
+      },
+      run: async () => { /* ... */ },
+    },
+  ],
+});
+```
+
 ## v3.2.0 — 2026-05-31
 
 **New:** `MarkdownEditor` — a generic, SSR-safe Markdown/MDX editor.

package/README.md

@@ -3920,13 +3920,18 @@ export default function RootLayout({ children }) {
 // test-app/scenarios/my_feature.ts
 import { registerScenario, assertEqual } from 'hazo_ui/test-harness';
 
-registerScenario({
-  id: 'my_feature',
+registerScenario('my_feature', {
   name: 'My Feature',
   pkg: 'my_pkg',
   cases: [
     {
       name: 'returns correct value',
+      doc: {
+        description: 'Verifies that myFunction adds two numbers correctly.',
+        inputs: 'myFunction(1, 2)',
+        expectedOutputs: 'Returns 3.',
+        caveats: 'None',
+      },
       run: async () => {
         const result = myFunction(1, 2);
         assertEqual(result, 3, 'should add two numbers');
@@ -3934,6 +3939,12 @@ registerScenario({
     },
     {
       name: 'throws on invalid input',
+      doc: {
+        description: 'Verifies that myFunction rejects null as the first argument.',
+        inputs: 'myFunction(null, 2)',
+        expectedOutputs: 'Throws an error containing "invalid input".',
+        caveats: 'None',
+      },
       run: async () => {
         await assertThrows(() => myFunction(null, 2), 'invalid input');
       },
@@ -3954,6 +3965,22 @@ export default function MyFeaturePage() {
 }
 ```
 
+### Case documentation (`doc` — required)
+
+Every case **must** include a `doc: CaseDoc` field. This is enforced at the TypeScript level — omitting it is a compile error. The `AutoTestRunner` surfaces it as a `▸/▾` per-case accordion so reviewers can read what each test verifies without opening the source file.
+
+```ts
+import type { CaseDoc } from 'hazo_ui/test-harness';
+
+// All four fields are required strings:
+const doc: CaseDoc = {
+  description: 'What this test verifies, in plain language.',
+  inputs: 'Inputs / preconditions fed in (URL, payload, fixture, state).',
+  expectedOutputs: 'What is asserted on success.',
+  caveats: 'None', // use "None" when nothing notable applies
+};
+```
+
 ### Copying failures as a Claude prompt
 
 `CopyAllFailuresButton` copies all failed cases as a structured prompt with 8 sections (what-went-wrong, expected/actual/diff, test code, code under test, error chain, context, ring buffer). Place it in your sidebar or test page header.

package/SETUP_CHECKLIST.md

@@ -258,8 +258,9 @@ import {
 // Import celebration (v2.18.0)
 import { CelebrationProvider, celebrate, CELEBRATION_GRADIENT } from 'hazo_ui';
 
-// Import test harness (v3.0.0) — test-app only, never in production bundles
-import { AutoTestProvider, AutoTestRunner, SidebarLayout, AppSidebar, registerScenario, assertEqual } from 'hazo_ui/test-harness';
+// Import test harness (v3.3.0) — test-app only, never in production bundles
+// Note: every Case must include a `doc: CaseDoc` field (required since v3.3.0)
+import { AutoTestProvider, AutoTestRunner, SidebarLayout, AppSidebar, registerScenario, assertEqual, type CaseDoc } from 'hazo_ui/test-harness';
 ```
 
 **Toaster setup**: Mount `<HazoUiToaster />` once at the root of your app (e.g., in `layout.tsx`) so `successToast()` / `errorToast()` calls have somewhere to render.

package/dist/test-harness/index.cjs

@@ -4,7 +4,7 @@ var React = require('react');
 var clsx = require('clsx');
 var tailwindMerge = require('tailwind-merge');
 var jsxRuntime = require('react/jsx-runtime');
-var hazo_core = require('hazo_core');
+var client = require('hazo_core/client');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
@@ -152,6 +152,7 @@ function build_initial_state() {
       status: "pending",
       cases: scenario.cases.map((c) => ({
         name: c.name,
+        doc: c.doc,
         status: "pending"
       }))
     });
@@ -681,7 +682,7 @@ ${ctx_lines.join("\n")}`);
 
 `;
     try {
-      const hazo_logs = await hazo_core.optional_import("hazo_logs");
+      const hazo_logs = await client.optional_import("hazo_logs");
       const get_ring = hazo_logs?.["getRingBuffer"];
       if (!hazo_logs || typeof get_ring !== "function") {
         ring_section += "ring buffer not available (hazo_logs >= 2.0.0 required)";
@@ -860,6 +861,63 @@ function CopySinglePromptButton({
     }
   );
 }
+function CaseRow({
+  c,
+  scenario_id,
+  pkg
+}) {
+  const [expanded, set_expanded] = React.useState(false);
+  return /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "px-6 py-2", children: [
+    /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "flex items-center gap-2 text-sm", children: [
+      c.doc && /* @__PURE__ */ jsxRuntime.jsx(
+        "button",
+        {
+          onClick: () => set_expanded((v) => !v),
+          className: "text-gray-400 hover:text-gray-600 text-xs font-mono w-3 shrink-0",
+          "aria-label": expanded ? "Collapse doc" : "Expand doc",
+          children: expanded ? "\u25BE" : "\u25B8"
+        }
+      ),
+      !c.doc && /* @__PURE__ */ jsxRuntime.jsx("span", { className: "w-3 shrink-0" }),
+      /* @__PURE__ */ jsxRuntime.jsx(StatusIcon, { status: c.status }),
+      /* @__PURE__ */ jsxRuntime.jsx("span", { className: cn(
+        "flex-1",
+        c.status === "failed" ? "text-red-700" : "text-gray-700"
+      ), children: c.name }),
+      c.durationMs != null && /* @__PURE__ */ jsxRuntime.jsxs("span", { className: "text-xs text-gray-400", children: [
+        c.durationMs,
+        "ms"
+      ] }),
+      c.status === "failed" && c.error && /* @__PURE__ */ jsxRuntime.jsx(
+        CopySinglePromptButton,
+        {
+          scenario_id,
+          case_result: c,
+          pkg
+        }
+      )
+    ] }),
+    expanded && c.doc && /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "mt-2 ml-8 text-xs rounded border border-gray-100 bg-gray-50 divide-y divide-gray-100", children: [
+      /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "px-3 py-2", children: [
+        /* @__PURE__ */ jsxRuntime.jsx("span", { className: "font-semibold text-gray-600", children: "Description" }),
+        /* @__PURE__ */ jsxRuntime.jsx("p", { className: "mt-0.5 text-gray-700", children: c.doc.description })
+      ] }),
+      /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "px-3 py-2", children: [
+        /* @__PURE__ */ jsxRuntime.jsx("span", { className: "font-semibold text-gray-600", children: "Inputs" }),
+        /* @__PURE__ */ jsxRuntime.jsx("p", { className: "mt-0.5 text-gray-700", children: c.doc.inputs })
+      ] }),
+      /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "px-3 py-2", children: [
+        /* @__PURE__ */ jsxRuntime.jsx("span", { className: "font-semibold text-gray-600", children: "Expected outputs" }),
+        /* @__PURE__ */ jsxRuntime.jsx("p", { className: "mt-0.5 text-gray-700", children: c.doc.expectedOutputs })
+      ] }),
+      /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "px-3 py-2", children: [
+        /* @__PURE__ */ jsxRuntime.jsx("span", { className: "font-semibold text-gray-600", children: "Caveats" }),
+        /* @__PURE__ */ jsxRuntime.jsx("p", { className: "mt-0.5 text-gray-700", children: c.doc.caveats })
+      ] })
+    ] }),
+    c.status === "failed" && c.error && /* @__PURE__ */ jsxRuntime.jsx("div", { className: "mt-1 ml-8 text-xs text-red-600 bg-red-50 rounded px-2 py-1 font-mono", children: c.error.message })
+  ] });
+}
 function ScenarioRow({
   scenario,
   pkg
@@ -901,28 +959,7 @@ function ScenarioRow({
         }
       )
     ] }),
-    expanded && /* @__PURE__ */ jsxRuntime.jsx("div", { className: "divide-y divide-gray-100", children: scenario.cases.map((c, i) => /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "px-6 py-2", children: [
-      /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "flex items-center gap-2 text-sm", children: [
-        /* @__PURE__ */ jsxRuntime.jsx(StatusIcon, { status: c.status }),
-        /* @__PURE__ */ jsxRuntime.jsx("span", { className: cn(
-          "flex-1",
-          c.status === "failed" ? "text-red-700" : "text-gray-700"
-        ), children: c.name }),
-        c.durationMs != null && /* @__PURE__ */ jsxRuntime.jsxs("span", { className: "text-xs text-gray-400", children: [
-          c.durationMs,
-          "ms"
-        ] }),
-        c.status === "failed" && c.error && /* @__PURE__ */ jsxRuntime.jsx(
-          CopySinglePromptButton,
-          {
-            scenario_id: scenario.id,
-            case_result: c,
-            pkg
-          }
-        )
-      ] }),
-      c.status === "failed" && c.error && /* @__PURE__ */ jsxRuntime.jsx("div", { className: "mt-1 ml-5 text-xs text-red-600 bg-red-50 rounded px-2 py-1 font-mono", children: c.error.message })
-    ] }, i)) })
+    expanded && /* @__PURE__ */ jsxRuntime.jsx("div", { className: "divide-y divide-gray-100", children: scenario.cases.map((c, i) => /* @__PURE__ */ jsxRuntime.jsx(CaseRow, { c, scenario_id: scenario.id, pkg }, i)) })
   ] });
 }
 function AutoTestRunner() {