cortena-ui 1.1.1 → 1.3.0

package/README.md

@@ -26,6 +26,89 @@ Consuming it: `../../CONSUMING.md`, section "cortena-ui".
   check in light, dark and system-dark; add an entry with every variant and
   size when adding a component.
 
+## Charts in tests
+
+Both chart engines size themselves from the parent box, and under jsdom every
+element measures 0×0. A page test that renders a screen containing a `<Chart>`
+therefore gets an empty `<div>`: no `<svg>`, no bars, nothing to assert. Two
+ways out, in order of preference.
+
+**1. `testMode`, when the test is about the page.** It gives the drawing area a
+600×300 floor, so the chart draws and the page renders as a whole:
+
+```tsx
+<Chart type="bar" data={rows} testMode={import.meta.env.MODE === "test"} />
+```
+
+It is a floor, not a fixed size — a parent that does give the chart 900px still
+gets 900px — so the same prop is harmless in a browser or screenshot test. A
+screen that composes charts internally can take the flag as a prop and pass it
+down, or read it once from the app's own test flag.
+
+**2. Mock the module, when the test is about everything except the chart.**
+Cheaper and faster, and the right choice when the assertion is "the dashboard
+renders" rather than "the chart drew". Mock `cortena-ui`'s `Chart` to a stub
+that echoes what it was handed:
+
+```tsx
+vi.mock("cortena-ui", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("cortena-ui")>()),
+  Chart: (props: { type: string }) => <div data-testid="chart" data-type={props.type} />,
+}));
+```
+
+Neither substitutes for the real check: whether a chart *looks* right is
+settled in the guide and in this package's browser tests, not in a page test.
+
+## A2UI: the vocabulary agents draw with
+
+`src/a2ui/` is Layer 1 of `cortena-docs/cortenaUI&Design/05-agent-ui.md`: an
+[A2UI](https://a2ui.org) catalogue bound to this package, plus a React renderer.
+An agent emits an A2UI payload, it arrives as an AG-UI `CUSTOM` event, and
+`<A2UIRenderer>` draws it from the catalogue and sends user events back.
+
+```tsx
+import { A2UIRenderer, defaultCatalogue } from "cortena-ui";
+
+<A2UIRenderer
+  message={customEvent.value}            // message, message[], or JSONL text
+  catalogue={defaultCatalogue}           // 27 components; see `pnpm a2ui:catalogue`
+  onAction={(action) => run.send(action)} // { surfaceId, componentId, name, payload }
+  resolveDataSource={(id) => sources[id]} // server-backed DataTable handles
+/>;
+```
+
+Two dialects fold onto the same surfaces: **v0.9** (`createSurface`,
+`updateComponents`, `updateDataModel`) and the **v0.8** form core already speaks
+(`beginRendering`, `surfaceUpdate`, `dataModelUpdate`), which is what the
+`canvas` tool pushes as JSON lines. Later messages fold onto earlier ones, so a
+push stream can be accumulated and handed to the renderer whole.
+
+Safety is by construction: a node is a catalogue name plus properties that must
+pass that entry's zod schema. An unknown component, an invalid property, a
+missing child id or a `javascript:` URL each render an inline error card; no part
+of a payload ever becomes markup.
+
+`pnpm a2ui:catalogue` writes `dist-a2ui/catalogue.json` and `.md` (gitignored,
+derived). DESIGN-34 generates the core system-prompt section from the JSON, so
+the prompt and the renderer cannot describe different components.
+
+### Why the renderer is written rather than adopted
+
+`@a2ui/react` 0.11.0 (Google, Apache-2.0) is a maintained v0.9 renderer and does
+support host catalogues. It was evaluated at DESIGN-33 and not adopted:
+
+| | |
+| --- | --- |
+| **zod major** | `@a2ui/web_core`'s binder reads zod 3 internals (`_def.typeName`, `_def.shape()`). This package's zod peer is `^3.25 \|\| ^4`; zod 4 has neither, so a catalogue authored with the consumer's zod 4 fails inside the binder. |
+| **Dialect** | It splits `v0_8` and `v0_9` into separate entry points with separate catalogues, so neither reads both. Every A2UI payload already written for Cortena's native nodes would have to be rewritten before it rendered on the web. |
+| **Weight and surface** | It pulls in `@a2ui/web_core` (3.8 MB unpacked), markdown-it, `@preact/signals-core` and date-fns, into a package that externalises everything and already renders markdown through react-markdown with a sanitize schema. `resolveDataSource` and `onAction` have no counterpart there, so it would be wrapped either way. |
+
+What is kept is what makes interop work: the wire format is A2UI's, the emitted
+action is shaped like A2UI's client-to-server `action`, and the catalogue is a
+schema-per-component registry. Swapping the engine later is mechanical. Nothing
+from `@a2ui/*` is installed, so `vitest.config.ts` has no entry for it.
+
 ## Commands
 
 ```bash
@@ -34,6 +117,7 @@ pnpm lint:design  # no literals where a token exists; no dangling var()
 pnpm build        # dist/ via tsdown (ESM + d.ts); also runs on prepack
 pnpm test         # Vitest browser mode, chromium light + dark
 pnpm guide        # three-theme guide on a local Vite server
+pnpm a2ui:catalogue  # dist-a2ui/catalogue.json + .md from the A2UI catalogue
 ```
 
 From the repo root the same are `pnpm ui:check`, `ui:build`, `ui:test`, `ui:guide`.
@@ -43,6 +127,7 @@ From the repo root the same are `pnpm ui:check`, `ui:build`, `ui:test`, `ui:guid
 ```
 src/index.ts          public surface; add an export per component
 src/components/*.tsx  one file per component, shadcn shape, Base UI primitives
+src/a2ui/             A2UI catalogue, React renderer and doc generator
 src/lib/cn.ts         clsx + tailwind-merge
 src/styles/index.css  what consumers import after the tokens: animation
                       utilities and the Base UI data-attribute variants