@mohasinac/appkit 4.11.2 → 4.11.3

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

@@ -109,6 +109,10 @@ export declare class ProductRepository extends BaseRepository<ProductDocument> {
             canFilter: boolean;
             canSort: boolean;
         };
+        isOnSale: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
         price: {
             canFilter: boolean;
             canSort: boolean;
@@ -117,6 +121,10 @@ export declare class ProductRepository extends BaseRepository<ProductDocument> {
             canFilter: boolean;
             canSort: boolean;
         };
+        availableQuantity: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
         viewCount: {
             canFilter: boolean;
             canSort: boolean;
@@ -129,6 +137,10 @@ export declare class ProductRepository extends BaseRepository<ProductDocument> {
             canFilter: boolean;
             canSort: boolean;
         };
+        bidsHaveStarted: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
         isSold: {
             canFilter: boolean;
             canSort: boolean;
@@ -137,6 +149,18 @@ export declare class ProductRepository extends BaseRepository<ProductDocument> {
             canFilter: boolean;
             canSort: boolean;
         };
+        isTestData: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
+        brandSlug: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
+        sublistingCategoryId: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
         createdAt: {
             canFilter: boolean;
             canSort: boolean;
@@ -166,6 +190,22 @@ export declare class ProductRepository extends BaseRepository<ProductDocument> {
             canFilter: boolean;
             canSort: boolean;
         };
+        prizeDrawMode: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
+        pricePerEntry: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
+        prizeCurrentEntries: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
+        prizeMaxEntries: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
         startingBid: {
             canFilter: boolean;
             canSort: boolean;
@@ -215,6 +255,10 @@ export declare class ProductRepository extends BaseRepository<ProductDocument> {
             canFilter: boolean;
             canSort: boolean;
         };
+        preOrderClosed: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
         tags: {
             canFilter: boolean;
             canSort: boolean;
@@ -231,7 +275,7 @@ export declare class ProductRepository extends BaseRepository<ProductDocument> {
             canFilter: boolean;
             canSort: boolean;
         };
-        freeShipping: {
+        shippingPaidBy: {
             canFilter: boolean;
             canSort: boolean;
         };

package/dist/features/products/repository/products.repository.js

@@ -493,22 +493,38 @@ ProductRepository.SIEVE_FIELDS = {
     status: { canFilter: true, canSort: true },
     storeId: { canFilter: true, canSort: false },
     storeName: { canFilter: true, canSort: true },
-    featured: { canFilter: true, canSort: false },
+    // canSort:true — STANDARD_SORT_OPTIONS offers "Featured First" and
+    // "Promoted First". They were `canSort:false` until 2026-08-21, so sievejs
+    // silently dropped the sort and both dropdown options did nothing on the
+    // admin and seller product lists.
+    featured: { canFilter: true, canSort: true },
     listingType: { canFilter: true, canSort: false },
-    isPromoted: { canFilter: true, canSort: false },
+    isPromoted: { canFilter: true, canSort: true },
+    isOnSale: { canFilter: true, canSort: false },
     price: { canFilter: true, canSort: true },
     stockQuantity: { canFilter: true, canSort: true },
+    availableQuantity: { canFilter: true, canSort: true },
     viewCount: { canFilter: true, canSort: true },
     currentBid: { canFilter: true, canSort: true },
     bidCount: { canFilter: true, canSort: true },
+    bidsHaveStarted: { canFilter: true, canSort: false },
     isSold: { canFilter: true, canSort: true },
     isPartOfBundle: { canFilter: true, canSort: false },
+    isTestData: { canFilter: true, canSort: false },
+    brandSlug: { canFilter: true, canSort: false },
+    sublistingCategoryId: { canFilter: true, canSort: false },
     createdAt: { canFilter: true, canSort: true, parseValue: parseSieveDateValue },
     updatedAt: { canFilter: true, canSort: true, parseValue: parseSieveDateValue },
     auctionEndDate: { canFilter: true, canSort: true, parseValue: parseSieveDateValue },
     prizeRevealWindowStart: { canFilter: true, canSort: true, parseValue: parseSieveDateValue },
     prizeRevealWindowEnd: { canFilter: true, canSort: true, parseValue: parseSieveDateValue },
     prizeRevealStatus: { canFilter: true, canSort: false },
+    prizeDrawMode: { canFilter: true, canSort: false },
+    // Prize-draw entry price. PrizeDrawsListingView emits min/max filters on
+    // this field; without an entry here sievejs dropped both clauses silently.
+    pricePerEntry: { canFilter: true, canSort: true },
+    prizeCurrentEntries: { canFilter: true, canSort: true },
+    prizeMaxEntries: { canFilter: true, canSort: true },
     startingBid: { canFilter: true, canSort: true },
     buyNowPrice: { canFilter: true, canSort: true },
     minBidIncrement: { canFilter: true, canSort: false },
@@ -521,11 +537,18 @@ ProductRepository.SIEVE_FIELDS = {
     preOrderCurrentCount: { canFilter: true, canSort: true },
     preOrderProductionStatus: { canFilter: true, canSort: false },
     preOrderCancellable: { canFilter: true, canSort: false },
+    preOrderClosed: { canFilter: true, canSort: false },
     tags: { canFilter: true, canSort: false },
     features: { canFilter: true, canSort: false },
     insurance: { canFilter: true, canSort: false },
     currency: { canFilter: true, canSort: false },
-    freeShipping: { canFilter: true, canSort: false },
+    // `freeShipping` used to be listed here and is NOT a ProductDocument field
+    // at all — free shipping is derived from `shippingPaidBy === "seller"`.
+    // The public "Free shipping" toggle emitted `shippingPaidBy==seller`
+    // (buildFirestoreSafeFilters), which sievejs then dropped because the real
+    // field had no entry: `throwExceptions:false` means an unknown field is
+    // silently skipped. The toggle did nothing at all until 2026-08-21.
+    shippingPaidBy: { canFilter: true, canSort: false },
     searchTokens: { canFilter: true, canSort: false },
     "classified.meetupArea": { canFilter: true, canSort: false },
     "classified.acceptsShipping": { canFilter: true, canSort: false },

package/dist/features/products/utils/listing-badge-variant.d.ts

@@ -1,3 +1,5 @@
+import type { ListingType } from "../types/index";
+export type ListingBadgeVariant = "default" | "primary" | "secondary" | "success" | "warning" | "danger";
 /**
  * Listing-kind → Badge variant map.
  *
@@ -6,5 +8,22 @@
  * deprecated `KIND_BADGE_VARIANT` export that previously lived in
  * `seller-products-styles.ts` (deleted 2026-06-17 in Phase 3 of the
  * Three-Layer Style System refactor).
+ *
+ * Typed `Record<ListingType, …>` (2026-08-21) so a new listing type is a
+ * COMPILE error here rather than a silent fallthrough. It previously covered
+ * only auction / pre-order / prize-draw / standard, so the other five types
+ * fell through to the caller's `?? "default"` and all rendered identically.
+ */
+export declare const LISTING_BADGE_VARIANT: Record<ListingType, ListingBadgeVariant>;
+/**
+ * Badge variant for a listing kind that may not be a real `ListingType` —
+ * a raw API string, or a UI-only sentinel like the seller dropdown's `"all"`.
+ *
+ * Callers used to index `LISTING_BADGE_VARIANT[kind] ?? "default"` directly
+ * with a plain `string`, which is what let the map stay incomplete for years
+ * without anyone noticing: the `??` swallowed every missing type. Going
+ * through this accessor keeps the map itself exhaustively typed (so a new
+ * listing type is a compile error there) while still tolerating a
+ * non-ListingType input here, where tolerance is genuinely needed.
  */
-export declare const LISTING_BADGE_VARIANT: Record<string, "default" | "primary" | "secondary" | "success" | "warning" | "danger">;
+export declare function listingBadgeVariant(kind: string | undefined): ListingBadgeVariant;

package/dist/features/products/utils/listing-badge-variant.js

@@ -1,3 +1,4 @@
+import { isListingType } from "./listing-type";
 /**
  * Listing-kind → Badge variant map.
  *
@@ -6,10 +7,34 @@
  * deprecated `KIND_BADGE_VARIANT` export that previously lived in
  * `seller-products-styles.ts` (deleted 2026-06-17 in Phase 3 of the
  * Three-Layer Style System refactor).
+ *
+ * Typed `Record<ListingType, …>` (2026-08-21) so a new listing type is a
+ * COMPILE error here rather than a silent fallthrough. It previously covered
+ * only auction / pre-order / prize-draw / standard, so the other five types
+ * fell through to the caller's `?? "default"` and all rendered identically.
  */
 export const LISTING_BADGE_VARIANT = {
+    standard: "default",
     auction: "warning",
     "pre-order": "secondary",
     "prize-draw": "primary",
-    standard: "default",
+    classified: "secondary",
+    "digital-code": "success",
+    live: "danger",
+    art: "primary",
+    stickers: "primary",
 };
+/**
+ * Badge variant for a listing kind that may not be a real `ListingType` —
+ * a raw API string, or a UI-only sentinel like the seller dropdown's `"all"`.
+ *
+ * Callers used to index `LISTING_BADGE_VARIANT[kind] ?? "default"` directly
+ * with a plain `string`, which is what let the map stay incomplete for years
+ * without anyone noticing: the `??` swallowed every missing type. Going
+ * through this accessor keeps the map itself exhaustively typed (so a new
+ * listing type is a compile error there) while still tolerating a
+ * non-ListingType input here, where tolerance is genuinely needed.
+ */
+export function listingBadgeVariant(kind) {
+    return kind && isListingType(kind) ? LISTING_BADGE_VARIANT[kind] : "default";
+}

package/dist/features/products/utils/listing-type.d.ts

@@ -1,4 +1,28 @@
 import type { ListingType } from "../types/index";
+/** True when `value` is a member of the canonical `ListingType` union. */
+export declare function isListingType(value: string): value is ListingType;
+/**
+ * Parse a multi-select listing-type URL value into canonical types.
+ *
+ * The type filter is a checkbox group, so its URL value is a pipe-joined set
+ * (`auction|pre-order`) — the same shape the Sieve adapter upgrades to a
+ * Firestore `in` query. Unknown tokens are DROPPED rather than passed through:
+ * an unrecognised value reaching `where("listingType","==",x)` matches zero
+ * documents forever with no error (Root Cause #33), so silently ignoring it and
+ * showing the wider result set is the safer failure mode.
+ *
+ * An empty result means "no type filter" — i.e. every type — which is exactly
+ * what an empty checkbox group should mean.
+ */
+export declare function parseSelectedListingTypes(raw: string | undefined | null): ListingType[];
+/**
+ * Toggle one type in a pipe-joined selection, returning the new URL value
+ * (`""` when nothing is left selected). Keeps canonical iteration order so the
+ * URL is stable regardless of the order the user ticked the boxes — otherwise
+ * `auction|art` and `art|auction` would be two different React Query keys for
+ * the same result set.
+ */
+export declare function toggleListingTypeSelection(raw: string | undefined | null, type: ListingType): string;
 /**
  * Canonical accessor for the listing-kind discriminator. `listingType` is the
  * single source of truth on every `ProductDocument` / `ProductItem` — the

package/dist/features/products/utils/listing-type.js

@@ -1,3 +1,51 @@
+import { ALL_LISTING_TYPES } from "../../../_internal/shared/listing-types/feature-flags";
+const LISTING_TYPE_SET = new Set(ALL_LISTING_TYPES);
+/** True when `value` is a member of the canonical `ListingType` union. */
+export function isListingType(value) {
+    return LISTING_TYPE_SET.has(value);
+}
+/**
+ * Parse a multi-select listing-type URL value into canonical types.
+ *
+ * The type filter is a checkbox group, so its URL value is a pipe-joined set
+ * (`auction|pre-order`) — the same shape the Sieve adapter upgrades to a
+ * Firestore `in` query. Unknown tokens are DROPPED rather than passed through:
+ * an unrecognised value reaching `where("listingType","==",x)` matches zero
+ * documents forever with no error (Root Cause #33), so silently ignoring it and
+ * showing the wider result set is the safer failure mode.
+ *
+ * An empty result means "no type filter" — i.e. every type — which is exactly
+ * what an empty checkbox group should mean.
+ */
+export function parseSelectedListingTypes(raw) {
+    if (!raw)
+        return [];
+    const seen = new Set();
+    for (const token of raw.split("|")) {
+        const trimmed = token.trim();
+        // "All" is the legacy single-select sentinel — treated as "no filter".
+        if (!trimmed || trimmed === "All")
+            continue;
+        if (isListingType(trimmed))
+            seen.add(trimmed);
+    }
+    return [...seen];
+}
+/**
+ * Toggle one type in a pipe-joined selection, returning the new URL value
+ * (`""` when nothing is left selected). Keeps canonical iteration order so the
+ * URL is stable regardless of the order the user ticked the boxes — otherwise
+ * `auction|art` and `art|auction` would be two different React Query keys for
+ * the same result set.
+ */
+export function toggleListingTypeSelection(raw, type) {
+    const current = new Set(parseSelectedListingTypes(raw));
+    if (current.has(type))
+        current.delete(type);
+    else
+        current.add(type);
+    return ALL_LISTING_TYPES.filter((t) => current.has(t)).join("|");
+}
 /**
  * Canonical accessor for the listing-kind discriminator. `listingType` is the
  * single source of truth on every `ProductDocument` / `ProductItem` — the

package/dist/features/promotions/actions/coupon-actions.d.ts

@@ -26,4 +26,11 @@ export type CouponCartItem = {
     listingType: ListingType;
 };
 export declare function validateCoupon(userId: string, code: string, orderTotal: number): Promise<CouponValidationResult>;
+/**
+ * Resolves productId → categorySlugs[] in a single batched `getAll` round-trip.
+ * Passed into the coupon repository so it can enforce category restrictions
+ * without importing the products repository itself. Invoked only when the
+ * coupon actually has a category restriction.
+ */
+export declare function resolveCouponCategorySlugs(productIds: string[]): Promise<Map<string, string[]>>;
 export declare function validateCouponForCart(userId: string, code: string, cartItems: CouponCartItem[]): Promise<CouponCartValidationResult>;

package/dist/features/promotions/actions/coupon-actions.js

@@ -5,11 +5,22 @@
  * are handled by the calling server action in the consumer.
  */
 import { couponsRepository } from "../repository/coupons.repository";
+import { productRepository } from "../../products/repository/products.repository";
 export async function validateCoupon(userId, code, orderTotal) {
     return couponsRepository.validateCoupon(code, userId, orderTotal);
 }
+/**
+ * Resolves productId → categorySlugs[] in a single batched `getAll` round-trip.
+ * Passed into the coupon repository so it can enforce category restrictions
+ * without importing the products repository itself. Invoked only when the
+ * coupon actually has a category restriction.
+ */
+export async function resolveCouponCategorySlugs(productIds) {
+    const products = await productRepository.listByIds(productIds);
+    return new Map(products.map((p) => [p.id, p.categorySlugs ?? []]));
+}
 export async function validateCouponForCart(userId, code, cartItems) {
-    const result = await couponsRepository.validateCouponForCart(code, userId, cartItems);
+    const result = await couponsRepository.validateCouponForCart(code, userId, cartItems, { resolveCategorySlugs: resolveCouponCategorySlugs });
     return {
         valid: result.valid,
         discountAmount: result.discountAmount ?? 0,

package/dist/features/promotions/actions/coupon-stacking.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Coupon Stacking Rules
+ *
+ * A cart may hold at most one seller-scoped coupon per store, plus at most
+ * one admin (platform-wide) coupon on top. Both scopes stack with each
+ * other freely — the old `combineWithSellerCoupons` opt-out was removed
+ * (2026-08-21): stacking is now unconditional as long as the two "buckets"
+ * (per-store, and the single platform-wide slot) don't collide.
+ *
+ * Pure function, no I/O — safe to call from both the cart-apply route and
+ * the checkout re-validation pass.
+ */
+import type { CartAppliedCoupon } from "../../cart/schemas/firestore";
+export interface IncomingCoupon {
+    code: string;
+    scope: "admin" | "seller";
+    storeId?: string;
+}
+/**
+ * Returns a human-readable conflict message, or null when `incoming` can be
+ * added alongside `existing` without violating the one-per-store +
+ * one-global rule.
+ */
+export declare function detectCouponConflict(existing: CartAppliedCoupon[], incoming: IncomingCoupon): string | null;

package/dist/features/promotions/actions/coupon-stacking.js

@@ -0,0 +1,21 @@
+/**
+ * Returns a human-readable conflict message, or null when `incoming` can be
+ * added alongside `existing` without violating the one-per-store +
+ * one-global rule.
+ */
+export function detectCouponConflict(existing, incoming) {
+    for (const applied of existing) {
+        if (applied.code === incoming.code) {
+            return `Coupon ${incoming.code} is already applied.`;
+        }
+        if (incoming.scope === "seller" &&
+            applied.scope === "seller" &&
+            applied.storeId === incoming.storeId) {
+            return `A coupon for this store is already applied (${applied.code}). Remove it first.`;
+        }
+        if (incoming.scope === "admin" && applied.scope === "admin") {
+            return `Only one platform-wide coupon can be applied at a time (${applied.code}). Remove it first.`;
+        }
+    }
+    return null;
+}

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

@@ -1,3 +1,4 @@
 export * from "./coupon-actions";
+export * from "./coupon-stacking";
 export * from "./promotions-actions";
 export * from "./seller-coupon-actions";

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

@@ -1,3 +1,4 @@
 export * from "./coupon-actions";
+export * from "./coupon-stacking";
 export * from "./promotions-actions";
 export * from "./seller-coupon-actions";

package/dist/features/promotions/actions/seller-coupon-actions.d.ts

@@ -32,7 +32,6 @@ export interface SellerCreateCouponInput {
         excludeProducts?: string[];
         excludeCategories?: string[];
         firstTimeUserOnly: boolean;
-        combineWithSellerCoupons: boolean;
     };
 }
 export type SellerUpdateCouponInput = Partial<Omit<SellerCreateCouponInput, "sellerCode" | "applicableToAuctions">>;

package/dist/features/promotions/actions/seller-coupon-actions.js

@@ -36,7 +36,6 @@ export async function sellerCreateCoupon(userId, input) {
         restrictions: {
             ...rest.restrictions,
             applicableSellers: [userId],
-            combineWithSellerCoupons: false,
         },
         stats: { totalUses: 0, totalRevenue: 0, totalDiscount: 0 },
     });

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

@@ -0,0 +1,20 @@
+import React from "react";
+export interface CouponHelpDetailsProps {
+    /**
+     * Show the note explaining that coupons are re-checked at order placement.
+     * Only meaningful where an order is actually about to be placed, so it is
+     * off by default and enabled at checkout.
+     */
+    showRevalidationNote?: boolean;
+    defaultOpen?: boolean;
+    /** Collapses sibling <Details> sharing the same name (browser-native). */
+    name?: string;
+}
+/**
+ * Expandable "How coupons work" explainer. Collapsed by default so it never
+ * competes with the coupon input it sits beside.
+ *
+ * All copy comes from COUPON_HELP so the cart, checkout and public coupons
+ * listing render identical text.
+ */
+export declare function CouponHelpDetails({ showRevalidationNote, defaultOpen, name, }: CouponHelpDetailsProps): React.JSX.Element;

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

@@ -0,0 +1,17 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Details, Summary, Stack, Text, Ul, Li, Span } from "../../../ui";
+import { COUPON_HELP } from "../constants/coupon-help";
+function HelpSection({ heading, items }) {
+    return (_jsxs(Stack, { gap: "dense", children: [_jsx(Text, { size: "sm", weight: "semibold", children: heading }), _jsx(Ul, { marker: "disc", indent: "md", spacing: "tight", size: "sm", children: items.map((item) => (_jsx(Li, { color: "muted", children: item }, item))) })] }));
+}
+/**
+ * Expandable "How coupons work" explainer. Collapsed by default so it never
+ * competes with the coupon input it sits beside.
+ *
+ * All copy comes from COUPON_HELP so the cart, checkout and public coupons
+ * listing render identical text.
+ */
+export function CouponHelpDetails({ showRevalidationNote = false, defaultOpen = false, name, }) {
+    return (_jsxs(Details, { tone: "card", padding: "none", defaultOpen: defaultOpen, name: name, children: [_jsxs(Summary, { paddingX: "x-md", paddingY: "y-md", size: "sm", weight: "semibold", layout: "flex", align: "center", justify: "between", children: [_jsx(Span, { children: COUPON_HELP.title }), _jsx(Span, { size: "xs", color: "muted", children: "Stacking rules" })] }), _jsxs(Stack, { gap: "comfortable", padding: "md", children: [_jsx(HelpSection, { heading: COUPON_HELP.stackingHeading, items: COUPON_HELP.stackingRules }), _jsx(HelpSection, { heading: COUPON_HELP.applicationHeading, items: COUPON_HELP.applicationRules }), _jsx(HelpSection, { heading: COUPON_HELP.failureHeading, items: COUPON_HELP.failureReasons }), showRevalidationNote && (_jsx(Text, { size: "xs", color: "muted", children: COUPON_HELP.revalidationNote }))] })] }));
+}

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

@@ -6,6 +6,7 @@ import { useUrlTable } from "../../../react/hooks/useUrlTable";
 import { Button, DateInput, IconButton, Input, ListingFilterDrawer, Pagination, RadioGroup, SortDropdown, Div, Grid, Row, Span, Stack, Text, Heading, StickyToolbar } from "../../../ui";
 import { usePromotions } from "../hooks/usePromotions";
 import { CouponCard } from "./CouponCard";
+import { CouponHelpDetails } from "./CouponHelpDetails";
 import { TABLE_KEYS } from "../../../constants/table-keys";
 import { COUPON_FIELDS } from "../../../constants/field-names";
 import { sortBy } from "../../../constants/sort";
@@ -106,7 +107,7 @@ export function CouponsIndexListing({ initialCoupons, storeId, }) {
     const clearFilters = () => {
         table.setMany({ type: "", [TABLE_KEYS.DATE_FROM]: "", [TABLE_KEYS.DATE_TO]: "" });
     };
-    return (_jsxs(Div, { className: "min-h-[40vh]", children: [_jsxs(StickyToolbar, { offset: "header", tone: "default", border: true, padding: "md", z: "above-toolbar", dismissible: true, id: "coupons-toolbar", children: [_jsxs(Row, { gap: "xs", className: "max-w-full", children: [_jsxs(Button, { type: "button", variant: hasActiveFilters ? "outline" : "ghost", onClick: openFilters, gap: "sm", rounded: "lg", paddingX: "md", paddingY: "sm", textSize: "sm", weight: "medium", className: hasActiveFilters ? "border-primary bg-primary-50 text-primary-700 dark:bg-primary-900/30 dark:text-primary-300 shrink-0" : "border-[var(--appkit-color-border)] text-[var(--appkit-color-text-muted)] shrink-0", children: [_jsx(SlidersHorizontal, { className: "h-4 w-4" }), _jsxs(Span, { className: "hidden sm:inline", children: ["Filters", hasActiveFilters ? " •" : ""] })] }), _jsxs(Row, { surface: "default", className: `flex-1 ${__O.hidden}`, border: "strong", rounded: "lg", children: [_jsx(Input, { bare: true, type: "text", value: searchInput, onChange: (e) => setSearchInput(e.target.value), onKeyDown: handleKeyDown, placeholder: "Search by name or description\u2026", className: "min-w-0 flex-1 bg-transparent px-[var(--appkit-space-3)] py-[var(--appkit-space-2)] text-[length:var(--appkit-text-sm)] text-[var(--appkit-color-text)] placeholder-zinc-400 outline-none" }), searchInput && (_jsx(IconButton, { type: "button", onClick: () => { setSearchInput(""); table.set(TABLE_KEYS.QUERY, ""); }, "aria-label": "Clear search", variant: "ghost", size: "sm", children: _jsx(X, { className: "h-3.5 w-3.5" }) })), _jsx(IconButton, { type: "button", onClick: commitSearch, "aria-label": "Search", variant: "ghost", size: "sm", children: _jsx(Search, { className: "h-4 w-4" }) })] }), _jsxs(Row, { color: "muted", textSize: "sm", gap: "xs", className: "shrink-0", children: [_jsx(Span, { className: "hidden md:inline whitespace-nowrap", children: "Sort by" }), _jsx(SortDropdown, { value: table.get(TABLE_KEYS.SORT) || DEFAULT_SORT, onChange: (v) => { table.set(TABLE_KEYS.SORT, v); }, options: COUPON_SORT_OPTIONS })] })] }), hasActiveFilters && (_jsxs(Row, { gap: "xs", wrap: true, className: "mt-2", children: [activeType && (_jsxs(Span, { layout: "flex", gap: "xs", size: "xs", weight: "medium", className: "bg-primary-50 dark:bg-primary-900/30 text-primary-700 dark:text-primary-300", rounded: "full", padding: "pill-sm-tall", children: [COUPON_TYPES.find((t) => t.value === activeType)?.label ?? activeType, _jsx(Button, { variant: "ghost", type: "button", onClick: () => { table.set(TABLE_KEYS.TYPE, ""); }, "aria-label": "Remove type filter", className: CLS_CHIP_BTN, children: _jsx(X, { className: "h-3 w-3" }) })] })), table.get(TABLE_KEYS.DATE_FROM) && (_jsxs(Span, { layout: "flex", gap: "xs", size: "xs", weight: "medium", className: "bg-primary-50 dark:bg-primary-900/30 text-primary-700 dark:text-primary-300", rounded: "full", padding: "pill-sm-tall", children: ["From: ", table.get(TABLE_KEYS.DATE_FROM), _jsx(Button, { variant: "ghost", type: "button", onClick: () => { table.set(TABLE_KEYS.DATE_FROM, ""); }, "aria-label": "Remove from-date filter", className: CLS_CHIP_BTN, children: _jsx(X, { className: "h-3 w-3" }) })] })), table.get(TABLE_KEYS.DATE_TO) && (_jsxs(Span, { layout: "flex", gap: "xs", size: "xs", weight: "medium", className: "bg-primary-50 dark:bg-primary-900/30 text-primary-700 dark:text-primary-300", rounded: "full", padding: "pill-sm-tall", children: ["To: ", table.get(TABLE_KEYS.DATE_TO), _jsx(Button, { variant: "ghost", type: "button", onClick: () => { table.set(TABLE_KEYS.DATE_TO, ""); }, "aria-label": "Remove to-date filter", className: CLS_CHIP_BTN, children: _jsx(X, { className: "h-3 w-3" }) })] })), _jsx(Button, { variant: "ghost", type: "button", onClick: clearFilters, textSize: "xs", textColor: "muted", className: "underline", children: "Clear all" })] }))] }), _jsxs(Div, { paddingY: "y-lg", paddingX: "x-md", children: [isLoading ? (_jsx(Grid, { gap: "sm", className: "md:grid-cols-2 lg:grid-cols-3", children: Array.from({ length: 6 }).map((_, i) => (_jsxs(Stack, { border: "skeleton", gap: "sm", rounded: "xl", padding: "md", className: "animate-pulse", children: [_jsx(Div, { className: "h-6 w-2/3", surface: "subtle", rounded: "default" }), _jsx(Div, { className: "h-4 w-full", surface: "subtle", rounded: "default" }), _jsx(Div, { className: "h-3 w-1/2", surface: "subtle", rounded: "default" })] }, i))) })) : displayCoupons.length === 0 ? (_jsx(Div, { className: "text-left", padding: "y-4xl", children: _jsx(Text, { color: "faint", children: "No coupons match your search." }) })) : (_jsx(Grid, { gap: "sm", className: "md:grid-cols-2 lg:grid-cols-3", children: displayCoupons.map((coupon) => (_jsx(CouponCard, { coupon: coupon, labels: {
+    return (_jsxs(Div, { className: "min-h-[40vh]", children: [_jsxs(StickyToolbar, { offset: "header", tone: "default", border: true, padding: "md", z: "above-toolbar", dismissible: true, id: "coupons-toolbar", children: [_jsxs(Row, { gap: "xs", className: "max-w-full", children: [_jsxs(Button, { type: "button", variant: hasActiveFilters ? "outline" : "ghost", onClick: openFilters, gap: "sm", rounded: "lg", paddingX: "md", paddingY: "sm", textSize: "sm", weight: "medium", className: hasActiveFilters ? "border-primary bg-primary-50 text-primary-700 dark:bg-primary-900/30 dark:text-primary-300 shrink-0" : "border-[var(--appkit-color-border)] text-[var(--appkit-color-text-muted)] shrink-0", children: [_jsx(SlidersHorizontal, { className: "h-4 w-4" }), _jsxs(Span, { className: "hidden sm:inline", children: ["Filters", hasActiveFilters ? " •" : ""] })] }), _jsxs(Row, { surface: "default", className: `flex-1 ${__O.hidden}`, border: "strong", rounded: "lg", children: [_jsx(Input, { bare: true, type: "text", value: searchInput, onChange: (e) => setSearchInput(e.target.value), onKeyDown: handleKeyDown, placeholder: "Search by name or description\u2026", className: "min-w-0 flex-1 bg-transparent px-[var(--appkit-space-3)] py-[var(--appkit-space-2)] text-[length:var(--appkit-text-sm)] text-[var(--appkit-color-text)] placeholder-zinc-400 outline-none" }), searchInput && (_jsx(IconButton, { type: "button", onClick: () => { setSearchInput(""); table.set(TABLE_KEYS.QUERY, ""); }, "aria-label": "Clear search", variant: "ghost", size: "sm", children: _jsx(X, { className: "h-3.5 w-3.5" }) })), _jsx(IconButton, { type: "button", onClick: commitSearch, "aria-label": "Search", variant: "ghost", size: "sm", children: _jsx(Search, { className: "h-4 w-4" }) })] }), _jsxs(Row, { color: "muted", textSize: "sm", gap: "xs", className: "shrink-0", children: [_jsx(Span, { className: "hidden md:inline whitespace-nowrap", children: "Sort by" }), _jsx(SortDropdown, { value: table.get(TABLE_KEYS.SORT) || DEFAULT_SORT, onChange: (v) => { table.set(TABLE_KEYS.SORT, v); }, options: COUPON_SORT_OPTIONS })] })] }), hasActiveFilters && (_jsxs(Row, { gap: "xs", wrap: true, className: "mt-2", children: [activeType && (_jsxs(Span, { layout: "flex", gap: "xs", size: "xs", weight: "medium", className: "bg-primary-50 dark:bg-primary-900/30 text-primary-700 dark:text-primary-300", rounded: "full", padding: "pill-sm-tall", children: [COUPON_TYPES.find((t) => t.value === activeType)?.label ?? activeType, _jsx(Button, { variant: "ghost", type: "button", onClick: () => { table.set(TABLE_KEYS.TYPE, ""); }, "aria-label": "Remove type filter", className: CLS_CHIP_BTN, children: _jsx(X, { className: "h-3 w-3" }) })] })), table.get(TABLE_KEYS.DATE_FROM) && (_jsxs(Span, { layout: "flex", gap: "xs", size: "xs", weight: "medium", className: "bg-primary-50 dark:bg-primary-900/30 text-primary-700 dark:text-primary-300", rounded: "full", padding: "pill-sm-tall", children: ["From: ", table.get(TABLE_KEYS.DATE_FROM), _jsx(Button, { variant: "ghost", type: "button", onClick: () => { table.set(TABLE_KEYS.DATE_FROM, ""); }, "aria-label": "Remove from-date filter", className: CLS_CHIP_BTN, children: _jsx(X, { className: "h-3 w-3" }) })] })), table.get(TABLE_KEYS.DATE_TO) && (_jsxs(Span, { layout: "flex", gap: "xs", size: "xs", weight: "medium", className: "bg-primary-50 dark:bg-primary-900/30 text-primary-700 dark:text-primary-300", rounded: "full", padding: "pill-sm-tall", children: ["To: ", table.get(TABLE_KEYS.DATE_TO), _jsx(Button, { variant: "ghost", type: "button", onClick: () => { table.set(TABLE_KEYS.DATE_TO, ""); }, "aria-label": "Remove to-date filter", className: CLS_CHIP_BTN, children: _jsx(X, { className: "h-3 w-3" }) })] })), _jsx(Button, { variant: "ghost", type: "button", onClick: clearFilters, textSize: "xs", textColor: "muted", className: "underline", children: "Clear all" })] }))] }), _jsx(Div, { paddingY: "y-md", paddingX: "x-md", children: _jsx(CouponHelpDetails, {}) }), _jsxs(Div, { paddingY: "y-lg", paddingX: "x-md", children: [isLoading ? (_jsx(Grid, { gap: "sm", className: "md:grid-cols-2 lg:grid-cols-3", children: Array.from({ length: 6 }).map((_, i) => (_jsxs(Stack, { border: "skeleton", gap: "sm", rounded: "xl", padding: "md", className: "animate-pulse", children: [_jsx(Div, { className: "h-6 w-2/3", surface: "subtle", rounded: "default" }), _jsx(Div, { className: "h-4 w-full", surface: "subtle", rounded: "default" }), _jsx(Div, { className: "h-3 w-1/2", surface: "subtle", rounded: "default" })] }, i))) })) : displayCoupons.length === 0 ? (_jsx(Div, { className: "text-left", padding: "y-4xl", children: _jsx(Text, { color: "faint", children: "No coupons match your search." }) })) : (_jsx(Grid, { gap: "sm", className: "md:grid-cols-2 lg:grid-cols-3", children: displayCoupons.map((coupon) => (_jsx(CouponCard, { coupon: coupon, labels: {
                                 copy: "Copy",
                                 copied: "Copied!",
                                 expires: "Expires",

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

@@ -1,4 +1,6 @@
 export { CouponCard } from "./CouponCard";
+export { CouponHelpDetails } from "./CouponHelpDetails";
+export type { CouponHelpDetailsProps } from "./CouponHelpDetails";
 export { CouponsIndexListing } from "./CouponsIndexListing";
 export type { CouponsIndexListingProps } from "./CouponsIndexListing";
 export { PromotionsView, PromotionsViewProductSection, PromotionsHero, } from "./PromotionsView";

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

@@ -1,3 +1,4 @@
 export { CouponCard } from "./CouponCard";
+export { CouponHelpDetails } from "./CouponHelpDetails";
 export { CouponsIndexListing } from "./CouponsIndexListing";
 export { PromotionsView, PromotionsViewProductSection, PromotionsHero, } from "./PromotionsView";

package/dist/features/promotions/constants/coupon-help.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Coupon Help Copy
+ *
+ * Single source of truth for the buyer-facing explanation of how coupon
+ * scoping and stacking work. Rendered by <CouponHelpDetails> on the cart,
+ * the checkout coupon box, and the public coupons listing — so the three
+ * surfaces can never drift (same reasoning as REFUND_COPY).
+ *
+ * Keep this in sync with `detectCouponConflict()`
+ * (features/promotions/actions/coupon-stacking.ts), which is what actually
+ * enforces the stacking rules described here, and with the seeded FAQ
+ * `faq-coupons-and-discounts`.
+ */
+export declare const COUPON_HELP: {
+    readonly title: "How coupons work";
+    /** The stacking rules — the part buyers most often get wrong. */
+    readonly stackingHeading: "You can use more than one coupon";
+    readonly stackingRules: readonly ["One store coupon per store. If your cart has items from three stores, you can apply each of those stores' coupons at the same time.", "Plus one platform-wide LetItRip coupon, on top of any store coupons.", "A second coupon for the same store, or a second platform-wide coupon, will be declined — remove the first one to swap it."];
+    /** How the discount is actually distributed. */
+    readonly applicationHeading: "Where each discount lands";
+    readonly applicationRules: readonly ["A store coupon only discounts that store's items.", "A platform-wide coupon is spread proportionally across every store in your cart.", "Orders are placed per store, so each store's order shows its own share of the discount."];
+    /** Reuses the failure reasons already written for the buyer shopping guide. */
+    readonly failureHeading: "Why a coupon might not apply";
+    readonly failureReasons: readonly ["The eligible items in your cart are below the coupon's minimum purchase amount — minimum spend is measured against the items the coupon actually covers, not your whole cart.", "The coupon has expired, or hasn't started yet.", "The coupon is limited to certain products or categories, and your cart has none of them.", "The coupon is first-order-only and you've ordered before.", "You've already used the coupon the maximum number of times allowed.", "The coupon ran out — some coupons have a total limit across all buyers."];
+    /** Shown at checkout only, where a coupon can be dropped at payment time. */
+    readonly revalidationNote: "Coupons are re-checked when you place the order. If one has expired or run out while it sat in your cart, it's removed and your total is recalculated before payment.";
+};

package/dist/features/promotions/constants/coupon-help.js

@@ -0,0 +1,42 @@
+/**
+ * Coupon Help Copy
+ *
+ * Single source of truth for the buyer-facing explanation of how coupon
+ * scoping and stacking work. Rendered by <CouponHelpDetails> on the cart,
+ * the checkout coupon box, and the public coupons listing — so the three
+ * surfaces can never drift (same reasoning as REFUND_COPY).
+ *
+ * Keep this in sync with `detectCouponConflict()`
+ * (features/promotions/actions/coupon-stacking.ts), which is what actually
+ * enforces the stacking rules described here, and with the seeded FAQ
+ * `faq-coupons-and-discounts`.
+ */
+export const COUPON_HELP = {
+    title: "How coupons work",
+    /** The stacking rules — the part buyers most often get wrong. */
+    stackingHeading: "You can use more than one coupon",
+    stackingRules: [
+        "One store coupon per store. If your cart has items from three stores, you can apply each of those stores' coupons at the same time.",
+        "Plus one platform-wide LetItRip coupon, on top of any store coupons.",
+        "A second coupon for the same store, or a second platform-wide coupon, will be declined — remove the first one to swap it.",
+    ],
+    /** How the discount is actually distributed. */
+    applicationHeading: "Where each discount lands",
+    applicationRules: [
+        "A store coupon only discounts that store's items.",
+        "A platform-wide coupon is spread proportionally across every store in your cart.",
+        "Orders are placed per store, so each store's order shows its own share of the discount.",
+    ],
+    /** Reuses the failure reasons already written for the buyer shopping guide. */
+    failureHeading: "Why a coupon might not apply",
+    failureReasons: [
+        "The eligible items in your cart are below the coupon's minimum purchase amount — minimum spend is measured against the items the coupon actually covers, not your whole cart.",
+        "The coupon has expired, or hasn't started yet.",
+        "The coupon is limited to certain products or categories, and your cart has none of them.",
+        "The coupon is first-order-only and you've ordered before.",
+        "You've already used the coupon the maximum number of times allowed.",
+        "The coupon ran out — some coupons have a total limit across all buyers.",
+    ],
+    /** Shown at checkout only, where a coupon can be dropped at payment time. */
+    revalidationNote: "Coupons are re-checked when you place the order. If one has expired or run out while it sat in your cart, it's removed and your total is recalculated before payment.",
+};

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

@@ -143,7 +143,16 @@ export declare class CouponsRepository extends BaseRepository<CouponDocument> {
         quantity: number;
         /** Canonical listing-kind snapshot (SB1-G Phase 4). */
         listingType: ListingType;
-    }>): Promise<{
+    }>, opts?: {
+        /**
+         * Lazily resolves productId → categorySlugs[]. Supplied by the action
+         * layer (which may import the products repository) so this repository
+         * never takes a cross-repository dependency. Called at most once, and
+         * only when the coupon actually carries a category restriction — so a
+         * coupon without one costs zero extra Firestore reads.
+         */
+        resolveCategorySlugs?: (productIds: string[]) => Promise<Map<string, string[]>>;
+    }): Promise<{
         valid: boolean;
         coupon?: CouponDocument;
         discountAmount?: number;