@mohasinac/appkit 4.53.0 → 4.53.2

package/dist/features/search/components/Search.js

@@ -10,6 +10,16 @@ const CLS_ICON_ROW = "w-4 h-4 flex-shrink-0 text-[var(--appkit-color-text-muted)
 const CLS_TRUNCATE = "font-medium truncate";
 import { Button, Div, Input, Li, Row, Select, Span, Stack, Text, Ul } from "../../../ui/index.js";
 import { useNavSuggestions } from "../hooks/useNavSuggestions.js";
+import { useSiteSearch } from "../hooks/useSiteSearch.js";
+/**
+ * The dropdown renders no group headings, so it needs no labels — but
+ * `useSiteSearch` requires one because `/search` does.
+ *
+ * 🛑 Declared at MODULE scope, not inline. It is a `useMemo` dependency
+ * inside the hook, and an inline arrow is a new identity on every render,
+ * which would re-run the scan on every keystroke of an unchanged query.
+ */
+const identityLabel = (typeKey) => typeKey;
 const DEFAULT_TYPE_ICONS = {
     page: "📄",
     category: "🗂️",
@@ -28,7 +38,7 @@ function SuggestionItem({ suggestion, itemIndex, activeIndex, onSelect, onHover,
     const isActive = activeIndex === itemIndex;
     return (_jsx(Li, { children: _jsxs(Button, { type: "button", variant: "ghost", onClick: () => onSelect(suggestion), onMouseEnter: () => onHover(itemIndex), className: `w-full flex items-center gap-[var(--appkit-space-3)] px-[var(--appkit-space-4)] py-[var(--appkit-space-3)] text-left transition-colors border-b border-[var(--appkit-color-border)] last:border-b-0 ${isActive ? "bg-[var(--appkit-color-surface)] bg-[var(--appkit-color-surface-elevated)]" : CLS_HOVER_ROW}`, children: [_jsx(Span, { size: "sm", children: typeIcons[suggestion.type] }), _jsxs(Div, { className: "flex-1 min-w-0", children: [_jsx(Text, { size: "sm", className: CLS_TRUNCATE, children: suggestion.title }), suggestion.subtitle && (_jsx(Text, { variant: "secondary", size: "xs", className: "truncate", children: suggestion.subtitle }))] }), _jsx(Span, { size: "xs", className: `${typeBadges[suggestion.type]}`, rounded: "full", padding: "pill-xs", children: suggestion.type })] }) }));
 }
-export function Search({ isOpen, onClose, onSearch, onOpen, value, onChange, placeholder, deferred = true, debounceMs = 300, onClear, className, router, quickLinks = [], labels, suggestionTypeIcons, suggestionTypeBadges, resourceTypes, defaultResourceType = "products", storageKey = "letitrip_search_type", }) {
+export function Search({ isOpen, onClose, onSearch, onOpen, value, onChange, placeholder, deferred = true, debounceMs = 300, onClear, className, router, quickLinks = [], labels, suggestionTypeIcons, suggestionTypeBadges, resourceTypes, defaultResourceType = "products", storageKey = "letitrip_search_type", searchIndexEnabled, }) {
     const isInlineMode = value !== undefined;
     const [query, setQuery] = useState(isInlineMode ? value : "");
     const [activeIndex, setActiveIndex] = useState(-1);
@@ -37,7 +47,33 @@ export function Search({ isOpen, onClose, onSearch, onOpen, value, onChange, pla
     const inputRef = useRef(null);
     const debounceRef = useRef(null);
     const inlineBlurRef = useRef(null);
-    const { suggestions, isLoading: suggestionsLoading } = useNavSuggestions(query, selectedType);
+    /*
+     * 🛑 BOTH hooks are called unconditionally — React's rules leave no choice,
+     * and it costs nothing here because each one is self-gating.
+     *
+     * `useSiteSearch` is gated on `active`: it issues no request until the user
+     * focuses or types, and then exactly one, for the whole page session.
+     * `useNavSuggestions` is gated on its own 3-character minimum AND on
+     * `remoteQuery` below, which is blank whenever the index is answering — so
+     * the fallback path makes no network request at all in the normal case.
+     */
+    const [searchIntent, setSearchIntent] = useState(false);
+    const local = useSiteSearch(query, {
+        active: searchIntent,
+        indexEnabled: searchIndexEnabled,
+        label: identityLabel,
+    });
+    /*
+     * The index is authoritative the moment it is `ready`. `loading` must NOT
+     * fall through to the remote path: that would fire the very round trips
+     * this replaces, for the one second before the local answer arrives, on
+     * every first keystroke.
+     */
+    const useLocal = local.status === "ready";
+    const remoteQuery = useLocal || local.status === "loading" ? "" : query;
+    const { suggestions: remoteSuggestions, isLoading: remoteLoading } = useNavSuggestions(remoteQuery, selectedType);
+    const suggestions = useLocal ? local.suggestions : remoteSuggestions;
+    const suggestionsLoading = useLocal ? false : local.status === "loading" || remoteLoading;
     const typeIcons = { ...DEFAULT_TYPE_ICONS, ...suggestionTypeIcons };
     const typeBadges = { ...DEFAULT_TYPE_BADGES, ...suggestionTypeBadges };
     // Restore persisted type from localStorage after mount
@@ -90,6 +126,7 @@ export function Search({ isOpen, onClose, onSearch, onOpen, value, onChange, pla
         setActiveIndex(-1);
     }, [isOpen, isInlineMode, query, suggestions.length]);
     const handleInlineChange = (nextValue) => {
+        setSearchIntent(true);
         setQuery(nextValue);
         if (!deferred) {
             if (debounceRef.current)
@@ -209,6 +246,10 @@ export function Search({ isOpen, onClose, onSearch, onOpen, value, onChange, pla
             }
         };
         return (_jsxs(Row, { className: `relative ${className ?? ""}`, gap: "sm", children: [_jsxs(Row, { className: "relative flex-1 min-w-0", children: [_jsx("svg", { className: "absolute left-3 w-4 h-4 text-zinc-400 pointer-events-none", "aria-hidden": "true", fill: "none", stroke: "currentColor", viewBox: "0 0 24 24", children: _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", strokeWidth: 2, d: SVG_PATH_SEARCH }) }), _jsx(Input, { ref: inputRef, bare: true, type: "search", value: query, onChange: (event) => handleInlineChange(event.target.value), onKeyDown: handleInlineKeyDown, onFocus: () => {
+                                // Focus is the earliest honest signal of intent, and it buys
+                                // the ~900 ms the artifact takes to land before the first
+                                // keystroke needs an answer.
+                                setSearchIntent(true);
                                 if (inlineBlurRef.current)
                                     clearTimeout(inlineBlurRef.current);
                                 setIsInlineOpen(true);
@@ -292,7 +333,10 @@ export function Search({ isOpen, onClose, onSearch, onOpen, value, onChange, pla
     };
     if (!isOpen)
         return null;
-    return (_jsx(Div, { border: "bottom-subtle", className: "animate-[fadeIn_150ms_ease-out]", surface: "default", shadow: "md", children: _jsxs(Div, { className: "container mx-auto md:py-[1rem] relative", padding: "inline", children: [_jsxs(Row, { gap: "sm", className: "md:gap-[0.75rem]", children: [_jsx(Div, { className: "flex-1 relative min-w-0", children: _jsx(Input, { ref: inputRef, bare: true, type: "search", placeholder: placeholder ?? labels.placeholder, value: query, onChange: (event) => setQuery(event.target.value), onKeyDown: handleOverlayKeyDown, className: "w-full rounded-lg border bg-[var(--appkit-color-surface)] text-zinc-900 placeholder:text-zinc-400 focus:border-primary focus:ring-2 focus:ring-primary/20 border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface)] dark:text-white dark:placeholder:text-slate-500" }) }), resourceTypes && resourceTypes.length > 0 && (_jsx(Select, { options: resourceTypes, value: selectedType, onValueChange: handleTypeChange, "aria-label": labels.resourceTypeLabel ?? "Search in", wrapperClassName: "flex-shrink-0 max-w-[92px] sm:max-w-[150px]" })), _jsxs(Button, { gap: "md", onClick: handleOverlaySearch, variant: "primary", size: "md", className: "hidden sm:", children: [_jsx("svg", { className: "w-5 h-5 shrink-0", fill: "none", stroke: "currentColor", viewBox: "0 0 24 24", children: _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", strokeWidth: 2, d: SVG_PATH_SEARCH }) }), labels.title] }), _jsx(Button, { rounded: "xl", variant: "ghost", onClick: () => onClose?.(), className: "p-[var(--appkit-space-2-5)] md:p-[var(--appkit-space-3)] transition-colors text-[var(--appkit-color-text-muted)] hover:text-zinc-700 text-[var(--appkit-color-text-muted)] hover:bg-surface-hover hover:text-[var(--appkit-color-text-muted)] flex-shrink-0", "aria-label": labels.closeAriaLabel, children: _jsx("svg", { className: "w-6 h-6 md:w-7 md:h-7 shrink-0", fill: "none", stroke: "currentColor", viewBox: "0 0 24 24", children: _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", strokeWidth: 2, d: "M6 18L18 6M6 6l12 12" }) }) })] }), (filteredSiteLinks.length > 0 || query) && (_jsxs(Stack, { className: "absolute top-full left-0 right-0 z-50 pt-[0.5rem] pb-[1rem]", padding: "x-md", gap: "sm", children: [filteredSiteLinks.length > 0 && !suggestionsLoading && (_jsxs(Div, { className: `${__O.hidden}`, rounded: "xl", shadow: "lg", surface: "default", border: "default", children: [_jsx(Div, { border: "default", className: "border-b", paddingY: "y-xs", paddingX: "x-md", children: _jsx(Text, { variant: "secondary", size: "xs", className: "uppercase tracking-wider", weight: "semibold", children: labels.quickLinks }) }), _jsx(Ul, { children: filteredSiteLinks.map((link) => {
+    return (_jsx(Div, { border: "bottom-subtle", className: "animate-[fadeIn_150ms_ease-out]", surface: "default", shadow: "md", children: _jsxs(Div, { className: "container mx-auto md:py-[1rem] relative", padding: "inline", children: [_jsxs(Row, { gap: "sm", className: "md:gap-[0.75rem]", children: [_jsx(Div, { className: "flex-1 relative min-w-0", children: _jsx(Input, { ref: inputRef, bare: true, type: "search", placeholder: placeholder ?? labels.placeholder, value: query, onFocus: () => setSearchIntent(true), onChange: (event) => {
+                                    setSearchIntent(true);
+                                    setQuery(event.target.value);
+                                }, onKeyDown: handleOverlayKeyDown, className: "w-full rounded-lg border bg-[var(--appkit-color-surface)] text-zinc-900 placeholder:text-zinc-400 focus:border-primary focus:ring-2 focus:ring-primary/20 border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface)] dark:text-white dark:placeholder:text-slate-500" }) }), resourceTypes && resourceTypes.length > 0 && (_jsx(Select, { options: resourceTypes, value: selectedType, onValueChange: handleTypeChange, "aria-label": labels.resourceTypeLabel ?? "Search in", wrapperClassName: "flex-shrink-0 max-w-[92px] sm:max-w-[150px]" })), _jsxs(Button, { gap: "md", onClick: handleOverlaySearch, variant: "primary", size: "md", className: "hidden sm:", children: [_jsx("svg", { className: "w-5 h-5 shrink-0", fill: "none", stroke: "currentColor", viewBox: "0 0 24 24", children: _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", strokeWidth: 2, d: SVG_PATH_SEARCH }) }), labels.title] }), _jsx(Button, { rounded: "xl", variant: "ghost", onClick: () => onClose?.(), className: "p-[var(--appkit-space-2-5)] md:p-[var(--appkit-space-3)] transition-colors text-[var(--appkit-color-text-muted)] hover:bg-surface-hover hover:text-[var(--appkit-color-text)] flex-shrink-0", "aria-label": labels.closeAriaLabel, children: _jsx("svg", { className: "w-6 h-6 md:w-7 md:h-7 shrink-0", fill: "none", stroke: "currentColor", viewBox: "0 0 24 24", children: _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", strokeWidth: 2, d: "M6 18L18 6M6 6l12 12" }) }) })] }), (filteredSiteLinks.length > 0 || query) && (_jsxs(Stack, { className: "absolute top-full left-0 right-0 z-50 pt-[0.5rem] pb-[1rem]", padding: "x-md", gap: "sm", children: [filteredSiteLinks.length > 0 && !suggestionsLoading && (_jsxs(Div, { className: `${__O.hidden}`, rounded: "xl", shadow: "lg", surface: "default", border: "default", children: [_jsx(Div, { border: "default", className: "border-b", paddingY: "y-xs", paddingX: "x-md", children: _jsx(Text, { variant: "secondary", size: "xs", className: "uppercase tracking-wider", weight: "semibold", children: labels.quickLinks }) }), _jsx(Ul, { children: filteredSiteLinks.map((link) => {
                                         const Icon = link.icon;
                                         const itemIndex = quickLinkItems.findIndex((item) => item.link.href === link.href);
                                         const isActive = activeIndex === itemIndex;

package/dist/features/search/components/SearchFacetRail.d.ts

@@ -0,0 +1,11 @@
+import React from "react";
+import type { FacetCount } from "../../../_internal/shared/search/to-groups";
+export interface SearchFacetRailProps {
+    facets: readonly FacetCount[];
+    /** Currently applied `k:v` pairs. */
+    selected: readonly string[];
+    onToggle: (pair: string) => void;
+    /** Values shown per key before the rest are hidden. */
+    maxPerKey?: number;
+}
+export declare function SearchFacetRail({ facets, selected, onToggle, maxPerKey, }: SearchFacetRailProps): React.JSX.Element | null;

package/dist/features/search/components/SearchFacetRail.js

@@ -0,0 +1,92 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/*
+ * WHY: Refining a 3,700-record local result set is free; refining a Firestore
+ *      one is an aggregation query per facet value plus a composite index per
+ *      shape. This rail only exists because Tier 1 made it cost nothing.
+ * WHAT: Toggleable `k:v` facet chips with live counts over the CURRENT hits.
+ *
+ * ## 🛑 Counts are over the current result set, not the catalogue
+ *
+ * Tick one chip and the others shrink, truthfully, because every number is a
+ * reduce over the hits the query just produced. `BaseRepository.facetCounts`
+ * cannot do this — it counts the collection, one aggregation query per value,
+ * and returns `undefined` on a missing index so the chip renders with no
+ * number at all. A count that can silently vanish is worse than no rail.
+ *
+ * ## 🛑 A chip whose count would be zero is not rendered
+ *
+ * It cannot be: the counts come from the hits, so a value with no hits has no
+ * entry. That is the structural version of Root Cause #72's rule — there, a
+ * hide-when-empty tab survived because its count map returned `undefined`
+ * ("unknown") rather than `0`, so four tabs were unhideable. Here there is no
+ * count map to be incomplete.
+ *
+ * @tag domain:search
+ * @tag layer:feature
+ * @tag pattern:none
+ * @tag access:client
+ * @tag consumers:SearchResultsClient
+ * @tag sideEffects:none
+ */
+import React from "react";
+import { Button, Div, Row, Span, Stack, Text } from "../../../ui/index.js";
+/**
+ * Short code -> heading.
+ *
+ * 🛑 `Partial`, and an unknown code is SKIPPED rather than shown raw. The
+ * codes are two letters to keep the artifact small (`lt:auction` over
+ * `listingType:auction`, ×3,700), which means a new one added on the builder
+ * side would otherwise surface to a visitor as a heading reading "sz". A
+ * facet nobody can name is not a refinement, and dropping it loses nothing
+ * the groups above do not already show.
+ */
+const FACET_KEY_LABEL = {
+    lt: "Type",
+    br: "Brand",
+    cn: "Condition",
+    fr: "Franchise",
+    ct: "Category",
+};
+/** Slug -> words. The artifact stores slugs; nobody wants to read one. */
+function humanise(value) {
+    const spaced = value.replace(/[-_]/g, " ");
+    return spaced.charAt(0).toUpperCase() + spaced.slice(1);
+}
+export function SearchFacetRail({ facets, selected, onToggle, maxPerKey = 6, }) {
+    const selectedSet = React.useMemo(() => new Set(selected), [selected]);
+    const byKey = React.useMemo(() => {
+        const map = new Map();
+        for (const f of facets) {
+            if (!FACET_KEY_LABEL[f.key])
+                continue; // see FACET_KEY_LABEL's 🛑
+            const bucket = map.get(f.key);
+            if (bucket)
+                bucket.push(f);
+            else
+                map.set(f.key, [f]);
+        }
+        return map;
+    }, [facets]);
+    /*
+     * A key offering ONE value is not a refinement — every result already has
+     * it, so ticking it changes nothing and the chip is pure noise. The
+     * exception is a value already selected: hiding the chip you used to narrow
+     * the page would leave no way to un-narrow it.
+     */
+    const keys = [...byKey.keys()].filter((k) => {
+        const values = byKey.get(k) ?? [];
+        return values.length > 1 || values.some((v) => selectedSet.has(`${v.key}:${v.value}`));
+    });
+    if (keys.length === 0)
+        return null;
+    return (_jsx(Stack, { gap: "sm", children: keys.map((key) => {
+            const values = byKey.get(key) ?? [];
+            const shown = values.slice(0, maxPerKey);
+            return (_jsxs(Stack, { gap: "xs", children: [_jsx(Text, { size: "xs", color: "muted", weight: "semibold", transform: "uppercase", children: FACET_KEY_LABEL[key] }), _jsxs(Row, { wrap: true, gap: "xs", children: [shown.map((f) => {
+                                const pair = `${f.key}:${f.value}`;
+                                const isOn = selectedSet.has(pair);
+                                return (_jsxs(Button, { size: "sm", variant: isOn ? "primary" : "outline", "aria-pressed": isOn, onClick: () => onToggle(pair), children: [humanise(f.value), _jsxs(Span, { size: "xs", color: isOn ? "inherit" : "muted", numeric: true, children: [" ", f.count] })] }, pair));
+                            }), values.length > shown.length && (_jsx(Div, { padding: "xs", children: _jsxs(Text, { size: "xs", color: "muted", children: ["+", values.length - shown.length, " more"] }) }))] })] }, key));
+        }) }));
+}

package/dist/features/search/components/SearchResultsClient.d.ts

@@ -0,0 +1,33 @@
+import React from "react";
+import type { SearchEverythingResult } from "../../../_internal/server/features/search/search-everything";
+export interface SearchResultsClientProps {
+    /** The query, resolved server-side from `?q=`. */
+    q: string;
+    /**
+     * The Tier 2 result. Empty (and unread) whenever `indexEnabled` is true —
+     * see the header.
+     */
+    initialResult: SearchEverythingResult;
+    indexEnabled: boolean;
+    /**
+     * Whether a session exists. FALSE for a guest, and that is what makes
+     * "signed out issues zero authenticated requests" verifiable in the
+     * Network panel rather than merely true on the server.
+     */
+    isSignedIn?: boolean;
+    /**
+     * `typeKey` -> heading.
+     *
+     * 🛑 A plain OBJECT, not a `(key: string) => string`. This component is
+     * rendered from a Server Component, and a function prop is not
+     * serialisable across the RSC boundary — it throws at render, not at
+     * compile. Same constraint `HomepageSectionBoundary` documents for its
+     * `sectionId`/`sectionType` strings.
+     *
+     * A key with no entry falls back to the key itself rather than being
+     * dropped: a group headed `scammer` is ugly, a group that silently
+     * disappears is a bug.
+     */
+    labels: Readonly<Record<string, string>>;
+}
+export declare function SearchResultsClient({ q, initialResult, indexEnabled, isSignedIn, labels, }: SearchResultsClientProps): React.JSX.Element;

package/dist/features/search/components/SearchResultsClient.js

@@ -0,0 +1,103 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+/*
+ * WHY: `/search` should answer from the local artifact — every type, mid-word
+ *      matching, exact counts, zero Firestore reads — while still rendering
+ *      something when the artifact is off or unreachable.
+ * WHAT: The client wrapper around `SearchResultsPageView`. Picks the tier,
+ *       owns the facet selection, and renders the rail.
+ *
+ * ## 🛑 The server result is a FALLBACK, not a first paint to be replaced
+ *
+ * `/search/page.tsx` does NOT run the Firestore fan-out when the index is
+ * enabled — it passes an empty envelope and 0 reads. So `initialResult` is
+ * meaningful only in the kill-switch case, and swapping a populated server
+ * result out from under the user is a flicker that cannot happen here.
+ *
+ * That is also why `loading` renders a waiting line rather than the empty
+ * state: with no server result behind it, an empty state would say "nothing
+ * matched" about a query nobody has finished asking (the `GatedPrice`
+ * three-state discipline, one surface over).
+ *
+ * ## 🛑 Facet selection lives in component state, NOT the URL
+ *
+ * `/search` is `noindex` and every result links out to a real indexable
+ * listing page, so a shareable faceted search URL has no SEO value and would
+ * multiply the crawl trap the page is already careful about. It also keeps
+ * `useUrlTable` out of a page that has no pagination — the one thing the
+ * listing views need it for.
+ *
+ * @tag domain:search
+ * @tag layer:feature
+ * @tag pattern:none
+ * @tag access:client
+ * @tag consumers:app/[locale]/search/page.tsx
+ * @tag sideEffects:network
+ */
+import React from "react";
+import { Text } from "../../../ui/index.js";
+import { useSiteSearch } from "../hooks/useSiteSearch.js";
+import { mergeSearchTiers, useScopedSearch } from "../hooks/useScopedSearch.js";
+import { SearchFacetRail } from "./SearchFacetRail.js";
+import { SearchResultsPageView } from "./SearchResultsPageView.js";
+export function SearchResultsClient({ q, initialResult, indexEnabled, isSignedIn = false, labels, }) {
+    const [selectedFacets, setSelectedFacets] = React.useState([]);
+    // Stable across renders — it is a `useMemo` dependency inside the hook.
+    const label = React.useCallback((typeKey) => labels[typeKey] ?? typeKey, [labels]);
+    /*
+     * `active` is unconditionally true here, unlike the header. Arriving on
+     * `/search?q=…` IS the intent — there is no cheaper signal to wait for,
+     * and gating on focus would mean a page whose entire purpose is results
+     * sits idle until somebody clicks the box.
+     */
+    const local = useSiteSearch(q, {
+        active: true,
+        indexEnabled,
+        facets: selectedFacets,
+        label,
+    });
+    const toggleFacet = React.useCallback((pair) => {
+        setSelectedFacets((prev) => prev.includes(pair) ? prev.filter((p) => p !== pair) : [...prev, pair]);
+    }, []);
+    /*
+     * Tier 2. `submittedQuery` is `q` — the URL parameter — so it changes when
+     * the user SUBMITS, not as they type. That is the whole gating story: the
+     * local tier runs per keystroke because it is free, this one runs per
+     * navigation because it is a bounded Firestore fan-out.
+     */
+    const scoped = useScopedSearch({ enabled: isSignedIn, submittedQuery: q });
+    const usingLocal = local.status === "ready" && local.result !== null;
+    const baseResult = usingLocal && local.result ? local.result : initialResult;
+    const result = React.useMemo(() => scoped.groups.length > 0
+        ? { ...baseResult, groups: mergeSearchTiers(baseResult.groups, scoped.groups) }
+        : baseResult, [baseResult, scoped.groups]);
+    /*
+     * 🛑 A dropped facet selection must not silently keep filtering.
+     *
+     * If the index fails after the user has ticked chips, the fallback result
+     * is unfiltered — so the chips would be lit while doing nothing. Clearing
+     * them is the honest state, and it is cheap because the rail is derived
+     * rather than stored.
+     */
+    React.useEffect(() => {
+        if (!usingLocal && selectedFacets.length > 0)
+            setSelectedFacets([]);
+    }, [usingLocal, selectedFacets.length]);
+    const waiting = local.status === "loading" && q.trim().length > 0;
+    return (_jsx(SearchResultsPageView, { result: waiting ? { ...result, groups: [], totalHits: 0 } : result, footnote: usingLocal && local.builtAt
+            ? `Catalogue index updated ${new Date(local.builtAt).toLocaleString()}.`
+            : undefined, renderAboveGroups: () => (_jsxs(_Fragment, { children: [waiting && _jsx(Text, { color: "muted", children: "Searching\u2026" }), usingLocal && (_jsx(SearchFacetRail, { facets: local.facets, selected: selectedFacets, onToggle: toggleFacet })), scoped.status === "failed" && (
+                /*
+                 * Said out loud, for the same reason as the line below it. A
+                 * seller whose draft is missing because the scoped fetch failed
+                 * will read the silence as "that draft does not exist".
+                 */
+                _jsx(Text, { size: "sm", color: "muted", children: "Couldn't search your account \u2014 results below are public listings only." })), local.status === "failed" && (
+                /*
+                 * Said out loud rather than degraded silently. `searchEverything`'s
+                 * own header records that a degraded source "is indistinguishable
+                 * from 'nothing matched'" — and on a page that otherwise rendered
+                 * fine, silence tells someone we have none of what they asked for.
+                 */
+                _jsx(Text, { size: "sm", color: "muted", children: "Showing a reduced set \u2014 the full catalogue index could not be loaded." }))] })) }));
+}

package/dist/features/search/components/SearchResultsPageView.d.ts

@@ -29,5 +29,19 @@ export interface SearchResultsPageViewProps {
     result: SearchEverythingResult;
     /** Rendered above the groups — the consumer owns the input control. */
     renderSearchInput?: () => React.ReactNode;
+    /**
+     * Rendered between the input and the groups. The facet rail lives here.
+     *
+     * A SLOT rather than a `facets` prop, because this component is also
+     * rendered from a Server Component with no facets at all (the kill-switch
+     * fallback), and a required-looking prop that is absent half the time
+     * invites a `?? []` that silently renders an empty rail.
+     */
+    renderAboveGroups?: () => React.ReactNode;
+    /**
+     * A short line under the heading — "results as of 10:51". Optional because
+     * the server tier has no build time to report.
+     */
+    footnote?: string;
 }
-export declare function SearchResultsPageView({ result, renderSearchInput, }: SearchResultsPageViewProps): React.JSX.Element;
+export declare function SearchResultsPageView({ result, renderSearchInput, renderAboveGroups, footnote, }: SearchResultsPageViewProps): React.JSX.Element;

package/dist/features/search/components/SearchResultsPageView.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { ROUTES } from "../../../next/routing/route-map.js";
 import { Section, Container, Stack, Row, Div, Heading, Text, Span, TextLink } from "../../../ui/index.js";
-export function SearchResultsPageView({ result, renderSearchInput, }) {
+export function SearchResultsPageView({ result, renderSearchInput, renderAboveGroups, footnote, }) {
     const { q, terms, groups, totalHits } = result;
     const hasQuery = q.trim().length > 0;
     /*
@@ -18,5 +18,5 @@ export function SearchResultsPageView({ result, renderSearchInput, }) {
     const normalisedAway = hasQuery && terms.length === 0;
     return (_jsx(Section, { padding: "page", children: _jsx(Container, { children: _jsxs(Stack, { gap: "loose", children: [_jsxs(Stack, { gap: "xs", children: [_jsx(Heading, { level: 1, children: hasQuery ? `Search: ${q}` : "Search" }), hasQuery && !normalisedAway && (_jsx(Text, { color: "muted", size: "sm", children: totalHits === 0
                                     ? "Nothing matched."
-                                    : `${totalHits}${groups.some((g) => g.truncated) ? "+" : ""} result${totalHits === 1 ? "" : "s"} across ${groups.length} section${groups.length === 1 ? "" : "s"}.` }))] }), renderSearchInput?.(), !hasQuery && (_jsx(Text, { color: "muted", children: "Search listings, categories, brands, stores, articles and help pages at once." })), normalisedAway && (_jsx(Text, { color: "muted", children: "That search had no searchable words in it. Try a product, part or category name." })), groups.map((group) => (_jsxs(Stack, { gap: "sm", children: [_jsxs(Row, { justify: "between", align: "center", wrap: true, gap: "sm", children: [_jsxs(Heading, { level: 2, size: "lg", children: [group.label, group.truncated && (_jsxs(Span, { size: "sm", color: "muted", children: [" ", "(", group.hits.length, "+)"] }))] }), _jsxs(TextLink, { href: group.moreHref, children: ["See all ", group.label.toLowerCase(), " \u2192"] })] }), _jsx(Stack, { gap: "xs", children: group.hits.map((hit) => (_jsxs(Div, { surface: "card", padding: "sm", rounded: "md", children: [_jsx(TextLink, { href: hit.href, children: hit.title }), hit.detail && (_jsx(Text, { size: "xs", color: "muted", children: hit.detail }))] }, `${group.key}-${hit.id}`))) })] }, group.key))), hasQuery && !normalisedAway && totalHits === 0 && (_jsxs(Stack, { gap: "xs", children: [_jsxs(Text, { color: "muted", children: ["No listings, categories, brands, stores, articles or help pages matched \u201C", q, "\u201D."] }), _jsx(TextLink, { href: ROUTES.PUBLIC.PRODUCTS, children: "Browse all listings \u2192" })] }))] }) }) }));
+                                    : `${totalHits}${groups.some((g) => g.truncated) ? "+" : ""} result${totalHits === 1 ? "" : "s"} across ${groups.length} section${groups.length === 1 ? "" : "s"}.` }))] }), footnote && (_jsx(Text, { size: "xs", color: "muted", children: footnote })), renderSearchInput?.(), renderAboveGroups?.(), !hasQuery && (_jsx(Text, { color: "muted", children: "Search listings, categories, brands, stores, articles and help pages at once." })), normalisedAway && (_jsx(Text, { color: "muted", children: "That search had no searchable words in it. Try a product, part or category name." })), groups.map((group) => (_jsxs(Stack, { gap: "sm", children: [_jsxs(Row, { justify: "between", align: "center", wrap: true, gap: "sm", children: [_jsxs(Heading, { level: 2, size: "lg", children: [group.label, group.truncated && (_jsxs(Span, { size: "sm", color: "muted", children: [" ", "(", group.hits.length, "+)"] }))] }), _jsxs(TextLink, { href: group.moreHref, children: ["See all ", group.label.toLowerCase(), " \u2192"] })] }), _jsx(Stack, { gap: "xs", children: group.hits.map((hit) => (_jsxs(Div, { surface: "card", padding: "sm", rounded: "md", children: [_jsx(TextLink, { href: hit.href, children: hit.title }), hit.detail && (_jsx(Text, { size: "xs", color: "muted", children: hit.detail }))] }, `${group.key}-${hit.id}`))) })] }, group.key))), hasQuery && !normalisedAway && totalHits === 0 && (_jsxs(Stack, { gap: "xs", children: [_jsxs(Text, { color: "muted", children: ["No listings, categories, brands, stores, articles or help pages matched \u201C", q, "\u201D."] }), _jsx(TextLink, { href: ROUTES.PUBLIC.PRODUCTS, children: "Browse all listings \u2192" })] }))] }) }) }));
 }

package/dist/features/search/components/index.d.ts

@@ -1,8 +1,2 @@
 export { Search } from "./Search";
 export type { SearchLabels, SearchProps, SearchQuickLink, SearchRouterAdapter, SearchResourceType, SearchResourceTypeOption, } from "./Search";
-export { SearchFiltersRow } from "./SearchFiltersRow";
-export type {} from "./SearchFiltersRow";
-export { SearchResultsSection } from "./SearchResultsSection";
-export type { SearchResultsSectionProps } from "./SearchResultsSection";
-export { SearchView } from "./SearchView";
-export type { SearchViewProps } from "./SearchView";

package/dist/features/search/components/index.js

@@ -1,4 +1 @@
 export { Search } from "./Search.js";
-export { SearchFiltersRow } from "./SearchFiltersRow.js";
-export { SearchResultsSection } from "./SearchResultsSection.js";
-export { SearchView } from "./SearchView.js";

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

@@ -1,6 +1,19 @@
 export interface NavSuggestionRecord {
     objectID: string;
     type: "page" | "category" | "blog" | "event" | "product";
+    /**
+     * The real index type key (`auction`, `part`, `faq`, `scammer`, …) when the
+     * row came from the local search artifact, which spans 21 types.
+     *
+     * 🛑 `type` above stays a 5-value union on purpose. It is what the
+     * dropdown's `DEFAULT_TYPE_ICONS` / `DEFAULT_TYPE_BADGES` maps switch on,
+     * so widening it would compile everywhere and render 16 types unstyled
+     * (Root Cause #20). `useSiteSearch.suggestionTypeFor` collapses the key
+     * into that union for presentation and puts the precise one here, so a
+     * badge can be specific where a map entry exists without any caller
+     * breaking where one does not.
+     */
+    typeKey?: string;
     title: string;
     subtitle?: string;
     url: string;

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

@@ -0,0 +1,34 @@
+import type { SearchGroup } from "../../../_internal/server/features/search/search-everything";
+export type ScopedSearchStatus = "idle" | "loading" | "ready" | "failed";
+export interface UseScopedSearchResult {
+    readonly status: ScopedSearchStatus;
+    readonly groups: readonly SearchGroup[];
+}
+export interface UseScopedSearchOptions {
+    /** False for a guest. No request is issued at all. */
+    enabled: boolean;
+    /** The committed query. Changing it re-fetches; typing does not. */
+    submittedQuery: string;
+}
+export declare function useScopedSearch({ enabled, submittedQuery, }: UseScopedSearchOptions): UseScopedSearchResult;
+/**
+ * Merge the two tiers.
+ *
+ * ## 🛑 Dedupe by DESTINATION, and local wins
+ *
+ * The tiers are NOT disjoint: a seller's published listing is in the public
+ * artifact AND in `my-listings`. Showing both is a duplicate-results bug;
+ * dropping the public one would lose the row a buyer would see.
+ *
+ * Local wins, so what survives in the scoped group is precisely the rows the
+ * artifact does not have — a seller's DRAFTS. Labelling that group "Your
+ * listings (incl. drafts)" is what makes the dedupe legible rather than
+ * mysterious.
+ *
+ * 🛑 The key is the HREF, not `${typeKey}:${id}`. The artifact keys products
+ * by SLUG and Firestore by document id, so a composite key would never
+ * collide and the dedupe would silently do nothing — the failure mode being
+ * a page that looks fine and shows everything twice. Both tiers already
+ * agree on where a row goes, which is the only identity they share.
+ */
+export declare function mergeSearchTiers(local: readonly SearchGroup[], scoped: readonly SearchGroup[]): SearchGroup[];

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

@@ -0,0 +1,114 @@
+"use client";
+/*
+ * WHY: A signed-in viewer's own records belong in the same box as the public
+ *      catalogue — but they cost real reads and must not be fetched the way
+ *      the free tier is.
+ * WHAT: Tier 2's client half, plus the merge with Tier 1.
+ *
+ * ## 🛑 ON SUBMIT, never per keystroke
+ *
+ * Tier 1 is a local scan and costs nothing, so it runs on every character.
+ * This one is a bounded Firestore fan-out — up to ~320 documents for an
+ * admin — so it runs when the user commits to a query. A debounced
+ * per-keystroke version of this endpoint is how a 50k/day read tier
+ * disappears in an afternoon.
+ *
+ * ## 🛑 A guest issues ZERO requests
+ *
+ * Gated on `enabled`, which the caller sets from the session. The server
+ * refuses too (`auth: true`, and `scopedSourcesFor(null)` is `[]`), but the
+ * client gate is what makes "signed out = no authenticated request in the
+ * Network panel" true, which is the only form of that claim anyone can
+ * verify.
+ *
+ * @tag domain:search
+ * @tag layer:feature
+ * @tag pattern:hook
+ * @tag access:client
+ * @tag consumers:SearchResultsClient
+ * @tag sideEffects:network
+ */
+import * as React from "react";
+import { apiClient } from "../../../http/index.js";
+import { normalizeError } from "../../../errors/normalize.js";
+import { SEARCH_ENDPOINTS } from "../../../constants/api-endpoints.js";
+/** Matches the server-side gate, so the two cannot disagree about what is worth asking. */
+const MIN_CHARS = 3;
+export function useScopedSearch({ enabled, submittedQuery, }) {
+    const [status, setStatus] = React.useState("idle");
+    const [groups, setGroups] = React.useState([]);
+    React.useEffect(() => {
+        const q = submittedQuery.trim();
+        if (!enabled || q.length < MIN_CHARS) {
+            setStatus("idle");
+            setGroups([]);
+            return;
+        }
+        /*
+         * An `AbortController` per query, mirroring `useNavSuggestions`. Without
+         * it, a slow response to an earlier query can land after a faster
+         * response to a later one and overwrite it — the user sees results for
+         * something they already moved on from, which looks like the search
+         * returning the wrong thing rather than like a race.
+         */
+        const controller = new AbortController();
+        setStatus("loading");
+        apiClient
+            .get(SEARCH_ENDPOINTS.SCOPED(q), { signal: controller.signal })
+            .then((res) => {
+            if (controller.signal.aborted)
+                return;
+            setGroups(res?.data?.groups ?? []);
+            setStatus("ready");
+        })
+            .catch((err) => {
+            if (controller.signal.aborted)
+                return;
+            const e = normalizeError(err);
+            /*
+             * `failed`, and the CALLER must say so out loud.
+             * `searchEverything`'s own header records that a degraded source "is
+             * indistinguishable from 'nothing matched'" — and on a page where
+             * the public half rendered fine, silence tells a seller their draft
+             * does not exist.
+             */
+            void e;
+            setGroups([]);
+            setStatus("failed");
+        });
+        return () => controller.abort();
+    }, [enabled, submittedQuery]);
+    return { status, groups };
+}
+/**
+ * Merge the two tiers.
+ *
+ * ## 🛑 Dedupe by DESTINATION, and local wins
+ *
+ * The tiers are NOT disjoint: a seller's published listing is in the public
+ * artifact AND in `my-listings`. Showing both is a duplicate-results bug;
+ * dropping the public one would lose the row a buyer would see.
+ *
+ * Local wins, so what survives in the scoped group is precisely the rows the
+ * artifact does not have — a seller's DRAFTS. Labelling that group "Your
+ * listings (incl. drafts)" is what makes the dedupe legible rather than
+ * mysterious.
+ *
+ * 🛑 The key is the HREF, not `${typeKey}:${id}`. The artifact keys products
+ * by SLUG and Firestore by document id, so a composite key would never
+ * collide and the dedupe would silently do nothing — the failure mode being
+ * a page that looks fine and shows everything twice. Both tiers already
+ * agree on where a row goes, which is the only identity they share.
+ */
+export function mergeSearchTiers(local, scoped) {
+    const seen = new Set();
+    for (const g of local)
+        for (const h of g.hits)
+            seen.add(h.href);
+    const deduped = scoped
+        .map((g) => ({ ...g, hits: g.hits.filter((h) => !seen.has(h.href)) }))
+        // A scoped group that is now empty is dropped entirely rather than
+        // rendered as a heading over nothing, which reads as a broken section.
+        .filter((g) => g.hits.length > 0);
+    return [...local, ...deduped];
+}

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

@@ -0,0 +1,26 @@
+import { type FacetCount } from "../../../_internal/shared/search/to-groups";
+import { type SearchIndexStatus } from "./useSearchIndex";
+import type { SearchEverythingResult } from "../../../_internal/server/features/search/search-everything";
+import type { NavSuggestionRecord } from "./useNavSuggestions";
+export interface UseSiteSearchOptions {
+    /** Flip true on focus or first keypress. Gates the artifact fetch. */
+    active: boolean;
+    /** `siteSettings.search?.indexEnabled` — read as `!== false`. */
+    indexEnabled?: boolean;
+    /** Restrict to these index type keys. Absent means every type. */
+    types?: readonly string[];
+    /** Require every one of these `k:v` pairs. The facet rail's selection. */
+    facets?: readonly string[];
+    /** `typeKey` -> heading. See `ToGroupsOptions.label`. */
+    label: (typeKey: string) => string;
+}
+export interface UseSiteSearchResult {
+    readonly status: SearchIndexStatus;
+    /** Null until the index is ready; never a fabricated empty result. */
+    readonly result: SearchEverythingResult | null;
+    readonly suggestions: readonly NavSuggestionRecord[];
+    readonly facets: readonly FacetCount[];
+    /** The index build this answered from, for a "results as of" line. */
+    readonly builtAt: string | null;
+}
+export declare function useSiteSearch(query: string, { active, indexEnabled, types, facets, label }: UseSiteSearchOptions): UseSiteSearchResult;