@mohasinac/appkit 4.30.19 → 4.31.0

package/dist/features/search/action-index/settings-entries.js

@@ -0,0 +1,268 @@
+/*
+ * WHY: "It should be searchable — if I search for the maintenance toggle it
+ *      should find it." A nav-only index cannot: the maintenance toggle is
+ *      not a page, it is a control on tab ⓵ of an 1800-line settings screen,
+ *      and the only thing naming it is a `<Toggle label="Maintenance mode">`
+ *      inside that screen's JSX.
+ * WHAT: Track B — the declarative map of settings and toggles, each with the
+ *       `?tab=`/`#anchor` that reaches the control itself.
+ *
+ * ## Why this is declared rather than derived
+ *
+ * Track A (`FieldUiMeta.index`) covers every schema-driven form for free. It
+ * yields **nothing** here, because `AdminSiteSettingsView` is not schema-driven
+ * — it is ~160 controls bound to individual `useState` calls, and it is on
+ * W8's tabbing list precisely because of that. Waiting for the derivation
+ * would mean the headline request — find the maintenance toggle — ships last.
+ *
+ * So this is a hand-written map, and it is the ONE in this plan that is
+ * defensible: there is no existing array it duplicates. `audit-nav-metadata`'s
+ * sibling check keeps its `tab` values inside `SiteSettingsTabId`, so the half
+ * that CAN drift is the half that is guarded.
+ *
+ * ## An anchor is CLAIMED, not assumed
+ *
+ * A deep link to `#setting-maintenance-mode` that matches no `id=` in the DOM
+ * scrolls nowhere and reads as the search having missed — so an entry opts in
+ * with `anchored: true`, and `audit-action-index` checks that the id exists.
+ * Everything else deep-links to its TAB, which is a smaller promise ("this
+ * lives on the Fees tab") and one the page can keep.
+ *
+ * The first run of that audit reported thirteen dead anchors, because this
+ * file declared twenty-two entries while the view carried nine ids. That is
+ * the rule doing its job on the commit that introduced it.
+ *
+ * EXPORTS: SITE_SETTINGS_ENTRIES, deriveSettingsEntries
+ *
+ * @tag domain:search
+ * @tag layer:shared
+ * @tag pattern:registry
+ * @tag access:isomorphic
+ * @tag consumers:action index
+ * @tag sideEffects:none
+ */
+/**
+ * The controls worth finding.
+ *
+ * Deliberately not all ~160: a search result list is only useful while it is
+ * short, and "Hero title" is not something anyone hunts for — they open the
+ * About tab and see it. What is here is what someone arrives ALREADY looking
+ * for, usually in a hurry, and usually not knowing which tab it is filed under.
+ */
+export const SITE_SETTINGS_ENTRIES = [
+    {
+        slug: "maintenance-mode",
+        anchored: true,
+        label: "Maintenance mode",
+        description: "Take the site offline for visitors and show a message instead.",
+        keywords: ["offline", "down for maintenance", "close the site", "under construction"],
+        tab: "branding",
+        kind: "toggle",
+    },
+    {
+        slug: "maintenance-message",
+        label: "Maintenance message",
+        description: "What visitors see while the site is in maintenance mode.",
+        keywords: ["offline message", "downtime notice"],
+        tab: "branding",
+        kind: "setting",
+    },
+    {
+        slug: "announcement-bar",
+        anchored: true,
+        label: "Announcement bar",
+        description: "Show a message across the top of every page.",
+        keywords: ["banner", "notice", "top bar", "sale banner"],
+        tab: "announcement",
+        kind: "toggle",
+    },
+    {
+        slug: "robots-noindex",
+        anchored: true,
+        label: "Hide from search engines",
+        description: "Stop Google indexing the site. Use carefully — recovery is slow.",
+        keywords: ["noindex", "google", "seo", "deindex", "hide from google"],
+        tab: "seo",
+        kind: "toggle",
+    },
+    {
+        slug: "razorpay-enabled",
+        anchored: true,
+        label: "Online payments (Razorpay)",
+        description: "Accept cards and UPI through Razorpay. Off by default; manual payment is the default.",
+        keywords: ["card payments", "razorpay", "online payment", "gateway", "upi"],
+        tab: "fees",
+        kind: "toggle",
+    },
+    {
+        slug: "manual-payment-enabled",
+        anchored: true,
+        label: "Manual UPI / bank transfer",
+        description: "Let buyers pay by transfer and upload proof for review.",
+        keywords: ["upi", "bank transfer", "manual payment", "proof"],
+        tab: "fees",
+        kind: "toggle",
+    },
+    {
+        slug: "cod-enabled",
+        anchored: true,
+        label: "Cash on delivery",
+        description: "Let buyers pay when the parcel arrives.",
+        keywords: ["cod", "cash on delivery", "pay on delivery"],
+        tab: "fees",
+        kind: "toggle",
+    },
+    {
+        slug: "platform-commission",
+        label: "Platform commission",
+        description: "What the platform takes from each sale, and its cap.",
+        keywords: ["commission", "our cut", "platform fee", "take rate"],
+        tab: "fees",
+        kind: "setting",
+    },
+    {
+        slug: "google-analytics",
+        label: "Google Analytics",
+        description: "The GA4 measurement id used for site traffic.",
+        keywords: ["ga4", "analytics id", "tracking", "measurement id", "google"],
+        tab: "integrations",
+        kind: "setting",
+    },
+    {
+        slug: "facebook-pixel",
+        label: "Facebook Pixel",
+        description: "The Meta Pixel id used for ad attribution.",
+        keywords: ["meta pixel", "facebook", "ads tracking", "conversion"],
+        tab: "integrations",
+        kind: "setting",
+    },
+    {
+        slug: "free-shipping-threshold",
+        label: "Free shipping threshold",
+        description: "The order value above which delivery is free.",
+        keywords: ["free delivery", "shipping over", "minimum for free shipping"],
+        tab: "shipping",
+        kind: "setting",
+    },
+    {
+        slug: "bid-increment",
+        label: "Minimum bid increment",
+        description: "The smallest amount a new bid must beat the current one by.",
+        keywords: ["bidding step", "increment", "auction minimum"],
+        tab: "auction",
+        kind: "setting",
+    },
+    {
+        slug: "anti-sniping",
+        label: "Anti-sniping extension",
+        description: "Extend an auction when a bid lands in its final seconds.",
+        keywords: ["sniping", "last second bid", "extend auction", "going going gone"],
+        tab: "auction",
+        kind: "setting",
+    },
+    {
+        slug: "email-notifications",
+        anchored: true,
+        label: "Email notifications",
+        description: "Whether the platform sends email at all.",
+        keywords: ["email", "resend", "transactional email", "stop emails"],
+        tab: "notifications",
+        kind: "toggle",
+    },
+    {
+        slug: "whatsapp-notifications",
+        anchored: true,
+        label: "WhatsApp notifications",
+        description: "Send order updates over WhatsApp.",
+        keywords: ["whatsapp", "order updates", "meta"],
+        tab: "notifications",
+        kind: "toggle",
+    },
+    {
+        slug: "daily-digest",
+        anchored: true,
+        label: "Daily status digest",
+        description: "A once-a-day operations summary to the admin inbox.",
+        keywords: ["digest", "daily email", "summary", "ops report"],
+        tab: "notifications",
+        kind: "toggle",
+    },
+    {
+        slug: "emi-threshold",
+        label: "EMI eligibility threshold",
+        description: "The order value above which instalments are offered.",
+        keywords: ["instalments", "installments", "emi minimum", "pay monthly"],
+        tab: "emi",
+        kind: "setting",
+    },
+    {
+        slug: "gst-rates",
+        label: "GST rates and HSN defaults",
+        description: "The tax rates applied to listings, and the fallback HSN code.",
+        keywords: ["tax", "gst", "hsn", "vat"],
+        tab: "gst",
+        kind: "setting",
+    },
+    {
+        slug: "gstin",
+        label: "GSTIN and registered business",
+        description: "The registration number and legal address printed on invoices.",
+        keywords: ["gstin", "tax number", "registered address", "legal name"],
+        tab: "legal",
+        kind: "setting",
+    },
+    {
+        slug: "enabled-listing-types",
+        label: "Enabled listing types",
+        description: "Which kinds of listing sellers may create.",
+        keywords: ["auctions off", "disable pre-orders", "listing types", "turn off"],
+        tab: "listings",
+        kind: "toggle",
+    },
+    {
+        slug: "watermark",
+        label: "Photo watermark",
+        description: "The mark stamped onto uploaded product photos.",
+        keywords: ["watermark", "logo on photos", "protect images"],
+        tab: "watermark",
+        kind: "setting",
+    },
+    {
+        slug: "upload-limits",
+        label: "Upload and listing limits",
+        description: "Maximum file size, image count and per-account listing caps.",
+        keywords: ["max upload", "file size", "how many listings", "quota", "limit"],
+        tab: "limits",
+        kind: "setting",
+    },
+];
+/**
+ * The settings entries, as index entries.
+ *
+ * `deepLink` carries the whole query-and-hash — `?tab=fees#setting-cod-enabled`
+ * — rather than just the tab, because landing on the right tab and leaving the
+ * reader to find the control among forty others is most of the way to not
+ * having searched at all.
+ */
+export function deriveSettingsEntries(settingsHref, requiredPermission = "settings:read") {
+    return SITE_SETTINGS_ENTRIES.map((entry) => ({
+        id: `admin:${entry.kind}:${entry.slug}`,
+        kind: entry.kind,
+        portal: "admin",
+        label: entry.label,
+        description: entry.description,
+        keywords: entry.keywords,
+        href: settingsHref,
+        deepLink: entry.anchored
+            ? `?tab=${entry.tab}#setting-${entry.slug}`
+            : `?tab=${entry.tab}`,
+        sectionPath: "Admin › System › Site Settings",
+        requiredPermission,
+        /*
+         * Above nav entries. Someone searching "maintenance" wants the toggle, not
+         * the settings page it lives on — and the page will also match, on its own
+         * description, so without this the container outranks the thing.
+         */
+        weight: 20,
+    }));
+}

package/dist/features/search/action-index/types.d.ts

@@ -0,0 +1,81 @@
+import type { NavPortal } from "../../../_internal/shared/features/layout/types";
+/**
+ * What kind of thing an entry is.
+ *
+ * The distinction that matters is `nav`/`page` (somewhere you go) versus
+ * `setting`/`toggle`/`action` (something you change or do) — a search for
+ * "maintenance mode" wants the toggle, not the settings page it lives on, and
+ * only the kind tells them apart.
+ */
+export type ActionIndexKind = "nav" | "page" | "section" | "setting" | "toggle" | "action";
+export interface ActionIndexEntry {
+    /** `{portal}:{kind}:{slug}` — also the overlay's React key. */
+    id: string;
+    kind: ActionIndexKind;
+    /** `public` for anything outside the three dashboards. */
+    portal: NavPortal | "public";
+    label: string;
+    description?: string;
+    keywords?: string[];
+    href: string;
+    /**
+     * The `?tab=`/`#anchor` that reaches the exact control, when the href alone
+     * only reaches the page it lives on. This is what makes a search for
+     * "maintenance" land on the toggle rather than on Site Settings.
+     */
+    deepLink?: string;
+    /** Breadcrumb for the result row — "Admin › System › Site Settings". */
+    sectionPath?: string;
+    requiredRole?: string;
+    requiredPermission?: string;
+    requiresTester?: boolean;
+    /** A lucide icon NAME. See the header for why this is not a component. */
+    iconName?: string;
+    /** Higher sorts first among equal-scoring matches. Default 0. */
+    weight?: number;
+}
+/** What an admin may change about a built-in entry. */
+export interface ActionIndexOverride {
+    enabled?: boolean;
+    label?: string;
+    description?: string;
+    keywords?: string[];
+    weight?: number;
+    group?: string;
+    order?: number;
+}
+/**
+ * The stored control document, `actionIndex/global`.
+ *
+ * Deliberately NOT folded into `siteSettings`: that document is read publicly
+ * and edge-cached, and this one is projected by role.
+ */
+export interface ActionIndexControl {
+    entries: Record<string, ActionIndexOverride>;
+    /** Admin-authored entries, appended after the static base. */
+    custom: ActionIndexEntry[];
+}
+export declare const ACTION_INDEX_COLLECTION: "actionIndex";
+export declare const ACTION_INDEX_DOC_ID: "global";
+/**
+ * Apply an admin's overrides to the static base.
+ *
+ * Order is load-bearing: override, then DROP disabled, then append `custom`.
+ * Dropping last would let an admin disable an entry and have their own
+ * replacement for it disappear too, since a custom entry may legitimately
+ * reuse a built-in id to supersede it.
+ */
+export declare function mergeActionIndex(base: readonly ActionIndexEntry[], control: ActionIndexControl | undefined): ActionIndexEntry[];
+/**
+ * Drop every entry the viewer may not reach.
+ *
+ * 🛑 Filtered SERVER-side, never in the browser. An entry the client is not
+ * allowed to act on is an entry it must not receive: the label alone is a site
+ * map of the admin panel, which is D8's whole point.
+ */
+export declare function projectActionIndexForViewer(entries: readonly ActionIndexEntry[], viewer: {
+    role?: string;
+    permissions?: readonly string[];
+    isTester?: boolean;
+    isAdmin?: boolean;
+}): ActionIndexEntry[];

package/dist/features/search/action-index/types.js

@@ -0,0 +1,102 @@
+/*
+ * WHY: "Searching 'maintenance' should land me on the maintenance toggle" —
+ *      and `Search.tsx` has had a **complete** quick-links path the whole
+ *      time. Both modes are built: the inline filter already matches
+ *      `link.keywords` as well as the label, the overlay renders a labelled
+ *      band, the keyboard index arithmetic accounts for it, and
+ *      `constants/search.ts` even holds the band's label string.
+ *
+ *      `grep "quickLinks="` returns **zero**. The one real mount passes nine
+ *      props and not that one. A finished feature with no input.
+ *
+ *      The reason nothing passed it is that there was nothing to pass: no
+ *      single list of what a user can DO existed. Nav lived in three arrays,
+ *      quick actions in a registry each page ignored, and settings nowhere at
+ *      all.
+ * WHAT: `ActionIndexEntry` — one shape for every navigable or actionable
+ *       surface, and the type the search, the command palette and (D7) the
+ *       admin control plane all read.
+ *
+ * ## Why `iconName` is a string
+ *
+ * The index is serialised — into a Firestore control document, through an API
+ * route, into React Query's cache. A `LucideIcon` component reference survives
+ * none of those. The renderer resolves the name; the index carries data.
+ *
+ * ## Why `href` and every permission field are CODE-owned
+ *
+ * D7 lets an admin rename, re-describe, retag, reorder and hide an entry —
+ * that is content. It does not let them repoint a built-in entry's route or
+ * relax its permission, because those are routing and access control. An
+ * admin-authored entry supplies its own `href`, and that one is validated at
+ * SAVE time (see the write route): an audit that runs on CI would let a bad
+ * href reach the sidebar and 404 until the next run.
+ *
+ * EXPORTS: ActionIndexEntry, ActionIndexKind, ActionIndexControl,
+ *          type ActionIndexOverride
+ *
+ * @tag domain:search
+ * @tag layer:shared
+ * @tag pattern:registry
+ * @tag access:isomorphic
+ * @tag consumers:Search,CommandPalette,action-index admin screen
+ * @tag sideEffects:none
+ */
+export const ACTION_INDEX_COLLECTION = "actionIndex";
+export const ACTION_INDEX_DOC_ID = "global";
+/**
+ * Apply an admin's overrides to the static base.
+ *
+ * Order is load-bearing: override, then DROP disabled, then append `custom`.
+ * Dropping last would let an admin disable an entry and have their own
+ * replacement for it disappear too, since a custom entry may legitimately
+ * reuse a built-in id to supersede it.
+ */
+export function mergeActionIndex(base, control) {
+    if (!control)
+        return [...base];
+    const merged = [];
+    for (const entry of base) {
+        const override = control.entries?.[entry.id];
+        if (override?.enabled === false)
+            continue;
+        merged.push(override
+            ? {
+                ...entry,
+                ...(override.label !== undefined ? { label: override.label } : {}),
+                ...(override.description !== undefined
+                    ? { description: override.description }
+                    : {}),
+                ...(override.keywords !== undefined ? { keywords: override.keywords } : {}),
+                ...(override.weight !== undefined ? { weight: override.weight } : {}),
+            }
+            : entry);
+    }
+    return merged.concat(control.custom ?? []);
+}
+/**
+ * Drop every entry the viewer may not reach.
+ *
+ * 🛑 Filtered SERVER-side, never in the browser. An entry the client is not
+ * allowed to act on is an entry it must not receive: the label alone is a site
+ * map of the admin panel, which is D8's whole point.
+ */
+export function projectActionIndexForViewer(entries, viewer) {
+    return entries.filter((entry) => {
+        if (entry.requiresTester && !viewer.isTester && !viewer.isAdmin)
+            return false;
+        if (entry.requiredRole && entry.requiredRole !== viewer.role && !viewer.isAdmin) {
+            return false;
+        }
+        /*
+         * An admin bypasses permission checks by design — `isAdminUser` short-
+         * circuits every one of them elsewhere, and an index that disagreed would
+         * hide screens the admin can plainly open from the sidebar.
+         */
+        if (entry.requiredPermission && !viewer.isAdmin) {
+            if (!viewer.permissions?.includes(entry.requiredPermission))
+                return false;
+        }
+        return true;
+    });
+}

package/dist/features/search/action-index/validate-entry.d.ts

@@ -0,0 +1,34 @@
+import type { ActionIndexEntry } from "./types";
+export interface ActionIndexValidationIssue {
+    field: "href" | "deepLink" | "id";
+    message: string;
+}
+export interface ActionIndexValidationContext {
+    /**
+     * Every route the app actually serves, as paths without a locale prefix.
+     * Built from the route map by the caller — a runtime cannot walk `src/app`.
+     */
+    knownRoutes: ReadonlySet<string>;
+    /** Anchors a page is known to render, keyed by route. */
+    knownAnchors?: Readonly<Record<string, ReadonlySet<string>>>;
+    /** Tab ids a route accepts, keyed by route. Absent = `?tab=` not checked. */
+    knownTabs?: Readonly<Record<string, ReadonlySet<string>>>;
+    /** Ids already in use — a duplicate silently shadows an existing entry. */
+    existingIds?: ReadonlySet<string>;
+}
+/**
+ * Normalise an href to the form `knownRoutes` is keyed by: no origin, no
+ * locale segment, no query, no hash, no trailing slash.
+ *
+ * The locale strip matters — an admin pasting the URL out of their address bar
+ * gets `/en/admin/orders`, and rejecting that would be technically correct and
+ * useless.
+ */
+export declare function normaliseRoute(href: string): string;
+/**
+ * The three checks, at save time.
+ *
+ * Returns every issue rather than the first, so an admin fixing a bad entry
+ * does not discover its second problem only after fixing the first.
+ */
+export declare function validateActionIndexEntry(entry: Pick<ActionIndexEntry, "id" | "href" | "deepLink">, ctx: ActionIndexValidationContext): ActionIndexValidationIssue[];

package/dist/features/search/action-index/validate-entry.js

@@ -0,0 +1,114 @@
+/*
+ * WHY: `audit-action-index` runs on CI. An admin-authored entry (D7) is written
+ *      at RUNTIME — so a bad href reaches the sidebar and the search, 404s for
+ *      everyone, and stays there until the next audit run notices. The master
+ *      plan's own words: without save-time validation, "admins can create
+ *      entries" is a self-service 404 generator.
+ * WHAT: The same three checks the audit performs, as a function the write route
+ *       calls before persisting, returning a 400 instead of a broken link.
+ *
+ * ## Why the route cannot just run the audit
+ *
+ * The audit reads FILES — it greps `settings-entries.ts` and the settings view
+ * for `id=` literals. A route has neither at runtime. So the checkable facts
+ * have to be passed in: the set of real routes, and the set of known anchors.
+ * That is the whole reason this is a function taking a context rather than a
+ * copy of the audit.
+ *
+ * ## What it deliberately does NOT check
+ *
+ * Whether the target page renders anything useful. A route that exists and an
+ * anchor that exists are provable from data the server has; "is this a sensible
+ * place to send someone" is not, and a validator that pretends otherwise would
+ * reject legitimate entries and teach admins to work around it.
+ *
+ * EXPORTS: validateActionIndexEntry, type ActionIndexValidationContext,
+ *          type ActionIndexValidationIssue
+ *
+ * @tag domain:search
+ * @tag layer:shared
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:/api/admin/action-index,audit-action-index
+ * @tag sideEffects:none
+ */
+/**
+ * Normalise an href to the form `knownRoutes` is keyed by: no origin, no
+ * locale segment, no query, no hash, no trailing slash.
+ *
+ * The locale strip matters — an admin pasting the URL out of their address bar
+ * gets `/en/admin/orders`, and rejecting that would be technically correct and
+ * useless.
+ */
+export function normaliseRoute(href) {
+    return (href
+        .replace(/^https?:\/\/[^/]+/, "")
+        .replace(/^\/[a-z]{2}(-[A-Z]{2})?(?=\/)/, "")
+        .replace(/[?#].*$/, "")
+        .replace(/\/+$/, "") || "/");
+}
+/** A dynamic route matches by shape: `/admin/orders/[id]` accepts any id. */
+function matchesKnownRoute(route, knownRoutes) {
+    if (knownRoutes.has(route))
+        return true;
+    const parts = route.split("/");
+    for (const known of knownRoutes) {
+        const knownParts = known.split("/");
+        if (knownParts.length !== parts.length)
+            continue;
+        const ok = knownParts.every((segment, i) => segment === parts[i] || /^\[.+\]$/.test(segment));
+        if (ok)
+            return true;
+    }
+    return false;
+}
+/**
+ * The three checks, at save time.
+ *
+ * Returns every issue rather than the first, so an admin fixing a bad entry
+ * does not discover its second problem only after fixing the first.
+ */
+export function validateActionIndexEntry(entry, ctx) {
+    const issues = [];
+    if (ctx.existingIds?.has(entry.id)) {
+        issues.push({
+            field: "id",
+            message: `"${entry.id}" is already used. A duplicate id silently shadows the existing entry, and an override written for one would land on the other.`,
+        });
+    }
+    const route = normaliseRoute(entry.href);
+    if (!entry.href.trim()) {
+        issues.push({ field: "href", message: "Enter the page this should open." });
+    }
+    else if (!route.startsWith("/")) {
+        issues.push({
+            field: "href",
+            message: "Start the link with / — an index entry points at a page on this site.",
+        });
+    }
+    else if (!matchesKnownRoute(route, ctx.knownRoutes)) {
+        issues.push({
+            field: "href",
+            message: `No page is served at ${route}. Check the path — a link that 404s is worse than no entry at all.`,
+        });
+    }
+    if (entry.deepLink) {
+        const tab = entry.deepLink.match(/[?&]tab=([^&#]+)/)?.[1];
+        const anchor = entry.deepLink.match(/#(.+)$/)?.[1];
+        const tabsForRoute = ctx.knownTabs?.[route];
+        if (tab && tabsForRoute && !tabsForRoute.has(tab)) {
+            issues.push({
+                field: "deepLink",
+                message: `${route} has no "${tab}" tab. The page would open on its default tab, which reads as the search having missed rather than as a broken link.`,
+            });
+        }
+        const anchorsForRoute = ctx.knownAnchors?.[route];
+        if (anchor && anchorsForRoute && !anchorsForRoute.has(anchor)) {
+            issues.push({
+                field: "deepLink",
+                message: `${route} renders nothing with id="${anchor}". The link would scroll nowhere.`,
+            });
+        }
+    }
+    return issues;
+}

package/dist/features/search/hooks/useNavSuggestions.d.ts

@@ -8,8 +8,12 @@ export interface NavSuggestionRecord {
 /**
  * W1-19 — wired to `/api/search/suggestions` 2026-05-23. Fetches up to 20
  * matches (5 per resource type) and surfaces them as typeahead rows.
+ *
+ * `minChars` is trailing and defaulted because this hook is part of appkit's
+ * public API (`appkit/src/index.ts`); existing 2-argument callers keep working
+ * and inherit the gate.
  */
-export declare function useNavSuggestions(query: string, selectedType?: string, debounceMs?: number): {
+export declare function useNavSuggestions(query: string, selectedType?: string, debounceMs?: number, minChars?: number): {
     suggestions: NavSuggestionRecord[];
     isLoading: boolean;
 };

package/dist/features/search/hooks/useNavSuggestions.js

@@ -20,11 +20,28 @@ const SUGGESTION_TYPE_PARAM_MAP = {
     blog: "blog",
     events: "event",
 };
+/**
+ * The shortest query that reaches the network.
+ *
+ * 🛑 Entity suggestions cost a real Firestore round trip — the route reads
+ * products, categories, blog posts and events. Below this length the result is
+ * dominated by whatever happens to sort first, so the request buys noise at the
+ * price of two round trips per typed word, on every page, for every visitor.
+ *
+ * This gate is for the ENTITY band only. Action/nav suggestions match an
+ * in-memory index and should stay available from the first character — typing
+ * "s" and seeing "Settings" is genuinely useful and costs nothing.
+ */
+const DEFAULT_MIN_CHARS = 3;
 /**
  * W1-19 — wired to `/api/search/suggestions` 2026-05-23. Fetches up to 20
  * matches (5 per resource type) and surfaces them as typeahead rows.
+ *
+ * `minChars` is trailing and defaulted because this hook is part of appkit's
+ * public API (`appkit/src/index.ts`); existing 2-argument callers keep working
+ * and inherit the gate.
  */
-export function useNavSuggestions(query, selectedType, debounceMs = 250) {
+export function useNavSuggestions(query, selectedType, debounceMs = 250, minChars = DEFAULT_MIN_CHARS) {
     const [suggestions, setSuggestions] = useState([]);
     const [isLoading, setIsLoading] = useState(false);
     const timerRef = useRef(null);
@@ -35,7 +52,10 @@ export function useNavSuggestions(query, selectedType, debounceMs = 250) {
         if (abortRef.current)
             abortRef.current.abort();
         const trimmed = query.trim();
-        if (!trimmed) {
+        // Below the gate is a deliberate no-op, not a failure: clear the rows and
+        // report not-loading, so the dropdown shows its action band rather than a
+        // spinner that never resolves.
+        if (trimmed.length < minChars) {
             setSuggestions([]);
             setIsLoading(false);
             return;
@@ -76,6 +96,6 @@ export function useNavSuggestions(query, selectedType, debounceMs = 250) {
             if (abortRef.current)
                 abortRef.current.abort();
         };
-    }, [query, selectedType, debounceMs]);
+    }, [query, selectedType, debounceMs, minChars]);
     return { suggestions, isLoading };
 }

package/dist/features/search/repository/search.repository.js

@@ -1,3 +1,5 @@
+import { SIEVE_OP, sieveFilter } from "../../../utils/sieve-builder";
+import { PRODUCT_FIELDS } from "../../../constants/field-names";
 /**
  * SearchRepository
  *
@@ -25,7 +27,7 @@ export class SearchRepository {
             filterParts.push(`condition==${query.condition}`);
         // SB1-G Phase 4 — canonical listingType discriminator.
         if (query.listingType) {
-            filterParts.push(`listingType==${query.listingType}`);
+            filterParts.push(sieveFilter(PRODUCT_FIELDS.LISTING_TYPE, SIEVE_OP.EQ, query.listingType));
         }
         if (query.inStock === true)
             filterParts.push("availableQuantity>0");