@classytic/pos-ui 0.2.0 → 1.3.0

package/dist/hooks/usePosDelivery.js

@@ -0,0 +1,133 @@
+"use client";
+
+import { branchScopedKey } from "./branch-scoped-key.js";
+import { useCallback } from "react";
+import { useLocalStorage } from "@classytic/fluid/client/hooks";
+import { toast } from "sonner";
+
+//#region src/hooks/usePosDelivery.ts
+/**
+* Delivery and payment TERM for the sale being rung.
+*
+* Two independent decisions that a till has never been able to express, and which
+* the backend now models end to end:
+*
+*   - **where the goods go** — carryout (the cashier hands them over) or delivery
+*     (a courier does, later, to an address);
+*   - **when the customer pays** — now, or on delivery.
+*
+* They are orthogonal. A phone order can be prepaid by bKash and shipped; a
+* walk-in can pay cash for something delivered tomorrow; and a COD order is the
+* one where no money exists yet.
+*
+* ## Persisted, branch-scoped, for the reason the cart is
+*
+* `ProductScreen` and `PaymentScreen` each mount their own hook instances — the POS
+* state machine swaps one screen for the other — so per-instance `useState` is wiped
+* on navigation. A delivery address typed on one screen and silently empty on the
+* next is the same class of loss `usePosCustomer` records, and here it would land as
+* a refused sale (`DELIVERY_ADDRESS_UNUSABLE`) with the customer at the counter.
+*
+* The namespace goes through `branchScopedKey`, so an unresolved branch gets the
+* sentinel and every mutator refuses rather than writing to a namespace about to be
+* abandoned. See `branch-scoped-key.ts`.
+*
+* ## The address shape
+*
+* `line1` + `city` are what the host's normalizer REQUIRES (be-prod's
+* `toFulfillmentAddress`; country defaults). The rest is evidence a courier and a
+* dispatcher actually need. The server normalizes and REFUSES an undispatchable
+* delivery before it takes payment or holds stock, so this form's job is to collect
+* enough that the refusal never fires — not to re-implement the validation.
+*
+* NOTE: this is the seventh hand-rolled address surface in the repo. A shared
+* `addressFields()` builder is planned (`tasks/pos-plan.md`); pos-ui depends on
+* neither `@classytic/formkit` nor `@classytic/commerce-ui` today, so it cannot
+* consume it yet. When it lands, this component is a migration target — the shape
+* below is deliberately the same field set.
+*/
+/** Match the cart's window: an abandoned sale's delivery details expire with it. */
+const DELIVERY_TTL = 864e5;
+const EMPTY_ADDRESS = {
+	recipientName: "",
+	recipientPhone: "",
+	addressLine1: "",
+	city: "",
+	area: "",
+	note: ""
+};
+/** Major-unit fee. A blank field is no fee, not a zero-valued fee row. */
+function parseFee(input) {
+	const n = Number.parseFloat(input);
+	return Number.isFinite(n) && n > 0 ? n : 0;
+}
+function usePosDelivery(branchId) {
+	const { key, ready } = branchScopedKey("pos:delivery", branchId);
+	const [method, setMethodState] = useLocalStorage(`${key}:method`, "pickup", DELIVERY_TTL);
+	const [address, setAddress] = useLocalStorage(`${key}:address`, EMPTY_ADDRESS, DELIVERY_TTL);
+	const [feeInput, setFeeInputState] = useLocalStorage(`${key}:fee`, "", DELIVERY_TTL);
+	const [paymentTerm, setPaymentTermState] = useLocalStorage(`${key}:paymentTerm`, "prepaid", DELIVERY_TTL);
+	/**
+	* The one guard every mutator calls first — the same shape `usePosCart` uses, and
+	* loud on purpose. The alternative is a typed address that is about to be orphaned
+	* when the branch resolves and the key changes under it.
+	*/
+	const refuseIfBranchUnresolved = useCallback(() => {
+		if (ready) return false;
+		toast.error("Branch not ready", { description: "The register is still resolving its branch. Try again in a moment." });
+		return true;
+	}, [ready]);
+	return {
+		method,
+		address,
+		feeInput,
+		paymentTerm,
+		setMethod: useCallback((next) => {
+			if (refuseIfBranchUnresolved()) return;
+			setMethodState(next);
+			/**
+			* Switching back to carryout clears collect-on-delivery.
+			*
+			* "Collect on delivery" names a delivery that has not happened yet. On a
+			* carryout sale there is no later collection — the customer is standing there
+			* — so leaving the term set would submit a sale that owes money to nobody, and
+			* the server would refuse it after the cashier had already moved on.
+			*/
+			if (next === "pickup") setPaymentTermState("prepaid");
+		}, [
+			refuseIfBranchUnresolved,
+			setMethodState,
+			setPaymentTermState
+		]),
+		setAddressField: useCallback((field, value) => {
+			if (refuseIfBranchUnresolved()) return;
+			setAddress((prev) => ({
+				...prev,
+				[field]: value
+			}));
+		}, [refuseIfBranchUnresolved, setAddress]),
+		setFeeInput: useCallback((value) => {
+			if (refuseIfBranchUnresolved()) return;
+			setFeeInputState(value);
+		}, [refuseIfBranchUnresolved, setFeeInputState]),
+		setPaymentTerm: useCallback((term) => {
+			if (refuseIfBranchUnresolved()) return;
+			setPaymentTermState(term);
+		}, [refuseIfBranchUnresolved, setPaymentTermState]),
+		reset: useCallback(() => {
+			setMethodState("pickup");
+			setAddress(EMPTY_ADDRESS);
+			setFeeInputState("");
+			setPaymentTermState("prepaid");
+		}, [
+			setMethodState,
+			setAddress,
+			setFeeInputState,
+			setPaymentTermState
+		]),
+		fee: parseFee(feeInput)
+	};
+}
+
+//#endregion
+export { usePosDelivery };

package/dist/hooks/usePosMultiOrder.d.ts

@@ -0,0 +1,22 @@
+import { PosCartItem } from "../dashboard/pos.types.js";
+//#region src/hooks/usePosMultiOrder.d.ts
+interface ParkedOrder {
+  id: string;
+  label: string;
+  cart: PosCartItem[];
+  customerName: string;
+  customerPhone: string;
+  membershipCardId: string;
+  discountInput: string;
+  parkedAt: number;
+}
+interface UsePosMultiOrderReturn {
+  orders: ParkedOrder[];
+  parkOrder: (order: Omit<ParkedOrder, "id" | "parkedAt">) => string;
+  resumeOrder: (id: string) => ParkedOrder | null;
+  deleteOrder: (id: string) => void;
+  canPark: boolean;
+}
+declare function usePosMultiOrder(branchId?: string): UsePosMultiOrderReturn;
+//#endregion
+export { ParkedOrder, UsePosMultiOrderReturn, usePosMultiOrder };

package/dist/hooks/usePosMultiOrder.js

@@ -1,5 +1,6 @@
 "use client";
 
+import { branchScopedKey } from "./branch-scoped-key.js";
 import { useCallback } from "react";
 import { useLocalStorage } from "@classytic/fluid/client/hooks";
 
@@ -11,13 +12,22 @@ import { useLocalStorage } from "@classytic/fluid/client/hooks";
 * Each parked order saves: cart items, customer info, discount state.
 */
 const MAX_PARKED_ORDERS = 5;
-const PARKED_TTL = 480 * 60 * 1e3;
+const PARKED_TTL = 288e5;
 function usePosMultiOrder(branchId) {
-	const [orders, setOrders] = useLocalStorage(branchId ? `pos:parked:${branchId}` : "pos:parked:default", [], PARKED_TTL);
-	const canPark = orders.length < MAX_PARKED_ORDERS;
+	/**
+	* Per-BRANCH, and an unresolved branch is not a branch — the same defect the
+	* cart had, with a longer fuse: a sale parked under `"default"` was orphaned the
+	* moment the branch resolved, and parked sales are the ONE cart the cashier
+	* expects to still be there after walking away. `branch-scoped-key.ts` has the
+	* full account.
+	*/
+	const { key, ready } = branchScopedKey("pos:parked", branchId);
+	const [orders, setOrders] = useLocalStorage(key, [], PARKED_TTL);
+	const canPark = ready && orders.length < MAX_PARKED_ORDERS;
 	return {
 		orders,
 		parkOrder: useCallback((order) => {
+			if (!ready) return "";
 			const id = `parked_${Date.now()}_${Math.random().toString(36).slice(2, 6)}`;
 			const parked = {
 				...order,
@@ -26,7 +36,7 @@ function usePosMultiOrder(branchId) {
 			};
 			setOrders((prev) => [...prev, parked]);
 			return id;
-		}, [setOrders]),
+		}, [setOrders, ready]),
 		resumeOrder: useCallback((id) => {
 			let found = null;
 			setOrders((prev) => {

package/dist/hooks/usePosPayment.d.ts

@@ -0,0 +1,22 @@
+import { PaymentOption, PaymentState, PosPaymentMethod, SplitPaymentEntry } from "@classytic/commerce-sdk/sales";
+//#region src/hooks/usePosPayment.d.ts
+declare function paymentNeedsReference(posMethod: PosPaymentMethod): boolean;
+interface UsePosPaymentReturn {
+  options: PaymentOption[];
+  isLoading: boolean;
+  state: PaymentState;
+  selectedOption: PaymentOption | null;
+  selectPayment: (key: string) => void;
+  setMode: (mode: "single" | "split") => void;
+  setCashReceived: (value: string) => void;
+  setReference: (value: string) => void;
+  addSplit: (paymentKey?: string) => void;
+  updateSplit: (id: string, patch: Partial<Pick<SplitPaymentEntry, "paymentKey" | "amount" | "reference">>) => void;
+  removeSplit: (id: string) => void;
+  validateSplitEntry: (id: string) => string | undefined;
+  validateAllSplits: () => boolean;
+  reset: () => void;
+}
+declare function usePosPayment(token?: string, total?: number): UsePosPaymentReturn;
+//#endregion
+export { type PaymentOption, type SplitPaymentEntry, UsePosPaymentReturn, paymentNeedsReference, usePosPayment };

package/dist/lib/delivery-payload.js

@@ -0,0 +1,83 @@
+//#region src/lib/delivery-payload.ts
+/**
+* What the customer owes: goods (after discounts) PLUS the delivery charge.
+*
+* The server computes the same sum and validates the tender against it, so a screen
+* quoting only the cart total collects too little and the sale is refused AFTER the
+* cashier has counted cash. Every payable figure on the screen reads this — numpad
+* target, split check, cash suggestions, both button labels.
+*
+* The fee only counts on a DELIVERY sale: a charge left in the box from a previous
+* selection must not silently inflate a carryout.
+*/
+function payableTotalOf(cartTotal, decision) {
+	return decision.method === "delivery" && decision.fee > 0 ? cartTotal + decision.fee : cartTotal;
+}
+/**
+* Does this sale take money at the till?
+*
+* Both conditions, not just the term. "Collect on delivery" names a delivery that
+* has not happened yet; on a carryout the customer is standing at the counter, so a
+* COD flag there would tell the cashier not to collect money that is owed right now.
+*/
+function isCollectOnDeliverySale(decision) {
+	return decision.paymentTerm === "collect_on_delivery" && decision.method === "delivery";
+}
+/**
+* Why this sale cannot be submitted, or `null`.
+*
+* Mirrors the server's refusal so the cashier is stopped at the field rather than at
+* the end of checkout. `addressLine1` + `city` are what the host normalizer requires;
+* the server re-checks and refuses (`DELIVERY_ADDRESS_UNUSABLE`) before taking a
+* tender or holding stock, so this is an affordance, never the enforcement.
+*/
+function deliveryBlocker(decision) {
+	if (decision.method !== "delivery") return null;
+	if (!decision.address.addressLine1?.trim()) return "Enter the delivery address";
+	if (!decision.address.city?.trim()) return "Enter the delivery city or town";
+	return null;
+}
+/**
+* The delivery fields for the create payload.
+*
+* Three omissions are deliberate and each has a consequence:
+*
+*   - **no `deliveryAddress` on a carryout** — there is nothing to dispatch to, and
+*     a stale address from a previous selection would ride along;
+*   - **no `deliveryPrice` when the fee is zero** — free delivery is real (a
+*     promotion, a loyalty perk), and an explicit `0` writes a priced shipping row
+*     for a sale that has none rather than leaving it identical to a carryout;
+*   - **blank address fields dropped** — an empty string is not a recipient name.
+*
+* `paymentTerm` is ALWAYS sent, prepaid included: the till knows the answer, and a
+* stated fact beats one every downstream reader infers from absence — absence is
+* also what an order written before the field existed looks like, and those are
+* different claims.
+*/
+function deliveryPayloadOf(decision) {
+	const base = {
+		deliveryMethod: decision.method,
+		paymentTerm: decision.paymentTerm
+	};
+	if (decision.method !== "delivery") return base;
+	const a = decision.address;
+	const address = {};
+	const put = (key, value) => {
+		const trimmed = value?.trim();
+		if (trimmed) address[key] = trimmed;
+	};
+	put("addressLine1", a.addressLine1);
+	put("city", a.city);
+	put("recipientName", a.recipientName);
+	put("recipientPhone", a.recipientPhone);
+	put("area", a.area);
+	put("note", a.note);
+	return {
+		...base,
+		deliveryAddress: address,
+		...decision.fee > 0 ? { deliveryPrice: decision.fee } : {}
+	};
+}
+
+//#endregion
+export { deliveryBlocker, deliveryPayloadOf, isCollectOnDeliverySale, payableTotalOf };

package/dist/lib/money.js

@@ -1,25 +1,62 @@
-import { MinorUnits, money, toMajor } from "@classytic/primitives/money";
+import { minorUnitFactor } from "@classytic/primitives/currency";
+import { MinorUnits, money, toMajor, toMajor as toMajor$1 } from "@classytic/primitives/money";
 
 //#region src/lib/money.ts
 /**
 * Money for POS — composed on `@classytic/primitives` (the canonical Money type
-* + arithmetic authority), with thin BDT display formatters on top. The package
-* is BD-tenant (BDT / `৳` / `en-BD`); a non-BD deployment forks these three
-* constants. Arithmetic and the `Money` type always come from primitives — this
-* module never re-implements them.
+* + arithmetic authority), with thin display formatters on top. Arithmetic and
+* the `Money` type always come from primitives — this module never
+* re-implements them.
+*
+* ## The tenant seam is the ONE fork knob
+*
+* `@classytic/pos-ui` is a country-agnostic package: it is published under the
+* neutral `@classytic` scope and mounted by hosts in any jurisdiction. The
+* deployment's currency, locale and symbol therefore live in the three
+* constants below, env-driven with a BD default, exactly as
+* `commerce-ui/src/lib/tenant.ts` does it. A fork sets the env vars; it does
+* not edit code.
+*
+* ## Why the exported names are `Minor` / `Major`, never `Paisa` / `Bdt`
+*
+* This module used to export `Paisa`, `formatPaisa`, `formatPaisaPlain`,
+* `paisaToMoney`, `formatBdt` and `formatBdtFixed`. Every one of those is
+* currency-neutral arithmetic wearing a Bangladeshi name, and the names are
+* what the next author reads. A `formatBdt` in a package that claims to serve
+* any country reads as though the package knows what currency it holds — so a
+* USD deployment either believes it must fork, or calls `formatBdt` on dollars
+* and ships a function name that lies about the money in it.
+*
+* The subunit name belongs to the DEPLOYMENT (paisa for BDT, cents for USD,
+* fils for KWD). The package only ever knows "minor units" and "major units".
+* Hosts that want a local alias declare their own — `be-prod/src/shared/money.ts`
+* is the reference: it is the Bangladesh host, so `Paisa` is correct there.
+*/
+/**
+* Exported so callers that need the CURRENCY itself (a minor-unit factor, an
+* `Intl` call) read it from the seam instead of re-declaring a literal — a
+* second `"BDT"` elsewhere is a fork knob nobody knows to turn.
 */
 const TENANT_CURRENCY = "BDT";
-/** Cast a raw number to `Paisa`. Use at SDK boundaries when the response
-*  type isn't yet branded, or for arithmetic results that guarantee minor
-*  units. One cast per source — not per callsite. */
-function Paisa(n) {
-	return MinorUnits(n, TENANT_CURRENCY);
-}
-const TENANT_LOCALE = "en-BD";
-const TENANT_SYMBOL = "৳";
-/** Adapt a paisa (minor-unit) wire value into a structured `Money`. */
-function paisaToMoney(paisa, currency = TENANT_CURRENCY) {
-	return money(paisa, currency);
+const TENANT_LOCALE = process.env.NEXT_PUBLIC_LOCALE ?? "en-BD";
+/**
+* Exported so a LABEL or placeholder can name the currency without a literal.
+* `"Amount (BDT)"` hardcoded in JSX is the same defect as a `Paisa` type name:
+* it survives a fork silently and then lies to the cashier.
+*/
+const TENANT_CURRENCY_SYMBOL = process.env.NEXT_PUBLIC_CURRENCY_SYMBOL ?? "৳";
+const TENANT_SYMBOL = TENANT_CURRENCY_SYMBOL;
+/**
+* Cast a raw number to `TenantMinorUnits`. Use at SDK boundaries when the
+* response type isn't yet branded, or for arithmetic results that guarantee
+* minor units. One cast per source — not per callsite.
+*/
+function TenantMinorUnits(n) {
+	return MinorUnits(n, "BDT");
+}
+/** Adapt a minor-unit wire value into a structured `Money`. */
+function minorToMoney(minor, currency = "BDT") {
+	return money(minor, currency);
 }
 /** Canonical formatter — structured `Money` → `৳1,234.00`. */
 function formatMoney(m) {
@@ -28,14 +65,50 @@ function formatMoney(m) {
 		currency: m.currency
 	}).format(toMajor(m));
 }
-/** Format a wire-format paisa value: `formatPaisa(489900)` → `৳4,899.00`. */
-function formatPaisa(paisa, currency = TENANT_CURRENCY) {
-	return formatMoney(paisaToMoney(paisa, currency));
+/** Format a wire-format minor-unit value: `formatMinor(489900)` → `৳4,899.00`. */
+function formatMinor(minor, currency = "BDT") {
+	return formatMoney(minorToMoney(minor, currency));
+}
+/** Compact MAJOR-unit formatter, no forced decimals: `formatMajor(4899)` → `৳4,899`. */
+function formatMajor(amount) {
+	return `${TENANT_SYMBOL}${(Number.isFinite(amount) ? amount : 0).toLocaleString(TENANT_LOCALE)}`;
 }
-/** Compact major-unit formatter, no forced decimals: `formatBdt(4899)` → `৳4,899`. */
-function formatBdt(bdt) {
-	return `${TENANT_SYMBOL}${(Number.isFinite(bdt) ? bdt : 0).toLocaleString(TENANT_LOCALE)}`;
+/**
+* Minor units in ONE major unit of the tenant currency, from
+* `@classytic/primitives/currency` — never a hardcoded `100`. BDT/USD are 100,
+* KWD is 1000, JPY is 1, so any rate derived by dividing by a literal is wrong
+* for a third of the world.
+*/
+function minorPerMajorUnit(currency = "BDT") {
+	return minorUnitFactor(currency);
+}
+/**
+* Minor units -> major units, via the CURRENCY's factor.
+*
+* Replaces a hand-written `/ 100` at five call sites (variant absolute prices in the
+* cart and the variant dialog, cash counted at shift open/close, the hardware
+* adapter's amount). `100` is right for BDT and USD and wrong for KWD (1000) and JPY
+* (1) — and each site had derived it independently, so they could drift apart as
+* easily as they were all wrong together.
+*/
+function minorToMajor(minor, currency = "BDT") {
+	return toMajor(minorToMoney(Number.isFinite(minor) ? minor : 0, currency));
+}
+/**
+* Major units -> integer minor units.
+*
+* Rounds, because the input is typically a parsed decimal from an operator's keypad
+* and IEEE division leaves values like `4899.999999999999`. A truncating conversion
+* there loses a minor unit on ordinary amounts.
+*
+* The `currency` parameter exists to make the factor OBSERVABLE. Without it the tests
+* could not tell this apart from a hardcoded `100` — BDT's factor is 100, so
+* substituting the literal kept every assertion green. A guard that cannot fail for
+* the reason it exists is decoration; callers still omit the argument.
+*/
+function majorToMinor(major, currency = "BDT") {
+	return Math.round((Number.isFinite(major) ? major : 0) * minorUnitFactor(currency));
 }
 
 //#endregion
-export { Paisa, formatBdt, formatMoney, formatPaisa, paisaToMoney };
+export { TENANT_CURRENCY_SYMBOL, TenantMinorUnits, formatMajor, formatMinor, formatMoney, majorToMinor, minorPerMajorUnit, minorToMajor, minorToMoney, toMajor$1 as toMajor };