@tallyui/pos 0.1.0 → 3.0.0-next.0

package/src/tax/exact.ts

@@ -0,0 +1,218 @@
+import type { TaxRounding } from '@tallyui/core';
+
+/** Micro-minor-units per minor unit. */
+export const MICROS_PER_MINOR = 1_000_000n;
+
+/** What an absent `TaxRounding` means (#287): the till's only rounding before #287a. */
+export const DEFAULT_TAX_ROUNDING = { granularity: 'per_order', mode: 'half_away_from_zero' } as const satisfies TaxRounding;
+
+/** Converts a plain decimal percentage with at most four fractional digits to safe integer ppm. */
+export function ratePpmFromPercent(percent: number | string): number {
+  const value = String(percent);
+  const match = /^(\d+)(?:\.(\d{1,4}))?$/.exec(value);
+  if (!match || match[0] !== value) {
+    throw new RangeError('Percent must be a plain decimal with at most four fractional digits');
+  }
+  const ratePpm = BigInt(match[1]) * 10000n + BigInt((match[2] ?? '').padEnd(4, '0'));
+  if (ratePpm > BigInt(Number.MAX_SAFE_INTEGER)) {
+    throw new RangeError('Rate must be a safe integer');
+  }
+  return Number(ratePpm);
+}
+
+/**
+ * Exact exclusive tax, or inclusive tax rounded half away from zero to a micro-minor-unit.
+ * Throws RangeError unless amount and rate are safe integers and rate is non-negative.
+ */
+export function taxMicros(amountMinor: number, ratePpm: number, pricesIncludeTax: boolean): bigint {
+  if (!Number.isSafeInteger(amountMinor) || !Number.isSafeInteger(ratePpm) || ratePpm < 0) {
+    throw new RangeError('Amount must be a safe integer and rate a non-negative safe integer');
+  }
+  const tax = BigInt(amountMinor) * BigInt(ratePpm);
+  if (!pricesIncludeTax) return tax;
+
+  const numerator = tax * MICROS_PER_MINOR;
+  const denominator = MICROS_PER_MINOR + BigInt(ratePpm);
+  const sign = numerator < 0n ? -1n : 1n;
+  return sign * ((sign * numerator + denominator / 2n) / denominator);
+}
+
+/** #287: `half_up` is Math.round's rule, Vendure's DefaultMoneyStrategy (default-money-strategy.js:19-21). */
+export type RoundingMode = 'half_away_from_zero' | 'half_up';
+
+/** `n / d` (d > 0) rounded to an integer in `mode`, exactly; the modes differ only on exact negative halves. */
+export function roundRatio(n: bigint, d: bigint, mode: RoundingMode = 'half_away_from_zero'): bigint {
+  if (mode === 'half_away_from_zero' && n < 0n) return -roundRatio(-n, d, mode);
+  const a = 2n * n + d, b = 2n * d; // floor(n / d + 1/2)
+  return a / b - (a < 0n && a % b !== 0n ? 1n : 0n);
+}
+
+/** Rounds micro-minor-units to integer minor units, half away from zero unless `mode` says otherwise. */
+export function roundMicrosToMinor(micros: bigint, mode?: RoundingMode): number {
+  const minor = roundRatio(micros, MICROS_PER_MINOR, mode);
+  if (minor < -BigInt(Number.MAX_SAFE_INTEGER) || minor > BigInt(Number.MAX_SAFE_INTEGER)) {
+    throw new RangeError('Rounded amount must be a safe integer');
+  }
+  return Number(minor);
+}
+
+export interface TaxLineInput {
+  unitPriceMinor: number; // integer, may be negative (returns)
+  quantity: number;       // integer >= 1
+  ratePpm: number;        // integer >= 0
+}
+
+export interface OrderTaxTotals {
+  subtotalMinor: number;  // excl. tax
+  taxMinor: number;       // rounded once
+  totalMinor: number;     // incl. tax
+  lineTaxMicros: bigint[]; // exact, one per input line, same order
+}
+
+/**
+ * Sums tax on each unit price × quantity and rounds once for the order.
+ * Exclusive: total = subtotal + tax. Inclusive: subtotal = total − tax.
+ * Empty orders return zeros and an empty lineTaxMicros.
+ * Throws RangeError for unsafe integer inputs or totals, negative rates, or quantity < 1.
+ */
+export function computeOrderTax(lines: TaxLineInput[], pricesIncludeTax: boolean): OrderTaxTotals {
+  let amountTotal = 0n;
+  let taxTotal = 0n;
+  const lineTaxMicros: bigint[] = [];
+
+  for (const line of lines) {
+    if (!Number.isSafeInteger(line.quantity) || line.quantity < 1) {
+      throw new RangeError('Quantity must be a safe integer >= 1');
+    }
+    let tax = taxMicros(line.unitPriceMinor, line.ratePpm, false) * BigInt(line.quantity);
+    const amount = BigInt(line.unitPriceMinor) * BigInt(line.quantity);
+    if (pricesIncludeTax) {
+      const numerator = tax * MICROS_PER_MINOR;
+      const denominator = MICROS_PER_MINOR + BigInt(line.ratePpm);
+      const sign = numerator < 0n ? -1n : 1n;
+      tax = sign * ((sign * numerator + denominator / 2n) / denominator);
+    }
+    amountTotal += amount;
+    taxTotal += tax;
+    lineTaxMicros.push(tax);
+  }
+
+  const taxMinor = taxTotal / MICROS_PER_MINOR
+    + BigInt(roundMicrosToMinor(taxTotal % MICROS_PER_MINOR));
+  const subtotalMinor = pricesIncludeTax ? amountTotal - taxMinor : amountTotal;
+  const totalMinor = pricesIncludeTax ? amountTotal : amountTotal + taxMinor;
+  for (const value of [subtotalMinor, taxMinor, totalMinor]) {
+    if (value < -BigInt(Number.MAX_SAFE_INTEGER) || value > BigInt(Number.MAX_SAFE_INTEGER)) {
+      throw new RangeError('Order totals must be safe integers');
+    }
+  }
+  return {
+    subtotalMinor: Number(subtotalMinor),
+    taxMinor: Number(taxMinor),
+    totalMinor: Number(totalMinor),
+    lineTaxMicros,
+  };
+}
+
+export interface RateTaxLine {
+  label: string;
+  code?: string;
+  ratePpm: number;
+  netMinor: number;
+  amountMinor: number;
+}
+
+type TaxedLine = { netMinor: number; discountMinor?: number; taxInclusive: boolean; taxLines: readonly { code?: string; ratePpm: number; taxMicros: string }[] };
+
+/**
+ * A `per_line_items` or `per_rate_group_items` store's figures (#287) as @vendure/core 3.7.3 computes them; undefined
+ * otherwise. `baseMinor` (the subtotal) is Σ each item's rounded net, `rates` the tax by `code`+`ratePpm`, summing to
+ * `taxMinor`; the total is their sum. Vendure's rounding is `half_up`. vendurepos scores the #38 set with this.
+ */
+export function roundedTaxByRate(lines: readonly TaxedLine[], rounding?: TaxRounding) {
+  if (rounding?.granularity !== 'per_line_items' && rounding?.granularity !== 'per_rate_group_items') return undefined;
+  // Known gap (#287): Vendure's inclusive per_rate_group_items total can differ from the shelf prices, which the display
+  // can't show until it has a rounding row (#310), so an order with any inclusive line keeps per_order's figures and rows.
+  if (rounding.granularity === 'per_rate_group_items' && lines.some((line) => line.taxInclusive)) return undefined;
+  const { granularity, mode } = rounding;
+  const rates = new Map<string, { code?: string; ratePpm: number; netMinor: bigint; amountMinor: bigint }>();
+  let baseMinor = 0n;
+  // vendurepos posts each line undiscounted (A) and its discountMinor as its own −D surcharge in the line's mode with
+  // the line's tax lines (vendurepos/app order-create.service.ts:654-663); a return line's negative D is its cap, not an item.
+  const items = lines.flatMap((line) => (line.discountMinor ?? 0) > 0
+    ? [{ ...line, netMinor: line.netMinor + line.discountMinor! }, { ...line, netMinor: -line.discountMinor! }] : [line]);
+  for (const line of items) {
+    const net = BigInt(line.netMinor);
+    const ratePpm = BigInt(line.taxLines.reduce((sum, tax) => sum + tax.ratePpm, 0));
+    // Each item's net is rounded first, at the sum of its rates (order-line.entity.js:121-122): an inclusive item's
+    // netPriceOf(gross) (:193-196, :249-251; surcharge.entity.js:33-38; tax-utils.js:16-17), an exclusive one's as it is.
+    const base = line.taxInclusive ? roundRatio(net * MICROS_PER_MINOR, MICROS_PER_MINOR + ratePpm, mode) : net;
+    // per_line_items: the item's tax is its rounded gross less that net (:201-204, :259-261; surcharge.entity.js:36-38;
+    // default-order-tax-calculation-strategy.js:22-29): round(net × r) exclusive, gross − net inclusive.
+    const lineTax = line.taxInclusive ? net - base : roundRatio(net * ratePpm, MICROS_PER_MINOR, mode);
+    let left = lineTax;
+    baseMinor += base;
+    line.taxLines.forEach((tax, index) => {
+      // Vendure's key is the rate's name and value (order-level-tax-calculation-strategy.js:103).
+      const key = JSON.stringify([tax.code ?? '', tax.ratePpm]);
+      const row = rates.get(key) ?? { code: tax.code, ratePpm: tax.ratePpm, netMinor: 0n, amountMinor: 0n };
+      // per_line_items, stacked rates: each rate's share of the item's tax, rounded (default-order-tax-calculation-strategy.js:51-66),
+      // the last rate taking the rest so the rows sum to the tax. per_rate_group_items: each rate takes the whole net, and
+      // a −D item joins its line's group (order-level-tax-calculation-strategy.js:88-91, :98-115).
+      const share = index === line.taxLines.length - 1 ? left : ratePpm === 0n ? 0n : roundRatio(lineTax * BigInt(tax.ratePpm), ratePpm, mode);
+      left -= share;
+      rates.set(key, { ...row, netMinor: row.netMinor + base, amountMinor: row.amountMinor + share });
+    });
+  }
+  const rows = [...rates.values()].map((row) => ({ ...row, netMinor: Number(row.netMinor), amountMinor: Number(
+    // per_rate_group_items: round(Σ net × r) once per group, and the order's tax is their sum (:35-49, :56).
+    granularity === 'per_rate_group_items' ? roundRatio(row.netMinor * BigInt(row.ratePpm), MICROS_PER_MINOR, mode) : row.amountMinor) }));
+  return { baseMinor: Number(baseMinor), taxMinor: rows.reduce((sum, row) => sum + row.amountMinor, 0), rates: rows };
+}
+
+/**
+ * Groups each line's stacked tax rates (ADR-040: each independently taxes the line's full
+ * tax-free base) by `code`+`ratePpm`, floors each group's exact tax to minor units, then
+ * distributes `orderTaxMinor` minus that floor sum by largest remainder (ties to the higher rate)
+ * so the rates sum to exactly `orderTaxMinor`. A line's `netMinor` is in its OWN tax mode
+ * (`taxInclusive`): an inclusive line's net already contains its tax, so its tax-free base is
+ * `netMinor − roundMicrosToMinor(Σ its taxMicros)`; an exclusive line's base is `netMinor` as is.
+ * Shared by a receipt's tax summary and a Z report's per-rate breakdown. That is `per_order`'s split; a `per_line_items` or
+ * `per_rate_group_items` order's rows are `roundedTaxByRate`'s (#287).
+ */
+export function taxLinesByRate(
+  lines: readonly TaxedLine[],
+  orderTaxMinor: number,
+  taxLabels?: Record<number, string>,
+  rounding?: TaxRounding,
+): RateTaxLine[] {
+  const label = (ratePpm: number) => taxLabels?.[ratePpm] ?? `Tax ${ratePpm / 10000}%`;
+  const rounded = roundedTaxByRate(lines, rounding);
+  if (rounded) return rounded.rates.map(({ code, ratePpm, netMinor, amountMinor }) => ({ label: label(ratePpm), code, ratePpm, netMinor, amountMinor }));
+  const byRate = new Map<string, { code?: string; ratePpm: number; micros: bigint; netMinor: number }>();
+  for (const line of lines) {
+    const lineTaxMicros = line.taxLines.reduce((sum, tax) => sum + BigInt(tax.taxMicros), 0n);
+    const base = line.taxInclusive ? line.netMinor - roundMicrosToMinor(lineTaxMicros) : line.netMinor;
+    for (const tax of line.taxLines) {
+      const key = JSON.stringify([tax.code ?? '', tax.ratePpm]);
+      const existing = byRate.get(key);
+      byRate.set(key, {
+        code: tax.code, ratePpm: tax.ratePpm,
+        micros: (existing?.micros ?? 0n) + BigInt(tax.taxMicros),
+        netMinor: (existing?.netMinor ?? 0) + base,
+      });
+    }
+  }
+  const groups = Array.from(byRate.values()).map(({ code, ratePpm, micros, netMinor }) => {
+    const floor = micros / MICROS_PER_MINOR - (micros < 0n && micros % MICROS_PER_MINOR !== 0n ? 1n : 0n);
+    return {
+      line: { label: label(ratePpm), code, ratePpm, netMinor, amountMinor: Number(floor) },
+      remainder: micros - floor * MICROS_PER_MINOR,
+    };
+  });
+  const leftover = orderTaxMinor - groups.reduce((sum, group) => sum + group.line.amountMinor, 0);
+  const ranked = [...groups].sort((a, b) =>
+    a.remainder === b.remainder ? b.line.ratePpm - a.line.ratePpm : a.remainder > b.remainder ? -1 : 1);
+  for (const group of ranked.slice(0, leftover)) group.line.amountMinor += 1;
+  return groups.map((group) => group.line);
+}

package/src/tax/index.ts

@@ -1,4 +1,5 @@
-export { calculateTax, extractTax, addTax } from './calculate';
-export { TaxProvider, useTax } from './tax-provider';
+export { MICROS_PER_MINOR, ratePpmFromPercent, taxMicros, roundMicrosToMinor, computeOrderTax, taxLinesByRate } from './exact';
+export type { TaxLineInput, OrderTaxTotals, RateTaxLine } from './exact';
+export { TaxProvider, useTax, taxLogger } from './tax-provider';
 export type { TaxProviderProps } from './tax-provider';
-export type { TaxResult, TaxRateMap, TaxContext } from './types';
+export type { TaxRateMap, TaxContext } from './types';

package/src/tax/tax-provider.tsx

@@ -1,27 +1,50 @@
 import { createContext, useContext, useMemo } from 'react';
 import type { ReactNode } from 'react';
+import type { TaxRounding } from '@tallyui/core';
 import type { TaxContext } from './types';
+import { createLogger } from '../logging';
+
+export const taxLogger = createLogger('tax');
 
 const TaxCtx = createContext<TaxContext | null>(null);
 
 export interface TaxProviderProps {
-  rates: Record<string, number>;
+  ratesPpm: Record<string, number>;
   pricesIncludeTax: boolean;
+  /** `ServerCapabilities.taxRounding` (#287); a change restarts an idle sale under it. */
+  rounding?: TaxRounding;
+  /** Tax class → the backend's rate name, for `per_rate_group_items`'s grouping (#287). */
+  rateCodes?: Record<string, string>;
   children: ReactNode;
 }
 
-export function TaxProvider({ rates, pricesIncludeTax, children }: TaxProviderProps) {
+export function TaxProvider({ ratesPpm, pricesIncludeTax, rounding, rateCodes, children }: TaxProviderProps) {
   const value = useMemo<TaxContext>(
-    () => ({
-      getTaxRate(taxClass?: string) {
-        if (taxClass && taxClass in rates) {
-          return rates[taxClass];
-        }
-        return rates.default ?? 0;
-      },
-      pricesIncludeTax,
-    }),
-    [rates, pricesIncludeTax],
+    () => {
+      if (Object.values(ratesPpm).some((rate) => !Number.isSafeInteger(rate) || rate < 0)) {
+        throw new RangeError('TaxProvider: rates must be integer ppm');
+      }
+      const unknown = new Set<string>();
+      return {
+        getTaxRatePpm: (taxClass) => {
+          if (taxClass !== undefined && Object.hasOwn(ratesPpm, taxClass)) return ratesPpm[taxClass];
+          // A class the store's rates don't key is taxed at the default rate; warn once per class and rate map.
+          if (taxClass !== undefined && !unknown.has(taxClass)) {
+            unknown.add(taxClass);
+            taxLogger.warn('No tax rate for this tax class; using the default rate', { taxClass });
+          }
+          return ratesPpm.default ?? 0;
+        },
+        // The name of the rate getTaxRatePpm picks: the class's own, else the default's.
+        getTaxRateCode: (taxClass) => {
+          const key = taxClass !== undefined && Object.hasOwn(ratesPpm, taxClass) ? taxClass : 'default';
+          return rateCodes && Object.hasOwn(rateCodes, key) ? rateCodes[key] : undefined;
+        },
+        pricesIncludeTax,
+        ...(rounding ? { rounding } : {}),
+      };
+    },
+    [ratesPpm, pricesIncludeTax, rounding, rateCodes],
   );
 
   return <TaxCtx.Provider value={value}>{children}</TaxCtx.Provider>;

package/src/tax/types.ts

@@ -1,15 +1,17 @@
-export interface TaxResult {
-  priceExclTax: number;
-  priceInclTax: number;
-  taxAmount: number;
-}
+import type { TaxRounding } from '@tallyui/core';
 
+/** Tax rates as integer parts per million (19% = 190000). */
 export type TaxRateMap = {
   default: number;
   [taxClass: string]: number;
 };
 
 export interface TaxContext {
-  getTaxRate(taxClass?: string): number;
+  /** Tax rate for a tax class as integer parts per million (19% = 190000); the default class when omitted or unknown. */
+  getTaxRatePpm(taxClass?: string): number;
+  /** The backend's name for that class's rate, when mapped: a `per_rate_group_items` store groups by name and value (#287). */
+  getTaxRateCode?(taxClass?: string): string | undefined;
   pricesIncludeTax: boolean;
+  /** The store's tax rounding strategy (#287); absent means `per_order`, half away from zero. */
+  rounding?: TaxRounding;
 }

package/src/tender/index.ts

@@ -0,0 +1,2 @@
+export { tenderReducer, initTenderState, initialTenderState, appliedMinor, changeMinor, quickTenderedAmounts, evenSplitShareMinor, activePlan, planLegs, MAX_TENDER_MINOR } from './tender-state';
+export type { PaymentTransport, TenderView, TenderLineId, TenderPlan, SplitTab, TenderState, TenderKey, TenderAction, PlanLeg } from './tender-state';

package/src/tender/tender-state.ts

@@ -0,0 +1,326 @@
+/** The transport a payment terminal is reached over: hardware-neutral, not tied to any backend. */
+export type PaymentTransport = 'bluetooth' | 'usb' | 'network' | 'tap_to_pay';
+
+export type TenderView = 'select' | 'amount' | 'cancel';
+export type TenderLineId = string | number;
+
+export type TenderPlan =
+  | { kind: 'even'; ways: number; from: number }
+  | { kind: 'fixed'; firstMinor: number; title: string | null; from: number }
+  | { kind: 'items'; lineIds: TenderLineId[]; firstMinor: number; ways: number; from: number };
+export type SplitTab = 'even' | 'amount' | 'percent' | 'item';
+
+export interface TenderState {
+  view: TenderView;
+  /** Method id being tendered; null in the 'select' and 'cancel' views. */
+  methodId: string | null;
+  readerId: string | null;
+  transport: PaymentTransport | null;
+  /** Keypad entry in minor units. */
+  entryMinor: number;
+  /** False until the cashier has touched the keypad since the entry was pre-filled. */
+  entryDirty: boolean;
+  plan: TenderPlan | null;
+  splitView: boolean;
+  splitTab: SplitTab;
+  pickedLineIds: TenderLineId[];
+  linesPaidBy: Record<TenderLineId, string[]>;
+}
+
+/** '0'..'9' plus the two edit keys. There is deliberately no decimal key: digits shift in from the right. */
+export type TenderKey =
+  '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | 'clear' | 'backspace';
+
+export type TenderAction =
+  | {
+      type: 'pick-method';
+      methodId: string;
+      prefillMinor: number;
+      readerId: string | null;
+      transport?: PaymentTransport | null;
+    }
+  | { type: 'pick-transport'; transport: PaymentTransport }
+  | { type: 'pick-reader'; readerId: string | null }
+  | { type: 'tender-started' }
+  | { type: 'key'; key: TenderKey }
+  | { type: 'set-entry'; minor: number }
+  | { type: 'back' }
+  | {
+      type: 'tender-recorded';
+      rowsSinceFrom: { title: string; amountMinor: number }[];
+      /** The order's balance once this row counts, so the next leg can be pre-typed. */
+      balanceMinor: number;
+    }
+  | { type: 'open-split' }
+  | { type: 'close-split' }
+  | { type: 'set-split-tab'; tab: SplitTab }
+  | { type: 'toggle-split-line'; lineId: TenderLineId }
+  | { type: 'set-plan'; plan: TenderPlan; balanceMinor: number }
+  | { type: 'clear-plan'; balanceMinor: number }
+  | { type: 'arm-custom' }
+  | { type: 'request-cancel' }
+  | { type: 'reset' };
+/** $9,999,999.99 at two decimals — a till will never legitimately take more, and it stops a stuck key running the display off the screen. */
+export const MAX_TENDER_MINOR = 999999999;
+export const initialTenderState: TenderState = {
+  view: 'select',
+  methodId: null,
+  readerId: null,
+  transport: null,
+  entryMinor: 0,
+  entryDirty: false,
+  plan: null,
+  splitView: false,
+  splitTab: 'even',
+  pickedLineIds: [],
+  linesPaidBy: {},
+};
+
+/**
+ * Reducer init. An order whose method the checkout store already holds — a URL seed, or a
+ * tab the cashier is coming back to — reopens its keypad prefilled with the balance, exactly
+ * as a tap on that tile would. Everything else starts from scratch.
+ */
+export function initTenderState({
+  methodId,
+  balanceMinor,
+}: {
+  methodId: string | null;
+  balanceMinor: number;
+}): TenderState {
+  if (!methodId) return initialTenderState;
+  return { ...initialTenderState, view: 'amount', methodId, entryMinor: balanceMinor };
+}
+
+export function tenderReducer(state: TenderState, action: TenderAction): TenderState {
+  switch (action.type) {
+    case 'pick-method':
+      return {
+        ...state,
+        view: 'amount',
+        methodId: action.methodId,
+        readerId: action.readerId,
+        transport: action.transport ?? null,
+        entryMinor: state.entryDirty ? state.entryMinor : action.prefillMinor,
+        entryDirty: state.entryDirty,
+      };
+    case 'pick-transport':
+      return { ...state, transport: action.transport };
+    case 'pick-reader':
+      return { ...state, readerId: action.readerId };
+    case 'key': {
+      if (state.view !== 'amount') {
+        return state;
+      }
+      if (action.key === 'backspace') {
+        return { ...state, entryMinor: Math.floor(state.entryMinor / 10), entryDirty: true };
+      }
+      if (action.key === 'clear') {
+        return { ...state, entryMinor: 0, entryDirty: true };
+      }
+      const digit = Number(action.key);
+      if (!state.entryDirty) {
+        return { ...state, entryMinor: digit, entryDirty: true };
+      }
+      const entryMinor = state.entryMinor * 10 + digit;
+      return entryMinor > MAX_TENDER_MINOR ? state : { ...state, entryMinor };
+    }
+    case 'set-entry':
+      return {
+        ...state,
+        entryMinor: Math.max(0, Math.min(action.minor, MAX_TENDER_MINOR)),
+        entryDirty: true,
+      };
+    case 'tender-started':
+      // A leg is being recorded: the method stays chosen for the next one; the entry
+      // clears until `tender-recorded` pre-types the next planned leg.
+      return { ...state, entryMinor: 0, entryDirty: false, splitView: false };
+    case 'back':
+      return {
+        ...state,
+        view: 'select',
+        methodId: null,
+        readerId: null,
+        transport: null,
+        entryMinor: 0,
+        entryDirty: false,
+      };
+    case 'tender-recorded': {
+      const linesPaidBy = { ...state.linesPaidBy };
+      if (
+        state.plan?.kind === 'items' &&
+        action.rowsSinceFrom.reduce((sum, row) => sum + row.amountMinor, 0) >= state.plan.firstMinor
+      ) {
+        for (const id of state.plan.lineIds) {
+          // Preserve the group's original methods when subsequently taking the rest.
+          linesPaidBy[id] ??= [...new Set(action.rowsSinceFrom.map((row) => row.title))];
+        }
+      }
+      // The method stays chosen for the next leg (the selector is always on screen now);
+      // the entry pre-types the next planned leg, or the balance when no plan is left.
+      const rows = action.rowsSinceFrom.map((row) => ({
+        minor: row.amountMinor,
+        title: row.title,
+      }));
+      const plan = activePlan(state.plan, rows.length, action.balanceMinor);
+      const entryMinor = plan
+        ? planLegs(plan, rows, action.balanceMinor).thisPaymentMinor
+        : action.balanceMinor;
+      return {
+        ...state,
+        view: state.methodId ? 'amount' : 'select',
+        entryMinor,
+        entryDirty: false,
+        splitView: false,
+        pickedLineIds: [],
+        linesPaidBy,
+      };
+    }
+    case 'open-split':
+      return {
+        ...state,
+        splitView: true,
+        pickedLineIds:
+          state.plan?.kind === 'items'
+            ? state.plan.lineIds.filter((id) => !state.linesPaidBy[id])
+            : state.pickedLineIds,
+      };
+    case 'close-split':
+      return { ...state, splitView: false };
+    case 'set-split-tab':
+      return { ...state, splitTab: action.tab };
+    case 'toggle-split-line':
+      if (state.linesPaidBy[action.lineId]) return state;
+      return {
+        ...state,
+        pickedLineIds: state.pickedLineIds.includes(action.lineId)
+          ? state.pickedLineIds.filter((id) => id !== action.lineId)
+          : [...state.pickedLineIds, action.lineId],
+      };
+    case 'set-plan':
+      return {
+        ...state,
+        plan: action.plan,
+        splitView: false,
+        pickedLineIds: [],
+        entryMinor:
+          state.view === 'amount'
+            ? planLegs(action.plan, [], action.balanceMinor).thisPaymentMinor
+            : state.entryMinor,
+        entryDirty: state.view !== 'amount' && state.entryDirty,
+      };
+    case 'clear-plan':
+    case 'arm-custom':
+      return {
+        ...state,
+        plan: null,
+        splitView: false,
+        view: action.type === 'arm-custom' ? 'amount' : state.view,
+        entryMinor: action.type === 'clear-plan' ? action.balanceMinor : 0,
+        entryDirty: false,
+      };
+    case 'request-cancel':
+      return { ...state, view: 'cancel', splitView: false };
+    case 'reset':
+      return initialTenderState;
+  }
+}
+/**
+ * What the leg applies to the order. Cash may be tendered above the balance;
+ * the excess is change, never an overpayment on the order.
+ */
+export function appliedMinor(entryMinor: number, balanceMinor: number): number {
+  return Math.max(0, Math.min(entryMinor, balanceMinor));
+}
+/** Change handed back. Zero for any tender whose method cannot give change. */
+export function changeMinor(
+  entryMinor: number,
+  appliedAmountMinor: number,
+  givesChange: boolean,
+): number {
+  return givesChange ? Math.max(0, entryMinor - appliedAmountMinor) : 0;
+}
+/**
+ * Quick tendered amounts under a cash keypad: the balance itself, then the next
+ * whole 5, 10 and 50 above it. Deduped, ascending, never below the balance.
+ * The caller supplies those major-unit steps already scaled to minor units.
+ */
+export function quickTenderedAmounts(
+  balanceMinor: number,
+  stepsMinor: readonly number[],
+): number[] {
+  if (balanceMinor === 0) {
+    return [];
+  }
+
+  const amounts = new Set<number>([balanceMinor]);
+  for (const stepMinor of stepsMinor) {
+    if (stepMinor <= 0) continue;
+    const remainder = balanceMinor % stepMinor;
+    amounts.add(remainder === 0 ? balanceMinor : balanceMinor + stepMinor - remainder);
+  }
+  return [...amounts].sort((left, right) => left - right);
+}
+/**
+ * Even split shares. Returns the next tender's share, rounded half-up to the
+ * minor unit; the last leg remains whatever balance is left.
+ */
+export function evenSplitShareMinor(balanceMinor: number, ways: number): number {
+  if (ways < 2) {
+    return balanceMinor;
+  }
+  const wholeShare = Math.floor(balanceMinor / ways);
+  const remainder = balanceMinor % ways;
+  return wholeShare + (remainder * 2 >= ways ? 1 : 0);
+}
+
+/** Completion is derived from payment rows, never an extra counter in the reducer. */
+export function activePlan(
+  plan: TenderPlan | null,
+  taken: number,
+  balanceMinor: number,
+): TenderPlan | null {
+  if (!plan || balanceMinor === 0) return null;
+  if (plan.kind !== 'items' && taken >= (plan.kind === 'even' ? plan.ways : 2)) return null;
+  return plan;
+}
+
+export interface PlanLeg {
+  minor: number;
+  state: 'done' | 'now' | 'todo' | 'rest';
+  title?: string;
+}
+
+/** Label pieces stay untranslated here; the flow supplies localized copy and item names. */
+export function planLegs(
+  plan: TenderPlan,
+  rowsSinceFrom: { minor: number; title: string }[],
+  balanceMinor: number,
+) {
+  const taken = rowsSinceFrom.length;
+  const legs: PlanLeg[] = rowsSinceFrom.map((row) => ({ ...row, state: 'done' }));
+  const groupPaid = rowsSinceFrom.reduce((sum, row) => sum + row.minor, 0);
+  const groupLeft =
+    plan.kind === 'items'
+      ? Math.min(balanceMinor, Math.max(0, plan.firstMinor - groupPaid))
+      : balanceMinor;
+  const rest = plan.kind === 'items' && groupLeft === 0;
+  const ways = plan.kind === 'fixed' ? 2 : Math.max(plan.ways, taken + 1);
+  const left = plan.kind === 'fixed' || rest ? 1 : Math.max(1, ways - taken);
+  const amount = rest ? balanceMinor : groupLeft;
+  const each =
+    plan.kind === 'fixed' && taken === 0
+      ? Math.min(plan.firstMinor, balanceMinor)
+      : evenSplitShareMinor(amount, left);
+  let remaining = amount;
+  for (let i = 0; i < left; i++) {
+    const minor = Math.min(remaining, i === left - 1 && plan.kind !== 'fixed' ? remaining : each);
+    legs.push({ minor, state: i === 0 ? 'now' : 'todo' });
+    remaining -= minor;
+  }
+  if (plan.kind === 'fixed' && remaining > 0) legs.push({ minor: remaining, state: 'todo' });
+  if (plan.kind === 'items' && !rest && balanceMinor > groupLeft)
+    legs.push({ minor: balanceMinor - groupLeft, state: 'rest' });
+  const title = plan.kind === 'fixed' && taken === 0 ? plan.title : null;
+  return { legs, thisPaymentMinor: each, label: { n: taken + 1, ways, rest, title } };
+}