@mohasinac/appkit 4.31.0 → 4.32.0

package/dist/features/seller/constants/store-tabs.js

@@ -0,0 +1,60 @@
+/*
+ * WHY: W8's C2 folds sibling store pages that are one task into one tabbed
+ *      page. Each absorbed page keeps a `?tab=` deep link so it stays findable
+ *      from the command palette and from a bookmark, and the action index's
+ *      `AIX_DEAD_DEEPLINK` check needs a union to validate those links
+ *      against — a deep link naming a tab that does not exist opens the page
+ *      on its default tab and reads as the search having missed.
+ *
+ * ## 🛑 Tab ids are NOT nav hrefs
+ *
+ * `navItemId(portal, href)` strips the query, so `/store/payouts` and
+ * `/store/payouts?tab=methods` produce the SAME nav id — which is at once the
+ * `navConfig` toggle key, the gate that makes `requiredPermission` run, and the
+ * action-index entry id. So the absorbed pages keep their own hrefs (as
+ * redirect shells) and these ids live only in `?tab=`.
+ *
+ * EXPORTS:
+ *   PAYOUTS_TABS / isPayoutsTabId, SHIPPING_TABS / isShippingTabId,
+ *   FULFILLMENT_TABS / isFulfillmentTabId, STOREFRONT_TABS / isStorefrontTabId
+ *
+ * @tag domain:seller
+ * @tag layer:constants
+ * @tag pattern:registry
+ * @tag access:isomorphic
+ * @tag consumers:store payouts/shipping/fulfillment/storefront pages,action index
+ * @tag sideEffects:none
+ */
+/** "Get paid": what I am owed, where it goes, on what schedule. */
+export const PAYOUTS_TABS = [
+    { id: "payouts", label: "Payouts", description: "What you have been paid, and what is still due." },
+    { id: "methods", label: "Methods", description: "Where your money goes — bank or UPI." },
+    { id: "settings", label: "Settings", description: "How often you get paid, and the minimum." },
+];
+export function isPayoutsTabId(value) {
+    return !!value && PAYOUTS_TABS.some((t) => t.id === value);
+}
+/** Shipping defaults, plus the reusable named presets built on top of them. */
+export const SHIPPING_TABS = [
+    { id: "rates", label: "Rates & zones", description: "What you charge to ship, and where you ship to." },
+    { id: "configs", label: "Named configs", description: "Named shipping rules you can reuse per listing." },
+];
+export function isShippingTabId(value) {
+    return !!value && SHIPPING_TABS.some((t) => t.id === value);
+}
+/** The pack-and-dispatch loop: the queue, then the paperwork it needs. */
+export const FULFILLMENT_TABS = [
+    { id: "queue", label: "Queue", description: "Orders waiting to be packed or handed over." },
+    { id: "print", label: "Print centre", description: "Print labels, invoices and barcodes in a batch." },
+];
+export function isFulfillmentTabId(value) {
+    return !!value && FULFILLMENT_TABS.some((t) => t.id === value);
+}
+/** The shop's identity — its look, and the address buyers reach it at. */
+export const STOREFRONT_TABS = [
+    { id: "profile", label: "Profile", description: "Your shop's name, logo, banner and description." },
+    { id: "slug", label: "Web address", description: "The web address buyers reach your shop at." },
+];
+export function isStorefrontTabId(value) {
+    return !!value && STOREFRONT_TABS.some((t) => t.id === value);
+}

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

@@ -0,0 +1,33 @@
+import { z } from "zod";
+/**
+ * 🛑 `""` is a real, meaningful value here — it is "keep the current status",
+ * which is what the panel's first option means and what its diff-against-the-
+ * loaded-order payload relies on. It is not an empty required field.
+ */
+export declare const sellerOrderUpdateSchema: z.ZodEffects<z.ZodObject<{
+    status: z.ZodEnum<["", "confirmed", "processing", "shipped", "delivered", "cancelled"]>;
+    trackingNumber: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>;
+    carrier: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>;
+    trackingUrl: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>;
+}, "strip", z.ZodTypeAny, {
+    status: "" | "cancelled" | "processing" | "delivered" | "confirmed" | "shipped";
+    trackingNumber?: string | undefined;
+    trackingUrl?: string | undefined;
+    carrier?: string | undefined;
+}, {
+    status: "" | "cancelled" | "processing" | "delivered" | "confirmed" | "shipped";
+    trackingNumber?: string | undefined;
+    trackingUrl?: string | undefined;
+    carrier?: string | undefined;
+}>, {
+    status: "" | "cancelled" | "processing" | "delivered" | "confirmed" | "shipped";
+    trackingNumber?: string | undefined;
+    trackingUrl?: string | undefined;
+    carrier?: string | undefined;
+}, {
+    status: "" | "cancelled" | "processing" | "delivered" | "confirmed" | "shipped";
+    trackingNumber?: string | undefined;
+    trackingUrl?: string | undefined;
+    carrier?: string | undefined;
+}>;
+export type SellerOrderUpdateValues = z.infer<typeof sellerOrderUpdateSchema>;

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

@@ -0,0 +1,75 @@
+/*
+ * WHY: The seller's "Update order" panel wrote a status change, a tracking
+ *      number, a carrier and a tracking URL with no schema at all — the one
+ *      form in the seller dashboard that changes what a BUYER sees about a
+ *      shipment they are waiting on.
+ *
+ *      Two rules were missing, both invisible until a buyer complained. A
+ *      tracking URL was a free string, so a typo'd or non-http value went
+ *      straight into the tracking link a buyer clicks. And a status could move
+ *      to `shipped` with no tracking number at all — the seller's own carrier
+ *      fields sat right there, empty, and nothing said so.
+ *
+ * WHAT: The four fields the panel offers, annotated for
+ *       `buildSectionsFromSchema`.
+ *
+ * EXPORTS:
+ *   sellerOrderUpdateSchema, type SellerOrderUpdateValues
+ *
+ * @tag domain:seller,orders
+ * @tag layer:schema
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:SellerOrderDetailPanel
+ * @tag sideEffects:none
+ */
+import { z } from "zod";
+import { annotate } from "../../shell/field-ui-meta";
+import { normalizeError } from "../../../errors/normalize";
+/**
+ * 🛑 `""` is a real, meaningful value here — it is "keep the current status",
+ * which is what the panel's first option means and what its diff-against-the-
+ * loaded-order payload relies on. It is not an empty required field.
+ */
+export const sellerOrderUpdateSchema = z
+    .object({
+    status: annotate(z.enum(["", "confirmed", "processing", "shipped", "delivered", "cancelled"]), {
+        section: "status", sectionLabel: "Update order", sectionRequired: true,
+        quick: true, order: 1, row: "full", kind: "select", label: "New status",
+    }),
+    trackingNumber: annotate(z.string().trim().max(120).optional().or(z.literal("")), {
+        section: "shipping", sectionLabel: "Shipment", order: 1, row: "pair",
+        label: "Tracking number",
+    }),
+    carrier: annotate(z.string().trim().max(80).optional().or(z.literal("")), {
+        section: "shipping", order: 2, row: "pair",
+    }),
+    trackingUrl: annotate(z.string().trim().max(2000).optional().or(z.literal("")), {
+        section: "shipping", order: 3, row: "full", inputType: "url",
+        label: "Tracking URL (optional)",
+    }),
+})
+    .superRefine((v, ctx) => {
+    const issue = (path, message) => ctx.addIssue({ code: z.ZodIssueCode.custom, path: [path], message });
+    // Marking an order shipped is what starts the buyer's "where is it"
+    // question, and the field that answers it is on this same panel.
+    if (v.status === "shipped" && !v.trackingNumber?.trim()) {
+        issue("trackingNumber", "A shipped order needs a tracking number.");
+    }
+    const url = v.trackingUrl?.trim();
+    if (url) {
+        let parsed = null;
+        try {
+            parsed = new URL(url);
+        }
+        catch (err) {
+            void normalizeError(err);
+            parsed = null;
+        }
+        if (!parsed)
+            issue("trackingUrl", "That is not a valid URL.");
+        else if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+            issue("trackingUrl", "A tracking URL must start with http or https.");
+        }
+    }
+});

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

@@ -0,0 +1,37 @@
+import { z } from "zod";
+/** Matches `replySchema` on `POST /api/store/reviews/[id]/reply`. */
+export declare const reviewReplySchema: z.ZodObject<{
+    reply: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    reply: string;
+}, {
+    reply: string;
+}>;
+export type ReviewReplyValues = z.infer<typeof reviewReplySchema>;
+/** The same reply, posted on every selected review. */
+export declare const reviewBulkReplySchema: z.ZodObject<{
+    reply: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    reply: string;
+}, {
+    reply: string;
+}>;
+export type ReviewBulkReplyValues = z.infer<typeof reviewBulkReplySchema>;
+/** Flags a review for admin investigation. */
+export declare const reviewContestSchema: z.ZodObject<{
+    reason: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    reason: string;
+}, {
+    reason: string;
+}>;
+export type ReviewContestValues = z.infer<typeof reviewContestSchema>;
+/** A private note to the buyer, never shown on the public review. */
+export declare const reviewFeedbackSchema: z.ZodObject<{
+    feedback: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    feedback: string;
+}, {
+    feedback: string;
+}>;
+export type ReviewFeedbackValues = z.infer<typeof reviewFeedbackSchema>;

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

@@ -0,0 +1,82 @@
+/*
+ * WHY: The seller's reviews page has FOUR write surfaces — reply, bulk reply,
+ *      contest, send-feedback — and not one of them had a schema. Every guard
+ *      was a `disabled={!text.trim()}` on the button, which is a UI hint, not a
+ *      rule: it says nothing about the ceiling the route enforces, and it
+ *      cannot say anything at all about content.
+ *
+ *      The reply route caps at 1000 characters. The textarea carried
+ *      `maxLength={1000}`, so the browser truncated silently rather than
+ *      saying so — a seller writing a long reply lost the tail with no message.
+ *      A schema puts the same number where it can be reported.
+ *
+ *      The contest route trims and requires a non-empty `reason` and nothing
+ *      more, so "x" filed a moderation request a human then has to interpret.
+ *      A ten-character floor matches the admin offer-cancel reason, which is
+ *      the same kind of record: the only durable account of why.
+ *
+ * WHAT: One schema per surface. Each is a single field, and that is the point —
+ *       they are the same shape as `hardBanReasonSchema`, and they get the same
+ *       error summary and section badge as every other form.
+ *
+ * EXPORTS:
+ *   reviewReplySchema, reviewBulkReplySchema, reviewContestSchema,
+ *   reviewFeedbackSchema, and their value types
+ *
+ * @tag domain:seller,reviews
+ * @tag layer:schema
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:SellerReviewsView
+ * @tag sideEffects:none
+ */
+import { z } from "zod";
+import { annotate } from "../../shell/field-ui-meta";
+/** Matches `replySchema` on `POST /api/store/reviews/[id]/reply`. */
+export const reviewReplySchema = z.object({
+    reply: annotate(z
+        .string()
+        .trim()
+        .min(1, "Write a reply before posting it.")
+        .max(1000, "A reply is capped at 1000 characters."), {
+        section: "reply", sectionLabel: "Store reply", sectionRequired: true,
+        quick: true, order: 1, row: "full", kind: "textarea",
+        help: "Shown publicly beneath the buyer's review.",
+    }),
+});
+/** The same reply, posted on every selected review. */
+export const reviewBulkReplySchema = z.object({
+    reply: annotate(z
+        .string()
+        .trim()
+        .min(1, "Write a reply before sending it.")
+        .max(1000, "A reply is capped at 1000 characters."), {
+        section: "reply", sectionLabel: "Reply", sectionRequired: true,
+        quick: true, order: 1, row: "full", kind: "textarea",
+        help: "The same reply will be posted on all selected reviews.",
+    }),
+});
+/** Flags a review for admin investigation. */
+export const reviewContestSchema = z.object({
+    reason: annotate(z
+        .string()
+        .trim()
+        .min(10, "Say why this review should be investigated — at least 10 characters.")
+        .max(1000), {
+        section: "contest", sectionLabel: "Reason", sectionRequired: true,
+        quick: true, order: 1, row: "full", kind: "textarea",
+        help: "Fake, abusive, off-topic — be specific; a moderator reads this.",
+    }),
+});
+/** A private note to the buyer, never shown on the public review. */
+export const reviewFeedbackSchema = z.object({
+    feedback: annotate(z
+        .string()
+        .trim()
+        .min(1, "Write your message before sending it.")
+        .max(1000, "Keep the message under 1000 characters."), {
+        section: "feedback", sectionLabel: "Feedback", sectionRequired: true,
+        quick: true, order: 1, row: "full", kind: "textarea",
+        help: "Sent to the buyer's notification inbox. Does not appear on the review.",
+    }),
+});

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

@@ -11,6 +11,6 @@ export { deriveQuickFields, deriveQuickFieldNames, allDefinitionFields, applyDer
 export type { FieldUiMeta, FieldRow, FieldKind, CalculatedTier, } from "./field-ui-meta";
 export { ui, annotate, ROW_COLUMNS, inferFieldUiMeta, resolveFieldUiMeta, unwrapSchema, schemaEnumOptions, schemaIsOptional, objectShape, } from "./field-ui-meta";
 export type { ResolvedField, FieldRenderer, BuildSectionsOptions, } from "./build-sections";
-export { buildSectionsFromSchema, resolveFields, groupFieldsBySection, packRows, } from "./build-sections";
+export { buildSectionsFromSchema, resolveFields, groupFieldsBySection, packRows, visibleValues, } from "./build-sections";
 export type { TitleDescriptionGroupProps, ImageFieldGroupProps, SeoFieldGroupProps, StatusFieldGroupProps, StatusFieldGroupOption, } from "./field-groups";
 export { TitleDescriptionGroup, ImageFieldGroup, SeoFieldGroup, StatusFieldGroup, } from "./field-groups";

package/dist/features/shell/index.js

@@ -4,5 +4,9 @@ export { QuickFormDrawer } from "./QuickFormDrawer";
 export { SectionForm, useSectionFormNav, orderSections, buildFieldToSectionIndex, sectionAnchorId, } from "./SectionForm";
 export { deriveQuickFields, deriveQuickFieldNames, allDefinitionFields, applyDerive, assertNoDeriveCollision, humaniseFieldName, } from "./entity-form";
 export { ui, annotate, ROW_COLUMNS, inferFieldUiMeta, resolveFieldUiMeta, unwrapSchema, schemaEnumOptions, schemaIsOptional, objectShape, } from "./field-ui-meta";
-export { buildSectionsFromSchema, resolveFields, groupFieldsBySection, packRows, } from "./build-sections";
+export { buildSectionsFromSchema, resolveFields, groupFieldsBySection, packRows, 
+// The payload builder. A `when` predicate hides a CONTROL, not a VALUE, so a
+// draft can still carry a field the user can no longer see — build the
+// submitted object from this, never from the raw draft.
+visibleValues, } from "./build-sections";
 export { TitleDescriptionGroup, ImageFieldGroup, SeoFieldGroup, StatusFieldGroup, } from "./field-groups";

package/dist/features/shipments/components/AdminShipmentLotItemsView.js

@@ -2,9 +2,12 @@
 import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
 import React from "react";
 import { useApiMutation } from "@mohasinac/appkit/client";
-import { Alert, Badge, Button, Div, FieldCheckbox, FieldInput, Grid, Heading, Modal, Pagination, Skeleton, Stack, Table, Thead, Tbody, Tr, Th, Td, Text, Textarea, } from "../../../ui";
+import { Alert, Badge, Button, Div, Heading, Modal, Pagination, Skeleton, Stack, Table, Thead, Tbody, Tr, Th, Td, Text, Textarea, } from "../../../ui";
 import { apiClient } from "../../../http";
-import { createShipmentItemSchema } from "../schemas/validation";
+import { createShipmentItemSchema, shipmentItemFormSchema, } from "../schemas/validation";
+import { SectionForm, useSectionFormNav, buildSectionsFromSchema, visibleValues, } from "../../shell";
+import { useFormShellState, FormShellContext, FormErrorSummary } from "../../../ui/forms";
+import { applyZodIssues } from "../../../ui/forms/apply-zod-issues";
 import { ValidationError } from "../../../errors/validation-error";
 import { ADMIN_ENDPOINTS } from "../../../constants/api-endpoints";
 import { ACTIONS } from "../../../_internal/shared/actions/action-registry";
@@ -34,10 +37,19 @@ export function AdminShipmentLotItemsView({ shipmentId, lotId }) {
     const [pageSize, setPageSize] = React.useState(50);
     const { items, meta, isLoading, refetch } = useShipmentItems(shipmentId, lotId, { page, pageSize });
     const [showAddItem, setShowAddItem] = React.useState(false);
-    const [title, setTitle] = React.useState("");
-    const [quantity, setQuantity] = React.useState("1");
-    const [priceRupees, setPriceRupees] = React.useState("0");
-    const [isForSelfUse, setIsForSelfUse] = React.useState(false);
+    const [itemDraft, setItemDraft] = React.useState({
+        title: "",
+        quantity: 1,
+        isForSelfUse: false,
+        price: 0,
+    });
+    const itemSections = React.useMemo(() => buildSectionsFromSchema(shipmentItemFormSchema), []);
+    const itemNav = useSectionFormNav(itemSections, itemDraft, { scope: "admin:shipment-item" });
+    const itemForm = useFormShellState(shipmentItemFormSchema, {
+        sections: itemNav.sectionMeta,
+        onGoToSection: itemNav.goToSection,
+        fieldToSectionIndex: itemNav.fieldToSectionIndex,
+    });
     const [showBulkImport, setShowBulkImport] = React.useState(false);
     const [bulkText, setBulkText] = React.useState("");
     const parsedBulkRows = React.useMemo(() => parseBulkText(bulkText), [bulkText]);
@@ -52,11 +64,19 @@ export function AdminShipmentLotItemsView({ shipmentId, lotId }) {
              * named no field. `Number(priceRupees)` also yields NaN on a typo,
              * which the schema rejects and the old payload sent.
              */
+            /*
+             * Built from `visibleValues`, so a price typed before "for self use" was
+             * ticked is dropped rather than submitted — the control is hidden by a
+             * `when` predicate, and a hidden control's value must not travel.
+             */
+            const draft = visibleValues(shipmentItemFormSchema, itemDraft);
             const parsed = createShipmentItemSchema.safeParse({
-                title,
-                quantity: Number(quantity),
-                isForSelfUse,
-                price: isForSelfUse ? undefined : Math.round(Number(priceRupees) * 100) / 100,
+                title: draft.title,
+                quantity: Number(draft.quantity),
+                isForSelfUse: draft.isForSelfUse,
+                price: draft.isForSelfUse
+                    ? undefined
+                    : Math.round(Number(draft.price ?? 0) * 100) / 100,
             });
             if (!parsed.success) {
                 // ValidationError carries the issue list; a bare Error flattens it to
@@ -66,10 +86,7 @@ export function AdminShipmentLotItemsView({ shipmentId, lotId }) {
             return apiClient.post(ADMIN_ENDPOINTS.SHIPMENT_LOT_ITEMS(shipmentId, lotId), parsed.data);
         },
         onSuccess: () => {
-            setTitle("");
-            setQuantity("1");
-            setPriceRupees("0");
-            setIsForSelfUse(false);
+            setItemDraft({ title: "", quantity: 1, isForSelfUse: false, price: 0 });
             setShowAddItem(false);
             refetch();
         },
@@ -105,7 +122,19 @@ export function AdminShipmentLotItemsView({ shipmentId, lotId }) {
         }),
         onSuccess: () => refetch(),
     });
-    return (_jsxs(Stack, { gap: "md", children: [_jsxs(Div, { layout: "flex", align: "center", justify: "between", children: [_jsxs(Heading, { level: 3, children: ["Lot Items (", meta?.total ?? items.length, "/500)"] }), _jsxs(Div, { className: "flex gap-[var(--appkit-space-2)]", children: [_jsx(Button, { size: "sm", variant: "secondary", onClick: () => setShowAddItem((v) => !v), children: showAddItem ? "Cancel" : "+ Add Item" }), _jsx(Button, { size: "sm", variant: "secondary", onClick: () => setShowBulkImport(true), children: "Bulk Import" })] })] }), _jsx(Alert, { variant: "info", children: "Only individually notable \"main\" items need a row here \u2014 everything else in the lot can be captured as a single remainder estimate on the lot itself. Linking an item to a product does not sync future edits either way." }), showAddItem && (_jsxs(Grid, { cols: 4, gap: "sm", children: [_jsx(FieldInput, { name: "title", label: "Title", required: true, value: title, onChange: setTitle }), _jsx(FieldInput, { name: "quantity", label: "Quantity", type: "number", min: "1", value: quantity, onChange: setQuantity }), _jsx(FieldInput, { name: "price", label: "Projected Sale Price (\u20B9)", type: "number", min: "0", value: priceRupees, onChange: setPriceRupees, disabled: isForSelfUse }), _jsx(FieldCheckbox, { name: "isForSelfUse", label: "For self use (no resale)", checked: isForSelfUse, onChange: setIsForSelfUse }), _jsx(Button, { size: "sm", isLoading: addItemMutation.isPending, disabled: !title || (!isForSelfUse && Number(priceRupees) <= 0), onClick: () => addItemMutation.mutate(), children: "Save Item" })] })), isLoading ? (_jsxs(Stack, { gap: "sm", children: [_jsx(Skeleton, { variant: "rectangular", height: "32px" }), _jsx(Skeleton, { variant: "rectangular", height: "32px" })] })) : items.length === 0 ? (_jsx(Text, { variant: "secondary", children: "No items tracked yet." })) : (_jsxs(Table, { children: [_jsx(Thead, { children: _jsxs(Tr, { children: [_jsx(Th, { children: "Title" }), _jsx(Th, { children: "Qty" }), _jsx(Th, { children: "Price" }), _jsx(Th, { children: "Status" }), _jsx(Th, {})] }) }), _jsx(Tbody, { children: items.map((item) => (_jsxs(Tr, { children: [_jsx(Td, { children: item.title }), _jsx(Td, { children: item.quantity }), _jsx(Td, { children: item.isForSelfUse ? "—" : formatCurrency(item.price ?? 0) }), _jsx(Td, { children: item.isForSelfUse ? (_jsx(Badge, { variant: "secondary", children: "Self use" })) : item.linkedProductId ? (_jsx(Badge, { variant: "success", children: "Linked" })) : (_jsx(Badge, { variant: "default", children: "Unlinked" })) }), _jsxs(Td, { className: "flex gap-[var(--appkit-space-2)]", children: [!item.isForSelfUse &&
+    return (_jsxs(Stack, { gap: "md", children: [_jsxs(Div, { layout: "flex", align: "center", justify: "between", children: [_jsxs(Heading, { level: 3, children: ["Lot Items (", meta?.total ?? items.length, "/500)"] }), _jsxs(Div, { className: "flex gap-[var(--appkit-space-2)]", children: [_jsx(Button, { size: "sm", variant: "secondary", onClick: () => setShowAddItem((v) => !v), children: showAddItem ? "Cancel" : "+ Add Item" }), _jsx(Button, { size: "sm", variant: "secondary", onClick: () => setShowBulkImport(true), children: "Bulk Import" })] })] }), _jsx(Alert, { variant: "info", children: "Only individually notable \"main\" items need a row here \u2014 everything else in the lot can be captured as a single remainder estimate on the lot itself. Linking an item to a product does not sync future edits either way." }), showAddItem && (_jsxs(FormShellContext.Provider, { value: itemForm.shellCtx, children: [_jsx(FormErrorSummary, {}), _jsx(SectionForm, { sections: itemSections, values: itemDraft, onChange: (partial) => setItemDraft((d) => ({ ...d, ...partial })), onSubmit: () => {
+                            /*
+                             * The guard lives here: SectionForm surfaces errors and scrolls to
+                             * them, then calls onSubmit unconditionally.
+                             */
+                            itemForm.clearErrors();
+                            const parsed = shipmentItemFormSchema.safeParse(visibleValues(shipmentItemFormSchema, itemDraft));
+                            if (!parsed.success) {
+                                applyZodIssues(parsed.error.issues, itemForm.setFieldError);
+                                return;
+                            }
+                            addItemMutation.mutate();
+                        }, onValidationChange: () => itemForm.validate(itemDraft), schema: shipmentItemFormSchema, openIds: itemNav.openIds, onOpenChange: itemNav.setOpenIds, submitLabel: "Save Item", cancelLabel: "Cancel", onCancel: () => setShowAddItem(false), isLoading: addItemMutation.isPending })] })), isLoading ? (_jsxs(Stack, { gap: "sm", children: [_jsx(Skeleton, { variant: "rectangular", height: "32px" }), _jsx(Skeleton, { variant: "rectangular", height: "32px" })] })) : items.length === 0 ? (_jsx(Text, { variant: "secondary", children: "No items tracked yet." })) : (_jsxs(Table, { children: [_jsx(Thead, { children: _jsxs(Tr, { children: [_jsx(Th, { children: "Title" }), _jsx(Th, { children: "Qty" }), _jsx(Th, { children: "Price" }), _jsx(Th, { children: "Status" }), _jsx(Th, {})] }) }), _jsx(Tbody, { children: items.map((item) => (_jsxs(Tr, { children: [_jsx(Td, { children: item.title }), _jsx(Td, { children: item.quantity }), _jsx(Td, { children: item.isForSelfUse ? "—" : formatCurrency(item.price ?? 0) }), _jsx(Td, { children: item.isForSelfUse ? (_jsx(Badge, { variant: "secondary", children: "Self use" })) : item.linkedProductId ? (_jsx(Badge, { variant: "success", children: "Linked" })) : (_jsx(Badge, { variant: "default", children: "Unlinked" })) }), _jsxs(Td, { className: "flex gap-[var(--appkit-space-2)]", children: [!item.isForSelfUse &&
                                             (item.linkedProductId ? (_jsx(Button, { size: "sm", variant: "ghost", isLoading: unlinkItemMutation.isPending, onClick: () => unlinkItemMutation.mutate(item.id), children: "Unlink" })) : (_jsx(Button, { size: "sm", variant: "ghost", onClick: () => setLinkTarget({ itemId: item.id, title: item.title }), children: "Create pre-order link" }))), _jsx(Button, { size: "sm", variant: "ghost", action: ACTIONS.SHIPMENT["delete"], isLoading: deleteItemMutation.isPending, onClick: () => deleteItemMutation.mutate(item.id), children: "Delete" })] })] }, item.id))) })] })), meta && meta.totalPages > 1 && (_jsx(Pagination, { currentPage: page, totalPages: meta.totalPages, onPageChange: setPage, pageSize: pageSize, onPageSizeChange: (size) => {
                     setPageSize(size);
                     setPage(1);

package/dist/features/shipments/schemas/validation.d.ts

@@ -262,6 +262,47 @@ export declare const createShipmentItemSchema: z.ZodEffects<z.ZodObject<{
     categorySlugs?: string[] | undefined;
     condition?: "new" | "used" | "refurbished" | "like_new" | "good" | "fair" | "poor" | "broken" | "graded" | undefined;
 }>;
+/**
+ * The four fields the add-item form actually offers, annotated for
+ * `buildSectionsFromSchema`.
+ *
+ * 🛑 A separate object rather than `shipmentItemBaseSchema.pick(...)`, for two
+ * reasons. `.pick()` returns NEW field instances and the annotation registry is
+ * a WeakMap keyed by instance, so the meta would not survive. And deriving the
+ * form from the full base schema would render `categorySlugs` (an array) and
+ * `condition` as controls the add-item row has never had — an array has no
+ * `FieldKind`, so it would appear as a disabled placeholder telling the user to
+ * supply a renderer.
+ *
+ * The base schema stays the API contract; this is the form's subset of it.
+ */
+export declare const shipmentItemFormSchema: z.ZodEffects<z.ZodObject<{
+    title: z.ZodString;
+    quantity: z.ZodNumber;
+    isForSelfUse: z.ZodBoolean;
+    price: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    title: string;
+    quantity: number;
+    isForSelfUse: boolean;
+    price?: number | undefined;
+}, {
+    title: string;
+    quantity: number;
+    isForSelfUse: boolean;
+    price?: number | undefined;
+}>, {
+    title: string;
+    quantity: number;
+    isForSelfUse: boolean;
+    price?: number | undefined;
+}, {
+    title: string;
+    quantity: number;
+    isForSelfUse: boolean;
+    price?: number | undefined;
+}>;
+export type ShipmentItemFormValues = z.infer<typeof shipmentItemFormSchema>;
 export declare const updateShipmentItemSchema: z.ZodObject<{
     title: z.ZodOptional<z.ZodString>;
     quantity: z.ZodOptional<z.ZodNumber>;

package/dist/features/shipments/schemas/validation.js

@@ -103,6 +103,55 @@ const shipmentItemBaseSchema = z.object({
     notes: z.string().optional(),
 });
 export const createShipmentItemSchema = shipmentItemBaseSchema.refine((item) => item.isForSelfUse || typeof item.price === "number", { message: "Projected sale price is required unless the item is for self use", path: ["price"] });
+/**
+ * The four fields the add-item form actually offers, annotated for
+ * `buildSectionsFromSchema`.
+ *
+ * 🛑 A separate object rather than `shipmentItemBaseSchema.pick(...)`, for two
+ * reasons. `.pick()` returns NEW field instances and the annotation registry is
+ * a WeakMap keyed by instance, so the meta would not survive. And deriving the
+ * form from the full base schema would render `categorySlugs` (an array) and
+ * `condition` as controls the add-item row has never had — an array has no
+ * `FieldKind`, so it would appear as a disabled placeholder telling the user to
+ * supply a renderer.
+ *
+ * The base schema stays the API contract; this is the form's subset of it.
+ */
+export const shipmentItemFormSchema = z
+    .object({
+    title: annotate(z.string().min(1, "Item title is required"), {
+        section: "item", sectionLabel: "Add item", sectionRequired: true,
+        order: 1, row: "pair", label: "Title",
+    }),
+    quantity: annotate(z.coerce.number().int().min(1, "At least one"), {
+        section: "item", order: 2, row: "quarter", kind: "number", label: "Quantity",
+    }),
+    isForSelfUse: annotate(z.boolean(), {
+        section: "item", order: 3, row: "quarter", kind: "toggle",
+        label: "For self use (no resale)",
+    }),
+    /*
+     * Hidden — not disabled — when the item is for self use. A self-use item has
+     * no projected sale price by definition, and `visibleValues()` then drops
+     * the value so a price typed before ticking the box cannot be submitted.
+     */
+    price: annotate(z.coerce.number().min(0).optional(), {
+        section: "item", order: 4, row: "pair", kind: "number",
+        label: "Projected sale price (₹)",
+        when: (v) => !v.isForSelfUse,
+    }),
+})
+    .superRefine((item, ctx) => {
+    // Mirrors `createShipmentItemSchema`'s refine. `when` hides the control; it
+    // does NOT relax the rule, so the rule has to tolerate the hidden case.
+    if (!item.isForSelfUse && typeof item.price !== "number") {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["price"],
+            message: "Projected sale price is required unless the item is for self use",
+        });
+    }
+});
 export const updateShipmentItemSchema = shipmentItemBaseSchema.partial().extend({
     // Link/unlink fields — written by the link route and by the unlink action
     // (PATCH with `null` to clear). Not part of item creation, so kept out of

package/dist/features/store-extensions/schemas/google-config-form.d.ts

@@ -18,6 +18,42 @@ export declare const storeGoogleConfigUpdateSchema: z.ZodObject<{
     businessName?: string | undefined;
 }>;
 export type StoreGoogleConfigFormValues = z.infer<typeof storeGoogleConfigUpdateSchema>;
+/**
+ * The seller-facing form schema — the same annotated fields, plus the one rule
+ * the server does not need.
+ *
+ * 🛑 `.superRefine()` wraps and returns a NEW schema instance, which is exactly
+ * why the annotations live on the FIELDS above rather than being applied here:
+ * the registry is a WeakMap keyed by instance, so `annotate()` must be the
+ * outermost call on each field, and any wrapper around the whole object is
+ * transparent to it. `objectShape()` sees through `.superRefine()` when
+ * `buildSectionsFromSchema` resolves the fields.
+ *
+ * The rule itself is a form-level one: a Place ID is only required once the
+ * seller has actually switched the feature on. Requiring it unconditionally
+ * would make an untouched, disconnected settings page fail validation on load.
+ */
+export declare const sellerGoogleReviewsFormSchema: z.ZodEffects<z.ZodObject<{
+    isConnected: z.ZodOptional<z.ZodBoolean>;
+    placeId: z.ZodOptional<z.ZodString>;
+    businessName: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    placeId?: string | undefined;
+    isConnected?: boolean | undefined;
+    businessName?: string | undefined;
+}, {
+    placeId?: string | undefined;
+    isConnected?: boolean | undefined;
+    businessName?: string | undefined;
+}>, {
+    placeId?: string | undefined;
+    isConnected?: boolean | undefined;
+    businessName?: string | undefined;
+}, {
+    placeId?: string | undefined;
+    isConnected?: boolean | undefined;
+    businessName?: string | undefined;
+}>;
 /**
  * What the seller's own settings page may see.
  *

package/dist/features/store-extensions/schemas/google-config-form.js

@@ -69,6 +69,30 @@ export const storeGoogleConfigUpdateSchema = z
     }),
 })
     .strict();
+/**
+ * The seller-facing form schema — the same annotated fields, plus the one rule
+ * the server does not need.
+ *
+ * 🛑 `.superRefine()` wraps and returns a NEW schema instance, which is exactly
+ * why the annotations live on the FIELDS above rather than being applied here:
+ * the registry is a WeakMap keyed by instance, so `annotate()` must be the
+ * outermost call on each field, and any wrapper around the whole object is
+ * transparent to it. `objectShape()` sees through `.superRefine()` when
+ * `buildSectionsFromSchema` resolves the fields.
+ *
+ * The rule itself is a form-level one: a Place ID is only required once the
+ * seller has actually switched the feature on. Requiring it unconditionally
+ * would make an untouched, disconnected settings page fail validation on load.
+ */
+export const sellerGoogleReviewsFormSchema = storeGoogleConfigUpdateSchema.superRefine((v, ctx) => {
+    if (v.isConnected && !(v.placeId ?? "").trim()) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["placeId"],
+            message: "A Place ID is required to show Google reviews on your store page",
+        });
+    }
+});
 /**
  * What the seller's own settings page may see.
  *