@appinternalleads/ui 0.2.0

package/src/fields/GroupField.tsx

@@ -0,0 +1,67 @@
+import { Box, Text } from '../core';
+import { FieldRenderer } from './FieldRenderer';
+import { controlOf, isVisible, resolveHint } from './control';
+import type { FieldErrors, GroupFieldSpec, ResolvedOptions } from './types';
+
+/**
+ * `group` — a set of fields under one name, as a plain section or a raised card.
+ *
+ * **A group reports no error of its own.** Everything wrong with it is wrong with one of its
+ * children, and *"Contact is required"* stacked above three fields that each say what they need
+ * is noise on top of the answer.
+ *
+ * `showIf` on a child resolves against the GROUP's values, not the block's. A group is a scope,
+ * and a condition that reached outside it would make the group's meaning depend on where it was
+ * mounted.
+ */
+export function GroupField({
+  field, value, onChange, errors, path, options,
+}: {
+  field: GroupFieldSpec;
+  value: Record<string, unknown> | undefined;
+  onChange: (next: Record<string, unknown>) => void;
+  errors?: FieldErrors;
+  path: string;
+  options?: ResolvedOptions;
+}) {
+  const obj = value ?? field.default ?? {};
+  const card = controlOf(field) === 'card';
+  const hint = resolveHint(field);
+
+  return (
+    <Box
+      gap="s3"
+      role="group"
+      aria-label={field.label}
+      {...(card
+        ? ({ p: 's4', radius: 'card', bg: 'surface1', lift: 1 } as const)
+        : ({} as const))}>
+      <Box gap="s1">
+        <Text variant="eyebrow" color="textTertiary" uppercase>
+          {field.label}
+        </Text>
+        {hint ? (
+          <Text variant="caption" color="textSecondary">
+            {hint}
+          </Text>
+        ) : null}
+      </Box>
+
+      <Box gap="s4">
+        {field.children
+          .filter(c => isVisible(c, obj))
+          .map(child => (
+            <FieldRenderer
+              key={child.key}
+              field={child}
+              path={`${path}.${child.key}`}
+              value={obj[child.key]}
+              onChange={next => onChange({ ...obj, [child.key]: next })}
+              errors={errors}
+              options={options}
+            />
+          ))}
+      </Box>
+    </Box>
+  );
+}

package/src/fields/JsonField.tsx

@@ -0,0 +1,47 @@
+import { Input } from '../core';
+import { FieldShell } from './FieldShell';
+import { space } from '../tokens';
+import type { JsonFieldSpec } from './types';
+
+/**
+ * `json`, in the `code` control.
+ *
+ * **Mono, and here the rule points the other way from the stepper.** A stepper's value is a
+ * number a human typed, so it is sans; this is machine content the user is editing verbatim, so
+ * it is mono. The face is not about who typed it — it is about what the string IS.
+ *
+ * The value is held as TEXT, never as a parsed object. Round-tripping through `JSON.parse` on
+ * every keystroke reformats what the user is typing underneath them and loses a trailing comma
+ * mid-edit; validity is checked at `validateField`, on blur.
+ */
+export function JsonField({
+  field,
+  value,
+  onChange,
+  error,
+  onBlur,
+}: {
+  field: JsonFieldSpec;
+  value: string | undefined;
+  onChange: (next: string) => void;
+  error?: string;
+  onBlur?: () => void;
+}) {
+  return (
+    <FieldShell field={field} error={error}>
+      <Input
+        value={value ?? ''}
+        onChangeText={onChange}
+        onBlur={onBlur}
+        placeholder={field.example}
+        multiline
+        mono
+        error={Boolean(error)}
+        minHeight={space.s14 * 2}
+        aria-required={field.required}
+        aria-invalid={Boolean(error)}
+        aria-labelledby={`${field.key}-label`}
+      />
+    </FieldShell>
+  );
+}

package/src/fields/ListField.tsx

@@ -0,0 +1,181 @@
+import { useState } from 'react';
+import { Box, Icon, Input, Pressable, Text } from '../core';
+import { useDs } from '../tokens';
+import { FieldRenderer } from './FieldRenderer';
+import { controlOf, itemSpec } from './control';
+import { FieldShell } from './FieldShell';
+import type { FieldErrors, ListFieldSpec, ResolvedOptions } from './types';
+
+type Props = {
+  field: ListFieldSpec;
+  value: unknown[] | undefined;
+  onChange: (next: unknown[]) => void;
+  error?: string;
+  errors?: FieldErrors;
+  path: string;
+  options?: ResolvedOptions;
+};
+
+/**
+ * `list`, as tags or a repeater.
+ *
+ * **`itemType` excludes `list`, `group` and `variant`, and the cap is deliberate.** The widget
+ * contract caps `collection` at one level of nesting for the same reason it gives: a tree of
+ * inputs is a debugger rather than a form. A list of groups of lists is expressible in JSON and
+ * unusable on a 390pt screen.
+ */
+export function ListField({ field, value, onChange, error, errors, path, options }: Props) {
+  const items = value ?? (field.default as unknown[] | undefined) ?? [];
+  const { maxItems } = field.constraints ?? {};
+  const full = maxItems !== undefined && items.length >= maxItems;
+
+  return controlOf(field) === 'repeater' ? (
+    <Repeater
+      field={field}
+      items={items}
+      onChange={onChange}
+      error={error}
+      errors={errors}
+      path={path}
+      options={options}
+      full={full}
+    />
+  ) : (
+    <Tags field={field} items={items} onChange={onChange} error={error} full={full} />
+  );
+}
+
+/**
+ * Chips plus one entry box.
+ *
+ * **Enter commits, and the box does not clear until it does.** A tag input that swallows what
+ * you typed because you tabbed away is the single most common way this control loses data.
+ */
+function Tags({
+  field, items, onChange, error, full,
+}: {
+  field: ListFieldSpec;
+  items: unknown[];
+  onChange: (next: unknown[]) => void;
+  error?: string;
+  full: boolean;
+}) {
+  const { colors } = useDs();
+  const [draft, setDraft] = useState('');
+  const numeric = field.itemType === 'number';
+
+  const commit = () => {
+    const trimmed = draft.trim();
+    if (!trimmed || full) return;
+    onChange([...items, numeric ? Number(trimmed) : trimmed]);
+    setDraft('');
+  };
+
+  return (
+    <FieldShell field={field} error={error}>
+      <Box gap="s2">
+        {items.length > 0 ? (
+          <Box row wrap gap="s2">
+            {items.map((item, i) => (
+              <Box
+                key={`${String(item)}-${i}`}
+                row
+                align="center"
+                gap="s1"
+                py="s1"
+                px="s3"
+                radius="pill"
+                bg="surfaceSunken">
+                <Text variant="caption" color="textSecondary">
+                  {String(item)}
+                </Text>
+                <Pressable
+                  onPress={() => onChange(items.filter((_, n) => n !== i))}
+                  hit={24}
+                  aria-label={`Remove ${String(item)}`}>
+                  <Icon name="close" size={12} color={colors.textTertiary} />
+                </Pressable>
+              </Box>
+            ))}
+          </Box>
+        ) : null}
+
+        {full ? null : (
+          <Input
+            value={draft}
+            onChangeText={setDraft}
+            onBlur={commit}
+            placeholder={field.example}
+            numeric={numeric}
+            error={Boolean(error)}
+            aria-labelledby={`${field.key}-label`}
+          />
+        )}
+      </Box>
+    </FieldShell>
+  );
+}
+
+/**
+ * One full field per element, each removable, with an add row beneath.
+ *
+ * This is where a list of anything other than a short string belongs — a `tags` chip cannot show
+ * a date picker or a toggle, and squeezing one in would make the chip the widget.
+ */
+function Repeater({
+  field, items, onChange, error, errors, path, options, full,
+}: {
+  field: ListFieldSpec;
+  items: unknown[];
+  onChange: (next: unknown[]) => void;
+  error?: string;
+  errors?: FieldErrors;
+  path: string;
+  options?: ResolvedOptions;
+  full: boolean;
+}) {
+  const { colors } = useDs();
+  return (
+    <FieldShell field={field} error={error}>
+      <Box gap="s3">
+        {items.map((item, i) => (
+          <Box key={i} row align="flex-start" gap="s2">
+            <Box flex={1}>
+              <FieldRenderer
+                field={itemSpec(field, i)}
+                path={`${path}.${i}`}
+                value={item}
+                onChange={next => onChange(items.map((v, n) => (n === i ? next : v)))}
+                errors={errors}
+                options={options}
+              />
+            </Box>
+            <Pressable
+              onPress={() => onChange(items.filter((_, n) => n !== i))}
+              hit={44}
+              aria-label={`Remove ${field.label} ${i + 1}`}>
+              <Icon name="close" size={14} color={colors.textTertiary} />
+            </Pressable>
+          </Box>
+        ))}
+
+        {full ? null : (
+          <Pressable
+            onPress={() => onChange([...items, undefined])}
+            row
+            align="center"
+            justify="flex-start"
+            gap="s2"
+            py="s2"
+            aria-label={`Add ${field.label}`}
+            style={{ minHeight: 44 }}>
+            <Icon name="plus" size={14} color={colors.accentInk} />
+            <Text variant="caption" color="accentInk">
+              Add
+            </Text>
+          </Pressable>
+        )}
+      </Box>
+    </FieldShell>
+  );
+}

package/src/fields/NumberField.tsx

@@ -0,0 +1,150 @@
+import { Box, Icon, Input, Pressable, Slider, Text } from '../core';
+import { useDs } from '../tokens';
+import { FieldShell } from './FieldShell';
+import { controlOf } from './control';
+import type { NumberFieldSpec } from './types';
+
+const clamp = (n: number, min?: number, max?: number) =>
+  Math.min(max ?? Number.POSITIVE_INFINITY, Math.max(min ?? Number.NEGATIVE_INFINITY, n));
+
+/**
+ * **Module scope, and that is a correctness requirement rather than a style preference.**
+ *
+ * Defined inside `NumberField` this is a NEW component type on every render, so React unmounts
+ * and remounts the `Pressable` whenever any state changes. In a browser that swallowed the first
+ * press after focus left a text field: blurring re-rendered the parent, the button was replaced
+ * mid-gesture, and the press landed on an element that no longer existed. The second press
+ * worked, which is what made it look like a flake.
+ *
+ * The unit tests never caught it because they pressed the stepper without a preceding focus
+ * change — there was no re-render between mount and press.
+ *
+ * A control at its bound is disabled, not hidden. A button that vanishes at the limit moves the
+ * one beside it under the thumb already reaching for it.
+ */
+function Step({
+  dir, disabled, label, onPress,
+}: {
+  dir: -1 | 1;
+  disabled: boolean;
+  label: string;
+  onPress: () => void;
+}) {
+  const { colors } = useDs();
+  return (
+    <Pressable
+      onPress={onPress}
+      disabled={disabled}
+      hit={44}
+      radius="control"
+      aria-label={`${dir === 1 ? 'Increase' : 'Decrease'} ${label}`}>
+      <Icon
+        name={dir === 1 ? 'plus' : 'minus'}
+        size={16}
+        color={disabled ? colors.textDisabled : colors.textPrimary}
+      />
+    </Pressable>
+  );
+}
+
+/**
+ * `number`, in the `stepper` and `single` controls.
+ *
+ * **The value is set in the sans face, not mono.** The rule is *a number a human typed is
+ * Switzer; a number the system computed is mono* — a stepper's value is the user's own answer,
+ * so it is prose about a quantity rather than a machine reading. Mono here would make an input
+ * look like output. It is `numeric` all the same, so the field does not twitch as the value
+ * crosses a digit width.
+ */
+export function NumberField({
+  field,
+  value,
+  onChange,
+  error,
+  onBlur,
+}: {
+  field: NumberFieldSpec;
+  value: number | undefined;
+  onChange: (next: number | undefined) => void;
+  error?: string;
+  onBlur?: () => void;
+}) {
+  const { min, max, step = 1 } = field.constraints ?? {};
+  const control = controlOf(field);
+  const current = value ?? field.default ?? min ?? 0;
+
+  if (control === 'slider') {
+    /* A slider without bounds is a scrollbar for an unknown range. `min`/`max` default only so
+       the control still draws while a spec is being written; a real one declares both. */
+    return (
+      <FieldShell field={field} error={error}>
+        <Box row align="center" gap="s3">
+          <Slider
+            value={current}
+            onChange={onChange}
+            min={min ?? 0}
+            max={max ?? 100}
+            step={step}
+            aria-label={field.label}
+            testID={`${field.key}-slider`}
+          />
+          {/* The value has to be readable while dragging — a slider with no number is a
+              gesture with no answer. */}
+          <Text numeric color="textSecondary">
+            {current}
+          </Text>
+        </Box>
+      </FieldShell>
+    );
+  }
+
+  if (control !== 'stepper') {
+    return (
+      <FieldShell field={field} error={error}>
+        <Input
+          value={value === undefined ? '' : String(value)}
+          onChangeText={t => onChange(t === '' ? undefined : Number(t))}
+          onBlur={onBlur}
+          placeholder={field.example}
+          numeric
+          error={Boolean(error)}
+          aria-required={field.required}
+          aria-invalid={Boolean(error)}
+          aria-labelledby={`${field.key}-label`}
+        />
+      </FieldShell>
+    );
+  }
+
+  const atMin = min !== undefined && current <= min;
+  const atMax = max !== undefined && current >= max;
+
+  return (
+    <FieldShell field={field} error={error}>
+      <Box
+        row
+        align="center"
+        justify="space-between"
+        px="s1"
+        radius="field"
+        bg="surface1"
+        edge={error ? 'fieldError' : 'field'}>
+        <Step
+          dir={-1}
+          disabled={atMin}
+          label={field.label}
+          onPress={() => onChange(clamp(current - step, min, max))}
+        />
+        <Text numeric aria-labelledby={`${field.key}-label`}>
+          {current}
+        </Text>
+        <Step
+          dir={1}
+          disabled={atMax}
+          label={field.label}
+          onPress={() => onChange(clamp(current + step, min, max))}
+        />
+      </Box>
+    </FieldShell>
+  );
+}

package/src/fields/QuestionBlock.tsx

@@ -0,0 +1,136 @@
+import { useCallback, useMemo, useRef, useState } from 'react';
+import { Box, Text } from '../core';
+import { FieldRenderer } from './FieldRenderer';
+import { initialAnswers, isVisible, validateBlock, validateField } from './control';
+import type {
+  Answers, FieldErrors, FieldSpec, QuestionBlockSpec, ResolvedOptions,
+} from './types';
+
+export type QuestionBlockProps = {
+  block: QuestionBlockSpec;
+  /** Controlled when supplied; otherwise the block holds its own answers. */
+  answers?: Answers;
+  onChange?: (answers: Answers) => void;
+  /**
+   * Errors from the host, merged over the ones this block finds on blur.
+   *
+   * **The block deliberately has no submit button.** The JSON describes the question, not the
+   * screen around it, so inventing an affordance the spec never mentions would put a control in
+   * every host whether or not it wanted one. A host renders its own button, calls
+   * `QuestionBlock.validate(block, answers)`, and passes what it gets back in here.
+   */
+  errors?: FieldErrors;
+  /**
+   * Options a host resolved from a field's `source`, keyed by field key.
+   *
+   * Absent means *not resolved yet* and renders as such; an empty array means the tool returned
+   * nothing. `EnumField` draws those differently on purpose — see its note.
+   */
+  options?: ResolvedOptions;
+};
+
+/**
+ * Renders one question block from its JSON.
+ *
+ * **Errors surface on blur, not on keystroke.** Validating as someone types tells them their
+ * half-written email address is invalid, which they already know; the field they have left is
+ * the first moment the answer is a claim rather than a work in progress. Once a field has
+ * errored it revalidates live, because at that point the user is fixing something and silence
+ * until the next blur would hide the fix.
+ */
+export function QuestionBlock({
+  block, answers, onChange, errors: hostErrors, options,
+}: QuestionBlockProps) {
+  const [own, setOwn] = useState<Answers>(() => initialAnswers(block));
+  const [blurred, setBlurred] = useState<FieldErrors>({});
+
+  const current = answers ?? own;
+  /**
+   * ⚠ **The freshest answers, for a blur that arrives in the same tick as its own change.**
+   *
+   * `DatePicker` commits by calling `onChange(next)` and then `onBlur()` synchronously — correctly,
+   * because a picker has no blur of its own and the value IS the discrete choice. But `blur` closes
+   * over `current`, which React has not updated yet, so it validated the value the field held
+   * BEFORE the pick and wrote "required" onto a field that had just been filled.
+   *
+   * Measured 2026-09-07 on a device: picking 15 September put `2026-09-15T11:30` in the field, the
+   * counter moved to "2 filled in", and the field showed a red ring reading *"Date and Time is
+   * required."* — the two halves of the same component disagreeing about whether it had an answer.
+   *
+   * A ref rather than reordering the two calls, because the ordering is the picker's business and
+   * every other control that ever commits-then-blurs would hit this the same way.
+   */
+  const latest = useRef(current);
+  latest.current = current;
+  const errors = useMemo(() => ({ ...blurred, ...hostErrors }), [blurred, hostErrors]);
+  const visible = useMemo(() => block.fields.filter(f => isVisible(f, current)), [block, current]);
+
+  const set = useCallback(
+    (field: FieldSpec, value: unknown) => {
+      const next = { ...current, [field.key]: value };
+      /* Before any state update, so a blur firing later in this same tick sees the new value. */
+      latest.current = next;
+      if (answers === undefined) setOwn(next);
+      onChange?.(next);
+      setBlurred(prev => {
+        if (!prev[field.key]) return prev;
+        const e = validateField(field, value, options?.[field.key]);
+        const { [field.key]: _drop, ...rest } = prev;
+        return e ? { ...rest, [field.key]: e } : rest;
+      });
+    },
+    [answers, current, onChange, options],
+  );
+
+  const blur = useCallback(
+    (field: FieldSpec) => {
+      const e = validateField(field, latest.current[field.key], options?.[field.key]);
+      setBlurred(prev => {
+        if (!e) {
+          const { [field.key]: _drop, ...rest } = prev;
+          return rest;
+        }
+        return { ...prev, [field.key]: e };
+      });
+    },
+    [options],
+  );
+
+  return (
+    <Box gap="s5" role="form" testID={`question-${block.slug}`}>
+      <Box gap="s1">
+        {block.step ? (
+          <Text variant="eyebrow" color="textTertiary" uppercase>
+            {`Step ${block.step.index} · ${block.step.label}`}
+          </Text>
+        ) : null}
+        <Text variant="heading" role="heading">
+          {block.question}
+        </Text>
+      </Box>
+
+      <Box gap="s4">
+        {visible.map(field => (
+          <FieldRenderer
+            key={field.key}
+            field={field}
+            path={field.key}
+            value={current[field.key]}
+            onChange={v => set(field, v)}
+            onBlur={() => blur(field)}
+            errors={errors}
+            options={options}
+          />
+        ))}
+      </Box>
+    </Box>
+  );
+}
+
+/**
+ * Every error in the block, for a host driving submission from its own button.
+ *
+ * Attached to the component rather than only exported loose so a host that has the component
+ * already does not have to find a second import to validate what it is rendering.
+ */
+QuestionBlock.validate = validateBlock;

package/src/fields/TextInputField.tsx

@@ -0,0 +1,51 @@
+import { Input } from '../core';
+import { space } from '../tokens';
+import { FieldShell } from './FieldShell';
+import { controlOf } from './control';
+import type { EmailFieldSpec, TextFieldSpec } from './types';
+
+/**
+ * `text` and `email`, in both controls.
+ *
+ * The well, its three hairline states and Android's M3 treatment all live in `Input` — this
+ * file decides only which of them apply, which is the whole reason the primitive layer exists.
+ */
+export function TextInputField({
+  field,
+  value,
+  onChange,
+  error,
+  onBlur,
+}: {
+  field: TextFieldSpec | EmailFieldSpec;
+  value: string | undefined;
+  onChange: (next: string) => void;
+  error?: string;
+  onBlur?: () => void;
+}) {
+  const multi = controlOf(field) === 'multi';
+
+  return (
+    <FieldShell field={field} error={error}>
+      <Input
+        value={value ?? ''}
+        onChangeText={onChange}
+        onBlur={onBlur}
+        placeholder={field.example}
+        multiline={multi}
+        maxLength={field.constraints?.maxLength}
+        email={field.type === 'email'}
+        error={Boolean(error)}
+        /* Four lines of room. A textarea that starts at one line and grows hides how much the
+           field expects; one that starts tall says "a paragraph". */
+        minHeight={multi ? space.s14 * 2 : undefined}
+        aria-required={field.required}
+        aria-invalid={Boolean(error)}
+        aria-labelledby={`${field.key}-label`}
+        aria-describedby={
+          error ? `${field.key}-error` : field.hint ? `${field.key}-hint` : undefined
+        }
+      />
+    </FieldShell>
+  );
+}