@mohasinac/appkit 4.62.1 → 4.63.0

package/dist/features/dashboard/components/DashboardSectionsClient.js

@@ -0,0 +1,66 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useMemo } from "react";
+import { useSiteSettings } from "../../../core/hooks/useSiteSettings.js";
+import { filterNavGroups } from "../../../_internal/client/features/layout/filterNavItems.js";
+import { hubSections } from "../../../_internal/shared/features/dashboard/hub-sections.js";
+import { ROUTES } from "../../../next/routing/route-map.js";
+import { DashboardHubView } from "./DashboardHubView.js";
+/**
+ * The sectioned index of a dashboard, for a landing page that is already a
+ * CLIENT component.
+ *
+ * ## Why a client variant exists at all
+ *
+ * `/store/page.tsx` and `/user/page.tsx` are `"use client"` and carry live stat
+ * tiles (`useStoreDashboard`, `useNotifications`, an avatar uploader). Turning
+ * either into a server component to fetch hub data would mean moving a working
+ * 250–360 line page into a sibling file for the sake of a card grid — a large
+ * diff over a working feature, which is the shape of Root Cause #60.
+ *
+ * So the DATA source differs and the RENDERER does not: this resolves sections
+ * from the same `useSiteSettings` navConfig the sidebar reads, and hands them to
+ * the same `<DashboardHubView>` the admin landing renders server-side. One card
+ * grid, two ways in — not two card grids.
+ *
+ * ## 🛑 No attention counts here, and that is honest rather than lazy
+ *
+ * Counts need Firestore, which a client component can only reach through an
+ * endpoint — a second billed invocation per landing visit for numbers the page
+ * did not previously show (Root Cause #94). The admin landing, which is a
+ * server component under a session-reading layout, gets them for free in its
+ * own render. A seller's one countable figure (pending orders) is already a
+ * live stat tile on `/store`, so the badge would be the second place for it.
+ *
+ * `counts={{}}` means every card renders without a badge — never with a `0`,
+ * which is the one answer that would wrongly read as "nothing waiting"
+ * (Root Cause #72).
+ */
+/**
+ * 🛑 `Record<NavPortal, …>` so a fourth portal is a COMPILE error here rather
+ * than a landing page whose section cards all link to `""`. An object keyed on
+ * `string` would accept the omission silently (Root Cause #61).
+ */
+const SECTION_ROUTE = {
+    admin: (slug) => String(ROUTES.ADMIN.SECTION(slug)),
+    store: (slug) => String(ROUTES.STORE.SECTION(slug)),
+    user: (slug) => String(ROUTES.USER.SECTION(slug)),
+};
+export function DashboardSectionsClient({ portal, groups, permissions, title, description, above, emptyMessage, }) {
+    const { data: settings } = useSiteSettings();
+    /*
+     * Derived, never copied into state — the settings query can resolve after
+     * first paint, and a `useState` seeded from it would freeze the pre-settings
+     * answer. Same reasoning as `AdminIntegrationsView`.
+     */
+    const sections = useMemo(() => hubSections(filterNavGroups([...groups], settings?.navConfig, permissions)), [groups, settings?.navConfig, permissions]);
+    const sectionHrefs = useMemo(() => Object.fromEntries(sections.map((s) => [s.slug, SECTION_ROUTE[portal](s.slug)])), [sections, portal]);
+    return (_jsx(DashboardHubView, { title: title, description: description, mode: "sections", sections: sections, sectionHrefs: sectionHrefs, counts: {}, above: above, emptyMessage: emptyMessage, 
+        /*
+         * 🛑 Withheld deliberately. `/store`'s entitlement filter lives in the
+         * layout and on the hub pages, not here, so a count rendered from these
+         * groups would over-promise on the Listings card. See the prop's own
+         * header — the section is right, the number would not be.
+         */
+        showScreenCount: false }));
+}

package/dist/features/dispute-reasons/components/AdminDisputeReasonsView.d.ts

@@ -0,0 +1,55 @@
+import React from "react";
+import { type DisputeKind } from "../../../_internal/shared/features/orders/dispute-reasons";
+/**
+ * Admin → Trust & Safety → Dispute reasons.
+ *
+ * ## Why a management page exists at all
+ *
+ * Inline create in the triage drawer was the cheaper half and was rejected on
+ * its own, for a reason worth keeping: **with no management page nothing can
+ * ever retire a reason**, so the list only grows and a typo'd row is permanent.
+ * Both shipped — the drawer so an agent never leaves a ticket to add a missing
+ * reason, this page so the eleven seeded rows are reviewable and retire has a
+ * home.
+ *
+ * ## 🛑 A row is OPENABLE, not just actionable
+ *
+ * `audit-listing-detail-affordance` requires it and the reason is Root Cause
+ * #56: a menu of pure mutations lets staff act on a record they were never able
+ * to read. Here that would mean retiring a reason without seeing its KIND — and
+ * the kind is the only field that decides which gate the reason inherits, so
+ * retiring the wrong one silently narrows the wrong form.
+ *
+ * `RecordDetailModal` is the shared primitive for exactly this; a bespoke modal
+ * would have tripped the Duplication Framework's Rule of Three on sight.
+ */
+export interface AdminDisputeReasonsViewProps {
+    /**
+     * The staff list endpoint, supplied by the consumer.
+     *
+     * 🛑 A PROP rather than a literal in here, for the same reason
+     * `RaiseDisputeForm` takes `reasonsEndpoint`: appkit holds no consumer
+     * routes. The path belongs in `API_ROUTES`, which is the one registry, and a
+     * literal here would be a second place it is written — exactly what
+     * `audit-hardcoded-api-routes` blocks.
+     */
+    endpoint: string;
+    /** `PATCH /api/admin/dispute-reasons/{id}` with `{ isActive }`. */
+    onSetActive: (id: string, isActive: boolean) => Promise<void>;
+    /** `POST /api/dispute-reasons` — the same endpoint the triage drawer uses. */
+    onCreate: (input: {
+        label: string;
+        kind: DisputeKind;
+    }) => Promise<void>;
+}
+/**
+ * The two fields, exported so the triage drawer's inline create and this page
+ * cannot drift on the label bound or the kind vocabulary.
+ */
+export declare function DisputeReasonFields({ label, kind, onLabel, onKind, }: {
+    label: string;
+    kind: DisputeKind;
+    onLabel: (v: string) => void;
+    onKind: (v: DisputeKind) => void;
+}): React.JSX.Element;
+export declare function AdminDisputeReasonsView({ endpoint, onSetActive, onCreate, }: AdminDisputeReasonsViewProps): React.JSX.Element;

package/dist/features/dispute-reasons/components/AdminDisputeReasonsView.js

@@ -0,0 +1,175 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useCallback, useState } from "react";
+import { Badge, Button, Row, Stack, Text } from "../../../ui/index.js";
+import { RecordDetailModal } from "../../../ui/components/RecordDetailModal.js";
+import { useToast } from "../../../ui/components/Toast.js";
+import { FieldInput } from "../../../ui/forms/FieldInput.js";
+import { FieldSelect } from "../../../ui/forms/FieldSelect.js";
+import { normalizeError } from "../../../errors/normalize.js";
+import { DataListingView } from "../../admin/components/DataListingView.js";
+import { ACTIONS } from "../../../_internal/shared/actions/action-registry.js";
+import { DISPUTE_KIND, } from "../../../_internal/shared/features/orders/dispute-reasons.js";
+import { DISPUTE_REASON_LABEL_MAX, } from "../schemas/firestore.js";
+/**
+ * What each kind MEANS, in one place.
+ *
+ * 🛑 A `Record<DisputeKind, string>`, so a third kind is a compile error here
+ * rather than a picker option rendering a bare token. The kind is the only
+ * field on a reason with a consequence — it decides which gate a dispute
+ * raised under it inherits — so it is the one that must never read as jargon.
+ */
+const KIND_MEANING = {
+    item: "Item problem — it arrived wrong or damaged",
+    not_reached: "Never arrived — the parcel did not reach the buyer",
+};
+/*
+ * Chips over `isActive`, as ordinary Sieve clauses. `listAll` applies no
+ * `isActive` filter of its own precisely so these work without the repository
+ * growing a method per chip.
+ *
+ * 🛑 "All" carries NO filter rather than `isActive==true|false`. A pipe-joined
+ * OR over a boolean would be two equalities merged for no reason, and — worse —
+ * it would exclude any row written before the field existed, which is the `!=`
+ * trap one step removed.
+ */
+const SCOPE_CHIPS = [
+    { id: "active", label: "Active", filter: "isActive==true" },
+    { id: "retired", label: "Retired", filter: "isActive==false" },
+    { id: "all", label: "All", filter: undefined },
+];
+/**
+ * The two fields, exported so the triage drawer's inline create and this page
+ * cannot drift on the label bound or the kind vocabulary.
+ */
+export function DisputeReasonFields({ label, kind, onLabel, onKind, }) {
+    return (_jsxs(Stack, { gap: "md", children: [_jsx(FieldInput, { name: "label", label: "Reason wording", required: true, value: label, onChange: onLabel, maxLength: DISPUTE_REASON_LABEL_MAX, placeholder: "The courier left it at the wrong flat" }), _jsx(FieldSelect, { name: "kind", label: "Kind", required: true, value: kind, onChange: (v) => onKind(v), 
+                /*
+                 * Two options, so `<FieldSelect>` is correct — `PaginatedSelect` is for
+                 * >5 (Rule #9), and a searchable dropdown over two values is worse than
+                 * a native select. Derived from the shipped union so a third kind
+                 * cannot exist in the gate and be missing here.
+                 */
+                options: DISPUTE_KIND.map((k) => ({ value: k, label: KIND_MEANING[k] })) })] }));
+}
+/** Create form. Shares `DisputeReasonFields` and the endpoint with the drawer. */
+function CreateReasonForm({ onSubmit, }) {
+    const [label, setLabel] = useState("");
+    const [kind, setKind] = useState(DISPUTE_KIND[0]);
+    const [busy, setBusy] = useState(false);
+    const { showToast } = useToast();
+    return (_jsxs(Stack, { gap: "md", children: [_jsx(Text, { size: "sm", color: "muted", children: "Short wording, as a buyer would read it. The detail goes in their own free-text field \u2014 this is a picker option, not the explanation." }), _jsx(DisputeReasonFields, { label: label, kind: kind, onLabel: setLabel, onKind: setKind }), _jsx(Button, { action: ACTIONS.ADMIN["add-dispute-reason"], isLoading: busy, disabled: busy || label.trim().length < 3, onClick: async () => {
+                    setBusy(true);
+                    try {
+                        await onSubmit({ label: label.trim(), kind });
+                    }
+                    catch (err) {
+                        void normalizeError(err);
+                        showToast("Couldn't add that reason.", "error");
+                    }
+                    finally {
+                        setBusy(false);
+                    }
+                } })] }));
+}
+export function AdminDisputeReasonsView({ endpoint, onSetActive, onCreate, }) {
+    const { showToast } = useToast();
+    const [open, setOpen] = useState(null);
+    const [pending, setPending] = useState(null);
+    const setActive = useCallback(async (row, isActive) => {
+        setPending(row.id);
+        try {
+            await onSetActive(row.id, isActive);
+            showToast(isActive ? `"${row.label}" is back in the picker.` : `"${row.label}" retired.`, "success");
+        }
+        catch (err) {
+            void normalizeError(err);
+            /*
+             * No optimistic flip anywhere here, so a failure needs no rollback —
+             * the row still shows what the server last told us. Only a successful
+             * write and the refetch behind it move the list.
+             */
+            showToast("Couldn't save that. Nothing was changed.", "error");
+        }
+        finally {
+            setPending(null);
+        }
+    }, [onSetActive, showToast]);
+    const rowControls = useCallback((row) => (_jsxs(Row, { align: "center", gap: "sm", children: [_jsx(Button, { variant: "ghost", size: "sm", onClick: () => setOpen(row), children: "View" }), _jsx(Button, { action: row.isActive
+                    ? ACTIONS.ADMIN["retire-dispute-reason"]
+                    : ACTIONS.ADMIN["reactivate-dispute-reason"], size: "sm", isLoading: pending === row.id, disabled: pending !== null, onClick: () => setActive(row, !row.isActive) })] })), [pending, setActive]);
+    return (_jsxs(_Fragment, { children: [_jsx(DataListingView, { config: {
+                    portal: "admin",
+                    title: "Dispute reasons",
+                    subtitle: "What buyers can pick when reporting a problem. A reason's kind decides which gate it inherits — the wording is yours.",
+                    endpoint: endpoint,
+                    queryKey: ["admin", "dispute-reasons"],
+                    defaultSort: "label",
+                    /*
+                     * 🛑 REQUIRED on `ListingViewConfig`, and the default must be one of
+                     * these or the dropdown opens with nothing selected (Root Cause #63).
+                     * Eleven rows, so the only orders worth offering are the buyer-facing
+                     * wording and which kind a reason belongs to.
+                     */
+                    sortOptions: [
+                        { value: "label", label: "Wording (A–Z)" },
+                        { value: "-label", label: "Wording (Z–A)" },
+                        { value: "kind", label: "Kind" },
+                    ],
+                    filterKeys: ["scope"],
+                    filterDefaults: { scope: "active" },
+                    buildFilters: (state) => SCOPE_CHIPS.find((c) => c.id === (state.scope ?? "active"))?.filter,
+                    mapRows: (res) => (res.items ?? []).map((r) => ({
+                        id: r.id,
+                        label: r.label,
+                        kind: r.kind,
+                        isActive: r.isActive,
+                        createdByName: r.createdByName,
+                    })),
+                    getTotal: (res, rows) => res.total ?? rows.length,
+                    /*
+                     * 🛑 No `searchPlaceholder` and no `search` — the endpoint does not read
+                     * `q`, and declaring either is what makes the box exist. ~39 views here
+                     * render a box whose endpoint ignores the term: it accepts typing, the
+                     * request carries it, and the results do not change, with no error
+                     * anywhere. Eleven rows with scope chips need no search.
+                     */
+                    emptyLabel: "No reasons in this scope.",
+                    primaryAction: {
+                        label: ACTIONS.ADMIN["add-dispute-reason"].label,
+                        onClick: ({ openCreatePanel }) => openCreatePanel(),
+                    },
+                    renderEditor: ({ closePanel }) => (_jsx(CreateReasonForm, { onSubmit: async (input) => {
+                            await onCreate(input);
+                            closePanel();
+                        } })),
+                    resolveEditorTitle: () => "Add a dispute reason",
+                    onRowClick: (row) => setOpen(row),
+                    renderRowActions: rowControls,
+                    renderCards: (rows) => (_jsx(Stack, { gap: "sm", children: rows.map((row) => (_jsxs(Row, { surface: "card", padding: "md", rounded: "lg", border: "default", align: "center", justify: "between", gap: "md", className: "min-w-0", children: [_jsxs(Stack, { gap: "xs", className: "min-w-0", children: [_jsxs(Row, { align: "center", gap: "sm", className: "min-w-0", children: [_jsx(Text, { weight: "semibold", color: "primary", className: "min-w-0", children: row.label }), _jsx(Badge, { variant: row.isActive ? "success" : "inactive", children: row.isActive ? "Active" : "Retired" })] }), _jsx(Text, { size: "xs", color: "muted", children: KIND_MEANING[row.kind] }), _jsxs(Text, { size: "xs", color: "faint", children: ["Added by ", row.createdByName] })] }), rowControls(row)] }, row.id))) })),
+                } }), open && (_jsx(RecordDetailModal, { isOpen: true, onClose: () => setOpen(null), title: open.label, badges: [
+                    {
+                        label: open.isActive ? "Active" : "Retired",
+                        variant: open.isActive ? "success" : "secondary",
+                    },
+                ], fields: [
+                    { label: "Buyer-facing wording", value: open.label },
+                    { label: "Kind", value: `${open.kind} — ${KIND_MEANING[open.kind]}` },
+                    {
+                        label: "State",
+                        value: open.isActive
+                            ? "Active — buyers see it on the dispute form"
+                            : "Retired — hidden from the form",
+                    },
+                    { label: "Added by", value: open.createdByName },
+                ], metadata: {
+                    id: open.id,
+                    /*
+                     * Stated on the record itself, because it is the fact an agent is
+                     * most likely to be unsure about at the moment they are deciding
+                     * whether to retire: the order snapshots the LABEL, so retiring
+                     * cannot rewrite what a past dispute said.
+                     */
+                    retiringIsNeverADelete: "Disputes already raised under this reason keep their wording — the order snapshots the label rather than pointing at this row.",
+                } }))] }));
+}

package/dist/features/dispute-reasons/repository/dispute-reasons.repository.d.ts

@@ -32,7 +32,31 @@ export declare class DisputeReasonsRepository extends BaseRepository<DisputeReas
         reason: DisputeReasonDocument;
         created: boolean;
     }>;
+    /**
+     * Every row, retired included — the staff management list.
+     *
+     * 🛑 Deliberately NOT `listActiveByKind` with the `isActive` clause dropped.
+     * That method also pins `kind`, and a management view must span both kinds:
+     * a reason retired for the wrong gate is exactly the row staff need to find.
+     *
+     * No `isActive` filter is applied here at all, so the caller's own Sieve
+     * filters decide — which is what lets the view offer Active / Retired / All
+     * chips without this method growing a parameter per chip.
+     */
+    listAll(model: SieveModel): Promise<FirebaseSieveResult<DisputeReasonDocument>>;
     /** Soft-retire. See the schema for why this is never a delete. */
     retire(id: string): Promise<void>;
+    /**
+     * Put a retired reason back in the picker.
+     *
+     * `createReason` already reactivates on a colliding re-add, which covers the
+     * agent who types the wording again. This covers the different case the
+     * management view creates: a row you can SEE and want back, where re-typing
+     * its exact label to resurrect it would be a trick rather than a control.
+     *
+     * The original `createdByName` is kept — they wrote the wording, and a
+     * reactivation is not authorship.
+     */
+    reactivate(id: string): Promise<void>;
 }
 export declare const disputeReasonsRepository: DisputeReasonsRepository;

package/dist/features/dispute-reasons/repository/dispute-reasons.repository.js

@@ -59,10 +59,38 @@ export class DisputeReasonsRepository extends BaseRepository {
         await this.createWithId(id, reason);
         return { reason, created: true };
     }
+    /**
+     * Every row, retired included — the staff management list.
+     *
+     * 🛑 Deliberately NOT `listActiveByKind` with the `isActive` clause dropped.
+     * That method also pins `kind`, and a management view must span both kinds:
+     * a reason retired for the wrong gate is exactly the row staff need to find.
+     *
+     * No `isActive` filter is applied here at all, so the caller's own Sieve
+     * filters decide — which is what lets the view offer Active / Retired / All
+     * chips without this method growing a parameter per chip.
+     */
+    async listAll(model) {
+        return this.sieveQuery(model, DisputeReasonsRepository.SIEVE_FIELDS, { baseQuery: this.getCollection(), defaultPageSize: 20, maxPageSize: 50 });
+    }
     /** Soft-retire. See the schema for why this is never a delete. */
     async retire(id) {
         await this.update(id, { isActive: false, updatedAt: new Date() });
     }
+    /**
+     * Put a retired reason back in the picker.
+     *
+     * `createReason` already reactivates on a colliding re-add, which covers the
+     * agent who types the wording again. This covers the different case the
+     * management view creates: a row you can SEE and want back, where re-typing
+     * its exact label to resurrect it would be a trick rather than a control.
+     *
+     * The original `createdByName` is kept — they wrote the wording, and a
+     * reactivation is not authorship.
+     */
+    async reactivate(id) {
+        await this.update(id, { isActive: true, updatedAt: new Date() });
+    }
 }
 DisputeReasonsRepository.SIEVE_FIELDS = {
     /*

package/dist/features/dispute-reasons/schemas/firestore.d.ts

@@ -22,10 +22,10 @@
  * should be able to add it without a release.
  */
 import type { DisputeKind } from "../../../_internal/shared/features/orders/dispute-reasons";
+import type { BaseDocument } from "../../../_internal/shared/types/base-document";
 export declare const DISPUTE_REASON_COLLECTION = "disputeReasons";
-export interface DisputeReasonDocument {
-    /** `dreason-<slug of label>`, so the same reason cannot be added twice. */
-    id: string;
+/** `id` is `dreason-<slug of label>`, so the same reason cannot be added twice. */
+export interface DisputeReasonDocument extends BaseDocument {
     /** Buyer-facing. Shown verbatim in the picker. */
     label: string;
     /** Which gate this reason is subject to. Never free-form. */
@@ -43,8 +43,6 @@ export interface DisputeReasonDocument {
     createdByName: string;
     /** The uid, for moderation. Never rendered. */
     createdByUid: string;
-    createdAt: Date;
-    updatedAt: Date;
 }
 export declare const DISPUTE_REASON_FIELDS: {
     readonly ID: "id";

package/dist/features/events/components/EventSaleBanner.js

@@ -16,5 +16,5 @@ export function EventSaleBanner({ discountPercent, couponCode, title, subtitle,
     const href = filterParam
         ? `${ROUTES.PUBLIC.PRODUCTS}?${encodeURIComponent(filterParam.key)}=${encodeURIComponent(filterParam.value)}`
         : `${ROUTES.PUBLIC.PRODUCTS}?onSale=true`;
-    return (_jsx(Section, { color: "inverse", tone: "accent-banner", className: `${__P.p6}`, rounded: "2xl", shadow: "lg", children: _jsxs(Stack, { gap: "md", children: [_jsxs(Stack, { gap: "xs", children: [_jsx(Heading, { level: 2, weight: "bold", size: "3xl", children: headline }), subtitle ? _jsx(Text, { color: "inverse-muted", size: "base", children: subtitle }) : null] }), couponCode ? (_jsxs(Div, { layout: "inline-flex", gap: "3", align: "center", className: "backdrop-blur", surface: "default", paddingY: "y-xs", paddingX: "x-md", rounded: "lg", children: [_jsx(Span, { size: "xs", className: "tracking-wide opacity-80", transform: "uppercase", children: "Code" }), _jsx(Span, { size: "lg", weight: "bold", className: "font-mono", children: couponCode })] })) : null, _jsx(Div, { children: _jsx(Link, { href: href, children: _jsx(Button, { variant: "secondary", children: "Shop the sale" }) }) })] }) }));
+    return (_jsx(Section, { color: "inverse", tone: "accent-banner", className: `${__P.p6}`, rounded: "2xl", shadow: "lg", children: _jsxs(Stack, { gap: "md", children: [_jsxs(Stack, { gap: "xs", children: [_jsx(Heading, { color: "inverse", variant: "none", level: 2, weight: "bold", size: "3xl", children: headline }), subtitle ? _jsx(Text, { color: "inverse-muted", size: "base", children: subtitle }) : null] }), couponCode ? (_jsxs(Div, { layout: "inline-flex", gap: "3", align: "center", className: "backdrop-blur", surface: "default", paddingY: "y-xs", paddingX: "x-md", rounded: "lg", children: [_jsx(Span, { size: "xs", className: "tracking-wide opacity-80", transform: "uppercase", children: "Code" }), _jsx(Span, { size: "lg", weight: "bold", className: "font-mono", children: couponCode })] })) : null, _jsx(Div, { children: _jsx(Link, { href: href, children: _jsx(Button, { variant: "secondary", children: "Shop the sale" }) }) })] }) }));
 }

package/dist/features/faq/components/FAQPageContent.js

@@ -45,12 +45,12 @@ export function FAQPageContent({ initialCategory = "all", categories, routeHelpe
                     total,
                     categoryCounts,
                     onSelect: handleCategorySelect,
-                }) }), _jsxs(Div, { layout: "grid", gap: "8", className: "grid-cols-1 lg:grid-cols-12", children: [_jsx(Div, { className: "hidden lg:col-span-4 lg:block xl:col-span-3", children: _jsx(FAQCategorySidebar, { selectedCategory: selectedCategory, onCategorySelect: handleCategorySelect, categoryCounts: categoryCounts, categories: categories, allFaqsHref: routeHelpers.allFaqsHref, categoryHref: routeHelpers.faqCategoryHref, contactHref: routeHelpers.contactHref, labels: {
+                }) }), _jsxs(Div, { layout: "grid", gap: "8", className: "lg:grid-cols-12", children: [_jsx(Div, { className: "hidden lg:col-span-4 lg:block xl:col-span-3", children: _jsx(FAQCategorySidebar, { selectedCategory: selectedCategory, onCategorySelect: handleCategorySelect, categoryCounts: categoryCounts, categories: categories, allFaqsHref: routeHelpers.allFaqsHref, categoryHref: routeHelpers.faqCategoryHref, contactHref: routeHelpers.contactHref, labels: {
                                 title: labels.categoriesTitle,
                                 allFaqs: labels.allFaqs,
                                 stillHaveQuestions: labels.stillHaveQuestions,
                                 contactSupport: labels.contactSupport,
-                            } }) }), _jsxs(Div, { className: "col-span-1 lg:col-span-8 xl:col-span-9", children: [_jsx(SlottedListingView, { portal: "public", inlineToolbar: true, className: "space-y-6", renderHeader: () => {
+                            } }) }), _jsxs(Div, { className: "lg:col-span-8 xl:col-span-9", children: [_jsx(SlottedListingView, { portal: "public", inlineToolbar: true, className: "space-y-6", renderHeader: () => {
                                     /*
                                      * The fuller answer, next to the short ones.
                                      *

package/dist/features/gateway-events/schemas/index.d.ts

@@ -44,13 +44,13 @@ export declare const gatewayEventFirestoreSchema: z.ZodObject<{
     terminal?: boolean | undefined;
     amount?: number | undefined;
     seedPurpose?: string | undefined;
+    payload?: Record<string, unknown> | undefined;
     orderIds?: string[] | undefined;
     processedAt?: Date | undefined;
     gatewayPaymentId?: string | undefined;
     gatewayOrderId?: string | undefined;
     providerEventId?: string | undefined;
     lastError?: string | undefined;
-    payload?: Record<string, unknown> | undefined;
     payloadTruncated?: boolean | undefined;
 }, {
     status: "received" | "failed" | "processed" | "processing" | "conflict" | "ignored";
@@ -69,13 +69,13 @@ export declare const gatewayEventFirestoreSchema: z.ZodObject<{
     terminal?: boolean | undefined;
     amount?: number | undefined;
     seedPurpose?: string | undefined;
+    payload?: Record<string, unknown> | undefined;
     orderIds?: string[] | undefined;
     processedAt?: Date | undefined;
     gatewayPaymentId?: string | undefined;
     gatewayOrderId?: string | undefined;
     providerEventId?: string | undefined;
     lastError?: string | undefined;
-    payload?: Record<string, unknown> | undefined;
     payloadTruncated?: boolean | undefined;
 }>;
 export type GatewayEventFromSchema = z.infer<typeof gatewayEventFirestoreSchema>;

package/dist/features/homepage/schemas/index.d.ts

@@ -867,16 +867,16 @@ export declare const carouselSlideFirestoreSchema: z.ZodObject<{
         opacity?: number | undefined;
         subtitle?: string | undefined;
     } | undefined;
+    settings?: {
+        height?: "medium" | "viewport" | "tall" | undefined;
+        autoplayDelayMs?: number | undefined;
+    } | undefined;
     analytics?: {
         views: number;
         lastViewed?: string | Date | z.objectOutputType<{
             toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
         }, z.ZodTypeAny, "passthrough"> | undefined;
     } | undefined;
-    settings?: {
-        height?: "medium" | "viewport" | "tall" | undefined;
-        autoplayDelayMs?: number | undefined;
-    } | undefined;
     carouselId?: string | null | undefined;
 }, {
     id: string;
@@ -976,16 +976,16 @@ export declare const carouselSlideFirestoreSchema: z.ZodObject<{
         opacity?: number | undefined;
         subtitle?: string | undefined;
     } | undefined;
+    settings?: {
+        height?: "medium" | "viewport" | "tall" | undefined;
+        autoplayDelayMs?: number | undefined;
+    } | undefined;
     analytics?: {
         views: number;
         lastViewed?: string | Date | z.objectInputType<{
             toDate: z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodDate>;
         }, z.ZodTypeAny, "passthrough"> | undefined;
     } | undefined;
-    settings?: {
-        height?: "medium" | "viewport" | "tall" | undefined;
-        autoplayDelayMs?: number | undefined;
-    } | undefined;
     carouselId?: string | null | undefined;
 }>;
 export type HomepageSectionFromSchema = z.infer<typeof homepageSectionFirestoreSchema>;

package/dist/features/inventory/schemas/stock-reservation.d.ts

@@ -0,0 +1,114 @@
+/**
+ * A HOLD on stock that is not yet an order.
+ *
+ * ## 🛑 Why this has to exist before S5b (Part 6)
+ *
+ * The plan calls this "the largest hidden cost" of the shared-purchase work,
+ * and the reason is that today there is no way to hold stock at all. The only
+ * mechanism is: `onOrderCreate` decrements `availableQuantity`, and
+ * `pendingOrderTimeout` puts it back if the buyer does not pay inside the
+ * 15-minute window. Both are keyed to an ORDER.
+ *
+ * A shared purchase runs for DAYS while co-buyers pay. With no primitive,
+ * either the coordinator places an order up front — which starts a 15-minute
+ * payment clock on a multi-day agreement — or nothing is held, and the item is
+ * sold out from under the arrangement by an ordinary buyer who happened to
+ * check out first. Neither is a product.
+ *
+ * ## The invariant, and where it already lives
+ *
+ * `products.repository.ts` already states it:
+ *
+ *     reserved = stockQuantity - availableQuantity
+ *
+ * …as the comment on `resolveStockResync` puts it, *"the difference between
+ * the two IS the outstanding reservation"*. This collection does not invent a
+ * new idea; it makes that difference ADDRESSABLE — every held unit gets a row
+ * saying who holds it and until when, instead of being an anonymous gap
+ * between two numbers that only an order can close.
+ *
+ * 🛑 So a reservation MUST move `availableQuantity` in the same transaction
+ * that writes its row. A row without the decrement holds nothing; a decrement
+ * without a row is the anonymous gap again, and nothing can expire it.
+ *
+ * ## Why a TTL rather than a cancel button
+ *
+ * A hold with no expiry is a leak: the holder closes the tab, and those units
+ * are off the shelf until a human notices. `expiresAt` means the worst case is
+ * bounded by the sweep interval, and the seller never has to ask anyone to
+ * release anything.
+ */
+import type { BaseDocument } from "../../../_internal/shared/types/base-document";
+export declare const STOCK_RESERVATION_COLLECTION = "stockReservations";
+/**
+ * Who is holding, and therefore what releases it.
+ *
+ * 🛑 A plain `holderId: string` was the first draft and it is wrong: the sweep
+ * and the release path both need to know WHICH system owns the hold before
+ * they can decide whether it is still legitimate. A discriminator makes
+ * "release every hold belonging to arrangement X" expressible; an opaque id
+ * makes it a string-prefix convention nobody enforces.
+ */
+export declare const RESERVATION_HOLDER_KINDS: readonly ["shared-purchase", "manual"];
+export type ReservationHolderKind = (typeof RESERVATION_HOLDER_KINDS)[number];
+/**
+ * 🛑 `cart` and `order` are deliberately NOT holder kinds.
+ *
+ * A cart holds nothing today — adding an item does not decrement anything —
+ * and making it hold would silently turn every abandoned cart into held
+ * stock. An order already has its own hold through `onOrderCreate` +
+ * `pendingOrderTimeout`; a second mechanism over the same units would
+ * double-decrement, which is exactly the class of bug `resolveStockResync`'s
+ * delta exists to prevent. Add a kind only when the thing that owns it also
+ * owns its release.
+ */
+export declare const RESERVATION_STATUSES: readonly ["held", "consumed", "released", "expired"];
+export type ReservationStatus = (typeof RESERVATION_STATUSES)[number];
+export interface StockReservationDocument extends BaseDocument {
+    productId: string;
+    /** Denormalised so the sweep can restore stock without reading the product first. */
+    quantity: number;
+    holderKind: ReservationHolderKind;
+    /** The arrangement / manual-hold id. Scoped by `holderKind`, never globally unique. */
+    holderId: string;
+    /** Who asked for it — an Auth uid, for the audit trail and for admin release. */
+    createdBy: string;
+    status: ReservationStatus;
+    /**
+     * 🛑 The whole point. A hold with no expiry is a leak: the holder closes the
+     * tab and the units are gone until a human notices.
+     */
+    expiresAt: Date;
+    /**
+     * Set when the hold ENDS, whichever way it ended. One field rather than
+     * three (`consumedAt`/`releasedAt`/`expiredAt`) because `status` already
+     * says which, and three nullable dates is three chances for the one that
+     * matters to be the one nobody set.
+     */
+    endedAt?: Date;
+    /** Free text on a manual release — why an admin took the hold back. */
+    endedReason?: string;
+}
+/** Default hold, when a caller names none. */
+export declare const RESERVATION_DEFAULT_TTL_HOURS = 72;
+/**
+ * 🛑 A ceiling, and it is load-bearing rather than defensive.
+ *
+ * A caller may pass any TTL it likes, which makes "hold this for a year" one
+ * typo away — and a year-long hold is indistinguishable from permanently
+ * deleted stock, because nothing in the UI shows a seller why their own
+ * product is unbuyable. 30 days is longer than any agreement window Part 6
+ * contemplates and short enough that a mistake self-heals.
+ */
+export declare const RESERVATION_MAX_TTL_HOURS: number;
+/** A reservation is only holding stock while it is `held` and unexpired. */
+export declare function isReservationActive(reservation: Pick<StockReservationDocument, "status" | "expiresAt">, now?: Date): boolean;
+/**
+ * Firestore hands back a `Timestamp`, a `Date` or an ISO string depending on
+ * the path a document took to get here, and the adapter that normalises those
+ * is not reachable from this file. Returning `null` on anything unparseable is
+ * the honest answer — and callers treat an unparseable expiry as NOT active,
+ * so the failure mode is a hold released early rather than one held forever.
+ */
+declare function toDate(value: unknown): Date | null;
+export { toDate as reservationExpiryDate };