@mohasinac/appkit 4.30.18 → 4.31.0

package/dist/features/seller/schemas/coupon-form.d.ts

@@ -3,6 +3,68 @@ import { z } from "zod";
  * 🛑 `annotate()` must be the OUTERMOST call on each field — it keys a WeakMap
  * by schema instance and every zod wrapper returns a new one.
  */
+/**
+ * The fields both coupon editors share, before either adds its own rules.
+ *
+ * Split out of `sellerCouponFormSchema` so the ADMIN editor can extend it.
+ * It could not before: that schema ends in `.superRefine`, which returns a
+ * ZodEffects with no `.extend()` — which is a large part of why the admin
+ * editor ended up declaring its own five-field `.passthrough()` stub locally
+ * and validating nothing at all.
+ */
+export declare const couponFormBase: z.ZodObject<{
+    code: z.ZodString;
+    type: z.ZodEnum<["percentage", "fixed", "free_shipping"]>;
+    value: z.ZodEffects<z.ZodString, string, string>;
+    minPurchase: z.ZodEffects<z.ZodString, string, string>;
+    maxDiscount: z.ZodEffects<z.ZodString, string, string>;
+    totalLimit: z.ZodEffects<z.ZodString, string, string>;
+    perUserLimit: z.ZodEffects<z.ZodString, string, string>;
+    startDate: z.ZodString;
+    endDate: z.ZodString;
+    isActive: z.ZodBoolean;
+    applicableProducts: z.ZodArray<z.ZodString, "many">;
+    applicableCategories: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    value: string;
+    code: string;
+    type: "fixed" | "percentage" | "free_shipping";
+    isActive: boolean;
+    endDate: string;
+    maxDiscount: string;
+    minPurchase: string;
+    applicableProducts: string[];
+    applicableCategories: string[];
+    totalLimit: string;
+    perUserLimit: string;
+    startDate: string;
+}, {
+    value: string;
+    code: string;
+    type: "fixed" | "percentage" | "free_shipping";
+    isActive: boolean;
+    endDate: string;
+    maxDiscount: string;
+    minPurchase: string;
+    applicableProducts: string[];
+    applicableCategories: string[];
+    totalLimit: string;
+    perUserLimit: string;
+    startDate: string;
+}>;
+/**
+ * The cross-field rules both editors need. Shared for the same reason the
+ * fields are: a percentage over 100 is the store paying the customer whichever
+ * portal typed it.
+ */
+export declare function refineCouponCommon(v: {
+    type: string;
+    value: string;
+    startDate: string;
+    endDate: string;
+    totalLimit: string;
+    perUserLimit: string;
+}, ctx: z.RefinementCtx): void;
 export declare const sellerCouponFormSchema: z.ZodEffects<z.ZodObject<{
     code: z.ZodString;
     type: z.ZodEnum<["percentage", "fixed", "free_shipping"]>;
@@ -70,3 +132,155 @@ export declare const sellerCouponFormSchema: z.ZodEffects<z.ZodObject<{
     startDate: string;
 }>;
 export type SellerCouponFormValues = z.infer<typeof sellerCouponFormSchema>;
+/**
+ * What `POST /api/store/coupons` accepts.
+ *
+ * The index signature is what lets it pass as a JSON body without a cast at the
+ * callsite — the named fields still constrain what may be set.
+ */
+export interface SellerCouponPayload {
+    [key: string]: string | number | boolean | string[] | undefined;
+    code: string;
+    type: SellerCouponFormValues["type"];
+    value: number;
+    minPurchase?: number;
+    maxDiscount?: number;
+    totalLimit: number;
+    perUserLimit: number;
+    startDate: string;
+    endDate: string;
+    isActive: boolean;
+    applicableProducts?: string[];
+    applicableCategories?: string[];
+}
+/**
+ * The draft, as the route wants it.
+ *
+ * 🛑 One implementation because the conditions have to match the form's, and a
+ * per-callsite conversion is how they stopped matching: the create client
+ * correctly zeroed `value` for a free-shipping coupon and then sent
+ * `maxDiscount` for EVERY type — so a cap typed while the type was
+ * "percentage" survived a switch to fixed or free-shipping, invisibly, because
+ * the input that would have shown it was no longer rendered.
+ *
+ * The rule is now stated once, here, next to the `when` predicates it mirrors:
+ * a field the form hides is a field the payload omits.
+ */
+export declare function couponDraftToPayload(draft: SellerCouponFormValues): SellerCouponPayload;
+/**
+ * A coupon as an ADMIN edits it — the seller's fields plus the ones only the
+ * platform can set.
+ *
+ * `AdminCouponEditorView` declared its own schema locally: five fields, two of
+ * them `.passthrough()`, against nineteen rendered controls. It was passed to
+ * `<Form schema>` and never parsed, so none of the seventeen unlisted controls
+ * was checked by anything — `value` could be 500%, `endDate` could precede
+ * `startDate`, and `buyQuantity` could be zero.
+ *
+ * Extending the shared base rather than restating it is what keeps the two
+ * portals' rules from drifting; that they had already drifted is Root Cause
+ * #59's shape on the validation axis.
+ */
+export declare const adminCouponFormSchema: z.ZodEffects<z.ZodObject<{
+    code: z.ZodString;
+    value: z.ZodEffects<z.ZodString, string, string>;
+    minPurchase: z.ZodEffects<z.ZodString, string, string>;
+    maxDiscount: z.ZodEffects<z.ZodString, string, string>;
+    totalLimit: z.ZodEffects<z.ZodString, string, string>;
+    perUserLimit: z.ZodEffects<z.ZodString, string, string>;
+    startDate: z.ZodString;
+    endDate: z.ZodString;
+    isActive: z.ZodBoolean;
+    applicableProducts: z.ZodArray<z.ZodString, "many">;
+    applicableCategories: z.ZodArray<z.ZodString, "many">;
+} & {
+    type: z.ZodEnum<["percentage", "fixed", "free_shipping", "buy_x_get_y"]>;
+    name: z.ZodString;
+    description: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>;
+    buyQuantity: z.ZodEffects<z.ZodString, string, string>;
+    getQuantity: z.ZodEffects<z.ZodString, string, string>;
+    currentUsage: z.ZodOptional<z.ZodNumber>;
+    firstTimeUserOnly: z.ZodBoolean;
+    appliesToAuctions: z.ZodBoolean;
+}, "strip", z.ZodTypeAny, {
+    value: string;
+    code: string;
+    type: "fixed" | "percentage" | "free_shipping" | "buy_x_get_y";
+    name: string;
+    isActive: boolean;
+    endDate: string;
+    firstTimeUserOnly: boolean;
+    maxDiscount: string;
+    minPurchase: string;
+    buyQuantity: string;
+    getQuantity: string;
+    applicableProducts: string[];
+    applicableCategories: string[];
+    totalLimit: string;
+    perUserLimit: string;
+    startDate: string;
+    appliesToAuctions: boolean;
+    description?: string | undefined;
+    currentUsage?: number | undefined;
+}, {
+    value: string;
+    code: string;
+    type: "fixed" | "percentage" | "free_shipping" | "buy_x_get_y";
+    name: string;
+    isActive: boolean;
+    endDate: string;
+    firstTimeUserOnly: boolean;
+    maxDiscount: string;
+    minPurchase: string;
+    buyQuantity: string;
+    getQuantity: string;
+    applicableProducts: string[];
+    applicableCategories: string[];
+    totalLimit: string;
+    perUserLimit: string;
+    startDate: string;
+    appliesToAuctions: boolean;
+    description?: string | undefined;
+    currentUsage?: number | undefined;
+}>, {
+    value: string;
+    code: string;
+    type: "fixed" | "percentage" | "free_shipping" | "buy_x_get_y";
+    name: string;
+    isActive: boolean;
+    endDate: string;
+    firstTimeUserOnly: boolean;
+    maxDiscount: string;
+    minPurchase: string;
+    buyQuantity: string;
+    getQuantity: string;
+    applicableProducts: string[];
+    applicableCategories: string[];
+    totalLimit: string;
+    perUserLimit: string;
+    startDate: string;
+    appliesToAuctions: boolean;
+    description?: string | undefined;
+    currentUsage?: number | undefined;
+}, {
+    value: string;
+    code: string;
+    type: "fixed" | "percentage" | "free_shipping" | "buy_x_get_y";
+    name: string;
+    isActive: boolean;
+    endDate: string;
+    firstTimeUserOnly: boolean;
+    maxDiscount: string;
+    minPurchase: string;
+    buyQuantity: string;
+    getQuantity: string;
+    applicableProducts: string[];
+    applicableCategories: string[];
+    totalLimit: string;
+    perUserLimit: string;
+    startDate: string;
+    appliesToAuctions: boolean;
+    description?: string | undefined;
+    currentUsage?: number | undefined;
+}>;
+export type AdminCouponFormValues = z.infer<typeof adminCouponFormSchema>;

package/dist/features/seller/schemas/coupon-form.js

@@ -44,7 +44,16 @@ const numericString = (label) => z
  * 🛑 `annotate()` must be the OUTERMOST call on each field — it keys a WeakMap
  * by schema instance and every zod wrapper returns a new one.
  */
-export const sellerCouponFormSchema = z
+/**
+ * The fields both coupon editors share, before either adds its own rules.
+ *
+ * Split out of `sellerCouponFormSchema` so the ADMIN editor can extend it.
+ * It could not before: that schema ends in `.superRefine`, which returns a
+ * ZodEffects with no `.extend()` — which is a large part of why the admin
+ * editor ended up declaring its own five-field `.passthrough()` stub locally
+ * and validating nothing at all.
+ */
+export const couponFormBase = z
     .object({
     code: annotate(z
         .string()
@@ -57,14 +66,26 @@ export const sellerCouponFormSchema = z
     type: annotate(z.enum(["percentage", "fixed", "free_shipping"]), {
         section: "basics", quick: true, order: 2, row: "pair",
     }),
+    /*
+     * `when` carries what the editor held as JSX conditionals, so a field the
+     * form hides is one the payload cannot carry — see `couponDraftToPayload`.
+     */
     value: annotate(numericString("The discount value"), {
         section: "basics", quick: true, order: 3, row: "pair",
+        when: (v) => v.type !== "free_shipping",
     }),
     minPurchase: annotate(numericString("Minimum purchase"), {
         section: "limits", sectionLabel: "Limits", order: 1, row: "pair",
     }),
+    /*
+     * A percentage cap is meaningless on a fixed or free-shipping coupon. The
+     * input was already hidden for those, and the value was SENT anyway — so a
+     * cap typed while the type was "percentage" persisted after switching to
+     * free shipping, invisibly.
+     */
     maxDiscount: annotate(numericString("Maximum discount"), {
         section: "limits", order: 2, row: "pair",
+        when: (v) => v.type === "percentage",
     }),
     totalLimit: annotate(numericString("Total uses"), {
         section: "limits", order: 3, row: "pair",
@@ -87,30 +108,141 @@ export const sellerCouponFormSchema = z
     applicableCategories: annotate(z.array(z.string()), {
         section: "scope", order: 2, row: "full", kind: "list",
     }),
+});
+/**
+ * The cross-field rules both editors need. Shared for the same reason the
+ * fields are: a percentage over 100 is the store paying the customer whichever
+ * portal typed it.
+ */
+export function refineCouponCommon(v, ctx) {
+    {
+        const issue = (path, message) => ctx.addIssue({ code: z.ZodIssueCode.custom, path: [path], message });
+        // A discount value is required for everything except free shipping, and
+        // a percentage above 100 is not a discount — it is the store paying the
+        // customer. Nothing bounded this before.
+        if (v.type !== "free_shipping") {
+            const amount = Number(v.value);
+            if (v.value.trim() === "")
+                issue("value", "A discount value is required.");
+            else if (amount <= 0)
+                issue("value", "The discount must be greater than zero.");
+            else if (v.type === "percentage" && amount > 100) {
+                issue("value", "A percentage discount cannot exceed 100%.");
+            }
+        }
+        if (v.startDate && v.endDate && v.startDate > v.endDate) {
+            issue("endDate", "The end date must be after the start date.");
+        }
+        // A per-customer limit above the total makes the total unreachable — the
+        // coupon reads as more generous than it can ever be.
+        const total = Number(v.totalLimit);
+        const perUser = Number(v.perUserLimit);
+        if (v.totalLimit.trim() && v.perUserLimit.trim() && perUser > total) {
+            issue("perUserLimit", "Uses per customer cannot exceed the total uses.");
+        }
+    }
+}
+export const sellerCouponFormSchema = couponFormBase.superRefine(refineCouponCommon);
+/**
+ * The draft, as the route wants it.
+ *
+ * 🛑 One implementation because the conditions have to match the form's, and a
+ * per-callsite conversion is how they stopped matching: the create client
+ * correctly zeroed `value` for a free-shipping coupon and then sent
+ * `maxDiscount` for EVERY type — so a cap typed while the type was
+ * "percentage" survived a switch to fixed or free-shipping, invisibly, because
+ * the input that would have shown it was no longer rendered.
+ *
+ * The rule is now stated once, here, next to the `when` predicates it mirrors:
+ * a field the form hides is a field the payload omits.
+ */
+export function couponDraftToPayload(draft) {
+    const isPercentage = draft.type === "percentage";
+    const hasValue = draft.type !== "free_shipping";
+    return {
+        code: draft.code,
+        type: draft.type,
+        value: hasValue ? Number(draft.value) || 0 : 0,
+        minPurchase: draft.minPurchase ? Number(draft.minPurchase) : undefined,
+        maxDiscount: isPercentage && draft.maxDiscount ? Number(draft.maxDiscount) : undefined,
+        totalLimit: Number(draft.totalLimit) || 0,
+        perUserLimit: Number(draft.perUserLimit) || 0,
+        startDate: draft.startDate,
+        endDate: draft.endDate,
+        isActive: draft.isActive,
+        ...(draft.applicableProducts?.length ? { applicableProducts: draft.applicableProducts } : {}),
+        ...(draft.applicableCategories?.length
+            ? { applicableCategories: draft.applicableCategories }
+            : {}),
+    };
+}
+/**
+ * A coupon as an ADMIN edits it — the seller's fields plus the ones only the
+ * platform can set.
+ *
+ * `AdminCouponEditorView` declared its own schema locally: five fields, two of
+ * them `.passthrough()`, against nineteen rendered controls. It was passed to
+ * `<Form schema>` and never parsed, so none of the seventeen unlisted controls
+ * was checked by anything — `value` could be 500%, `endDate` could precede
+ * `startDate`, and `buyQuantity` could be zero.
+ *
+ * Extending the shared base rather than restating it is what keeps the two
+ * portals' rules from drifting; that they had already drifted is Root Cause
+ * #59's shape on the validation axis.
+ */
+export const adminCouponFormSchema = couponFormBase
+    .extend({
+    /*
+     * Widened past the seller's three. Only the platform runs buy-x-get-y —
+     * a seller offering one would be spending another seller's stock.
+     */
+    type: annotate(z.enum(["percentage", "fixed", "free_shipping", "buy_x_get_y"]), {
+        section: "basics", quick: true, order: 2, row: "pair", label: "Coupon type",
+    }),
+    name: annotate(z.string().min(1, "Give the campaign a name.").max(120), {
+        section: "basics", quick: true, order: 4, row: "pair", label: "Campaign name",
+    }),
+    description: annotate(z.string().max(500).optional().or(z.literal("")), {
+        section: "basics", order: 5, row: "full", kind: "textarea",
+    }),
+    buyQuantity: annotate(numericString("Buy quantity"), {
+        section: "basics", order: 6, row: "pair", kind: "number",
+        when: (v) => v.type === "buy_x_get_y",
+    }),
+    getQuantity: annotate(numericString("Get quantity"), {
+        section: "basics", order: 7, row: "pair", kind: "number",
+        when: (v) => v.type === "buy_x_get_y",
+    }),
+    /*
+     * Written by orders, never by this form. `t3-mirror` renders it read-only
+     * instead of as a box an admin could set to whatever they liked — which is
+     * what "Current usage" was, `disabled` by an attribute a programmatic
+     * submit ignores.
+     */
+    currentUsage: annotate(z.number().int().min(0).optional(), {
+        section: "limits", order: 5, row: "pair", derived: true, tier: "t3-mirror",
+        label: "Current usage", help: "Updated by orders.",
+    }),
+    firstTimeUserOnly: annotate(z.boolean(), {
+        section: "scope", order: 3, row: "quarter", label: "First-time users only",
+    }),
+    appliesToAuctions: annotate(z.boolean(), {
+        section: "scope", order: 4, row: "quarter", label: "Applies to auctions",
+    }),
 })
     .superRefine((v, ctx) => {
-    const issue = (path, message) => ctx.addIssue({ code: z.ZodIssueCode.custom, path: [path], message });
-    // A discount value is required for everything except free shipping, and
-    // a percentage above 100 is not a discount — it is the store paying the
-    // customer. Nothing bounded this before.
-    if (v.type !== "free_shipping") {
-        const amount = Number(v.value);
-        if (v.value.trim() === "")
-            issue("value", "A discount value is required.");
-        else if (amount <= 0)
-            issue("value", "The discount must be greater than zero.");
-        else if (v.type === "percentage" && amount > 100) {
-            issue("value", "A percentage discount cannot exceed 100%.");
+    refineCouponCommon(v, ctx);
+    // A buy-x-get-y with a zero on either side is not an offer.
+    if (v.type === "buy_x_get_y") {
+        for (const key of ["buyQuantity", "getQuantity"]) {
+            const n = Number(v[key]);
+            if (v[key].trim() === "" || !Number.isFinite(n) || n < 1) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: [key],
+                    message: "Enter a whole number of one or more.",
+                });
+            }
         }
     }
-    if (v.startDate && v.endDate && v.startDate > v.endDate) {
-        issue("endDate", "The end date must be after the start date.");
-    }
-    // A per-customer limit above the total makes the total unreachable — the
-    // coupon reads as more generous than it can ever be.
-    const total = Number(v.totalLimit);
-    const perUser = Number(v.perUserLimit);
-    if (v.totalLimit.trim() && v.perUserLimit.trim() && perUser > total) {
-        issue("perUserLimit", "Uses per customer cannot exceed the total uses.");
-    }
 });

package/dist/features/seller/schemas/offer-forms.d.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import type { OfferBounds } from "../../../_internal/shared/features/offers/config";
 export declare const counterOfferFormSchema: z.ZodObject<{
     counterAmount: z.ZodNumber;
     sellerNote: z.ZodOptional<z.ZodString>;
@@ -13,16 +14,24 @@ export type CounterOfferFormValues = z.infer<typeof counterOfferFormSchema>;
 /**
  * Buyer-side Make-an-Offer form.
  *
- * A factory rather than a constant because both bounds depend on the listing:
- * the floor is `minOfferAmount(listedPrice, minOfferPercent)` and the ceiling is
- * the listed price itself. Both are re-checked server-side in `makeOffer` — this
- * exists so the buyer is told before submitting, using the SAME
- * `minOfferAmount()` the server uses, rather than a second rounding rule that
- * could disagree by a rupee.
+ * A factory rather than a constant because both bounds depend on the listing.
+ * It takes the already-resolved `OfferBounds` rather than recomputing them:
+ * `resolveOfferBounds()` is what `makeOffer` enforces, so anything this schema
+ * accepts, the server accepts. Deriving a second floor here is exactly how the
+ * forms came to advertise a 50% minimum the server rejected at 70 (see the
+ * offers config header).
+ *
+ * Three shapes, all from the same bounds object:
+ *
+ * - **Buy request** (`isBuyRequest`) — no cart on this type and no haggling
+ *   opted in, so `min === max` and the only legal amount is the asking price.
+ * - **Offer, no cart** — floor to asking price *inclusive*: with no Add to Cart
+ *   button, refusing a full-price offer would leave the buyer nowhere to go.
+ * - **Offer, cartable** — the original rule, ceiling exclusive of the price.
  */
 export declare function makeOfferFormSchema(opts: {
     listedPrice: number;
-    minOffer: number;
+    bounds: OfferBounds;
     formatAmount: (n: number) => string;
 }): z.ZodObject<{
     offerAmount: z.ZodNumber;

package/dist/features/seller/schemas/offer-forms.js

@@ -31,21 +31,37 @@ export const counterOfferFormSchema = z.object({
 /**
  * Buyer-side Make-an-Offer form.
  *
- * A factory rather than a constant because both bounds depend on the listing:
- * the floor is `minOfferAmount(listedPrice, minOfferPercent)` and the ceiling is
- * the listed price itself. Both are re-checked server-side in `makeOffer` — this
- * exists so the buyer is told before submitting, using the SAME
- * `minOfferAmount()` the server uses, rather than a second rounding rule that
- * could disagree by a rupee.
+ * A factory rather than a constant because both bounds depend on the listing.
+ * It takes the already-resolved `OfferBounds` rather than recomputing them:
+ * `resolveOfferBounds()` is what `makeOffer` enforces, so anything this schema
+ * accepts, the server accepts. Deriving a second floor here is exactly how the
+ * forms came to advertise a 50% minimum the server rejected at 70 (see the
+ * offers config header).
+ *
+ * Three shapes, all from the same bounds object:
+ *
+ * - **Buy request** (`isBuyRequest`) — no cart on this type and no haggling
+ *   opted in, so `min === max` and the only legal amount is the asking price.
+ * - **Offer, no cart** — floor to asking price *inclusive*: with no Add to Cart
+ *   button, refusing a full-price offer would leave the buyer nowhere to go.
+ * - **Offer, cartable** — the original rule, ceiling exclusive of the price.
  */
 export function makeOfferFormSchema(opts) {
-    const { listedPrice, minOffer, formatAmount } = opts;
+    const { listedPrice, bounds, formatAmount } = opts;
+    const amount = z.coerce
+        .number({ invalid_type_error: "Enter an offer amount." })
+        .positive("Offer amount must be greater than zero.");
+    const bounded = bounds.isBuyRequest
+        ? amount
+            .min(bounds.min, `This seller is not taking lower offers — the price is ${formatAmount(bounds.min)}.`)
+            .max(bounds.max, `This seller is not taking lower offers — the price is ${formatAmount(bounds.max)}.`)
+        : amount
+            .min(bounds.min, `Minimum offer is ${formatAmount(bounds.min)}.`)
+            .max(bounds.max, bounds.max >= listedPrice
+            ? `Your offer cannot exceed the asking price of ${formatAmount(listedPrice)}.`
+            : `Offer must be below the listed price of ${formatAmount(listedPrice)} — use Add to Cart to buy at that price.`);
     return z.object({
-        offerAmount: z.coerce
-            .number({ invalid_type_error: "Enter an offer amount." })
-            .positive("Offer amount must be greater than zero.")
-            .min(minOffer, `Minimum offer is ${formatAmount(minOffer)}.`)
-            .max(listedPrice - 0.01, `Offer must be below the listed price of ${formatAmount(listedPrice)} — use Add to Cart to buy at that price.`),
+        offerAmount: bounded,
         buyerNote: z.string().max(300, "Keep your note under 300 characters.").optional(),
     });
 }

package/dist/features/shell/FormShell.js

@@ -6,7 +6,7 @@ import { Button } from "../../ui/components/Button";
 import { IconButton } from "../../ui/components/IconButton";
 import { classNames } from "../../ui/style.helper";
 import { FORM_ACTION_META, FORM_ACTION_ID } from "../products/constants/action-defs";
-import { Div, Row, Span, Stack, Text } from "../../ui";
+import { ActionRow, Div, Row, Span, Stack, Text } from "../../ui";
 /**
  * Carries the `schema` prop passed to `<FormShell>` down to any nested
  * `<SectionForm>` that doesn't declare its own `schema`/`SectionDef.schema` —
@@ -125,5 +125,5 @@ export function FormShell({ isOpen, onClose, title, breadcrumb, schema, isDirty
     return (_jsxs(FormSchemaContext.Provider, { value: schema, children: [_jsx(Div, { surface: "overlay-sm", className: "fixed inset-0 backdrop-blur-[2px]", style: { zIndex: "calc(var(--appkit-z-modal) - 1)" }, "aria-hidden": "true", onClick: attemptClose }), _jsxs(Div, { layout: "flex", ref: panelRef, role: "dialog", "aria-modal": "true", "aria-label": title, className: "fixed top-0 bottom-0 left-0 right-0 lg:left-[10%] lg:right-[10%] [flex-direction:column] bg-[var(--appkit-color-surface)]", shadow: "2xl", style: { zIndex: "var(--appkit-z-modal)" }, children: [_jsxs(Row, { gap: "sm", paddingX: "x-5", className: "flex-shrink-0 sticky top-0 z-10 border-b border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface)]", padding: "y-sm", children: [previewMode ? (_jsxs(Button, { variant: "ghost", type: "button", onClick: () => setPreviewMode(false), "aria-label": "Back to edit", gap: "xs", rounded: "lg", textSize: "sm", textColor: "muted", className: "flex-shrink-0", children: [_jsx(ArrowLeft, { className: "w-4 h-4" }), _jsx(Span, { className: "hidden sm:inline", children: "Back to Edit" })] })) : (_jsx(IconButton, { type: "button", onClick: attemptClose, "aria-label": "Close", variant: "ghost", rounded: "lg", className: "text-[var(--appkit-color-text-muted)] flex-shrink-0", children: _jsx(X, { className: "w-5 h-5" }) })), _jsxs(Div, { className: "flex-1 min-w-0", children: [breadcrumb && (_jsx(Text, { className: "text-[var(--appkit-color-text-muted)] truncate mb-0.5", size: "xs", children: breadcrumb })), _jsx(Text, { className: "text-[var(--appkit-color-text)] truncate", size: "sm", weight: "semibold", children: previewMode ? `Preview — ${title}` : title })] }), _jsx(Row, { gap: "xs", className: "flex-shrink-0", children: previewMode ? null : (_jsxs(_Fragment, { children: [previewSlot && (_jsxs(Button, { variant: "outline", type: "button", onClick: () => setPreviewMode(true), gap: "xs", rounded: "lg", paddingX: "sm", textSize: "sm", textColor: "muted", children: [_jsx(Eye, { className: "w-4 h-4" }), _jsx(Span, { className: "hidden sm:inline", children: "Preview" })] })), onSaveDraft && (_jsx(Button, { variant: "outline", size: "sm", onClick: handleSaveDraft, disabled: isLoading || savingDraft || publishing, isLoading: savingDraft, children: saveLabel })), onPublish && (_jsx(Button, { variant: "primary", size: "sm", onClick: handlePublish, disabled: isLoading || savingDraft || publishing, isLoading: publishing, children: publishLabel }))] })) })] }), _jsxs(Div, { layout: "flex", className: `flex-1 ${__O.hidden}`, children: [sections && sections.length > 0 && !previewMode && (_jsx("nav", { "aria-label": "Form sections", className: "hidden lg:flex flex-col flex-shrink-0 w-48 border-r border-[var(--appkit-color-border)] py-[var(--appkit-space-4)] px-[var(--appkit-space-3)] gap-[var(--appkit-space-1)] overflow-y-auto", children: sections.map((sec) => (_jsx(Button, { variant: "ghost", type: "button", onClick: () => scrollToSection(sec.id), rounded: "lg", paddingX: "sm", paddingY: "xs", textSize: "sm", textColor: "muted", justify: "start", className: "text-left", children: sec.label }, sec.id))) })), sections && sections.length > 0 && !previewMode && (_jsx(Row, { gap: "px", className: `lg:hidden fixed top-[var(--form-shell-topbar-h,57px)] left-0 right-0 z-10 ${__O.xAuto} px-[1.25rem] bg-[var(--appkit-color-surface)] border-b border-[var(--appkit-color-border)]`, padding: "y-xs", children: sections.map((sec) => (_jsx(Button, { variant: "outline", type: "button", onClick: () => scrollToSection(sec.id), rounded: "full", paddingX: "sm", paddingY: "xs", textSize: "xs", textColor: "muted", className: "flex-shrink-0 hover:border-primary hover:text-primary whitespace-nowrap", children: sec.label }, sec.id))) })), _jsx(Div, { ref: bodyRef, className: classNames("flex-1 overflow-y-auto", sections && sections.length > 0 && !previewMode ? "pt-[var(--appkit-space-0)] lg:pt-[var(--appkit-space-0)]" : ""), children: previewMode && previewSlot ? (_jsxs(_Fragment, { children: [_jsxs(Row, { textSize: "sm", gap: "xs", className: "sticky top-0 z-10 bg-[var(--appkit-color-warning-surface)] border-b border-[var(--appkit-color-warning)] text-[var(--appkit-color-warning-text,var(--appkit-color-warning))]", paddingY: "y-xs", paddingX: "x-md", children: [_jsx(Eye, { className: "w-4 h-4 flex-shrink-0" }), _jsx(Span, { children: "Preview \u2014 not visible to buyers until published" })] }), _jsx(Div, { padding: "y-md", children: previewSlot() })] })) : splitPreview && previewSlot ? (
                                 // S-STORE-3-D — desktop 60/40 split: form left, preview right.
                                 // Below `lg`, falls back to single-column form (preview-as-modal via existing toggle).
-                                _jsxs(Div, { className: "lg:grid lg:grid-cols-[3fr_2fr] lg:gap-[1.5rem] lg:px-[1.5rem] lg:py-[1.5rem] lg:max-w-[1400px] lg:mx-auto", children: [_jsx(Div, { className: "max-w-3xl mx-auto px-[1.25rem] sm:px-[1.5rem] lg:max-w-none lg:px-[0] lg:py-[0]", padding: "y-lg", children: children }), _jsxs(Div, { className: `hidden lg:block sticky lg:top-4 lg:self-start lg:max-h-[calc(100vh-6rem)] ${__O.yAuto} border border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface-raised)] ${__P.p4}`, rounded: "lg", children: [_jsxs(Row, { textWeight: "semibold", textSize: "xs", gap: "xs", className: "mb-3 uppercase tracking-wide text-[var(--appkit-color-text-muted)]", children: [_jsx(Eye, { className: "w-3.5 h-3.5" }), _jsx(Span, { children: "Live preview" })] }), previewSlot()] })] })) : (_jsx(Div, { className: "max-w-3xl mx-auto px-[1.25rem] sm:px-[1.5rem]", padding: "y-lg", children: children })) })] }), !previewMode && renderBottomBar ? (renderBottomBar()) : !previewMode && (onSaveDraft || onPublish) ? (_jsxs(Stack, { gap: "none", className: "flex-shrink-0 sticky bottom-0 z-10 border-t border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface)]", children: [footerTopSlot && (_jsx(Div, { paddingX: "x-5", padding: "t-sm", children: footerTopSlot })), _jsxs(Row, { justify: "between", paddingX: "x-5", padding: "y-sm", style: { paddingBottom: "calc(var(--appkit-space-3) + var(--keyboard-inset-height, 0px))" }, children: [_jsx(Button, { variant: "ghost", size: "sm", onClick: attemptClose, disabled: isLoading, children: FORM_ACTION_META[FORM_ACTION_ID.DISCARD].label }), _jsxs(Row, { gap: "xs", children: [onSaveDraft && (_jsx(Button, { variant: "outline", size: "sm", onClick: handleSaveDraft, disabled: isLoading || savingDraft || publishing, isLoading: savingDraft, children: saveLabel })), onPublish && (_jsxs(Button, { variant: "primary", size: "sm", onClick: handlePublish, disabled: isLoading || savingDraft || publishing, isLoading: publishing, children: [publishLabel, " \u2192"] }))] })] })] })) : null] }), showUnsaved && (_jsxs(_Fragment, { children: [_jsx(Div, { surface: "overlay-lg", className: "fixed inset-0", style: { zIndex: "var(--appkit-z-confirm)" }, onClick: () => setShowUnsaved(false) }), _jsxs(Div, { className: "fixed top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2 w-[90vw] max-w-sm bg-[var(--appkit-color-surface)]", shadow: "2xl", rounded: "xl", padding: "lg", style: { zIndex: "var(--appkit-z-confirm)" }, children: [_jsxs(Row, { gap: "sm", align: "start", className: "mb-4", children: [_jsx(Span, { layout: "flex-center", className: "flex-shrink-0 w-10 h-10 bg-[var(--appkit-color-warning-surface)]", rounded: "full", children: _jsx(AlertTriangle, { className: "w-5 h-5 text-[var(--appkit-color-warning)]" }) }), _jsxs(Stack, { gap: "xs", children: [_jsx(Text, { className: "text-[var(--appkit-color-text)]", weight: "semibold", children: "Unsaved changes" }), _jsx(Text, { className: "text-[var(--appkit-color-text-muted)]", size: "sm", children: "You have unsaved changes. Leave without saving?" })] })] }), _jsxs(Row, { gap: "xs", justify: "end", children: [_jsx(Button, { variant: "outline", size: "sm", onClick: () => setShowUnsaved(false), children: "Stay" }), _jsx(Button, { variant: "danger", size: "sm", onClick: () => { setShowUnsaved(false); onClose(); }, children: "Leave" })] })] })] }))] }));
+                                _jsxs(Div, { className: "lg:grid lg:grid-cols-[3fr_2fr] lg:gap-[1.5rem] lg:px-[1.5rem] lg:py-[1.5rem] lg:max-w-[1400px] lg:mx-auto", children: [_jsx(Div, { className: "max-w-3xl mx-auto px-[1.25rem] sm:px-[1.5rem] lg:max-w-none lg:px-[0] lg:py-[0]", padding: "y-lg", children: children }), _jsxs(Div, { className: `hidden lg:block sticky lg:top-4 lg:self-start lg:max-h-[calc(100vh-6rem)] ${__O.yAuto} border border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface-raised)] ${__P.p4}`, rounded: "lg", children: [_jsxs(Row, { textWeight: "semibold", textSize: "xs", gap: "xs", className: "mb-3 uppercase tracking-wide text-[var(--appkit-color-text-muted)]", children: [_jsx(Eye, { className: "w-3.5 h-3.5" }), _jsx(Span, { children: "Live preview" })] }), previewSlot()] })] })) : (_jsx(Div, { className: "max-w-3xl mx-auto px-[1.25rem] sm:px-[1.5rem]", padding: "y-lg", children: children })) })] }), !previewMode && renderBottomBar ? (renderBottomBar()) : !previewMode && (onSaveDraft || onPublish) ? (_jsxs(Stack, { gap: "none", className: "flex-shrink-0 sticky bottom-0 z-10 border-t border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface)]", children: [footerTopSlot && (_jsx(Div, { paddingX: "x-5", padding: "t-sm", children: footerTopSlot })), _jsxs(ActionRow, { align: "end", paddingX: "x-5", padding: "y-sm", style: { paddingBottom: "calc(var(--appkit-space-3) + var(--keyboard-inset-height, 0px))" }, anchor: _jsx(Button, { variant: "ghost", size: "sm", onClick: attemptClose, disabled: isLoading, children: FORM_ACTION_META[FORM_ACTION_ID.DISCARD].label }), children: [onSaveDraft && (_jsx(Button, { variant: "outline", size: "sm", onClick: handleSaveDraft, disabled: isLoading || savingDraft || publishing, isLoading: savingDraft, children: saveLabel })), onPublish && (_jsxs(Button, { variant: "primary", size: "sm", onClick: handlePublish, disabled: isLoading || savingDraft || publishing, isLoading: publishing, children: [publishLabel, " \u2192"] }))] })] })) : null] }), showUnsaved && (_jsxs(_Fragment, { children: [_jsx(Div, { surface: "overlay-lg", className: "fixed inset-0", style: { zIndex: "var(--appkit-z-confirm)" }, onClick: () => setShowUnsaved(false) }), _jsxs(Div, { className: "fixed top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2 w-[90vw] max-w-sm bg-[var(--appkit-color-surface)]", shadow: "2xl", rounded: "xl", padding: "lg", style: { zIndex: "var(--appkit-z-confirm)" }, children: [_jsxs(Row, { gap: "sm", align: "start", className: "mb-4", children: [_jsx(Span, { layout: "flex-center", className: "flex-shrink-0 w-10 h-10 bg-[var(--appkit-color-warning-surface)]", rounded: "full", children: _jsx(AlertTriangle, { className: "w-5 h-5 text-[var(--appkit-color-warning)]" }) }), _jsxs(Stack, { gap: "xs", children: [_jsx(Text, { className: "text-[var(--appkit-color-text)]", weight: "semibold", children: "Unsaved changes" }), _jsx(Text, { className: "text-[var(--appkit-color-text-muted)]", size: "sm", children: "You have unsaved changes. Leave without saving?" })] })] }), _jsxs(Row, { gap: "xs", justify: "end", children: [_jsx(Button, { variant: "outline", size: "sm", onClick: () => setShowUnsaved(false), children: "Stay" }), _jsx(Button, { variant: "danger", size: "sm", onClick: () => { setShowUnsaved(false); onClose(); }, children: "Leave" })] })] })] }))] }));
 }

package/dist/features/shell/QuickFormDrawer.js

@@ -6,7 +6,7 @@ import { Button } from "../../ui/components/Button";
 import { IconButton } from "../../ui/components/IconButton";
 import { FormField } from "../../ui/components/FormField";
 import { Toggle } from "../../ui/components/Toggle";
-import { Div, Form, Row, Stack, Text } from "../../ui";
+import { ActionRow, Div, Form, Row, Stack, Text } from "../../ui";
 import { FormShellContext, FormErrorSummary } from "../../ui/forms";
 import { useHandMode } from "../../_internal/client/hand-mode";
 function initValues(fields, defaults = {}) {
@@ -203,5 +203,5 @@ export function QuickFormDrawer({ isOpen, onClose, title, fields, defaultValues,
                                                     : field.type === "select"
                                                         ? "select"
                                                         : "text", value: String(value ?? ""), onChange: (v) => set(field.name, field.type === "number" ? Number(v) : v), options: field.options, placeholder: field.placeholder, disabled: busy, error: errors[field.name] }), field.helperText && !errors[field.name] && (_jsx(Text, { className: "mt-1 text-[var(--appkit-color-text-muted)]", size: "xs", children: field.helperText }))] }, field.name));
-                                }), renderExtra?.(values, set)] }), _jsxs(Div, { className: "flex-shrink-0 border-t border-[var(--appkit-color-border)] bg-[var(--appkit-color-bg)]", children: [_jsx(Div, { paddingX: "x-md", padding: "t-sm", children: _jsx(FormErrorSummary, {}) }), _jsxs(Row, { padding: "md", align: "center", justify: "between", gap: "sm", children: [_jsx(Button, { variant: "outline", size: "sm", onClick: handleClose, disabled: busy, children: cancelLabel }), _jsxs(Button, { variant: "primary", size: "sm", onClick: () => void handleSubmit(), disabled: busy, isLoading: busy, children: [submitLabel, " \u2192"] })] })] })] })] }) }));
+                                }), renderExtra?.(values, set)] }), _jsxs(Div, { className: "flex-shrink-0 border-t border-[var(--appkit-color-border)] bg-[var(--appkit-color-bg)]", children: [_jsx(Div, { paddingX: "x-md", padding: "t-sm", children: _jsx(FormErrorSummary, {}) }), _jsxs(ActionRow, { padding: "md", children: [_jsx(Button, { variant: "outline", size: "sm", onClick: handleClose, disabled: busy, children: cancelLabel }), _jsxs(Button, { variant: "primary", size: "sm", onClick: () => void handleSubmit(), disabled: busy, isLoading: busy, children: [submitLabel, " \u2192"] })] })] })] })] }) }));
 }

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

@@ -110,6 +110,14 @@ export interface SectionFormProps<T extends object = Record<string, JsonValue>>
 export declare function orderSections<T extends object>(sections: SectionDef<T>[]): SectionDef<T>[];
 /** `fieldName -> index into the ORDERED section list`. */
 export declare function buildFieldToSectionIndex<T extends object>(ordered: SectionDef<T>[]): Record<string, number>;
+export interface UseSectionFormNavOptions {
+    /**
+     * `"{portal}:{surface}"` — persists this form's open set to the user's
+     * profile. Omit for in-memory-only, which is the default and what every
+     * pre-existing call site gets.
+     */
+    scope?: string;
+}
 export interface UseSectionFormNavResult<T extends object> {
     /** Sections in render order — required first. */
     ordered: SectionDef<T>[];
@@ -126,8 +134,18 @@ export interface UseSectionFormNavResult<T extends object> {
  * `fieldToSectionIndex` into `useFormShellState(schema, nav)` and `openIds`
  * back into `<SectionForm>`.
  */
-export declare function useSectionFormNav<T extends object = Record<string, JsonValue>>(sections: SectionDef<T>[], values?: T): UseSectionFormNavResult<T>;
+export declare function useSectionFormNav<T extends object = Record<string, JsonValue>>(sections: SectionDef<T>[], values?: T, opts?: UseSectionFormNavOptions): UseSectionFormNavResult<T>;
 /** DOM id for a section panel — kept in one place so nav and render agree. */
 export declare function sectionAnchorId(id: string): string;
+/**
+ * Scroll a section into view and focus the first invalid control inside it.
+ *
+ * Deliberately module-level and shared by `goToSection` and `SectionForm`'s own
+ * submit handler: the deferred frame is the load-bearing part and is easy to
+ * drop when copying. The panel must MOUNT before it can be scrolled to —
+ * expanding is a state update, so without the deferral the scroll lands on a
+ * zero-height collapsed header and the offending field stays off-screen.
+ */
+export declare function scrollToSection(id: string): void;
 export declare function SectionForm<T extends object = Record<string, JsonValue>>({ sections, values, onChange, onSubmit, submitLabel, isLoading, schema, openIds: controlledOpenIds, onOpenChange, expandMode, hideActions, destructiveAction, onValidationChange, onCancel, cancelLabel, bottomBar, }: SectionFormProps<T>): import("react").JSX.Element;
 export default SectionForm;