@mohasinac/appkit 4.21.0 → 4.23.0

package/dist/features/shell/QuickFormDrawer.js

@@ -25,6 +25,15 @@ export function QuickFormDrawer({ isOpen, onClose, title, fields, defaultValues,
     const drawerRef = useRef(null);
     const [values, setValues] = useState(() => initValues(fields, defaultValues));
     const [errors, setErrors] = useState({});
+    /*
+     * The drawer's `errors` state is already submit-gated (only `validate()`
+     * writes it), but the summary below reads `liveErrors`, which is a pure
+     * function of the current values and therefore non-empty from first paint.
+     * Without this flag the drawer opens listing every field it is about to
+     * ask for. Reset on close, so reopening starts clean.
+     */
+    const [submitAttemptCount, setSubmitAttemptCount] = useState(0);
+    const submitAttempted = submitAttemptCount > 0;
     const [submitting, setSubmitting] = useState(false);
     // Re-initialise when defaultValues change (e.g. edit mode)
     useEffect(() => {
@@ -101,6 +110,7 @@ export function QuickFormDrawer({ isOpen, onClose, title, fields, defaultValues,
     })();
     const handleSubmit = useCallback(async (e) => {
         e?.preventDefault();
+        setSubmitAttemptCount((n) => n + 1);
         if (!validate())
             return;
         setSubmitting(true);
@@ -118,6 +128,7 @@ export function QuickFormDrawer({ isOpen, onClose, title, fields, defaultValues,
     const handleClose = useCallback(() => {
         setValues(initValues(fields, defaultValues));
         setErrors({});
+        setSubmitAttemptCount(0);
         onClose();
     }, [fields, defaultValues, onClose]);
     // Keyboard: Esc → close; Tab → trap focus
@@ -175,7 +186,10 @@ export function QuickFormDrawer({ isOpen, onClose, title, fields, defaultValues,
         isDirty: false,
         isSubmitting: submitting,
         stepErrorCounts: [],
-    }), [liveErrors, submitting]);
+        submitAttempted,
+        submitAttemptCount,
+        markSubmitAttempted: () => setSubmitAttemptCount((n) => n + 1),
+    }), [liveErrors, submitting, submitAttempted, submitAttemptCount]);
     if (!isOpen)
         return null;
     const busy = submitting || isLoading;

package/dist/features/shell/SectionForm.d.ts

@@ -1,7 +1,7 @@
 import { type ReactNode } from "react";
 import type { JsonValue } from "@mohasinac/appkit/client";
 import type { ZodTypeAny } from "zod";
-import type { FormShellStep } from "../../ui/forms/FormShell";
+import { type FormShellStep } from "../../ui/forms/FormShell";
 /**
  * A collapsible form segment. Replaces `StepDef` — the differences are the
  * point, not incidental:
@@ -64,6 +64,20 @@ export interface SectionFormProps<T extends object = Record<string, JsonValue>>
     expandMode?: "single" | "multi";
     /** Suppress the built-in submit row (a FormShell footer owns it instead). */
     hideActions?: boolean;
+    /**
+     * Secondary action for the pinned mobile bar. Omit on a settings page with
+     * nowhere to go back to — the bar then shows Save alone.
+     */
+    onCancel?: () => void;
+    cancelLabel?: string;
+    /**
+     * Publish Save/Cancel and the error sheet into the mobile bottom-chrome
+     * tier. On by default: a SectionForm is a page-level form, which is exactly
+     * the case the pinned bar exists for. The hook suppresses itself inside a
+     * Modal or SideDrawer regardless, so this is only for the rarer case of a
+     * page that wants to own the bar itself.
+     */
+    bottomBar?: boolean;
     /**
      * Fires whenever live validation recomputes. SectionForm deliberately does
      * NOT mount its own `FormShellContext.Provider` — the owning view keeps the
@@ -95,5 +109,5 @@ export interface UseSectionFormNavResult<T extends object> {
 export declare function useSectionFormNav<T extends object = Record<string, JsonValue>>(sections: SectionDef<T>[], values?: T): UseSectionFormNavResult<T>;
 /** DOM id for a section panel — kept in one place so nav and render agree. */
 export declare function sectionAnchorId(id: string): string;
-export declare function SectionForm<T extends object = Record<string, JsonValue>>({ sections, values, onChange, onSubmit, submitLabel, isLoading, schema, openIds: controlledOpenIds, onOpenChange, expandMode, hideActions, onValidationChange, }: SectionFormProps<T>): import("react").JSX.Element;
+export declare function SectionForm<T extends object = Record<string, JsonValue>>({ sections, values, onChange, onSubmit, submitLabel, isLoading, schema, openIds: controlledOpenIds, onOpenChange, expandMode, hideActions, onValidationChange, onCancel, cancelLabel, bottomBar, }: SectionFormProps<T>): import("react").JSX.Element;
 export default SectionForm;

package/dist/features/shell/SectionForm.js

@@ -5,6 +5,8 @@ import { Button } from "../../ui/components/Button";
 import { CollapsibleSection } from "../../ui/components/CollapsibleSection";
 import { Badge } from "../../ui/components/Badge";
 import { Row, Span, Stack } from "../../ui";
+import { FormShellContext } from "../../ui/forms/FormShell";
+import { useFormBottomActions } from "../layout/hooks/useFormBottomActions";
 import { FormSchemaContext } from "./FormShell";
 /** Sections in render order: required first, original order preserved within each group. */
 export function orderSections(sections) {
@@ -53,8 +55,15 @@ export function useSectionFormNav(sections, values) {
 export function sectionAnchorId(id) {
     return `section-${id}`;
 }
-export function SectionForm({ sections, values, onChange, onSubmit, submitLabel = "Save", isLoading = false, schema, openIds: controlledOpenIds, onOpenChange, expandMode = "multi", hideActions = false, onValidationChange, }) {
+export function SectionForm({ sections, values, onChange, onSubmit, submitLabel = "Save", isLoading = false, schema, openIds: controlledOpenIds, onOpenChange, expandMode = "multi", hideActions = false, onValidationChange, onCancel, cancelLabel, bottomBar = true, }) {
     const inheritedSchema = useContext(FormSchemaContext);
+    /*
+     * SectionForm deliberately does not OWN a FormShellContext (the owning view
+     * keeps the provider — see the prop docs above), but it does own the submit
+     * button, so it is the one place that knows an attempt happened. Null when
+     * a caller renders it outside a provider, which is legitimate.
+     */
+    const shellCtx = useContext(FormShellContext);
     const [fieldErrors, setFieldErrors] = useState({});
     const [uncontrolledOpenIds, setUncontrolledOpenIds] = useState(() => orderSections(sections).filter((s) => s.required).map((s) => s.id));
     const ordered = useMemo(() => orderSections(sections.filter((s) => (s.when ? s.when(values) : true))), [sections, values]);
@@ -100,6 +109,23 @@ export function SectionForm({ sections, values, onChange, onSubmit, submitLabel
         onChange(partial);
         runValidation({ ...values, ...partial });
     }, [values, onChange, runValidation]);
+    /*
+     * The one submit path, shared by the inline button below and the pinned
+     * mobile bar — so an attempt is recorded and the error sheet revealed
+     * identically whichever the user presses.
+     */
+    const handleSubmit = useCallback(() => {
+        shellCtx?.markSubmitAttempted();
+        void onSubmit();
+    }, [shellCtx, onSubmit]);
+    useFormBottomActions({
+        onSubmit: handleSubmit,
+        onCancel,
+        submitLabel,
+        cancelLabel,
+        isLoading,
+        enabled: bottomBar && !hideActions,
+    });
     const toggle = useCallback((id) => {
         const isOpen = openIds.includes(id);
         if (expandMode === "single") {
@@ -123,6 +149,6 @@ export function SectionForm({ sections, values, onChange, onSubmit, submitLabel
                         toggle(section.id); }, keepMounted: section.keepMounted, renderHeaderExtra: errorCount > 0
                         ? () => (_jsxs(Badge, { variant: "danger", children: [errorCount, " ", errorCount === 1 ? "issue" : "issues"] }))
                         : undefined, children: section.render({ values, onChange: handleFieldChange, errors: fieldErrors }) }, section.id));
-            }), !hideActions && (_jsx(Row, { justify: "end", paddingY: "y-sm", children: _jsx(Button, { variant: "primary", type: "submit", onClick: () => void onSubmit(), isLoading: isLoading, disabled: isLoading, children: submitLabel }) }))] }));
+            }), !hideActions && (_jsx(Row, { justify: "end", paddingY: "y-sm", children: _jsx(Button, { variant: "primary", type: "submit", onClick: handleSubmit, isLoading: isLoading, disabled: isLoading, children: submitLabel }) }))] }));
 }
 export default SectionForm;

package/dist/features/shipments/components/AdminShipmentEditorView.js

@@ -11,6 +11,7 @@ import { ACTIONS } from "../../../_internal/shared/actions/action-registry";
 import { createShipmentSchema } from "../schemas/validation";
 import { useShipment } from "../hooks/useShipments";
 import { formatCurrency } from "../../../utils/number.formatter";
+import { RecordStatusTimeline } from "../../status-history/components/RecordStatusTimeline";
 const STATUS_OPTIONS = [
     { label: "Planning", value: "planning" },
     { label: "Ordered", value: "ordered" },
@@ -77,7 +78,9 @@ export function AdminShipmentEditorView({ shipmentId, onSaved }) {
             onSaved?.(saved.id);
         },
     });
-    return (_jsx(Form, { schema: createShipmentSchema, spacing: "md", children: ({ setFieldError }) => (_jsxs(_Fragment, { children: [_jsxs(Grid, { cols: 2, gap: "md", children: [_jsx(FieldInput, { name: "shipmentNumber", label: "Shipment Number", required: true, value: shipmentNumber, onChange: setShipmentNumber, placeholder: "SH-2026-0001" }), _jsx(FieldInput, { name: "supplierName", label: "Supplier Name", required: true, value: supplierName, onChange: setSupplierName }), _jsx(FieldInput, { name: "originCountry", label: "Origin Country", value: originCountry, onChange: setOriginCountry }), _jsx(FieldSelect, { name: "status", label: "Status", required: true, value: status, onChange: setStatus, options: STATUS_OPTIONS }), _jsx(FieldInput, { name: "trackingNumber", label: "Tracking Number", value: trackingNumber, onChange: setTrackingNumber }), _jsx(FieldInput, { name: "carrier", label: "Carrier", value: carrier, onChange: setCarrier }), _jsx(FieldInput, { name: "etaDate", label: "ETA Date", type: "date", value: etaDate, onChange: setEtaDate }), _jsx(FieldInput, { name: "laborHoursSpent", label: "Labor Hours Spent", type: "number", min: "0", value: laborHoursSpent, onChange: setLaborHoursSpent }), _jsx(FieldInput, { name: "customsTotal", label: "Customs Total (\u20B9)", type: "number", min: "0", value: customsTotalRupees, onChange: setCustomsTotalRupees, hint: "Split across lots by declared value" }), _jsx(FieldInput, { name: "shippingTotal", label: "Shipping Total (\u20B9)", type: "number", min: "0", value: shippingTotalRupees, onChange: setShippingTotalRupees, hint: "Split across lots by weight" })] }), _jsx(FieldTextarea, { name: "notes", label: "Notes", value: notes, onChange: setNotes, rows: 3 }), _jsx(FormErrorSummary, {}), _jsx(Button, { type: "button", isLoading: saveMutation.isPending, onClick: () => {
+    return (_jsx(Form, { schema: createShipmentSchema, spacing: "md", children: ({ setFieldError, markSubmitAttempted }) => (_jsxs(_Fragment, { children: [_jsxs(Grid, { cols: 2, gap: "md", children: [_jsx(FieldInput, { name: "shipmentNumber", label: "Shipment Number", required: true, value: shipmentNumber, onChange: setShipmentNumber, placeholder: "SH-2026-0001" }), _jsx(FieldInput, { name: "supplierName", label: "Supplier Name", required: true, value: supplierName, onChange: setSupplierName }), _jsx(FieldInput, { name: "originCountry", label: "Origin Country", value: originCountry, onChange: setOriginCountry }), _jsx(FieldSelect, { name: "status", label: "Status", required: true, value: status, onChange: setStatus, options: STATUS_OPTIONS }), _jsx(FieldInput, { name: "trackingNumber", label: "Tracking Number", value: trackingNumber, onChange: setTrackingNumber }), _jsx(FieldInput, { name: "carrier", label: "Carrier", value: carrier, onChange: setCarrier }), _jsx(FieldInput, { name: "etaDate", label: "ETA Date", type: "date", value: etaDate, onChange: setEtaDate }), _jsx(FieldInput, { name: "laborHoursSpent", label: "Labor Hours Spent", type: "number", min: "0", value: laborHoursSpent, onChange: setLaborHoursSpent }), _jsx(FieldInput, { name: "customsTotal", label: "Customs Total (\u20B9)", type: "number", min: "0", value: customsTotalRupees, onChange: setCustomsTotalRupees, hint: "Split across lots by declared value" }), _jsx(FieldInput, { name: "shippingTotal", label: "Shipping Total (\u20B9)", type: "number", min: "0", value: shippingTotalRupees, onChange: setShippingTotalRupees, hint: "Split across lots by weight" })] }), _jsx(FieldTextarea, { name: "notes", label: "Notes", value: notes, onChange: setNotes, rows: 3 }), _jsx(FormErrorSummary, {}), _jsx(Button, { type: "button", isLoading: saveMutation.isPending, onClick: () => {
+                        // type="button" — no native submit, so unhide the summary here.
+                        markSubmitAttempted();
                         const parsed = createShipmentSchema.safeParse({
                             shipmentNumber,
                             supplierName,
@@ -92,7 +95,7 @@ export function AdminShipmentEditorView({ shipmentId, onSaved }) {
                             return;
                         }
                         saveMutation.mutate();
-                    }, children: isCreate ? "Create Shipment" : "Save Changes" }), !isCreate && shipmentId && (_jsx(ShipmentLotsSection, { shipmentId: shipmentId, lots: lots, onLotsChanged: refetchLots }))] })) }));
+                    }, children: isCreate ? "Create Shipment" : "Save Changes" }), !isCreate && shipmentId && (_jsx(ShipmentLotsSection, { shipmentId: shipmentId, lots: lots, onLotsChanged: refetchLots })), !isCreate && (_jsx(RecordStatusTimeline, { entries: shipment?.statusHistory, truncatedCount: shipment?.statusHistoryTruncated }))] })) }));
 }
 function ShipmentLotsSection({ shipmentId, lots, onLotsChanged, }) {
     const [showAddLot, setShowAddLot] = React.useState(false);

package/dist/features/shipments/repository/shipments.repository.d.ts

@@ -4,8 +4,26 @@
  */
 import { BaseRepository, parseSieveDateValue, type SieveModel, type FirebaseSieveResult } from "../../../providers/db-firebase";
 import { type ShipmentDocument, type ShipmentCreateInput, type ShipmentUpdateInput } from "../schemas/firestore";
+import { type HistoryActor } from "../../../_internal/shared/history/index";
+/** Who/why for a shipment write that lands in `statusHistory`. */
+export interface ShipmentWriteContext {
+    actor?: HistoryActor;
+    trigger?: string;
+    reason?: string;
+    note?: string;
+}
 export declare class ShipmentsRepository extends BaseRepository<ShipmentDocument> {
     constructor();
+    /**
+     * The admin edit path. Two route callers, no funnel before this.
+     *
+     * `prior` is optional and unused by the current caller — the admin PATCH
+     * route does NOT fetch the shipment first (its GET sibling does), so this
+     * takes one read. That is the honest cost here rather than a hidden one:
+     * without the before-value a slipped ETA would record as
+     * `undefined → newDate`, which cannot answer "how many times did this move".
+     */
+    adminUpdate(shipmentId: string, patch: Partial<ShipmentDocument>, ctx?: ShipmentWriteContext, prior?: ShipmentDocument | null): Promise<ShipmentDocument>;
     findByShipmentNumber(shipmentNumber: string): Promise<ShipmentDocument | null>;
     private assertShipmentNumberAvailable;
     create(input: ShipmentCreateInput): Promise<ShipmentDocument>;

package/dist/features/shipments/repository/shipments.repository.js

@@ -4,11 +4,33 @@
  */
 import { BaseRepository, prepareForFirestore, parseSieveDateValue, } from "../../../providers/db-firebase";
 import { ConflictError } from "../../../errors";
-import { SHIPMENT_COLLECTION, SHIPMENT_FIELDS, SHIPMENT_ITEM_COLLECTION, DEFAULT_SHIPMENT_TOTALS, createShipmentId, } from "../schemas/firestore";
+import { SHIPMENT_COLLECTION, SHIPMENT_FIELDS, SHIPMENT_ITEM_COLLECTION, DEFAULT_SHIPMENT_TOTALS, createShipmentId, SHIPMENT_TRACKED_FIELDS, SHIPMENT_HISTORY_PII_FIELDS, } from "../schemas/firestore";
+import { withHistory } from "../../../_internal/shared/history/index";
 export class ShipmentsRepository extends BaseRepository {
     constructor() {
         super(SHIPMENT_COLLECTION);
     }
+    /**
+     * The admin edit path. Two route callers, no funnel before this.
+     *
+     * `prior` is optional and unused by the current caller — the admin PATCH
+     * route does NOT fetch the shipment first (its GET sibling does), so this
+     * takes one read. That is the honest cost here rather than a hidden one:
+     * without the before-value a slipped ETA would record as
+     * `undefined → newDate`, which cannot answer "how many times did this move".
+     */
+    async adminUpdate(shipmentId, patch, ctx, prior) {
+        const current = prior !== undefined ? prior : await this.findById(shipmentId);
+        const withEntry = withHistory(current, patch, {
+            tracked: SHIPMENT_TRACKED_FIELDS,
+            actor: ctx?.actor ?? { role: "system" },
+            trigger: ctx?.trigger ?? "adminUpdateShipment",
+            reason: ctx?.reason,
+            note: ctx?.note,
+            piiFields: SHIPMENT_HISTORY_PII_FIELDS,
+        });
+        return this.update(shipmentId, withEntry ?? patch);
+    }
     async findByShipmentNumber(shipmentNumber) {
         return this.findOneBy(SHIPMENT_FIELDS.SHIPMENT_NUMBER, shipmentNumber);
     }

package/dist/features/shipments/schemas/firestore.d.ts

@@ -13,6 +13,7 @@
  * never inline in a Vercel route or React component.
  */
 import { type GenerateShipmentIdInput } from "../../../utils/id-generators";
+import type { StatusChangeEntry } from "../../../_internal/shared/history/types";
 import type { BaseDocument } from "../../../_internal/shared/types/base-document";
 import type { MediaField } from "../../media/types";
 import type { ListingType } from "../../products/types";
@@ -57,6 +58,9 @@ export interface ShipmentDocument extends BaseDocument {
     totals: ShipmentTotals;
     totalsComputedAt?: Date;
     createdBy: string;
+    /** Who changed what, when, and why. See § "Status History" in CLAUDE.md. */
+    statusHistory?: StatusChangeEntry[];
+    statusHistoryTruncated?: number;
 }
 export interface ShipmentLot extends BaseDocument {
     shipmentId: string;
@@ -148,3 +152,13 @@ export declare const shipmentQueryHelpers: {
     readonly notCancelled: () => readonly ["status", "!=", ShipmentStatus];
 };
 export declare function createShipmentId(input: GenerateShipmentIdInput): string;
+/**
+ * The fields whose changes earn a timeline entry.
+ *
+ * A procurement shipment's dates ARE its status for practical purposes — "ETA
+ * slipped twice before it landed" is the question this answers, and each slip
+ * overwrites the previous `etaDate`.
+ */
+export declare const SHIPMENT_TRACKED_FIELDS: readonly ["status", "etaDate", "receivedDate", "trackingNumber"];
+/** PII on this document, for `withHistory`'s scrub. */
+export declare const SHIPMENT_HISTORY_PII_FIELDS: readonly ["supplierEmail", "supplierPhone", "contactName"];

package/dist/features/shipments/schemas/firestore.js

@@ -74,3 +74,22 @@ export const shipmentQueryHelpers = {
 export function createShipmentId(input) {
     return generateShipmentId(input);
 }
+/**
+ * The fields whose changes earn a timeline entry.
+ *
+ * A procurement shipment's dates ARE its status for practical purposes — "ETA
+ * slipped twice before it landed" is the question this answers, and each slip
+ * overwrites the previous `etaDate`.
+ */
+export const SHIPMENT_TRACKED_FIELDS = [
+    "status",
+    "etaDate",
+    "receivedDate",
+    "trackingNumber",
+];
+/** PII on this document, for `withHistory`'s scrub. */
+export const SHIPMENT_HISTORY_PII_FIELDS = [
+    "supplierEmail",
+    "supplierPhone",
+    "contactName",
+];

package/dist/features/status-history/components/RecordStatusTimeline.d.ts

@@ -0,0 +1,12 @@
+import type { StatusChangeEntry } from "../../../_internal/shared/history/types";
+export interface RecordStatusTimelineProps {
+    /** The record's `statusHistory`. Absent or empty renders `emptyLabel`. */
+    entries?: StatusChangeEntry[];
+    /** The record's `statusHistoryTruncated` — "earlier history trimmed". */
+    truncatedCount?: number;
+    title?: string;
+    emptyLabel?: string;
+    className?: string;
+}
+export declare function RecordStatusTimeline({ entries, truncatedCount, title, emptyLabel, className, }: RecordStatusTimelineProps): import("react").JSX.Element;
+export default RecordStatusTimeline;

package/dist/features/status-history/components/RecordStatusTimeline.js

@@ -0,0 +1,90 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { StatusTimeline } from "./StatusTimeline";
+/**
+ * The timeline for an entity with no fixed phase vocabulary.
+ *
+ * ## Why this exists rather than seven more wrappers
+ *
+ * `OrderStatusTimeline` and `OfferPhaseTimeline` each supply a KNOWN sequence
+ * of phases — placed → paid → shipped → delivered, made → countered →
+ * accepted → paid — and render the steps a record has not reached yet as
+ * upcoming. That shape earns a dedicated wrapper because the vocabulary is
+ * part of the product.
+ *
+ * Support tickets, payouts, stores, scammer profiles, bids, shipments,
+ * catalogue items and ads have no such sequence: a store goes active →
+ * suspended → active, a bid goes active → outbid → active → won, a payout
+ * retries. There is nothing to pre-render. So the timeline is simply the
+ * entries that happened, in order — and writing that eight times would be
+ * eight chances for the actor label, the em-dash rule or the negative tone to
+ * drift, which is the bug-fix multiplier the Duplication Framework names.
+ *
+ * ## Never fabricate a step
+ *
+ * A record written before its entity adopted history has no `statusHistory`
+ * at all. That renders `emptyLabel`, NOT a step derived from `updatedAt` —
+ * "last write of any kind" is not an event, and a made-up date makes the
+ * record lie. Same rule the offer timeline follows for `expired`.
+ */
+/**
+ * Statuses that render in the error tone.
+ *
+ * Deliberately a shared set rather than a per-entity prop: these words mean
+ * the same thing on every entity that uses them, and a per-entity list is one
+ * more thing to keep aligned. A value not listed renders neutral, which is
+ * the safe direction — a real transition shown in the wrong tone is a smaller
+ * defect than a normal one shown as a failure.
+ */
+const NEGATIVE_STATUSES = new Set([
+    "cancelled",
+    "canceled",
+    "rejected",
+    "failed",
+    "forfeited",
+    "suspended",
+    "removed",
+    "declined",
+    "expired",
+    "lost",
+]);
+/** Ended, but not a failure — the record simply moved on. */
+const MUTED_STATUSES = new Set(["outbid", "closed", "superseded", "archived"]);
+function humanise(value) {
+    if (value === null || value === undefined || value === "")
+        return "—";
+    if (typeof value === "boolean")
+        return value ? "yes" : "no";
+    const s = String(value);
+    return s.replace(/_/g, " ").replace(/^./, (c) => c.toUpperCase());
+}
+/**
+ * One entry → one step.
+ *
+ * `status` is the headline when it changed; otherwise the step is named after
+ * the fields that did move, so an entry recording only "ETA moved" still
+ * reads as a real event rather than a blank row.
+ */
+function toStep(entry, index) {
+    const statusChange = entry.changes["status"] ?? entry.changes["listingStatus"];
+    const to = statusChange?.to;
+    const label = statusChange
+        ? humanise(to)
+        : Object.keys(entry.changes).map(humanise).join(", ") || "Updated";
+    const toKey = typeof to === "string" ? to.toLowerCase() : "";
+    return {
+        key: `${entry.at instanceof Date ? entry.at.toISOString() : String(entry.at)}-${index}`,
+        label,
+        date: entry.at instanceof Date ? entry.at.toISOString() : String(entry.at),
+        negative: NEGATIVE_STATUSES.has(toKey),
+        muted: MUTED_STATUSES.has(toKey),
+        actorRole: entry.actorRole,
+        reason: entry.reason,
+        note: entry.note,
+    };
+}
+export function RecordStatusTimeline({ entries, truncatedCount, title = "History", emptyLabel = "No recorded history yet", className, }) {
+    const steps = (entries ?? []).map(toStep);
+    return (_jsx(StatusTimeline, { title: title, steps: steps, truncatedCount: truncatedCount, emptyLabel: emptyLabel, className: className }));
+}
+export default RecordStatusTimeline;

package/dist/features/status-history/index.d.ts

@@ -9,3 +9,5 @@
  */
 export { StatusTimeline, stepsFromEntries } from "./components/StatusTimeline";
 export type { StatusTimelineProps, TimelineEntry, TimelineStep } from "./components/StatusTimeline";
+export { RecordStatusTimeline } from "./components/RecordStatusTimeline";
+export type { RecordStatusTimelineProps } from "./components/RecordStatusTimeline";

package/dist/features/status-history/index.js

@@ -8,3 +8,4 @@
  * is an entirely unrelated concept.
  */
 export { StatusTimeline, stepsFromEntries } from "./components/StatusTimeline";
+export { RecordStatusTimeline } from "./components/RecordStatusTimeline";

package/dist/features/stores/repository/store.repository.d.ts

@@ -6,6 +6,14 @@
  */
 import { BaseRepository, type SieveModel, type FirebaseSieveResult, type DocumentSnapshot } from "../../../providers/db-firebase";
 import { StoreDocument } from "../schemas";
+import { type HistoryActor } from "../../../_internal/shared/history/index";
+/** Who/why for a store write that lands in `statusHistory`. */
+export interface StoreWriteContext {
+    actor?: HistoryActor;
+    trigger?: string;
+    reason?: string;
+    note?: string;
+}
 export declare class StoreRepository extends BaseRepository<StoreDocument> {
     constructor();
     private encryptSecrets;
@@ -33,9 +41,29 @@ export declare class StoreRepository extends BaseRepository<StoreDocument> {
      */
     updateStore(storeSlug: string, data: Partial<Omit<StoreDocument, "id" | "storeSlug" | "ownerId" | "createdAt">>): Promise<StoreDocument>;
     /**
-     * Admin: approve or reject a store.
+     * Admin: approve, reject or suspend a store — and the ONLY correct way to
+     * move `status`, because `isPublic` must move with it.
+     *
+     * `status` and `isPublic` are two distinct fields and public visibility
+     * gates on `isPublic`. The admin PATCH route wrote `status` directly and
+     * never touched `isPublic` until 2026-08-26, so approving a pending store
+     * left it `isPublic: false` — active, and invisible on every public
+     * surface, with nothing anywhere reporting a problem. Same two-field trap
+     * CLAUDE.md already records for `becomeSeller` / `createStore`.
+     *
+     * `extra` carries the other admin fields so a single save is a single
+     * write and a single timeline entry; `prior` keeps that entry read-free
+     * for the route, which has already fetched the store to 404 on a missing
+     * one (Rule #6).
+     */
+    setStatus(storeSlug: string, status: StoreDocument["status"], extra?: Partial<StoreDocument>, ctx?: StoreWriteContext, prior?: StoreDocument | null): Promise<StoreDocument>;
+    /**
+     * Admin field edits that do NOT move `status` — verification, featuring,
+     * capabilities, the suspension reason on an already-suspended store.
      */
-    setStatus(storeSlug: string, status: StoreDocument["status"]): Promise<StoreDocument>;
+    adminUpdate(storeSlug: string, patch: Partial<StoreDocument>, ctx?: StoreWriteContext, prior?: StoreDocument | null): Promise<StoreDocument>;
+    /** Append a timeline entry when the patch touches a tracked field. */
+    private withStoreHistory;
     /**
      * Paginated list of stores with Sieve filtering/sorting.
      * Filters to active + public stores for the public listing.

package/dist/features/stores/repository/store.repository.js

@@ -6,10 +6,11 @@
  */
 import { BaseRepository, prepareForFirestore, applySieveToFirestore, } from "../../../providers/db-firebase";
 import { increment } from "../../../contracts/field-ops";
-import { STORE_COLLECTION, STORE_FIELDS, DEFAULT_STORE_DATA, StoreStatusValues, } from "../schemas";
+import { STORE_COLLECTION, STORE_FIELDS, DEFAULT_STORE_DATA, StoreStatusValues, STORE_TRACKED_FIELDS, STORE_HISTORY_PII_FIELDS, } from "../schemas";
 import { DatabaseError } from "../../../errors";
 import { normalizeError } from "../../../errors/normalize";
 import { encryptSecret, decryptSecret, } from "../../../security/settings-encryption";
+import { withHistory } from "../../../_internal/shared/history/index";
 export class StoreRepository extends BaseRepository {
     constructor() {
         super(STORE_COLLECTION);
@@ -97,16 +98,54 @@ export class StoreRepository extends BaseRepository {
         });
     }
     /**
-     * Admin: approve or reject a store.
+     * Admin: approve, reject or suspend a store — and the ONLY correct way to
+     * move `status`, because `isPublic` must move with it.
+     *
+     * `status` and `isPublic` are two distinct fields and public visibility
+     * gates on `isPublic`. The admin PATCH route wrote `status` directly and
+     * never touched `isPublic` until 2026-08-26, so approving a pending store
+     * left it `isPublic: false` — active, and invisible on every public
+     * surface, with nothing anywhere reporting a problem. Same two-field trap
+     * CLAUDE.md already records for `becomeSeller` / `createStore`.
+     *
+     * `extra` carries the other admin fields so a single save is a single
+     * write and a single timeline entry; `prior` keeps that entry read-free
+     * for the route, which has already fetched the store to 404 on a missing
+     * one (Rule #6).
      */
-    async setStatus(storeSlug, status) {
-        return this.update(storeSlug, {
+    async setStatus(storeSlug, status, extra, ctx, prior) {
+        const current = prior !== undefined ? prior : await this.findById(storeSlug);
+        return this.update(storeSlug, this.withStoreHistory(current, {
             status,
             // Auto-set isPublic when approved
             ...(status === StoreStatusValues.ACTIVE && { isPublic: true }),
             ...(status !== StoreStatusValues.ACTIVE && { isPublic: false }),
+            ...extra,
             updatedAt: new Date(),
+        }, ctx, "setStatus"));
+    }
+    /**
+     * Admin field edits that do NOT move `status` — verification, featuring,
+     * capabilities, the suspension reason on an already-suspended store.
+     */
+    async adminUpdate(storeSlug, patch, ctx, prior) {
+        const current = prior !== undefined ? prior : await this.findById(storeSlug);
+        return this.update(storeSlug, this.withStoreHistory(current, { ...patch, updatedAt: new Date() }, ctx, "adminUpdateStore"));
+    }
+    /** Append a timeline entry when the patch touches a tracked field. */
+    withStoreHistory(current, patch, ctx, defaultTrigger) {
+        const withEntry = withHistory(current, patch, {
+            tracked: STORE_TRACKED_FIELDS,
+            actor: ctx?.actor ?? { role: "system" },
+            trigger: ctx?.trigger ?? defaultTrigger,
+            reason: ctx?.reason,
+            note: ctx?.note,
+            // `mapDoc` decrypts whatsappConfig.accessToken on EVERY read, so a
+            // live Meta credential is in memory whenever this diff runs, and
+            // `encryptPiiFields` never descends into arrays.
+            piiFields: STORE_HISTORY_PII_FIELDS,
         });
+        return withEntry ?? patch;
     }
     /**
      * Paginated list of stores with Sieve filtering/sorting.

package/dist/features/stores/schemas/firestore.d.ts

@@ -4,6 +4,7 @@
  * Canonical Firestore document interfaces, collection names, field constants,
  * and helpers for the stores feature.
  */
+import type { StatusChangeEntry } from "../../../_internal/shared/history/types";
 import type { StoreCapability } from "../../auth/permissions/constants";
 import type { BaseDocument } from "../../../_internal/shared/types/base-document";
 export type ShippingProviderType = "self-courier" | "store-pickup" | "custom";
@@ -139,7 +140,35 @@ export interface StoreDocument extends BaseDocument {
         /** When the seller first connected their account */
         connectedAt?: Date;
     };
+    /**
+     * Who changed what, when, and why. See § "Status History" in CLAUDE.md.
+     *
+     * The question this answers for a seller is "why is my store suspended and
+     * who did it" — previously recoverable only from `adminAuditLog`, which is
+     * admin-only and which the seller can never see.
+     */
+    statusHistory?: StatusChangeEntry[];
+    statusHistoryTruncated?: number;
 }
+/**
+ * The fields whose changes earn a timeline entry.
+ *
+ * `isPublic` is tracked alongside `status` deliberately: the two are supposed
+ * to move together (`setStatus` syncs them) and the admin PATCH route did NOT
+ * until 2026-08-26, so an approved store stayed invisible. A timeline that
+ * shows them diverging is how the next instance gets noticed.
+ *
+ * `adminNotes` is excluded — its own schema comment says it is never shown to
+ * the store owner or the public, and `statusHistory` rides on the store
+ * document the owner can read.
+ */
+export declare const STORE_TRACKED_FIELDS: readonly ["status", "isPublic", "isVerified", "isFeatured", "suspensionReason", "capabilities"];
+/**
+ * PII on this document, for `withHistory`'s scrub. `whatsappConfig.accessToken`
+ * is a live Meta credential; `mapDoc` decrypts it on EVERY read, so it is
+ * present in memory whenever a diff runs.
+ */
+export declare const STORE_HISTORY_PII_FIELDS: readonly ["accessToken", "payoutDetails", "upiVpa", "accountNumber"];
 export type { StoreCapability } from "../../auth/permissions/constants";
 export declare const STORE_COLLECTION: "stores";
 export declare const STORE_FIELDS: {

package/dist/features/stores/schemas/firestore.js

@@ -12,6 +12,37 @@ export const StoreStatusValues = {
     SUSPENDED: "suspended",
     REJECTED: "rejected",
 };
+/**
+ * The fields whose changes earn a timeline entry.
+ *
+ * `isPublic` is tracked alongside `status` deliberately: the two are supposed
+ * to move together (`setStatus` syncs them) and the admin PATCH route did NOT
+ * until 2026-08-26, so an approved store stayed invisible. A timeline that
+ * shows them diverging is how the next instance gets noticed.
+ *
+ * `adminNotes` is excluded — its own schema comment says it is never shown to
+ * the store owner or the public, and `statusHistory` rides on the store
+ * document the owner can read.
+ */
+export const STORE_TRACKED_FIELDS = [
+    "status",
+    "isPublic",
+    "isVerified",
+    "isFeatured",
+    "suspensionReason",
+    "capabilities",
+];
+/**
+ * PII on this document, for `withHistory`'s scrub. `whatsappConfig.accessToken`
+ * is a live Meta credential; `mapDoc` decrypts it on EVERY read, so it is
+ * present in memory whenever a diff runs.
+ */
+export const STORE_HISTORY_PII_FIELDS = [
+    "accessToken",
+    "payoutDetails",
+    "upiVpa",
+    "accountNumber",
+];
 export const STORE_COLLECTION = "stores";
 export const STORE_FIELDS = {
     ID: "id",