@tallyui/components 2.0.0 → 3.0.0-next.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tallyui/components",
-  "version": "2.0.0",
+  "version": "3.0.0-next.0",
   "type": "module",
   "description": "Universal POS UI components for Tally UI",
   "main": "./dist/index.js",
@@ -27,26 +27,26 @@
     "directory": "packages/components"
   },
   "peerDependencies": {
-    "@tallyui/core": "2.0.0",
-    "@tallyui/primitives": "2.0.0",
-    "@tallyui/theme": "2.0.0",
+    "@tallyui/core": "^3.0.0-next.0",
+    "@tallyui/primitives": "^3.0.0-next.0",
+    "@tallyui/theme": "^3.0.0-next.0",
     "react": ">=18",
     "react-native": ">=0.74",
     "react-native-svg": ">=15"
   },
   "dependencies": {
     "class-variance-authority": "^0.7.1",
-    "@tallyui/pos": "2.0.0"
+    "@tallyui/pos": "3.0.0-next.0"
   },
   "devDependencies": {
-    "@tallyui/connector-medusa": "2.0.0",
-    "@tallyui/connector-vendure": "2.0.0",
-    "@tallyui/connector-woocommerce": "2.0.0",
-    "@tallyui/mock-api": "2.0.0",
+    "@tallyui/connector-medusa": "3.0.0-next.0",
+    "@tallyui/connector-vendure": "3.0.0-next.0",
+    "@tallyui/connector-woocommerce": "3.0.0-next.0",
+    "@tallyui/mock-api": "3.0.0-next.0",
     "@types/react": ">=18",
     "react": "^19.2.4",
     "react-native-svg": "15.12.1",
-    "rxdb": "16.21.1",
+    "rxdb": "17.5.0",
     "rxjs": "7.8.2"
   },
   "scripts": {

package/src/customer/customer-card.tsx

@@ -1,15 +1,20 @@
-import { useCustomerTraits } from '@tallyui/core';
+import { useCustomerTraits, type CustomerTraits } from '@tallyui/core';
 import { cn } from '@tallyui/theme';
 import { Text, VStack, type VStackProps } from '../ui';
 
-export interface CustomerCardProps extends Omit<VStackProps, 'children'> {
-  doc: any;
+export interface CustomerCardProps<Doc = any> extends Omit<VStackProps, 'children'> {
+  doc: Doc;
+  traits?: CustomerTraits<Doc>;
   className?: string;
 }
 
-export function CustomerCard({ doc, className, ...props }: CustomerCardProps) {
+function CustomerCardFromContext<Doc>(props: CustomerCardProps<Doc>) {
   const traits = useCustomerTraits();
-  if (!traits) return null;
+  return traits ? <CustomerCard {...props} traits={traits} /> : null;
+}
+
+export function CustomerCard<Doc>({ doc, traits, className, ...props }: CustomerCardProps<Doc>) {
+  if (!traits) return <CustomerCardFromContext doc={doc} className={className} {...props} />;
 
   const name = traits.getName(doc);
   const email = traits.getEmail(doc);

package/src/customer/customer-form.tsx

@@ -15,6 +15,7 @@ export interface CustomerFormProps extends Omit<ViewProps, 'children'> {
   onChangeField: (field: keyof CustomerFormValues, value: string) => void;
   onSubmit?: () => void;
   submitLabel?: string;
+  showAddress?: boolean;
   className?: string;
 }
 
@@ -43,6 +44,7 @@ export function CustomerForm({
   onChangeField,
   onSubmit,
   submitLabel = 'Save Customer',
+  showAddress = true,
   className,
   ...viewProps
 }: CustomerFormProps) {
@@ -58,7 +60,7 @@ export function CustomerForm({
       </View>
       <FormField label="Email" value={values.email} onChangeText={(v) => onChangeField('email', v)} placeholder="email@example.com" keyboardType="email-address" />
       <FormField label="Phone" value={values.phone} onChangeText={(v) => onChangeField('phone', v)} placeholder="Phone number" keyboardType="phone-pad" />
-      <FormField label="Address" value={values.address} onChangeText={(v) => onChangeField('address', v)} placeholder="Street address" multiline />
+      {showAddress && <FormField label="Address" value={values.address} onChangeText={(v) => onChangeField('address', v)} placeholder="Street address" multiline />}
 
       {onSubmit && (
         <Pressable onPress={onSubmit} className="items-center rounded-lg bg-primary px-4 py-3">

package/src/customer/customer-picker.tsx

@@ -0,0 +1,124 @@
+import { useEffect, useRef, useState } from 'react';
+import { Pressable, Text, TextInput, View } from 'react-native';
+import { customerTraits, CustomerServiceError, ConnectorUnauthorizedError, type Customer, type CustomerInput } from '@tallyui/core';
+import { cn } from '@tallyui/theme';
+import { CustomerCard } from './customer-card';
+import { CustomerSelect } from './customer-select';
+import { CustomerForm, type CustomerFormValues } from './customer-form';
+
+export interface CustomerPickerProps {
+  /** The connector's searchCustomers, bound to its context by the app. */
+  search: (query: string) => Promise<Customer[]>;
+  /** The connector's createCustomer, bound; absent hides "New customer". */
+  create?: (input: CustomerInput) => Promise<Customer>;
+  selected: Customer | null;
+  onSelect: (customer: Customer | null) => void;
+  /** Called for errors the picker can't explain to the cashier, including ConnectorUnauthorizedError, which means the app should sign in again. */
+  onError?: (error: unknown) => void;
+  /** false disables search and create (online only in v1). */
+  online: boolean;
+  /** Debounce before a search, ms. */
+  debounceMs?: number;
+  className?: string;
+}
+
+/** `@tallyui/core/server`'s `payloadBoundErrors` bound on `customer.email`, in UTF-16 code units. */
+const EMAIL_MAX = 254;
+/** A simple shape, not RFC 5322: one `@`, a non-empty local part, a domain with text either side of a dot, no whitespace or NUL. */
+const EMAIL_SHAPE = /^[^\s@\u0000]+@[^\s@\u0000]+\.[^\s@\u0000]+$/u;
+
+export function CustomerPicker({ search, create, selected, onSelect, onError, online, debounceMs = 250, className }: CustomerPickerProps) {
+  const [query, setQuery] = useState('');
+  const [customers, setCustomers] = useState<Customer[]>([]);
+  const [error, setError] = useState<string | null>(null);
+  const [showForm, setShowForm] = useState(false);
+  const [creating, setCreating] = useState(false);
+  const [values, setValues] = useState<CustomerFormValues>({ firstName: '', lastName: '', email: '', phone: '', address: '' });
+  const sequence = useRef(0);
+  const searchRef = useRef(search);
+  searchRef.current = search;
+  const [noResults, setNoResults] = useState(false);
+
+  function handleError(error: unknown) {
+    if (error instanceof CustomerServiceError) {
+      setError(error.code === 'network' ? "Couldn't reach the store. Try again."
+        : error.code === 'server' ? "The store couldn't do that. Try again." : error.message);
+    } else {
+      setError(error instanceof ConnectorUnauthorizedError ? 'Sign in again to continue.' : 'Something went wrong. Try again.');
+      onError?.(error);
+    }
+  }
+
+  useEffect(() => {
+    const current = ++sequence.current;
+    setNoResults(false);
+    setError(null);
+    if (!online || !query.trim()) { setCustomers([]); return; }
+    const timer = setTimeout(async () => {
+      try {
+        const results = await searchRef.current(query);
+        if (current === sequence.current) { setCustomers(results); setNoResults(results.length === 0); }
+      } catch (error) {
+        if (current === sequence.current) handleError(error);
+      }
+    }, debounceMs);
+    return () => { clearTimeout(timer); sequence.current++; };
+  }, [query, online, debounceMs]);
+
+  async function submit() {
+    const email = values.email.trim();
+    if (!online || !create || creating || !email) return;
+    // The till sends this email in order.create, whose shape check refuses one over 254 characters: refuse it here instead.
+    if (email.length > EMAIL_MAX || !EMAIL_SHAPE.test(email)) return setError(`Enter a valid email address (up to ${EMAIL_MAX} characters)`);
+    setCreating(true);
+    setError(null);
+    try {
+      const created = await create({ email,
+        ...(values.firstName.trim() ? { firstName: values.firstName.trim() } : {}),
+        ...(values.lastName.trim() ? { lastName: values.lastName.trim() } : {}),
+        ...(values.phone.trim() ? { phone: values.phone.trim() } : {}),
+      });
+      onSelect(created);
+      setValues({ firstName: '', lastName: '', email: '', phone: '', address: '' });
+      setShowForm(false);
+    } catch (error) {
+      handleError(error);
+    } finally {
+      setCreating(false);
+    }
+  }
+
+  return <View className={cn('gap-3', className)}>
+    {selected && <View>
+      <CustomerCard doc={selected} traits={customerTraits} />
+      <Pressable accessibilityRole="button" className="items-center rounded-lg border border-border px-4 py-3" onPress={() => onSelect(null)}><Text className="text-sm font-semibold text-foreground">Remove customer</Text></Pressable>
+    </View>}
+    <Text className="text-xs font-medium text-muted-foreground">Search customers</Text>
+    <TextInput accessibilityLabel="Search customers" value={query} onChangeText={setQuery} editable={online}
+      className="rounded-lg border border-border bg-card px-3 py-2 text-sm text-foreground"
+      placeholderTextColorClassName="accent-muted-foreground" placeholder="Name or email" />
+    {!online && <Text className="text-sm text-muted-foreground">Connect to search or add customers.</Text>}
+    {noResults && <Text className="text-sm text-muted-foreground">No customers found.</Text>}
+    {error && <Text accessibilityRole="alert" className="text-sm text-destructive">{error}</Text>}
+    <CustomerSelect customers={customers} traits={customerTraits} onSearch={setQuery}
+      onSelect={(customer) => { onSelect(customer); setQuery(''); }} />
+    {create && <Pressable accessibilityRole="button" disabled={!online || creating} onPress={() => setShowForm(true)}
+      className={cn('items-center rounded-lg border border-border px-4 py-3', (!online || creating) && 'opacity-50')}>
+      <Text className="text-sm font-semibold text-foreground">New customer</Text>
+    </Pressable>}
+    {showForm && <View>
+      <CustomerForm values={values} showAddress={false}
+        onChangeField={(field, value) => setValues((current) => ({ ...current, [field]: value }))} />
+      <View className="flex-row gap-3">
+        <Pressable accessibilityRole="button" disabled={!online || creating || !values.email.trim()} onPress={submit}
+          className={cn('items-center rounded-lg bg-primary px-4 py-3', (!online || creating || !values.email.trim()) && 'opacity-50')}>
+          <Text className="text-sm font-semibold text-primary-foreground">Save Customer</Text>
+        </Pressable>
+        <Pressable accessibilityRole="button" className="items-center rounded-lg border border-border px-4 py-3"
+          onPress={() => { setShowForm(false); setValues({ firstName: '', lastName: '', email: '', phone: '', address: '' }); }}>
+          <Text className="text-sm font-semibold text-foreground">Cancel</Text>
+        </Pressable>
+      </View>
+    </View>}
+  </View>;
+}

package/src/customer/customer-select.tsx

@@ -1,17 +1,18 @@
-import { ScrollView, View } from 'react-native';
+import { Pressable, ScrollView, View } from 'react-native';
 import { Select } from '@tallyui/primitives';
-import { useCustomerTraits } from '@tallyui/core';
+import { useCustomerTraits, type CustomerTraits } from '@tallyui/core';
 import { cn } from '@tallyui/theme';
 import { VStack, type VStackProps } from '../ui';
 import { CustomerCard } from './customer-card';
 
-export interface CustomerSelectProps extends Omit<VStackProps, 'children'> {
+export interface CustomerSelectProps<Doc = any> extends Omit<VStackProps, 'children'> {
   /** Customer documents to display as options */
-  customers: any[];
+  customers: Doc[];
   /** Currently selected customer (if any) */
-  selected?: any;
+  selected?: Doc | null;
   /** Called when a customer is selected */
-  onSelect: (customer: any) => void;
+  onSelect: (customer: Doc) => void;
+  traits?: CustomerTraits<Doc>;
   /** Called when the search text changes */
   onSearch: (query: string) => void;
   /** Placeholder text for the search input */
@@ -39,16 +40,24 @@ export interface CustomerSelectProps extends Omit<VStackProps, 'children'> {
  * />
  * ```
  */
-export function CustomerSelect({
+export function CustomerSelect<Doc>(props: CustomerSelectProps<Doc>) {
+  return props.traits ? <CustomerSelectView {...props} /> : <CustomerSelectFromContext {...props} />;
+}
+
+function CustomerSelectFromContext<Doc>(props: CustomerSelectProps<Doc>) {
+  return <CustomerSelectView {...props} traits={useCustomerTraits()} />;
+}
+
+function CustomerSelectView<Doc>({
   customers,
   selected,
   onSelect,
   onSearch,
   placeholder = 'Search customers...',
   className,
+  traits,
   ...props
-}: CustomerSelectProps) {
-  const traits = useCustomerTraits();
+}: CustomerSelectProps<Doc>) {
 
   // Map selected customer to Select primitive's Option format
   const selectedOption = selected && traits
@@ -56,7 +65,7 @@ export function CustomerSelect({
     : undefined;
 
   // Build a lookup so we can resolve the original customer doc on selection
-  const customerById = new Map<string, any>();
+  const customerById = new Map<string, Doc>();
   if (traits) {
     for (const customer of customers) {
       customerById.set(traits.getId(customer), customer);
@@ -78,7 +87,7 @@ export function CustomerSelect({
         {selected && traits && (
           <Select.Trigger asChild>
             <View className="rounded-lg border border-primary bg-primary/5 px-3 py-2">
-              <CustomerCard doc={selected} />
+              <CustomerCard doc={selected} traits={traits} />
             </View>
           </Select.Trigger>
         )}
@@ -89,6 +98,7 @@ export function CustomerSelect({
               {customers.map((customer, index) => {
                 const id = traits?.getId(customer) ?? String(index);
                 const label = traits?.getName(customer) ?? '';
+                const email = traits?.getEmail(customer);
                 return (
                   <Select.Item
                     key={id}
@@ -96,9 +106,9 @@ export function CustomerSelect({
                     label={label}
                     asChild
                   >
-                    <View className="border-b border-border px-3 py-2">
-                      <CustomerCard doc={customer} />
-                    </View>
+                    <Pressable accessibilityLabel={email ? `${label}, ${email}` : label} className="border-b border-border px-3 py-2">
+                      <CustomerCard doc={customer} traits={traits} />
+                    </Pressable>
                   </Select.Item>
                 );
               })}

package/src/customer/index.ts

@@ -2,3 +2,4 @@ export { CustomerCard, type CustomerCardProps } from './customer-card';
 export { CustomerSelect, type CustomerSelectProps } from './customer-select';
 export { CustomerForm, type CustomerFormProps, type CustomerFormValues } from './customer-form';
 export { CustomerOrderHistory, type CustomerOrderHistoryProps } from './customer-order-history';
+export { CustomerPicker, type CustomerPickerProps } from './customer-picker';

package/src/index.ts

@@ -63,6 +63,8 @@ export {
 export {
   CustomerCard,
   CustomerSelect,
+  CustomerPicker,
+  type CustomerPickerProps,
   type CustomerCardProps,
   type CustomerSelectProps,
   CustomerForm,

package/src/product/product-grid.tsx

@@ -1,9 +1,16 @@
 import type { ReactNode } from 'react';
-import { ScrollView, View } from 'react-native';
+import { FlatList, View } from 'react-native';
 import { cn } from '@tallyui/theme';
 import { useProductTraits } from '@tallyui/core';
 import { VStack, type VStackProps } from '../ui';
 
+// Limit initial mounts for a 2,000-product catalogue to eight rows.
+const INITIAL_ROWS = 8;
+// Keep each render batch small for a 2,000-product catalogue.
+const BATCH_ROWS = 8;
+// Keep nearby rows mounted without rendering the whole 2,000-product catalogue.
+const WINDOW_SIZE = 5;
+
 export interface ProductGridProps extends Omit<VStackProps, 'children'> {
   /** Array of product documents to render */
   items: any[];
@@ -27,10 +34,9 @@ export interface ProductGridProps extends Omit<VStackProps, 'children'> {
 }
 
 /**
- * A scrollable product grid with optional search and filter slots.
+ * A virtualized product grid with optional search and filter slots.
  *
- * Uses ScrollView + flexWrap for cross-platform grid layout rather than
- * FlatList numColumns, which keeps things predictable in both native and web.
+ * Uses FlatList numColumns to render rows near the viewport on native and web.
  *
  * ```tsx
  * <ProductGrid
@@ -70,13 +76,21 @@ export function ProductGrid({
       {filterSlot && <View className="px-3 pb-2">{filterSlot}</View>}
 
       {hasItems ? (
-        <ScrollView contentContainerClassName="flex-row flex-wrap p-1">
-          {visibleItems.map((item, index) => (
-            <View key={item.id ?? index} style={{ width: `${100 / numColumns}%` }} className="p-1">
+        <FlatList
+          key={numColumns}
+          data={visibleItems}
+          numColumns={numColumns}
+          keyExtractor={(item, index) => String(item.id ?? index)}
+          contentContainerClassName="p-1"
+          initialNumToRender={INITIAL_ROWS}
+          maxToRenderPerBatch={BATCH_ROWS}
+          windowSize={WINDOW_SIZE}
+          renderItem={({ item, index }) => (
+            <View style={{ width: `${100 / numColumns}%` }} className="p-1">
               {renderItem(item, index)}
             </View>
-          ))}
-        </ScrollView>
+          )}
+        />
       ) : (
         emptyState ?? null
       )}

package/src/register/closure-sheet.tsx

@@ -1,7 +1,7 @@
 import { useEffect, useRef, useState } from 'react';
 import { AccessibilityInfo, Animated, View } from 'react-native';
 import type { useRegisterSession } from '@tallyui/pos';
-import { countVariance, varianceText } from '@tallyui/pos';
+import { countVariance, TAX_ROUNDING_MIXED_NOTE, varianceText } from '@tallyui/pos';
 
 import { formatMoney, minorUnitDigits } from '@tallyui/core';
 import { Button } from '../ui/button';
@@ -136,6 +136,12 @@ export function ClosureSheet({ register, currency, onPrint, onDone }: ClosureShe
         )}
         {/* Not a figure: shows who approved the close even while blind. */}
         {!!approvedBy && <Text testID="closure-approved-by">Approved by {approvedBy}</Text>}
+        {/* Not a figure either (#287). The wording is approved by the Front desk, 2026-09-30. */}
+        {closure.breakdowns.tax_rounding_mixed === true && (
+          <Text testID="closure-tax-rounding-mixed" className="text-muted-foreground">
+            {TAX_ROUNDING_MIXED_NOTE}
+          </Text>
+        )}
         {!!error && (
           <Text testID="closure-print-error" className="text-destructive">
             {error}

package/src/sale/catalogue.tsx

@@ -1,6 +1,6 @@
 import { useEffect, useMemo, useState, type ReactNode } from 'react';
 import { Pressable, Text, View } from 'react-native';
-import type { ProductTraits } from '@tallyui/core';
+import { useStockOverlaid, useStockOverlayAsOf, type ProductTraits } from '@tallyui/core';
 import { catalogueEntries, findEntryByCode, searchProducts, variantPriceLabel, type CatalogueEntry } from '@tallyui/pos';
 import { ProductGrid, ProductImage, ProductPrice, ProductStockBadge, ProductTitle } from '../product';
 import { SearchInput } from '../input';
@@ -36,12 +36,14 @@ export function Catalogue<Doc>({ products, traits, currency, onSelect, statusTex
   products: Doc[];
   traits: ProductTraits<Doc>;
   currency: string;
+  /** Receives the chosen product and variant with the nearest ConnectorProvider's stock overlay applied (a copy). */
   onSelect: (entry: CatalogueEntry<Doc>) => void;
   statusText?: string;
   /** Rendered at the end of the status line, e.g. a register control at phone width; the row renders even without `statusText`. */
   statusAccessory?: ReactNode;
   lastSyncedAt: Date | null;
-  /** The last completed stock reconcile pass, persisted across restarts; the later of this and lastSyncedAt wins. */
+  /** The last completed stock reconcile pass, persisted across restarts. The "stock as of" time shown is the
+   * latest of this, the provider's stockOverlayAsOf (when valid) and lastSyncedAt; null and omitted alike. */
   lastStockCheckAt?: Date | null;
   /** Whether to show a 12- or 24-hour clock in the stock-as-of time; undefined keeps the locale default. A platform
    * reads this off its own device APIs (e.g. expo-localization's getCalendars()) and passes it in. */
@@ -51,7 +53,13 @@ export function Catalogue<Doc>({ products, traits, currency, onSelect, statusTex
    * in its unfocused wedge listener — not this prop's job. */
   minCodeLength?: number;
 }) {
-  const stockAsOf = laterOf(lastStockCheckAt, lastSyncedAt);
+  // Idempotent (the adapter's overlay returns just the fields the stock map sets), so an app that already
+  // merges the overlay itself keeps working, and can drop its own merge.
+  const shown = useStockOverlaid(products) as Doc[];
+  const overlayAsOf = useStockOverlayAsOf();
+  const parsedOverlayAsOf = overlayAsOf ? new Date(overlayAsOf) : undefined;
+  const validOverlayAsOf = parsedOverlayAsOf && !isNaN(parsedOverlayAsOf.getTime()) ? parsedOverlayAsOf : undefined;
+  const stockAsOf = laterOf(laterOf(lastStockCheckAt, validOverlayAsOf), lastSyncedAt);
   const [query, setQuery] = useState('');
   // The chooser is live (medusapos ADR 0007): it holds only the chosen product's id and derives its choices
   // from the current entries below, so an open chooser shows each reconcile pass as it lands.
@@ -59,8 +67,8 @@ export function Catalogue<Doc>({ products, traits, currency, onSelect, statusTex
   const [width, setWidth] = useState(0);
   // ProductGrid has 4 px padding on each side of the content and each cell.
   const columns = Math.max(2, Math.min(6, Math.floor((width - 8) / (MIN_TILE_WIDTH + 8))));
-  const entries = useMemo(() => catalogueEntries(products, traits), [products, traits]);
-  const results = useMemo(() => searchProducts(products, query, traits), [products, query, traits]);
+  const entries = useMemo(() => catalogueEntries(shown, traits), [shown, traits]);
+  const results = useMemo(() => searchProducts(shown, query, traits), [shown, query, traits]);
   const choices = useMemo(() => (chooserId === null ? []
     : entries.filter((entry) => traits.getId(entry.product) === chooserId)), [entries, chooserId, traits]);
   // A product that leaves the catalogue (a resync, or no longer sellable) closes its chooser.

package/src/sale/orders-list.tsx

@@ -1,9 +1,29 @@
 import { useEffect, useRef, useState, type ReactNode } from 'react';
 import { Pressable, ScrollView, Text, View } from 'react-native';
-import { formatMoney } from '@tallyui/core';
-import { needsAttention, type PosOrder } from '@tallyui/pos';
+import { formatMoney, knownWarnings } from '@tallyui/core';
+import { needsAttention, type OutboxState, type PosOrder } from '@tallyui/pos';
 
 const STATUS_LABEL = { pending: 'Waiting to sync', applied: 'Synced', rejected: 'Not accepted' };
+/** `figures_mismatch`'s labels; a field a newer store sends that isn't here is shown by its raw name. */
+const FIGURE_LABELS = new Map([['subtotalMinor', 'Subtotal'], ['taxMinor', 'Tax'], ['discountMinor', 'Discount']]);
+/** A rejected sale's line in the cashier's words, by the store's error code (#269). The store's own message goes to the
+ * sync log (the outbox logs it), never here. */
+const REFUSAL_SENTENCES = new Map([
+  ['invalid_payload', "The online store refused this sale: this till sent it in a form the store can't read. Ask the store owner to look at the till's sync log."],
+  ['unsupported_version', "The online store refused this sale: the store's software is older than this till's. Ask the store owner to update the POS plugin."],
+  ['idempotency_mismatch', "The online store has a different sale under this sale's number. Don't send it again; ask the store owner to compare the two."],
+  ['store_configuration', 'The online store refused this sale: a setting on the store needs changing. Once the store owner fixes it, press Retry.'],
+  ['platform_error', "The online store refused this sale. Ask the store owner to look at the till's sync log."],
+  ['internal_error', "The online store hit a fault in its POS plugin and refused this sale. Ask the store owner to look at the till's sync log."],
+  ['insufficient_stock', "The online store refused this sale: it doesn't have enough stock of one of the items."],
+  ['unsupported_tax_mode', "The online store refused this sale: its tax settings can't take a sale like this one. Ask the store owner to check them."],
+  ['unknown_variant', 'The online store refused this sale: that product variation no longer exists.'],
+  ['invalid_quantity', "The online store refused this sale: a quantity or a discount on it isn't allowed."],
+  ['underpaid', 'The online store refused this sale: the payments add up to less than the total.'],
+  ['unsupported_currency', "The online store refused this sale: the store doesn't take this currency."],
+]);
+// Any other code, or none: platform_error's sentence, as the generic fallback (approved by the Front desk, 2026-09-30).
+const refusalSentence = (code: string | undefined) => REFUSAL_SENTENCES.get(code ?? '') ?? REFUSAL_SENTENCES.get('platform_error')!;
 
 /** Keeps an unparseable value as is, like medusapos's date util, since `Intl` throws on an invalid date. */
 function defaultFormatDate(iso: string) {
@@ -13,9 +33,11 @@ function defaultFormatDate(iso: string) {
 
 /** The "Needs attention" (when not empty) and "Recent" orders, lifted from medusapos/app's orders screen (ADR-052).
  * `onRetry` is the outbox's `requeue`; `formatDate` replaces the app's date util; `footer` is the app's own content
- * (medusapos: the feedback link). The router and session redirect stay in the app. */
-export function OrdersList({ orders, onRetry, formatDate = defaultFormatDate, footer }: {
+ * (medusapos: the feedback link). The router and session redirect stay in the app. `stuck` is the outbox's
+ * `state.stuck` (`useOrderOutbox`): those pending orders need attention too, each with its own entry's reason and since. */
+export function OrdersList({ orders, onRetry, formatDate = defaultFormatDate, footer, stuck }: {
   orders: PosOrder[]; onRetry(orderIds: string[]): Promise<number>; formatDate?: (iso: string) => string; footer?: ReactNode;
+  stuck?: OutboxState['stuck'];
 }) {
   const retrying = useRef(new Set<string>());
   const [retryingIds, setRetryingIds] = useState(new Set<string>());
@@ -26,21 +48,33 @@ export function OrdersList({ orders, onRetry, formatDate = defaultFormatDate, fo
     setRetryingIds(new Set(retrying.current));
   }, [orders]);
   return <ScrollView className="flex-1 bg-background p-4">
-    {[{ title: 'Needs attention', orders: needsAttention(orders) }, { title: 'Recent', orders }].filter((section) => section.title === 'Recent' || section.orders.length > 0).map((section) => (
+    {[{ title: 'Needs attention', orders: needsAttention(orders, { stuckCommandIds: stuck?.commandIds }) }, { title: 'Recent', orders }].filter((section) => section.title === 'Recent' || section.orders.length > 0).map((section) => (
       <View key={section.title} className="mb-6 gap-3">
         <Text accessibilityRole="header" className="text-xl font-semibold text-foreground">{section.title}</Text>
         {section.orders.map((order) => {
           const count = order.lines.reduce((sum, line) => sum + line.quantity, 0);
+          // The order's own stuck entry: its clock and latest reason, not the earliest across all stuck orders.
+          const stuckEntry = order.syncStatus === 'pending' ? stuck?.orders.find((entry) => entry.commandId === order.commandId) : undefined;
           return (
           <View key={order.id} className="gap-1 rounded-md border border-border bg-card p-3">
             <Text className="text-foreground">{order.serverRefs?.displayId ? `Order #${order.serverRefs.displayId} · ` : ''}{count} {count === 1 ? 'item' : 'items'}</Text>
             <Text className="text-muted-foreground">{formatDate(order.createdAt)} · {formatMoney({ amount: order.totalMinor, currency: order.currency })} · {STATUS_LABEL[order.syncStatus]}</Text>
-            {order.syncStatus === 'rejected' && order.error ? <Text className="text-destructive">{order.error.code}: {order.error.message}</Text> : null}
+            {stuckEntry ? <Text className="text-destructive">
+              {/* The same words for any reason, with no reason code; the hour as the status line has it (numeric, #245). */}
+              {`Hasn't reached the online store since ${new Date(stuckEntry.since).toLocaleTimeString(undefined, { hour: 'numeric', minute: '2-digit' })}.`}
+            </Text> : null}
+            {/* The code's sentence alone: the cashier sees no error code and never the store's message. */}
+            {order.syncStatus === 'rejected' ? <Text className="text-destructive">{refusalSentence(order.error?.code)}</Text> : null}
             {/* A late sale (ADR-032) needs no Retry of its own; a rejected one still gets its Retry below. */}
             {order.lateSessionId !== undefined ? <Text className="text-foreground">Taken after the register closed. It is not in that register's closure.</Text> : null}
-            {section.title === 'Needs attention' && order.syncStatus === 'rejected' ? order.error?.code === 'idempotency_mismatch'
-              ? <Text className="text-foreground">This sale needs checking against the store before it can be sent again.</Text>
-              : <Pressable accessibilityRole="button" disabled={retryingIds.has(order.id)} onPress={async () => {
+            {order.localWarnings?.map((warning, index) => <Text key={index} className="text-foreground">
+              {warning.code === 'customer_omitted'
+                ? `The customer's ${warning.field} couldn't be sent to the store, so the order isn't linked to them.`
+                : "The terminal's payment reference couldn't be kept; the payment is recorded without it."}
+            </Text>)}
+            {/* idempotency_mismatch isn't requeueable (the outbox's NOT_REQUEUEABLE): its sentence says not to send it again, and no Retry. */}
+            {section.title === 'Needs attention' && order.syncStatus === 'rejected' && order.error?.code !== 'idempotency_mismatch'
+              ? <Pressable accessibilityRole="button" disabled={retryingIds.has(order.id)} onPress={async () => {
                 if (retrying.current.has(order.id)) return;
                 retrying.current.add(order.id);
                 setRetryingIds(new Set(retrying.current));
@@ -51,9 +85,17 @@ export function OrdersList({ orders, onRetry, formatDate = defaultFormatDate, fo
               }} className="rounded-md bg-primary px-4 py-2">
                 <Text className="text-center font-semibold text-primary-foreground">Retry</Text>
               </Pressable> : null}
-            {order.warnings?.map((warning, index) => <View key={index} className="border-l-4 border-warning pl-2"><Text className="text-foreground">
+            {knownWarnings(order.warnings).map((warning, index) => <View key={index} className="border-l-4 border-warning pl-2"><Text className="text-foreground">
               {warning.code === 'insufficient_stock'
                 ? `Stock short by ${warning.quantity} for ${order.lines.find((line) => line.variantId === warning.variantId)?.name}`
+                : warning.code === 'tax_rate_mismatch'
+                ? `Tax at ${(warning.ratePpm / 10000).toLocaleString(undefined, { maximumFractionDigits: 4 })}%: store ${formatMoney({ amount: warning.serverMinor, currency: order.currency })} vs POS ${formatMoney({ amount: warning.expectedMinor, currency: order.currency })}`
+                : warning.code === 'customer_ignored'
+                ? `The online store didn't recognise the customer on this sale, so it was saved as a guest sale. Customer id: ${warning.customerId}.`
+                : warning.code === 'figures_mismatch'
+                ? `The online store worked out different figures for this sale. ${warning.fields.map(({ field, tillMinor, serverMinor }) => `${FIGURE_LABELS.get(field) ?? field}: till ${formatMoney({ amount: tillMinor, currency: order.currency })}, store ${formatMoney({ amount: serverMinor, currency: order.currency })}.`).join(' ')}`
+                : warning.bridgeMinor !== undefined
+                ? `Store calculated ${formatMoney({ amount: warning.serverMinor, currency: order.currency })}; a rounding line of ${warning.bridgeMinor > 0 ? '+' : ''}${formatMoney({ amount: warning.bridgeMinor, currency: order.currency })} brought it to ${formatMoney({ amount: warning.expectedMinor, currency: order.currency })}`
                 : `Store total ${formatMoney({ amount: warning.serverMinor, currency: order.currency })} vs POS ${formatMoney({ amount: warning.expectedMinor, currency: order.currency })}`}
             </Text></View>)}
           </View>

package/src/sale/receipt.tsx

@@ -1,7 +1,7 @@
 import { useEffect } from 'react';
 import { Pressable, Text, View } from 'react-native';
 import { formatMoney } from '@tallyui/core';
-import { buildReceiptData, type Order } from '@tallyui/pos';
+import { buildReceiptData, type SentOrder } from '@tallyui/pos';
 import { injectPrintStyle } from './print-style';
 import { discountLabel } from './discount-form';
 
@@ -11,7 +11,7 @@ const defaultFormatDate = (iso: string) => new Intl.DateTimeFormat(undefined, {
  * TV6a's `Cart`), outbox strip and date util, so `Receipt` stays platform-neutral (ADR-052). */
 export function Receipt({ order, store, cashier, registerId, newSale, taxLabel = (ratePpm: number) => `Tax ${ratePpm / 10000}%`,
   topInset = 0, formatDate = defaultFormatDate }: {
-  order: Order; store: { name: string; address?: string }; cashier: string; registerId: string; newSale: () => void;
+  order: SentOrder; store: { name: string; address?: string }; cashier: string; registerId: string; newSale: () => void;
   taxLabel?: (ratePpm: number) => string; topInset?: number; formatDate?: (iso: string) => string;
 }) {
   useEffect(injectPrintStyle, []);
@@ -34,6 +34,7 @@ export function Receipt({ order, store, cashier, registerId, newSale, taxLabel =
     <Text className="text-foreground">Order {receipt.header.orderNumber.slice(-8)}</Text>
     <Text className="text-muted-foreground">{formatDate(receipt.header.date)}</Text>
     <Text className="text-muted-foreground">Cashier: {receipt.header.cashier}</Text>
+    {receipt.header.customer && <Text className="text-muted-foreground">Customer: {receipt.header.customer}</Text>}
     {receipt.lineItems.map((line, index) => <View key={index}>
       <Text className="text-foreground">{line.name}</Text>
       {/* Before any discount, then the line's own discounts as sub-rows (TallyUI ADR-063); they add up to the subtotal. */}