@mohasinac/appkit 4.60.1 → 4.62.0

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

@@ -135,6 +135,7 @@ const DEFAULT_DRAFT = {
     status: "draft",
     createdBy: "",
     allowGuestParticipation: false,
+    isPinned: false,
     discountPercent: "10",
     saleBannerText: "",
     couponId: "",
@@ -211,6 +212,72 @@ function SpinPrizesEditor({ values, onChange, }) {
     return (_jsxs(Stack, { gap: "sm", rounded: "lg", border: "default", padding: "sm", children: [_jsx(Text, { size: "xs", weight: "medium", color: "muted", children: "Spin prizes (weighted random)" }), values.spinPrizes.length === 0 && (_jsx(Text, { size: "xs", color: "muted", children: "No spin prizes yet. Add at least one to enable spinning." })), values.spinPrizes.map((p) => (_jsxs(Grid, { align: "end", gap: "xs", className: "grid-cols-12", children: [_jsx(Div, { className: "col-span-5", children: _jsx(Input, { label: "Label", value: p.label, onChange: (e) => onChange({ spinPrizes: values.spinPrizes.map((sp) => sp.id === p.id ? { ...sp, label: e.target.value } : sp) }), placeholder: "\u20B9100 off" }) }), _jsxs(Div, { className: "col-span-3", children: [_jsx(Text, { size: "xs", weight: "medium", className: "mb-1", children: "Coupon" }), _jsx(CouponInlineSelect, { scope: "admin", value: p.couponId ?? "", onChange: (id) => onChange({ spinPrizes: values.spinPrizes.map((sp) => sp.id === p.id ? { ...sp, couponId: id || undefined } : sp) }), placeholder: "Search\u2026", allowCreate: false })] }), _jsx(Div, { className: "col-span-2", children: _jsx(Input, { label: "Weight", type: "number", value: String(p.weight), onChange: (e) => onChange({ spinPrizes: values.spinPrizes.map((sp) => sp.id === p.id ? { ...sp, weight: Number(e.target.value) || 0 } : sp) }) }) }), _jsx(Row, { centered: true, className: "col-span-1", padding: "b-xs", children: _jsx(Toggle, { checked: p.isActive, onChange: (v) => onChange({ spinPrizes: values.spinPrizes.map((sp) => sp.id === p.id ? { ...sp, isActive: v } : sp) }), label: "" }) }), _jsx(Row, { centered: true, className: "col-span-1", padding: "b-xs", children: _jsx(Button, { variant: "ghost", type: "button", onClick: () => onChange({ spinPrizes: values.spinPrizes.filter((sp) => sp.id !== p.id) }), className: CLS_REMOVE_BTN_LG, "aria-label": "Remove prize", children: "\u00D7" }) })] }, p.id))), _jsx(Button, { type: "button", variant: "outline", size: "sm", onClick: () => onChange({ spinPrizes: [...values.spinPrizes, { id: `prize-${Date.now()}`, label: "", couponId: undefined, weight: 1, isActive: true }] }), children: "+ Add spin prize" }), _jsx(Input, { label: "Max spins per user", type: "number", value: values.spinMaxPerUser, onChange: (e) => onChange({ spinMaxPerUser: e.target.value }), placeholder: "1" }), _jsxs(Grid, { cols: 2, gap: "sm", children: [_jsx(Input, { label: "Spin window start", type: "datetime-local", value: values.spinWindowStart, onChange: (e) => onChange({ spinWindowStart: e.target.value }) }), _jsx(Input, { label: "Spin window end", type: "datetime-local", value: values.spinWindowEnd, onChange: (e) => onChange({ spinWindowEnd: e.target.value }) })] })] }));
 }
 // --- Component ---------------------------------------------------------------
+/**
+ * The API's event shape -> the editor's draft shape.
+ *
+ * A pure adapter at module scope. The extraction is not cosmetic: this was
+ * 45 lines of field mapping inside a `useEffect` inside a 455-line
+ * component, which is exactly where a wrong default hides.
+ *
+ * Every `|| ""` and `Boolean()` is load-bearing. An ABSENT field — any event
+ * predating the one that added it — must still seed a CONTROLLED input;
+ * `undefined` makes React treat it as uncontrolled and the field stops
+ * accepting edits.
+ *
+ * 🛑 `requireLogin: event.surveyConfig?.requireLogin !== false` is the one
+ * default deliberately INVERTED — absent means true, because a survey that
+ * silently stopped requiring a login would collect anonymous entries nobody
+ * asked for. Do not "tidy" it into `Boolean(...)`.
+ */
+function eventToDraft(event) {
+    return {
+        type: event.type || "sale",
+        title: event.title || "",
+        slug: event.slug || "",
+        description: event.description || "",
+        startsAt: toLocalDatetime(event.startsAt),
+        endsAt: toLocalDatetime(event.endsAt),
+        coverImageUrl: event.coverImageUrl || event.coverImage?.url || "",
+        tags: Array.isArray(event.tags) ? event.tags : [],
+        status: event.status || "draft",
+        createdBy: event.createdBy || "",
+        allowGuestParticipation: Boolean(event.allowGuestParticipation),
+        // `Boolean()` so an ABSENT field (every event predating the pin) seeds
+        // the toggle as off rather than leaving it `undefined`, which React
+        // would read as an uncontrolled input.
+        isPinned: Boolean(event.isPinned),
+        discountPercent: String(event.saleConfig?.discountPercent ?? 10),
+        saleBannerText: event.saleConfig?.bannerText || "",
+        couponId: event.offerConfig?.couponId || "",
+        displayCode: event.offerConfig?.displayCode || "",
+        offerBannerText: event.offerConfig?.bannerText || "",
+        pollOptions: event.pollConfig?.options?.length
+            ? event.pollConfig.options
+            : [{ id: "opt1", label: "" }, { id: "opt2", label: "" }],
+        allowMultiSelect: Boolean(event.pollConfig?.allowMultiSelect),
+        allowComment: Boolean(event.pollConfig?.allowComment),
+        resultsVisibility: event.pollConfig?.resultsVisibility || "always",
+        requireLogin: event.surveyConfig?.requireLogin !== false,
+        maxEntriesPerUser: String(event.surveyConfig?.maxEntriesPerUser ?? 1),
+        hasLeaderboard: Boolean(event.surveyConfig?.hasLeaderboard),
+        hasPointSystem: Boolean(event.surveyConfig?.hasPointSystem),
+        pointsLabel: event.surveyConfig?.pointsLabel ?? "Points",
+        entryReviewRequired: Boolean(event.surveyConfig?.entryReviewRequired),
+        surveyFields: Array.isArray(event.surveyConfig?.formFields) ? event.surveyConfig.formFields : [],
+        anonymous: Boolean(event.feedbackConfig?.anonymous),
+        feedbackFields: Array.isArray(event.feedbackConfig?.formFields) ? event.feedbackConfig.formFields : [],
+        hasRaffle: Boolean(event.hasRaffle),
+        raffleType: event.raffleType || "open_raffle",
+        raffleTopN: String(event.raffleTopN ?? 10),
+        rafflePrize: event.rafflePrize || "",
+        rafflePrizeCouponId: event.rafflePrizeCouponId || "",
+        rafflePrizeProductIds: Array.isArray(event.rafflePrizeProductIds) ? event.rafflePrizeProductIds : [],
+        spinPrizes: Array.isArray(event.spinPrizes) ? event.spinPrizes : [],
+        spinMaxPerUser: String(event.spinMaxPerUser ?? 1),
+        spinWindowStart: toLocalDatetime(event.spinWindowStart),
+        spinWindowEnd: toLocalDatetime(event.spinWindowEnd),
+    };
+}
 export function AdminEventEditorView({ eventId, onSaved, embedded, allowedTypes, ...rest }) {
     const isEdit = Boolean(eventId);
     const [draft, setDraft] = React.useState(DEFAULT_DRAFT);
@@ -243,49 +310,8 @@ export function AdminEventEditorView({ eventId, onSaved, embedded, allowedTypes,
         const event = eventQuery.data?.data ?? eventQuery.data;
         if (!event?.id)
             return;
-        setDraft({
-            type: event.type || "sale",
-            title: event.title || "",
-            slug: event.slug || "",
-            description: event.description || "",
-            startsAt: toLocalDatetime(event.startsAt),
-            endsAt: toLocalDatetime(event.endsAt),
-            coverImageUrl: event.coverImageUrl || event.coverImage?.url || "",
-            tags: Array.isArray(event.tags) ? event.tags : [],
-            status: event.status || "draft",
-            createdBy: event.createdBy || "",
-            allowGuestParticipation: Boolean(event.allowGuestParticipation),
-            discountPercent: String(event.saleConfig?.discountPercent ?? 10),
-            saleBannerText: event.saleConfig?.bannerText || "",
-            couponId: event.offerConfig?.couponId || "",
-            displayCode: event.offerConfig?.displayCode || "",
-            offerBannerText: event.offerConfig?.bannerText || "",
-            pollOptions: event.pollConfig?.options?.length
-                ? event.pollConfig.options
-                : [{ id: "opt1", label: "" }, { id: "opt2", label: "" }],
-            allowMultiSelect: Boolean(event.pollConfig?.allowMultiSelect),
-            allowComment: Boolean(event.pollConfig?.allowComment),
-            resultsVisibility: event.pollConfig?.resultsVisibility || "always",
-            requireLogin: event.surveyConfig?.requireLogin !== false,
-            maxEntriesPerUser: String(event.surveyConfig?.maxEntriesPerUser ?? 1),
-            hasLeaderboard: Boolean(event.surveyConfig?.hasLeaderboard),
-            hasPointSystem: Boolean(event.surveyConfig?.hasPointSystem),
-            pointsLabel: event.surveyConfig?.pointsLabel ?? "Points",
-            entryReviewRequired: Boolean(event.surveyConfig?.entryReviewRequired),
-            surveyFields: Array.isArray(event.surveyConfig?.formFields) ? event.surveyConfig.formFields : [],
-            anonymous: Boolean(event.feedbackConfig?.anonymous),
-            feedbackFields: Array.isArray(event.feedbackConfig?.formFields) ? event.feedbackConfig.formFields : [],
-            hasRaffle: Boolean(event.hasRaffle),
-            raffleType: event.raffleType || "open_raffle",
-            raffleTopN: String(event.raffleTopN ?? 10),
-            rafflePrize: event.rafflePrize || "",
-            rafflePrizeCouponId: event.rafflePrizeCouponId || "",
-            rafflePrizeProductIds: Array.isArray(event.rafflePrizeProductIds) ? event.rafflePrizeProductIds : [],
-            spinPrizes: Array.isArray(event.spinPrizes) ? event.spinPrizes : [],
-            spinMaxPerUser: String(event.spinMaxPerUser ?? 1),
-            spinWindowStart: toLocalDatetime(event.spinWindowStart),
-            spinWindowEnd: toLocalDatetime(event.spinWindowEnd),
-        });
+        // The 45-line field mapping lives in `eventToDraft` at module scope.
+        setDraft(eventToDraft(event));
         setSlugManual(true);
         setRaffleWinnerName(event.raffleWinnerDisplayName || "");
         setRaffleEntryCount(typeof event.raffleEntryCount === "number" ? event.raffleEntryCount : null);
@@ -304,6 +330,7 @@ export function AdminEventEditorView({ eventId, onSaved, embedded, allowedTypes,
                 endsAt: toISOString(draft.endsAt),
                 coverImageUrl: draft.coverImageUrl || undefined,
                 allowGuestParticipation: draft.allowGuestParticipation,
+                isPinned: draft.isPinned,
                 ...buildEventTypeConfig(draft),
                 ...buildEventRaffleFields(draft),
             };
@@ -380,10 +407,10 @@ export function AdminEventEditorView({ eventId, onSaved, embedded, allowedTypes,
             // The per-step `validate` is gone: every rule it stated is already in
             // eventDraftSchema (title/startsAt/endsAt are .min(1)), and it only ever
             // acted as a gate to the next step.
-            render: ({ values, onChange }) => (_jsxs(Stack, { gap: "md", children: [_jsx(Heading, { level: 3, className: "mb-2", children: "Event Details" }), !isEdit && (_jsx(Select, { label: "Event type", value: values.type, options: allowedTypes ? EVENT_TYPE_OPTIONS.filter((o) => allowedTypes.includes(o.value)) : EVENT_TYPE_OPTIONS, onChange: (e) => onChange({ type: e.target.value }) })), _jsx(Input, { label: "Title", value: values.title, onChange: (e) => {
+            render: ({ values, onChange, errors }) => (_jsxs(Stack, { gap: "md", children: [_jsx(Heading, { level: 3, className: "mb-2", children: "Event Details" }), !isEdit && (_jsx(Select, { label: "Event type", error: errors.type, value: values.type, options: allowedTypes ? EVENT_TYPE_OPTIONS.filter((o) => allowedTypes.includes(o.value)) : EVENT_TYPE_OPTIONS, onChange: (e) => onChange({ type: e.target.value }) })), _jsx(Input, { label: "Title", error: errors.title, value: values.title, onChange: (e) => {
                             const v = e.target.value;
                             onChange({ title: v, ...(!slugManual && { slug: toEventSlug(v) }) });
-                        }, placeholder: "Charizard Flash Sale 2026", required: true }), _jsx(Input, { label: "Slug", value: values.slug, onChange: (e) => { setSlugManual(true); onChange({ slug: e.target.value }); }, placeholder: "event-charizard-flash-sale-2026", helperText: "Auto-generated from title. Must start with 'event-'." }), _jsxs(Stack, { gap: "xs", children: [_jsx(Label, { children: "Description" }), _jsx(RichTextEditor, { value: values.description, onChange: (v) => onChange({ description: v }), minHeightClassName: "min-h-[120px]", placeholder: "Describe this event\u2026" })] }), _jsxs(Grid, { cols: 2, gap: "sm", children: [_jsx(Input, { label: "Starts at", type: "datetime-local", value: values.startsAt, onChange: (e) => onChange({ startsAt: e.target.value }), required: true }), _jsx(Input, { label: "Ends at", type: "datetime-local", value: values.endsAt, onChange: (e) => onChange({ endsAt: e.target.value }), required: true })] }), _jsx(TagInput, { label: "Tags", value: values.tags, onChange: (t) => onChange({ tags: t }), placeholder: "e.g. pokemon, sale, 2026" })] })),
+                        }, placeholder: "Charizard Flash Sale 2026", required: true }), _jsx(Input, { label: "Slug", error: errors.slug, value: values.slug, onChange: (e) => { setSlugManual(true); onChange({ slug: e.target.value }); }, placeholder: "event-charizard-flash-sale-2026", helperText: "Auto-generated from title. Must start with 'event-'." }), _jsxs(Stack, { gap: "xs", children: [_jsx(Label, { children: "Description" }), _jsx(RichTextEditor, { value: values.description, onChange: (v) => onChange({ description: v }), minHeightClassName: "min-h-[120px]", placeholder: "Describe this event\u2026" })] }), _jsxs(Grid, { cols: 2, gap: "sm", children: [_jsx(Input, { label: "Starts at", error: errors.startsAt, type: "datetime-local", value: values.startsAt, onChange: (e) => onChange({ startsAt: e.target.value }), required: true }), _jsx(Input, { label: "Ends at", error: errors.endsAt, type: "datetime-local", value: values.endsAt, onChange: (e) => onChange({ endsAt: e.target.value }), required: true })] }), _jsx(TagInput, { label: "Tags", value: values.tags, onChange: (t) => onChange({ tags: t }), placeholder: "e.g. pokemon, sale, 2026" })] })),
         },
         {
             id: "media",
@@ -392,26 +419,28 @@ export function AdminEventEditorView({ eventId, onSaved, embedded, allowedTypes,
             // section mid-upload discards the transfer.
             keepMounted: true,
             fields: ["coverImageUrl"],
-            render: ({ values, onChange }) => (_jsxs(Stack, { gap: "md", children: [_jsx(Heading, { level: 3, className: "mb-2", children: "Media" }), _jsx(Input, { label: "Cover Image URL (optional)", value: values.coverImageUrl, onChange: (e) => onChange({ coverImageUrl: e.target.value }), placeholder: "https://\u2026", helperText: "Direct link to the event cover image." })] })),
+            render: ({ values, onChange, errors }) => (_jsxs(Stack, { gap: "md", children: [_jsx(Heading, { level: 3, className: "mb-2", children: "Media" }), _jsx(Input, { label: "Cover Image URL (optional)", error: errors.coverImageUrl, value: values.coverImageUrl, onChange: (e) => onChange({ coverImageUrl: e.target.value }), placeholder: "https://\u2026", helperText: "Direct link to the event cover image." })] })),
         },
         {
             id: "settings",
             label: "Settings",
-            fields: ["status", "allowGuestParticipation", "discountPercent", "saleBannerText", "couponId", "displayCode", "offerBannerText", "pollOptions", "resultsVisibility", "allowMultiSelect", "allowComment", "maxEntriesPerUser", "hasLeaderboard", "hasPointSystem", "pointsLabel", "entryReviewRequired", "surveyFields", "anonymous", "feedbackFields"],
+            fields: ["status", "allowGuestParticipation", "isPinned", "discountPercent", "saleBannerText", "couponId", "displayCode", "offerBannerText", "pollOptions", "resultsVisibility", "allowMultiSelect", "allowComment", "maxEntriesPerUser", "hasLeaderboard", "hasPointSystem", "pointsLabel", "entryReviewRequired", "surveyFields", "anonymous", "feedbackFields"],
             // Same: the offer-coupon, offer-display-code and poll-minimum-options
             // rules are all stated in eventDraftSchema's superRefine, which now
             // surfaces them inline on the field instead of as a step-blocking banner.
-            render: ({ values, onChange }) => (_jsxs(Stack, { gap: "md", children: [_jsx(Heading, { level: 3, className: "mb-2", children: "Event Settings" }), isEdit && (_jsx(Select, { label: "Status", value: values.status, options: EVENT_STATUS_OPTIONS, onChange: (e) => onChange({ status: e.target.value }) })), values.createdBy && (_jsxs(Stack, { gap: "none", children: [_jsx(Text, { size: "sm", weight: "medium", className: "mb-1", children: "Created by" }), _jsx(Text, { size: "sm", color: "muted", children: values.createdBy })] })), _jsxs(Stack, { gap: "xs", surface: "muted", rounded: "lg", border: "default", padding: "sm", children: [_jsx(Toggle, { checked: values.allowGuestParticipation, onChange: (v) => onChange({ allowGuestParticipation: v }), label: "Allow guest participation (no login required)" }), _jsx(Text, { size: "xs", color: "muted", children: "When enabled, unauthenticated visitors can participate in this event (poll vote, survey/feedback response, raffle entry, or wheel spin), identified by a hashed IP address instead of an account. Applies uniformly to whatever entry mechanism this event type uses." })] }), values.type === "sale" && (_jsxs(Stack, { gap: "xs", surface: "muted", rounded: "lg", border: "default", padding: "sm", children: [_jsx(Text, { size: "sm", weight: "semibold", color: "muted", children: "Sale configuration" }), _jsxs(Grid, { cols: 2, gap: "sm", children: [_jsx(Input, { label: "Discount %", type: "number", value: values.discountPercent, onChange: (e) => onChange({ discountPercent: e.target.value }), placeholder: "10" }), _jsx(Input, { label: "Banner text (optional)", value: values.saleBannerText, onChange: (e) => onChange({ saleBannerText: e.target.value }), placeholder: "Limited time \u2014 ends Sunday!" })] })] })), values.type === "offer" && (_jsxs(Stack, { gap: "xs", surface: "muted", rounded: "lg", border: "default", padding: "sm", children: [_jsx(Text, { size: "sm", weight: "semibold", color: "muted", children: "Offer configuration" }), _jsxs(Grid, { cols: 2, gap: "sm", children: [_jsxs(Div, { children: [_jsx(Text, { size: "sm", weight: "medium", className: "mb-1", children: "Coupon" }), _jsx(CouponInlineSelect, { scope: "admin", value: values.couponId, onChange: (id) => onChange({ couponId: id ?? "" }), placeholder: "Search coupons\u2026", allowCreate: false })] }), _jsx(Input, { label: "Display code", value: values.displayCode, onChange: (e) => onChange({ displayCode: e.target.value }), placeholder: "CHARIZARD25", required: true })] }), _jsx(Input, { label: "Banner text (optional)", value: values.offerBannerText, onChange: (e) => onChange({ offerBannerText: e.target.value }), placeholder: "Use CHARIZARD25 at checkout" })] })), values.type === "poll" && (_jsxs(Stack, { gap: "md", rounded: "xl", border: "default", padding: "md", children: [_jsx(Text, { size: "sm", weight: "semibold", color: "muted", children: "Poll configuration" }), _jsxs(Stack, { gap: "xs", children: [_jsx(Text, { size: "xs", color: "muted", children: "Options (minimum 2)" }), values.pollOptions.map((opt, idx) => (_jsxs(Row, { gap: "xs", children: [_jsx(Div, { className: "flex-1", children: _jsx(Input, { value: opt.label, onChange: (e) => onChange({ pollOptions: values.pollOptions.map((o) => o.id === opt.id ? { ...o, label: e.target.value } : o) }), placeholder: `Option ${idx + 1}` }) }), values.pollOptions.length > 2 && (_jsx(Button, { variant: "ghost", type: "button", onClick: () => onChange({ pollOptions: values.pollOptions.filter((o) => o.id !== opt.id) }), className: CLS_REMOVE_BTN_PX2, "aria-label": "Remove option", children: "\u00D7" }))] }, opt.id))), _jsx(Button, { type: "button", variant: "outline", size: "sm", onClick: () => onChange({ pollOptions: [...values.pollOptions, { id: `opt${Date.now()}`, label: "" }] }), children: "+ Add option" })] }), _jsx(Select, { label: "Results visibility", value: values.resultsVisibility, options: POLL_VISIBILITY_OPTIONS, onChange: (e) => onChange({ resultsVisibility: e.target.value }) }), _jsxs(Stack, { gap: "sm", children: [_jsx(Toggle, { checked: values.allowMultiSelect, onChange: (v) => onChange({ allowMultiSelect: v }), label: "Allow multi-select" }), _jsx(Toggle, { checked: values.allowComment, onChange: (v) => onChange({ allowComment: v }), label: "Allow comment with vote" })] })] })), values.type === "survey" && (_jsxs(Stack, { gap: "md", rounded: "xl", border: "default", padding: "md", children: [_jsx(Text, { size: "sm", weight: "semibold", color: "muted", children: "Survey configuration" }), _jsxs(Grid, { cols: 2, gap: "sm", children: [_jsx(Input, { label: "Max entries per user", type: "number", value: values.maxEntriesPerUser, onChange: (e) => onChange({ maxEntriesPerUser: e.target.value }), placeholder: "1" }), values.hasPointSystem && (_jsx(Input, { label: "Points label", value: values.pointsLabel, onChange: (e) => onChange({ pointsLabel: e.target.value }), placeholder: "Points" }))] }), _jsxs(Stack, { gap: "xs", children: [_jsx(Toggle, { checked: values.requireLogin, onChange: (v) => onChange({ requireLogin: v }), label: "Require login to participate" }), _jsx(Toggle, { checked: values.hasLeaderboard, onChange: (v) => onChange({ hasLeaderboard: v }), label: "Show leaderboard" }), _jsx(Toggle, { checked: values.hasPointSystem, onChange: (v) => onChange({ hasPointSystem: v }), label: "Enable point system" }), _jsx(Toggle, { checked: values.entryReviewRequired, onChange: (v) => onChange({ entryReviewRequired: v }), label: "Require employee review before entry is approved" })] }), _jsx(FormFieldBuilder, { fields: values.surveyFields, setFields: (f) => onChange({ surveyFields: f }) })] })), values.type === "feedback" && (_jsxs(Stack, { gap: "md", rounded: "xl", border: "default", padding: "md", children: [_jsx(Text, { size: "sm", weight: "semibold", color: "muted", children: "Feedback configuration" }), _jsx(Toggle, { checked: values.anonymous, onChange: (v) => onChange({ anonymous: v }), label: "Allow anonymous submissions" }), _jsx(FormFieldBuilder, { fields: values.feedbackFields, setFields: (f) => onChange({ feedbackFields: f }) })] }))] })),
+            render: ({ values, onChange, errors }) => (_jsxs(Stack, { gap: "md", children: [_jsx(Heading, { level: 3, className: "mb-2", children: "Event Settings" }), isEdit && (_jsx(Select, { label: "Status", error: errors.status, value: values.status, options: EVENT_STATUS_OPTIONS, onChange: (e) => onChange({ status: e.target.value }) })), values.createdBy && (_jsxs(Stack, { gap: "none", children: [_jsx(Text, { size: "sm", weight: "medium", className: "mb-1", children: "Created by" }), _jsx(Text, { size: "sm", color: "muted", children: values.createdBy })] })), _jsxs(Stack, { gap: "xs", surface: "muted", rounded: "lg", border: "default", padding: "sm", children: [_jsx(Toggle, { checked: values.allowGuestParticipation, onChange: (v) => onChange({ allowGuestParticipation: v }), label: "Allow guest participation (no login required)" }), _jsx(Text, { size: "xs", color: "muted", children: "When enabled, unauthenticated visitors can participate in this event (poll vote, survey/feedback response, raffle entry, or wheel spin), identified by a hashed IP address instead of an account. Applies uniformly to whatever entry mechanism this event type uses." })] }), _jsxs(Stack, { gap: "xs", surface: "muted", rounded: "lg", border: "default", padding: "sm", children: [_jsx(Toggle, { checked: values.isPinned, onChange: (v) => onChange({ isPinned: v }), label: "Pin to the top of Events" }), _jsx(Text, { size: "xs", color: "muted", children: "Pinned events are listed first on the Events page and in the homepage strip, ahead of the usual soonest-first order. A pinned event still has to be Active to appear at all \u2014 pinning does not publish it." })] }), values.type === "sale" && (_jsxs(Stack, { gap: "xs", surface: "muted", rounded: "lg", border: "default", padding: "sm", children: [_jsx(Text, { size: "sm", weight: "semibold", color: "muted", children: "Sale configuration" }), _jsxs(Grid, { cols: 2, gap: "sm", children: [_jsx(Input, { label: "Discount %", error: errors.discountPercent, type: "number", value: values.discountPercent, onChange: (e) => onChange({ discountPercent: e.target.value }), placeholder: "10" }), _jsx(Input, { label: "Banner text (optional)", value: values.saleBannerText, error: errors.saleBannerText, onChange: (e) => onChange({ saleBannerText: e.target.value }), placeholder: "Limited time \u2014 ends Sunday!" })] })] })), values.type === "offer" && (_jsxs(Stack, { gap: "xs", surface: "muted", rounded: "lg", border: "default", padding: "sm", children: [_jsx(Text, { size: "sm", weight: "semibold", color: "muted", children: "Offer configuration" }), _jsxs(Grid, { cols: 2, gap: "sm", children: [_jsxs(Div, { children: [_jsx(Text, { size: "sm", weight: "medium", className: "mb-1", children: "Coupon" }), _jsx(CouponInlineSelect, { scope: "admin", value: values.couponId, onChange: (id) => onChange({ couponId: id ?? "" }), placeholder: "Search coupons\u2026", allowCreate: false })] }), _jsx(Input, { label: "Display code", error: errors.displayCode, value: values.displayCode, onChange: (e) => onChange({ displayCode: e.target.value }), placeholder: "CHARIZARD25", required: true })] }), _jsx(Input, { label: "Banner text (optional)", value: values.offerBannerText, error: errors.offerBannerText, onChange: (e) => onChange({ offerBannerText: e.target.value }), placeholder: "Use CHARIZARD25 at checkout" })] })), values.type === "poll" && (_jsxs(Stack, { gap: "md", rounded: "xl", border: "default", padding: "md", children: [_jsx(Text, { size: "sm", weight: "semibold", color: "muted", children: "Poll configuration" }), _jsxs(Stack, { gap: "xs", children: [_jsx(Text, { size: "xs", color: "muted", children: "Options (minimum 2)" }), values.pollOptions.map((opt, idx) => (_jsxs(Row, { gap: "xs", children: [_jsx(Div, { className: "flex-1", children: _jsx(Input, { value: opt.label, 
+                                                    /* Indexed: a failure on option 2 arrives as `pollOptions.1.label`. */
+                                                    error: errors[`pollOptions.${idx}.label`], onChange: (e) => onChange({ pollOptions: values.pollOptions.map((o) => o.id === opt.id ? { ...o, label: e.target.value } : o) }), placeholder: `Option ${idx + 1}` }) }), values.pollOptions.length > 2 && (_jsx(Button, { variant: "ghost", type: "button", onClick: () => onChange({ pollOptions: values.pollOptions.filter((o) => o.id !== opt.id) }), className: CLS_REMOVE_BTN_PX2, "aria-label": "Remove option", children: "\u00D7" }))] }, opt.id))), _jsx(Button, { type: "button", variant: "outline", size: "sm", onClick: () => onChange({ pollOptions: [...values.pollOptions, { id: `opt${Date.now()}`, label: "" }] }), children: "+ Add option" })] }), _jsx(Select, { label: "Results visibility", error: errors.resultsVisibility, value: values.resultsVisibility, options: POLL_VISIBILITY_OPTIONS, onChange: (e) => onChange({ resultsVisibility: e.target.value }) }), _jsxs(Stack, { gap: "sm", children: [_jsx(Toggle, { checked: values.allowMultiSelect, onChange: (v) => onChange({ allowMultiSelect: v }), label: "Allow multi-select" }), _jsx(Toggle, { checked: values.allowComment, onChange: (v) => onChange({ allowComment: v }), label: "Allow comment with vote" })] })] })), values.type === "survey" && (_jsxs(Stack, { gap: "md", rounded: "xl", border: "default", padding: "md", children: [_jsx(Text, { size: "sm", weight: "semibold", color: "muted", children: "Survey configuration" }), _jsxs(Grid, { cols: 2, gap: "sm", children: [_jsx(Input, { label: "Max entries per user", error: errors.maxEntriesPerUser, type: "number", value: values.maxEntriesPerUser, onChange: (e) => onChange({ maxEntriesPerUser: e.target.value }), placeholder: "1" }), values.hasPointSystem && (_jsx(Input, { label: "Points label", error: errors.pointsLabel, value: values.pointsLabel, onChange: (e) => onChange({ pointsLabel: e.target.value }), placeholder: "Points" }))] }), _jsxs(Stack, { gap: "xs", children: [_jsx(Toggle, { checked: values.requireLogin, onChange: (v) => onChange({ requireLogin: v }), label: "Require login to participate" }), _jsx(Toggle, { checked: values.hasLeaderboard, onChange: (v) => onChange({ hasLeaderboard: v }), label: "Show leaderboard" }), _jsx(Toggle, { checked: values.hasPointSystem, onChange: (v) => onChange({ hasPointSystem: v }), label: "Enable point system" }), _jsx(Toggle, { checked: values.entryReviewRequired, onChange: (v) => onChange({ entryReviewRequired: v }), label: "Require employee review before entry is approved" })] }), _jsx(FormFieldBuilder, { fields: values.surveyFields, setFields: (f) => onChange({ surveyFields: f }) })] })), values.type === "feedback" && (_jsxs(Stack, { gap: "md", rounded: "xl", border: "default", padding: "md", children: [_jsx(Text, { size: "sm", weight: "semibold", color: "muted", children: "Feedback configuration" }), _jsx(Toggle, { checked: values.anonymous, onChange: (v) => onChange({ anonymous: v }), label: "Allow anonymous submissions" }), _jsx(FormFieldBuilder, { fields: values.feedbackFields, setFields: (f) => onChange({ feedbackFields: f }) })] }))] })),
         },
         {
             id: "raffle",
             label: "Raffle / Spin",
             fields: ["hasRaffle", "raffleType", "raffleTopN", "rafflePrize", "rafflePrizeCouponId", "rafflePrizeProductIds", "spinPrizes", "spinMaxPerUser", "spinWindowStart", "spinWindowEnd"],
-            render: ({ values, onChange }) => {
+            render: ({ values, onChange, errors }) => {
                 const isRaffleType = values.type === "raffle" || values.type === "spin_wheel";
                 const showRaffleConfig = isRaffleType || values.hasRaffle;
                 const isSpinMode = values.type === "spin_wheel" || values.raffleType === "spin_wheel";
-                return (_jsxs(Stack, { gap: "md", children: [_jsx(Heading, { level: 3, className: "mb-2", children: "Raffle & Spin Wheel" }), !isRaffleType && (_jsx(Toggle, { checked: values.hasRaffle, onChange: (v) => onChange({ hasRaffle: v }), label: "Attach a raffle to this event" })), !isRaffleType && !values.hasRaffle && (_jsx(Text, { size: "sm", color: "muted", children: "Enable the toggle above to attach a raffle draw to this event. Not applicable for this event type by default." })), showRaffleConfig && (_jsxs(Stack, { gap: "md", rounded: "xl", border: "default", padding: "md", children: [_jsxs(Grid, { cols: 2, gap: "sm", children: [_jsx(Select, { label: "Raffle type", value: values.type === "spin_wheel" ? "spin_wheel" : values.raffleType, options: RAFFLE_TYPE_OPTIONS, onChange: (e) => onChange({ raffleType: e.target.value }), disabled: values.type === "spin_wheel" }), _jsx(Input, { label: "Top N (for top-N raffle types)", type: "number", value: values.raffleTopN, onChange: (e) => onChange({ raffleTopN: e.target.value }), placeholder: "10" })] }), _jsx(Input, { label: "Prize description", value: values.rafflePrize, onChange: (e) => onChange({ rafflePrize: e.target.value }), placeholder: "\u20B92,000 store credit + exclusive Pikachu sticker" }), _jsxs(Div, { children: [_jsx(Text, { size: "sm", weight: "medium", className: "mb-1", children: "Coupon for winner (optional)" }), _jsx(CouponInlineSelect, { scope: "admin", value: values.rafflePrizeCouponId, onChange: (id) => onChange({ rafflePrizeCouponId: id ?? "" }), placeholder: "Search coupons\u2026", allowCreate: false })] }), _jsxs(Div, { children: [_jsx(Text, { size: "sm", weight: "medium", className: "mb-1", children: "Prize products (optional)" }), _jsx(ProductInlineSelect, { scope: "admin", multiple: true, value: values.rafflePrizeProductIds, onChange: (ids) => onChange({ rafflePrizeProductIds: ids }), placeholder: "Search products to feature as prizes\u2026" }), _jsx(Text, { size: "xs", color: "muted", className: "mt-1", children: "Products shown to winners or displayed as the prize showcase." })] }), isSpinMode && _jsx(SpinPrizesEditor, { values: values, onChange: onChange }), isEdit && (_jsxs(Stack, { gap: "xs", rounded: "lg", padding: "sm", className: CLS_RAFFLE_PANEL, children: [_jsxs(Row, { justify: "between", gap: "sm", children: [_jsx(Text, { size: "sm", weight: "medium", className: CLS_RAFFLE_HEADING, children: raffleWinnerName ? `Winner: ${raffleWinnerName}` : "Raffle not yet triggered" }), _jsx(Button, { type: "button", action: ACTIONS.EVENT["draw-raffle-winner"], size: "sm", onClick: () => triggerRaffleMutation.mutate(), disabled: triggerRaffleMutation.isPending || Boolean(raffleWinnerName), children: triggerRaffleMutation.isPending ? "Triggering…" : raffleWinnerName ? "Already triggered" : "Trigger Raffle Now" })] }), raffleEntryCount !== null && _jsxs(Text, { size: "xs", className: CLS_RAFFLE_BODY, children: ["Pool size: ", raffleEntryCount] }), raffleGithubUrl && _jsxs(Text, { size: "xs", className: `break-all ${CLS_RAFFLE_BODY}`, children: ["Fairness proof: ", raffleGithubUrl] }), triggerMessage && _jsx(Text, { size: "xs", className: CLS_RAFFLE_HEADING, children: triggerMessage })] }))] }))] }));
+                return (_jsxs(Stack, { gap: "md", children: [_jsx(Heading, { level: 3, className: "mb-2", children: "Raffle & Spin Wheel" }), !isRaffleType && (_jsx(Toggle, { checked: values.hasRaffle, onChange: (v) => onChange({ hasRaffle: v }), label: "Attach a raffle to this event" })), !isRaffleType && !values.hasRaffle && (_jsx(Text, { size: "sm", color: "muted", children: "Enable the toggle above to attach a raffle draw to this event. Not applicable for this event type by default." })), showRaffleConfig && (_jsxs(Stack, { gap: "md", rounded: "xl", border: "default", padding: "md", children: [_jsxs(Grid, { cols: 2, gap: "sm", children: [_jsx(Select, { label: "Raffle type", error: errors.raffleType, value: values.type === "spin_wheel" ? "spin_wheel" : values.raffleType, options: RAFFLE_TYPE_OPTIONS, onChange: (e) => onChange({ raffleType: e.target.value }), disabled: values.type === "spin_wheel" }), _jsx(Input, { label: "Top N (for top-N raffle types)", error: errors.raffleTopN, type: "number", value: values.raffleTopN, onChange: (e) => onChange({ raffleTopN: e.target.value }), placeholder: "10" })] }), _jsx(Input, { label: "Prize description", error: errors.rafflePrize, value: values.rafflePrize, onChange: (e) => onChange({ rafflePrize: e.target.value }), placeholder: "\u20B92,000 store credit + exclusive Pikachu sticker" }), _jsxs(Div, { children: [_jsx(Text, { size: "sm", weight: "medium", className: "mb-1", children: "Coupon for winner (optional)" }), _jsx(CouponInlineSelect, { scope: "admin", value: values.rafflePrizeCouponId, onChange: (id) => onChange({ rafflePrizeCouponId: id ?? "" }), placeholder: "Search coupons\u2026", allowCreate: false })] }), _jsxs(Div, { children: [_jsx(Text, { size: "sm", weight: "medium", className: "mb-1", children: "Prize products (optional)" }), _jsx(ProductInlineSelect, { scope: "admin", multiple: true, value: values.rafflePrizeProductIds, onChange: (ids) => onChange({ rafflePrizeProductIds: ids }), placeholder: "Search products to feature as prizes\u2026" }), _jsx(Text, { size: "xs", color: "muted", className: "mt-1", children: "Products shown to winners or displayed as the prize showcase." })] }), isSpinMode && _jsx(SpinPrizesEditor, { values: values, onChange: onChange }), isEdit && (_jsxs(Stack, { gap: "xs", rounded: "lg", padding: "sm", className: CLS_RAFFLE_PANEL, children: [_jsxs(Row, { justify: "between", gap: "sm", children: [_jsx(Text, { size: "sm", weight: "medium", className: CLS_RAFFLE_HEADING, children: raffleWinnerName ? `Winner: ${raffleWinnerName}` : "Raffle not yet triggered" }), _jsx(Button, { type: "button", action: ACTIONS.EVENT["draw-raffle-winner"], size: "sm", onClick: () => triggerRaffleMutation.mutate(), disabled: triggerRaffleMutation.isPending || Boolean(raffleWinnerName), children: triggerRaffleMutation.isPending ? "Triggering…" : raffleWinnerName ? "Already triggered" : "Trigger Raffle Now" })] }), raffleEntryCount !== null && _jsxs(Text, { size: "xs", className: CLS_RAFFLE_BODY, children: ["Pool size: ", raffleEntryCount] }), raffleGithubUrl && _jsxs(Text, { size: "xs", className: `break-all ${CLS_RAFFLE_BODY}`, children: ["Fairness proof: ", raffleGithubUrl] }), triggerMessage && _jsx(Text, { size: "xs", className: CLS_RAFFLE_HEADING, children: triggerMessage })] }))] }))] }));
             },
         },
     ];

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

@@ -8,6 +8,7 @@ import { sieveFilter, sieveMultiEq, sieveAnd, SIEVE_OP } from "../../../utils/si
 import { sortBy } from "../../../constants/sort.js";
 import { safeRead } from "../../../errors/safe-read.js";
 import { hidePublicTestData } from "../../../_internal/server/features/tester/visibility.js";
+import { sortPinnedFirst } from "../utils/sort-pinned.js";
 function sp(params, key) {
     const v = params[key];
     return Array.isArray(v) ? v[0] ?? "" : v ?? "";
@@ -69,7 +70,7 @@ export async function EventsListPageView({ searchParams = {} }) {
      * refetch threads the real viewer, so a signed-in tester still sees them.
      */
     const publicResult = result
-        ? { ...result, items: hidePublicTestData(result.items) }
+        ? { ...result, items: sortPinnedFirst(hidePublicTestData(result.items)) }
         : result;
     return (_jsx(Main, { children: _jsx(Section, { padding: "y-2xl", children: _jsxs(Container, { size: "xl", children: [_jsx(Heading, { level: 1, className: "mb-8", color: "primary", size: "3xl", weight: "semibold", children: "Events" }), _jsx(AdSlot, { id: "listing-sidebar-top", className: "mb-6" }), _jsx(EventsIndexListing, { initialData: publicResult, facetCounts: facetCounts }), _jsx(AdSlot, { id: "listing-sidebar-bottom", className: "mt-8" })] }) }) }));
 }

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

@@ -17,6 +17,22 @@ export interface EventDocument extends BaseDocument {
     title: string;
     description: string;
     status: EventStatus;
+    /**
+     * Lift this event to the top of `/events` and the homepage rail, ahead of
+     * the `startsAt` ASC default.
+     *
+     * 🛑 DELIBERATELY NOT IN `EVENT_INDEXED_FIELDS` AND NOT SORTABLE IN SIEVE.
+     * A Firestore `orderBy` EXCLUDES every document that lacks the ordering
+     * field (Root Cause #100), and `isPinned` is absent from all 1 live event
+     * and every seeded row that is not pinned — so ordering by it would empty
+     * the events page entirely while answering HTTP 200. The ordering is
+     * applied in memory by `sortPinnedFirst`; see the bound stated there.
+     *
+     * Absent means not pinned. Do not default it to `false` on write — a
+     * written `false` and an absent field must stay interchangeable, because
+     * every event that predates this field has the latter.
+     */
+    isPinned?: boolean;
     /** Test-data flag — set on the shared admin-seeded test event; swept by testDataCleanup. */
     isTestData?: boolean;
     /** When isTestData, the cutoff after which testDataCleanup deletes this doc. */
@@ -134,6 +150,7 @@ export declare const EVENT_FIELDS: {
     readonly WINNER_IMAGES: "winnerImages";
     readonly ADDITIONAL_IMAGES: "additionalImages";
     readonly TAGS: "tags";
+    readonly IS_PINNED: "isPinned";
     readonly ALLOW_GUEST_PARTICIPATION: "allowGuestParticipation";
     readonly CREATED_BY: "createdBy";
     readonly CREATED_AT: "createdAt";

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

@@ -38,6 +38,7 @@ export const EVENT_FIELDS = {
     WINNER_IMAGES: "winnerImages",
     ADDITIONAL_IMAGES: "additionalImages",
     TAGS: "tags",
+    IS_PINNED: "isPinned",
     ALLOW_GUEST_PARTICIPATION: "allowGuestParticipation",
     CREATED_BY: "createdBy",
     CREATED_AT: "createdAt",

package/dist/features/events/utils/sort-pinned.d.ts

@@ -0,0 +1,33 @@
+/** Just the part of an event this ordering reads. */
+export interface PinnableEvent {
+    isPinned?: boolean;
+}
+/**
+ * Lift pinned events to the front, preserving the relative order of both
+ * groups.
+ *
+ * 🛑 WHY THIS IS IN MEMORY AND NOT AN `orderBy`. Firestore's `orderBy`
+ * excludes every document that lacks the ordering field (Root Cause #100), and
+ * `isPinned` is absent from every event that is not pinned — which is all of
+ * them bar one. Sorting on it in the query would return an events page
+ * containing only the pinned row, with no error and a 200, and the failure
+ * reads as "the other events were deleted" rather than as a bad sort.
+ *
+ * A boolean is also a one-bit sort key, so it would need a composite index
+ * paired with `startsAt` for every filter combination the page offers, to buy
+ * an ordering a single pass over at most `pageSize` rows already gives.
+ *
+ * 🛑 THE BOUND, STATED RATHER THAN IMPLIED: this reorders WITHIN the page it
+ * is handed. A pinned event that falls on page 3 of a paginated result is
+ * lifted to the top of page 3, not onto page 1. That is sufficient while the
+ * whole catalogue fits one page — live holds 1 event against a pageSize of
+ * 24, and the homepage rail asks for 6 — and it is the reason to revisit this
+ * if events ever outgrow a single page. The fix then is a second bounded
+ * query on `isPinned == true` (an EQUALITY, which is index-friendly and does
+ * not have the missing-field problem an `orderBy` has) merged ahead of the
+ * main result, not an `orderBy` on this field.
+ *
+ * `Array.prototype.sort` is specified as stable, so the comparator only needs
+ * to express the pinned/unpinned difference to leave everything else alone.
+ */
+export declare function sortPinnedFirst<T extends PinnableEvent>(items: readonly T[]): T[];

package/dist/features/events/utils/sort-pinned.js

@@ -0,0 +1,46 @@
+/*
+ * WHY: One implementation of "pinned events come first", shared by the two
+ *      surfaces that render an event list.
+ * WHAT: `sortPinnedFirst` — a stable partition on `EventDocument.isPinned`.
+ *
+ * EXPORTS:
+ *   sortPinnedFirst — readonly T[] -> T[], pinned first, order otherwise kept
+ *
+ * @tag domain:events
+ * @tag layer:util
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:features/events/components/EventsListPageView.tsx,features/events/actions/event-actions.ts
+ * @tag sideEffects:none
+ */
+/**
+ * Lift pinned events to the front, preserving the relative order of both
+ * groups.
+ *
+ * 🛑 WHY THIS IS IN MEMORY AND NOT AN `orderBy`. Firestore's `orderBy`
+ * excludes every document that lacks the ordering field (Root Cause #100), and
+ * `isPinned` is absent from every event that is not pinned — which is all of
+ * them bar one. Sorting on it in the query would return an events page
+ * containing only the pinned row, with no error and a 200, and the failure
+ * reads as "the other events were deleted" rather than as a bad sort.
+ *
+ * A boolean is also a one-bit sort key, so it would need a composite index
+ * paired with `startsAt` for every filter combination the page offers, to buy
+ * an ordering a single pass over at most `pageSize` rows already gives.
+ *
+ * 🛑 THE BOUND, STATED RATHER THAN IMPLIED: this reorders WITHIN the page it
+ * is handed. A pinned event that falls on page 3 of a paginated result is
+ * lifted to the top of page 3, not onto page 1. That is sufficient while the
+ * whole catalogue fits one page — live holds 1 event against a pageSize of
+ * 24, and the homepage rail asks for 6 — and it is the reason to revisit this
+ * if events ever outgrow a single page. The fix then is a second bounded
+ * query on `isPinned == true` (an EQUALITY, which is index-friendly and does
+ * not have the missing-field problem an `orderBy` has) merged ahead of the
+ * main result, not an `orderBy` on this field.
+ *
+ * `Array.prototype.sort` is specified as stable, so the comparator only needs
+ * to express the pinned/unpinned difference to leave everything else alone.
+ */
+export function sortPinnedFirst(items) {
+    return [...items].sort((a, b) => Number(b.isPinned === true) - Number(a.isPinned === true));
+}

package/dist/features/gateway-events/repository/gateway-events.repository.js

@@ -1,46 +1,9 @@
+// One shared predicate — this file had its own copy; see firestore-codes.ts.
+import { isAlreadyExistsError } from "../../../errors/firestore-codes.js";
 import { BaseRepository, applySieveToFirestore, parseSieveDateValue, prepareForFirestore, } from "../../../providers/db-firebase/index.js";
 import { normalizeError } from "../../../errors/normalize.js";
 import { GATEWAY_EVENTS_COLLECTION, GATEWAY_EVENT_ERROR_MAX_BYTES, GATEWAY_EVENT_FIELDS, GATEWAY_EVENT_LEASE_SECONDS, GATEWAY_EVENT_RETENTION_DAYS, createGatewayEventId, } from "../schemas/firestore.js";
 /** gRPC `ALREADY_EXISTS`. The one failure of `.create()` that means "duplicate". */
-const GRPC_ALREADY_EXISTS = 6;
-/**
- * Is this the specific "a document with that id already exists" failure, as
- * opposed to any other write failure?
- *
- * 🛑 THIS DISTINCTION IS THE WHOLE POINT, and it is where the inbox differs
- * from every other `.create()` claim in the codebase.
- *
- * `refunds/actions.ts` catches *every* error from its claim and treats it as a
- * duplicate — and that is correct THERE, because the cost of being wrong is
- * issuing a second real refund, so it must fail CLOSED.
- *
- * Here the cost of being wrong is inverted: treating a permissions error or a
- * Firestore outage as "already have it" would make the route ack 200 and the
- * event would be **silently lost** — which is the exact failure this collection
- * exists to prevent. So the inbox fails OPEN: anything that is not
- * ALREADY_EXISTS propagates, the route answers 503, and the gateway sends it
- * again.
- *
- * Same primitive, opposite failure direction, because the asymmetry of harm is
- * opposite. Do not "unify" these two call sites.
- */
-function isAlreadyExists(err) {
-    if (typeof err !== "object" || err === null)
-        return false;
-    const code = err.code;
-    if (code === GRPC_ALREADY_EXISTS)
-        return true;
-    /*
-     * The Admin SDK has also surfaced this as a string code and as a plain
-     * message depending on version and transport. Checked in addition to, never
-     * instead of, the numeric code — a message test alone is the kind of
-     * stringly-typed guard that breaks silently on an SDK bump.
-     */
-    if (code === "already-exists" || code === "ALREADY_EXISTS")
-        return true;
-    const message = err.message;
-    return typeof message === "string" && message.includes("ALREADY_EXISTS");
-}
 function truncate(value, maxBytes) {
     if (!value)
         return undefined;
@@ -86,7 +49,7 @@ export class GatewayEventsRepository extends BaseRepository {
             return { claimed: true, id, doc };
         }
         catch (err) {
-            if (isAlreadyExists(err)) {
+            if (isAlreadyExistsError(err)) {
                 void normalizeError(err);
                 return { claimed: false, id };
             }

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

@@ -34,12 +34,12 @@ export declare const gatewayEventFirestoreSchema: z.ZodObject<{
     createdAt: Date;
     updatedAt: Date;
     expiresAt: Date;
+    claimedAt: Date;
     gateway: string;
     receivedAt: Date;
     attempts: number;
     bodySha256: string;
     leaseExpiresAt: Date;
-    claimedAt: Date;
     rawEvent: string;
     terminal?: boolean | undefined;
     amount?: number | undefined;
@@ -59,12 +59,12 @@ export declare const gatewayEventFirestoreSchema: z.ZodObject<{
     createdAt: Date;
     updatedAt: Date;
     expiresAt: Date;
+    claimedAt: Date;
     gateway: string;
     receivedAt: Date;
     attempts: number;
     bodySha256: string;
     leaseExpiresAt: Date;
-    claimedAt: Date;
     rawEvent: string;
     terminal?: boolean | undefined;
     amount?: number | undefined;

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

@@ -16,9 +16,10 @@ import { Button, Div, Form, FieldInput, FieldSelect, Stack, Text } from "../../.
 import { ADMIN_ENDPOINTS } from "../../../constants/api-endpoints.js";
 import { apiClient } from "../../../http/index.js";
 import { sortBy } from "../../../constants/sort.js";
+import { normalizeError } from "../../../errors/normalize.js";
 import { sieveFilter, SIEVE_OP } from "../../../utils/sieve-builder.js";
 import { operatorMessage } from "./operator-message.js";
-import { BoxTypeValues } from "../schemas/firestore.js";
+import { BoxTypeValues, STORAGE_BOX_FIELDS, } from "../schemas/firestore.js";
 const TYPE_OPTIONS = BoxTypeValues.map((v) => ({ value: v, label: v }));
 /**
  * The register-a-box form.
@@ -26,47 +27,58 @@ const TYPE_OPTIONS = BoxTypeValues.map((v) => ({ value: v, label: v }));
  * Exported because it is a PAGE now, not a drawer — see the note on
  * `primaryAction` below for why create could not share the row affordance.
  */
+// audit-form-sectionised-ok: a three-field quick create (code, type, location),
+// not a multi-section editor. <SectionForm> derives its sections from a schema
+// and pins a mobile action bar for a long scroll; neither has anything to do
+// here, and sections of one field each would be chrome around three inputs.
 export function RegisterBoxForm({ onCreated }) {
     const [code, setCode] = React.useState("");
     const [boxType, setBoxType] = React.useState(BoxTypeValues[0]);
     const [location, setLocation] = React.useState("");
     const [busy, setBusy] = React.useState(false);
-    return (_jsx(Form, { onSubmit: (e) => e.preventDefault(), className: "space-y-4", children: ({ setFieldError, clearErrors }) => (_jsxs(Stack, { gap: "md", children: [_jsx(FieldInput, { name: "code", label: "Box code", required: true, value: code, onChange: setCode, placeholder: "AC60-03", hint: "Exactly what is written on the physical label." }), _jsx(FieldSelect, { name: "boxType", label: "Box type", value: boxType, onChange: setBoxType, options: TYPE_OPTIONS }), _jsx(FieldInput, { name: "location", label: "Where it is", value: location, onChange: setLocation, placeholder: "Shelf B, second from top" }), _jsx(Text, { size: "xs", color: "muted", children: "A second box with the same code is the same box \u2014 the registry refuses a duplicate rather than merging two." }), _jsx(Div, { children: _jsx(Button, { type: "submit", variant: "primary", isLoading: busy, onClick: async () => {
-                            clearErrors();
-                            if (!code.trim()) {
-                                setFieldError("code", "A box needs a code");
-                                return;
-                            }
-                            setBusy(true);
-                            try {
-                                await apiClient.post(ADMIN_ENDPOINTS.INVENTORY_BOXES, {
-                                    code: code.trim(),
-                                    boxType,
-                                    ...(location.trim() ? { location: location.trim() } : {}),
-                                });
-                                onCreated();
-                            }
-                            catch (err) {
-                                /*
-                                 * 🛑 `operatorMessage`, not a raw fallback. This read
-                                 * `toUserMessage(undefined, undefined, { fallback: e.message })`
-                                 * under a comment claiming it never showed server text —
-                                 * which is false twice over: `undefined` for the code means
-                                 * the map never runs, so the fallback is ALWAYS what shows.
-                                 * A comment asserting the fix while the code reintroduces the
-                                 * bug is how Root Cause #86 would come back, and how the seed
-                                 * `listingType` bug survived its own fix one field over.
-                                 *
-                                 * The split is on status: the 409 here ("Box AC60-03 already
-                                 * exists") is authored for this operator and must survive; a
-                                 * 5xx terminates in a constant.
-                                 */
-                                setFieldError("code", operatorMessage(err));
-                            }
-                            finally {
-                                setBusy(false);
-                            }
-                        }, children: "Register box" }) })] })) }));
+    /*
+     * Lifted out of the submit button's `onClick`, where it sat five braces deep
+     * inside the render-prop's JSX. The two `<Form>` helpers arrive as arguments
+     * rather than being captured, which is what lets this live in the component
+     * body beside the state it writes.
+     */
+    const submitBox = async (setFieldError, clearErrors) => {
+        clearErrors();
+        if (!code.trim()) {
+            setFieldError("code", "A box needs a code");
+            return;
+        }
+        setBusy(true);
+        try {
+            await apiClient.post(ADMIN_ENDPOINTS.INVENTORY_BOXES, {
+                code: code.trim(),
+                boxType,
+                ...(location.trim() ? { location: location.trim() } : {}),
+            });
+            onCreated();
+        }
+        catch (err) {
+            /*
+             * 🛑 `operatorMessage`, not a raw fallback. This read
+             * `toUserMessage(undefined, undefined, { fallback: e.message })`
+             * under a comment claiming it never showed server text — which is
+             * false twice over: `undefined` for the code means the map never
+             * runs, so the fallback is ALWAYS what shows. A comment asserting
+             * the fix while the code reintroduces the bug is how Root Cause #86
+             * would come back, and how the seed `listingType` bug survived its
+             * own fix one field over.
+             *
+             * The split is on status: the 409 here ("Box AC60-03 already
+             * exists") is authored for this operator and must survive; a 5xx
+             * terminates in a constant.
+             */
+            setFieldError("code", operatorMessage(normalizeError(err)));
+        }
+        finally {
+            setBusy(false);
+        }
+    };
+    return (_jsx(Form, { onSubmit: (e) => e.preventDefault(), className: "space-y-4", children: ({ setFieldError, clearErrors }) => (_jsxs(Stack, { gap: "md", children: [_jsx(FieldInput, { name: "code", label: "Box code", required: true, value: code, onChange: setCode, placeholder: "AC60-03", hint: "Exactly what is written on the physical label." }), _jsx(FieldSelect, { name: "boxType", label: "Box type", value: boxType, onChange: setBoxType, options: TYPE_OPTIONS }), _jsx(FieldInput, { name: "location", label: "Where it is", value: location, onChange: setLocation, placeholder: "Shelf B, second from top" }), _jsx(Text, { size: "xs", color: "muted", children: "A second box with the same code is the same box \u2014 the registry refuses a duplicate rather than merging two." }), _jsx(Div, { children: _jsx(Button, { type: "submit", variant: "primary", isLoading: busy, onClick: () => submitBox(setFieldError, clearErrors), children: "Register box" }) })] })) }));
 }
 export function AdminStorageBoxesView() {
     const config = React.useMemo(() => ({
@@ -109,9 +121,13 @@ export function AdminStorageBoxesView() {
          * AC60-2 — the kind of ordering that makes an operator distrust the
          * screen — which is why `ordinal` is denormalised on write.
          */
-        defaultSort: "ordinal",
+        defaultSort: sortBy(STORAGE_BOX_FIELDS.ORDINAL, "ASC"),
         sortOptions: [
-            { value: "ordinal", label: "Box number" },
+            // Same expression as `defaultSort`, not a matching literal beside it —
+            // `sortBy(f, "ASC")` is the bare field, so the two are identical by
+            // construction. A default that is not one of the options opens the
+            // dropdown with nothing selected (Root Cause #63).
+            { value: sortBy(STORAGE_BOX_FIELDS.ORDINAL, "ASC"), label: "Box number" },
             { value: sortBy("createdAt", "DESC"), label: "Newest" },
             { value: sortBy("code", "ASC"), label: "Code A–Z" },
         ],