@appinternalleads/ui 0.2.0

package/package.json

@@ -0,0 +1,160 @@
+{
+  "name": "@appinternalleads/ui",
+  "version": "0.2.0",
+  "description": "React + React Native component library. Components are generated from JSON; see SPEC.md.",
+  "workspaces": [
+    "site"
+  ],
+  "type": "module",
+  "main": "dist/cjs/index.js",
+  "types": "dist/esm/index.d.ts",
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src tests tools",
+    "generate": "vite-node -c vite.tools.config.ts tools/generate.ts",
+    "rive:receipt-printer": "node tools/rive-receipt-printer.mjs",
+    "publish:npm": "node tools/publish-npm.mjs",
+    "storybook": "storybook dev -p 6006 --no-open",
+    "build-storybook": "storybook build",
+    "visual": "storybook build --quiet && playwright test",
+    "visual:update": "storybook build --quiet && playwright test --update-snapshots",
+    "visual:site": "npm run site:build && playwright test -c playwright.site.config.ts",
+    "demo": "vite --config demo/vite.config.ts",
+    "site": "npm run build && npm --workspace site run dev",
+    "site:build": "npm run build && npm --workspace site run build",
+    "demo:build": "vite build --config demo/vite.config.ts",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && tsc -p tsconfig.build.json --module commonjs --moduleResolution node --outDir dist/cjs --declaration false --declarationMap false && node -e \"require('fs').writeFileSync('dist/cjs/package.json', JSON.stringify({type:'commonjs'}) + String.fromCharCode(10))\" && node tools/use-client.mjs",
+    "say": "vite-node -c vite.tools.config.ts tools/say-block.ts --",
+    "say:detect": "node tools/speak.mjs --detect",
+    "ask": "node tools/ask/cli.mjs",
+    "ask:build": "vite build --config tools/ask/vite.config.ts && esbuild tools/speech/speakable.ts --bundle --format=esm --platform=node --outfile=tools/ask/dist/speakable.mjs --log-level=error && esbuild tools/ask/elicit.ts --bundle --format=esm --platform=node --outfile=tools/ask/dist/elicit.mjs --log-level=error && node tools/ask/build-support.mjs",
+    "ask:check": "node tools/ask/check.mjs",
+    "ask:tui": "vite-node -c vite.tools.config.ts tools/ask/tui/index.tsx --",
+    "ask:mcp": "node tools/ask/mcp.mjs",
+    "ask:tui:check": "vite-node -c vite.tools.config.ts tools/ask/tui/check.tsx --",
+    "ask:shots": "FORCE_COLOR=3 vite-node -c vite.tools.config.ts tools/ask/tui/shots.tsx --",
+    "ask:mcp:check": "node tools/ask/mcp-check.mjs",
+    "say:check": "vite-node -c vite.tools.config.ts tools/ask/say-check.ts --",
+    "ask:probe": "node tools/ask/schema-probe.mjs",
+    "ask:pack:check": "node tools/ask/pack-check.mjs",
+    "ask:eval": "vite-node -c vite.tools.config.ts tools/ask/eval/run.ts --",
+    "ask:eval:audit": "vite-node -c vite.tools.config.ts tools/ask/eval/audit.ts --",
+    "ask:tui:pty": "node tools/ask/tui/pty-check.mjs",
+    "check:rules": "vitest run tests/componentRules.test.ts tests/onboarding/guard.test.tsx tests/sheetIntegration.test.tsx tests/onboarding/buttonActions.test.tsx tests/sheets.test.ts"
+  },
+  "peerDependencies": {
+    "next": ">=14",
+    "phosphor-react-native": "*",
+    "react": ">=18",
+    "react-native": ">=0.76",
+    "react-native-safe-area-context": "*",
+    "react-native-svg": "*"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@playwright/test": "^1.62.1",
+    "@react-native-community/datetimepicker": "^9.2.0",
+    "@react-native-community/slider": "^5.2.1",
+    "@rive-app/react-native": "^0.4.20",
+    "@storybook/addon-a11y": "^10.6.0",
+    "@storybook/react-vite": "^10.6.0",
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.1.0",
+    "@testing-library/user-event": "^14.5.2",
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.7",
+    "ajv": "^8.20.0",
+    "ajv-formats": "^3.0.1",
+    "eslint": "^10.9.1",
+    "ink": "^7.1.1",
+    "ink-testing-library": "^4.0.0",
+    "jsdom": "^25.0.1",
+    "next": "^15.5.25",
+    "phosphor-react-native": "^3.0.6",
+    "react": "19.2.3",
+    "react-devtools-core": "^7.0.1",
+    "react-dom": "19.2.3",
+    "react-native": "0.86.0",
+    "react-native-nitro-modules": "^0.35.10",
+    "react-native-safe-area-context": "^5.9.1",
+    "react-native-svg": "^15.15.5",
+    "react-native-svg-web": "^1.0.9",
+    "react-native-web": "^0.21.2",
+    "storybook": "^10.6.0",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.69.0",
+    "vitest": "^2.1.8"
+  },
+  "peerDependenciesMeta": {
+    "react-native-safe-area-context": {
+      "optional": true
+    },
+    "next": {
+      "optional": true
+    }
+  },
+  "module": "dist/esm/index.js",
+  "react-native": "src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/esm/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js"
+    },
+    "./native": {
+      "types": "./dist/esm/native/index.d.ts",
+      "import": "./dist/esm/native/index.js",
+      "require": "./dist/cjs/native/index.js"
+    },
+    "./native/receipt-printer": {
+      "types": "./dist/esm/native/RiveReceiptStage.d.ts",
+      "import": "./dist/esm/native/RiveReceiptStage.js",
+      "require": "./dist/cjs/native/RiveReceiptStage.js"
+    },
+    "./next": {
+      "types": "./dist/esm/next/index.d.ts",
+      "import": "./dist/esm/next/index.js",
+      "require": "./dist/cjs/next/index.js"
+    },
+    "./next/config": {
+      "types": "./dist/esm/next/config.d.ts",
+      "import": "./dist/esm/next/config.js",
+      "require": "./dist/cjs/next/config.js"
+    },
+    "./question.schema.json": "./spec/question.schema.json",
+    "./component.schema.json": "./spec/component.schema.json",
+    "./examples/*": "./spec/examples/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "spec",
+    "!src/**/*.test.*",
+    "!src/**/*.stories.*",
+    "tools/ask/mcp.mjs",
+    "tools/ask/serve.mjs",
+    "tools/ask/stale.mjs",
+    "tools/ask/policy.mjs",
+    "tools/ask/dist",
+    "tools/speak.mjs"
+  ],
+  "sideEffects": false,
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AppEGLabs/turbo-waddle-package.git"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "bin": {
+    "comppack-ask": "tools/ask/mcp.mjs"
+  },
+  "dependencies": {
+    "@rive-app/react-canvas": "^4.35.0"
+  }
+}

package/spec/ASKING.md

@@ -0,0 +1,264 @@
+# Choosing a widget — the derivation rule
+
+**Status** Draft.
+**Audience** Whoever authors question JSON. Usually an agent; sometimes a person.
+**Companion to** [`QUESTION-SCHEMA.md`](./QUESTION-SCHEMA.md), which says what is *valid*. This says
+what is *right*.
+
+---
+
+## 0. What this library does, and what it does not
+
+**This library provides components.** It draws a question from JSON and hands back answers. That
+is the whole of it.
+
+| Not the library's job | Whose |
+|---|---|
+| Where the agent runs, and how the JSON travels | The app |
+| Whether the question is a sheet, a turn in a chat, or a row in a task list | The app |
+| Persisting an unanswered question, resuming it, expiring it | The app |
+| Deciding that a question is needed at all | The agent |
+
+The line is the same one drawn twice already: `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.
+
+**So this document is a contract, not code.** Nothing here executes. It exists because the schema
+can only reject what is *invalid* — and a date asked as a text box is perfectly valid.
+
+---
+
+## 1. The rule
+
+**Two questions decide the type. One more decides the control.**
+
+> **1. What IS the answer?** — a date, a number, one of a known set, a yes or no, free prose.
+> **2. Does the asker already know the possible answers?** If yes it is `enum`, whatever the
+>    domain. If no it is a scalar.
+> **3. How many are there, and how long are they?** That, and only that, decides the control.
+
+Booking a meeting room and picking a candidate's seniority are unrelated domains and the same
+widget. That is the test for whether a choice is real: **derive from the shape of the answer,
+never from the subject.**
+
+---
+
+## 2. Type
+
+| The answer is | Type | Not |
+|---|---|---|
+| A calendar day | `date` | `text` — a typed date is a parsing problem you gave the user |
+| A day and a time | `datetime` | two fields |
+| A quantity | `number` | `text`, even when it happens to be digits |
+| Yes or no | `toggle` | an `enum` of two, which asks the user to read both |
+| One of a set the asker can name | `enum` | `text` with the options in the hint |
+| One of a set only the connector knows | `enum` + `source` | `text` |
+| Several of a set, or several free strings | `list` | comma-separated `text` |
+| An email address | `email` | `text` — the keyboard, autocorrect and validation all differ |
+| A sentence or a paragraph | `text` | anything else |
+| Fields that belong to one thing | `group` | four loose fields with a shared prefix |
+| A shape that depends on a choice | `variant` | every branch's fields at once, most disabled |
+| **Several of a set the asker can name** | `enum` + `multiple` | `list` — that is free entry, and this set is closed |
+| **Two ends of one band** | `range` | two `number` fields with a convention between them |
+| **Several numbers under one submit** | `counters` | a `group` of numbers — it validates the same and draws wrongly |
+| **Parts of one whole** | `share` | anything else, unless they really sum to 100 |
+| **Documents the run must read** | `file` | a `text` field asking for a link |
+| **A recording** | `media` | `file` — the affordance and the copy both differ |
+| **Firing a step** | `action` | a `toggle` the user then has to submit |
+
+**Nothing that returns nothing is an ask.** Progress, sequences and status belong to the app's run
+state, not to `question/1` — a card reporting on the run is not asking, and giving one schema two
+verbs is how both get muddled.
+| A payload the user is editing verbatim | `json` | `text` |
+
+**`email` is a type, not a hint.** So is `date`. A type carries the keyboard, the validation and
+the control with it — a hint carries none of them and is not read by anyone in a hurry.
+
+---
+
+## 3. Control
+
+The type is decided by the answer. **The control is decided by the count and the length**, and by
+nothing else.
+
+### `enum` — how many options?
+
+| Count | Control | Why |
+|---:|---|---|
+| 2–4, short labels | `segmented` | All options visible at once, no interaction to see them |
+| 2–8, or labels that wrap | `radio` | A column reads at any label length; segmented shrinks the label |
+| 9 or more | `select` | Past a screenful, scrolling a list is not choosing |
+| Any count, and the value is a filter or a tag | `chips` | Reads as *a facet*, not as *the answer to a question* |
+| From a `source` | `select` | The count is not knowable when the JSON is written |
+
+**A `source` field is always `select`.** The asker does not know whether the connector will return
+three channels or sixty-one, and a segmented control of sixty-one is a bug that only appears in
+production.
+
+### `number` — bounded, and how precisely?
+
+| Situation | Control |
+|---|---|
+| A small count the user will nudge — 1 to ~50 | `stepper` |
+| A bounded range where the exact value barely matters — a weight, a threshold | `slider` |
+| Unbounded, or precise, or large — an amount, a year | `single` |
+
+**A slider with no `min` and `max` is a scrollbar for an unknown range.** If you cannot state
+both, it is not a slider.
+
+### `text` — one line or a paragraph?
+
+`single` for a name, a title, a trigger. `multi` for anything you would expect a sentence of.
+**The control is a promise about length**, and a single-line box asking for context gets one
+clause.
+
+### `list` — what does one element need?
+
+`tags` when an element is a short string and a chip can show all of it. `repeater` when an
+element needs a real field — a date, a toggle, an enum. A chip cannot hold a date picker, and
+squeezing one in makes the chip the widget.
+
+### `toggle`, `group`, `variant`, `json`
+
+`toggle` is `switch` in a settings row and `checkbox` in a form where it sits among other fields.
+`group` is `card` when it is one of several things on screen and `section` when it is the screen.
+`variant` is `tabs` at two or three branches and `select` past that. `json` has one control.
+
+---
+
+## 4. Before you ask anything
+
+**The best question is the one you did not have to ask.**
+
+- **Never ask for something you can infer.** A date the user already gave in the sentence, a
+  channel with only one candidate, a name already on the account.
+- **Never ask twice in one field.** "Name and email" is two fields, and a single box gets a string
+  that has to be split by guesswork.
+- **Ask everything you need in one block, or say why not.** The schema allows one field or twenty.
+  A four-field ask delivered as four exchanges reads as an interrogation, and the user cannot see
+  what they are agreeing to. Batch by *what the interruption is for*, not by what fits.
+- **`required: false` is a real answer.** If the run can proceed without it, marking it required
+  makes the user invent something.
+- **If no question would fix it, do not ask one.** The app already has a word for that state.
+
+---
+
+## 5. Writing the copy
+
+The fields that carry words are not decoration; they are the whole of the asking.
+
+| Field | Is | Is not |
+|---|---|---|
+| `question` | A sentence, addressed to a person | A restatement of the field labels |
+| `label` | What the value is | A sentence, or a question |
+| `example` | **A specimen value** — `Senior Backend Engineer` | Prose. It becomes the placeholder |
+| `hint` | The full explanation, one line | A repeat of the label |
+
+**`hint` interpolates `{default}` and `{constraints.*}`.** Writing the numbers out is correct
+exactly until someone changes `max`.
+
+---
+
+## 6. Worked
+
+**"Schedule the standup summary."** The agent knows the workflow and the channel; it does not know
+when.
+
+```json
+{ "schema": "question/1", "slug": "schedule-standup",
+  "question": "When should this run?",
+  "fields": [
+    { "key": "at", "type": "datetime", "label": "First run", "required": true },
+    { "key": "repeat", "type": "enum", "control": "segmented", "label": "Repeat",
+      "options": ["Daily", "Weekdays", "Weekly"], "default": "Weekdays" } ]}
+```
+
+Three options and short labels, so `segmented`. A day and a time together, so `datetime` and not
+two fields. The channel is not asked for, because it is known.
+
+**"Post this to Slack."** The agent knows the message; it does not know the channel, and it cannot
+know the options until it calls the connector.
+
+```json
+{ "key": "channel", "type": "enum", "control": "select", "label": "Channel",
+  "source": { "tool": "SLACK_LIST_CHANNELS", "labelPath": "name", "valuePath": "id" } }
+```
+
+`source`, so `select` — the count is unknowable here. The host resolves it and passes the options
+in; **the library never fetches.**
+
+**"Shortlist the applicants."** A bounded count the user will nudge, and a threshold where the
+exact number barely matters.
+
+```json
+[ { "key": "shortlist-size", "type": "number", "control": "stepper", "label": "Shortlist size",
+    "default": 10, "constraints": { "min": 1, "max": 47 },
+    "hint": "Top {default} of {constraints.max} will be shown for review." },
+  { "key": "min-score", "type": "number", "control": "slider", "label": "Minimum score",
+    "default": 60, "constraints": { "min": 0, "max": 100, "step": 5 } } ]
+```
+
+Both are numbers; the controls differ because one is counted and one is dialled.
+
+---
+
+## 7. Getting it wrong
+
+Each of these validates. Each is still wrong.
+
+| Written | Should be |
+|---|---|
+| `text` asking for a date | `date` |
+| `text` with the options listed in the `hint` | `enum` |
+| `enum` + `segmented` with 12 options | `select` |
+| `enum` + `segmented` with a `source` | `select` — the count is unknowable |
+| `number` + `slider` with no `min`/`max` | `stepper`, or state the bounds |
+| `text` + `single` asking for context | `multi` |
+| Two facts in one `label` | Two fields |
+| `list` of dates as `tags` | `repeater` |
+| `required: true` on something optional | `required: false` |
+
+---
+
+## 8. Open
+
+1. **Should a validator enforce §7?** The schema rejects the invalid; nothing rejects the merely
+   poor. A lint over question JSON — segmented past four, a `source` that is not `select`, a
+   slider without bounds — would make this document checkable rather than advisory. It is not
+   built, and it is the obvious next thing if agent output proves inconsistent.
+2. **How does an agent learn the count for §3?** For a static `options` array it can count. For a
+   `source` it cannot, which is why that rule is absolute rather than a threshold.
+
+---
+
+## 9. The widgets, and when to name one
+
+**Don't, normally.** State what the answer is; the renderer picks. That is what lets a redesign
+change every ask in the product at once instead of migrating thousands of stored objects.
+
+`preferred` exists for the case where the derivation is wrong and no amount of option metadata
+fixes it. It is **honoured when legal and dropped when not**, so a stale hint degrades rather than
+breaking a question that was valid when it was written.
+
+| Answer shape | Draws as | `preferred` alternatives |
+|---|---|---|
+| `text` · single | 01 Text Input Field | `text-field` when it needs a label and helper |
+| `text` · multi | 03 TextArea | — |
+| `enum`, ≤ 8, unordered | 12 Radio | `dropdown` when the set is the user's own data |
+| `enum`, > 8 | 04 Dropdown | — |
+| `enum`, ordered, small | 15 Horizontal List | `arc-picker` when the ordering is a dial, not a list |
+| `enum` with scores | 17 Card Picker | — |
+| `enum` + `multiple` | 13 Checkboxes | `card-picker` when the options carry reasons |
+| `number` bounded | 10 Slider | `numerical-holder` below ~12, where a track is overkill |
+| `range` | 11 Range Picker | — |
+| `counters` | 19 Counter Group | — |
+| `share` | 16 Pie Chart Picker | — |
+| `file` · `media` | 07 · 08 | — |
+| `datetime` + `presets` | 09 Date & Time | — |
+| `action` | 05 Button | — |
+| Several fields, one submit | 21 Aggregated Input | — |
+| Any of the above, `blocking` + `reason` | 06 Container | — |
+
+**A hint that contradicts the answer's shape is dropped, not honoured.** `arc-picker` on a
+`multiple` enum cannot draw two marks on one dial, so it degrades to checkboxes; the linter says
+so at `info`, because it is a note rather than a fault.