@mohasinac/appkit 4.63.2 → 4.63.4

package/dist/features/promotions/components/AttachedCouponsSection.js

@@ -0,0 +1,99 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId } from "react";
+import { Badge, Div, Grid, Heading, Stack, Text } from "../../../ui/index.js";
+import { formatCurrency } from "../../../utils/number.formatter.js";
+import { CouponCodeCopyRow } from "./CouponCodeCopyRow.js";
+/**
+ * Headline summary of what a coupon gives — "25% off", "₹200 off",
+ * "Free shipping".
+ *
+ * 🛑 `type` is a plain `string` here, not the `CouponType` union, because this
+ * renders a PROJECTION of a document rather than the document. That is a
+ * deliberate trade: a new coupon type added upstream falls through to the
+ * coupon's own `name` instead of failing to compile. The alternative —
+ * `Record<CouponType, …>` — is the right shape when the exhaustiveness is the
+ * point (Root Cause #61), and the wrong one across a serialisation boundary
+ * where the value has already been stringified.
+ */
+function summarise(coupon) {
+    switch (coupon.type) {
+        case "percentage":
+            return `${coupon.discountValue}% off`;
+        case "fixed":
+            return `${formatCurrency(coupon.discountValue, "INR")} off`;
+        case "free_shipping":
+            return "Free shipping";
+        case "points_earn":
+            return `${coupon.discountValue}% back in points`;
+        default:
+            // buy_x_get_y and anything added later: the name already says it.
+            return null;
+    }
+}
+/** "Min. spend ₹999 · Up to ₹500 off · Ends 10 Nov" — only the parts that exist. */
+function conditionsOf(coupon) {
+    const parts = [];
+    if (coupon.minPurchase)
+        parts.push(`Min. spend ${formatCurrency(coupon.minPurchase, "INR")}`);
+    if (coupon.maxDiscount)
+        parts.push(`Up to ${formatCurrency(coupon.maxDiscount, "INR")} off`);
+    /*
+     * 🛑 An absent `endsAt` means NO END DATE, not "expired" — it is `undefined`
+     * for every open-ended coupon. Rendering "Expired" here would libel every
+     * one of them, and rendering nothing is correct: there is no deadline to
+     * report. Expiry is not this component's job at all; `getAttachedCoupons`
+     * has already dropped anything past its window.
+     */
+    if (coupon.endsAt) {
+        parts.push(`Ends ${new Date(coupon.endsAt).toLocaleDateString("en-IN", { day: "numeric", month: "short" })}`);
+    }
+    return parts.length > 0 ? parts.join(" · ") : null;
+}
+/**
+ * The coupons a piece of content advertises — events and blog posts alike.
+ *
+ * Copy-code only, by design: the reader takes the code to checkout, where
+ * every existing validation, per-user limit and stacking rule already applies
+ * against a real cart. An "apply to cart" button here would have to reproduce
+ * `detectCouponConflict`'s one-seller-coupon-per-store-plus-one-admin rule and
+ * explain its refusals on a page that knows nothing about the cart.
+ *
+ * 🛑 Renders NOTHING when there are no coupons — not an empty state. This sits
+ * inside an article or an event description, and a "no coupons available" box
+ * on the 95% of posts that never had one is noise that makes the 5% harder to
+ * notice.
+ *
+ * 🛑 It deliberately does NOT label which seller a coupon belongs to, even
+ * though `CouponDocument` carries `scope`/`storeId`. A reader cannot act on
+ * that: the coupon either applies to their cart or it does not, and checkout
+ * is where that is decided and explained. Printing a store name here would
+ * imply a scope the card cannot actually enforce.
+ */
+export function AttachedCouponsSection({ coupons, title = "Coupons", description, }) {
+    /*
+     * 🛑 `useId`, not a literal. This component is reusable and nothing stops a
+     * page mounting it twice — a hardcoded id would then appear on two elements
+     * and `aria-labelledby` would resolve to whichever came first, silently
+     * mislabelling the second section. React generates one id per instance.
+     *
+     * Called before the empty-return below because it is a HOOK: an early
+     * return above it would change the hook order between a post with coupons
+     * and one without.
+     */
+    const headingId = useId();
+    if (coupons.length === 0)
+        return null;
+    return (_jsxs(Stack, { gap: "md", "aria-labelledby": headingId, children: [_jsxs(Stack, { gap: "xs", children: [_jsx(Heading, { id: headingId, level: 2, weight: "semibold", size: "xl", children: title }), description ? (_jsx(Text, { size: "sm", color: "muted", children: description })) : null] }), _jsx(Grid, { cols: "cardsWide", gap: "md", children: coupons.map((coupon) => {
+                    const summary = summarise(coupon);
+                    const conditions = conditionsOf(coupon);
+                    /*
+                     * `surface="card"` already carries the border, radius and shadow —
+                     * adding `border=` / `rounded=` beside it emits a second, competing
+                     * set of utilities, and with `important: true` in both Tailwind
+                     * configs the winner is decided by emission order rather than by
+                     * anything readable here (Root Cause #79).
+                     */
+                    return (_jsx(Div, { surface: "card", padding: "card", children: _jsxs(Stack, { gap: "sm", children: [_jsxs(Stack, { gap: "xs", children: [summary ? (_jsx(Div, { children: _jsx(Badge, { variant: "primary", children: summary }) })) : null, _jsx(Text, { weight: "semibold", children: coupon.name }), coupon.description ? (_jsx(Text, { size: "sm", color: "muted", children: coupon.description })) : null] }), _jsx(CouponCodeCopyRow, { code: coupon.code, ariaContext: coupon.name }), conditions ? (_jsx(Text, { size: "xs", color: "muted", children: conditions })) : null] }) }, coupon.id));
+                }) })] }));
+}

package/dist/features/promotions/components/CouponCodeCopyRow.d.ts

@@ -0,0 +1,19 @@
+export interface CouponCodeCopyRowProps {
+    /** The code to copy. Rendered verbatim — it is what the buyer must type. */
+    code: string;
+    /** Accessible context, e.g. the coupon name. Appended to the button label for screen readers. */
+    ariaContext?: string;
+}
+/**
+ * The code + "Copy code" row. ONE implementation, shared by `EventOfferCard`
+ * (offer events, one coupon) and `AttachedCouponsSection` (events and blog
+ * posts, several).
+ *
+ * Extracted rather than copied: this is the second consumer, and the
+ * Duplication Framework's keep-it rule ("Rule of Three — two copies is
+ * observation") is outranked here by its consolidate rule #2, the bug-fix
+ * multiplier. The clipboard call has a real failure mode — it is denied
+ * outright on insecure origins and by permission — and a fix to that handling
+ * in one copy would silently not reach the other.
+ */
+export declare function CouponCodeCopyRow({ code, ariaContext }: CouponCodeCopyRowProps): import("react").JSX.Element;

package/dist/features/promotions/components/CouponCodeCopyRow.js

@@ -0,0 +1,39 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from "react";
+import { normalizeError } from "../../../errors/normalize.js";
+import { Code, Row } from "../../../ui/index.js";
+import { Button } from "../../../ui/components/Button.js";
+/**
+ * The code + "Copy code" row. ONE implementation, shared by `EventOfferCard`
+ * (offer events, one coupon) and `AttachedCouponsSection` (events and blog
+ * posts, several).
+ *
+ * Extracted rather than copied: this is the second consumer, and the
+ * Duplication Framework's keep-it rule ("Rule of Three — two copies is
+ * observation") is outranked here by its consolidate rule #2, the bug-fix
+ * multiplier. The clipboard call has a real failure mode — it is denied
+ * outright on insecure origins and by permission — and a fix to that handling
+ * in one copy would silently not reach the other.
+ */
+export function CouponCodeCopyRow({ code, ariaContext }) {
+    const [copied, setCopied] = useState(false);
+    const copyCode = async () => {
+        try {
+            await navigator.clipboard.writeText(code);
+            setCopied(true);
+            setTimeout(() => setCopied(false), 2000);
+        }
+        catch (_err) {
+            /*
+             * Clipboard access is denied outright on insecure origins and by user
+             * permission. The button simply never flips to "Copied", and the code is
+             * still on screen to select by hand — so the failure costs convenience,
+             * never the ability to use the coupon. Nothing is shown to the user,
+             * because there is nothing they could do about it.
+             */
+            void normalizeError(_err);
+        }
+    };
+    return (_jsxs(Row, { surface: "muted", padding: "inline", align: "center", gap: "3", rounded: "lg", children: [_jsx(Code, { className: "flex-1", weight: "bold", size: "base", color: "primary", children: code }), _jsx(Button, { type: "button", variant: "outline", onClick: copyCode, "aria-label": ariaContext ? `Copy coupon code ${code} — ${ariaContext}` : `Copy coupon code ${code}`, children: copied ? "Copied!" : "Copy code" })] }));
+}

package/dist/features/promotions/components/index.d.ts

@@ -1,3 +1,7 @@
+export { AttachedCouponsSection } from "./AttachedCouponsSection";
+export type { AttachedCouponsSectionProps } from "./AttachedCouponsSection";
+export { CouponCodeCopyRow } from "./CouponCodeCopyRow";
+export type { CouponCodeCopyRowProps } from "./CouponCodeCopyRow";
 export { CouponCard } from "./CouponCard";
 export { CouponHelpDetails } from "./CouponHelpDetails";
 export type { CouponHelpDetailsProps } from "./CouponHelpDetails";

package/dist/features/promotions/components/index.js

@@ -1,3 +1,5 @@
+export { AttachedCouponsSection } from "./AttachedCouponsSection.js";
+export { CouponCodeCopyRow } from "./CouponCodeCopyRow.js";
 export { CouponCard } from "./CouponCard.js";
 export { CouponHelpDetails } from "./CouponHelpDetails.js";
 export { CouponsIndexListing } from "./CouponsIndexListing.js";

package/dist/features/promotions/constants/attached-coupons.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Attached coupons — the contract shared by every layer that carries a set of
+ * coupon ids on a piece of CONTENT (`EventDocument.couponIds`,
+ * `BlogPostDocument.couponIds`).
+ *
+ * This file is deliberately dependency-free: the Zod write schemas, the admin
+ * editors, the repository's batch read and the public renderer all import the
+ * cap from here, so the number cannot drift between what an editor may save
+ * and what a page is willing to read. A cap enforced in one of those four
+ * places is not a cap.
+ */
+/**
+ * Most coupons one event or blog post may carry.
+ *
+ * 🛑 This is a Rule #6 bound, not a style preference. The public event and
+ * blog pages resolve these ids in a Server Component, so the number is a
+ * direct multiplier on a guest-reachable read. Ten is already generous for a
+ * promotion readers are expected to scan; the write schemas reject more, and
+ * `couponsRepository.findByIds` re-clamps so a document hand-edited in the
+ * Firestore console still cannot widen the read.
+ *
+ * Raising it means re-checking both: the schemas AND the repository.
+ */
+export declare const ATTACHED_COUPON_MAX = 10;
+/**
+ * The public projection of a coupon when it is attached to content.
+ *
+ * 🛑 This is an ALLOW-LIST, and the reason it exists is Root Cause #70: a
+ * public payload built by spreading a document and deleting keys publishes
+ * every field nobody thought to delete — including fields the TypeScript
+ * interface never declared. `CouponDocument` carries `usage.currentUsage`,
+ * `analytics.totalRevenue`, `analytics.totalDiscount`, the whole
+ * `restrictions` block and `createdBy`; none of that is a reader's business,
+ * and `analytics.*` is seller revenue.
+ *
+ * Note the existing `GET /api/coupons` returns whole documents. That is
+ * pre-existing and out of scope here — but it is precisely why this path
+ * starts with a projection instead of inheriting the habit.
+ */
+export interface AttachedCoupon {
+    id: string;
+    code: string;
+    name: string;
+    description: string;
+    /** `percentage` | `fixed` | `free_shipping` | `buy_x_get_y` | `points_earn` */
+    type: string;
+    /** The headline number: percent for `percentage`, rupees for `fixed`. */
+    discountValue: number;
+    /** Cap on a percentage discount, in rupees. */
+    maxDiscount?: number;
+    /** Minimum cart value before the coupon applies, in rupees. */
+    minPurchase?: number;
+    /** ISO string — `undefined` means no end date, NOT "expired". */
+    endsAt?: string;
+}

package/dist/features/promotions/constants/attached-coupons.js

@@ -0,0 +1,24 @@
+/**
+ * Attached coupons — the contract shared by every layer that carries a set of
+ * coupon ids on a piece of CONTENT (`EventDocument.couponIds`,
+ * `BlogPostDocument.couponIds`).
+ *
+ * This file is deliberately dependency-free: the Zod write schemas, the admin
+ * editors, the repository's batch read and the public renderer all import the
+ * cap from here, so the number cannot drift between what an editor may save
+ * and what a page is willing to read. A cap enforced in one of those four
+ * places is not a cap.
+ */
+/**
+ * Most coupons one event or blog post may carry.
+ *
+ * 🛑 This is a Rule #6 bound, not a style preference. The public event and
+ * blog pages resolve these ids in a Server Component, so the number is a
+ * direct multiplier on a guest-reachable read. Ten is already generous for a
+ * promotion readers are expected to scan; the write schemas reject more, and
+ * `couponsRepository.findByIds` re-clamps so a document hand-edited in the
+ * Firestore console still cannot widen the read.
+ *
+ * Raising it means re-checking both: the schemas AND the repository.
+ */
+export const ATTACHED_COUPON_MAX = 10;

package/dist/features/promotions/repository/coupons.repository.d.ts

@@ -27,6 +27,26 @@ export declare class CouponsRepository extends BaseRepository<CouponDocument> {
      * @returns Promise<CouponDocument | null>
      */
     getCouponByCode(code: string): Promise<CouponDocument | null>;
+    /**
+     * Batch-read coupons by id, for content that ATTACHES a set of them
+     * (`EventDocument.couponIds`, `BlogPostDocument.couponIds`).
+     *
+     * 🛑 ONE `getAll`, never a loop of `findById`. A blog post carrying six
+     * coupons would otherwise be six sequential round trips on a public,
+     * ISR-regenerated page — Rule #6 budgets about three for a whole request.
+     *
+     * 🛑 Order is PRESERVED and missing ids are DROPPED, not nulled — the same
+     * contract as `categoriesRepository.findByIds`, deliberately, so the two
+     * batch readers in this codebase cannot behave differently. A content
+     * editor's ordering is the display order, and a coupon that was deleted
+     * after being attached must not render as a hole in the grid.
+     *
+     * Bounded at `ATTACHED_COUPON_MAX`. The cap is the reason this is safe to
+     * call from a Server Component: the write schemas enforce the same number,
+     * so a hand-edited Firestore document cannot turn a public page into an
+     * unbounded read.
+     */
+    findByIds(ids: string[]): Promise<CouponDocument[]>;
     /**
      * Get all active coupons
      *

package/dist/features/promotions/repository/coupons.repository.js

@@ -9,6 +9,7 @@ import { serverLogger } from "../../../monitoring/server-logger.js";
  */
 import { BaseRepository, prepareForFirestore, parseSieveDateValue, } from "../../../providers/db-firebase/index.js";
 import { COUPONS_COLLECTION, COUPON_FIELDS, isValidCouponCode, isCouponValid, canUserUseCoupon, calculateDiscount, createCouponId, } from "../schemas/index.js";
+import { ATTACHED_COUPON_MAX } from "../constants/attached-coupons.js";
 import { USER_COLLECTION } from "../../auth/schemas/index.js";
 import { DatabaseError } from "../../../errors/index.js";
 import { increment, arrayUnion, serverTimestamp } from "../../../contracts/field-ops.js";
@@ -71,6 +72,44 @@ export class CouponsRepository extends BaseRepository {
             throw new DatabaseError(`Failed to retrieve coupon by code: ${error instanceof Error ? error.message : "Unknown error"}`);
         }
     }
+    /**
+     * Batch-read coupons by id, for content that ATTACHES a set of them
+     * (`EventDocument.couponIds`, `BlogPostDocument.couponIds`).
+     *
+     * 🛑 ONE `getAll`, never a loop of `findById`. A blog post carrying six
+     * coupons would otherwise be six sequential round trips on a public,
+     * ISR-regenerated page — Rule #6 budgets about three for a whole request.
+     *
+     * 🛑 Order is PRESERVED and missing ids are DROPPED, not nulled — the same
+     * contract as `categoriesRepository.findByIds`, deliberately, so the two
+     * batch readers in this codebase cannot behave differently. A content
+     * editor's ordering is the display order, and a coupon that was deleted
+     * after being attached must not render as a hole in the grid.
+     *
+     * Bounded at `ATTACHED_COUPON_MAX`. The cap is the reason this is safe to
+     * call from a Server Component: the write schemas enforce the same number,
+     * so a hand-edited Firestore document cannot turn a public page into an
+     * unbounded read.
+     */
+    async findByIds(ids) {
+        const unique = Array.from(new Set(ids.filter(Boolean))).slice(0, ATTACHED_COUPON_MAX);
+        if (unique.length === 0)
+            return [];
+        try {
+            const refs = unique.map((id) => this.db.collection(this.collection).doc(id));
+            const snaps = await this.db.getAll(...refs);
+            return snaps.filter((s) => s.exists).map((s) => this.mapDoc(s));
+        }
+        catch (error) {
+            const e = normalizeError(error);
+            /*
+             * `kind` and a COUNT, never the raw message and never the ids —
+             * Root Cause #86 (a thrown message is written for a developer and this
+             * one can reach a user through a 500) plus Hobby's ~4 KB/s log budget.
+             */
+            throw new DatabaseError(`Failed to batch-read ${unique.length} coupon(s) by id (${e.kind})`);
+        }
+    }
     /**
      * Get all active coupons
      *

package/dist/features/promotions/schemas/attached-coupons.d.ts

@@ -0,0 +1,39 @@
+import { z } from "zod";
+/**
+ * The write shape for any `couponIds`-style field — one definition, imported
+ * by the event schema, the blog schema and both admin API routes.
+ *
+ * 🛑 ONE definition on purpose. Four hand-written `z.array(z.string())`s would
+ * be four chances for the cap to drift, and a cap enforced on three of four
+ * write paths is not a cap — the fourth is simply the way in. This is the same
+ * failure as the ten hand-maintained copies of the `ListingType` union in
+ * Root Cause #61.
+ *
+ * `.max()` carries a message because this one is reachable by a human in an
+ * admin form, and "Too big: expected array to have <=10 items" is not an
+ * instruction.
+ */
+export declare const attachedCouponIdsSchema: z.ZodType<string[] | undefined>;
+/**
+ * Dedupe and drop blanks. Still ONE definition — it moved out of the schema,
+ * it did not become four copies.
+ *
+ * 🛑 WHY IT IS NOT A `.transform()` ANY MORE, which is where it started:
+ *
+ * `.transform()` wraps the schema in `z.ZodEffects`, and **`ZodEffects` is a
+ * zod 3 type that does not exist in zod 4**. This repo runs both — appkit is
+ * pinned to zod 3.25.76 (peer `^3.24.0`) while the consumer app resolves zod
+ * 4.4.3 — so appkit's emitted `.d.ts` referenced a type the consumer's zod
+ * cannot resolve, the inference collapsed to `unknown`, and four admin routes
+ * failed to typecheck with `Type 'unknown' is not assignable to type
+ * 'string[] | undefined'`.
+ *
+ * The declared peer range is the thing that is actually wrong here, and
+ * aligning the two majors is a real migration rather than a drive-by. Until
+ * then: no schema crossing the package boundary may use `.transform()`,
+ * `.refine()` or `.preprocess()`, because all three produce `ZodEffects`.
+ *
+ * Callers apply this after parsing, which is the same boundary the dedupe
+ * always ran at — the route, not the client.
+ */
+export declare function dedupeAttachedCouponIds(ids: readonly string[] | undefined): string[] | undefined;

package/dist/features/promotions/schemas/attached-coupons.js

@@ -0,0 +1,66 @@
+import { z } from "zod";
+import { ATTACHED_COUPON_MAX } from "../constants/attached-coupons.js";
+/**
+ * The write shape for any `couponIds`-style field — one definition, imported
+ * by the event schema, the blog schema and both admin API routes.
+ *
+ * 🛑 ONE definition on purpose. Four hand-written `z.array(z.string())`s would
+ * be four chances for the cap to drift, and a cap enforced on three of four
+ * write paths is not a cap — the fourth is simply the way in. This is the same
+ * failure as the ten hand-maintained copies of the `ListingType` union in
+ * Root Cause #61.
+ *
+ * `.max()` carries a message because this one is reachable by a human in an
+ * admin form, and "Too big: expected array to have <=10 items" is not an
+ * instruction.
+ */
+/*
+ * 🛑 THE EXPLICIT ANNOTATION IS LOAD-BEARING — do not delete it as redundant.
+ *
+ * This repo runs TWO zod majors: appkit is pinned to 3.25.76 (peer `^3.24.0`)
+ * and the consumer app resolves 4.4.3. Inferred, this export's `.d.ts` reads
+ * `z.ZodOptional<z.ZodArray<z.ZodString, "many">>` — and zod 4's `ZodArray`
+ * takes ONE type parameter, not two. The consumer cannot resolve that shape,
+ * the inference collapses to `unknown`, and four admin routes fail with
+ * `Type 'unknown' is not assignable to type 'string[] | undefined'`.
+ *
+ * `z.ZodType<T>` is spelled the same in both majors and `z.infer` yields `T`
+ * from it either way, so the emitted declaration stays resolvable on both
+ * sides of the boundary.
+ *
+ * The real defect is the version split — appkit's declared peer range and the
+ * app's installed major disagree — and aligning them is a migration, not a
+ * drive-by. Until that happens, any appkit zod schema a consumer infers from
+ * needs this treatment.
+ */
+export const attachedCouponIdsSchema = z
+    .array(z.string().min(1))
+    .max(ATTACHED_COUPON_MAX, `At most ${ATTACHED_COUPON_MAX} coupons can be attached.`)
+    .optional();
+/**
+ * Dedupe and drop blanks. Still ONE definition — it moved out of the schema,
+ * it did not become four copies.
+ *
+ * 🛑 WHY IT IS NOT A `.transform()` ANY MORE, which is where it started:
+ *
+ * `.transform()` wraps the schema in `z.ZodEffects`, and **`ZodEffects` is a
+ * zod 3 type that does not exist in zod 4**. This repo runs both — appkit is
+ * pinned to zod 3.25.76 (peer `^3.24.0`) while the consumer app resolves zod
+ * 4.4.3 — so appkit's emitted `.d.ts` referenced a type the consumer's zod
+ * cannot resolve, the inference collapsed to `unknown`, and four admin routes
+ * failed to typecheck with `Type 'unknown' is not assignable to type
+ * 'string[] | undefined'`.
+ *
+ * The declared peer range is the thing that is actually wrong here, and
+ * aligning the two majors is a real migration rather than a drive-by. Until
+ * then: no schema crossing the package boundary may use `.transform()`,
+ * `.refine()` or `.preprocess()`, because all three produce `ZodEffects`.
+ *
+ * Callers apply this after parsing, which is the same boundary the dedupe
+ * always ran at — the route, not the client.
+ */
+export function dedupeAttachedCouponIds(ids) {
+    if (!ids)
+        return undefined;
+    return Array.from(new Set(ids.filter(Boolean)));
+}

package/dist/features/shell/SectionForm.js

@@ -209,6 +209,13 @@ export function SectionForm({ sections, values, onChange, onSubmit, submitLabel
     // validator on every render and re-fire the effect below in a loop.
     const onValidationChangeRef = useRef(onValidationChange);
     onValidationChangeRef.current = onValidationChange;
+    /**
+     * The last error map actually HANDED TO the caller.
+     *
+     * 🛑 This is what stops an infinite render loop, and the loop froze the whole
+     * app — see `emitValidation` below.
+     */
+    const lastEmittedRef = useRef(null);
     /**
      * Are two field-error maps the same set of messages?
      *
@@ -232,6 +239,44 @@ export function SectionForm({ sections, values, onChange, onSubmit, submitLabel
             .filter((s) => s.fields?.some((f) => keys.some((k) => k === f || k.startsWith(`${f}.`))))
             .map((s) => s.id);
     }, [ordered]);
+    /**
+     * Hand the result to the caller, but ONLY when it actually changed.
+     *
+     * ## 🛑 The loop this closes froze every admin editor drawer
+     *
+     * `runValidation` runs on EVERY render by design: `values` is a fresh object
+     * each time, so `ordered` → `erroringSectionIds` → `runValidation` are all
+     * new identities and the effect below re-fires. The comment there argues
+     * that is safe, and for this component's OWN state it is — `sameErrors` and
+     * the `forceOpenIds` length check both return the previous object, so React
+     * bails out.
+     *
+     * It was NOT safe for the caller. `onValidationChange` was invoked
+     * unconditionally on every run, and the real call site is
+     * `onValidationChange={() => form.validate(draft)}` — which setStates. So:
+     * render → effect → emit → caller setState → render → … forever. React
+     * reported "Maximum update depth exceeded" ~4x/second.
+     *
+     * The visible symptom was not a validation bug at all. A React tree stuck in
+     * an update loop never commits a transition, and App Router navigation IS a
+     * transition — so with the drawer open, Cancel, the X, the sort dropdown and
+     * even plain nav links all did nothing. Measured on production: `router.replace`
+     * produced ZERO `history.replaceState` calls, no error, no failed request.
+     * The only escape was a full page reload.
+     *
+     * Emitting only on a real change is also what the prop NAME promises; firing
+     * it with an identical map on every render was never meaningful to a caller.
+     */
+    const emitValidation = useCallback((next, index) => {
+        const prev = lastEmittedRef.current;
+        if (prev && sameErrors(prev, next))
+            return;
+        lastEmittedRef.current = next;
+        onValidationChangeRef.current?.(next, index);
+    }, 
+    // `sameErrors` is a pure local helper; `lastEmittedRef`/`onValidationChangeRef`
+    // are refs. Nothing here needs to re-create this callback.
+    []);
     const runValidation = useCallback((nextValues) => {
         const activeSchema = schema ?? inheritedSchema;
         if (!activeSchema)
@@ -243,7 +288,7 @@ export function SectionForm({ sections, values, onChange, onSubmit, submitLabel
         if (parsed.success) {
             setFieldErrors((prev) => (Object.keys(prev).length === 0 ? prev : {}));
             setForceOpenIds((prev) => (prev.length === 0 ? prev : []));
-            onValidationChangeRef.current?.({}, fieldToSectionIndex);
+            emitValidation({}, fieldToSectionIndex);
             return;
         }
         const next = {};
@@ -266,7 +311,7 @@ export function SectionForm({ sections, values, onChange, onSubmit, submitLabel
             const kept = prev.filter((id) => stillBad.has(id));
             return kept.length === prev.length ? prev : kept;
         });
-        onValidationChangeRef.current?.(next, fieldToSectionIndex);
+        emitValidation(next, fieldToSectionIndex);
     }, [schema, inheritedSchema, fieldToSectionIndex, erroringSectionIds]);
     /*
      * 🛑 `values` MUST be a dependency, and leaving it out cost the entire admin

package/dist/schemas/registry.d.ts

@@ -169,6 +169,7 @@ export declare const SCHEMAS: {
             }>, "many">>;
             category: import("zod").ZodString;
             tags: import("zod").ZodArray<import("zod").ZodString, "many">;
+            couponIds: import("zod").ZodType<string[] | undefined, import("zod").ZodTypeDef, string[] | undefined>;
             isFeatured: import("zod").ZodBoolean;
             isPinned: import("zod").ZodBoolean;
             status: import("zod").ZodEnum<["draft", "published", "archived"]>;
@@ -210,6 +211,7 @@ export declare const SCHEMAS: {
             publishedAt?: string | Date | import("zod").objectOutputType<{
                 toDate: import("zod").ZodFunction<import("zod").ZodTuple<[], import("zod").ZodUnknown>, import("zod").ZodDate>;
             }, import("zod").ZodTypeAny, "passthrough"> | undefined;
+            couponIds?: string[] | undefined;
             coverImage?: {
                 type: "video" | "image" | "file";
                 url: string;
@@ -264,6 +266,7 @@ export declare const SCHEMAS: {
             publishedAt?: string | Date | import("zod").objectInputType<{
                 toDate: import("zod").ZodFunction<import("zod").ZodTuple<[], import("zod").ZodUnknown>, import("zod").ZodDate>;
             }, import("zod").ZodTypeAny, "passthrough"> | undefined;
+            couponIds?: string[] | undefined;
             coverImage?: {
                 type: "video" | "image" | "file";
                 url: string;
@@ -4895,6 +4898,7 @@ export declare const SCHEMAS: {
             authorName: import("zod").ZodString;
             isFeatured: import("zod").ZodBoolean;
             isPinned: import("zod").ZodBoolean;
+            couponIds: import("zod").ZodType<string[] | undefined, import("zod").ZodTypeDef, string[] | undefined>;
         }, "strip", import("zod").ZodTypeAny, {
             status: "published" | "draft" | "archived";
             title: string;
@@ -4911,6 +4915,7 @@ export declare const SCHEMAS: {
             isPinned: boolean;
             metaTitle: string;
             metaDescription: string;
+            couponIds?: string[] | undefined;
         }, {
             status: "published" | "draft" | "archived";
             title: string;
@@ -4927,6 +4932,7 @@ export declare const SCHEMAS: {
             isPinned: boolean;
             metaTitle: string;
             metaDescription: string;
+            couponIds?: string[] | undefined;
         }>;
         readonly event: import("zod").ZodEffects<import("zod").ZodObject<{
             type: import("zod").ZodString;
@@ -4945,6 +4951,8 @@ export declare const SCHEMAS: {
                 id: string;
                 label: string;
             }>, "many">;
+            couponIds: import("zod").ZodType<string[] | undefined, import("zod").ZodTypeDef, string[] | undefined>;
+            rafflePrizeCouponIds: import("zod").ZodType<string[] | undefined, import("zod").ZodTypeDef, string[] | undefined>;
         }, "passthrough", import("zod").ZodTypeAny, import("zod").objectOutputType<{
             type: import("zod").ZodString;
             title: import("zod").ZodString;
@@ -4962,6 +4970,8 @@ export declare const SCHEMAS: {
                 id: string;
                 label: string;
             }>, "many">;
+            couponIds: import("zod").ZodType<string[] | undefined, import("zod").ZodTypeDef, string[] | undefined>;
+            rafflePrizeCouponIds: import("zod").ZodType<string[] | undefined, import("zod").ZodTypeDef, string[] | undefined>;
         }, import("zod").ZodTypeAny, "passthrough">, import("zod").objectInputType<{
             type: import("zod").ZodString;
             title: import("zod").ZodString;
@@ -4979,6 +4989,8 @@ export declare const SCHEMAS: {
                 id: string;
                 label: string;
             }>, "many">;
+            couponIds: import("zod").ZodType<string[] | undefined, import("zod").ZodTypeDef, string[] | undefined>;
+            rafflePrizeCouponIds: import("zod").ZodType<string[] | undefined, import("zod").ZodTypeDef, string[] | undefined>;
         }, import("zod").ZodTypeAny, "passthrough">>, import("zod").objectOutputType<{
             type: import("zod").ZodString;
             title: import("zod").ZodString;
@@ -4996,6 +5008,8 @@ export declare const SCHEMAS: {
                 id: string;
                 label: string;
             }>, "many">;
+            couponIds: import("zod").ZodType<string[] | undefined, import("zod").ZodTypeDef, string[] | undefined>;
+            rafflePrizeCouponIds: import("zod").ZodType<string[] | undefined, import("zod").ZodTypeDef, string[] | undefined>;
         }, import("zod").ZodTypeAny, "passthrough">, import("zod").objectInputType<{
             type: import("zod").ZodString;
             title: import("zod").ZodString;
@@ -5013,6 +5027,8 @@ export declare const SCHEMAS: {
                 id: string;
                 label: string;
             }>, "many">;
+            couponIds: import("zod").ZodType<string[] | undefined, import("zod").ZodTypeDef, string[] | undefined>;
+            rafflePrizeCouponIds: import("zod").ZodType<string[] | undefined, import("zod").ZodTypeDef, string[] | undefined>;
         }, import("zod").ZodTypeAny, "passthrough">>;
         readonly productFeature: import("zod").ZodEffects<import("zod").ZodObject<{
             label: import("zod").ZodString;

package/dist/server-entry.d.ts

@@ -52,6 +52,7 @@ export { listPublicProducts, parsePublicProductParams, defaultAvailabilityForLis
 export { getAuctionForDetail, getProductFeaturesForAuction, } from "./_internal/server/features/auctions/index";
 export { getPreOrderForDetail, getProductFeaturesForPreOrder, } from "./_internal/server/features/pre-orders/index";
 export { getBrandForDetail, getBrandCategoryForDetail, createBrandAction, updateBrandAction, deleteBrandAction, toggleBrandActiveAction, } from "./_internal/server/features/brands/index";
+export { getAttachedCoupons, toAttachedCoupon } from "./_internal/server/features/promotions/index";
 export { getBlogPostForDetail, getBlogPostById, createBlogPostAction, updateBlogPostAction, deleteBlogPostAction, publishBlogPostAction, unpublishBlogPostAction, } from "./_internal/server/features/blog/index";
 export { getEventForDetail, registerForEventAction, cancelEventRegistrationAction, createEventAction, updateEventAction, } from "./_internal/server/features/events/index";
 export { createProductAction, createAuctionAction, createPreOrderAction, updateProductAction, deleteProductAction, setProductStatusAction, setProductFeaturedAction, } from "./_internal/server/features/products/index";

package/dist/server-entry.js

@@ -61,6 +61,8 @@ export { getAuctionForDetail, getProductFeaturesForAuction, } from "./_internal/
 export { getPreOrderForDetail, getProductFeaturesForPreOrder, } from "./_internal/server/features/pre-orders/index.js";
 // S3: brands data layer + actions
 export { getBrandForDetail, getBrandCategoryForDetail, createBrandAction, updateBrandAction, deleteBrandAction, toggleBrandActiveAction, } from "./_internal/server/features/brands/index.js";
+// Promotional coupons attached to content (events + blog posts)
+export { getAttachedCoupons, toAttachedCoupon } from "./_internal/server/features/promotions/index.js";
 // S3: blog data layer + actions
 export { getBlogPostForDetail, getBlogPostById, createBlogPostAction, updateBlogPostAction, deleteBlogPostAction, publishBlogPostAction, unpublishBlogPostAction, } from "./_internal/server/features/blog/index.js";
 // S3: events data layer + actions

package/dist/server.d.ts

@@ -478,6 +478,7 @@ export { getBrandForDetail } from "./_internal/server/features/brands/index";
 export { getFranchiseForDetail, listActiveFranchises, renderFranchiseOg, } from "./_internal/server/features/franchises/index";
 export { getBlogPostForDetail } from "./_internal/server/features/blog/index";
 export { getEventForDetail } from "./_internal/server/features/events/index";
+export { getAttachedCoupons, toAttachedCoupon } from "./_internal/server/features/promotions/index";
 export { getSublistingCategoryForDetail } from "./_internal/server/features/sublisting-categories/index";
 export { getCategoryForDetail, listRootCategories, listFeaturedCategories, listMenuCategories, getCategoryTree, listSitemapCategories } from "./_internal/server/features/categories/index";
 export { renderProductOg, renderProductOgImage, type ProductOgData, type OgOptions } from "./_internal/server/features/products/og";