@mohasinac/appkit 4.59.0 → 4.60.0

package/dist/features/inventory/components/AdminStorageBoxesView.js

@@ -0,0 +1,168 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/*
+ * WHY: The box registry needs the same listing chrome every other admin
+ *      surface has — search, sort, pagination, a create affordance and a row
+ *      you can open — and `DataListingView` is that, for ~86 configs.
+ * WHAT: The config, plus the inline create drawer.
+ *
+ * @tag domain:inventory
+ * @tag layer:feature
+ * @tag access:client
+ */
+import React from "react";
+import { DataListingView, } from "../../admin/components/DataListingView.js";
+import { Button, Div, Form, FieldInput, FieldSelect, Stack, Text } from "../../../ui/index.js";
+import { ADMIN_ENDPOINTS } from "../../../constants/api-endpoints.js";
+import { apiClient } from "../../../http/index.js";
+import { sortBy } from "../../../constants/sort.js";
+import { sieveFilter, SIEVE_OP } from "../../../utils/sieve-builder.js";
+import { operatorMessage } from "./operator-message.js";
+import { BoxTypeValues } from "../schemas/firestore.js";
+const TYPE_OPTIONS = BoxTypeValues.map((v) => ({ value: v, label: v }));
+/**
+ * The register-a-box form.
+ *
+ * Exported because it is a PAGE now, not a drawer — see the note on
+ * `primaryAction` below for why create could not share the row affordance.
+ */
+export function RegisterBoxForm({ onCreated }) {
+    const [code, setCode] = React.useState("");
+    const [boxType, setBoxType] = React.useState(BoxTypeValues[0]);
+    const [location, setLocation] = React.useState("");
+    const [busy, setBusy] = React.useState(false);
+    return (_jsx(Form, { onSubmit: (e) => e.preventDefault(), className: "space-y-4", children: ({ setFieldError, clearErrors }) => (_jsxs(Stack, { gap: "md", children: [_jsx(FieldInput, { name: "code", label: "Box code", required: true, value: code, onChange: setCode, placeholder: "AC60-03", hint: "Exactly what is written on the physical label." }), _jsx(FieldSelect, { name: "boxType", label: "Box type", value: boxType, onChange: setBoxType, options: TYPE_OPTIONS }), _jsx(FieldInput, { name: "location", label: "Where it is", value: location, onChange: setLocation, placeholder: "Shelf B, second from top" }), _jsx(Text, { size: "xs", color: "muted", children: "A second box with the same code is the same box \u2014 the registry refuses a duplicate rather than merging two." }), _jsx(Div, { children: _jsx(Button, { type: "submit", variant: "primary", isLoading: busy, onClick: async () => {
+                            clearErrors();
+                            if (!code.trim()) {
+                                setFieldError("code", "A box needs a code");
+                                return;
+                            }
+                            setBusy(true);
+                            try {
+                                await apiClient.post(ADMIN_ENDPOINTS.INVENTORY_BOXES, {
+                                    code: code.trim(),
+                                    boxType,
+                                    ...(location.trim() ? { location: location.trim() } : {}),
+                                });
+                                onCreated();
+                            }
+                            catch (err) {
+                                /*
+                                 * 🛑 `operatorMessage`, not a raw fallback. This read
+                                 * `toUserMessage(undefined, undefined, { fallback: e.message })`
+                                 * under a comment claiming it never showed server text —
+                                 * which is false twice over: `undefined` for the code means
+                                 * the map never runs, so the fallback is ALWAYS what shows.
+                                 * A comment asserting the fix while the code reintroduces the
+                                 * bug is how Root Cause #86 would come back, and how the seed
+                                 * `listingType` bug survived its own fix one field over.
+                                 *
+                                 * The split is on status: the 409 here ("Box AC60-03 already
+                                 * exists") is authored for this operator and must survive; a
+                                 * 5xx terminates in a constant.
+                                 */
+                                setFieldError("code", operatorMessage(err));
+                            }
+                            finally {
+                                setBusy(false);
+                            }
+                        }, children: "Register box" }) })] })) }));
+}
+export function AdminStorageBoxesView() {
+    const config = React.useMemo(() => ({
+        portal: "admin",
+        title: "Storage Boxes",
+        subtitle: "The physical AC60 and AC30 boxes, and what is in each one. A box is here because somebody labelled it.",
+        /*
+         * `search.fields` names what the index actually matches — `searchTxt` is
+         * built from the code, the type and the location, and nothing else. A
+         * placeholder promising more is the empty-list lie the admin products
+         * toolbar was making about SKUs.
+         */
+        search: {
+            placeholder: "Search by code or location",
+            fields: ["code", "boxType", "location"],
+        },
+        emptyLabel: "No boxes registered yet",
+        filterKeys: ["status", "boxType"],
+        /*
+         * 🛑 REQUIRED — see the long note in `AdminMoveLedgerView`. Its absence
+         * threw `TypeError: buildFilters is not a function` during render, so
+         * `/admin/inventory/boxes` never painted.
+         *
+         * Joined with "," because sievejs reads a comma as AND: status AND
+         * boxType, which is what two independent chip groups mean. A "|" would
+         * be an OR-group on ONE field and is what `sieveMultiEq` is for —
+         * getting that backwards is how a filter silently widens instead of
+         * narrowing.
+         */
+        buildFilters: (state) => {
+            const parts = [];
+            if (state.status)
+                parts.push(sieveFilter("status", SIEVE_OP.EQ, state.status));
+            if (state.boxType)
+                parts.push(sieveFilter("boxType", SIEVE_OP.EQ, state.boxType));
+            return parts.join(",") || undefined;
+        },
+        /*
+         * Sorted by `ordinal`, not `code`. A string sort puts AC60-10 before
+         * AC60-2 — the kind of ordering that makes an operator distrust the
+         * screen — which is why `ordinal` is denormalised on write.
+         */
+        defaultSort: "ordinal",
+        sortOptions: [
+            { value: "ordinal", label: "Box number" },
+            { value: sortBy("createdAt", "DESC"), label: "Newest" },
+            { value: sortBy("code", "ASC"), label: "Code A–Z" },
+        ],
+        queryKey: ["admin", "inventory", "boxes"],
+        endpoint: ADMIN_ENDPOINTS.INVENTORY_BOXES,
+        mapRows: (response) => (response.items ?? []).map((box) => ({
+            id: box.id,
+            primary: box.code,
+            secondary: [
+                box.boxType,
+                box.location,
+                /*
+                 * The ADVISORY rollup, labelled as of its own timestamp rather
+                 * than presented as live. A scheduled job writes it, so a box
+                 * that changed an hour ago reads stale — saying "as of" is the
+                 * difference between a cache and a lie.
+                 */
+                box.rollup
+                    ? `${box.rollup.totalUnits} units in ${box.rollup.distinctProducts} products`
+                    : "not yet counted",
+            ]
+                .filter(Boolean)
+                .join(" · "),
+            status: box.status,
+            updatedAt: box.updatedAt ? String(box.updatedAt) : "",
+        })),
+        /*
+         * A real detail page, so `DataListingView` gives every row the direct
+         * edit affordance it composes — and a middle-clickable link, which is
+         * how an operator opens three boxes to compare them.
+         */
+        rowHrefTemplate: "/admin/inventory/boxes/{id}",
+        /*
+         * 🛑 `href`, NOT `renderEditor`, and the two are mutually exclusive
+         * here for a reason I nearly got wrong.
+         *
+         * `DataListingView` resolves its row affordances in the order
+         * `onRowClick` → `renderEditor` → `rowHrefTemplate`. So a config
+         * carrying BOTH a create drawer and a row href gets the drawer on every
+         * row: the pencil calls `openEditPanel(row.id)` and a create form that
+         * ignores the id opens, presented as an edit of that box. A create form
+         * reached through an edit affordance is the clickable-card lie in a new
+         * shape.
+         *
+         * So create is a PAGE (`primaryAction.href`, which exists for exactly
+         * this per the config's own docs) and the row href is the detail page.
+         * Registering a box is also not a one-field drawer job — it is the
+         * moment the code is chosen, and the code is immutable afterwards
+         * because the document id derives from it.
+         */
+        primaryAction: { label: "Register box", href: "/admin/inventory/boxes/new" },
+    }), []);
+    return _jsx(DataListingView, { config: config });
+}

package/dist/features/inventory/components/ReceiveStationView.d.ts

@@ -0,0 +1,39 @@
+/** A shipment item that can actually be received — i.e. one that is linked. */
+export interface ReceivableItem {
+    itemId: string;
+    productId: string;
+    productTitle: string;
+    /**
+     * 🛑 THE MACHINE KEY, and what a scan actually produces. `id-generators.ts`'s
+     * reconciliation header is explicit that `barcodeId` is "what a CODE128
+     * symbol encodes and what a scan resolves" while `sku` is the human key —
+     * so a station indexed on `sku` alone would fail to recognise its own
+     * printed labels. I built it that way first.
+     */
+    barcodeId: string | null;
+    /** The human key. Accepted too, because an operator reads and types this. */
+    sku: string | null;
+    /** What the shipment says arrived, for the operator to count against. */
+    expectedQuantity: number;
+}
+/** An item with no `linkedProductId` — nameable, but not receivable. */
+export interface UnlinkedItem {
+    itemId: string;
+    lotId: string;
+    title: string;
+}
+export interface BoxOption {
+    id: string;
+    code: string;
+    location: string | null;
+}
+export interface ReceiveStationViewProps {
+    shipmentId: string;
+    shipmentNumber: string;
+    items: ReceivableItem[];
+    unlinked: UnlinkedItem[];
+    boxes: BoxOption[];
+    itemsFailed: boolean;
+    boxesFailed: boolean;
+}
+export declare function ReceiveStationView({ shipmentId, shipmentNumber, items, unlinked, boxes, itemsFailed, boxesFailed, }: ReceiveStationViewProps): import("react").JSX.Element;

package/dist/features/inventory/components/ReceiveStationView.js

@@ -0,0 +1,413 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * The receive station — a scan loop that ends in one commit.
+ *
+ * A crate arrives, someone opens it, and for the next twenty minutes their
+ * hands are full and their eyes are on the item, not the screen. Everything
+ * here follows from that.
+ *
+ * THE LOOP:  scan `BOX-AC60-03` → that box is ARMED
+ *            scan `LIR-DRAN-4F2A1` → one unit of that product staged into it
+ *            scan it again → the same row increments
+ *            scan another `BOX-…` → the armed box changes, rows keep theirs
+ *            press Commit → the whole table lands in one transaction
+ *
+ * 🛑 ARMING IS WHAT MAKES THIS WORTH BUILDING. Thirty items into one box is
+ * thirty-one scans, not sixty. A station that asked for the box every time
+ * would be slower than a clipboard, which is what it is replacing.
+ *
+ * 🛑 RECEIVING NEVER TOUCHES `stockQuantity`. The shipment-link route already
+ * does, and doing both double-counts. This answers "where is it", never "how
+ * many exist".
+ */
+import { useEffect, useMemo, useRef, useState } from "react";
+import { Alert, Badge, Button, Card, CardBody, Div, Heading, Row, Stack, Table, Tbody, Td, Text, TextLink, Th, Thead, Tr, } from "../../../ui/index.js";
+import { QuantityStepper } from "../../../ui/components/QuantityStepper.js";
+import { FieldInput } from "../../../ui/forms/index.js";
+import { Form } from "../../../ui/components/Form.js";
+import { useToast } from "../../../ui/components/Toast.js";
+import { apiClient } from "../../../http/index.js";
+import { ADMIN_ENDPOINTS } from "../../../constants/api-endpoints.js";
+import { ROUTES } from "../../../next/routing/route-map.js";
+import { operatorMessage } from "./operator-message.js";
+import { MAX_RECEIVE_ROWS } from "../schemas/firestore.js";
+/** `boxId::productId` — the staging table's natural key, mirroring `placementId`. */
+function rowKey(boxId, productId) {
+    return `${boxId}::${productId}`;
+}
+export function ReceiveStationView({ shipmentId, shipmentNumber, items, unlinked, boxes, itemsFailed, boxesFailed, }) {
+    const { showToast } = useToast();
+    const [armed, setArmed] = useState(null);
+    const [rows, setRows] = useState({});
+    /*
+     * 🛑 THE REF IS THE AUTHORITY; `rows` only renders.
+     *
+     * Two reasons, and the second is a correctness bug I wrote before noticing.
+     *
+     * 1. A scanner types faster than React re-renders. Two `LIR-…` scans can
+     *    both submit before a single render commits, and a handler reading the
+     *    state `rows` from its closure would see the pre-first-scan value for
+     *    both — the second overwrites the first and one item silently vanishes
+     *    from the table while the operator's echo says it landed twice.
+     *
+     * 2. A `setRows(prev => …)` updater does NOT run synchronously. It is
+     *    evaluated during the next render, so `stage()` cannot learn from it
+     *    whether it actually staged anything — a flag mutated inside the updater
+     *    is still `false` when `stage()` returns, which made every refused scan
+     *    report success.
+     *
+     * Writing the ref first and passing a plain value to `setRows` makes both
+     * problems go away: the decision is always against the real current table.
+     */
+    const rowsRef = useRef({});
+    /** Mutates the authoritative table and schedules the render. */
+    function applyRows(next) {
+        const computed = next(rowsRef.current);
+        rowsRef.current = computed;
+        setRows(computed);
+    }
+    const [scan, setScan] = useState("");
+    const [committing, setCommitting] = useState(false);
+    /** The in-flight guard. State renders the spinner; this prevents the second send. */
+    const committingRef = useRef(false);
+    /*
+     * The last scan, echoed large. A toast per scan would be thirty toasts
+     * stacked over the table, and the operator is not reading them — they need
+     * one glance to confirm the beep meant something.
+     */
+    const [lastScan, setLastScan] = useState(null);
+    const scanRef = useRef(null);
+    /*
+     * ONE index, keyed by both codes.
+     *
+     * `barcodeId` is what the symbol on the label encodes; `sku` is what is
+     * printed beneath it in human-readable text. An operator with a peeled or
+     * smudged label types the SKU, so refusing it would make the station useless
+     * for exactly the items most likely to need typing. Both resolve to the same
+     * product, so accepting both costs nothing and the ambiguity is only
+     * apparent — the two formats cannot collide (`LIR-XXXXXXXX`, two segments
+     * of fixed width, versus `LIR-TOKEN-SUFFIX`, three).
+     */
+    const byCode = useMemo(() => {
+        const m = new Map();
+        for (const it of items) {
+            if (it.barcodeId)
+                m.set(it.barcodeId.toUpperCase(), it);
+            if (it.sku)
+                m.set(it.sku.toUpperCase(), it);
+        }
+        return m;
+    }, [items]);
+    /*
+     * 🛑 Box codes are matched WITH AND WITHOUT the `BOX-` prefix.
+     *
+     * The stored `code` is `AC60-03` (`generateStorageBoxId` slugifies exactly
+     * that) while the printed label's symbol encodes `BOX-AC60-03` — the prefix
+     * exists so the station knows what KIND of thing it just read without a
+     * lookup. Indexing only the stored spelling would mean the station does not
+     * recognise the labels this project prints, which is the same mistake as
+     * indexing items on `sku`.
+     */
+    const byBoxCode = useMemo(() => {
+        const m = new Map();
+        for (const b of boxes) {
+            const code = b.code.toUpperCase();
+            m.set(code, b);
+            m.set(`BOX-${code}`, b);
+        }
+        return m;
+    }, [boxes]);
+    const staged = Object.values(rows);
+    const atCap = staged.length >= MAX_RECEIVE_ROWS;
+    const totalUnits = staged.reduce((n, r) => n + r.quantity, 0);
+    /*
+     * 🛑 THE FIELD IS RE-FOCUSED AFTER EVERY SCAN AND EVERY ROW EDIT.
+     *
+     * A barcode scanner is a keyboard that types very fast and presses Enter.
+     * If focus has moved — because the operator nudged a stepper, or a toast
+     * took it, or they clicked the table — the barcode goes wherever focus is:
+     * into a quantity box as digits, or nowhere at all. Nothing on screen says
+     * so, and the operator has already put the item in the box. That is the
+     * failure this effect exists to prevent, and it is why the dependency list
+     * includes the row count.
+     */
+    useEffect(() => {
+        scanRef.current?.focus();
+    }, [lastScan, staged.length, armed?.id]);
+    /**
+     * Stages one unit, and REPORTS WHETHER IT DID.
+     *
+     * 🛑 THE RETURN VALUE IS THE POINT. This used to return void and bail with a
+     * bare `return prev` at the cap, while every caller announced "+1 …" the
+     * moment it had called — so a refused scan rendered as a successful one. At
+     * a station where the operator trusts the echo instead of re-reading the
+     * table, that is the single worst bug this screen could have: the item is
+     * physically in the box and the record says it is not.
+     *
+     * The cap is checked against `rowsRef`, never the caller's `atCap`: that
+     * value comes from the last render and a scanner fires two submits before
+     * React commits one, so it is routinely a row stale. The ref is the only
+     * authority. `atCap` survives solely to render the informational notice,
+     * where being one render behind costs nothing.
+     */
+    function stage(item, box, by = 1) {
+        const key = rowKey(box.id, item.productId);
+        const current = rowsRef.current;
+        const existing = current[key];
+        /*
+         * 🛑 A REPEAT SCAN INCREMENTS; it does not add a second row. Twenty scans
+         * of one product would otherwise be twenty rows, and the 50-row
+         * transaction ceiling would be hit by a single item while the operator
+         * thinks they have barely started. An increment is therefore allowed even
+         * at the cap — it adds no row.
+         */
+        if (existing) {
+            applyRows((c) => ({
+                ...c,
+                [key]: { ...existing, quantity: existing.quantity + by },
+            }));
+            return true;
+        }
+        // A NEW row at the cap is refused, and the caller is told so.
+        if (Object.keys(current).length >= MAX_RECEIVE_ROWS)
+            return false;
+        applyRows((c) => ({
+            ...c,
+            [key]: {
+                boxId: box.id,
+                boxCode: box.code,
+                productId: item.productId,
+                productTitle: item.productTitle,
+                code: item.barcodeId ?? item.sku,
+                quantity: by,
+            },
+        }));
+        return true;
+    }
+    /**
+     * A box the prefetched list does not contain, resolved from the server.
+     *
+     * 🛑 THIS EXISTS BECAUSE THE PREFETCHED LIST IS CAPPED AT 50 (Rule #6 — every
+     * list endpoint paginates). Without this, registering a 51st box produces a
+     * station that reads its label, finds nothing, and says "unrecognised code"
+     * about a box that plainly exists — the silent-ceiling failure this codebase
+     * keeps paying for, where a bounded read is mistaken for the whole set.
+     *
+     * It runs only on a miss, so the common case stays instant and a box-arm is
+     * roughly one scan in twenty anyway.
+     */
+    async function resolveBoxFromServer(code) {
+        const bare = code.startsWith("BOX-") ? code.slice(4) : code;
+        try {
+            const res = await apiClient.get(`${ADMIN_ENDPOINTS.INVENTORY_BOXES}?filters=code==${encodeURIComponent(bare)}&pageSize=1`);
+            const hit = res?.items?.[0];
+            return hit
+                ? { id: hit.id, code: hit.code, location: hit.location ?? null }
+                : null;
+        }
+        catch {
+            // A failed lookup must not masquerade as "no such box" — the caller
+            // distinguishes the two in what it tells the operator.
+            return null;
+        }
+    }
+    async function handleScan(raw) {
+        const code = raw.trim().toUpperCase();
+        setScan("");
+        if (!code)
+            return;
+        const box = byBoxCode.get(code);
+        if (box) {
+            setArmed(box);
+            setLastScan({ text: `Armed ${box.code}`, tone: "ok" });
+            return;
+        }
+        /*
+         * A `BOX-` prefix is an unambiguous declaration of intent, so a miss here
+         * is worth a round trip rather than an "unrecognised code" — the operator
+         * is holding a box with a label this project printed.
+         */
+        if (code.startsWith("BOX-")) {
+            const fetched = await resolveBoxFromServer(code);
+            if (fetched) {
+                setArmed(fetched);
+                setLastScan({ text: `Armed ${fetched.code}`, tone: "ok" });
+                return;
+            }
+            setLastScan({
+                text: `No box registered as ${code.slice(4)} — register it first`,
+                tone: "bad",
+            });
+            return;
+        }
+        const item = byCode.get(code);
+        if (item) {
+            if (!armed) {
+                /*
+                 * 🛑 REFUSED, not staged into a guessed box. Defaulting to "the last
+                 * box" or "the only box" would put stock somewhere nobody chose, and
+                 * a placement is only worth having if it is where the thing actually
+                 * is. The operator loses one scan; a wrong shelf loses the item.
+                 */
+                setLastScan({
+                    text: `No box armed — scan a box code before ${item.productTitle}`,
+                    tone: "bad",
+                });
+                return;
+            }
+            /*
+             * 🛑 THE ECHO FOLLOWS WHAT `stage` ACTUALLY DID. There is no pre-check
+             * against `atCap` here any more: that value comes from the last render
+             * and a scanner outruns it, so a scan could be refused by `stage`'s
+             * authoritative check and still echo "+1". `stage` owns the decision
+             * and reports it; this only phrases it.
+             */
+            if (stage(item, armed)) {
+                setLastScan({
+                    text: `+1 ${item.productTitle} → ${armed.code}`,
+                    tone: "ok",
+                });
+            }
+            else {
+                setLastScan({
+                    text: `Table is full at ${MAX_RECEIVE_ROWS} rows — commit, then carry on`,
+                    tone: "bad",
+                });
+            }
+            return;
+        }
+        /*
+         * 🛑 AN UNKNOWN CODE IS AN ERROR, NEVER A NO-OP. Clearing the field and
+         * saying nothing is the worst available behaviour: the operator hears the
+         * scanner beep, sees the field empty, and assumes it counted. This is the
+         * one case that also gets a toast, because it is rare and does need eyes.
+         */
+        setLastScan({ text: `Unrecognised code: ${code}`, tone: "bad" });
+        showToast(`${code} is not a box code or a SKU in this shipment. Check the label, or add the item by hand below.`, "error");
+    }
+    async function commit() {
+        /*
+         * 🛑 SENT FROM THE REF, not the rendered `staged`. Pressing Commit
+         * immediately after the last scan — which is exactly what an operator
+         * does — can run this handler before the render carrying that scan has
+         * committed, and the rendered array would then be one row short. The
+         * dropped row is the last thing scanned, so it is also the one the
+         * operator remembers putting in the box.
+         */
+        /*
+         * 🛑 A REF GUARD, even though `<Button isLoading>` already sets
+         * `disabled` and refuses its own click handler. Both of those read the
+         * `committing` STATE, which is one render stale — and the cost of the gap
+         * here is not a wasted request, it is the entire crate received twice,
+         * with a second ledger row per item saying it arrived again. Two lines
+         * against a double-counted shipment is not a close call.
+         */
+        if (committingRef.current)
+            return;
+        const sending = Object.values(rowsRef.current);
+        if (sending.length === 0)
+            return;
+        committingRef.current = true;
+        setCommitting(true);
+        try {
+            const res = await apiClient.post(ADMIN_ENDPOINTS.INVENTORY_RECEIVE, {
+                shipmentId,
+                rows: sending.map((r) => ({
+                    boxId: r.boxId,
+                    productId: r.productId,
+                    quantity: r.quantity,
+                })),
+            });
+            /*
+             * The SERVER's counts are quoted when it returns them. It is the only
+             * party that knows what actually landed, and `sending` is merely what we
+             * asked for — reporting our own request back as a result is how a UI
+             * ends up confidently describing a write that differed.
+             */
+            const units = sending.reduce((n, r) => n + r.quantity, 0);
+            showToast(`Received ${res?.units ?? units} units across ${res?.rows ?? sending.length} rows`, "success");
+            /*
+             * 🛑 ONLY THE SENT ROWS ARE REMOVED — not the whole table.
+             *
+             * The scan field keeps focus through the request, so the operator
+             * carries on scanning while it is in flight; that is the designed
+             * behaviour, not an edge case. A blanket clear would throw those scans
+             * away, and they are the ones nobody can reconstruct — the items are
+             * already in the boxes and the echo said they counted.
+             *
+             * The quantity is compared, not just the key: a row scanned again
+             * mid-flight has a HIGHER quantity than what was sent, so the delta has
+             * to survive. Subtracting what was sent and keeping the remainder is the
+             * only version that neither loses nor double-counts.
+             *
+             * Cleared only on success. A failed commit keeps the table exactly as it
+             * was — the server refused as a unit, so nothing landed.
+             */
+            applyRows((c) => {
+                const next = { ...c };
+                for (const r of sending) {
+                    const key = rowKey(r.boxId, r.productId);
+                    const live = next[key];
+                    if (!live)
+                        continue;
+                    const remainder = live.quantity - r.quantity;
+                    if (remainder > 0)
+                        next[key] = { ...live, quantity: remainder };
+                    else
+                        delete next[key];
+                }
+                return next;
+            });
+            setLastScan({ text: "Committed. Carry on.", tone: "ok" });
+        }
+        catch (err) {
+            showToast(operatorMessage(err), "error");
+        }
+        finally {
+            committingRef.current = false;
+            setCommitting(false);
+        }
+    }
+    return (_jsxs(Stack, { gap: "comfortable", children: [_jsxs(Div, { children: [_jsx(Heading, { level: 1, size: "2xl", children: "Receive into boxes" }), _jsxs(Text, { color: "muted", children: ["Shipment ", shipmentNumber, ". Scan a box code to arm it, then scan items."] })] }), boxesFailed && (_jsx(Alert, { variant: "warning", children: "Could not load the box list. Scanning a box code will not arm anything until this page is reloaded \u2014 the list is unknown, not empty." })), itemsFailed && (_jsx(Alert, { variant: "warning", children: "Could not load this shipment's items. Scanning a SKU will not match anything until this page is reloaded." })), !boxesFailed && boxes.length === 0 && (_jsx(Alert, { variant: "warning", children: "There are no storage boxes registered yet. Register one before receiving \u2014 stock has to go somewhere named." })), _jsx(Card, { variant: armed ? "default" : "outlined", children: _jsx(CardBody, { children: _jsxs(Row, { align: "center", justify: "between", gap: "md", wrap: true, children: [_jsxs(Div, { children: [_jsx(Text, { size: "xs", color: "muted", transform: "uppercase", children: "Armed box" }), armed ? (_jsxs(Row, { align: "center", gap: "sm", children: [_jsx(Heading, { level: 2, size: "2xl", children: armed.code }), armed.location && (_jsx(Badge, { variant: "info", children: armed.location }))] })) : (_jsx(Heading, { level: 2, size: "xl", color: "muted", children: "Nothing armed \u2014 scan a box code" }))] }), armed && (_jsx(Button, { variant: "ghost", onClick: () => setArmed(null), children: "Disarm" }))] }) }) }), _jsx(Card, { variant: "default", children: _jsxs(CardBody, { children: [_jsx(Form, { onSubmit: (e) => {
+                                e.preventDefault();
+                                void handleScan(scan);
+                            }, children: _jsx(FieldInput, { name: "scan", label: "Scan", 
+                                // `inputRef`, not `ref` — see FieldInput's own note on why the
+                                // inner control is named rather than implied.
+                                inputRef: scanRef, value: scan, onChange: setScan, autoComplete: "off", placeholder: "BOX-\u2026 to arm a box \u00B7 LIR-\u2026 to add an item", hint: armed
+                                    ? `Items scanned now go into ${armed.code}`
+                                    : "Scan a box code first" }) }), lastScan && (_jsx(Div, { children: _jsx(Text, { size: "lg", weight: "semibold", color: lastScan.tone === "ok" ? "success" : "error", role: "status", "aria-live": "polite", children: lastScan.text }) }))] }) }), _jsx(Card, { variant: "default", children: _jsxs(CardBody, { children: [_jsxs(Row, { align: "center", justify: "between", wrap: true, gap: "sm", children: [_jsxs(Heading, { level: 2, size: "lg", children: ["Staged (", staged.length, "/", MAX_RECEIVE_ROWS, ")"] }), _jsxs(Row, { align: "center", gap: "sm", children: [_jsxs(Text, { size: "sm", color: "muted", children: [totalUnits, " unit", totalUnits === 1 ? "" : "s"] }), _jsxs(Button, { variant: "primary", isLoading: committing, disabled: staged.length === 0, onClick: () => void commit(), children: ["Commit ", staged.length > 0 ? `${staged.length} rows` : ""] })] })] }), atCap && (_jsxs(Alert, { variant: "info", children: [MAX_RECEIVE_ROWS, " rows is one transaction's worth. Commit these, then keep scanning \u2014 a bigger table would have to be written in pieces, and a half-received crate is worse than two commits."] })), staged.length === 0 ? (_jsx(Text, { color: "muted", children: "Nothing staged. Scan a box, then scan items into it." })) : (_jsxs(Table, { children: [_jsx(Thead, { children: _jsxs(Tr, { children: [_jsx(Th, { children: "Box" }), _jsx(Th, { children: "Product" }), _jsx(Th, { children: "Code" }), _jsx(Th, { children: "Qty" }), _jsx(Th, { children: "Remove" })] }) }), _jsx(Tbody, { children: staged.map((r) => {
+                                        const key = rowKey(r.boxId, r.productId);
+                                        return (_jsxs(Tr, { children: [_jsx(Td, { children: _jsx(Badge, { variant: "info", children: r.boxCode }) }), _jsx(Td, { children: r.productTitle }), _jsx(Td, { children: _jsx(Text, { numeric: true, size: "sm", children: r.code ?? "—" }) }), _jsx(Td, { children: _jsx(QuantityStepper, { value: r.quantity, min: 1, max: 9999, 
+                                                        // Many steppers on one page, so a bare "Quantity"
+                                                        // names none of them.
+                                                        ariaLabel: `Quantity of ${r.productTitle} for ${r.boxCode}`, onChange: (n) => applyRows((c) => ({
+                                                            ...c,
+                                                            [key]: { ...c[key], quantity: n },
+                                                        })) }) }), _jsx(Td, { children: _jsx(Button, { variant: "ghost", onClick: () => applyRows((c) => {
+                                                            const next = { ...c };
+                                                            delete next[key];
+                                                            return next;
+                                                        }), children: "Remove" }) })] }, key));
+                                    }) })] }))] }) }), _jsx(Card, { variant: "default", children: _jsxs(CardBody, { children: [_jsx(Heading, { level: 2, size: "lg", children: "Add by hand" }), items.length === 0 ? (_jsx(Text, { color: "muted", children: "No linked items on this shipment yet." })) : (_jsxs(Table, { children: [_jsx(Thead, { children: _jsxs(Tr, { children: [_jsx(Th, { children: "Item" }), _jsx(Th, { children: "Scan code" }), _jsx(Th, { children: "Expected" }), _jsx(Th, { children: "Add" })] }) }), _jsx(Tbody, { children: items.map((it) => (_jsxs(Tr, { children: [_jsx(Td, { children: it.productTitle }), _jsx(Td, { children: _jsx(Text, { numeric: true, size: "sm", children: it.barcodeId ??
+                                                        it.sku ??
+                                                        "no code yet — add by hand, or run the SKU backfill" }) }), _jsx(Td, { children: it.expectedQuantity }), _jsx(Td, { children: _jsx(Button, { variant: "outline", 
+                                                    // Disabled only for the one condition that is stable
+                                                    // between renders. The cap is `stage`'s call, and it
+                                                    // reports — the same reasoning as the scan path.
+                                                    disabled: !armed, onClick: () => {
+                                                        if (!armed)
+                                                            return;
+                                                        const ok = stage(it, armed);
+                                                        setLastScan(ok
+                                                            ? {
+                                                                text: `+1 ${it.productTitle} → ${armed.code}`,
+                                                                tone: "ok",
+                                                            }
+                                                            : {
+                                                                text: `Table is full at ${MAX_RECEIVE_ROWS} rows — commit first`,
+                                                                tone: "bad",
+                                                            });
+                                                    }, children: armed ? `Into ${armed.code}` : "Arm a box first" }) })] }, it.itemId))) })] }))] }) }), unlinked.length > 0 && (_jsxs(Alert, { variant: "warning", children: [_jsxs(Text, { weight: "semibold", children: [unlinked.length, " item", unlinked.length === 1 ? "" : "s", " cannot be received yet"] }), _jsx(Text, { size: "sm", children: "A box placement records a product, so each of these needs linking to a listing first:" }), _jsx(Stack, { gap: "xs", children: unlinked.map((u) => (_jsxs(Text, { size: "sm", children: ["\u00B7 ", u.title, " \u2014", " ", _jsx(TextLink, { href: String(ROUTES.ADMIN.SHIPMENT_LOT_ITEMS(shipmentId, u.lotId)), children: "link it in its lot" })] }, u.itemId))) })] }))] }));
+}

package/dist/features/inventory/components/operator-message.d.ts

@@ -0,0 +1,29 @@
+/**
+ * A failed inventory write, as something an operator can act on.
+ *
+ * 🛑 THIS EXISTS BECAUSE `toUserMessage(undefined, undefined, { fallback })`
+ * IS THE `?? error` ANTI-PATTERN. Passing `undefined` for the code means the
+ * mapping never runs and the server's own message is always what shows — which
+ * is precisely the bug Rule #9 records: an unmapped failure printed server
+ * internals to the user, and a Node `MODULE_NOT_FOUND` with a require stack was
+ * rendered inside a modal. I wrote that call before noticing.
+ *
+ * But the inventory screens genuinely need the server's words for the 4xx
+ * cases, and that is not a contradiction. "AC60-03 is retired", "holds 2,
+ * cannot move 5" and "duplicate box code" are messages written FOR the
+ * operator, naming the box and the count, and they tell them what to do next.
+ * `GENERIC_USER_MESSAGE` in their place turns a recoverable mistake into a
+ * mystery at a station where someone is holding the physical item.
+ *
+ * So the rule is split on STATUS, which is the thing that actually
+ * distinguishes the two:
+ *
+ * · 4xx — deliberate, authored, operator-facing. Show it.
+ * · 5xx (and anything with no status) — unplanned. Route through the code map,
+ *   which terminates in a constant and never returns server text. `mapToHttpError`
+ *   also scrubs 5xx messages in production, so the server text may well already
+ *   be generic by the time it arrives — but relying on that would make this
+ *   correct only in production, and the station is also used against a local
+ *   server.
+ */
+export declare function operatorMessage(err: unknown, t?: (key: string) => string): string;