@mohasinac/appkit 4.31.1 → 4.32.1

package/dist/_internal/server/features/products/list-public.d.ts

@@ -1,3 +1,4 @@
+import { type ViewerLike } from "../tester/visibility";
 import type { JsonValue } from "../../../../schemas/types";
 import { type AvailabilityFilter } from "../../../../constants/field-names";
 /** Vercel Hobby Fluid Compute ceiling (CLAUDE.md Rule #6) — never fetch more at once. */
@@ -156,6 +157,23 @@ export interface PublicProductListOptions {
      * so tests can pin it.
      */
     now?: Date;
+    /**
+     * Who is asking, for tester-sandbox visibility.
+     *
+     * 🛑 Omitting it means ANONYMOUS, and anonymous never sees `isTestData` rows.
+     * Deliberately fail-closed: an undefined viewer is the default a caller gets
+     * by forgetting, and forgetting must not publish the sandbox.
+     *
+     * On 2026-08-31 the public `/api/products` returned **25 tester fixtures in
+     * its first 40 rows** to an unauthenticated caller — `stickers-tester-sandbox-1`,
+     * `prizedraw-tester-sandbox-closed`, `live-tester-sandbox-1` — because this
+     * function had no viewer concept at all. CLAUDE.md had already recorded that
+     * `filterTestDataForViewer` was wired into the STORE read paths only, and that
+     * the other listing routes "need the identical one-line treatment when touched
+     * next". This is that treatment, applied at the one shared implementation
+     * rather than at each of its callers.
+     */
+    viewer?: ViewerLike | null;
 }
 /** Every field path a per-type facet can filter on. Read by the wiring audit. */
 export declare const TYPE_FACET_FIELD_PATHS: string[];

package/dist/_internal/server/features/products/list-public.js

@@ -34,6 +34,7 @@
  * @tag sideEffects:firestore-read
  */
 import { productRepository } from "../../../../repositories";
+import { filterTestDataForViewer } from "../tester/visibility";
 import { normalizeError } from "../../../../errors/normalize";
 import { serverLogger } from "../../../../monitoring/server-logger";
 import { PRODUCT_FIELDS } from "../../../../constants/field-names";
@@ -464,6 +465,7 @@ export async function listPublicProducts(input, opts) {
             filters,
             sorts,
             enabled: opts?.enabledListingTypes,
+            viewer: opts?.viewer,
         });
     }
     // ── Path C: unavailable, everything else. One bounded query per distinct
@@ -528,6 +530,7 @@ export async function listPublicProducts(input, opts) {
             filters: clauses.map((c) => sieveAnd(safeFilters, clauseToSieve(c, now))).join(" OR "),
             sorts,
             enabled: opts?.enabledListingTypes,
+            viewer: opts?.viewer,
         });
     }
     // ── Path A ("all") and the dense "available" case share one query. The only
@@ -638,6 +641,7 @@ export async function listPublicProducts(input, opts) {
         filters,
         sorts,
         enabled: opts?.enabledListingTypes,
+        viewer: opts?.viewer,
     });
 }
 /**
@@ -661,17 +665,31 @@ async function runQuery(executor, query) {
         return null;
     }
 }
-/** Apply the feature-flag post-filter and assemble the result. */
+/** Apply the tester-visibility and feature-flag post-filters, then assemble. */
 function finish(draft) {
-    const { enabled, ...result } = draft;
-    if (!enabled || enabled.size === 0)
-        return result;
-    // Feature-flagged-off types never reach a public surface.
+    const { enabled, viewer, ...result } = draft;
     const before = result.items.length;
-    const items = result.items.filter((it) => {
-        const lt = typeof it.listingType === "string" ? it.listingType : "standard";
-        return enabled.has(lt);
-    });
+    /*
+     * Tester sandbox rows, unless the viewer may see them.
+     *
+     * 🛑 A post-filter, NOT a query clause. A Firestore inequality on the
+     * test-data flag excludes every document that LACKS the field — which is all
+     * real content, since the flag is new and optional — so such a query returns
+     * ONLY test data, exactly inverting the intent. That trap is written up in
+     * CLAUDE.md's tester section and is why `filterTestDataForViewer` exists as
+     * an in-memory filter in the first place.
+     *
+     * Cheap: the flag is sparse (~25 documents), so this drops a handful of rows
+     * from a page that was already fetched.
+     */
+    let items = filterTestDataForViewer(result.items, viewer);
+    // Feature-flagged-off types never reach a public surface.
+    if (enabled && enabled.size > 0) {
+        items = items.filter((it) => {
+            const lt = typeof it.listingType === "string" ? it.listingType : "standard";
+            return enabled.has(lt);
+        });
+    }
     const removed = before - items.length;
     return {
         ...result,

package/dist/client.d.ts

@@ -112,6 +112,8 @@ export type { LotteryConfigWriteInput } from "./features/lottery/schemas/config-
 export { PrizeDrawLotteryDetailView } from "./_internal/client/features/lottery/PrizeDrawLotteryDetailView";
 export type { LotteryConfig, LotterySlot, ClientLotterySlot, ClientLotteryConfig, LotteryPricingMode, LotteryEntryStatus } from "./features/lottery/types";
 export { BottomSheet } from "./features/layout/index";
+export { PageTabs } from "./features/layout/PageTabs";
+export type { PageTabDef, PageTabsProps } from "./features/layout/PageTabs";
 export { ImageUpload } from "./features/media/index";
 export type { ImageUploadProps } from "./features/media/index";
 export { AvatarUpload } from "./features/media/index";
@@ -126,6 +128,8 @@ export { useMediaUpload } from "./features/media/index";
 export { SessionProvider, useSession } from "./react/contexts/SessionContext";
 export type { SessionProviderProps } from "./react/contexts/SessionContext";
 export { useUrlTable } from "./react/hooks/useUrlTable";
+export { useTabParam } from "./react/hooks/useTabParam";
+export type { UseTabParamOptions } from "./react/hooks/useTabParam";
 export type { UseUrlTableOptions } from "./react/hooks/useUrlTable";
 export { useBulkSelection } from "./react/hooks/useBulkSelection";
 export type { UseBulkSelectionOptions, UseBulkSelectionReturn } from "./react/hooks/useBulkSelection";
@@ -218,6 +222,7 @@ export { AdminDashboardView, AdminAnalyticsView, AdminPageViewsReportView, Admin
 export type { AdminDashboardViewProps, AdminAnalyticsViewProps, AdminAnalyticsViewLabels, AdminPrizeDrawsViewProps, AdminCarouselViewProps, AdminFulfillmentViewProps, AdminListingScaffoldRow, ListingViewConfig } from "./features/admin/index";
 export type { BulkActionItem } from "./ui/components/BulkActionBar";
 export { PERMISSION_GROUPS, PERMISSION_DOMAINS, getPermissionsForDomain, formatPermLabel } from "./features/auth/permissions/constants";
+export { Details, Summary } from "./ui/components/Details";
 export { ADMIN_ENDPOINTS } from "./constants/index";
 export { SELLER_ENDPOINTS } from "./constants/index";
 export { TourProvider, useTour } from "./_internal/client/features/tour/TourProvider";
@@ -499,6 +504,10 @@ 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";
 export { AdminActionIndexView } from "./features/admin/components/AdminActionIndexView";

package/dist/client.js

@@ -168,6 +168,7 @@ export { PrizeDrawLotteryDetailView } from "./_internal/client/features/lottery/
 // [CLIENT-ONLY]-Cannot run in SSR mode â€" uses browser-only APIs (window, navigator, localStorage, matchMedia, DOM events) that do not exist in Node.js.
 // BottomSheet - Shared export for bottom sheet.
 export { BottomSheet } from "./features/layout/index";
+export { PageTabs } from "./features/layout/PageTabs";
 export { ImageUpload } from "./features/media/index";
 export { AvatarUpload } from "./features/media/index";
 // [CLIENT-ONLY]-Cannot run in SSR mode â€" uses browser-only APIs (window, navigator, localStorage, matchMedia, DOM events) that do not exist in Node.js.
@@ -195,6 +196,7 @@ export { useMediaUpload } from "./features/media/index";
 export { SessionProvider, useSession } from "./react/contexts/SessionContext";
 // ThemeProvider — exported above alongside the registry-aware variant.
 export { useUrlTable } from "./react/hooks/useUrlTable";
+export { useTabParam } from "./react/hooks/useTabParam";
 export { useBulkSelection } from "./react/hooks/useBulkSelection";
 export { useEntityDelete } from "./react/hooks/useEntityDelete";
 // Client-safe constants, UI primitives, and views
@@ -264,6 +266,14 @@ export { AdminSidebar } from "./features/admin/components/AdminSidebar";
 export { AdminDashboardView, AdminAnalyticsView, AdminPageViewsReportView, AdminPrizeDrawsView, AdminCarouselView, AdminSublistingCategoriesView, AdminFulfillmentView, DataTable, DataListingView, useAdminListingData, toRecordArray, toStringValue, toRelativeDate } from "./features/admin/index";
 // S-ADMIN-7 — permission catalog data, shared by AdminEmployeeEditorView and the read-only /admin/permissions page.
 export { PERMISSION_GROUPS, PERMISSION_DOMAINS, getPermissionsForDomain, formatPermLabel } from "./features/auth/permissions/constants";
+/*
+ * The permissions CATALOGUE renders these, and it became a client-graph module
+ * in W8 C2 when it moved from its own page into a tab on /admin/roles. Its
+ * previous comment — "Details/Summary aren't re-exported from client.ts" — was
+ * accurate and is now the reason the bare-entry import would be a Turbopack
+ * leak (Root Cause #6).
+ */
+export { Details, Summary } from "./ui/components/Details";
 export { ADMIN_ENDPOINTS } from "./constants/index";
 export { SELLER_ENDPOINTS } from "./constants/index";
 // P-16 — Tour system (driver.js-backed onboarding walkthrough).
@@ -493,6 +503,8 @@ 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";
 export { AdminActionIndexView } from "./features/admin/components/AdminActionIndexView";
 export { SellerSupportView } from "./features/seller/components/SellerSupportView";

package/dist/features/account/components/UserBidsView.js

@@ -31,7 +31,12 @@ export function UserBidsView() {
     const config = {
         portal: "user",
         title: "My Bids",
-        searchPlaceholder: "Search by auction title…",
+        search: {
+            placeholder: "Search by auction title…",
+            // `/api/user/bids` filters in memory: `(b.productTitle ?? "").includes(q)`.
+            // The bid document carries no other text.
+            fields: ["productTitle"],
+        },
         emptyLabel: "You haven't placed any bids yet.",
         filterKeys: ["status"],
         defaultSort: sortBy("bidDate", "DESC"),

package/dist/features/account/components/UserOrdersView.js

@@ -48,7 +48,14 @@ export function UserOrdersView({ onOrderClick }) {
     const config = {
         portal: "user",
         title: "My Orders",
-        searchPlaceholder: "Search by order id…",
+        search: {
+            placeholder: "Search by order id…",
+            // `/api/user/orders` filters in memory on `o.id` and nothing else — not
+            // the product titles the rows display, which is what a buyer would try
+            // first. Saying "order id" is the honest promise until the route can
+            // match more.
+            fields: ["id"],
+        },
         emptyLabel: "You haven't placed any orders yet.",
         filterKeys: ["status", "orderType"],
         defaultSort: sortBy("createdAt", "DESC"),

package/dist/features/account/components/UserReturnsView.js

@@ -21,7 +21,12 @@ export function UserReturnsView({ onOrderClick }) {
     const config = {
         portal: "user",
         title: "Returns & Refunds",
-        searchPlaceholder: "Search by order id…",
+        search: {
+            placeholder: "Search by order id…",
+            // Same route as /user/orders, scoped to returned statuses — so the same
+            // single in-memory match on `o.id`.
+            fields: ["id"],
+        },
         emptyLabel: "You have no return or refund requests.",
         filterKeys: [],
         defaultSort: sortBy("updatedAt", "DESC"),

package/dist/features/admin/components/AdminAdsView.js

@@ -1,24 +1,41 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { normalizeError } from "../../../errors/normalize";
 import { useApiMutation, sieveFilter, SIEVE_OP, sortBy } from "@mohasinac/appkit/client";
 import React from "react";
 import { useQuery, useQueryClient } from "@tanstack/react-query";
-import { Alert, Button, Checkbox, Div, Input, Label, PaginatedSelect, Row, Select, Stack, Text, TextLink } from "../../../ui";
+import { Alert, Button, Div, Input, Label, PaginatedSelect, Row, Select, Stack, Text, TextLink } from "../../../ui";
 import { apiClient } from "../../../http";
 import { ADMIN_ENDPOINTS } from "../../../constants/api-endpoints";
+import { adsConfigSchema } from "../schemas/admin-ops-forms";
+import { SectionForm, useSectionFormNav, buildSectionsFromSchema, visibleValues, } from "../../shell";
+import { useFormShellState, FormShellContext } from "../../../ui/forms";
+import { FormErrorSummary } from "../../../ui/forms/FormErrorSummary";
 import { DataListingView } from "./DataListingView";
 const __P = {
     p3: "p-[var(--appkit-space-3)]",
 };
-function AdsSettingsPanel({ adsenseClientId, setAdsenseClientId, thirdPartyScriptUrl, setThirdPartyScriptUrl, consentRequired, setConsentRequired, serverCredentialIssues, localCredentialIssues, credentialStatus, providerCredentialsMasked, settingsMutation, hasPendingCredentialInput, currentConsentRequired, settingsMessage, onSave, }) {
-    return (_jsxs(Stack, { border: "default", className: __P.p3, gap: "3", rounded: "lg", children: [_jsx(Text, { size: "sm", weight: "semibold", children: "Provider and publish settings" }), _jsx(Text, { className: "text-[var(--appkit-color-text-muted)]", size: "xs", children: "Save provider credentials here before publishing AdSense or third-party inventory." }), serverCredentialIssues.length > 0 ? (_jsx(Alert, { variant: "warning", title: "Provider credentials need attention", children: serverCredentialIssues.join("; ") })) : null, _jsxs(Div, { layout: "grid", gap: "3", className: "grid-cols-1 md:grid-cols-2", children: [_jsx(Input, { label: "AdSense client id", value: adsenseClientId, onChange: (event) => setAdsenseClientId(event.target.value), placeholder: providerCredentialsMasked?.adsenseClientId || "ca-pub-XXXXXXXXXX" }), _jsx(Input, { label: "Third-party script URL", value: thirdPartyScriptUrl, onChange: (event) => setThirdPartyScriptUrl(event.target.value), placeholder: providerCredentialsMasked?.thirdPartyScriptUrl || "https://..." })] }), _jsxs(Text, { className: "text-[var(--appkit-color-text-muted)]", size: "xs", children: ["Stored credentials: AdSense ", credentialStatus?.hasAdsenseClientId ? "configured" : "missing", " \u00B7 Third-party ", credentialStatus?.hasThirdPartyScriptUrl ? "configured" : "missing"] }), _jsxs(Row, { align: "center", justify: "between", gap: "3", children: [_jsxs(Label, { layout: "flex", gap: "md", size: "sm", children: [_jsx(Checkbox, { bare: true, checked: consentRequired, onChange: (event) => setConsentRequired(event.target.checked) }), "Require consent globally for ad rendering"] }), _jsx(Button, { size: "sm", variant: "outline", disabled: settingsMutation.isPending || localCredentialIssues.length > 0 || (!hasPendingCredentialInput && consentRequired === Boolean(currentConsentRequired)), onClick: onSave, children: settingsMutation.isPending ? "Saving..." : "Save settings" })] }), localCredentialIssues.length > 0 ? (_jsx(Alert, { variant: "error", title: "Fix settings before saving", children: localCredentialIssues.join("; ") })) : null, settingsMessage ? (_jsx(Alert, { variant: settingsMessage.toLowerCase().includes("failed") ? "error" : "success", title: "Settings", children: settingsMessage })) : null] }));
+function AdsSettingsPanel({ draft, onChange, serverCredentialIssues, credentialStatus, providerCredentialsMasked, settingsMutation, settingsMessage, onSave, }) {
+    const sections = React.useMemo(() => buildSectionsFromSchema(adsConfigSchema, {
+        renderers: {
+            adsenseClientId: ({ values, onChange: set, errors }) => (_jsx(Input, { label: "AdSense client id", value: values.adsenseClientId ?? "", onChange: (event) => set({ adsenseClientId: event.target.value }), placeholder: providerCredentialsMasked?.adsenseClientId || "ca-pub-XXXXXXXXXX", helperText: "Leave blank to keep the stored value.", error: errors.adsenseClientId })),
+            thirdPartyScriptUrl: ({ values, onChange: set, errors }) => (_jsx(Input, { label: "Third-party script URL", type: "url", value: values.thirdPartyScriptUrl ?? "", onChange: (event) => set({ thirdPartyScriptUrl: event.target.value }), placeholder: providerCredentialsMasked?.thirdPartyScriptUrl || "https://...", helperText: "Must be https. Leave blank to keep the stored value.", error: errors.thirdPartyScriptUrl })),
+        },
+    }), [providerCredentialsMasked]);
+    const nav = useSectionFormNav(sections, draft, { scope: "admin:ads-settings" });
+    const form = useFormShellState(adsConfigSchema, {
+        sections: nav.sectionMeta,
+        onGoToSection: nav.goToSection,
+        fieldToSectionIndex: nav.fieldToSectionIndex,
+    });
+    return (_jsxs(Stack, { border: "default", className: __P.p3, gap: "3", rounded: "lg", children: [_jsx(Text, { size: "sm", weight: "semibold", children: "Provider and publish settings" }), _jsx(Text, { className: "text-[var(--appkit-color-text-muted)]", size: "xs", children: "Save provider credentials here before publishing AdSense or third-party inventory." }), serverCredentialIssues.length > 0 ? (_jsx(Alert, { variant: "warning", title: "Provider credentials need attention", children: serverCredentialIssues.join("; ") })) : null, _jsxs(FormShellContext.Provider, { value: form.shellCtx, children: [_jsx(FormErrorSummary, {}), _jsx(SectionForm, { sections: sections, values: draft, onChange: (partial) => onChange({ ...draft, ...partial }), onSubmit: onSave, onValidationChange: () => form.validate(draft), schema: adsConfigSchema, openIds: nav.openIds, onOpenChange: nav.setOpenIds, submitLabel: "Save settings", isLoading: settingsMutation.isPending })] }), _jsxs(Text, { className: "text-[var(--appkit-color-text-muted)]", size: "xs", children: ["Stored credentials: AdSense ", credentialStatus?.hasAdsenseClientId ? "configured" : "missing", " \u00B7 Third-party ", credentialStatus?.hasThirdPartyScriptUrl ? "configured" : "missing"] }), settingsMessage ? (_jsx(Alert, { variant: settingsMessage.toLowerCase().includes("failed") ? "error" : "success", title: "Settings", children: settingsMessage })) : null] }));
 }
 export function AdminAdsView({ endpoint = ADMIN_ENDPOINTS.ADS, labels = {}, createHref = "/admin/ads/new", renderEditLink, }) {
     const queryClient = useQueryClient();
-    const [consentRequired, setConsentRequired] = React.useState(false);
-    const [adsenseClientId, setAdsenseClientId] = React.useState("");
-    const [thirdPartyScriptUrl, setThirdPartyScriptUrl] = React.useState("");
+    const [draft, setDraft] = React.useState({
+        consentRequired: false,
+        adsenseClientId: "",
+        thirdPartyScriptUrl: "",
+    });
     const [settingsMessage, setSettingsMessage] = React.useState(null);
     // Lightweight metadata-only fetch (placements, consent, credential status) —
     // decoupled from the paginated listing query DataListingView owns internally.
@@ -39,7 +56,9 @@ export function AdminAdsView({ endpoint = ADMIN_ENDPOINTS.ADS, labels = {}, crea
     React.useEffect(() => {
         if (!metaQuery.data)
             return;
-        setConsentRequired(Boolean(metaQuery.data.consentRequired));
+        // Only the consent switch is seeded from the server: both credentials come
+        // back masked, so an input pre-filled with bullets would submit bullets.
+        setDraft((d) => ({ ...d, consentRequired: Boolean(metaQuery.data?.consentRequired) }));
     }, [metaQuery.data]);
     const settingsMutation = useApiMutation({
         mutationFn: async (payload) => {
@@ -47,8 +66,7 @@ export function AdminAdsView({ endpoint = ADMIN_ENDPOINTS.ADS, labels = {}, crea
         },
         onSuccess: async () => {
             setSettingsMessage("Ad settings saved.");
-            setAdsenseClientId("");
-            setThirdPartyScriptUrl("");
+            setDraft((d) => ({ ...d, adsenseClientId: "", thirdPartyScriptUrl: "" }));
             await queryClient.invalidateQueries({ queryKey: ["admin-ads-meta"] });
         },
         onError: (error) => {
@@ -58,33 +76,17 @@ export function AdminAdsView({ endpoint = ADMIN_ENDPOINTS.ADS, labels = {}, crea
     const placements = metaQuery.data?.placements ?? [];
     const credentialStatus = metaQuery.data?.providerCredentialStatus;
     const serverCredentialIssues = credentialStatus?.issues ?? [];
-    const localCredentialIssues = React.useMemo(() => {
-        const issues = [];
-        if (adsenseClientId.trim() && !/^ca-pub-[0-9]{10,20}$/.test(adsenseClientId.trim())) {
-            issues.push("AdSense client id must match format ca-pub-XXXXXXXXXX");
-        }
-        if (thirdPartyScriptUrl.trim()) {
-            try {
-                const parsed = new URL(thirdPartyScriptUrl.trim());
-                if (parsed.protocol !== "https:") {
-                    issues.push("Third-party script URL must be https");
-                }
-            }
-            catch (_err) {
-                void normalizeError(_err);
-                issues.push("Third-party script URL must be a valid URL");
-            }
-        }
-        return issues;
-    }, [adsenseClientId, thirdPartyScriptUrl]);
-    const hasPendingCredentialInput = adsenseClientId.trim().length > 0 || thirdPartyScriptUrl.trim().length > 0;
     const saveSettings = () => {
         setSettingsMessage(null);
+        const v = visibleValues(adsConfigSchema, draft);
         const payload = {
-            consentRequired,
+            consentRequired: v.consentRequired,
             providerCredentials: {
-                adsenseClientId: adsenseClientId.trim() || undefined,
-                thirdPartyScriptUrl: thirdPartyScriptUrl.trim() || undefined,
+                // `undefined` on a blank field is what leaves the STORED credential
+                // alone - the route never sends the real value back, so an empty input
+                // means "unchanged", not "clear it".
+                adsenseClientId: v.adsenseClientId?.trim() || undefined,
+                thirdPartyScriptUrl: v.thirdPartyScriptUrl?.trim() || undefined,
             },
         };
         settingsMutation.mutate(payload);
@@ -156,7 +158,7 @@ export function AdminAdsView({ endpoint = ADMIN_ENDPOINTS.ADS, labels = {}, crea
                         { label: "AdSense", value: "adsense" },
                         { label: "Third Party", value: "thirdParty" },
                     ], onChange: (e) => setPendingFilters((p) => ({ ...p, provider: e.target.value === "all" ? "" : e.target.value })) }), _jsx(Label, { size: "sm", color: "muted", children: "Placement" }), _jsx(PaginatedSelect, { value: pendingFilters.placement || undefined, onChange: (v) => setPendingFilters((p) => ({ ...p, placement: v ?? "" })), options: placements.map((item) => ({ value: item.id, label: item.label })) })] })),
-        renderAboveContent: () => (_jsxs(Stack, { gap: "md", className: __P.p3, children: [metaQuery.error ? (_jsx(Alert, { variant: "error", title: "Could not load ads", children: metaQuery.error instanceof Error ? metaQuery.error.message : "Unknown error" })) : null, _jsx(AdsSettingsPanel, { adsenseClientId: adsenseClientId, setAdsenseClientId: setAdsenseClientId, thirdPartyScriptUrl: thirdPartyScriptUrl, setThirdPartyScriptUrl: setThirdPartyScriptUrl, consentRequired: consentRequired, setConsentRequired: setConsentRequired, serverCredentialIssues: serverCredentialIssues, localCredentialIssues: localCredentialIssues, credentialStatus: credentialStatus, providerCredentialsMasked: metaQuery.data?.providerCredentialsMasked, settingsMutation: settingsMutation, hasPendingCredentialInput: hasPendingCredentialInput, currentConsentRequired: Boolean(metaQuery.data?.consentRequired), settingsMessage: settingsMessage, onSave: saveSettings })] })),
+        renderAboveContent: () => (_jsxs(Stack, { gap: "md", className: __P.p3, children: [metaQuery.error ? (_jsx(Alert, { variant: "error", title: "Could not load ads", children: metaQuery.error instanceof Error ? metaQuery.error.message : "Unknown error" })) : null, _jsx(AdsSettingsPanel, { draft: draft, onChange: setDraft, serverCredentialIssues: serverCredentialIssues, credentialStatus: credentialStatus, providerCredentialsMasked: metaQuery.data?.providerCredentialsMasked, settingsMutation: settingsMutation, settingsMessage: settingsMessage, onSave: saveSettings })] })),
     };
     return _jsx(DataListingView, { config: config });
 }

package/dist/features/admin/components/AdminAuditLogView.js

@@ -50,7 +50,18 @@ export function AdminAuditLogView({ children, ...props }) {
     const config = {
         portal: "admin",
         title: "Audit Log",
-        searchPlaceholder: "Search by actor uid",
+        search: {
+            placeholder: "Search by actor uid (exact)",
+            /*
+             * `/api/admin/audit-log` builds `actorUid==${q}` — an EQUALITY, stated in
+             * that route's own comment because `@=` is prefix-only against Firestore
+             * anyway. A partial uid matches nothing, so the box commits on Enter and
+             * says "exact" rather than letting someone type half a uid and watch an
+             * empty list.
+             */
+            mode: "exact",
+            fields: ["actorUid"],
+        },
         emptyLabel: "No audit log entries found",
         filterKeys: ["action", "actorUid"],
         defaultSort: sortBy("createdAt", "DESC"),

package/dist/features/admin/components/AdminBundlesView.js

@@ -62,7 +62,11 @@ export function AdminBundlesView({ editHrefTemplate, newHref }) {
     const config = {
         portal: "admin",
         title: "Bundles",
-        searchPlaceholder: "Search bundles by name or slug…",
+        search: {
+            placeholder: "Search bundles by name or slug…",
+            // `/api/admin/bundles` filters in memory on `b.name` and `b.slug`.
+            fields: ["name", "slug"],
+        },
         emptyLabel: BUNDLE_COPY.adminList.empty,
         filterKeys: ["isActive", "bundleStockStatus"],
         defaultSort: sortBy("name", "ASC"),

package/dist/features/admin/components/AdminCarouselEditorView.js

@@ -4,12 +4,14 @@ import { useApiMutation } from "@mohasinac/appkit/client";
 import React from "react";
 import { useQuery } from "@tanstack/react-query";
 import { z } from "zod";
-import { Alert, Button, ConfirmDeleteModal, Div, Form, FormActions, Heading, Input, Row, Select, Slider, Stack, StackedViewShell, Text, Toggle } from "../../../ui";
+import { Alert, Button, ConfirmDeleteModal, Div, Heading, Input, Row, Select, Slider, Stack, StackedViewShell, Text, Toggle } from "../../../ui";
 import { FieldInput, FormErrorSummary } from "../../../ui/forms";
 import { apiClient } from "../../../http";
 import { ADMIN_ENDPOINTS } from "../../../constants/api-endpoints";
 import { ROUTES } from "../../../next/routing/route-map";
 import { ACTIONS } from "../../../_internal/shared/actions/action-registry";
+import { SectionForm, useSectionFormNav, } from "../../shell";
+import { useFormShellState, FormShellContext } from "../../../ui/forms";
 const __P = {
     p3: "p-[var(--appkit-space-3)]",
 };
@@ -21,7 +23,6 @@ const carouselSlideSchema = z.object({
     order: z.number().int().min(0),
     active: z.boolean(),
 }).passthrough();
-// ── helpers ─────────────────────────────────────────────────────────────────
 function makeCard(zone = 1) {
     return {
         id: `card-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`,
@@ -207,16 +208,83 @@ export function AdminCarouselEditorView({ slideId, onSaved, onDeleted, onCancel,
         onError: (err) => setErrorMsg(err?.message ?? "Failed to delete."),
     });
     const occupiedZones = cards.map((c) => c.zone);
+    /*
+     * Hand-written sections around the JSX that was already here, which is the
+     * `AdminCategoryEditorView` pattern. Deriving is not available: `background`
+     * is a discriminated union with its own editor, `cards[].buttons[]` is two
+     * levels of array, and neither has a `FieldKind`.
+     *
+     * `fields` is what makes the error summary's jump links and the per-section
+     * error badge work — it maps a Zod path back to the panel holding that
+     * control.
+     */
+    const sections = React.useMemo(() => [
+        {
+            id: "info",
+            label: "Slide info",
+            required: true,
+            fields: ["title", "active", "order", "settings"],
+            render: () => (_jsxs(Stack, { gap: "md", children: [_jsx(FieldInput, { name: "title", label: "Title", value: title, onChange: (v) => setTitle(v), required: true, placeholder: "e.g. Hot Wheels RLC Exclusives" }), _jsx(Toggle, { label: "Active (visible on homepage)", checked: active, onChange: setActive }), _jsx(Input, { label: "Display order", type: "number", value: order, onChange: (e) => setOrder(e.target.value), min: 0, placeholder: "1" }), _jsx(Select, { label: "Slide height", value: height, onChange: (e) => setHeight(e.target.value), options: HEIGHT_OPTIONS }), _jsx(Input, { label: "Autoplay delay (ms)", type: "number", value: autoplayDelayMs, onChange: (e) => setAutoplayDelayMs(e.target.value), min: 1000, max: 15000, placeholder: "4000", helperText: "How long this slide shows before auto-advancing. Default: 4000 ms." })] })),
+        },
+        {
+            id: "background",
+            label: "Background",
+            fields: ["background"],
+            render: () => _jsx(BackgroundEditor, { value: background, onChange: setBackground }),
+        },
+        {
+            id: "overlay",
+            label: "Overlay text",
+            fields: ["overlay"],
+            render: () => (_jsxs(Stack, { gap: "md", children: [_jsx(Text, { size: "sm", color: "muted", children: "Centred text layered over the background. Leave blank to use cards only." }), _jsx(Input, { label: "Heading", value: overlayTitle, onChange: (e) => setOverlayTitle(e.target.value), placeholder: "India's #1 Collectibles Marketplace" }), _jsx(Input, { label: "Subtitle", value: overlaySubtitle, onChange: (e) => setOverlaySubtitle(e.target.value), placeholder: "Pokemon TCG - Hot Wheels - Beyblade X" }), _jsx(Input, { label: "Description", value: overlayDesc, onChange: (e) => setOverlayDesc(e.target.value), placeholder: "One sentence description..." }), _jsxs(Stack, { className: `${__P.p3}`, gap: "sm", rounded: "lg", border: "default", children: [_jsx(Text, { size: "sm", weight: "medium", children: "CTA button" }), _jsx(Input, { label: "Button text", value: overlayBtnText, onChange: (e) => setOverlayBtnText(e.target.value), placeholder: "Shop Now" }), _jsx(Input, { label: "Button link", value: overlayBtnLink, onChange: (e) => setOverlayBtnLink(e.target.value), placeholder: String(ROUTES.PUBLIC.PRODUCTS) }), _jsx(Select, { label: "Variant", value: overlayBtnVariant, onChange: (e) => setOverlayBtnVariant(e.target.value), options: VARIANT_OPTIONS.filter((v) => ["primary", "secondary", "outline"].includes(v.value)) }), _jsx(Toggle, { label: "Open in new tab", checked: overlayBtnNewTab, onChange: setOverlayBtnNewTab })] })] })),
+        },
+        {
+            id: "cards",
+            label: "Cards (0-2)",
+            fields: ["cards"],
+            render: () => (_jsxs(Stack, { gap: "md", children: [_jsxs(Row, { className: CLS_ROW_BETWEEN, children: [_jsx(Text, { size: "sm", color: "muted", children: "A slide holds at most two cards." }), cards.length < 2 && (_jsx(Button, { type: "button", variant: "outline", size: "sm", onClick: handleAddCard, children: "+ Add card" }))] }), cards.length === 0 && (_jsx(Text, { size: "sm", color: "faint", children: "No cards - the overlay text covers the whole slide." })), cards.map((card, i) => (_jsx(CardEditor, { card: card, index: i, otherZones: occupiedZones.filter((z) => z !== card.zone), onChange: (updated) => setCards(cards.map((c, ci) => (ci === i ? updated : c))), onRemove: () => setCards(cards.filter((_, ci) => ci !== i)) }, card.id)))] })),
+        },
+    ], [
+        title, active, order, height, autoplayDelayMs, background, cards, occupiedZones,
+        overlayTitle, overlaySubtitle, overlayDesc, overlayBtnText, overlayBtnLink,
+        overlayBtnVariant, overlayBtnNewTab, handleAddCard,
+    ]);
+    /**
+     * The values the nav and the error summary key on. Not a draft the form
+     * writes through - see the `onChange` note at the SectionForm below.
+     */
+    const draftForNav = React.useMemo(() => ({ title, active, order, cards }), [title, active, order, cards]);
+    const nav = useSectionFormNav(sections, draftForNav, { scope: "admin:carousel-editor" });
+    const form = useFormShellState(carouselSlideSchema, {
+        sections: nav.sectionMeta,
+        onGoToSection: nav.goToSection,
+        fieldToSectionIndex: nav.fieldToSectionIndex,
+    });
     return (_jsx(StackedViewShell, { portal: "admin", ...rest, title: isEdit ? "Edit Carousel Slide" : "New Carousel Slide", sections: [
             errorMsg ? _jsx(Alert, { variant: "error", children: errorMsg }, "err") : null,
             successMsg ? _jsx(Alert, { variant: "success", children: successMsg }, "ok") : null,
-            _jsx(Form, { schema: carouselSlideSchema, onSubmit: (e) => e.preventDefault(), spacing: "lg", children: ({ setFieldError, clearErrors }) => (_jsxs(_Fragment, { children: [_jsxs(Div, { className: CLS_PANEL, children: [_jsx(Heading, { level: 3, className: CLS_SECTION_HEADING, children: "Slide info" }), _jsx(FieldInput, { name: "title", label: "Title", value: title, onChange: (v) => setTitle(v), required: true, placeholder: "e.g. Hot Wheels RLC Exclusives" }), _jsx(Toggle, { label: "Active (visible on homepage)", checked: active, onChange: setActive }), _jsx(Input, { label: "Display order", type: "number", value: order, onChange: (e) => setOrder(e.target.value), min: 0, placeholder: "1" }), _jsx(Select, { label: "Slide height", value: height, onChange: (e) => setHeight(e.target.value), options: HEIGHT_OPTIONS }), _jsx(Input, { label: "Autoplay delay (ms)", type: "number", value: autoplayDelayMs, onChange: (e) => setAutoplayDelayMs(e.target.value), min: 1000, max: 15000, placeholder: "4000", helperText: "How long this slide shows before auto-advancing. Default: 4000 ms." })] }), _jsxs(Div, { className: CLS_PANEL, children: [_jsx(Heading, { level: 3, className: CLS_SECTION_HEADING, children: "Background" }), _jsx(BackgroundEditor, { value: background, onChange: setBackground })] }), _jsxs(Div, { className: CLS_PANEL, children: [_jsx(Heading, { level: 3, className: CLS_SECTION_HEADING, children: "Overlay text (optional)" }), _jsx(Text, { size: "sm", color: "muted", children: "Centred text layered over the background. Leave blank to use cards only." }), _jsx(Input, { label: "Heading", value: overlayTitle, onChange: (e) => setOverlayTitle(e.target.value), placeholder: "India's #1 Collectibles Marketplace" }), _jsx(Input, { label: "Subtitle", value: overlaySubtitle, onChange: (e) => setOverlaySubtitle(e.target.value), placeholder: "Pok\u00E9mon TCG \u00B7 Hot Wheels \u00B7 Beyblade X" }), _jsx(Input, { label: "Description", value: overlayDesc, onChange: (e) => setOverlayDesc(e.target.value), placeholder: "One sentence description..." }), _jsxs(Stack, { className: `${__P.p3}`, gap: "sm", rounded: "lg", border: "default", children: [_jsx(Text, { size: "sm", weight: "medium", children: "CTA button" }), _jsx(Input, { label: "Button text", value: overlayBtnText, onChange: (e) => setOverlayBtnText(e.target.value), placeholder: "Shop Now" }), _jsx(Input, { label: "Button link", value: overlayBtnLink, onChange: (e) => setOverlayBtnLink(e.target.value), placeholder: String(ROUTES.PUBLIC.PRODUCTS) }), _jsx(Select, { label: "Variant", value: overlayBtnVariant, onChange: (e) => setOverlayBtnVariant(e.target.value), options: VARIANT_OPTIONS.filter((v) => ["primary", "secondary", "outline"].includes(v.value)) }), _jsx(Toggle, { label: "Open in new tab", checked: overlayBtnNewTab, onChange: setOverlayBtnNewTab })] })] }), _jsxs(Div, { className: CLS_PANEL, children: [_jsxs(Row, { className: CLS_ROW_BETWEEN, children: [_jsx(Heading, { level: 3, className: CLS_SECTION_HEADING, children: "Cards (0\u20132)" }), cards.length < 2 && (_jsx(Button, { type: "button", variant: "outline", size: "sm", onClick: handleAddCard, children: "+ Add card" }))] }), cards.length === 0 && (_jsx(Text, { size: "sm", color: "faint", children: "No cards \u2014 the overlay text covers the whole slide." })), cards.map((card, i) => (_jsx(CardEditor, { card: card, index: i, otherZones: occupiedZones.filter((z) => z !== card.zone), onChange: (updated) => setCards(cards.map((c, ci) => (ci === i ? updated : c))), onRemove: () => setCards(cards.filter((_, ci) => ci !== i)) }, card.id)))] }), _jsx(FormErrorSummary, {}), _jsxs(FormActions, { children: [_jsx(Button, { type: "submit", isLoading: saveMutation.isPending, disabled: !title || saveMutation.isPending, onClick: () => {
-                                        clearErrors();
-                                        if (!title.trim()) {
-                                            setFieldError("title", "Title is required");
-                                            return;
-                                        }
-                                        saveMutation.mutate();
-                                    }, children: isEdit ? "Save changes" : "Create slide" }), onCancel && (_jsx(Button, { type: "button", variant: "outline", onClick: onCancel, children: "Cancel" })), isEdit && (_jsxs(_Fragment, { children: [_jsx(Button, { type: "button", variant: "danger", isLoading: deleteMutation.isPending, onClick: () => setDeleteConfirmOpen(true), children: ACTIONS.ADMIN["delete-carousel"].label }), _jsx(ConfirmDeleteModal, { isOpen: deleteConfirmOpen, onClose: () => setDeleteConfirmOpen(false), onConfirm: () => { setDeleteConfirmOpen(false); deleteMutation.mutate(); }, title: ACTIONS.ADMIN["delete-carousel"].confirmation.title, message: ACTIONS.ADMIN["delete-carousel"].confirmation.body, isDeleting: deleteMutation.isPending })] }))] })] })) }, "slide-form"),
+            _jsxs(FormShellContext.Provider, { value: form.shellCtx, children: [_jsx(FormErrorSummary, {}), _jsx(SectionForm, { sections: sections, values: draftForNav, 
+                        /*
+                         * The sections render from this component's own state, so
+                         * `onChange` has nothing to route: every control already writes
+                         * through its own setter, and the values object exists to give the
+                         * error summary and the per-section badge a field map. Rebuilding
+                         * eighteen scalars into one draft object would be a second source
+                         * of truth for the same values.
+                         */
+                        onChange: () => undefined, onSubmit: () => {
+                            form.clearErrors();
+                            if (!title.trim()) {
+                                form.setFieldError("title", "Title is required");
+                                return;
+                            }
+                            saveMutation.mutate();
+                        }, schema: carouselSlideSchema, openIds: nav.openIds, onOpenChange: nav.setOpenIds, submitLabel: isEdit ? "Save changes" : "Create slide", cancelLabel: "Cancel", onCancel: onCancel, isLoading: saveMutation.isPending, destructiveAction: isEdit
+                            ? {
+                                label: ACTIONS.ADMIN["delete-carousel"].label,
+                                onClick: () => setDeleteConfirmOpen(true),
+                                disabled: deleteMutation.isPending,
+                            }
+                            : undefined }), isEdit && (_jsx(ConfirmDeleteModal, { isOpen: deleteConfirmOpen, onClose: () => setDeleteConfirmOpen(false), onConfirm: () => { setDeleteConfirmOpen(false); deleteMutation.mutate(); }, title: ACTIONS.ADMIN["delete-carousel"].confirmation.title, message: ACTIONS.ADMIN["delete-carousel"].confirmation.body, isDeleting: deleteMutation.isPending }))] }, "slide-form"),
         ] }));
 }

package/dist/features/admin/components/AdminFaqsView.js

@@ -33,7 +33,16 @@ export function AdminFaqsView({ children, onBulkArchive, onBulkDelete, ...props
     const config = useMemo(() => ({
         portal: "admin",
         title: "FAQs",
-        searchPlaceholder: "Search questions, categories, or tokens",
+        search: {
+            placeholder: "Search questions, answers, categories or tags",
+            /*
+             * `buildFaqSearchTxt` indexes the question, the category, every tag AND
+             * the answer body, all prefix-expanded. The old placeholder said
+             * "tokens" — the name of the implementation — and omitted the answer,
+             * which is the largest thing it searches.
+             */
+            fields: ["question", "answer", "category", "tags"],
+        },
         emptyLabel: "No FAQs found",
         filterKeys: ["isActive"],
         defaultSort: sortBy("priority", "ASC"),

package/dist/features/admin/components/AdminNotificationsView.js

@@ -81,7 +81,13 @@ export function AdminNotificationsView({ children, ...props }) {
         // Title search is not expressible here — `title` is not in the repository's
         // SIEVE_FIELDS and Sieve→Firestore cannot OR across two fields. The route
         // treats `q` as an exact userId lookup, so the placeholder says exactly that.
-        searchPlaceholder: "Search by user ID",
+        search: {
+            placeholder: "Search by user ID (exact)",
+            // `/api/admin/notifications` builds `userId==${q}`. An equality, so a
+            // partial id matches nothing and the box commits on Enter.
+            mode: "exact",
+            fields: ["userId"],
+        },
         emptyLabel: "No notifications found",
         filterKeys: ["type", "readState"],
         defaultSort: sortBy("createdAt", "DESC"),