@appinternalleads/ui 0.2.0

package/src/components/onboarding/receipt-printer/ReceiptPrinterView.tsx

@@ -0,0 +1,477 @@
+import { useEffect, useId, useRef, useState, type ComponentType, type ReactNode } from 'react';
+import { Box, Input, Select, Text, useReduceMotion } from '../../../core';
+import { Button, Callout, Checkbox, IconButton } from '../../../ds';
+import { useDs, type DensityName } from '../../../tokens';
+import { useOperationRunner } from '../../../runtime/operations';
+import { resolveConfig, type OnboardingPreset, type OnboardingResult, type PatternStatus } from '../shared/contract';
+import { ONBOARDING_TIMING, type OnboardingOperation } from '../shared/mock';
+import { InvalidConfig } from '../shared/InvalidConfig';
+import { FieldLabel, OnboardingCard } from '../shared/OnboardingCard';
+import { Hidden } from '../shared/parts';
+import { runOutcome, useDefaultOperation, usePatternStatus, useSceneReport, useSeededReducer } from '../shared/runtime';
+import { guarded } from '../shared/guard';
+import {
+  RECEIPT_MAX_LENGTH, RECEIPT_PRINTER_PRESETS, validateReceiptPrinter,
+  type ReceiptField, type ReceiptFieldDef, type ReceiptItemField, type ReceiptPrinterSettings, type ReceiptValues,
+} from './contract';
+import {
+  currenciesOf, hasChoices, initialReceiptPrinter, methodsOf, receiptPrinterSeed, receiptPrinterView, reduceReceiptPrinter, valuesOf,
+  type ReceiptDraft, type ReceiptFieldDraft, type ReceiptLines, type ReceiptPrinterSeed,
+} from './engine';
+import { ReceiptStage } from './ReceiptStage';
+import type { ReceiptStageProps } from './ReceiptStage.types';
+
+export type ReceiptPrinterOperations = {
+  /**
+   * Record, send or print the receipt for real — a POS, an email, a thermal printer. The paper
+   * feeds while it runs, and the receipt is `printed` once both are done. Default: succeeds.
+   */
+  print: OnboardingOperation<{ receipt: ReceiptValues; lines: ReceiptLines }>;
+};
+
+/** How wide the printer may grow: 260, 340 or 420 points. It shrinks with its container below that. */
+export type ReceiptPrinterSize = 'small' | 'medium' | 'large';
+const STAGE_WIDTH: Record<ReceiptPrinterSize, number> = { small: 260, medium: 340, large: 420 };
+
+export type ReceiptPrinterProps = {
+  preset?: OnboardingPreset;
+  config?: Partial<ReceiptPrinterSettings>;
+  density?: DensityName;
+  status?: PatternStatus;
+  result?: OnboardingResult;
+  operations?: ReceiptPrinterOperations;
+  reload?: OnboardingOperation<void>;
+  initial?: ReceiptPrinterSeed;
+  size?: ReceiptPrinterSize;
+  /**
+   * What draws the printer. Default: the Rive printer on the web and a still receipt on native. A
+   * React Native app that installs the Rive runtime passes `RiveReceiptStage` from
+   * `@comppack/ui/native/receipt-printer` (or uses `NativeReceiptPrinter`, which does) for the same animated printer.
+   */
+  stage?: ComponentType<ReceiptStageProps>;
+  /** The form as typed, on every change. */
+  onChange?: (draft: ReceiptDraft) => void;
+  /** The receipt is printed and at rest: the values it was printed from, and its lines. */
+  onPrinted?: (receipt: ReceiptValues, lines: ReceiptLines) => void;
+  onReset?: () => void;
+  /**
+   * The fields were redefined in the "Edit fields" mode — added, removed, renamed, re-keyed or a
+   * new heading. The list is config-shaped: save it as `config.fields` and the form comes back the same.
+   */
+  onFieldsChange?: (fields: ReceiptFieldDef[]) => void;
+  onScene?: (scene: string) => void;
+  testID?: string;
+};
+
+/**
+ * **Receipt Printer** — a payment form and a golden roll printer. Print checks the form; if it is
+ * complete the fields lock, the host's `print` operation runs, and the receipt feeds out of the
+ * printer with exactly what was typed on it. Printed, the receipt stays; Print again reprints the
+ * form as it now stands, and Reset puts the form and the printer back where they started.
+ *
+ * Reduced motion keeps the print and drops the feed: the receipt appears at rest. The printed
+ * receipt is also read out, since the printer itself is a picture.
+ */
+function ReceiptPrinterView(props: ReceiptPrinterProps) {
+  const config = resolveConfig(RECEIPT_PRINTER_PRESETS, props.preset, props.config);
+  const issues = validateReceiptPrinter(config);
+  if (issues.length) return <InvalidConfig title={config.title} issues={issues} testID={props.testID} />;
+  return <Valid {...props} config={config} />;
+}
+
+/** Each built-in field's label is a config key, so it can be renamed; these are the fallbacks for a blank one. */
+const LABEL_KEYS: Record<ReceiptField, keyof ReceiptPrinterSettings> = {
+  currency: 'currencyLabel', paymentMethod: 'paymentMethodLabel', date: 'dateLabel', message: 'messageLabel',
+};
+const FALLBACK: Record<string, string> = {
+  currencyLabel: 'Currency', paymentMethodLabel: 'Payment method', dateLabel: 'Date', messageLabel: 'Message', itemsLabel: 'Items',
+  itemNameLabel: 'Item', quantityLabel: 'Qty', amountLabel: 'Amount', optionalLabel: 'optional', addItemLabel: 'Add item',
+  removeItemLabel: 'Remove', editFieldsLabel: 'Edit fields', doneEditingLabel: 'Done', addFieldLabel: 'Add field',
+  removeFieldLabel: 'Remove field', fieldLabelLabel: 'Label', fieldKeyLabel: 'Key', headingLabel: 'Heading',
+};
+/** A field list as config — what `onFieldsChange` reports and `config.fields` takes back. */
+const asConfig = (fields: ReceiptFieldDraft[]): ReceiptFieldDef[] =>
+  fields.map(f => ({ key: f.key, label: f.label, value: f.value, ...(f.heading ? { heading: true } : {}) }));
+const labelOf = (c: ReceiptPrinterSettings, key: keyof ReceiptPrinterSettings) => {
+  const v = c[key];
+  return typeof v === 'string' && v.trim() ? v : FALLBACK[key as string] ?? '';
+};
+
+function Valid({
+  config, density, status = 'ready', result, operations, reload, initial, size = 'medium', stage: Stage = ReceiptStage, onChange, onPrinted, onReset, onFieldsChange, onScene, testID,
+}: Omit<ReceiptPrinterProps, 'config'> & { config: ReceiptPrinterSettings }) {
+  const { colors } = useDs();
+  const uid = useId();
+  const runner = useOperationRunner();
+  const reduceMotion = useReduceMotion();
+  const key = JSON.stringify([config, initial ?? null]);
+  const [state, send, ref] = useSeededReducer(
+    reduceReceiptPrinter,
+    () => initialReceiptPrinter(config, initial ?? (config.ship ? receiptPrinterSeed(config, config.ship) : {})),
+    key,
+    () => runner.cancel('print'),
+  );
+  const pattern = usePatternStatus(hasChoices(config) ? status : status === 'ready' ? 'empty' : status, reload);
+  const v = receiptPrinterView(config, state);
+  useSceneReport(pattern.status === 'ready' ? v.scene : pattern.status, onScene);
+  const print = useDefaultOperation(operations?.print, ONBOARDING_TIMING.print, () => result === 'error');
+
+  const runPrint = (job: number) => {
+    const s = ref.current;
+    if (!s.printed) return;
+    runOutcome(runner, 'print', print, { receipt: valuesOf(s.draft), lines: s.printed }, {
+      ok: () => send({ type: 'acknowledged', job }),
+      fail: message => send({ type: 'failed', job, message }),
+    });
+  };
+  /* A board that ships mid-print runs its operation, as a real print would. */
+  useEffect(() => { if (ref.current.run === 'printing') runPrint(ref.current.job); }, [key]);
+  /* Printed means both halves are done; say so once per print, with what was printed. A receipt that
+     was already printed when the board mounted (a restored session) is not announced again. */
+  const announced = useRef(state.run === 'printed' ? state.job : 0);
+  useEffect(() => {
+    if (state.run !== 'printed' || !state.printed || state.job === announced.current) return;
+    announced.current = state.job;
+    onPrinted?.(valuesOf(state.draft), state.printed);
+  }, [state.run, state.job]);
+
+  const submit = () => {
+    const before = ref.current;
+    const next = reduceReceiptPrinter(before, { type: 'print', config });
+    send({ type: 'print', config });
+    if (next.run === 'printing' && next.job !== before.job) { ref.current = next; runPrint(next.job); }
+  };
+  const reset = () => { runner.cancel('print'); send({ type: 'reset', config }); onReset?.(); };
+  const edit = (field: ReceiptField, value: string) => {
+    send({ type: 'field', field, value });
+    onChange?.({ ...ref.current.draft, [field]: value });
+  };
+  const [editingFields, setEditingFields] = useState(false);
+  /* The builder's edits: apply, then report the new structure (a value typed is not a structure change). */
+  const defineField = (a: Parameters<typeof reduceReceiptPrinter>[1]) => {
+    const next = reduceReceiptPrinter(ref.current, a);
+    send(a);
+    onChange?.(next.draft);
+    onFieldsChange?.(asConfig(next.draft.fields));
+  };
+  const editFieldValue = (index: number, value: string) => {
+    send({ type: 'fieldValue', index, value });
+    onChange?.(reduceReceiptPrinter(ref.current, { type: 'fieldValue', index, value }).draft);
+  };
+  const editItem = (index: number, field: ReceiptItemField, value: string) => {
+    send({ type: 'item', index, field, value });
+    onChange?.({ ...ref.current.draft, items: ref.current.draft.items.map((it, i) => (i === index ? { ...it, [field]: value } : it)) });
+  };
+  const addItem = () => { send({ type: 'addItem' }); onChange?.(reduceReceiptPrinter(ref.current, { type: 'addItem' }).draft); };
+  const removeItem = (index: number) => { send({ type: 'removeItem', index }); onChange?.(reduceReceiptPrinter(ref.current, { type: 'removeItem', index }).draft); };
+
+  const currencies = currenciesOf(config);
+  const methods = methodsOf(config);
+  const symbol = currencies.find(c => c.code === state.draft.currency)?.symbol;
+  const id = (f: ReceiptField) => `${uid}-${f}`;
+  const locked = v.busy;
+  const field = (f: ReceiptField, extra: { numeric?: boolean; prefix?: string; placeholder?: string } = {}) => (
+    <Input
+      nativeID={id(f)}
+      value={state.draft[f]}
+      onChangeText={t => edit(f, t)}
+      onSubmit={submit}
+      disabled={locked}
+      maxLength={f === 'message' ? RECEIPT_MAX_LENGTH.message + 8 : undefined}
+      numeric={extra.numeric}
+      prefix={extra.prefix}
+      placeholder={extra.placeholder}
+      error={Boolean(v.errors[f])}
+      aria-required={f !== 'message'}
+      aria-invalid={Boolean(v.errors[f])}
+      aria-labelledby={`${id(f)}-label`}
+      aria-describedby={v.errors[f] ? `${id(f)}-error` : undefined}
+    />
+  );
+  const cell = (f: ReceiptField, control: ReactNode, basis = 200) => (
+    <Box key={f} gap="s1" style={{ flexGrow: 1, flexBasis: basis, minWidth: 0 }}>
+      <FieldLabel nativeID={`${id(f)}-label`} hint={f === 'message' ? labelOf(config, 'optionalLabel') : undefined}>{labelOf(config, LABEL_KEYS[f])}</FieldLabel>
+      {control}
+      {v.errors[f] ? <Text nativeID={`${id(f)}-error`} variant="caption" style={{ fontSize: 12, color: colors.status.needsUser }}>{v.errors[f]!}</Text> : null}
+    </Box>
+  );
+
+  return (
+    <OnboardingCard
+      testID={testID}
+      header={config}
+      copy={config}
+      density={density}
+      status={pattern.status}
+      onRetry={pattern.retry}
+      onEmptyAction={pattern.retry}
+      chip={v.chip}
+      hint={v.hint}
+      secondary={v.canReset ? { label: config.resetLabel, onPress: reset } : undefined}
+      primary={{ label: v.primaryLabel, busy: v.busy, disabled: v.busy, onPress: submit }}>
+      <Box gap="s4">
+        <Box row wrap gap="s5" align="flex-start">
+          <Box role="group" aria-label={config.title} row wrap gap="s3" style={{ flexGrow: 1, flexBasis: 280, minWidth: 0 }}>
+            <FieldsEditor
+              uid={uid}
+              config={config}
+              fields={state.draft.fields}
+              errors={v.errors}
+              locked={locked}
+              editing={editingFields && !locked}
+              canAdd={v.canAddField}
+              onToggle={() => setEditingFields(e => !e)}
+              onValue={editFieldValue}
+              onDefine={defineField}
+              onSubmit={submit}
+            />
+            <ItemsEditor
+              uid={uid}
+              config={config}
+              items={state.draft.items}
+              errors={v.errors}
+              symbol={symbol}
+              locked={locked}
+              canAdd={v.canAddItem}
+              canRemove={v.canRemoveItem}
+              onEdit={editItem}
+              onAdd={addItem}
+              onRemove={removeItem}
+              onSubmit={submit}
+            />
+            {cell('currency', (
+              <Select
+                value={state.draft.currency || undefined}
+                onChange={c => edit('currency', c)}
+                options={currencies.map(c => ({ value: c.code, label: `${c.code} (${c.symbol})` }))}
+                disabled={locked}
+                error={Boolean(v.errors.currency)}
+                aria-labelledby={`${id('currency')}-label`}
+              />
+            ), 120)}
+            {cell('paymentMethod', (
+              <Select
+                value={state.draft.paymentMethod || undefined}
+                onChange={m => edit('paymentMethod', m)}
+                options={methods.map(m => ({ value: m.id, label: m.label }))}
+                disabled={locked}
+                error={Boolean(v.errors.paymentMethod)}
+                aria-labelledby={`${id('paymentMethod')}-label`}
+              />
+            ), 140)}
+            {cell('date', field('date', { placeholder: 'YYYY-MM-DD' }), 140)}
+            {cell('message', field('message'), 140)}
+          </Box>
+          <Box align="center" style={{ flexGrow: 1, flexBasis: 240, minWidth: 0 }}>
+            <Stage
+              testID={testID ? `${testID}-printer` : undefined}
+              lines={v.lines}
+              job={state.job}
+              phase={v.phase}
+              reduceMotion={reduceMotion}
+              onPrinted={job => send({ type: 'fed', job })}
+              label={v.phase === 'idle' ? 'Receipt printer, ready' : `Receipt printer, ${v.phase === 'printing' ? 'printing' : 'printed'} receipt`}
+              maxWidth={STAGE_WIDTH[size] ?? STAGE_WIDTH.medium}
+            />
+          </Box>
+        </Box>
+        {state.run === 'failed' ? <Callout alert title={config.failTitle}>{state.failMessage || config.failBody}</Callout> : null}
+        <Box role="status" aria-live="polite">
+          {state.run === 'printing' ? <Hidden>{config.printingHint}</Hidden> : null}
+          {state.run === 'printed' && state.printed ? <Hidden>{receiptSpeech(state.printed)}</Hidden> : null}
+        </Box>
+      </Box>
+    </OnboardingCard>
+  );
+}
+
+/**
+ * **The host's own fields.** Normally a labelled input each — the labels are the host's. "Edit
+ * fields" turns each into its definition instead: its label, its key (which follows the label until
+ * typed by hand), whether it is the receipt's heading, and Remove; and adds Add field. Done goes
+ * back to the values. Every change to a definition is reported through `onFieldsChange`.
+ */
+function FieldsEditor({
+  uid, config, fields, errors, locked, editing, canAdd, onToggle, onValue, onDefine, onSubmit,
+}: {
+  uid: string;
+  config: ReceiptPrinterSettings;
+  fields: ReceiptFieldDraft[];
+  errors: Record<string, string>;
+  locked: boolean;
+  editing: boolean;
+  canAdd: boolean;
+  onToggle: () => void;
+  onValue: (index: number, value: string) => void;
+  onDefine: (a: Parameters<typeof reduceReceiptPrinter>[1]) => void;
+  onSubmit: () => void;
+}) {
+  const { colors } = useDs();
+  const err = (i: number, part: 'label' | 'key' | 'value') => errors[`fields.${i}.${part}`];
+  const errorText = (id: string, text?: string) =>
+    text ? <Text nativeID={id} variant="caption" style={{ fontSize: 12, color: colors.status.needsUser }}>{text}</Text> : null;
+  return (
+    <Box gap="s3" style={{ flexGrow: 1, flexBasis: '100%', minWidth: 0 }}>
+      <Box row justify="flex-end">
+        <Button variant="secondary" size="xsmall" onPress={onToggle} disabled={locked} aria-pressed={editing}>
+          {editing ? labelOf(config, 'doneEditingLabel') : labelOf(config, 'editFieldsLabel')}
+        </Button>
+      </Box>
+      {editing ? (
+        <Box role="group" aria-label={labelOf(config, 'editFieldsLabel')} gap="s3">
+          {fields.map((f, i) => {
+            const name = f.label || `${labelOf(config, 'fieldLabelLabel')} ${i + 1}`;
+            const problems = [err(i, 'label'), err(i, 'key')].filter(Boolean).join(' ');
+            return (
+              <Box key={i} gap="s1" style={{ borderRadius: 10, backgroundColor: colors.surfaceSunken, padding: 10 }}>
+                <Box row gap="s2" align="center">
+                  <Box style={{ flexGrow: 1, flexBasis: 0, minWidth: 80 }}>
+                    <Input
+                      value={f.label}
+                      onChangeText={t => onDefine({ type: 'fieldDef', index: i, label: t })}
+                      placeholder={labelOf(config, 'fieldLabelLabel')}
+                      error={Boolean(err(i, 'label'))}
+                      aria-invalid={Boolean(err(i, 'label'))}
+                      aria-label={`${labelOf(config, 'fieldLabelLabel')} ${i + 1}`}
+                      aria-describedby={problems ? `${uid}-fielddef-${i}-error` : undefined}
+                    />
+                  </Box>
+                  <Box style={{ flexGrow: 1, flexBasis: 0, minWidth: 80 }}>
+                    <Input
+                      value={f.key}
+                      onChangeText={t => onDefine({ type: 'fieldDef', index: i, key: t.replace(/\s+/g, '') })}
+                      mono
+                      error={Boolean(err(i, 'key'))}
+                      aria-invalid={Boolean(err(i, 'key'))}
+                      aria-label={`${labelOf(config, 'fieldKeyLabel')} ${i + 1}`}
+                      aria-describedby={problems ? `${uid}-fielddef-${i}-error` : undefined}
+                    />
+                  </Box>
+                  <IconButton icon="close" label={`${labelOf(config, 'removeFieldLabel')} ${name}`} onPress={() => onDefine({ type: 'removeField', index: i })} />
+                </Box>
+                <Checkbox
+                  checked={f.heading}
+                  onChange={on => onDefine({ type: 'fieldDef', index: i, heading: on })}
+                  label={`${labelOf(config, 'headingLabel')} — ${name}`}
+                />
+                {errorText(`${uid}-fielddef-${i}-error`, problems)}
+              </Box>
+            );
+          })}
+          <Box row>
+            <Button variant="secondary" size="xsmall" onPress={() => onDefine({ type: 'addField' })} disabled={!canAdd}>{`+ ${labelOf(config, 'addFieldLabel')}`}</Button>
+          </Box>
+        </Box>
+      ) : (
+        <Box row wrap gap="s3">
+          {fields.map((f, i) => (
+            <Box key={i} gap="s1" style={{ flexGrow: 1, flexBasis: f.heading ? '100%' : 140, minWidth: 0 }}>
+              <FieldLabel nativeID={`${uid}-field-${i}-label`}>{f.label || `${labelOf(config, 'fieldLabelLabel')} ${i + 1}`}</FieldLabel>
+              <Input
+                nativeID={`${uid}-field-${i}`}
+                value={f.value}
+                onChangeText={t => onValue(i, t)}
+                onSubmit={onSubmit}
+                disabled={locked}
+                error={Boolean(err(i, 'value'))}
+                aria-required
+                aria-invalid={Boolean(err(i, 'value'))}
+                aria-labelledby={`${uid}-field-${i}-label`}
+                aria-describedby={err(i, 'value') || err(i, 'label') || err(i, 'key') ? `${uid}-field-${i}-error` : undefined}
+              />
+              {errorText(`${uid}-field-${i}-error`, [err(i, 'value'), err(i, 'label') || err(i, 'key') ? `${labelOf(config, 'editFieldsLabel')} to fix its label or key.` : ''].filter(Boolean).join(' ') || undefined)}
+            </Box>
+          ))}
+        </Box>
+      )}
+    </Box>
+  );
+}
+
+/**
+ * **The item lines** — one row per line (item, quantity, price of one) with Remove, and Add item
+ * under them, up to `RECEIPT_MAX_ITEMS`. The column labels are config keys like every other label;
+ * each input also carries its line number in its accessible name ("Item 2").
+ */
+function ItemsEditor({
+  uid, config, items, errors, symbol, locked, canAdd, canRemove, onEdit, onAdd, onRemove, onSubmit,
+}: {
+  uid: string;
+  config: ReceiptPrinterSettings;
+  items: ReceiptDraft['items'];
+  errors: Record<string, string>;
+  symbol?: string;
+  locked: boolean;
+  canAdd: boolean;
+  canRemove: boolean;
+  onEdit: (index: number, field: ReceiptItemField, value: string) => void;
+  onAdd: () => void;
+  onRemove: (index: number) => void;
+  onSubmit: () => void;
+}) {
+  const { colors } = useDs();
+  const [itemL, qtyL, amountL] = [labelOf(config, 'itemNameLabel'), labelOf(config, 'quantityLabel'), labelOf(config, 'amountLabel')];
+  const input = (i: number, f: ReceiptItemField, label: string, extra: { numeric?: boolean; prefix?: string; maxLength?: number } = {}) => {
+    const err = errors[`items.${i}.${f}`];
+    return (
+      <Input
+        nativeID={`${uid}-items-${i}-${f}`}
+        value={items[i]![f]}
+        onChangeText={t => onEdit(i, f, t)}
+        onSubmit={onSubmit}
+        disabled={locked}
+        numeric={extra.numeric}
+        prefix={extra.prefix}
+        maxLength={extra.maxLength}
+        error={Boolean(err)}
+        aria-required
+        aria-invalid={Boolean(err)}
+        aria-label={`${label} ${i + 1}`}
+        aria-describedby={err ? `${uid}-items-${i}-error` : undefined}
+      />
+    );
+  };
+  return (
+    <Box role="group" aria-label={labelOf(config, 'itemsLabel')} gap="s2" style={{ flexGrow: 1, flexBasis: '100%', minWidth: 0 }}>
+      <FieldLabel>{labelOf(config, 'itemsLabel')}</FieldLabel>
+      {/* Column headings, once, in the rows' own widths (the inputs are also named "Item 2", "Qty 2"…). */}
+      <Box row gap="s2" aria-hidden>
+        <Text variant="caption" color="textSecondary" style={{ fontSize: 11, flexGrow: 1, flexBasis: 0, minWidth: 0 }}>{itemL}</Text>
+        <Text variant="caption" color="textSecondary" style={{ fontSize: 11, width: 52 }}>{qtyL}</Text>
+        <Text variant="caption" color="textSecondary" style={{ fontSize: 11, width: 96 }}>{amountL}</Text>
+        {canRemove ? <Box style={{ width: 32 }} /> : null}
+      </Box>
+      {items.map((_, i) => {
+        const rowErrors = (['name', 'quantity', 'amount'] as const).map(f => errors[`items.${i}.${f}`]).filter(Boolean);
+        return (
+          <Box key={i} gap="s1">
+            {/* One line per item at every width: the name takes what is left. */}
+            <Box row gap="s2" align="center">
+              <Box style={{ flexGrow: 1, flexBasis: 0, minWidth: 64 }}>{input(i, 'name', itemL, { maxLength: RECEIPT_MAX_LENGTH.itemName! + 8 })}</Box>
+              <Box style={{ width: 52 }}>{input(i, 'quantity', qtyL, { numeric: true })}</Box>
+              <Box style={{ width: 96 }}>{input(i, 'amount', amountL, { numeric: true, prefix: symbol })}</Box>
+              {canRemove ? (
+                <IconButton icon="close" label={`${labelOf(config, 'removeItemLabel')} ${itemL} ${i + 1}`} onPress={() => onRemove(i)} disabled={locked} />
+              ) : null}
+            </Box>
+            {rowErrors.length ? <Text nativeID={`${uid}-items-${i}-error`} variant="caption" style={{ fontSize: 12, color: colors.status.needsUser }}>{rowErrors.join(' ')}</Text> : null}
+          </Box>
+        );
+      })}
+      {errors.items ? <Text variant="caption" style={{ fontSize: 12, color: colors.status.needsUser }}>{errors.items}</Text> : null}
+      <Box row>
+        <Button variant="secondary" size="xsmall" onPress={onAdd} disabled={!canAdd}>{`+ ${labelOf(config, 'addItemLabel')}`}</Button>
+      </Box>
+    </Box>
+  );
+}
+
+/** The printed receipt, as one sentence for a screen reader. */
+export function receiptSpeech(l: ReceiptLines): string {
+  const items = l.items.map(it => `${it.line}, ${it.amount}`).join('; ');
+  const details = l.details.map(d => `${d.label}: ${d.value}`).join(', ');
+  return `Receipt printed. ${l.title ? `${l.title}, ` : ''}${l.meta}. ${details ? `${details}. ` : ''}${items}. ${l.paymentLabel} ${l.paymentMethod}. ${l.totalLabel} ${l.total}.${l.message ? ` ${l.message}` : ''}`;
+}
+
+/** Receipt Printer, guarded: a wrong-kind config is refused by name and a render error is caught, never thrown to the page (`shared/guard`). */
+export const ReceiptPrinter = guarded(ReceiptPrinterView, RECEIPT_PRINTER_PRESETS, 'ReceiptPrinter');

package/src/components/onboarding/receipt-printer/ReceiptStage.tsx

@@ -0,0 +1,15 @@
+import { useEffect } from 'react';
+import { ReceiptPaper } from './ReceiptPaper';
+import type { ReceiptStageProps } from './ReceiptStage.types';
+
+export type { ReceiptStageProps };
+
+/**
+ * **The native half: the receipt as a still.** The Rive runtime this component animates with on
+ * the web (`@rive-app/react-canvas`) is a browser runtime, so it is never imported here — native
+ * apps resolve this file and bundle none of it. A print lands at rest at once.
+ */
+export function ReceiptStage({ lines, job, phase, onPrinted, label, maxWidth, testID }: ReceiptStageProps) {
+  useEffect(() => { if (phase === 'printing') onPrinted(job); }, [phase, job]);
+  return <ReceiptPaper lines={lines} phase={phase} maxWidth={maxWidth} label={label} testID={testID} />;
+}

package/src/components/onboarding/receipt-printer/ReceiptStage.types.ts

@@ -0,0 +1,39 @@
+import type { ReceiptLines, PrinterPhase } from './engine';
+
+/**
+ * **The printer and its paper — the one boundary between the component and how it is drawn.**
+ *
+ * The component hands over the lines to print and a phase, and hears back once the paper is at
+ * rest. It never learns how: the web half (`ReceiptStage.web.tsx`) feeds the receipt out of a Rive
+ * printer; the native half, and the web half whenever the Rive runtime cannot load, draw the same
+ * receipt as a still (`ReceiptPaper`). Nothing about Rive — artboards, view models, triggers —
+ * crosses this line.
+ */
+export type ReceiptStageProps = {
+  /** Printed lines while printing or printed; a live preview of the form while idle. */
+  lines: ReceiptLines;
+  /** Which print this is. A new job while `printing` feeds a new receipt. */
+  job: number;
+  phase: PrinterPhase;
+  /** Skip the feed: the paper appears at rest (`prefers-reduced-motion`). The print still happens. */
+  reduceMotion: boolean;
+  /** The paper for `job` is at rest. Called once per job, on every platform. */
+  onPrinted: (job: number) => void;
+  /** The printer's accessible name — the receipt itself is read from the view's live region. */
+  label: string;
+  /** The stage's widest, in points. It shrinks with its container below that, never squeezes. */
+  maxWidth: number;
+  testID?: string;
+};
+
+/**
+ * The Rive artboard's size: 400 wide; 560 tall with one item line and two field rows, 24 taller for
+ * each more line and 22 for each more field row (either way shorter for fewer). The file lengthens
+ * its own artboard (`lineCount`, `detailCount`), and the stage keeps the same aspect ratio at every
+ * width, so a long receipt makes a taller stage rather than a squeezed one.
+ */
+export const STAGE_WIDTH = 400;
+export const STAGE_ROW = 24;
+export const STAGE_FIELD_ROW = 22;
+export const stageAspect = (lines: number, fields: number) =>
+  STAGE_WIDTH / (560 + STAGE_ROW * (Math.max(1, lines) - 1) + STAGE_FIELD_ROW * (Math.max(0, fields) - 2));