@appinternalleads/ui 0.2.0

package/src/fields/types.ts

@@ -0,0 +1,536 @@
+/**
+ * TypeScript mirror of `spec/question.schema.json`.
+ *
+ * **A discriminated union, deliberately.** The JSON Schema rejects `type: "text"` with
+ * `control: "stepper"` at validation time; this rejects the same thing at compile time, so a
+ * hand-written call site and a generated one fail identically. That pairing is the whole point
+ * — a rule enforced in one place and not the other is a rule that holds until someone is in a
+ * hurry.
+ */
+
+/**
+ * **Seventeen types — eleven carried from `Field` v2, six added for the input widgets.**
+ *
+ * The six exist because nine of the 26 widgets returned shapes `question/1` had no words for.
+ * They were added rather than given a second schema (decision Q1a): two vocabularies would mean
+ * every agent needs a rule for choosing between them, and that rule becomes the thing nobody can
+ * change. A wide union is a manageable cost; two schemas is a permanent tax.
+ *
+ * | Added | Answer | Widget |
+ * |---|---|---|
+ * | `range` | `[number, number]` | 11 Range Picker |
+ * | `counters` | `Record<string, number>` | 19 Counter Group |
+ * | `share` | the picked slice's key | 16 Pie Chart Picker |
+ * | `file` | `FileRef[]` | 07 File Upload |
+ * | `media` | `FileRef` | 08 Voice Recorder |
+ * | `action` | nothing — firing it IS the answer | 05 Button |
+ *
+ * **Progress readouts (22–26) are deliberately absent**, and so is 20 · Step Executor. They
+ * return nothing, so putting them here would make `question/1` mean two verbs — asking and
+ * reporting. The app composes those from its own run state (decision Q5c).
+ */
+export type FieldType =
+  | 'text' | 'email' | 'number' | 'toggle' | 'date' | 'datetime'
+  | 'enum' | 'list' | 'group' | 'variant' | 'json'
+  | 'range' | 'counters' | 'share' | 'file' | 'media' | 'action';
+
+/**
+ * **What this renderer can actually draw.**
+ *
+ * The widget contract's rule for output types applies verbatim here: *never return or accept a
+ * type the client cannot render.* A field whose type is outside this set renders as an explicit
+ * unsupported state (§`UnsupportedField`) rather than throwing or silently drawing nothing —
+ * a blank where an input should be gives the user no error, no explanation and no way back.
+ */
+export const RENDERABLE_FIELD_TYPES = [
+  'text', 'email', 'number', 'toggle', 'enum', 'json', 'date', 'datetime', 'list',
+  'group', 'variant',
+  'range', 'counters', 'share', 'file', 'media', 'action',
+] as const;
+export type RenderableFieldType = (typeof RENDERABLE_FIELD_TYPES)[number];
+
+/**
+ * **The twenty widgets an ask can name**, for `preferred`. Six of the 26 are missing on purpose:
+ * 20 and 22–26 return nothing, so they are not asks (decision Q5c).
+ */
+export const WIDGET_NAMES = [
+  'text-input-field', 'text-field', 'text-area', 'dropdown', 'button', 'container',
+  'file-upload', 'voice-recorder', 'date-time-picker', 'slider', 'range-picker',
+  'radio-button', 'checkboxes', 'numerical-holder', 'horizontal-list-picker',
+  'pie-chart-picker', 'card-picker', 'arc-picker', 'counter-group',
+  'aggregated-input-card',
+] as const;
+export type WidgetName = (typeof WIDGET_NAMES)[number];
+
+type FieldBase = {
+  key: string;
+  label: string;
+  required?: boolean;
+  /** Full description, shown under the field. Templatable — see `resolveHint`. */
+  hint?: string;
+  /** Renders only when every entry matches the current answers. */
+  showIf?: Record<string, unknown>;
+  /**
+   * **A hint, honoured when legal and dropped when not** (decision Q2b).
+   *
+   * The agent states what the answer IS; the renderer picks how to draw it. This is the escape
+   * valve for the case the derivation gets wrong — and it is safe precisely because it cannot
+   * corrupt the contract: a stored `preferred` that becomes illegal for its type is ignored, not
+   * an error, so a redesign still changes every ask at once.
+   */
+  preferred?: WidgetName;
+};
+
+/**
+ * **An option, rich or bare** (decision Q4a).
+ *
+ * A bare string is still legal and still the common case. The object exists because the Card
+ * Picker's contract is that *score and reason travel to every option shape* — a card face showing
+ * only a name has hidden the run's work.
+ *
+ * ⚠ **The producer side is the real cost here, not the schema.** `score` and `note` are run
+ * output leaking into an ask: whatever composes this JSON now needs access to *why the ranker
+ * ranked*. That coupling is real and was accepted deliberately.
+ */
+export type OptionSpec = {
+  value: string;
+  label: string;
+  /** The run's ordering. The rank disc shows it; the SELECTION is still the user's. */
+  rank?: number;
+  score?: number;
+  /** Why the run put it here. Prose, one or two lines. */
+  note?: string;
+  /** `share` only: this slice's percentage. The slices must sum to 100. */
+  pct?: number;
+  /**
+   * **The way out.** An option that admits the gap rather than answering — *"I don't know"*,
+   * *"I can't tell"*, *"Not yet"*.
+   *
+   * It is a flag rather than a phrase the linter recognises. Detecting an escape by matching
+   * prose was tried first and was wrong twice in one afternoon: it missed *"I can't tell — keep
+   * both"* and *"Not yet — leave them unfiled"*, which are escapes by any reading. A property is
+   * checkable; a wording convention is a rule that holds until someone writes a better sentence.
+   *
+   * It also renders differently — muted until picked, so it reads as an escape rather than as a
+   * candidate.
+   */
+  escape?: boolean;
+};
+
+export type OptionEntry = string | OptionSpec;
+
+/**
+ * **The wordings that mean "no answer", recognised for bare strings only.**
+ *
+ * `escape: true` is the real mechanism — a property, not a phrase. This exists so a plain
+ * `string[]` written before the flag existed keeps its escape, and so an author who writes the
+ * obvious sentence gets the obvious behaviour.
+ *
+ * It lives here, once. It was written twice first — once for bare strings arriving at a widget
+ * and once for options arriving through the schema — and **neither path was the one the adapter
+ * actually used**, so `"I don't know"` rendered at full weight beside the real candidates. The
+ * screenshot showed it; no test did, because no test asserted a colour.
+ */
+const ESCAPE_WORDING = /^(i don't know|i can't tell|not sure|none of these|unsure|no preference)/i;
+
+export const isEscapeWording = (label: string) => ESCAPE_WORDING.test(label);
+
+/** Normalises either form to the rich one, so a renderer never branches on which it got. */
+export function toOption(o: OptionEntry): OptionSpec {
+  return typeof o === 'string'
+    ? { value: o, label: o, escape: isEscapeWording(o) }
+    : { ...o, escape: o.escape ?? isEscapeWording(o.label) };
+}
+
+export type TextFieldSpec = FieldBase & {
+  type: 'text';
+  control?: 'single' | 'multi';
+  default?: string;
+  /** A short specimen value. **Never prose** — that is what `hint` is for. */
+  example?: string;
+  constraints?: { minLength?: number; maxLength?: number; pattern?: string };
+};
+
+export type EmailFieldSpec = FieldBase & {
+  type: 'email';
+  control?: 'single';
+  default?: string;
+  example?: string;
+  constraints?: { maxLength?: number };
+};
+
+export type NumberFieldSpec = FieldBase & {
+  type: 'number';
+  control?: 'single' | 'stepper' | 'slider';
+  default?: number;
+  example?: string;
+  constraints?: { min?: number; max?: number; step?: number; precision?: number };
+};
+
+export type ToggleFieldSpec = FieldBase & {
+  type: 'toggle';
+  control?: 'switch' | 'checkbox';
+  default?: boolean;
+  /* `constraints` and `example` are forbidden by the schema. A specimen value for a boolean is
+     a category error, and there is nothing to constrain. */
+};
+
+/**
+ * One of a set the asker can name — or, with `multiple`, several of it.
+ *
+ * **`multiple: true` is how multi-select arrived** (decision Q3a). It was the single most common
+ * missing case: `enum` was single-select and `list` is free entry, so *"tick any of these four
+ * channels"* had no representation at all. A flag on `enum` keeps one type for one idea — a
+ * closed set — where a separate `multi-enum` would have split it in two.
+ */
+export type EnumFieldSpec = FieldBase & {
+  type: 'enum';
+  control?: 'select' | 'radio' | 'segmented' | 'chips' | 'cards' | 'arc' | 'checkboxes';
+  /** With `multiple`, the default is an array. */
+  default?: string | string[];
+  example?: string;
+  /** Several of the set rather than one. The answer becomes `string[]`. */
+  multiple?: boolean;
+  /** Static options, bare or rich. The schema requires either this or `source`. */
+  options?: OptionEntry[];
+  /** Runtime options from a sibling `LIST_*` tool — resolved by the host, never fetched here. */
+  source?: FieldSource;
+  /** Widgets that submit their own set: the label, and what it says at zero. */
+  submit?: SubmitSpec;
+  /**
+   * **The counter line, which is not the submit label.**
+   *
+   * Conflating the two produced *"Use 1 channels"* on the first spec-driven render: a submit
+   * label is a verb the user presses, a counter line is a statement about what is currently
+   * true. Widget 13 has only the second. `{n}` interpolates; `empty` states the consequence.
+   */
+  counter?: { text: string; empty?: string };
+};
+
+/**
+ * A submit control's two labels.
+ *
+ * **At zero the label states the consequence and the button is not disabled.** `{n}` interpolates
+ * the count. A greyed verb tells the user nothing about what pressing it would do.
+ */
+export type SubmitSpec = { label: string; empty?: string };
+
+/**
+ * A calendar day, or a day and a time.
+ *
+ * **`control: 'presets'` stores the RULE, not a resolved date.** `next-monday` survives the run
+ * being resumed on Thursday; `2026-09-14` does not, and resolving early is how a run ends up
+ * booking last week. The presets reuse `options` rather than adding a `presets` key — one
+ * vocabulary for "a named set the asker can list".
+ */
+export type DateFieldSpec = FieldBase & {
+  type: 'date' | 'datetime';
+  control?: 'picker' | 'presets';
+  /** `presets` only. The `value` is the rule; the `label` is what the chip says. */
+  options?: OptionEntry[];
+  /** ISO. `YYYY-MM-DD` for a date, a full ISO timestamp for a datetime. */
+  default?: string;
+  example?: string;
+  constraints?: { min?: string; max?: string };
+};
+
+export type JsonFieldSpec = FieldBase & {
+  type: 'json';
+  control?: 'code';
+  default?: unknown;
+  example?: string;
+  constraints?: { maxBytes?: number };
+};
+
+/** The element types a list may hold. `list`, `group` and `variant` are excluded. */
+export type ItemType =
+  | 'text' | 'email' | 'number' | 'toggle' | 'date' | 'datetime' | 'enum' | 'json';
+
+export type ListFieldSpec = FieldBase & {
+  type: 'list';
+  control?: 'tags' | 'repeater';
+  default?: unknown[];
+  example?: string;
+  itemType?: ItemType;
+  constraints?: { minItems?: number; maxItems?: number };
+  /** Passed to each element when `itemType` is `enum`. */
+  options?: string[];
+  source?: FieldSource;
+};
+
+export type GroupFieldSpec = FieldBase & {
+  type: 'group';
+  control?: 'section' | 'card';
+  default?: Record<string, unknown>;
+  /** At least one. A group with nothing in it is a heading. */
+  children: FieldSpec[];
+};
+
+/**
+ * A tagged union: the user picks one child and fills in that one.
+ *
+ * **The value carries the tag, not just the payload** — `{ variant, value }`. A bare payload
+ * cannot say which branch produced it, so a variant whose branches happen to share a shape would
+ * round-trip into the wrong one. The tag is the only thing that makes the choice recoverable.
+ */
+export type VariantFieldSpec = FieldBase & {
+  type: 'variant';
+  control?: 'tabs' | 'select';
+  default?: VariantValue;
+  /** At least two. A union of one is the thing itself. */
+  children: FieldSpec[];
+};
+
+export type VariantValue = { variant: string; value?: unknown };
+
+/* ── The six added for the input widgets ─────────────────────────────────── */
+
+/**
+ * **`range` → `[number, number]`** · widget 11.
+ *
+ * One field, not two numbers with a convention between them. The pair is the answer, and the
+ * constraint that makes it one — `lo ≤ hi − 1` — belongs to the field rather than to a
+ * cross-field rule the agent has to remember to write.
+ */
+export type RangeFieldSpec = FieldBase & {
+  type: 'range';
+  control?: 'track';
+  default?: [number, number];
+  example?: string;
+  /** `unit` is display only — `3–9 yrs`. It never travels in the answer. */
+  constraints?: { min?: number; max?: number; step?: number };
+  unit?: string;
+};
+
+/**
+ * **`counters` → `Record<string, number>`** · widget 19.
+ *
+ * Several numbers under one submit. A `group` of `number` fields would validate identically and
+ * draw wrongly: the widget's whole point is that the rows share a total and a single button, and
+ * a group renders each row as its own labelled control.
+ */
+export type CountersFieldSpec = FieldBase & {
+  type: 'counters';
+  control?: 'rows';
+  default?: Record<string, number>;
+  /** At least one. Each row's `key` is a key in the answer object. */
+  rows: CounterRowSpec[];
+  /** Applies to every row. Per-row bounds would be a second vocabulary for the same idea. */
+  constraints?: { min?: number; max?: number };
+  submit?: SubmitSpec;
+  /** `{total}` interpolates. At zero, state the consequence rather than showing `0`. */
+  counter?: { text: string; empty?: string };
+};
+
+export type CounterRowSpec = {
+  key: string;
+  label: string;
+  /** One line under the label. What this row actually costs. */
+  note?: string;
+  default?: number;
+};
+
+/**
+ * **`share` → the picked slice's key** · widget 16.
+ *
+ * ⚠ **Only legal when the options really are parts of one whole.** The percentages must sum to
+ * 100 — a donut asserts a partition, and drawing one over numbers that are not a partition is a
+ * lie the geometry tells before any label can correct it. **JSON Schema cannot sum**, so this is
+ * one of the few rules the validator cannot hold; `lintQuestion` checks it instead.
+ */
+export type ShareFieldSpec = FieldBase & {
+  type: 'share';
+  control?: 'donut';
+  default?: string;
+  /** Rich options carrying `pct`. Bare strings are illegal here — a share needs a number. */
+  options: OptionSpec[];
+  /** `true` when the distribution came from the run rather than from a user. */
+  derived?: boolean;
+};
+
+/**
+ * **`file` → `FileRef[]`** · widget 07.
+ *
+ * **The library renders state only** (decision Q14a). It takes the refs and reports `onAdd` and
+ * `onRemove`; the app runs the picker and the upload. A component library that acquires a file
+ * picker, a transport and a retry policy has stopped being one — the same line `EnumField` draws
+ * by taking resolved options rather than fetching them.
+ */
+export type FileFieldSpec = FieldBase & {
+  type: 'file';
+  control?: 'dropzone';
+  example?: string;
+  constraints?: {
+    maxItems?: number;
+    maxBytes?: number;
+    /** Extensions, uppercase, as the copy shows them: `["PDF", "DOCX"]`. */
+    accept?: string[];
+  };
+};
+
+/** **`media` → one `FileRef`** · widget 08. An audio FILE — this widget produces no transcript. */
+export type MediaFieldSpec = FieldBase & {
+  type: 'media';
+  control?: 'audio';
+  constraints?: { maxSeconds?: number };
+};
+
+/**
+ * **`action` → nothing. Firing it IS the answer** · widget 05.
+ *
+ * The value lives in the envelope's `outcome`, not in `answers`. Two things carry the weight:
+ * `consequence` says what pressing does and that nothing has happened yet, and `done` is what the
+ * control says afterwards — a verb that stays a verb after the deed describes something already
+ * done.
+ */
+export type ActionFieldSpec = FieldBase & {
+  type: 'action';
+  control?: 'buttons';
+  /** What happens on press, and that nothing has yet. Never omitted. */
+  consequence: string;
+  /** `{n}` interpolates `count`. The label carries the count; the count matches what is visible. */
+  confirm: string;
+  /** After the press. States the outcome, not the verb. */
+  done?: string;
+  dismiss?: string;
+  count?: number;
+};
+
+/** A type this build cannot draw yet. Declared so the union stays total. */
+export type UnsupportedFieldSpec = FieldBase & {
+  type: Exclude<FieldType, RenderableFieldType>;
+  control?: string;
+  default?: unknown;
+  example?: string;
+  constraints?: Record<string, unknown>;
+  options?: string[];
+  itemType?: string;
+  source?: FieldSource;
+  children?: FieldSpec[];
+};
+
+/** Runtime options from a sibling `LIST_*` tool. Carried forward from `Field` v2 unchanged. */
+export type FieldSource = {
+  tool: string;
+  args?: Record<string, unknown>;
+  labelPath: string;
+  valuePath: string;
+};
+
+export type FieldSpec =
+  | TextFieldSpec | EmailFieldSpec | NumberFieldSpec
+  | ToggleFieldSpec | EnumFieldSpec | JsonFieldSpec | DateFieldSpec | ListFieldSpec
+  | GroupFieldSpec | VariantFieldSpec
+  | RangeFieldSpec | CountersFieldSpec | ShareFieldSpec
+  | FileFieldSpec | MediaFieldSpec | ActionFieldSpec
+  | UnsupportedFieldSpec;
+
+export type QuestionBlockSpec = {
+  schema: 'question/1';
+  slug: string;
+  /**
+   * Where this question came from. The widget contract's word, not a synonym.
+   *
+   * **`derived` was added by writing the fixtures** (decision Q13b, and the reason for taking
+   * that route). Three widgets ask about the run's own output rather than about the user's plan
+   * — 06's duplicate, 16's distribution, 17's ranking — and calling those `inferred` would have
+   * flattened a distinction that matters: an inference is a guess about the user, a derivation is
+   * a claim about work already done, and being wrong costs differently.
+   */
+  provenance?: 'declared' | 'inferred' | 'derived';
+  /** `false` means the run proceeds and collects the answer later. Default `true`. */
+  blocking?: boolean;
+  /**
+   * **Why the run stopped here** (decision Q6a). Blocking only.
+   *
+   * `question` is what is being asked; this is what went wrong. Widget 06 draws it in its own
+   * tinted block above the ask, because *blocked and offered must never look alike* — and a halt
+   * with no stated cause reads as a bug rather than as a decision waiting on the user.
+   */
+  reason?: string;
+  /** 1-based, matching the widget contract's collection steps. */
+  step?: { index: number; label: string };
+  question: string;
+  fields: FieldSpec[];
+};
+
+/**
+ * **What comes back — always the envelope, never a bare value** (decision Q8b).
+ *
+ * An agent that cannot tell *skipped* from *never answered* will re-ask, or proceed as though it
+ * had an answer. Making that distinction conditional on `blocking` would have returned the
+ * failure exactly where the stakes are lowest and the volume highest, so it is unconditional.
+ *
+ * It travels **alone** (decision Q9a) — the block is not echoed back. The `slug` identifies what
+ * was asked, and whoever asked it still has the block.
+ */
+export type AnswerBlock = {
+  schema: 'answer/1';
+  slug: string;
+  /** ISO 8601. */
+  at: string;
+  state: 'answered' | 'skipped' | 'superseded' | 'failed';
+  /** Keyed by field `key`. Empty for an `action`, whose answer is the outcome itself. */
+  answers: Answers;
+  outcome: 'accept' | 'reject' | 'cancel';
+  /** What the run should do with a rejection. */
+  rejection?: 're-plan' | 'widen' | 'escalate' | 'hard-stop';
+  /** A recorded disagreement: the user chose against a scored recommendation. */
+  overrode?: { chose: string; over: string; score?: number };
+  /** Inherited downstream — a degraded answer taints what is derived from it. */
+  degraded?: boolean;
+  /**
+   * **The app's obligation, not the library's.**
+   *
+   * Re-opening an answered ask sets this. What it *means* — that the run re-plans from this point
+   * — is a statement about run control, and nothing in this library can enforce it. Named here so
+   * it is read as an obligation on the receiver rather than as behaviour the library provides.
+   */
+  superseded?: boolean;
+};
+
+/**
+ * **An imported JSON file, narrowed to a block — with a check rather than a cast.**
+ *
+ * `import block from './ask.json'` gives `schema: string`, not `schema: "question/1"`, so a
+ * literal-typed union rejects it. Every consumer hits this on their first line, and the
+ * workaround they would otherwise copy — `as unknown as QuestionBlockSpec` — silently accepts
+ * *any* object, including the wrong file.
+ *
+ * This costs one runtime comparison and turns a class of mistake into a message. It does not
+ * validate the whole block: `spec/question.schema.json` does that, and a renderer that ran ajv
+ * on every render would be paying for a check the author already ran.
+ */
+export function asQuestionBlock(json: unknown): QuestionBlockSpec {
+  const block = json as QuestionBlockSpec;
+  if (!block || block.schema !== 'question/1') {
+    throw new Error(
+      `Not a question/1 block: schema is ${JSON.stringify((block as { schema?: unknown })?.schema)}. `
+      + 'Validate against @comppack/ui/question.schema.json to find out why.',
+    );
+  }
+  return block;
+}
+
+export type Answers = Record<string, unknown>;
+export type FieldErrors = Record<string, string>;
+
+export type RenderableFieldSpec =
+  | TextFieldSpec | EmailFieldSpec | NumberFieldSpec
+  | ToggleFieldSpec | EnumFieldSpec | JsonFieldSpec | DateFieldSpec | ListFieldSpec
+  | GroupFieldSpec | VariantFieldSpec
+  | RangeFieldSpec | CountersFieldSpec | ShareFieldSpec
+  | FileFieldSpec | MediaFieldSpec | ActionFieldSpec;
+
+export function isRenderable(f: FieldSpec): f is RenderableFieldSpec {
+  return (RENDERABLE_FIELD_TYPES as readonly string[]).includes(f.type);
+}
+
+/**
+ * Options a host resolved from a field's `source`, keyed by field key.
+ *
+ * **Fetching is the host's job.** A `source` names a `LIST_*` tool and the arguments to call it
+ * with; resolving that needs the connector layer, an auth token and a cache. A component library
+ * that acquires those has stopped being a component library.
+ */
+export type ResolvedOptions = Record<string, string[]>;

package/src/generated/StatusChip.tsx

@@ -0,0 +1,22 @@
+/**
+ * GENERATED from spec/components/status-chip.json by tools/generate.ts — component/1.
+ *
+ * Edits here are legal and will be overwritten the next time the JSON is generated. Every value
+ * below is a TOKEN NAME: the generator resolves raw values and refuses to emit anything it
+ * cannot resolve, so a hex literal cannot reach this file.
+ */
+import { Box, Text } from '../core';
+
+export type StatusChipProps = {
+  status: 'executed' | 'running' | 'queued' | 'error';
+  label: string;
+};
+
+/** A status word on its ground. The dot beside it is redundant by design. */
+export function StatusChip({ status, label }: StatusChipProps) {
+  return (
+    <Box row align="center" gap="s1" px="s2" py="s1" bg={`statusBg.${status}`} radius="part.pill">
+      <Text color={`status.${status}`} variant="caption">{label}</Text>
+    </Box>
+  );
+}

package/src/generated/index.ts

@@ -0,0 +1,2 @@
+/* GENERATED. An unexported component did not ship. */
+export { StatusChip, type StatusChipProps } from './StatusChip';

package/src/index.ts

@@ -0,0 +1,18 @@
+/**
+ * `@comppack/ui` — React + React Native component library.
+ *
+ * Components are rendered from JSON; the schema is `spec/question.schema.json` and the
+ * architecture is `SPEC.md`. Import tokens from here too — never inline a material value at a
+ * call site.
+ */
+export * from './tokens';
+export * from './core';
+export * from './values';
+export * from './ds';
+export { fonts, hitTarget, scale, UI_SCALE } from './legacyTokens';
+export * from './fields';
+export * from './widgets';
+/* The component families (Directory · Checklist · Grid · Table) — catalogue shape only today;
+   nothing is implemented. See docs/architecture/COMPONENT-FAMILIES.md. */
+export * from './components';
+export * from './sheets';