@mohasinac/appkit 4.31.1 → 4.32.1

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.
  *

package/dist/features/stores/actions/store-query-actions.js

@@ -19,13 +19,15 @@ import { PRODUCT_FIELDS } from "../../../constants/field-names";
 export async function listStores(params = {}, viewer) {
     const { filters, sorts = "-createdAt", page = 1, pageSize = 24, q } = params;
     const model = { filters, sorts, page, pageSize };
+    // The same fix as the admin route: `q` travels as the searchTxt term, not as
+    // `storeName_=`, which was a prefix match on the name alone.
     const filtersArr = [];
-    if (q)
-        filtersArr.push(`storeName_=${q}`);
     if (filters)
         filtersArr.push(filters);
     model.filters = filtersArr.join(",") || undefined;
-    const result = await storeRepository.listStores(model);
+    const result = await storeRepository.listStores(model, true, {
+        search: q || undefined,
+    });
     return { ...result, items: filterTestDataForViewer(result.items, viewer) };
 }
 /**

package/dist/features/stores/repository/store.repository.d.ts

@@ -98,7 +98,9 @@ export declare class StoreRepository extends BaseRepository<StoreDocument> {
     /**
      * Admin: list all stores regardless of status.
      */
-    listAllStores(model: SieveModel): Promise<FirebaseSieveResult<StoreDocument>>;
+    listAllStores(model: SieveModel, opts?: {
+        search?: string;
+    }): Promise<FirebaseSieveResult<StoreDocument>>;
     /**
      * Cloud Functions: atomically increment `stats.totalProducts` counter.
      */

package/dist/features/stores/repository/store.repository.js

@@ -230,8 +230,12 @@ export class StoreRepository extends BaseRepository {
     /**
      * Admin: list all stores regardless of status.
      */
-    async listAllStores(model) {
-        return this.listStores(model, false);
+    async listAllStores(model, opts) {
+        // 🛑 `opts` is forwarded. It was not, so the admin store list had no way to
+        // reach the `searchTxt` path `listStores` already implements — and both its
+        // caller and the public one fell back to `storeName_=`, a PREFIX match on
+        // the name alone. "Beyblade Arena" was unfindable by "arena".
+        return this.listStores(model, false, opts);
     }
     /**
      * Cloud Functions: atomically increment `stats.totalProducts` counter.

package/dist/features/tester/seed-data/tester-checklist-seed-data.js

@@ -396,6 +396,12 @@ const rawTesterChecklistItems = [
             href: "/products",
             cases: [
                 { key: "standard-detail", label: "Standard product detail page loads correctly", href: "/products/product-tester-standard-1" },
+                {
+                    key: "tester-fixtures-hidden-from-the-public",
+                    label: "SIGNED OUT, no product on /products has an id containing \"tester\" — the sandbox is invisible to the public",
+                    description: "Fixed 2026-09-01. BEFORE: the public products endpoint had no viewer concept, so an ANONYMOUS caller got 25 tester fixtures in its first 40 rows — stickers-tester-sandbox-1, prizedraw-tester-sandbox-closed, live-tester-sandbox-1 — and they filled the public marketplace. AFTER: open /products in a private window and scan the grid; nothing should be named \"Tester …\". Then sign in AS A TESTER and reload — the sandbox items must come back. Both halves matter: hiding them from everyone would break the tester programme, and a fixture that never reappears is the opposite bug.",
+                    href: "/products",
+                },
                 {
                     key: "seed-images-are-labelled-tiles",
                     label: "Every seeded product image is a readable tile showing the item's own name — NOT a broken-image icon and NOT an empty grey box",
@@ -2053,6 +2059,79 @@ const rawTesterChecklistItems = [
                 { key: "shipping-configs-crud", label: "Creating, editing, and listing shipping configs works", href: "/store/shipping-configs" },
                 { key: "payout-methods-crud", label: "Adding, editing, and listing payout methods works", href: "/store/payout-methods" },
                 { key: "payout-settings-page", label: "Payout settings page saves correctly", href: "/store/payout-settings" },
+                {
+                    key: "consolidated-tabs-old-urls",
+                    label: "Each absorbed URL still lands on the right TAB, not just the right page",
+                    description: "W8 C2 folded six sibling pages into tabs. BEFORE: /store/payout-methods, /store/payout-settings, /store/shipping-configs, /store/print-center, /store/slug, /admin/permissions and /admin/settings/navigation were each their own page with their own sidebar entry. AFTER: each redirects to its host with ?tab= set, and the sidebar entry is gone. Visit all seven old URLs. Each must land on the host page with the CORRECT tab already selected — a landing on the host's FIRST tab is the failure, and it looks like success unless you check which tab is active.",
+                    href: "/store/payout-methods",
+                },
+                {
+                    key: "consolidated-tabs-url-writeback",
+                    label: "Clicking a tab updates ?tab= in the address bar",
+                    description: "BEFORE: the settings page read ?tab= once on load and never wrote it back, so copying the URL after clicking a tab shared the DEFAULT tab. AFTER: every tabbed page writes the tab into the URL on click. On /store/payouts click through all three tabs, watch ?tab= change, then copy the address and open it in a new tab — it must reopen on the same panel. Back must leave the page rather than walking back through the tabs.",
+                    href: "/store/payouts",
+                },
+                {
+                    key: "print-center-selection-deeplink",
+                    label: "Print labels for a selection still carries the selection through the redirect",
+                    description: "/store/print-center is now a redirect, and it is deep-linked from the orders and products lists as ?type=order&ids=…&autoprint=1. Select two orders on /store/orders, use the print action, and confirm the Print Centre tab opens with those two orders loaded. Arriving at an EMPTY Print Centre is the failure — it looks like a normal empty state, which is why this case names the before.",
+                    href: "/store/orders",
+                },
+                {
+                    key: "search-box-promises-match-corpus",
+                    label: "Every dashboard search box matches what its placeholder promises",
+                    description: "BEFORE: four boxes promised a match the data could not make. /admin/prize-draws, /admin/deals and /admin/featured each read \"or seller\" while the product search index carries no store name at all, and /admin/stores read \"slugs, or owner names\" while the route ran a STARTS-WITH match on the store name alone. Each returned an empty list that reads as \"there are none\", not as \"this box cannot search that\". AFTER: type a seller's name into /admin/prize-draws — the placeholder no longer offers it. On /admin/stores type a word from the MIDDLE of a store's name (\"arena\", for Beyblade Arena) and a word from its description: both must now return it.",
+                    href: "/admin/stores",
+                },
+                {
+                    key: "exact-search-boxes-commit-on-enter",
+                    label: "The two exact-match boxes say so and do not search while you type",
+                    description: "/admin/audit-log matches `actorUid` and /admin/notifications matches `userId`, both by EQUALITY — a partial id matches nothing. Both placeholders now say \"(exact)\". Type half a uid: the list must not churn per keystroke, and must not show \"no results\" until you press Enter. Each intermediate query would be a billed read that cannot match.",
+                    href: "/admin/audit-log",
+                },
+                {
+                    key: "consolidated-tabs-command-palette",
+                    label: "The absorbed surfaces are still findable by name in search",
+                    description: "Their sidebar entries were deleted, and the action index is derived from the sidebar — so without a deliberate entry they would vanish from search on the day they became easier to reach. Search for \"upi\", \"threshold\", \"barcode\", \"slug\" and \"permissions catalogue\". Each must return a result that opens the right TAB.",
+                    href: "/store/payouts",
+                },
+            ],
+        },
+        {
+            pageKey: "sectionised-forms",
+            pageLabel: "Forms — sections, error summary and the mobile bar",
+            href: "/admin/orders",
+            cases: [
+                {
+                    key: "form-sections-save-unchanged",
+                    label: "Every migrated form still saves exactly the fields it saved before",
+                    description: "W8 C3 moved 16 hand-rolled forms onto <SectionForm>. The risk is a field that renders but no longer reaches the payload. On each of these, change EVERY field, save, reload, and confirm each value came back: the admin order editor (status, tracking number, carrier, notes), the admin user editor (role, email verified, display name, phone, tester flags, admin notes, bio, location, website, four social links), WhatsApp settings, the seller order panel, and the ad settings panel. A field that silently reverts is the failure, and nothing errors when it happens.",
+                    href: "/admin/orders",
+                },
+                {
+                    key: "form-error-summary-jumps",
+                    label: "A validation error names its section and jumps to it",
+                    description: "BEFORE: an invalid field produced a banner listing the problem with no way to reach it, and on the site-settings page the summary was mounted outside every form context and so displayed NOTHING at all. AFTER: submit a form with a bad value (a negative refund on an order, a non-https third-party ad URL, an AdSense id that is not ca-pub-…) and the summary must list it, tag it with its section, collapse open that section when clicked, and show a count badge on the section header.",
+                    href: "/admin/ads",
+                },
+                {
+                    key: "form-mobile-action-bar",
+                    label: "Save and Cancel appear in the pinned mobile bar, once",
+                    description: "On a phone-width viewport, a page-level form publishes its actions into the bottom chrome tier. Open /admin/products/new and confirm exactly ONE Save row is visible — not one in the page and one pinned. Inside a drawer or modal (the admin order editor, the review reply modal) the pinned bar must NOT appear: an overlay owns its own footer, and a viewport-fixed bar renders behind the backdrop.",
+                    href: "/admin/products/new",
+                },
+                {
+                    key: "form-conditional-fields-drop-values",
+                    label: "A field hidden by a condition does not submit a stale value",
+                    description: "BEFORE: hiding a control left its last value in the payload. AFTER: on the admin user editor, switch \"Is Tester\" ON, tick \"Can test admin areas\", switch \"Is Tester\" back OFF, save, reload — the admin-test flag must be false. Same shape on a shipment item: enter a price, tick \"for self use\", save; the price must not be stored.",
+                    href: "/admin/users",
+                },
+                {
+                    key: "site-settings-save-still-writes-everything",
+                    label: "Site settings still saves every tab's fields in one Save",
+                    description: "Its 20 tabs write ONE document through one payload, and its schema is deliberately passthrough because that payload carries keys the TypeScript interface does not declare. A closed schema here would silently strip them. Change one field on each of three different tabs, press \"Save all changes\" once, reload, and confirm all three persisted — and that fields on tabs you did NOT touch are unchanged.",
+                    href: "/admin/site",
+                },
             ],
         },
         {

package/dist/features/whatsapp-bot/components/SellerWhatsAppSettingsView.js

@@ -12,12 +12,15 @@ const __O = {
 };
 const CLS_SECTION_CARD = "border border-[var(--appkit-color-border)] rounded-xl p-[var(--appkit-space-5)]";
 import { useQuery, useQueryClient } from "@tanstack/react-query";
-import { Alert, Badge, Button, Div, Form, FormActions, Heading, Input, Row, Section, Span, Stack, Text, Toggle, useToast } from "../../../ui";
+import { Alert, Badge, Button, Div, Heading, Input, Row, Section, Span, Stack, Text, Toggle, useToast } from "../../../ui";
 import { apiClient } from "../../../http";
 import { WHATSAPP_SELLER_ENDPOINTS } from "../../../constants/api-endpoints";
 import { ACTIONS } from "../../../_internal/shared/actions/action-registry";
 import { buildPurchaseAnnouncementMessage } from "../helpers/whatsapp";
-import { whatsappSettingsSchema } from "../../admin/schemas/admin-user-form";
+import { whatsappConnectionSchema, } from "../../admin/schemas/admin-user-form";
+import { SectionForm, useSectionFormNav, buildSectionsFromSchema, visibleValues, } from "../../shell";
+import { useFormShellState, FormShellContext } from "../../../ui/forms";
+import { applyZodIssues } from "../../../ui/forms/apply-zod-issues";
 import { FormErrorSummary } from "../../../ui/forms/FormErrorSummary";
 // ---------------------------------------------------------------------------
 // Sub-components
@@ -101,20 +104,40 @@ export function SellerWhatsAppSettingsView({ hasCapability }) {
     });
     const cfg = data ?? null;
     // Connection form state
-    const [phoneNumber, setPhoneNumber] = React.useState("");
-    const [wabaId, setWabaId] = React.useState("");
-    const [catalogId, setCatalogId] = React.useState("");
-    const [accessToken, setAccessToken] = React.useState("");
+    const [draft, setDraft] = React.useState({
+        phoneNumber: "",
+        wabaId: "",
+        catalogId: "",
+        accessToken: "",
+    });
     const [syncEnabled, setSyncEnabled] = React.useState(false);
     React.useEffect(() => {
         if (!cfg)
             return;
-        setPhoneNumber(cfg.phoneNumber ?? "");
-        setWabaId(cfg.wabaId ?? "");
-        setCatalogId(cfg.catalogId ?? "");
-        setAccessToken(cfg.accessToken ?? "");
+        setDraft({
+            phoneNumber: cfg.phoneNumber ?? "",
+            wabaId: cfg.wabaId ?? "",
+            catalogId: cfg.catalogId ?? "",
+            accessToken: cfg.accessToken ?? "",
+        });
         setSyncEnabled(cfg.catalogSyncEnabled ?? false);
     }, [cfg]);
+    /*
+     * The access token needs a renderer: it is a `text` field to the schema, and
+     * the control is a masked input with a reveal that must stay suppressed while
+     * the field still holds the server's sentinel.
+     */
+    const sections = React.useMemo(() => buildSectionsFromSchema(whatsappConnectionSchema, {
+        renderers: {
+            accessToken: ({ values, onChange }) => (_jsx(MaskedTokenInput, { label: "System User Access Token", value: values.accessToken ?? "", onChange: (v) => onChange({ accessToken: v }), placeholder: "EAAxxxxxxxx\u2026", helperText: "Long-lived token with WhatsApp Business permissions" })),
+        },
+    }), []);
+    const nav = useSectionFormNav(sections, draft, { scope: "store:whatsapp" });
+    const form = useFormShellState(whatsappConnectionSchema, {
+        sections: nav.sectionMeta,
+        onGoToSection: nav.goToSection,
+        fieldToSectionIndex: nav.fieldToSectionIndex,
+    });
     /*
      * The CONNECTION form. Credentials only.
      *
@@ -131,16 +154,17 @@ export function SellerWhatsAppSettingsView({ hasCapability }) {
     const saveMutation = useApiMutation({
         errorMessage: "Failed to save settings.",
         mutationFn: async () => {
+            const v = visibleValues(whatsappConnectionSchema, draft);
             const payload = {};
-            if (phoneNumber)
-                payload.phoneNumber = phoneNumber;
-            if (wabaId)
-                payload.wabaId = wabaId;
-            if (catalogId)
-                payload.catalogId = catalogId;
+            if (v.phoneNumber)
+                payload.phoneNumber = v.phoneNumber;
+            if (v.wabaId)
+                payload.wabaId = v.wabaId;
+            if (v.catalogId)
+                payload.catalogId = v.catalogId;
             // Only send accessToken if user has typed a new value (not the masked placeholder)
-            if (accessToken && accessToken !== MASKED_TOKEN)
-                payload.accessToken = accessToken;
+            if (v.accessToken && v.accessToken !== MASKED_TOKEN)
+                payload.accessToken = v.accessToken;
             return apiClient.put(WHATSAPP_SELLER_ENDPOINTS.SETTINGS, payload);
         },
         onSuccess: () => {
@@ -224,10 +248,17 @@ export function SellerWhatsAppSettingsView({ hasCapability }) {
                                     ? cfg?.connected === true
                                     : Boolean(cfg?.[step.checkKey]);
                             return (_jsxs(Row, { gap: "sm", align: "start", children: [_jsx(Row, { textWeight: "bold", textSize: "xs", className: `flex-shrink-0 w-6 h-6 mt-0.5 ${done ? "bg-[var(--appkit-color-success)] text-white" : "bg-[var(--appkit-color-surface-elevated)] text-[var(--appkit-color-text-muted)] dark:text-[var(--appkit-color-text-faint)]"}`, align: "center", justify: "center", rounded: "full", children: done ? "✓" : step.n }), _jsxs(Div, { children: [_jsx(Text, { size: "sm", weight: "medium", color: "primary", children: step.title }), _jsx(Text, { className: "mt-0.5", color: "muted", size: "xs", children: step.body })] })] }, step.n));
-                        }) })] }), _jsxs(Section, { className: CLS_SECTION_CARD, children: [_jsxs(Row, { justify: "between", align: "center", className: "mb-4", children: [_jsx(Heading, { level: 2, size: "sm", weight: "semibold", color: "primary", children: "Connection" }), isLoading ? null : cfg?.connected ? (_jsx(Badge, { variant: "success", children: "Connected" })) : (_jsx(Badge, { variant: "default", children: "Not configured" }))] }), _jsxs(Form, { schema: whatsappSettingsSchema, onSubmit: (e) => {
-                            e.preventDefault();
-                            saveMutation.mutate();
-                        }, spacing: "md", children: [_jsx(FormErrorSummary, {}), _jsx(Input, { label: "WhatsApp Business Phone Number", value: phoneNumber, onChange: (e) => setPhoneNumber(e.target.value), placeholder: "919876543210", helperText: "Digits only, include country code (e.g. 91 for India)" }), _jsx(Input, { label: "WABA ID (WhatsApp Business Account ID)", value: wabaId, onChange: (e) => setWabaId(e.target.value), placeholder: "123456789012345", helperText: "From Meta Business Manager \u2192 WhatsApp Accounts" }), _jsx(Input, { label: "Catalog ID", value: catalogId, onChange: (e) => setCatalogId(e.target.value), placeholder: "987654321098765", helperText: "From Meta Commerce Manager \u2192 Catalogs" }), _jsx(MaskedTokenInput, { label: "System User Access Token", value: accessToken, onChange: setAccessToken, placeholder: "EAAxxxxxxxx\u2026", helperText: "Long-lived token with WhatsApp Business permissions" }), _jsx(FormActions, { align: "right", children: _jsx(Button, { type: "submit", isLoading: saveMutation.isPending, disabled: saveMutation.isPending, children: saveMutation.isPending ? "Saving…" : ACTIONS.STORE["whatsapp-connect"].label }) })] })] }), _jsxs(Section, { className: CLS_SECTION_CARD, children: [_jsx(Heading, { level: 2, className: "mb-4", color: "primary", size: "sm", weight: "semibold", children: "Catalog Sync" }), _jsxs(Row, { justify: "between", align: "center", className: "mb-4", children: [_jsxs(Div, { children: [_jsx(Text, { size: "sm", color: "muted", children: "Enable catalog sync" }), _jsx(Text, { size: "xs", color: "muted", children: "When enabled, your published standard products can be synced to WhatsApp." })] }), _jsx(Toggle, { checked: syncEnabled, onChange: handleSyncToggle, disabled: !cfg?.connected || syncToggleMutation.isPending })] }), cfg?.lastCatalogSyncAt && (_jsxs(Row, { color: "muted", textSize: "xs", gap: "sm", align: "center", className: "mb-3", children: [_jsxs(Text, { children: ["Last sync: ", new Date(cfg.lastCatalogSyncAt).toLocaleString("en-IN")] }), cfg.lastSyncCount !== undefined && _jsxs(Text, { children: ["\u00B7 ", cfg.lastSyncCount, " products"] }), cfg.lastSyncStatus && (_jsx(Badge, { variant: STATUS_VARIANT[cfg.lastSyncStatus] ?? "default", children: cfg.lastSyncStatus }))] })), _jsx(Text, { className: "mb-3", color: "faint", size: "xs", children: "Only published standard products are synced. Auctions and pre-orders are excluded. Batches of up to 50 products per call." }), _jsxs(Row, { gap: "3", children: [_jsx(Button, { onClick: () => syncMutation.mutate(), isLoading: syncMutation.isPending, disabled: !cfg?.connected || !syncEnabled || syncMutation.isPending, variant: "secondary", children: syncMutation.isPending ? "Syncing…" : ACTIONS.STORE["whatsapp-catalog-sync"].label }), _jsx(Button, { onClick: () => void startImport(), isLoading: importing, disabled: !cfg?.connected || !syncEnabled || importing, variant: "secondary", children: importing ? "Importing…" : ACTIONS.STORE["whatsapp-catalog-import"].label })] }), _jsxs(Text, { className: "mt-3", color: "faint", size: "xs", children: [_jsx(Span, { weight: "bold", children: "Push" }), " sends your published standard products to WhatsApp.", " ", _jsx(Span, { weight: "bold", children: "Import" }), " creates draft products from your WhatsApp catalog. Products are matched by slug in the description field."] })] }), _jsxs(Section, { className: CLS_SECTION_CARD, children: [_jsx(Heading, { level: 2, className: "mb-2", color: "primary", size: "sm", weight: "semibold", children: "Purchase Announcement Preview" }), _jsx(Text, { className: "mb-3", color: "muted", size: "xs", children: "This message is sent automatically to your phone and the platform admin when a new order is placed." }), _jsx(Div, { textSize: "sm", className: "font-mono", color: "primary", surface: "muted", padding: "inline", rounded: "lg", children: buildPurchaseAnnouncementMessage({
+                        }) })] }), _jsxs(Section, { className: CLS_SECTION_CARD, children: [_jsxs(Row, { justify: "between", align: "center", className: "mb-4", children: [_jsx(Heading, { level: 2, size: "sm", weight: "semibold", color: "primary", children: "Connection" }), isLoading ? null : cfg?.connected ? (_jsx(Badge, { variant: "success", children: "Connected" })) : (_jsx(Badge, { variant: "default", children: "Not configured" }))] }), _jsxs(FormShellContext.Provider, { value: form.shellCtx, children: [_jsx(FormErrorSummary, {}), _jsx(SectionForm, { sections: sections, values: draft, onChange: (partial) => setDraft((d) => ({ ...d, ...partial })), onSubmit: () => {
+                                    // SectionForm scrolls to the first bad section and then submits
+                                    // regardless, so the guard lives here.
+                                    form.clearErrors();
+                                    const parsed = whatsappConnectionSchema.safeParse(visibleValues(whatsappConnectionSchema, draft));
+                                    if (!parsed.success) {
+                                        applyZodIssues(parsed.error.issues, form.setFieldError);
+                                        return;
+                                    }
+                                    saveMutation.mutate();
+                                }, onValidationChange: () => form.validate(draft), schema: whatsappConnectionSchema, openIds: nav.openIds, onOpenChange: nav.setOpenIds, submitLabel: ACTIONS.STORE["whatsapp-connect"].label, isLoading: saveMutation.isPending })] })] }), _jsxs(Section, { className: CLS_SECTION_CARD, children: [_jsx(Heading, { level: 2, className: "mb-4", color: "primary", size: "sm", weight: "semibold", children: "Catalog Sync" }), _jsxs(Row, { justify: "between", align: "center", className: "mb-4", children: [_jsxs(Div, { children: [_jsx(Text, { size: "sm", color: "muted", children: "Enable catalog sync" }), _jsx(Text, { size: "xs", color: "muted", children: "When enabled, your published standard products can be synced to WhatsApp." })] }), _jsx(Toggle, { checked: syncEnabled, onChange: handleSyncToggle, disabled: !cfg?.connected || syncToggleMutation.isPending })] }), cfg?.lastCatalogSyncAt && (_jsxs(Row, { color: "muted", textSize: "xs", gap: "sm", align: "center", className: "mb-3", children: [_jsxs(Text, { children: ["Last sync: ", new Date(cfg.lastCatalogSyncAt).toLocaleString("en-IN")] }), cfg.lastSyncCount !== undefined && _jsxs(Text, { children: ["\u00B7 ", cfg.lastSyncCount, " products"] }), cfg.lastSyncStatus && (_jsx(Badge, { variant: STATUS_VARIANT[cfg.lastSyncStatus] ?? "default", children: cfg.lastSyncStatus }))] })), _jsx(Text, { className: "mb-3", color: "faint", size: "xs", children: "Only published standard products are synced. Auctions and pre-orders are excluded. Batches of up to 50 products per call." }), _jsxs(Row, { gap: "3", children: [_jsx(Button, { onClick: () => syncMutation.mutate(), isLoading: syncMutation.isPending, disabled: !cfg?.connected || !syncEnabled || syncMutation.isPending, variant: "secondary", children: syncMutation.isPending ? "Syncing…" : ACTIONS.STORE["whatsapp-catalog-sync"].label }), _jsx(Button, { onClick: () => void startImport(), isLoading: importing, disabled: !cfg?.connected || !syncEnabled || importing, variant: "secondary", children: importing ? "Importing…" : ACTIONS.STORE["whatsapp-catalog-import"].label })] }), _jsxs(Text, { className: "mt-3", color: "faint", size: "xs", children: [_jsx(Span, { weight: "bold", children: "Push" }), " sends your published standard products to WhatsApp.", " ", _jsx(Span, { weight: "bold", children: "Import" }), " creates draft products from your WhatsApp catalog. Products are matched by slug in the description field."] })] }), _jsxs(Section, { className: CLS_SECTION_CARD, children: [_jsx(Heading, { level: 2, className: "mb-2", color: "primary", size: "sm", weight: "semibold", children: "Purchase Announcement Preview" }), _jsx(Text, { className: "mb-3", color: "muted", size: "xs", children: "This message is sent automatically to your phone and the platform admin when a new order is placed." }), _jsx(Div, { textSize: "sm", className: "font-mono", color: "primary", surface: "muted", padding: "inline", rounded: "lg", children: buildPurchaseAnnouncementMessage({
                             buyerName: "Ravi K.",
                             firstItemName: "Charizard PSA 9",
                             additionalItemCount: 2,

package/dist/index.d.ts

@@ -3220,5 +3220,9 @@ export { SITE_SETTINGS_ENTRIES, deriveSettingsEntries, } from "./features/search
 export type { SettingsIndexSource } from "./features/search/action-index/settings-entries";
 export { SITE_SETTINGS_TABS, SITE_SETTINGS_TAB_IDS, isSiteSettingsTabId, } from "./features/admin/constants/site-settings-tabs";
 export type { SiteSettingsTab, SiteSettingsTabId } from "./features/admin/constants/site-settings-tabs";
+export { PAYOUTS_TABS, isPayoutsTabId, SHIPPING_TABS, isShippingTabId, FULFILLMENT_TABS, isFulfillmentTabId, STOREFRONT_TABS, isStorefrontTabId, } from "./features/seller/constants/store-tabs";
+export type { StoreDashboardTab, PayoutsTabId, ShippingTabId, FulfillmentTabId, StorefrontTabId, } from "./features/seller/constants/store-tabs";
+export { ROLES_TABS, isRolesTabId, ADMIN_SETTINGS_TABS, isAdminSettingsTabId, } from "./features/admin/constants/admin-page-tabs";
+export type { AdminPageTab, RolesTabId, AdminSettingsTabId, } from "./features/admin/constants/admin-page-tabs";
 export { validateActionIndexEntry, normaliseRoute, } from "./features/search/action-index/validate-entry";
 export type { ActionIndexValidationContext, ActionIndexValidationIssue, } from "./features/search/action-index/validate-entry";

package/dist/index.js

@@ -5626,4 +5626,6 @@ export { deriveNavEntries, deriveQuickActionEntries, buildActionIndexBase, } fro
 export { matchesNavQuery } from "./_internal/shared/features/layout/matchesNavQuery";
 export { SITE_SETTINGS_ENTRIES, deriveSettingsEntries, } from "./features/search/action-index/settings-entries";
 export { SITE_SETTINGS_TABS, SITE_SETTINGS_TAB_IDS, isSiteSettingsTabId, } from "./features/admin/constants/site-settings-tabs";
+export { PAYOUTS_TABS, isPayoutsTabId, SHIPPING_TABS, isShippingTabId, FULFILLMENT_TABS, isFulfillmentTabId, STOREFRONT_TABS, isStorefrontTabId, } from "./features/seller/constants/store-tabs";
+export { ROLES_TABS, isRolesTabId, ADMIN_SETTINGS_TABS, isAdminSettingsTabId, } from "./features/admin/constants/admin-page-tabs";
 export { validateActionIndexEntry, normaliseRoute, } from "./features/search/action-index/validate-entry";

package/dist/next/index.d.ts

@@ -36,5 +36,7 @@ export { navItemId } from "../_internal/shared/features/layout/types";
 export { matchesNavQuery } from "../_internal/shared/features/layout/matchesNavQuery";
 export { buildActionIndexBase, deriveNavEntries, deriveQuickActionEntries, } from "../features/search/action-index/derive";
 export { deriveSettingsEntries } from "../features/search/action-index/settings-entries";
+export { deriveConsolidatedTabEntries, CONSOLIDATED_TAB_SURFACES, } from "../features/search/action-index/tab-entries";
+export type { ConsolidatedTabSurface, ConsolidatedTabHrefs, } from "../features/search/action-index/tab-entries";
 export { mergeActionIndex, projectActionIndexForViewer, } from "../features/search/action-index/types";
 export type { ActionIndexEntry, ActionIndexControl, ActionIndexOverride, } from "../features/search/action-index/types";

package/dist/next/index.js

@@ -62,4 +62,5 @@ export { matchesNavQuery } from "../_internal/shared/features/layout/matchesNavQ
  */
 export { buildActionIndexBase, deriveNavEntries, deriveQuickActionEntries, } from "../features/search/action-index/derive";
 export { deriveSettingsEntries } from "../features/search/action-index/settings-entries";
+export { deriveConsolidatedTabEntries, CONSOLIDATED_TAB_SURFACES, } from "../features/search/action-index/tab-entries";
 export { mergeActionIndex, projectActionIndexForViewer, } from "../features/search/action-index/types";

package/dist/react/hooks/useTabParam.d.ts

@@ -0,0 +1,19 @@
+export interface UseTabParamOptions {
+    /**
+     * A locale-aware router, when the caller has one. Without it the plain
+     * `next/navigation` router drops the locale prefix on replace.
+     */
+    router?: {
+        replace: (url: string) => void;
+    };
+    pathname?: string;
+}
+/**
+ * The active tab, kept in `?tab=`.
+ *
+ * `isValid` is the page's own type guard — `isSiteSettingsTabId`,
+ * `isPayoutsTabId`, and so on — so an unknown value in the URL is IGNORED
+ * rather than written into state. That is what makes a stale bookmark open the
+ * default tab instead of rendering an empty panel.
+ */
+export declare function useTabParam<T extends string>(isValid: (value: string | null | undefined) => value is T, fallback: T, options?: UseTabParamOptions): [T, (next: string) => void];