@appinternalleads/ui 0.2.0

package/README.md

@@ -0,0 +1,315 @@
+# @comppack/ui
+
+A React and React Native component library that **renders UI from JSON at runtime**.
+
+It replaces four copies of `@comppack/ds` that had already drifted apart, and now backs
+`canvas-app`, `keyboard-app`, `turbo-waddle-key` and `turbo-waddle-building` from one source —
+the same JSON file rendering on the web and on iOS, with no code generated on either path.
+
+**Released as `v0.1.2`.** [Jump to implementing it →](#implementing-it)
+
+```bash
+npm install
+npm test          # 474 unit tests, run through react-native-web
+npm run demo      # the web playground on :5180 — JSON in, UI out, answers back
+npm run site      # the docs site on :3000 — every document, every widget, live
+npm run storybook # the component gallery, and the visual gate's fixtures
+npm run visual    # build storybook, then screenshot-diff every story
+npm run generate  # layer-2 JSON -> component + types + story + test + docs
+npm run build     # ESM + CJS + declarations
+
+npm run ask -- 17-card-picker   # ask it in a browser, answer/1 to stdout
+npm run ask:tui -- 10-slider    # ask it in the terminal instead
+npm run ask:mcp                 # the MCP server, on stdio
+```
+
+## Read these first
+
+| | |
+|---|---|
+| [`SPEC.md`](./SPEC.md) | Architecture — the two JSON layers, the primitive set, token resolution, the gates |
+| [`spec/QUESTION-SCHEMA.md`](./spec/QUESTION-SCHEMA.md) | The runtime JSON contract, and what changed from the shipped `Field` spec |
+| [`spec/ASKING.md`](./spec/ASKING.md) | How to choose a widget — for whoever authors the JSON, agent or person |
+| [`tasks/COMPONENT-LIBRARY.md`](./tasks/COMPONENT-LIBRARY.md) | The build record — every task, every finding, every open question |
+| [`tasks/INPUT-WIDGETS.md`](./tasks/INPUT-WIDGETS.md) | The 26 chat widgets: build order, what is done, what is blocked |
+| [`tasks/PLATFORM-TARGETS.md`](./tasks/PLATFORM-TARGETS.md) | React, React Native and Next.js from one source — what is done and what is open |
+| [`tasks/MCP-TOOLS.md`](./tasks/MCP-TOOLS.md) | **The MCP tool surface for CLI agents** — why the validator cannot be a tool's schema, and the five phases that follow |
+| [`tasks/RENDERER-OVERRIDES.md`](./tasks/RENDERER-OVERRIDES.md) | The override API as tasks, and the five code changes that must precede it |
+| [`docs/DECISIONS.md`](./docs/DECISIONS.md) | The problem as stated, every decision taken on it, and what is still open |
+| [`docs/INTEGRATION.md`](./docs/INTEGRATION.md) | **Installing and configuring it in another app** — the long form of the section below |
+| [`site/README.md`](./site/README.md) | The documentation site — a real consumer, and the gate that proves it |
+| [`docs/SPEECH.md`](./docs/SPEECH.md) | **Hearing an ask read aloud** — CLI only, on all three platforms; nothing ships in the package |
+| [`docs/DEPLOYING.md`](./docs/DEPLOYING.md) | **Which accounts deploy the site** — and why the commit author blocks it |
+| [`docs/RFC-MCP.md`](./docs/RFC-MCP.md) | **Unapproved.** Making the library MCP-first — where it fits, and where MCP cannot reach |
+| [`docs/HANDOFF-CONFLICTS.md`](./docs/HANDOFF-CONFLICTS.md) | Every place the input-widget handoff and paper disagree, and which won |
+| [`docs/ASK-CLI-BACKLOG.md`](./docs/ASK-CLI-BACKLOG.md) | **Asking from a CLI** — the browser handoff and the terminal renderer: every open task, and the five decisions that gate them |
+| [`docs/AGENT-BLOCKS-PLAN.md`](./docs/AGENT-BLOCKS-PLAN.md) | **Unapproved.** An agent block set — all 27 reference blocks dispositioned, and why no second schema |
+| [`docs/RFC-RENDERER-OVERRIDES.md`](./docs/RFC-RENDERER-OVERRIDES.md) | **Unapproved.** Letting another team replace one renderer — nine decisions, all open |
+| [`docs/LIBRARY-QUESTIONNAIRE.md`](./docs/LIBRARY-QUESTIONNAIRE.md) | What the library is today, answered against the repo rather than intent |
+
+## The one rule
+
+**There are two JSON layers and they do different jobs.**
+
+*Question JSON* (`spec/question.schema.json`) describes an automation's inputs and is read **at
+runtime** by `QuestionBlock`. It names no colours, radii or spacing at all, which is why anyone
+can author it — and why a new question is data rather than a build step.
+
+*Component JSON* (`spec/component.schema.json`) describes a component as a full visual tree and is
+consumed **at build time** by the generator, which resolves every raw value to a design token and
+refuses anything it cannot. Reading either as a revision of the other is the expensive mistake
+here.
+
+## Layout
+
+```
+src/tokens/   the only files with a hex literal
+src/core/     the 16 primitives — props are token names, never values
+src/values/   tier-3 value widgets
+src/ds/       the ported @comppack/ds component layer
+src/fields/   the 17 field types and their controls
+src/native/   the OS-backed Slider and DatePicker — the ONLY files naming a native peer
+src/widgets/  the chat result-card family — shell, surface hook, state machine
+src/next/     Next.js — the config wrapper and the SSR stylesheet flush
+src/generated/ emitted from component JSON
+spec/         both schemas, and validated examples
+tools/        the generator
+```
+
+**The invariant:** `react-native` is imported at runtime by `src/core/` and `src/tokens/`, and
+nowhere else. That is what keeps a platform split cheap.
+
+## The boundary
+
+**This library provides components.** It draws a question from JSON and hands back answers.
+
+Where an agent runs, how the JSON travels, whether the question appears as a sheet or a turn in a
+conversation, whether an unanswered one persists — **all of that is the app's.** The same line is
+already drawn twice inside the library: `EnumField` takes resolved options rather than fetching
+them, and `ReachBar` takes reachability as a prop rather than subscribing to a store. A component
+set that acquires a transport, a task store or an auth token has stopped being one.
+
+`spec/ASKING.md` is the exception that proves it — guidance for the JSON's author, shipped here
+because the schema can only reject what is invalid, and a date asked as a text box is perfectly
+valid.
+
+## Implementing it
+
+**The same JSON renders on both.** What differs is three lines of bundler config on the web and
+nothing at all on native — the library ships a native and a web half of each primitive that needs
+one, and picks between them by file extension.
+
+### 1. Install — identical on both
+
+```bash
+npm install github:AppEGLabs/turbo-waddle-package#v0.1.2
+npm install react-native-svg phosphor-react-native react-native-safe-area-context
+```
+
+Five peers, every one required: `react` ≥ 18 and `react-native` ≥ 0.76 for the primitives,
+`react-native-svg` for the donut, dial and ring, `phosphor-react-native` for the icons,
+`react-native-safe-area-context` for `SafeArea`.
+
+**There are no optional peers.** There were two, and the word was false — a barrel export is a
+static import, so an "optional" module reached through one is not optional. The `Slider` and
+`DatePicker` you get are built from React Native primitives. The OS-backed pair is a separate
+entry point that installs nothing unless you import it:
+
+```bash
+npm install @react-native-community/slider @react-native-community/datetimepicker
+```
+```ts
+import { NativeSlider, NativeDatePicker } from '@comppack/ui/native';
+```
+
+### 2a. Mobile — nothing to configure
+
+```bash
+cd ios && pod install
+```
+
+That is the whole setup. Metro resolves `.js` for native and the package ships its native halves
+there.
+
+```tsx
+import { useState } from 'react';
+import { SafeAreaProvider } from 'react-native-safe-area-context';
+import { DsProvider, WidgetBlock, asQuestionBlock, initialAnswers } from '@comppack/ui';
+import json from '@comppack/ui/examples/widgets/17-card-picker.json';
+
+/* A JSON import types `schema` as `string`, not `"question/1"`. `asQuestionBlock` narrows it
+   with a real check, so the wrong file is a message rather than a render that goes strange. */
+const block = asQuestionBlock(json);
+
+export default function App() {
+  const [answers, setAnswers] = useState(() => initialAnswers(block));
+  return (
+    <SafeAreaProvider>
+      <DsProvider>
+        <WidgetBlock block={block} answers={answers} onChange={setAnswers} />
+      </DsProvider>
+    </SafeAreaProvider>
+  );
+}
+```
+
+**Both snippets on this page are compiled, not written from memory.** They live as real files in
+[`../comppack-ui-lab/src/readme-snippets/`](../comppack-ui-lab/src/readme-snippets), typechecked against
+the *installed* package — the first version of the one above did not compile, and that is how
+`asQuestionBlock` came to exist.
+
+Sliders, ranges and the arc dial are **draggable** — and their ± buttons and chip legends stay,
+because WCAG 2.5.7 wants a single-pointer path that is not a drag.
+
+### 2b. Web — three lines, and they are not optional
+
+`react-native-web` does the rendering; your bundler needs to know two things Metro already knows.
+
+```ts
+// vite.config.ts — webpack's `resolve.extensions` and `alias` take the same values
+export default defineConfig({
+  resolve: {
+    // `.web.js` BEFORE `.js`, or you get the native half of every split primitive
+    extensions: ['.web.js', '.js', '.web.ts', '.ts', '.web.tsx', '.tsx', '.json'],
+    alias: [
+      // Exact-match: a bare string alias matches by PREFIX and rewrites
+      // `react-native/Libraries/...` into a path that does not exist
+      { find: /^react-native$/, replacement: 'react-native-web' },
+      { find: /^react-native-svg$/, replacement: 'react-native-svg-web' },
+    ],
+  },
+});
+```
+```bash
+npm install react-native-web react-native-svg-web
+```
+
+Then the component code is **the same file** as mobile — no `Platform.select`, no `.web.tsx` in
+your app. `<DsProvider>` and `<WidgetBlock>` behave identically; the card reads **its own width**
+at 640px to decide its layout, so the same card is the mobile card inside a narrow desktop panel.
+
+⚠ **Get the extension order wrong and nothing crashes.** You silently get the native
+implementation running under `react-native-web`. It renders and works — those halves are built
+from primitives, not native modules — you just lose `<input type="range">`'s keyboard support and
+`<input type="date">`'s locale calendar. Worth checking rather than assuming.
+
+### 2c. Next.js — the App Router
+
+Two more lines than Vite, because Next compiles differently and renders on a server.
+
+```js
+// next.config.mjs
+import { withCompPack } from '@comppack/ui/next/config';
+export default withCompPack({ reactStrictMode: true });
+```
+```tsx
+// app/layout.tsx — the stylesheet flush. RNW ships no CSS file; it builds a sheet as
+// components render and injects it into a document the server does not have.
+import { CompPackRegistry } from '@comppack/ui/next';
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return <html lang="en"><body><CompPackRegistry>{children}</CompPackRegistry></body></html>;
+}
+```
+
+**The build marks every drawing module `'use client'` and deliberately leaves the pure half
+unmarked**, so `answerBlock`, `lintQuestion` and the formatters import cleanly into a server
+component while anything that draws needs a `'use client'` file of your own to hold the `useState`.
+
+The long form — and the one token exception — is [`docs/INTEGRATION.md`](./docs/INTEGRATION.md) §4.
+
+### 3. The same on both — answers back
+
+```tsx
+import { WidgetBlock, answerBlock, lintQuestion } from '@comppack/ui';
+
+<WidgetBlock
+  block={block}
+  answers={answers}
+  onChange={setAnswers}
+  onSubmit={a => send(answerBlock(block, a))}  // the answer/1 envelope
+  prompt={lastUserMessage}                      // from your transcript, never the block
+  options={{ channel: resolved }}               // you resolve `source`; this never fetches
+/>
+```
+
+`lintQuestion(block)` warns about asks that are valid but poor — a menu of three options, a
+required single-select with no way out. It never refuses, and the renderer does not call it.
+
+### What you own, and it is deliberate
+
+| | |
+|---|---|
+| Resolving a field's `source` | It names a `LIST_*` tool; you call it and pass `options` |
+| The eight widget states | They live in your run, not in the widget |
+| Acting on `superseded` | Re-opening an answer sets the flag; invalidating what was derived from it is yours — nothing here can enforce that |
+
+### Verified, not assumed
+
+Every claim above was checked by installing the package into a bare React Native app with **no
+aliases, stock Metro, stock Babel and stock tsconfig** — [`../comppack-ui-lab`](../comppack-ui-lab).
+The git-tag install produces a bundle byte-for-byte identical to the npm tarball's, and all
+twenty JSON fixtures render from it on device and in Chrome.
+
+### The npm registry route
+
+Prepared but not taken: `@comppack` is not yet a scope on npm, and creating an org needs the website
+plus a paid plan for private packages. The git tag needs neither and the repo is private, so it
+gives the same access control for nothing. [`docs/INTEGRATION.md`](./docs/INTEGRATION.md) §0 has
+the steps if you want the registry later.
+
+---
+
+## Asking from a CLI
+
+**A terminal cannot draw a slider, and the thing that most often needs to ask has no window at
+all.** So the ask goes to the browser, or the terminal draws the half it can. Both read the same
+`question/1`, both hand back the same `answer/1`, and both put the envelope on **stdout** with
+everything else on stderr:
+
+```bash
+node tools/ask/cli.mjs 17-card-picker | jq '.answers.keep'
+# ["maya","tobias","priya"]
+```
+
+| | |
+|---|---|
+| `npm run ask -- <fixture>` | One-shot loopback server, the real widgets, `answer/1` back. All twenty |
+| `npm run ask:tui -- <fixture>` | **All twenty asks** in the terminal. Tab moves between fields, the arrows belong to the control, `esc` returns `outcome: "cancel"`. The one a terminal cannot draw says so and names the command that can |
+| `npm run ask:mcp` | The MCP server — one tool, `ask_user`, plus `validate_question` |
+| `--speak` | Reads the ask aloud, and the answer back. [`docs/SPEECH.md`](./docs/SPEECH.md) |
+
+### From an agent
+
+**`comppack-ask` is a `bin` in this package**, so registering it needs no clone:
+
+```bash
+claude mcp add comppack-ask -- npx -y comppack-ask
+```
+
+The `question` argument's schema is [`spec/question.generate.json`](./spec/question.generate.json)
+— the **generation profile**, not the validator. `question.schema.json` is 23 KB with 26 `if` and
+ten self-references and cannot be a tool's `inputSchema`; the profile is flat, 8 KB on the wire,
+and carries the derivation rule in its `description` fields, which is the document a model reads
+while authoring. [`tests/generate-profile.test.ts`](./tests/generate-profile.test.ts) holds the two
+together: anything the profile accepts, the validator accepts.
+
+`ask_user` lints before it opens a browser. Four of the fifteen rules stop an ask because the
+widget **cannot function** — `slider-without-bounds`, `enum-without-options`, `share-does-not-sum`,
+`range-default-inverted`. The other eleven are criticisms of a *working* ask and travel with it;
+refusing those would make this an editor of questions rather than a renderer of them.
+
+### What ships, and what does not
+
+`files` carries the server, its page and `speak.mjs`. It does **not** carry the terminal renderer:
+that needs Ink, a devDependency, and shipping it would hand you a command that cannot run.
+
+| `npm run ask:check` | every fixture in a real browser, pressing its own submit |
+| `npm run ask:tui:check` | the terminal renderer — 11 keystroke cases, then every fixture, failing on a blank |
+| `npm run ask:tui:pty` | the same renderer in a **real pty**, because raw mode and the escape parser only exist there |
+| `npm run ask:mcp:check` | the MCP handshake, end to end, answering a real ask |
+| `npm run ask:pack:check` | packs, installs into a throwaway project, handshakes the **installed** bin |
+| `npm run ask:eval` | does the model reach for it when it fits, and leave it alone when it does not |
+
+The last one needs an Anthropic credential and has not been run.
+[`docs/ASK-CLI-BACKLOG.md`](./docs/ASK-CLI-BACKLOG.md) is the transport work;
+[`tasks/MCP-TOOLS.md`](./tasks/MCP-TOOLS.md) is the tool surface.