@tallyui/pos 0.1.0 → 2.0.0

package/src/tax/tax-provider.tsx

@@ -5,23 +5,24 @@ import type { TaxContext } from './types';
 const TaxCtx = createContext<TaxContext | null>(null);
 
 export interface TaxProviderProps {
-  rates: Record<string, number>;
+  ratesPpm: Record<string, number>;
   pricesIncludeTax: boolean;
   children: ReactNode;
 }
 
-export function TaxProvider({ rates, pricesIncludeTax, children }: TaxProviderProps) {
+export function TaxProvider({ ratesPpm, pricesIncludeTax, 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');
+      }
+      return {
+        getTaxRatePpm: (taxClass) =>
+          (taxClass === undefined ? undefined : ratesPpm[taxClass]) ?? ratesPpm.default ?? 0,
+        pricesIncludeTax,
+      };
+    },
+    [ratesPpm, pricesIncludeTax],
   );
 
   return <TaxCtx.Provider value={value}>{children}</TaxCtx.Provider>;

package/src/tax/types.ts

@@ -1,15 +1,11 @@
-export interface TaxResult {
-  priceExclTax: number;
-  priceInclTax: number;
-  taxAmount: number;
-}
-
+/** 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;
   pricesIncludeTax: boolean;
 }

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 } };
+}

package/src/currency/currency-provider.test.tsx

@@ -1,36 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { renderHook } from '@testing-library/react';
-import type { ReactNode } from 'react';
-import { CurrencyProvider, useCurrencyFormatter } from './currency-provider';
-
-function wrapper(currency: string, locale?: string) {
-  return function Wrapper({ children }: { children: ReactNode }) {
-    return (
-      <CurrencyProvider currencyCode={currency} locale={locale}>
-        {children}
-      </CurrencyProvider>
-    );
-  };
-}
-
-describe('CurrencyProvider + useCurrencyFormatter', () => {
-  it('formats using provided currency and locale', () => {
-    const { result } = renderHook(() => useCurrencyFormatter(), {
-      wrapper: wrapper('USD', 'en-US'),
-    });
-    expect(result.current(10.5)).toBe('$10.50');
-  });
-
-  it('formats EUR with German locale', () => {
-    const { result } = renderHook(() => useCurrencyFormatter(), {
-      wrapper: wrapper('EUR', 'de-DE'),
-    });
-    expect(result.current(10.5).replace(/\s/g, ' ')).toBe('10,50 €');
-  });
-
-  it('throws when used outside provider', () => {
-    expect(() => {
-      renderHook(() => useCurrencyFormatter());
-    }).toThrow('useCurrencyFormatter() must be used within a <CurrencyProvider>');
-  });
-});

package/src/currency/format-currency.test.ts

@@ -1,36 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { formatCurrency } from './format-currency';
-
-describe('formatCurrency', () => {
-  it('formats USD with default locale', () => {
-    const result = formatCurrency(10.5, 'USD', 'en-US');
-    expect(result).toBe('$10.50');
-  });
-
-  it('formats EUR with German locale', () => {
-    const result = formatCurrency(10.5, 'EUR', 'de-DE');
-    expect(result.replace(/\s/g, ' ')).toBe('10,50 €');
-  });
-
-  it('formats JPY (zero decimals)', () => {
-    const result = formatCurrency(1000, 'JPY', 'ja-JP');
-    expect(result).toContain('1,000');
-  });
-
-  it('formats zero', () => {
-    const result = formatCurrency(0, 'USD', 'en-US');
-    expect(result).toBe('$0.00');
-  });
-
-  it('formats negative numbers', () => {
-    const result = formatCurrency(-5.99, 'USD', 'en-US');
-    expect(result).toContain('5.99');
-  });
-
-  it('memoizes formatter for same currency+locale pair', () => {
-    const a = formatCurrency(1, 'USD', 'en-US');
-    const b = formatCurrency(2, 'USD', 'en-US');
-    expect(a).toBe('$1.00');
-    expect(b).toBe('$2.00');
-  });
-});

package/src/currency/format-currency.ts

@@ -1,18 +0,0 @@
-const formatters = new Map<string, Intl.NumberFormat>();
-
-function getFormatter(currencyCode: string, locale?: string): Intl.NumberFormat {
-  const key = `${currencyCode}:${locale ?? 'default'}`;
-  let formatter = formatters.get(key);
-  if (!formatter) {
-    formatter = new Intl.NumberFormat(locale, {
-      style: 'currency',
-      currency: currencyCode,
-    });
-    formatters.set(key, formatter);
-  }
-  return formatter;
-}
-
-export function formatCurrency(amount: number, currencyCode: string, locale?: string): string {
-  return getFormatter(currencyCode, locale).format(amount);
-}

package/src/logging/logger.test.ts

@@ -1,154 +0,0 @@
-import { describe, it, expect, vi } from 'vitest';
-import { createLogger } from './logger';
-import type { LogSink, LogEntry } from './types';
-
-function createTestSink(overrides?: Partial<LogSink>): LogSink & { entries: LogEntry[] } {
-  const entries: LogEntry[] = [];
-  return {
-    id: 'test',
-    levels: ['debug', 'info', 'warn', 'error'],
-    write: (entry) => entries.push(entry),
-    entries,
-    ...overrides,
-  };
-}
-
-describe('createLogger', () => {
-  it('creates a logger with default root scope', () => {
-    const logger = createLogger();
-    expect(logger).toBeDefined();
-    expect(typeof logger.debug).toBe('function');
-    expect(typeof logger.info).toBe('function');
-    expect(typeof logger.warn).toBe('function');
-    expect(typeof logger.error).toBe('function');
-  });
-
-  it('writes log entries to registered sinks', () => {
-    const logger = createLogger();
-    const sink = createTestSink();
-    logger.addSink(sink);
-
-    logger.info('hello world');
-
-    expect(sink.entries).toHaveLength(1);
-    expect(sink.entries[0].level).toBe('info');
-    expect(sink.entries[0].message).toBe('hello world');
-    expect(sink.entries[0].scope).toBe('root');
-    expect(sink.entries[0].timestamp).toBeGreaterThan(0);
-  });
-
-  it('includes data in log entries', () => {
-    const logger = createLogger();
-    const sink = createTestSink();
-    logger.addSink(sink);
-
-    logger.error('failed', { code: 500 });
-
-    expect(sink.entries[0].data).toEqual({ code: 500 });
-  });
-
-  it('only writes to sinks that match the log level', () => {
-    const logger = createLogger();
-    const errorOnly = createTestSink({ id: 'errors', levels: ['error'] });
-    logger.addSink(errorOnly);
-
-    logger.debug('debug msg');
-    logger.info('info msg');
-    logger.warn('warn msg');
-    logger.error('error msg');
-
-    expect(errorOnly.entries).toHaveLength(1);
-    expect(errorOnly.entries[0].level).toBe('error');
-  });
-
-  it('removes sinks by id', () => {
-    const logger = createLogger();
-    const sink = createTestSink();
-    logger.addSink(sink);
-    logger.info('before');
-    logger.removeSink('test');
-    logger.info('after');
-
-    expect(sink.entries).toHaveLength(1);
-    expect(sink.entries[0].message).toBe('before');
-  });
-});
-
-describe('scoped loggers', () => {
-  it('creates a child logger with a scoped name', () => {
-    const logger = createLogger();
-    const sink = createTestSink();
-    logger.addSink(sink);
-
-    const child = logger.createScope('order-builder');
-    child.info('order created');
-
-    expect(sink.entries[0].scope).toBe('order-builder');
-  });
-
-  it('child loggers share sinks with parent', () => {
-    const logger = createLogger();
-    const sink = createTestSink();
-    logger.addSink(sink);
-
-    const child = logger.createScope('tax');
-    child.warn('rate missing');
-    logger.info('root message');
-
-    expect(sink.entries).toHaveLength(2);
-    expect(sink.entries[0].scope).toBe('tax');
-    expect(sink.entries[1].scope).toBe('root');
-  });
-
-  it('sinks can filter by scope', () => {
-    const logger = createLogger();
-    const taxOnly = createTestSink({ id: 'tax-sink', scopes: ['tax'] });
-    logger.addSink(taxOnly);
-
-    const taxLog = logger.createScope('tax');
-    const orderLog = logger.createScope('order');
-
-    taxLog.info('tax message');
-    orderLog.info('order message');
-
-    expect(taxOnly.entries).toHaveLength(1);
-    expect(taxOnly.entries[0].scope).toBe('tax');
-  });
-
-  it('sinks added to parent are visible to existing children', () => {
-    const logger = createLogger();
-    const child = logger.createScope('child');
-
-    const sink = createTestSink();
-    logger.addSink(sink);
-
-    child.info('after add');
-    expect(sink.entries).toHaveLength(1);
-  });
-
-  it('sinks removed from parent are removed from children', () => {
-    const logger = createLogger();
-    const sink = createTestSink();
-    logger.addSink(sink);
-
-    const child = logger.createScope('child');
-    child.info('before');
-    logger.removeSink('test');
-    child.info('after');
-
-    expect(sink.entries).toHaveLength(1);
-  });
-
-  it('nested scopes (grandchild) share sinks with root', () => {
-    const logger = createLogger();
-    const sink = createTestSink();
-    logger.addSink(sink);
-
-    const child = logger.createScope('parent');
-    const grandchild = child.createScope('grandchild');
-
-    grandchild.info('deep message');
-    expect(sink.entries).toHaveLength(1);
-    expect(sink.entries[0].scope).toBe('grandchild');
-  });
-});