@mohasinac/appkit 4.14.0 → 4.15.0

package/dist/features/seller/components/OfferPhaseTimeline.js

@@ -0,0 +1,107 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * OfferPhaseTimeline — the offer-shaped wrapper around `<StatusTimeline>`.
+ *
+ * An offer is an order with more phases in front of it, so it shares the rail
+ * and supplies only its own vocabulary:
+ *
+ *   made → countered → accepted → paid
+ *   with declined / withdrawn / expired as the terminal-negative branch
+ *
+ * ## `superseded` is a RENDER KEY, never an OfferStatus
+ *
+ * A document that is `withdrawn` **and** carries `supersededByOfferId` is not
+ * a walk-away — the buyer countered, and the negotiation continued into the
+ * next round. It renders neutral ("Superseded"), not negative ("Withdrawn").
+ *
+ * Deliberately NOT an eighth `OfferStatus` value: `ADMIN_OFFER_STATUS_TABS`
+ * would then gain a chip that matches zero stored rows, which is exactly the
+ * defect `audit-filter-tab-enums` exists to catch.
+ *
+ * ## Back-compat
+ *
+ * Offers written before `statusHistory` existed have none. Branch B derives
+ * what it can from the scalars — and `expired` gets **no date at all**,
+ * because `expireMany` never wrote one. `updatedAt` is "last write of any
+ * kind" and `expiresAt` is a deadline, not an event; using either would be a
+ * fabricated timestamp.
+ */
+import { StatusTimeline, stepsFromEntries, } from "../../status-history/components/StatusTimeline";
+const PHASE_LABELS = {
+    pending: "Offer made",
+    countered: "Countered",
+    accepted: "Accepted",
+    paid: "Paid",
+    declined: "Declined",
+    withdrawn: "Withdrawn",
+    expired: "Expired",
+    superseded: "Superseded",
+};
+const NEGATIVE = new Set(["declined", "withdrawn", "expired"]);
+const labelFor = (status) => PHASE_LABELS[status] ?? status;
+const isNegative = (status) => NEGATIVE.has(status);
+/** Branch B — scalars only, for offers with no recorded history. */
+function buildLegacySteps(o) {
+    const steps = [
+        { key: "pending", label: PHASE_LABELS.pending, date: o.createdAt },
+    ];
+    const s = (o.status ?? "").toLowerCase();
+    if (s === "countered") {
+        steps.push({ key: "countered", label: PHASE_LABELS.countered, date: o.respondedAt });
+    }
+    if (s === "accepted" || s === "paid") {
+        steps.push({
+            key: "accepted",
+            label: PHASE_LABELS.accepted,
+            date: o.acceptedAt ?? o.respondedAt,
+        });
+    }
+    if (s === "paid") {
+        steps.push({ key: "paid", label: PHASE_LABELS.paid, date: o.paidAt });
+    }
+    if (s === "declined") {
+        steps.push({ key: "declined", label: PHASE_LABELS.declined, date: o.respondedAt, negative: true });
+    }
+    if (s === "withdrawn") {
+        steps.push(o.superseded
+            ? { key: "superseded", label: PHASE_LABELS.superseded, date: o.respondedAt, muted: true }
+            : { key: "withdrawn", label: PHASE_LABELS.withdrawn, date: o.respondedAt, negative: true });
+    }
+    if (s === "expired") {
+        // No date, on purpose. `expireMany` never wrote one before W2.
+        steps.push({ key: "expired", label: PHASE_LABELS.expired, negative: true });
+    }
+    return steps;
+}
+/** Re-key a withdrawn+superseded step so it reads neutral, not negative. */
+function applySupersede(steps, superseded) {
+    if (!superseded)
+        return steps;
+    return steps.map((s) => s.key === "withdrawn"
+        ? { ...s, key: "superseded", label: PHASE_LABELS.superseded, negative: false, muted: true }
+        : s);
+}
+export function OfferPhaseTimeline({ status, timeline, timelineTruncated, superseded = false, createdAt, respondedAt, acceptedAt, paidAt, chain, className = "", }) {
+    const own = applySupersede(stepsFromEntries(timeline, labelFor, isNegative).length
+        ? stepsFromEntries(timeline, labelFor, isNegative)
+        : buildLegacySteps({ status, createdAt, respondedAt, acceptedAt, paidAt, superseded }), superseded);
+    const priorRounds = (chain ?? []).filter((r) => r.id !== undefined);
+    const hasChain = priorRounds.length > 1;
+    const steps = hasChain
+        ? priorRounds.flatMap((round, idx) => {
+            const roundSteps = applySupersede(buildLegacySteps({
+                status: round.status,
+                createdAt: round.createdAt,
+                respondedAt: round.respondedAt,
+                superseded: round.superseded,
+            }), round.superseded);
+            return roundSteps.map((s, i) => ({
+                ...s,
+                roundLabel: i === 0 ? `Round ${round.counterRound || idx + 1}` : undefined,
+                note: i === roundSteps.length - 1 ? (round.sellerNote ?? round.buyerNote) : undefined,
+            }));
+        })
+        : own;
+    return (_jsx(StatusTimeline, { title: hasChain ? "Negotiation" : "Offer history", steps: steps, truncatedCount: timelineTruncated, emptyLabel: "No offer history yet", className: className }));
+}

package/dist/features/seller/components/SellerBidsView.js

@@ -1,10 +1,11 @@
 "use client";
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { normalizeError } from "../../../errors/normalize";
 import { SIEVE_OP, Stack, sieveFilter } from "@mohasinac/appkit/client";
 import { sortBy } from "@mohasinac/appkit/client";
 import { useState, useCallback } from "react";
-import { Badge, Button, Div, FilterChipGroup, Span, Text, useToast } from "../../../ui";
+import { Badge, Button, Div, FilterChipGroup, RecordDetailModal, Span, Text, useToast } from "../../../ui";
+import { buildBidDetailFields, bidStatusBadge } from "../../auctions/components/bid-detail-fields";
 import { SELLER_ENDPOINTS } from "../../../constants/api-endpoints";
 import { ACTIONS } from "../../../_internal/shared/actions/action-registry";
 import { buildBulkAction } from "../../../_internal/shared/actions/bulk-helpers";
@@ -29,6 +30,7 @@ const STATUS_BADGE = {
     cancelled: "danger",
 };
 export function SellerBidsView({ endpoint = SELLER_ENDPOINTS.BIDS }) {
+    const [detail, setDetail] = useState(null);
     const { showToast } = useToast();
     const [collapsedGroups, setCollapsedGroups] = useState(new Set());
     const toggleGroup = (id) => setCollapsedGroups((s) => {
@@ -130,9 +132,14 @@ export function SellerBidsView({ endpoint = SELLER_ENDPOINTS.BIDS }) {
             }
             return (_jsx(Stack, { gap: "3", children: groupedRows.map((group) => {
                     const collapsed = collapsedGroups.has(group.id);
-                    return (_jsxs(Div, { className: "border border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface)]", rounded: "lg", children: [_jsxs(Button, { variant: "ghost", type: "button", onClick: () => toggleGroup(group.id), justify: "between", paddingX: "md", paddingY: "y-xs-tall", textSize: "sm", weight: "semibold", textColor: "default", className: "w-full hover:bg-[var(--appkit-color-surface-raised)]", children: [_jsxs(Span, { className: "truncate", children: [group.title, " ", _jsxs(Span, { size: "xs", weight: "normal", className: "text-[var(--appkit-color-text-muted)]", children: ["\u00B7 ", group.bids.length, " bid", group.bids.length === 1 ? "" : "s"] })] }), _jsx(Span, { "aria-hidden": true, className: "text-[var(--appkit-color-text-muted)]", children: collapsed ? "▸" : "▾" })] }), !collapsed && (_jsx(Div, { className: "border-t border-[var(--appkit-color-border)]", children: _jsx(DataTable, { rows: group.bids, columns: columns, isLoading: false, emptyLabel: "", selectedIds: new Set(selection.selectedIds), onToggleSelect: selection.toggleSelect }) }))] }, group.id));
+                    return (_jsxs(Div, { className: "border border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface)]", rounded: "lg", children: [_jsxs(Button, { variant: "ghost", type: "button", onClick: () => toggleGroup(group.id), justify: "between", paddingX: "md", paddingY: "y-xs-tall", textSize: "sm", weight: "semibold", textColor: "default", className: "w-full hover:bg-[var(--appkit-color-surface-raised)]", children: [_jsxs(Span, { className: "truncate", children: [group.title, " ", _jsxs(Span, { size: "xs", weight: "normal", className: "text-[var(--appkit-color-text-muted)]", children: ["\u00B7 ", group.bids.length, " bid", group.bids.length === 1 ? "" : "s"] })] }), _jsx(Span, { "aria-hidden": true, className: "text-[var(--appkit-color-text-muted)]", children: collapsed ? "▸" : "▾" })] }), !collapsed && (_jsx(Div, { className: "border-t border-[var(--appkit-color-border)]", children: _jsx(DataTable, { rows: group.bids, columns: columns, isLoading: false, emptyLabel: "", selectedIds: new Set(selection.selectedIds), onToggleSelect: selection.toggleSelect, 
+                                    // Without this the row could be selected and bulk-acted
+                                    // on but never opened — a seller could cancel a bid they
+                                    // had no way to read (Root Cause #56).
+                                    onRowClick: (row) => setDetail(row) }) }))] }, group.id));
                 }) }));
         },
     };
-    return _jsx(DataListingView, { config: config });
+    const detailBadge = detail ? bidStatusBadge(detail.status) : null;
+    return (_jsxs(_Fragment, { children: [_jsx(DataListingView, { config: config }), _jsx(RecordDetailModal, { isOpen: detail !== null, onClose: () => setDetail(null), title: detail?.productTitle || "Bid", badges: detailBadge ? [{ label: detailBadge.label }] : undefined, fields: detail ? buildBidDetailFields(detail, "seller") : undefined })] }));
 }

package/dist/features/seller/components/SellerCouponEditorView.js

@@ -5,6 +5,8 @@ import { Badge, Button, Checkbox, Div, Form, Heading, IconButton, Input, Label,
 import { ProductInlineSelect } from "./ProductInlineSelect";
 import { CategoryInlineSelect } from "./CategoryInlineSelect";
 import { normalizeError } from "../../../errors/normalize";
+import { FormErrorSummary, applyZodIssues } from "../../../ui/forms";
+import { sellerCouponFormSchema } from "../schemas/coupon-form";
 const __O = {
     hidden: "overflow-hidden",
 };
@@ -39,22 +41,20 @@ export function SellerCouponEditorView({ couponId, initial, onSave, onCancel, })
     const [saving, setSaving] = useState(false);
     const [error, setError] = useState(null);
     const set = (key, value) => setDraft((d) => ({ ...d, [key]: value }));
-    const handleSubmit = async (e) => {
+    const handleSubmit = async (e, setFieldError) => {
         e.preventDefault();
-        if (!draft.code.trim()) {
-            setError("Coupon code is required");
-            return;
-        }
-        if (draft.type !== "free_shipping" && !draft.value) {
-            setError("Discount value is required");
-            return;
-        }
-        if (!draft.startDate || !draft.endDate) {
-            setError("Start and end dates are required");
-            return;
-        }
-        if (draft.startDate > draft.endDate) {
-            setError("Start date must be before end date");
+        // Replaces four hand-rolled `if` checks that covered presence and date
+        // order and nothing else — a 500% percentage discount, a non-numeric
+        // value, a negative minimum spend and a per-customer limit above the
+        // total all passed. Errors now land on the field, not in one banner.
+        const parsed = sellerCouponFormSchema.safeParse(draft);
+        if (!parsed.success) {
+            if (setFieldError) {
+                applyZodIssues(parsed.error.issues, setFieldError);
+            }
+            else {
+                setError(parsed.error.issues[0]?.message ?? "Please check the form.");
+            }
             return;
         }
         setError(null);
@@ -71,11 +71,11 @@ export function SellerCouponEditorView({ couponId, initial, onSave, onCancel, })
         }
     };
     const isEdit = Boolean(couponId);
-    return (_jsx(Form, { onSubmit: handleSubmit, noValidate: true, children: _jsxs(Stack, { gap: "none", className: `max-w-lg mx-auto border border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface)] ${__O.hidden}`, rounded: "xl", shadow: "sm", children: [_jsx(Div, { className: "h-[3px] w-full [background:linear-gradient(to_right,var(--appkit-color-primary-700)_0%,var(--appkit-color-cobalt)_55%,var(--appkit-color-secondary-400)_100%)]", "aria-hidden": "true" }), _jsx(Div, { border: "bottom", paddingY: "y-md-lg", padding: "x-lg", children: _jsxs(Row, { justify: "between", gap: "3", children: [_jsx(Heading, { level: 2, className: "text-[var(--appkit-color-text)]", size: "lg", weight: "semibold", children: isEdit ? "Edit Coupon" : "Create Coupon" }), isEdit && (_jsx(Badge, { variant: draft.isActive ? "success" : "default", children: draft.isActive ? "Active" : "Inactive" }))] }) }), _jsxs(Stack, { gap: "5", padding: "lg", children: [error && (_jsx(Div, { textSize: "sm", className: "border border-error/20", color: "error", surface: "danger-surface", padding: "inline", rounded: "lg", children: error })), _jsx(Input, { label: "Coupon Code", value: draft.code, onChange: (e) => set("code", e.target.value.toUpperCase().replace(/\s+/g, "")), placeholder: "e.g. WELCOME10", required: true, disabled: isEdit, helperText: isEdit ? "Code cannot be changed after creation" : "Customers enter this at checkout" }), _jsx(Select, { label: "Discount Type", value: draft.type, options: TYPE_OPTIONS, onChange: (e) => set("type", e.target.value) }), draft.type !== "free_shipping" && (_jsx(Input, { label: draft.type === "percentage" ? "Discount Percentage (%)" : "Discount Amount (₹)", type: "number", min: 1, max: draft.type === "percentage" ? 100 : undefined, value: draft.value, onChange: (e) => set("value", e.target.value), placeholder: draft.type === "percentage" ? "e.g. 10" : "e.g. 50", required: true, helperText: draft.type === "percentage"
+    return (_jsx(Form, { schema: sellerCouponFormSchema, onSubmit: (e) => e.preventDefault(), children: ({ setFieldError }) => (_jsxs(Stack, { gap: "none", className: `max-w-lg mx-auto border border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface)] ${__O.hidden}`, rounded: "xl", shadow: "sm", children: [_jsx(Div, { className: "h-[3px] w-full [background:linear-gradient(to_right,var(--appkit-color-primary-700)_0%,var(--appkit-color-cobalt)_55%,var(--appkit-color-secondary-400)_100%)]", "aria-hidden": "true" }), _jsx(Div, { border: "bottom", paddingY: "y-md-lg", padding: "x-lg", children: _jsxs(Row, { justify: "between", gap: "3", children: [_jsx(Heading, { level: 2, className: "text-[var(--appkit-color-text)]", size: "lg", weight: "semibold", children: isEdit ? "Edit Coupon" : "Create Coupon" }), isEdit && (_jsx(Badge, { variant: draft.isActive ? "success" : "default", children: draft.isActive ? "Active" : "Inactive" }))] }) }), _jsxs(Stack, { gap: "5", padding: "lg", children: [_jsx(FormErrorSummary, {}), error && (_jsx(Div, { textSize: "sm", className: "border border-error/20", color: "error", surface: "danger-surface", padding: "inline", rounded: "lg", children: error })), _jsx(Input, { label: "Coupon Code", value: draft.code, onChange: (e) => set("code", e.target.value.toUpperCase().replace(/\s+/g, "")), placeholder: "e.g. WELCOME10", required: true, disabled: isEdit, helperText: isEdit ? "Code cannot be changed after creation" : "Customers enter this at checkout" }), _jsx(Select, { label: "Discount Type", value: draft.type, options: TYPE_OPTIONS, onChange: (e) => set("type", e.target.value) }), draft.type !== "free_shipping" && (_jsx(Input, { label: draft.type === "percentage" ? "Discount Percentage (%)" : "Discount Amount (₹)", type: "number", min: 1, max: draft.type === "percentage" ? 100 : undefined, value: draft.value, onChange: (e) => set("value", e.target.value), placeholder: draft.type === "percentage" ? "e.g. 10" : "e.g. 50", required: true, helperText: draft.type === "percentage"
                                 ? "Enter a value between 1 and 100"
                                 : "Fixed rupee discount applied to the order" })), draft.type === "percentage" && (_jsx(Input, { label: "Max Discount Cap (\u20B9, optional)", type: "number", min: 0, value: draft.maxDiscount, onChange: (e) => set("maxDiscount", e.target.value), placeholder: "Leave blank for no cap", helperText: "Maximum rupee discount regardless of percentage" })), _jsx(Input, { label: "Minimum Order Amount (\u20B9, optional)", type: "number", min: 0, value: draft.minPurchase, onChange: (e) => set("minPurchase", e.target.value), placeholder: "Leave blank for no minimum" }), _jsxs(Div, { children: [_jsx(Text, { size: "sm", className: CLS_SECTION_LABEL, children: "Usage Limits" }), _jsxs(Div, { layout: "grid", gap: "3", className: "grid-cols-2", children: [_jsx(Input, { label: "Total Uses", type: "number", min: 0, value: draft.totalLimit, onChange: (e) => set("totalLimit", e.target.value), placeholder: "0 = unlimited" }), _jsx(Input, { label: "Per Customer", type: "number", min: 0, value: draft.perUserLimit, onChange: (e) => set("perUserLimit", e.target.value), placeholder: "0 = unlimited" })] })] }), _jsxs(Div, { children: [_jsx(Text, { size: "sm", className: CLS_SECTION_LABEL, children: "Validity Period" }), _jsxs(Div, { layout: "grid", gap: "3", className: "grid-cols-2", children: [_jsx(Input, { label: "Start Date", type: "date", value: draft.startDate, onChange: (e) => set("startDate", e.target.value), required: true }), _jsx(Input, { label: "End Date", type: "date", value: draft.endDate, onChange: (e) => set("endDate", e.target.value), required: true })] })] }), _jsxs(Div, { children: [_jsx(Text, { size: "sm", className: CLS_SECTION_LABEL, children: "Applicability (optional)" }), _jsxs(Stack, { gap: "sm", children: [_jsxs(Div, { children: [_jsx(Text, { size: "xs", className: "mb-1 text-[var(--appkit-color-text-secondary)]", children: "Applicable products" }), _jsx(ProductInlineSelect, { scope: "store", multiple: true, value: draft.applicableProducts, onChange: (v) => set("applicableProducts", v), placeholder: "Restrict to specific products\u2026" })] }), _jsxs(Div, { children: [_jsx(Text, { size: "xs", className: "mb-1 text-[var(--appkit-color-text-secondary)]", children: "Applicable categories" }), _jsx(CategoryInlineSelect, { value: "", onChange: (id) => {
                                                         if (!id || draft.applicableCategories.includes(id))
                                                             return;
                                                         set("applicableCategories", [...draft.applicableCategories, id]);
-                                                    }, placeholder: "Add a category\u2026" }), draft.applicableCategories.length > 0 && (_jsx(Row, { wrap: true, gap: "sm", padding: "t-xs", children: draft.applicableCategories.map((cid) => (_jsxs(Span, { layout: "inline-flex", gap: "xs", border: "strong", padding: "pill-sm", rounded: "full", surface: "muted", color: "primary", size: "xs", children: [cid, _jsx(IconButton, { type: "button", "aria-label": `Remove ${cid}`, variant: "ghost", className: "text-[var(--appkit-color-text-muted)] hover:text-[var(--appkit-color-text)]", onClick: () => set("applicableCategories", draft.applicableCategories.filter((c) => c !== cid)), children: "\u00D7" })] }, cid))) }))] }), _jsx(Text, { size: "xs", className: "text-[var(--appkit-color-text-secondary)]", children: "Leave both empty to apply the coupon to every product in your store." })] })] }), _jsx(Row, { className: "border border-[var(--appkit-color-border)] dark:border-[var(--appkit-color-border-dark)]", padding: "inline", align: "center", gap: "3", rounded: "lg", children: _jsxs(Label, { layout: "flex", gap: "lg", className: "cursor-pointer w-full", children: [_jsx(Checkbox, { bare: true, checked: draft.isActive, onChange: (e) => set("isActive", e.target.checked), className: "h-4 w-4 rounded border-[var(--appkit-color-border)] text-[var(--appkit-color-primary)] focus:ring-[var(--appkit-color-primary)]" }), _jsxs(Div, { className: "flex-1 min-w-0", children: [_jsx(Text, { size: "sm", className: "text-[var(--appkit-color-text-primary)]", weight: "medium", children: "Active" }), _jsx(Text, { size: "xs", className: "text-[var(--appkit-color-text-secondary)]", children: "Customers can apply this coupon at checkout" })] })] }) })] }), _jsx(Div, { className: "border-t border-[var(--appkit-color-border)]", padding: "inlineLg", children: _jsxs(Row, { justify: "end", gap: "3", children: [onCancel && (_jsx(Button, { type: "button", variant: "outline", onClick: onCancel, disabled: saving, children: "Cancel" })), _jsx(Button, { type: "submit", isLoading: saving, disabled: saving, children: isEdit ? "Save Changes" : "Create Coupon" })] }) })] }) }));
+                                                    }, placeholder: "Add a category\u2026" }), draft.applicableCategories.length > 0 && (_jsx(Row, { wrap: true, gap: "sm", padding: "t-xs", children: draft.applicableCategories.map((cid) => (_jsxs(Span, { layout: "inline-flex", gap: "xs", border: "strong", padding: "pill-sm", rounded: "full", surface: "muted", color: "primary", size: "xs", children: [cid, _jsx(IconButton, { type: "button", "aria-label": `Remove ${cid}`, variant: "ghost", className: "text-[var(--appkit-color-text-muted)] hover:text-[var(--appkit-color-text)]", onClick: () => set("applicableCategories", draft.applicableCategories.filter((c) => c !== cid)), children: "\u00D7" })] }, cid))) }))] }), _jsx(Text, { size: "xs", className: "text-[var(--appkit-color-text-secondary)]", children: "Leave both empty to apply the coupon to every product in your store." })] })] }), _jsx(Row, { className: "border border-[var(--appkit-color-border)] dark:border-[var(--appkit-color-border-dark)]", padding: "inline", align: "center", gap: "3", rounded: "lg", children: _jsxs(Label, { layout: "flex", gap: "lg", className: "cursor-pointer w-full", children: [_jsx(Checkbox, { bare: true, checked: draft.isActive, onChange: (e) => set("isActive", e.target.checked), className: "h-4 w-4 rounded border-[var(--appkit-color-border)] text-[var(--appkit-color-primary)] focus:ring-[var(--appkit-color-primary)]" }), _jsxs(Div, { className: "flex-1 min-w-0", children: [_jsx(Text, { size: "sm", className: "text-[var(--appkit-color-text-primary)]", weight: "medium", children: "Active" }), _jsx(Text, { size: "xs", className: "text-[var(--appkit-color-text-secondary)]", children: "Customers can apply this coupon at checkout" })] })] }) })] }), _jsx(Div, { className: "border-t border-[var(--appkit-color-border)]", padding: "inlineLg", children: _jsxs(Row, { justify: "end", gap: "3", children: [onCancel && (_jsx(Button, { type: "button", variant: "outline", onClick: onCancel, disabled: saving, children: "Cancel" })), _jsx(Button, { type: "submit", isLoading: saving, disabled: saving, onClick: (e) => void handleSubmit(e, setFieldError), children: isEdit ? "Save Changes" : "Create Coupon" })] }) })] })) }));
 }

package/dist/features/seller/components/SellerOffersView.js

@@ -5,6 +5,7 @@ import { sortBy } from "@mohasinac/appkit/client";
 import React from "react";
 import { FilterChipGroup, ListingLayout, RowActionMenu, RecordDetailModal } from "../../../ui";
 import { QuickFormDrawer } from "../../shell/QuickFormDrawer";
+import { OfferPhaseTimeline } from "./OfferPhaseTimeline";
 import { counterOfferFormSchema } from "../schemas/offer-forms";
 import { SELLER_ENDPOINTS } from "../../../constants/api-endpoints";
 import { SELLER_OFFER_STATUS_TABS } from "../../admin/constants/filter-tabs";
@@ -79,7 +80,7 @@ export function SellerOffersView({ children, onAcceptOffer, onRejectOffer, onCou
                         ? [{ label: "Buyer must pay by", value: toRelativeDate(d.checkoutDeadline) }]
                         : []),
                     ...(d.sellerNote ? [{ label: "Your note", value: toStringValue(d.sellerNote, "") }] : []),
-                ] }), _jsx(QuickFormDrawer, { isOpen: counterRow !== null, onClose: () => setCounterRow(null), title: `Counter offer — ${counterRow?.primary ?? ""}`, submitLabel: "Send counter", isLoading: isCountering, schema: counterOfferFormSchema, fields: [
+                ], extra: _jsx(OfferPhaseTimeline, { status: toStringValue(d.status, "pending"), timeline: d.timeline, timelineTruncated: d.timelineTruncated, superseded: Boolean(d.superseded), createdAt: toStringValue(d.createdAt, ""), respondedAt: toStringValue(d.respondedAt, ""), acceptedAt: toStringValue(d.acceptedAt, ""), paidAt: toStringValue(d.paidAt, ""), chain: d.chain }) }), _jsx(QuickFormDrawer, { isOpen: counterRow !== null, onClose: () => setCounterRow(null), title: `Counter offer — ${counterRow?.primary ?? ""}`, submitLabel: "Send counter", isLoading: isCountering, schema: counterOfferFormSchema, fields: [
                     {
                         name: "counterAmount",
                         label: "Your counter price (₹)",

package/dist/features/seller/components/SellerPayoutSettingsView.js

@@ -5,7 +5,7 @@ import { z } from "zod";
 import { Alert, Badge, Checkbox, Div, FormField, FormGroup, Heading, Label, Row, Stack, Text, Toggle } from "../../../ui";
 import { StackedViewShell } from "../../../ui";
 import { FormShellContext, useFormShellState, applyZodIssues, FormErrorSummary } from "../../../ui/forms";
-import { SectionForm, useSectionFormNav } from "../../shell";
+import { SectionForm, useSectionFormNav, annotate } from "../../shell";
 import { SELLER_ENDPOINTS } from "../../../constants/api-endpoints";
 import { normalizeError } from "../../../errors/normalize";
 const __P = {
@@ -16,20 +16,44 @@ const __P = {
 // accountNumber field's helpText below), and the exact keep-existing
 // semantics live server-side; a client-side format requirement risks
 // blocking that legitimate blank-resave case.
+/**
+ * Section membership and row span live on the FIELD (W3).
+ *
+ * The `sections` array below still hand-writes this form's JSX, because its
+ * Payout Method panel is genuinely bespoke — a configured/not-configured
+ * badge, a "current UPI/bank" alert, and a UPI-vs-bank branch. What is NOT
+ * hand-written any more is which field belongs where and how wide it is:
+ * that is read off the schema, and `audit-form-field-roundtrip` (W4) can
+ * cross-check the two so they cannot drift apart.
+ *
+ * 🛑 `annotate()` must be the OUTERMOST call on each field. It keys a WeakMap
+ * by schema instance, and every zod wrapper returns a NEW instance — so
+ * `annotate(z.string(), …).optional()` silently loses the metadata and the
+ * field falls into the "advanced" fallback section. `audit-field-ui-meta`
+ * blocks that ordering.
+ */
 const payoutSettingsDraftSchema = z.object({
-    method: z.enum(["upi", "bank_transfer"]),
-    upiId: z.string(),
-    accountHolderName: z.string(),
-    accountNumber: z.string(),
-    ifscCode: z.string(),
-    bankName: z.string(),
-    accountType: z.enum(["savings", "current"]),
-    gstin: z.string(),
-    pan: z.string(),
-    businessType: z.string(),
-    autoPayout: z.boolean(),
-    minimumThreshold: z.string(),
-    emiEnabled: z.boolean(),
+    method: annotate(z.enum(["upi", "bank_transfer"]), {
+        section: "method", sectionLabel: "Payout Method", sectionRequired: true,
+        quick: true, order: 1, row: "pair",
+    }),
+    upiId: annotate(z.string(), { section: "method", quick: true, order: 2, row: "pair" }),
+    accountHolderName: annotate(z.string(), { section: "method", quick: true, order: 3, row: "full" }),
+    // Account number and IFSC read as one unit and each needs about half the
+    // width — the pairing this whole mechanism exists to make declarative
+    // instead of a bare `grid-cols-2` that is two columns wide at 320px.
+    accountNumber: annotate(z.string(), { section: "method", quick: true, order: 4, row: "pair" }),
+    ifscCode: annotate(z.string(), { section: "method", quick: true, order: 5, row: "pair" }),
+    bankName: annotate(z.string(), { section: "method", quick: true, order: 6, row: "pair" }),
+    accountType: annotate(z.enum(["savings", "current"]), { section: "method", quick: true, order: 7, row: "pair" }),
+    gstin: annotate(z.string(), { section: "tax", sectionLabel: "Tax Info", order: 1, row: "pair" }),
+    pan: annotate(z.string(), { section: "tax", order: 2, row: "pair" }),
+    businessType: annotate(z.string(), { section: "tax", order: 3, row: "pair" }),
+    autoPayout: annotate(z.boolean(), {
+        section: "preferences", sectionLabel: "Preferences", order: 1, row: "quarter",
+    }),
+    minimumThreshold: annotate(z.string(), { section: "preferences", order: 2, row: "pair" }),
+    emiEnabled: annotate(z.boolean(), { section: "preferences", order: 3, row: "quarter" }),
 }).superRefine((v, ctx) => {
     if (v.method === "upi") {
         if (!v.upiId.trim()) {

package/dist/features/seller/repository/offer.repository.d.ts

@@ -7,6 +7,17 @@
 import { BaseRepository, parseSieveDateValue } from "../../../providers/db-firebase";
 import type { SieveModel, FirebaseSieveResult } from "../../../providers/db-firebase";
 import type { OfferDocument, OfferCreateInput, OfferUpdateInput } from "../schemas";
+import { type HistoryActor } from "../../../_internal/shared/history/index";
+/**
+ * Who/why for a write that lands in an offer's `statusHistory`.
+ * Optional throughout so existing callers keep compiling and record `system`.
+ */
+export interface OfferWriteContext {
+    actor?: HistoryActor;
+    trigger?: string;
+    reason?: string;
+    note?: string;
+}
 declare class OfferRepository extends BaseRepository<OfferDocument> {
     constructor();
     /** Override mapDoc to auto-decrypt PII on every offer read */
@@ -107,12 +118,32 @@ declare class OfferRepository extends BaseRepository<OfferDocument> {
      * `product.updatedAt` advances past the previously-created offer dates.
      */
     countByBuyerAndProduct(buyerUid: string, productId: string, since: Date): Promise<number>;
-    updateStatus(offerId: string, patch: OfferUpdateInput): Promise<OfferDocument>;
-    accept(offerId: string, lockedPrice: number, sellerNote?: string, checkoutDeadline?: Date): Promise<OfferDocument>;
-    decline(offerId: string, sellerNote?: string): Promise<OfferDocument>;
-    counter(offerId: string, counterAmount: number, sellerNote?: string): Promise<OfferDocument>;
-    acceptCounter(offerId: string, checkoutDeadline?: Date): Promise<OfferDocument>;
-    withdraw(offerId: string): Promise<OfferDocument>;
+    /**
+     * The single write choke point for offers, so `statusHistory` is appended
+     * in ONE place rather than at every call site — the same shape
+     * `OrderRepository.updateWithHistory` uses.
+     *
+     * `prior` is the already-fetched document when the caller has one. Every
+     * real caller does (`respondToOffer`, `acceptCounterOffer`, `withdrawOffer`,
+     * `counterOfferByBuyer`, `finalizeLockedLines`, the admin PATCH, both expiry
+     * sweeps), so threading it through means history costs **zero extra reads**.
+     */
+    updateStatus(offerId: string, patch: OfferUpdateInput, ctx?: OfferWriteContext, prior?: OfferDocument | null): Promise<OfferDocument>;
+    accept(offerId: string, lockedPrice: number, sellerNote?: string, checkoutDeadline?: Date, ctx?: OfferWriteContext, prior?: OfferDocument | null): Promise<OfferDocument>;
+    decline(offerId: string, sellerNote?: string, ctx?: OfferWriteContext, prior?: OfferDocument | null): Promise<OfferDocument>;
+    counter(offerId: string, counterAmount: number, sellerNote?: string, ctx?: OfferWriteContext, prior?: OfferDocument | null): Promise<OfferDocument>;
+    acceptCounter(offerId: string, checkoutDeadline?: Date, ctx?: OfferWriteContext, prior?: OfferDocument | null): Promise<OfferDocument>;
+    /**
+     * Two distinct events share this method:
+     *  - the buyer walks away        → status alone
+     *  - the buyer counters          → status + `supersededByOfferId`
+     *
+     * The second is what makes the chain walkable forward, and it is ONE write
+     * with ONE history entry. A `withdrawn` document carrying
+     * `supersededByOfferId` renders as *Superseded* (neutral) rather than
+     * *Withdrawn* (negative) — the negotiation continued, it did not end.
+     */
+    withdraw(offerId: string, supersededByOfferId?: string, ctx?: OfferWriteContext, prior?: OfferDocument | null): Promise<OfferDocument>;
     /**
      * Terminal transition, called once the buyer's order for this offer exists.
      *
@@ -121,7 +152,21 @@ declare class OfferRepository extends BaseRepository<OfferDocument> {
      * client-side patch in UserOffersPanel, which meant a reload showed the offer
      * back at "accepted" and it could be added to the cart and ordered again.
      */
-    markPaid(offerId: string, orderId: string): Promise<OfferDocument>;
+    markPaid(offerId: string, orderId: string, prior?: OfferDocument | null): Promise<OfferDocument>;
+    /**
+     * Every round of one negotiation, oldest first.
+     *
+     * A single-field equality — served by Firestore's AUTOMATIC index, so this
+     * adds no composite index and none of the existing `offers` indexes is
+     * affected. The sort is done in memory because the result is at most 3 rows
+     * (the per-buyer offer limit), which is cheaper than the index a compound
+     * orderBy would demand.
+     *
+     * Offers written before `chainRootOfferId` existed return ZERO rows, not
+     * one — callers must fall back to `[offer]` and never read empty as
+     * "this offer is missing".
+     */
+    findChain(chainRootOfferId: string): Promise<OfferDocument[]>;
     /**
      * Cloud Functions compatibility: pending/countered offers already expired.
      */
@@ -133,7 +178,23 @@ declare class OfferRepository extends BaseRepository<OfferDocument> {
      * price remained claimable long after the seller expected it to lapse.
      */
     findExpiredAccepted(now: Date): Promise<OfferDocument[]>;
-    expireMany(offerIds: string[]): Promise<void>;
+    /**
+     * Bulk-expire, taking the DOCUMENTS rather than their ids.
+     *
+     * The signature changed deliberately. `arrayUnion` would let a batch append
+     * without a read, but it **cannot enforce the FIFO cap** — so history would
+     * grow unbounded on exactly the path that touches the most documents at
+     * once. Folding entries in memory and writing whole arrays keeps the cap,
+     * and costs **zero extra reads**: `findExpiredActive`, `findExpiredAccepted`
+     * and the admin cancel route all already hold full `OfferDocument`s.
+     *
+     * Also carries the admin path: a reasoned cancel is an expiry with an actor
+     * and a reason, recorded in the offer's own history as well as in
+     * `adminAuditLog`.
+     */
+    expireMany(offers: OfferDocument[], ctx?: OfferWriteContext & {
+        cancelledByAdminUid?: string;
+    }): Promise<void>;
 }
 export declare const offerRepository: OfferRepository;
 export { OfferRepository };