@appinternalleads/ui 0.2.0 → 0.3.0

package/src/components/threshold-flow/contract.ts

@@ -1,5 +1,5 @@
-import type { DataType, Hue } from '../../tokens';
-import { DATA_TYPES, HUES } from '../../tokens';
+import type { DataType, Hue } from '../../tokens/hue';
+import { DATA_TYPES, HUES } from '../../tokens/hue';
 
 /**
  * **`threshold-flow/1` — the portable ThresholdFlow document.**
@@ -49,11 +49,16 @@ export type ThresholdUnit = {
   max?: number;
 };
 
-/** Every visible string the flow owns. All optional in the document; `copyFor` fills the rest. */
+/**
+ * **Every word the flow shows that is not in the stages themselves.** All optional in the document;
+ * `copyFor` fills the rest from `THRESHOLD_FLOW_COPY`. A value may hold placeholders, filled at
+ * render: `{one}` / `{other}` (the flow's `noun`), `{count}`, `{title}` (a stage's title), and the
+ * ones each key's comment names. A blank value falls back to the default.
+ */
 export type ThresholdFlowCopy = {
   /** The primary button: "Activate approval". */
   action: string;
-  /** The primary button while activating: "Activating…". */
+  /** The primary button, and the status chip, while activating: "Activating…". */
   activating: string;
   /** The primary button after a failed activation: "Try again". */
   retry: string;
@@ -63,15 +68,80 @@ export type ThresholdFlowCopy = {
   checking: string;
   /** The footer's unit note: "amounts in USD". */
   unit: string;
-  /** The button that leaves live and unlocks the stages: "Edit stages". */
+  /** The button that leaves live and unlocks the stages: "Edit {other}". */
   edit: string;
+  /** Add, under the stages: "Add {one}". */
+  add: string;
   emptyTitle: string;
   emptyBody: string;
   emptyCta: string;
   /** The failed-activation callout's title. Its body is the host's error message. */
   errorTitle: string;
+  /** The status chip once live. */
+  statusLive: string;
+  /** The status chip while a stage needs fixing, or after a refusal. */
+  statusAttention: string;
+  /** The stage count (chip and footer), one stage: "{count} {one}". */
+  countOne: string;
+  /** The stage count, any other number: "{count} {other}". */
+  countOther: string;
+  /** The footer when one stage is invalid: "{count} {one} needs fixing". */
+  fixOne: string;
+  /** The footer when several are: "{count} {other} need fixing". */
+  fixOther: string;
+  /** The stage list's accessible name: "{title} {other}" — `{title}` is the flow's title. */
+  listLabel: string;
+  /** A stage's remove button (accessible name): "Remove {title}". */
+  remove: string;
+  /** A stage's empty or zero value. */
+  errorEmpty: string;
+  /** A stage over `unit.max`: "Must be {max} or less." */
+  errorOverMax: string;
+  /** A stage not above the one before: "Must be more than {previous} ({value})." */
+  errorNotMore: string;
+  /** What a screen reader hears while the host fetches the flow: "Loading {title}". */
+  loading: string;
+  /** The title of a document the validator refused. Its body is the validator's own messages. */
+  refused: string;
+  /** The card's title when a refused document has none. */
+  untitled: string;
+};
+
+/** The English default for every key of `ThresholdFlowCopy`. */
+export const THRESHOLD_FLOW_COPY: ThresholdFlowCopy = {
+  action: 'Activate',
+  activating: 'Activating…',
+  retry: 'Try again',
+  live: 'Live',
+  checking: 'Checking…',
+  unit: '',
+  edit: 'Edit {other}',
+  add: 'Add {one}',
+  emptyTitle: 'No {other} yet',
+  emptyBody: 'Add a {one} to get started.',
+  emptyCta: 'Add first {one}',
+  errorTitle: 'Couldn’t activate',
+  statusLive: 'Live',
+  statusAttention: 'Needs attention',
+  countOne: '{count} {one}',
+  countOther: '{count} {other}',
+  fixOne: '{count} {one} needs fixing',
+  fixOther: '{count} {other} need fixing',
+  listLabel: '{title} {other}',
+  remove: 'Remove {title}',
+  errorEmpty: 'Enter a value greater than 0.',
+  errorOverMax: 'Must be {max} or less.',
+  errorNotMore: 'Must be more than {previous} ({value}).',
+  loading: 'Loading {title}',
+  refused: 'This flow can’t be shown',
+  untitled: 'ThresholdFlow',
 };
 
+/** Fill `{name}` placeholders. An unknown placeholder is left as written. */
+export function fillCopy(template: string, vars: Record<string, string | number>): string {
+  return template.replace(/\{(\w+)\}/g, (m, k: string) => (k in vars ? String(vars[k]) : m));
+}
+
 export type ThresholdFlowConfig = {
   /** Resolves the hue through `TYPE_HUE`. Preferred over `hue`. */
   type?: DataType;
@@ -107,23 +177,20 @@ export const MAX_STAGES = 8;
 
 export const DEFAULT_NOUN = { one: 'stage', other: 'stages' } as const;
 
-/** The prototype's own default copy, used for any key the document omits. */
+/**
+ * The flow's copy: `THRESHOLD_FLOW_COPY` ← the document's `copy` (non-blank strings only), with the
+ * noun placeholders (`{one}`, `{other}`) filled. Other placeholders are filled where used.
+ */
 export function copyFor(config: ThresholdFlowConfig): ThresholdFlowCopy {
   const noun = config.noun ?? DEFAULT_NOUN;
-  return {
-    action: 'Activate',
-    activating: 'Activating…',
-    retry: 'Try again',
-    live: 'Live',
-    checking: 'Checking…',
-    unit: '',
-    edit: `Edit ${noun.other}`,
-    emptyTitle: `No ${noun.other} yet`,
-    emptyBody: `Add a ${noun.one} to get started.`,
-    emptyCta: `Add first ${noun.one}`,
-    errorTitle: 'Couldn’t activate',
-    ...config.copy,
-  };
+  const given = config.copy && typeof config.copy === 'object' ? config.copy : {};
+  const out = { ...THRESHOLD_FLOW_COPY };
+  for (const k of Object.keys(out) as (keyof ThresholdFlowCopy)[]) {
+    const v = (given as Partial<ThresholdFlowCopy>)[k];
+    if (typeof v === 'string' && v.trim()) out[k] = v;
+    out[k] = fillCopy(out[k], { one: noun.one, other: noun.other });
+  }
+  return out;
 }
 
 export function nounFor(config: ThresholdFlowConfig, count: number): string {
@@ -177,6 +244,14 @@ export function validateThresholdFlow(doc: unknown): ThresholdFlowIssue[] {
   if (!Array.isArray(p.defaultItems)) return [...issues, { code: 'schema', message: 'props.defaultItems must be an array.' }];
   if (p.type !== undefined && !DATA_TYPES.includes(p.type)) issues.push({ code: 'unknown-type', message: `Unknown type "${String(p.type)}".` });
   if (p.hue !== undefined && !HUES.includes(p.hue)) issues.push({ code: 'unknown-hue', message: `Unknown hue "${String(p.hue)}".` });
+  if (p.copy !== undefined) {
+    if (!p.copy || typeof p.copy !== 'object' || Array.isArray(p.copy)) issues.push({ code: 'schema', message: 'props.copy must be an object of strings.' });
+    else {
+      for (const [k, v] of Object.entries(p.copy)) {
+        if (typeof v !== 'string') issues.push({ code: 'schema', message: `props.copy.${k} must be text.` });
+      }
+    }
+  }
   if (p.defaultItems.length > MAX_STAGES) issues.push({ code: 'too-many', message: `At most ${MAX_STAGES} stages.` });
 
   const seen = new Set<string>();
@@ -219,14 +294,15 @@ export function validateThresholdFlow(doc: unknown): ThresholdFlowIssue[] {
 export function stageErrors(
   stages: { id: string; title: string; value: number | null }[],
   unit?: ThresholdUnit,
+  copy: Pick<ThresholdFlowCopy, 'errorEmpty' | 'errorOverMax' | 'errorNotMore'> = THRESHOLD_FLOW_COPY,
 ): Record<string, string> {
   const out: Record<string, string> = {};
   stages.forEach((s, i) => {
-    if (s.value === null || !(s.value > 0)) { out[s.id] = 'Enter a value greater than 0.'; return; }
-    if (unit?.max !== undefined && s.value > unit.max) { out[s.id] = `Must be ${formatValue(unit, unit.max)} or less.`; return; }
+    if (s.value === null || !(s.value > 0)) { out[s.id] = copy.errorEmpty; return; }
+    if (unit?.max !== undefined && s.value > unit.max) { out[s.id] = fillCopy(copy.errorOverMax, { max: formatValue(unit, unit.max) }); return; }
     const prev = stages[i - 1];
     if (prev && prev.value !== null && s.value <= prev.value) {
-      out[s.id] = `Must be more than ${prev.title} (${formatValue(unit, prev.value)}).`;
+      out[s.id] = fillCopy(copy.errorNotMore, { previous: prev.title, value: formatValue(unit, prev.value) });
     }
   });
   return out;

package/src/components/threshold-flow/engine.ts

@@ -1,5 +1,5 @@
 import {
-  stageErrors, type ThresholdFlowConfig, type ThresholdFlowDocument, type ThresholdItem,
+  copyFor, stageErrors, type ThresholdFlowConfig, type ThresholdFlowDocument, type ThresholdItem,
 } from './contract';
 
 /**
@@ -97,7 +97,7 @@ export const isLocked = (s: ThresholdFlowState) => s.phase === 'activating' || s
 
 /** Per-stage messages, derived. */
 export function errorsOf(s: ThresholdFlowState, config: ThresholdFlowConfig): Record<string, string> {
-  return stageErrors(liveStages(s), config.unit);
+  return stageErrors(liveStages(s), config.unit, copyFor(config));
 }
 
 export function canAdd(s: ThresholdFlowState, config: ThresholdFlowConfig): boolean {

package/src/components/threshold-flow/index.ts

@@ -5,7 +5,7 @@
  * `docs/components/threshold-flow/THRESHOLD-FLOW.md`.
  */
 export {
-  THRESHOLD_FLOW_SCHEMA, MAX_STAGES, DEFAULT_NOUN,
+  THRESHOLD_FLOW_SCHEMA, THRESHOLD_FLOW_COPY, MAX_STAGES, DEFAULT_NOUN,
   answerOf, copyFor, formatValue, nounFor, stageErrors, validateThresholdFlow,
   type ThresholdFlowConfig, type ThresholdFlowCopy, type ThresholdFlowDocument, type ThresholdFlowIssue,
   type ThresholdItem, type ThresholdTemplate, type ThresholdUnit,

package/src/ds/blockControls.tsx

@@ -556,7 +556,7 @@ export const STEPPER_REPEAT_MS = 80;
  * limits — and each button disables at its limit rather than vanishing. Holding a button repeats.
  */
 export function NumberStepper({
-  label, value, onChange, min, max, step = 1, disabled, format,
+  label, value, onChange, min, max, step = 1, disabled, format, increaseLabel, decreaseLabel,
 }: {
   label: string;
   value: number;
@@ -567,6 +567,10 @@ export function NumberStepper({
   disabled?: boolean;
   /** The value in words for a screen reader and the display — "4 seats". */
   format?: (n: number) => string;
+  /** The + button's name; default "Increase {label}". */
+  increaseLabel?: string;
+  /** The − button's name; default "Decrease {label}". */
+  decreaseLabel?: string;
 }) {
   const { colors, density } = useDs();
   const clamp = (n: number) => Math.min(max, Math.max(min, n));
@@ -597,7 +601,7 @@ export function NumberStepper({
     const atLimit = dir === 1 ? value >= max : value <= min;
     return (
       <Pressable
-        aria-label={dir === 1 ? `Increase ${label}` : `Decrease ${label}`}
+        aria-label={dir === 1 ? increaseLabel ?? `Increase ${label}` : decreaseLabel ?? `Decrease ${label}`}
         disabled={disabled || atLimit}
         onPress={() => bump(dir)}
         onPressIn={() => startHold(dir)}

package/src/ds/blocks.tsx

@@ -197,6 +197,8 @@ export type BlockCardProps = {
    * `action` replaces it with the caller's own control.
    */
   error?: { title: string; body: string; action?: ReactNode; onRetry?: () => void; retryLabel?: string; chipLabel?: string };
+  /** What a screen reader hears while the card loads. Default: "Loading <title>". */
+  loadingLabel?: string;
   /** Left of the footer: a line of state — "Live · runs on every new request". */
   hint?: ReactNode;
   /** Right of the footer: the card's buttons. One primary per view. */
@@ -244,7 +246,7 @@ const SKELETON_ROWS: [`${number}%`, `${number}%`][] = [['44%', '28%'], ['36%', '
  * ready body, which keeps the user's work on screen.
  */
 export function BlockCard({
-  title, subtitle, icon, type, hue, meta, status = 'ready', empty, error, hint, actions, children, testID, style, header = true,
+  title, subtitle, icon, type, hue, meta, status = 'ready', empty, error, hint, actions, children, testID, style, header = true, loadingLabel,
   flush = false, footer = 'row', metaWraps = false,
 }: BlockCardProps) {
   const { colors, lift1 } = useDs();
@@ -256,7 +258,7 @@ export function BlockCard({
   let body: ReactNode = children;
   if (status === 'loading') {
     body = (
-      <Box gap="s4" role="progressbar" aria-label={`Loading ${title}`} aria-busy>
+      <Box gap="s4" role="progressbar" aria-label={loadingLabel ?? `Loading ${title}`} aria-busy>
         {SKELETON_ROWS.map(([a, b]) => (
           <Box key={a} row align="center" gap="s3">
             <Box width={32} height={32} style={{ borderRadius: blockRadii.tile, backgroundColor: colors.band }} />

package/src/index.ts

@@ -16,3 +16,5 @@ export * from './widgets';
    nothing is implemented. See docs/architecture/COMPONENT-FAMILIES.md. */
 export * from './components';
 export * from './sheets';
+/* The agent component contract: search, describe, render/1, validation, result/1. */
+export * from './agent';

package/src/runtime/query/filters.ts

@@ -0,0 +1,35 @@
+/** The filter primitive, pure: no React — `queryEngine` re-exports it, and contracts import it directly. */
+
+/**
+ * **The one filter primitive — N1/N5, decided 2026-09-18.** A filter is `{ column, op, value }`
+ * over a column of the data contract, whoever authored it. A USER's chip and an AGENT's dynamic
+ * addition are the same object, differing only in `author`; there is no second filter system. The
+ * shape is the handoff's own (`{ "column": "category", "op": "eq", "value": "Materials" }`).
+ */
+export const FILTER_OPS = [
+  /* text / any */ 'eq', 'neq', 'contains', 'startsWith',
+  /* ordered: numbers and dates alike, compared by the adapter in the column's own domain */
+  'gt', 'gte', 'lt', 'lte', 'between',
+  /* multi-value cells ("Paperback, Ebook") and set membership */ 'includes',
+  /* presence */ 'isEmpty', 'isNotEmpty',
+] as const;
+export type FilterOp = (typeof FILTER_OPS)[number];
+
+/**
+ * Operators that need no `value` — the rule is complete without one, so `validateFilter` must not
+ * reject them for an empty value.
+ */
+export const VALUELESS_FILTER_OPS: readonly FilterOp[] = ['isEmpty', 'isNotEmpty'];
+
+/** `between` carries two bounds in `value`, separated by this. Kept as one string so a filter stays
+    one flat `{ column, op, value }` — the shape both authors share and the descriptor already has. */
+export const RANGE_SEPARATOR = '..';
+export type FilterAuthor = 'user' | 'agent';
+/**
+ * `not` negates the match, and exists because a rule's consequence can be *exclude these* as
+ * easily as *show only these*. Negation belongs here rather than in a doubled operator list:
+ * `neq` would have needed a partner for each of the other eleven, and the two questions "does
+ * this cell match" and "do I want the ones that match" are genuinely separate. Absent or `false`
+ * means an ordinary filter, so every existing filter and fixture is unaffected.
+ */
+export type QueryFilter = { column: string; op: FilterOp; value: string; author?: FilterAuthor; not?: boolean };

package/src/runtime/query/queryEngine.ts

@@ -51,39 +51,10 @@ export function createEpochGuard() {
 
 // ── DataAdapter contract (README "Data fetching") ─────────────────────────────────────────────
 
-/**
- * **The one filter primitive — N1/N5, decided 2026-09-18.** A filter is `{ column, op, value }`
- * over a column of the data contract, whoever authored it. A USER's chip and an AGENT's dynamic
- * addition are the same object, differing only in `author`; there is no second filter system. The
- * shape is the handoff's own (`{ "column": "category", "op": "eq", "value": "Materials" }`).
- */
-export const FILTER_OPS = [
-  /* text / any */ 'eq', 'neq', 'contains', 'startsWith',
-  /* ordered: numbers and dates alike, compared by the adapter in the column's own domain */
-  'gt', 'gte', 'lt', 'lte', 'between',
-  /* multi-value cells ("Paperback, Ebook") and set membership */ 'includes',
-  /* presence */ 'isEmpty', 'isNotEmpty',
-] as const;
-export type FilterOp = (typeof FILTER_OPS)[number];
-
-/**
- * Operators that need no `value` — the rule is complete without one, so `validateFilter` must not
- * reject them for an empty value.
- */
-export const VALUELESS_FILTER_OPS: readonly FilterOp[] = ['isEmpty', 'isNotEmpty'];
-
-/** `between` carries two bounds in `value`, separated by this. Kept as one string so a filter stays
-    one flat `{ column, op, value }` — the shape both authors share and the descriptor already has. */
-export const RANGE_SEPARATOR = '..';
-export type FilterAuthor = 'user' | 'agent';
-/**
- * `not` negates the match, and exists because a rule's consequence can be *exclude these* as
- * easily as *show only these*. Negation belongs here rather than in a doubled operator list:
- * `neq` would have needed a partner for each of the other eleven, and the two questions "does
- * this cell match" and "do I want the ones that match" are genuinely separate. Absent or `false`
- * means an ordinary filter, so every existing filter and fixture is unaffected.
- */
-export type QueryFilter = { column: string; op: FilterOp; value: string; author?: FilterAuthor; not?: boolean };
+/* The filter primitive — its operators and shape — is pure, and lives in `./filters` so contracts
+   and servers can use it without React. Re-exported here: the public surface is unchanged. */
+export { FILTER_OPS, RANGE_SEPARATOR, VALUELESS_FILTER_OPS, type FilterAuthor, type FilterOp, type QueryFilter } from './filters';
+import { FILTER_OPS, RANGE_SEPARATOR, VALUELESS_FILTER_OPS, type FilterAuthor, type FilterOp, type QueryFilter } from './filters';
 
 export type FilterRejection = 'unknown-column' | 'bad-operator' | 'empty-value' | 'filter-not-served';
 export type FilterCheck = { ok: true } | { ok: false; reason: FilterRejection };