@appinternalleads/ui 0.2.0

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

@@ -0,0 +1,171 @@
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { Alignment, Fit, Layout, useRive } from '@rive-app/react-canvas';
+import { Box } from '../../../core';
+import { HUE, blockRadii } from '../../../tokens';
+import type { ReceiptLines } from './engine';
+import { ReceiptPaper } from './ReceiptPaper';
+import { RECEIPT_PRINTER_RIV } from './riv';
+import { stageAspect, type ReceiptStageProps } from './ReceiptStage.types';
+
+export type { ReceiptStageProps };
+
+/**
+ * **The web half: a Rive printer that feeds the receipt out, line by line.**
+ *
+ * The Rive file (`rive/receipt-printer/receipt-printer.rml`) owns the artwork and the motion. This
+ * owns only the conversation with it, through the `Receipt` view model — never a shape:
+ *
+ * - the ten receipt strings are written before every print, so the paper carries what was typed —
+ *   but never onto a receipt that is on its way out: while a printed receipt tears off (before a
+ *   reprint or a reset) it keeps its own text, and the new lines land when the machine leaves it;
+ * - `print`, `reset` and `reveal` are triggers (`reveal` lands at rest with no feed — reduced motion,
+ *   or a receipt that was already printed when the stage mounted), and `reduceMotion` also turns a
+ *   reset's tear-off into a cut;
+ * - `status` is written by the file's own state machine (`idle` · `printing` · `printed` ·
+ *   `tearing`), and `printed` is how the stage knows the paper is at rest.
+ *
+ * If the runtime or the file cannot load (a blocked WASM download, say), the stage falls back to
+ * the still, `ReceiptPaper`, and a print still ends — the form never waits on a printer that is not
+ * there.
+ */
+
+const ARTBOARD = 'ReceiptPrinter';
+const MACHINE = 'ReceiptPrinterMachine';
+const LINE_KEYS = ['title', 'badge', 'total', 'meta', 'paymentMethod', 'message', 'paymentLabel', 'totalLabel'] as const;
+
+let bytes: Uint8Array | null = null;
+/** The `.riv`, decoded once per page; each stage gets its own copy of the buffer. */
+function rivBuffer(): ArrayBuffer {
+  if (!bytes) {
+    const bin = atob(RECEIPT_PRINTER_RIV);
+    bytes = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i);
+  }
+  return bytes.slice().buffer;
+}
+
+type Instance = {
+  string(path: string): { value: string } | null;
+  number(path: string): { value: number } | null;
+  list(path: string): { length: number; removeInstanceAt(i: number): void; addInstance(vmi: never): void; instanceAt(i: number): Instance | null } | null;
+};
+type ItemFactory = { viewModelByName(name: string): { instance(): unknown } | null };
+
+/** Make a view-model list hold exactly `rows` — rows are reused, added or removed only at the end. */
+function syncList(rive: ItemFactory, vm: Instance, path: string, model: string, rows: Record<string, string>[]) {
+  const list = vm.list(path);
+  if (!list) return;
+  while (list.length > rows.length) list.removeInstanceAt(list.length - 1);
+  const vmModel = rive.viewModelByName(model);
+  while (list.length < rows.length && vmModel) list.addInstance(vmModel.instance() as never);
+  rows.forEach((row, i) => {
+    const inst = list.instanceAt(i);
+    for (const [k, v] of Object.entries(row)) {
+      const p = inst?.string(k);
+      if (p && p.value !== v) p.value = v;
+    }
+  });
+}
+
+/**
+ * The lines onto the view model: the strings, the `details` list (the host's fields, one
+ * `ReceiptDetail` label/value row each) and the `items` list (one `ReceiptItem` per line), and the
+ * two counts that lengthen the paper, the artboard and the feed together. Returns what the file now
+ * holds, which the stage's height follows.
+ */
+function writeLines(rive: ItemFactory, vm: Instance, lines: ReceiptLines): { lines: number; fields: number } {
+  for (const k of LINE_KEYS) {
+    const p = vm.string(k);
+    if (p && p.value !== lines[k]) p.value = lines[k];
+  }
+  syncList(rive, vm, 'details', 'ReceiptDetail', lines.details);
+  syncList(rive, vm, 'items', 'ReceiptItem', lines.items);
+  const n = Math.max(1, lines.items.length);
+  const d = lines.details.length;
+  const lineCount = vm.number('lineCount');
+  const detailCount = vm.number('detailCount');
+  if (lineCount && lineCount.value !== n) lineCount.value = n;
+  if (detailCount && detailCount.value !== d) detailCount.value = d;
+  return { lines: n, fields: d };
+}
+
+export function ReceiptStage({ lines, job, phase, reduceMotion, onPrinted, label, maxWidth, testID }: ReceiptStageProps) {
+  const [failed, setFailed] = useState(false);
+  const params = useMemo(() => ({
+    buffer: rivBuffer(),
+    artboard: ARTBOARD,
+    stateMachine: MACHINE,
+    autoplay: true,
+    autoBind: true,
+    layout: new Layout({ fit: Fit.Contain, alignment: Alignment.Center }),
+    onLoadError: () => setFailed(true),
+  }), []);
+  const { rive, RiveComponent } = useRive(params);
+
+  /* The job whose feed this stage started; `null` while the printer is idle. */
+  const started = useRef<number | null>(null);
+  const printed = useRef(onPrinted);
+  printed.current = onPrinted;
+  const latest = useRef(lines);
+  latest.current = lines;
+  /* How many lines the file holds — the stage's height follows the paper, not the form. */
+  const [shown, setShown] = useState({ lines: Math.max(1, lines.items.length), fields: lines.details.length });
+
+  /* 1 · The lines, before anything is triggered — so a print never feeds the previous receipt, and a
+     printed receipt about to tear off (a reprint, or a reset, with motion) keeps its own text. */
+  useEffect(() => {
+    const vm = rive?.viewModelInstance;
+    if (!vm) return;
+    const b = vm.boolean('reduceMotion');
+    if (b && b.value !== reduceMotion) b.value = reduceMotion;
+    const status = vm.string('status')?.value;
+    const leaving = status === 'tearing'
+      || (status === 'printed' && !reduceMotion && (phase === 'idle' || started.current !== job));
+    if (!leaving) setShown(writeLines(rive, vm as unknown as Instance, lines));
+  }, [rive, lines, phase, job, reduceMotion]);
+
+  /* 2 · The phase, as triggers. Each job is started once; idle retracts whatever is out. */
+  useEffect(() => {
+    const vm = rive?.viewModelInstance;
+    if (!vm) return;
+    if (phase === 'idle') {
+      if (vm.string('status')?.value !== 'idle') vm.trigger('reset')?.trigger();
+      started.current = null;
+      return;
+    }
+    if (started.current === job) return;
+    started.current = job;
+    /* Printed already when this stage first sees it (a restored session): land at rest, no replay. */
+    const reveal = reduceMotion || phase === 'printed';
+    /* A reveal over a receipt already at rest changes nothing the file reports — `status` stays
+       `printed` — so the new lines, written in step 1, are this job's paper at rest now. */
+    if (reveal && vm.string('status')?.value === 'printed') { printed.current(job); return; }
+    vm.trigger(reveal ? 'reveal' : 'print')?.trigger();
+  }, [rive, phase, job, reduceMotion]);
+
+  /* 3 · The file says where the paper is: at rest (printed), or past a tear-off — a fresh feed or
+     an idle stub — which is when lines held back in step 1 go on. */
+  useEffect(() => {
+    const vm = rive?.viewModelInstance;
+    const status = vm?.string('status');
+    if (!vm || !status) return;
+    const heard = () => {
+      if (status.value === 'printing' || status.value === 'idle') setShown(writeLines(rive, vm as unknown as Instance, latest.current));
+      if (status.value === 'printed' && started.current !== null) printed.current(started.current);
+    };
+    status.on(heard);
+    return () => status.off(heard);
+  }, [rive]);
+
+  /* Without the runtime, the still — and a print completes at once, exactly as on native. */
+  useEffect(() => { if (failed && phase === 'printing') onPrinted(job); }, [failed, phase, job]);
+
+  if (failed) return <ReceiptPaper lines={lines} phase={phase} maxWidth={maxWidth} label={label} testID={testID} />;
+  return (
+    /* The warm ground shows while the runtime loads; the artboard paints over it. `data-rive` says
+       which — a screenshot (the visual gate) waits for `ready`. */
+    <Box testID={testID} role="img" aria-label={label} style={{ width: '100%', maxWidth, aspectRatio: stageAspect(shown.lines, shown.fields), borderRadius: blockRadii.mid, overflow: 'hidden', backgroundColor: HUE.butter.hs }}>
+      <RiveComponent aria-hidden="true" data-rive={rive ? 'ready' : 'loading'} style={{ width: '100%', height: '100%', display: 'block' }} />
+    </Box>
+  );
+}

package/src/components/onboarding/receipt-printer/contract.ts

@@ -0,0 +1,169 @@
+import type { HeaderConfig, LoadCopy, OnboardingIssue, PresetsFile } from '../shared/contract';
+import presetsJson from './presets.json';
+
+/**
+ * **Receipt Printer** — a payment form beside a golden roll printer. Print validates the form,
+ * hands the receipt to the host's `print` operation, and feeds it out of the printer line by line
+ * (Rive, `rive/receipt-printer/receipt-printer.rml`); the values typed are the values printed, and
+ * the paper is as long as the receipt — one line per item.
+ *
+ * The config is the form's starting values, the choices it offers, and every word it shows. The
+ * form's own fields are `fields` — a list the host defines: each has a `key` (what the value is
+ * reported as), a `label` (what the form and the receipt call it) and a starting `value`, and one
+ * may be the receipt's `heading`. A bookshop can drop "Business name" for "Book name: Harry
+ * Potter"; a person can do the same in the component's "Edit fields" mode, and an agent or a sheet
+ * by sending the list. `items` is a list too, so a receipt can have many lines. The receipt itself
+ * is never config: it is built from what the person typed (`engine.ts`).
+ */
+
+export const RECEIPT_PRINTER_SCENES = ['default', 'invalid', 'printing', 'printed', 'failed', 'loading', 'empty', 'error'] as const;
+export type ReceiptPrinterScene = (typeof RECEIPT_PRINTER_SCENES)[number];
+/** Scenes that are an operation in flight — see `sceneProps`. */
+export const RECEIPT_PRINTER_IN_FLIGHT: readonly string[] = ['printing'];
+
+/** A currency the form offers. `decimals` is its minor unit: 2 for ₹ and $, 0 for ¥. */
+export type ReceiptCurrency = { code: string; symbol: string; decimals: number };
+export type ReceiptPaymentMethod = { id: string; label: string };
+/** One line of the receipt: what, how many, and the price of one. */
+export type ReceiptItem = { name: string; quantity: number; amount: number };
+/**
+ * One of the host's own fields. `key` is how its value is reported (`onPrinted`'s `fields`) — a
+ * name like `bookName`; `label` is what the form and the receipt call it; `heading` prints it large
+ * at the top of the receipt, in place of a business name (the first one marked wins).
+ */
+export type ReceiptFieldDef = { key: string; label: string; value: string; heading?: boolean };
+
+/** The form's values — what a person types, and what the receipt is printed from. */
+export type ReceiptValues = {
+  /** The host's own fields, by key: `{ bookName: 'Harry Potter', reader: 'Oliver' }`. */
+  fields: Record<string, string>;
+  /** One or more lines, at most `RECEIPT_MAX_ITEMS`. */
+  items: ReceiptItem[];
+  /** A `currencies[].code`. */
+  currency: string;
+  /** A `paymentMethods[].id`. */
+  paymentMethod: string;
+  /** `YYYY-MM-DD`. */
+  date: string;
+  /** Printed at the foot of the receipt. Optional. */
+  message: string;
+};
+
+/** Every word the form shows, by field — rename any of them in the config. */
+export type ReceiptFormLabels = {
+  itemsLabel: string;
+  itemNameLabel: string;
+  quantityLabel: string;
+  amountLabel: string;
+  currencyLabel: string;
+  paymentMethodLabel: string;
+  dateLabel: string;
+  messageLabel: string;
+  optionalLabel: string;
+  addItemLabel: string;
+  removeItemLabel: string;
+  /** The field builder. */
+  editFieldsLabel: string;
+  doneEditingLabel: string;
+  addFieldLabel: string;
+  removeFieldLabel: string;
+  fieldLabelLabel: string;
+  fieldKeyLabel: string;
+  headingLabel: string;
+};
+
+/** Every word the receipt prints that is not typed — rename any of them in the config. */
+export type ReceiptPaperLabels = {
+  paymentLabel: string;
+  totalLabel: string;
+  /** After the payment method: "UPI (PAID)". */
+  paidLabel: string;
+};
+
+export type ReceiptPrinterSettings = HeaderConfig & LoadCopy & Omit<ReceiptValues, 'fields'> & ReceiptFormLabels & ReceiptPaperLabels & {
+  /** The form's own fields, in order. */
+  fields: ReceiptFieldDef[];
+  currencies: ReceiptCurrency[];
+  paymentMethods: ReceiptPaymentMethod[];
+  printLabel: string;
+  printingLabel: string;
+  againLabel: string;
+  resetLabel: string;
+  readyHint: string;
+  printingHint: string;
+  printedHint: string;
+  invalidHint: string;
+  printedChip: string;
+  failTitle: string;
+  failBody: string;
+  ship?: ReceiptPrinterScene;
+};
+
+export const RECEIPT_PRINTER_PRESETS = presetsJson as unknown as PresetsFile<ReceiptPrinterSettings>;
+
+/** The built-in single-value fields, in form order. The host's own fields and the items are lists. */
+export const RECEIPT_FIELDS = ['currency', 'paymentMethod', 'date', 'message'] as const;
+export type ReceiptField = (typeof RECEIPT_FIELDS)[number];
+export type ReceiptItemField = keyof ReceiptItem;
+
+/** The longest each may be — past that the receipt would ellipsize it. */
+export const RECEIPT_MAX_LENGTH = { heading: 28, fieldValue: 24, fieldLabel: 16, itemName: 22, message: 28 } as const;
+export const RECEIPT_MAX_QUANTITY = 99;
+export const RECEIPT_MAX_AMOUNT = 9_999_999;
+/** The most lines one receipt prints. A longer sheet is refused with a reason, never cut short. */
+export const RECEIPT_MAX_ITEMS = 30;
+/** The most fields the host may define. */
+export const RECEIPT_MAX_FIELDS = 12;
+/** A field key: a name an app or an agent can use — `bookName`, `order_id`. */
+export const FIELD_KEY = /^[A-Za-z][A-Za-z0-9_]{0,31}$/;
+
+const isText = (v: unknown) => typeof v === 'string' && v.trim() !== '';
+
+/**
+ * The config's own problems — never the form's (a blank business name is something a person fixes
+ * in the form, not a broken config). Empty lists are not problems either: no currencies or payment
+ * methods shows the empty scene, and no items starts the form with one blank line. A starting
+ * `currency` or `paymentMethod` the lists do not offer falls back to the first one.
+ */
+export function validateReceiptPrinter(c: ReceiptPrinterSettings): OnboardingIssue[] {
+  const issues: OnboardingIssue[] = [];
+  const currencies = Array.isArray(c?.currencies) ? c.currencies : [];
+  const methods = Array.isArray(c?.paymentMethods) ? c.paymentMethods : [];
+  const items = Array.isArray(c?.items) ? c.items : [];
+  const fields = Array.isArray(c?.fields) ? c.fields : [];
+  const codes = new Set<string>();
+  currencies.forEach((cur, i) => {
+    if (!isText(cur?.code)) issues.push({ path: `currencies[${i}].code`, message: 'Each currency needs a code, like INR.' });
+    else if (codes.has(cur.code)) issues.push({ path: `currencies[${i}].code`, message: `${cur.code} is listed twice.` });
+    else codes.add(cur.code);
+    if (!isText(cur?.symbol)) issues.push({ path: `currencies[${i}].symbol`, message: 'Each currency needs a symbol, like ₹.' });
+    const d = cur?.decimals;
+    if (typeof d !== 'number' || !Number.isInteger(d) || d < 0 || d > 3) issues.push({ path: `currencies[${i}].decimals`, message: 'Decimals must be a whole number from 0 to 3.' });
+  });
+  const ids = new Set<string>();
+  methods.forEach((m, i) => {
+    if (!isText(m?.id)) issues.push({ path: `paymentMethods[${i}].id`, message: 'Each payment method needs an id.' });
+    else if (ids.has(m.id)) issues.push({ path: `paymentMethods[${i}].id`, message: `${m.id} is listed twice.` });
+    else ids.add(m.id);
+    if (!isText(m?.label)) issues.push({ path: `paymentMethods[${i}].label`, message: 'Each payment method needs a label.' });
+  });
+  const keys = new Set<string>();
+  if (fields.length > RECEIPT_MAX_FIELDS) issues.push({ path: 'fields', message: `At most ${RECEIPT_MAX_FIELDS} fields — this has ${fields.length}.` });
+  else fields.forEach((f, i) => {
+    const key = f?.key;
+    if (typeof key !== 'string' || !FIELD_KEY.test(key)) issues.push({ path: `fields[${i}].key`, message: 'A key starts with a letter and uses only letters, digits and _, like bookName.' });
+    else if (keys.has(key)) issues.push({ path: `fields[${i}].key`, message: `${key} is used twice.` });
+    else keys.add(key);
+    if (!isText(f?.label)) issues.push({ path: `fields[${i}].label`, message: 'Each field needs a label.' });
+    if (f?.value !== undefined && typeof f.value !== 'string') issues.push({ path: `fields[${i}].value`, message: 'A value is text.' });
+  });
+  if (items.length > RECEIPT_MAX_ITEMS) issues.push({ path: 'items', message: `A receipt prints at most ${RECEIPT_MAX_ITEMS} lines — this has ${items.length}.` });
+  else items.forEach((it, i) => {
+    if (!isText(it?.name)) issues.push({ path: `items[${i}].name`, message: 'Each item needs a name.' });
+    const q = it?.quantity;
+    if (typeof q !== 'number' || !Number.isInteger(q) || q < 1 || q > RECEIPT_MAX_QUANTITY) issues.push({ path: `items[${i}].quantity`, message: `Quantity must be a whole number from 1 to ${RECEIPT_MAX_QUANTITY}.` });
+    const a = it?.amount;
+    if (typeof a !== 'number' || !Number.isFinite(a) || a < 0 || a > RECEIPT_MAX_AMOUNT) issues.push({ path: `items[${i}].amount`, message: 'Amount must be a number, zero or more.' });
+  });
+  return issues.slice(0, 12);
+}