@veluai/velu 0.2.13 → 0.2.15

package/runtime/velu-ui/components/Search.jsx

@@ -1,460 +1,460 @@
-import React, {
-  useState,
-  useRef,
-  useEffect,
-  useMemo,
-  useCallback,
-} from 'react';
-import resolveIcon from '../lib/resolveIcon.jsx';
-
-/**
- * Search — a Raycast-style command palette for the docs site. Ported
- * from the Claude-Design "Velu Search" handoff and retokenized onto
- * velu-ui's scale (themes for free via [data-theme]).
- *
- *   <Search results={[…]} onSelect={(item) => …} />
- *
- * Renders a trigger box (drop it at the top of the page). Clicking it —
- * or pressing ⌘K / Ctrl+K anywhere — reveals the palette: a scrim plus
- * a centered panel with a search input and grouped, keyboard-navigable
- * results (↑/↓ to move, Enter to pick, Esc / scrim-click to close).
- *
- * @typedef {Object} SearchResult
- * @property {string} id
- * @property {string} group       'Recent Searches' | 'Suggested' | 'Pages'
- * @property {string[]} breadcrumb
- * @property {string} title
- * @property {'page'|'anchor'|'ext'} kind
- * @property {string} desc
- * @property {string} [href]
- *
- * @param {{ results?: SearchResult[], placeholder?: string,
- *           onSelect?: (item: SearchResult) => void,
- *           className?: string }} props
- */
-
-/* Sample result set — the demo data from the design. Override via the
-   `results` prop with real indexed content. */
-const DEFAULT_RESULTS = [
-  {
-    id: 'auth-pw',
-    group: 'Recent Searches',
-    breadcrumb: ['Authentication setup', 'Password'],
-    title: 'Password',
-    kind: 'anchor',
-    desc: 'Password authentication provides access control through credentials.',
-  },
-  {
-    id: 'gh-sync',
-    group: 'Recent Searches',
-    breadcrumb: ['Get Started', 'GitHub & GitLab Sync'],
-    title: 'Enabling GitHub sync',
-    kind: 'page',
-    desc: 'Connect a GitHub repository to keep your docs in sync on every push.',
-  },
-  {
-    id: 'ai-search',
-    group: 'Recent Searches',
-    breadcrumb: ['Your Docs Site'],
-    title: 'AI Search',
-    kind: 'page',
-    desc: 'Configure semantic search for your documentation site.',
-  },
-  {
-    id: 'quickstart',
-    group: 'Suggested',
-    breadcrumb: ['Get Started'],
-    title: 'Quickstart',
-    kind: 'page',
-    desc: 'Set up Velu and publish your first docs site in under 5 minutes.',
-  },
-  {
-    id: 'overview',
-    group: 'Suggested',
-    breadcrumb: ['Get Started'],
-    title: 'Overview',
-    kind: 'page',
-    desc: 'Velu is an AI-native documentation platform built for humans and AI agents.',
-  },
-  {
-    id: 'site-settings',
-    group: 'Suggested',
-    breadcrumb: ['Your Docs Site'],
-    title: 'Site Settings',
-    kind: 'page',
-    desc: 'Configure domain, theme, navigation and SEO for your docs site.',
-  },
-  {
-    id: 'oauth',
-    group: 'Pages',
-    breadcrumb: ['Authentication setup', 'OAuth'],
-    title: 'OAuth',
-    kind: 'anchor',
-    desc: 'Configure OAuth providers for sign-in.',
-  },
-  {
-    id: 'saml',
-    group: 'Pages',
-    breadcrumb: ['Authentication setup', 'SAML'],
-    title: 'SAML',
-    kind: 'anchor',
-    desc: 'Enterprise single sign-on via SAML 2.0.',
-  },
-];
-
-const GROUP_ORDER = ['Recent Searches', 'Suggested', 'Pages'];
-
-/* Left-hand glyph: '#' for an anchor, an icon for page / external. */
-function ResultGlyph({ kind }) {
-  if (kind === 'anchor') {
-    return <span className="velu-search__glyph-hash">#</span>;
-  }
-  const icon = kind === 'ext' ? 'external-link' : 'file-text';
-  return (
-    <span className="velu-search__glyph-icon">
-      {resolveIcon(icon, { size: '1em' })}
-    </span>
-  );
-}
-
-function Breadcrumb({ items }) {
-  return (
-    <div className="velu-search__crumbs">
-      {items.map((c, i) => (
-        <React.Fragment key={i}>
-          {i > 0 && <span className="velu-search__crumb-sep">›</span>}
-          <span>{c}</span>
-        </React.Fragment>
-      ))}
-    </div>
-  );
-}
-
-function PaletteRow({ item, selected, navMode, onHover, onSelect }) {
-  const ref = useRef(null);
-  useEffect(() => {
-    // Only auto-scroll for keyboard nav — on mouse hover the pointer is
-    // already on the row, and scrolling there nudges the list (a 1px
-    // jitter that flickers a line at the list edge).
-    if (selected && navMode.current === 'keyboard' && ref.current) {
-      ref.current.scrollIntoView({ block: 'nearest' });
-    }
-  }, [selected, navMode]);
-  return (
-    <div
-      ref={ref}
-      className={`velu-search__row${selected ? ' velu-search__row--selected' : ''}`}
-      onMouseEnter={onHover}
-      onClick={onSelect}
-      role="option"
-      aria-selected={selected}
-    >
-      <div className="velu-search__row-glyph">
-        <ResultGlyph kind={item.kind} />
-      </div>
-      <Breadcrumb items={item.breadcrumb} />
-      <div className="velu-search__row-title">{item.title}</div>
-      <div className="velu-search__row-desc">{item.desc}</div>
-      <div className="velu-search__row-meta">
-        <span className="velu-search__kbd">↵</span>
-      </div>
-    </div>
-  );
-}
-
-/* The revealed palette — scrim + centered panel. When `search` (an async
-   query → results function, e.g. the Pagefind client) is provided, results
-   come from it; otherwise the static `results` list is filtered in-memory. */
-function SearchPalette({ results, search, placeholder, onSelect, onClose }) {
-  const [query, setQuery] = useState('');
-  const [selected, setSelected] = useState(0);
-  const [asyncResults, setAsyncResults] = useState([]);
-  const [searching, setSearching] = useState(false);
-  const inputRef = useRef(null);
-  // 'keyboard' | 'mouse' — which input last moved the selection; gates
-  // the rows' scrollIntoView so mouse hover doesn't jitter the list.
-  const navMode = useRef('keyboard');
-
-  useEffect(() => {
-    inputRef.current?.focus();
-  }, []);
-
-  // Async source (Pagefind): debounce the query, fetch results.
-  useEffect(() => {
-    if (!search) return undefined;
-    const q = query.trim();
-    if (!q) {
-      setAsyncResults([]);
-      setSearching(false);
-      return undefined;
-    }
-    let cancelled = false;
-    setSearching(true);
-    const t = setTimeout(async () => {
-      const r = await search(q).catch(() => []);
-      if (!cancelled) {
-        setAsyncResults(Array.isArray(r) ? r : []);
-        setSearching(false);
-      }
-    }, 150);
-    return () => {
-      cancelled = true;
-      clearTimeout(t);
-    };
-  }, [query, search]);
-
-  const filtered = useMemo(() => {
-    if (search) return asyncResults;
-    const q = query.trim().toLowerCase();
-    if (!q) {
-      // Empty query → just the recents.
-      return results.filter((r) => r.group === 'Recent Searches');
-    }
-    return results.filter((r) => {
-      const hay = `${r.title} ${r.breadcrumb.join(' ')} ${r.desc}`.toLowerCase();
-      return hay.includes(q);
-    });
-  }, [search, asyncResults, query, results]);
-
-  const grouped = useMemo(() => {
-    const map = new Map();
-    filtered.forEach((r) => {
-      const g = r.group || 'Pages';
-      if (!map.has(g)) map.set(g, []);
-      map.get(g).push(r);
-    });
-    const known = GROUP_ORDER.filter((g) => map.has(g));
-    const extra = [...map.keys()].filter((g) => !GROUP_ORDER.includes(g));
-    return [...known, ...extra].map((g) => [g, map.get(g)]);
-  }, [filtered]);
-
-  const flat = useMemo(
-    () => grouped.flatMap(([, items]) => items),
-    [grouped],
-  );
-
-  useEffect(() => setSelected(0), [query]);
-
-  const pick = useCallback(
-    (item) => {
-      onSelect?.(item);
-      onClose();
-    },
-    [onSelect, onClose],
-  );
-
-  useEffect(() => {
-    const onKey = (e) => {
-      if (e.key === 'Escape') {
-        e.preventDefault();
-        onClose();
-      } else if (e.key === 'ArrowDown') {
-        e.preventDefault();
-        navMode.current = 'keyboard';
-        setSelected((s) => Math.min(s + 1, flat.length - 1));
-      } else if (e.key === 'ArrowUp') {
-        e.preventDefault();
-        navMode.current = 'keyboard';
-        setSelected((s) => Math.max(s - 1, 0));
-      } else if (e.key === 'Enter') {
-        e.preventDefault();
-        if (flat[selected]) pick(flat[selected]);
-        else onClose();
-      }
-    };
-    window.addEventListener('keydown', onKey);
-    return () => window.removeEventListener('keydown', onKey);
-  }, [flat, selected, pick, onClose]);
-
-  let rowIndex = -1;
-
-  return (
-    <div
-      className="velu-search__scrim"
-      onClick={onClose}
-      role="presentation"
-    >
-      <div
-        className="velu-search__palette"
-        role="dialog"
-        aria-modal="true"
-        aria-label="Search"
-        onClick={(e) => e.stopPropagation()}
-      >
-        <div className="velu-search__input-wrap">
-          <span className="velu-search__input-icon" aria-hidden="true">
-            {resolveIcon('search', { size: '1em' })}
-          </span>
-          <input
-            ref={inputRef}
-            className="velu-search__input"
-            placeholder={placeholder}
-            value={query}
-            onChange={(e) => setQuery(e.target.value)}
-            spellCheck={false}
-            aria-label="Search query"
-          />
-          <span className="velu-search__kbd">esc</span>
-        </div>
-
-        <div className="velu-search__list" role="listbox">
-          {grouped.length === 0 &&
-            (search && !query.trim() ? (
-              <div className="velu-search__empty">
-                <span className="velu-search__empty-icon" aria-hidden="true">
-                  {resolveIcon('search', { size: '1em' })}
-                </span>
-                <div className="velu-search__empty-title">Search the docs</div>
-                <div className="velu-search__empty-sub">
-                  Type to find pages and sections.
-                </div>
-              </div>
-            ) : searching ? (
-              <div className="velu-search__empty">
-                <div className="velu-search__empty-sub">Searching…</div>
-              </div>
-            ) : (
-              <div className="velu-search__empty">
-                <span className="velu-search__empty-icon" aria-hidden="true">
-                  {resolveIcon('search-x', { size: '1em' })}
-                </span>
-                <div className="velu-search__empty-title">
-                  No results for &ldquo;{query}&rdquo;
-                </div>
-                <div className="velu-search__empty-sub">
-                  Try a different keyword or browse the sidebar.
-                </div>
-              </div>
-            ))}
-          {grouped.map(([group, items]) => (
-            <div key={group}>
-              <div className="velu-search__group">{group}</div>
-              {items.map((item) => {
-                rowIndex += 1;
-                const idx = rowIndex;
-                return (
-                  <PaletteRow
-                    key={item.id}
-                    item={item}
-                    selected={idx === selected}
-                    navMode={navMode}
-                    onHover={() => {
-                      navMode.current = 'mouse';
-                      setSelected(idx);
-                    }}
-                    onSelect={() => pick(item)}
-                  />
-                );
-              })}
-            </div>
-          ))}
-        </div>
-      </div>
-    </div>
-  );
-}
-
-/* Shown instead of the palette when search is unavailable (e.g. the local
-   dev preview has no search index — that's generated when the site deploys).
-   Reuses the palette's empty-state styling so it looks at home. */
-function SearchUnavailable({ message, onClose }) {
-  useEffect(() => {
-    const onKey = (e) => {
-      if (e.key === 'Escape') {
-        e.preventDefault();
-        onClose();
-      }
-    };
-    window.addEventListener('keydown', onKey);
-    return () => window.removeEventListener('keydown', onKey);
-  }, [onClose]);
-  return (
-    <div className="velu-search__scrim" onClick={onClose} role="presentation">
-      <div
-        className="velu-search__palette"
-        role="dialog"
-        aria-modal="true"
-        aria-label="Search unavailable"
-        onClick={(e) => e.stopPropagation()}
-      >
-        <div className="velu-search__empty">
-          <span className="velu-search__empty-icon" aria-hidden="true">
-            {resolveIcon('search-x', { size: '1em' })}
-          </span>
-          <div className="velu-search__empty-title">
-            Search isn’t available in the dev preview
-          </div>
-          <div className="velu-search__empty-sub">{message}</div>
-        </div>
-      </div>
-    </div>
-  );
-}
-
-export default function Search({
-  results = DEFAULT_RESULTS,
-  search,
-  placeholder = 'Search documentation',
-  onSelect,
-  unavailable = false,
-  unavailableMessage = 'Full-text search is generated when your site is deployed — it isn’t available in the local preview.',
-  className = '',
-  ...rest
-}) {
-  const [open, setOpen] = useState(false);
-  // Show ⌘ K on Mac, Ctrl K elsewhere. SSR-safe: default to the
-  // non-Mac label (so the server render matches the first client
-  // render), then switch on the client if it's actually Mac.
-  const [isMac, setIsMac] = useState(false);
-  useEffect(() => {
-    if (typeof navigator === 'undefined') return;
-    const ua = navigator.userAgent || '';
-    const plat = navigator.platform || '';
-    setIsMac(/Mac|iPhone|iPad|iPod/i.test(plat) || /Mac/i.test(ua));
-  }, []);
-
-  // Global ⌘K (Mac) / Ctrl+K (Win/Linux) opens the palette.
-  useEffect(() => {
-    const onKey = (e) => {
-      if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === 'k') {
-        e.preventDefault();
-        setOpen(true);
-      }
-    };
-    window.addEventListener('keydown', onKey);
-    return () => window.removeEventListener('keydown', onKey);
-  }, []);
-
-  return (
-    <>
-      <button
-        type="button"
-        className={`velu-search__trigger ${className}`.trim()}
-        onClick={() => setOpen(true)}
-        {...rest}
-      >
-        <span className="velu-search__trigger-icon" aria-hidden="true">
-          {resolveIcon('search', { size: '1.5em' })}
-        </span>
-        <span className="velu-search__trigger-label">Search…</span>
-        <span className="velu-search__kbd">{isMac ? '⌘ K' : 'Ctrl K'}</span>
-      </button>
-
-      {open &&
-        (unavailable ? (
-          <SearchUnavailable
-            message={unavailableMessage}
-            onClose={() => setOpen(false)}
-          />
-        ) : (
-          <SearchPalette
-            results={results}
-            search={search}
-            placeholder={placeholder}
-            onSelect={onSelect}
-            onClose={() => setOpen(false)}
-          />
-        ))}
-    </>
-  );
-}
+import React, {
+  useState,
+  useRef,
+  useEffect,
+  useMemo,
+  useCallback,
+} from 'react';
+import resolveIcon from '../lib/resolveIcon.jsx';
+
+/**
+ * Search — a Raycast-style command palette for the docs site. Ported
+ * from the Claude-Design "Velu Search" handoff and retokenized onto
+ * velu-ui's scale (themes for free via [data-theme]).
+ *
+ *   <Search results={[…]} onSelect={(item) => …} />
+ *
+ * Renders a trigger box (drop it at the top of the page). Clicking it —
+ * or pressing ⌘K / Ctrl+K anywhere — reveals the palette: a scrim plus
+ * a centered panel with a search input and grouped, keyboard-navigable
+ * results (↑/↓ to move, Enter to pick, Esc / scrim-click to close).
+ *
+ * @typedef {Object} SearchResult
+ * @property {string} id
+ * @property {string} group       'Recent Searches' | 'Suggested' | 'Pages'
+ * @property {string[]} breadcrumb
+ * @property {string} title
+ * @property {'page'|'anchor'|'ext'} kind
+ * @property {string} desc
+ * @property {string} [href]
+ *
+ * @param {{ results?: SearchResult[], placeholder?: string,
+ *           onSelect?: (item: SearchResult) => void,
+ *           className?: string }} props
+ */
+
+/* Sample result set — the demo data from the design. Override via the
+   `results` prop with real indexed content. */
+const DEFAULT_RESULTS = [
+  {
+    id: 'auth-pw',
+    group: 'Recent Searches',
+    breadcrumb: ['Authentication setup', 'Password'],
+    title: 'Password',
+    kind: 'anchor',
+    desc: 'Password authentication provides access control through credentials.',
+  },
+  {
+    id: 'gh-sync',
+    group: 'Recent Searches',
+    breadcrumb: ['Get Started', 'GitHub & GitLab Sync'],
+    title: 'Enabling GitHub sync',
+    kind: 'page',
+    desc: 'Connect a GitHub repository to keep your docs in sync on every push.',
+  },
+  {
+    id: 'ai-search',
+    group: 'Recent Searches',
+    breadcrumb: ['Your Docs Site'],
+    title: 'AI Search',
+    kind: 'page',
+    desc: 'Configure semantic search for your documentation site.',
+  },
+  {
+    id: 'quickstart',
+    group: 'Suggested',
+    breadcrumb: ['Get Started'],
+    title: 'Quickstart',
+    kind: 'page',
+    desc: 'Set up Velu and publish your first docs site in under 5 minutes.',
+  },
+  {
+    id: 'overview',
+    group: 'Suggested',
+    breadcrumb: ['Get Started'],
+    title: 'Overview',
+    kind: 'page',
+    desc: 'Velu is an AI-native documentation platform built for humans and AI agents.',
+  },
+  {
+    id: 'site-settings',
+    group: 'Suggested',
+    breadcrumb: ['Your Docs Site'],
+    title: 'Site Settings',
+    kind: 'page',
+    desc: 'Configure domain, theme, navigation and SEO for your docs site.',
+  },
+  {
+    id: 'oauth',
+    group: 'Pages',
+    breadcrumb: ['Authentication setup', 'OAuth'],
+    title: 'OAuth',
+    kind: 'anchor',
+    desc: 'Configure OAuth providers for sign-in.',
+  },
+  {
+    id: 'saml',
+    group: 'Pages',
+    breadcrumb: ['Authentication setup', 'SAML'],
+    title: 'SAML',
+    kind: 'anchor',
+    desc: 'Enterprise single sign-on via SAML 2.0.',
+  },
+];
+
+const GROUP_ORDER = ['Recent Searches', 'Suggested', 'Pages'];
+
+/* Left-hand glyph: '#' for an anchor, an icon for page / external. */
+function ResultGlyph({ kind }) {
+  if (kind === 'anchor') {
+    return <span className="velu-search__glyph-hash">#</span>;
+  }
+  const icon = kind === 'ext' ? 'external-link' : 'file-text';
+  return (
+    <span className="velu-search__glyph-icon">
+      {resolveIcon(icon, { size: '1em' })}
+    </span>
+  );
+}
+
+function Breadcrumb({ items }) {
+  return (
+    <div className="velu-search__crumbs">
+      {items.map((c, i) => (
+        <React.Fragment key={i}>
+          {i > 0 && <span className="velu-search__crumb-sep">›</span>}
+          <span>{c}</span>
+        </React.Fragment>
+      ))}
+    </div>
+  );
+}
+
+function PaletteRow({ item, selected, navMode, onHover, onSelect }) {
+  const ref = useRef(null);
+  useEffect(() => {
+    // Only auto-scroll for keyboard nav — on mouse hover the pointer is
+    // already on the row, and scrolling there nudges the list (a 1px
+    // jitter that flickers a line at the list edge).
+    if (selected && navMode.current === 'keyboard' && ref.current) {
+      ref.current.scrollIntoView({ block: 'nearest' });
+    }
+  }, [selected, navMode]);
+  return (
+    <div
+      ref={ref}
+      className={`velu-search__row${selected ? ' velu-search__row--selected' : ''}`}
+      onMouseEnter={onHover}
+      onClick={onSelect}
+      role="option"
+      aria-selected={selected}
+    >
+      <div className="velu-search__row-glyph">
+        <ResultGlyph kind={item.kind} />
+      </div>
+      <Breadcrumb items={item.breadcrumb} />
+      <div className="velu-search__row-title">{item.title}</div>
+      <div className="velu-search__row-desc">{item.desc}</div>
+      <div className="velu-search__row-meta">
+        <span className="velu-search__kbd">↵</span>
+      </div>
+    </div>
+  );
+}
+
+/* The revealed palette — scrim + centered panel. When `search` (an async
+   query → results function, e.g. the Pagefind client) is provided, results
+   come from it; otherwise the static `results` list is filtered in-memory. */
+function SearchPalette({ results, search, placeholder, onSelect, onClose }) {
+  const [query, setQuery] = useState('');
+  const [selected, setSelected] = useState(0);
+  const [asyncResults, setAsyncResults] = useState([]);
+  const [searching, setSearching] = useState(false);
+  const inputRef = useRef(null);
+  // 'keyboard' | 'mouse' — which input last moved the selection; gates
+  // the rows' scrollIntoView so mouse hover doesn't jitter the list.
+  const navMode = useRef('keyboard');
+
+  useEffect(() => {
+    inputRef.current?.focus();
+  }, []);
+
+  // Async source (Pagefind): debounce the query, fetch results.
+  useEffect(() => {
+    if (!search) return undefined;
+    const q = query.trim();
+    if (!q) {
+      setAsyncResults([]);
+      setSearching(false);
+      return undefined;
+    }
+    let cancelled = false;
+    setSearching(true);
+    const t = setTimeout(async () => {
+      const r = await search(q).catch(() => []);
+      if (!cancelled) {
+        setAsyncResults(Array.isArray(r) ? r : []);
+        setSearching(false);
+      }
+    }, 150);
+    return () => {
+      cancelled = true;
+      clearTimeout(t);
+    };
+  }, [query, search]);
+
+  const filtered = useMemo(() => {
+    if (search) return asyncResults;
+    const q = query.trim().toLowerCase();
+    if (!q) {
+      // Empty query → just the recents.
+      return results.filter((r) => r.group === 'Recent Searches');
+    }
+    return results.filter((r) => {
+      const hay = `${r.title} ${r.breadcrumb.join(' ')} ${r.desc}`.toLowerCase();
+      return hay.includes(q);
+    });
+  }, [search, asyncResults, query, results]);
+
+  const grouped = useMemo(() => {
+    const map = new Map();
+    filtered.forEach((r) => {
+      const g = r.group || 'Pages';
+      if (!map.has(g)) map.set(g, []);
+      map.get(g).push(r);
+    });
+    const known = GROUP_ORDER.filter((g) => map.has(g));
+    const extra = [...map.keys()].filter((g) => !GROUP_ORDER.includes(g));
+    return [...known, ...extra].map((g) => [g, map.get(g)]);
+  }, [filtered]);
+
+  const flat = useMemo(
+    () => grouped.flatMap(([, items]) => items),
+    [grouped],
+  );
+
+  useEffect(() => setSelected(0), [query]);
+
+  const pick = useCallback(
+    (item) => {
+      onSelect?.(item);
+      onClose();
+    },
+    [onSelect, onClose],
+  );
+
+  useEffect(() => {
+    const onKey = (e) => {
+      if (e.key === 'Escape') {
+        e.preventDefault();
+        onClose();
+      } else if (e.key === 'ArrowDown') {
+        e.preventDefault();
+        navMode.current = 'keyboard';
+        setSelected((s) => Math.min(s + 1, flat.length - 1));
+      } else if (e.key === 'ArrowUp') {
+        e.preventDefault();
+        navMode.current = 'keyboard';
+        setSelected((s) => Math.max(s - 1, 0));
+      } else if (e.key === 'Enter') {
+        e.preventDefault();
+        if (flat[selected]) pick(flat[selected]);
+        else onClose();
+      }
+    };
+    window.addEventListener('keydown', onKey);
+    return () => window.removeEventListener('keydown', onKey);
+  }, [flat, selected, pick, onClose]);
+
+  let rowIndex = -1;
+
+  return (
+    <div
+      className="velu-search__scrim"
+      onClick={onClose}
+      role="presentation"
+    >
+      <div
+        className="velu-search__palette"
+        role="dialog"
+        aria-modal="true"
+        aria-label="Search"
+        onClick={(e) => e.stopPropagation()}
+      >
+        <div className="velu-search__input-wrap">
+          <span className="velu-search__input-icon" aria-hidden="true">
+            {resolveIcon('search', { size: '1em' })}
+          </span>
+          <input
+            ref={inputRef}
+            className="velu-search__input"
+            placeholder={placeholder}
+            value={query}
+            onChange={(e) => setQuery(e.target.value)}
+            spellCheck={false}
+            aria-label="Search query"
+          />
+          <span className="velu-search__kbd">esc</span>
+        </div>
+
+        <div className="velu-search__list" role="listbox">
+          {grouped.length === 0 &&
+            (search && !query.trim() ? (
+              <div className="velu-search__empty">
+                <span className="velu-search__empty-icon" aria-hidden="true">
+                  {resolveIcon('search', { size: '1em' })}
+                </span>
+                <div className="velu-search__empty-title">Search the docs</div>
+                <div className="velu-search__empty-sub">
+                  Type to find pages and sections.
+                </div>
+              </div>
+            ) : searching ? (
+              <div className="velu-search__empty">
+                <div className="velu-search__empty-sub">Searching…</div>
+              </div>
+            ) : (
+              <div className="velu-search__empty">
+                <span className="velu-search__empty-icon" aria-hidden="true">
+                  {resolveIcon('search-x', { size: '1em' })}
+                </span>
+                <div className="velu-search__empty-title">
+                  No results for &ldquo;{query}&rdquo;
+                </div>
+                <div className="velu-search__empty-sub">
+                  Try a different keyword or browse the sidebar.
+                </div>
+              </div>
+            ))}
+          {grouped.map(([group, items]) => (
+            <div key={group}>
+              <div className="velu-search__group">{group}</div>
+              {items.map((item) => {
+                rowIndex += 1;
+                const idx = rowIndex;
+                return (
+                  <PaletteRow
+                    key={item.id}
+                    item={item}
+                    selected={idx === selected}
+                    navMode={navMode}
+                    onHover={() => {
+                      navMode.current = 'mouse';
+                      setSelected(idx);
+                    }}
+                    onSelect={() => pick(item)}
+                  />
+                );
+              })}
+            </div>
+          ))}
+        </div>
+      </div>
+    </div>
+  );
+}
+
+/* Shown instead of the palette when search is unavailable (e.g. the local
+   dev preview has no search index — that's generated when the site deploys).
+   Reuses the palette's empty-state styling so it looks at home. */
+function SearchUnavailable({ message, onClose }) {
+  useEffect(() => {
+    const onKey = (e) => {
+      if (e.key === 'Escape') {
+        e.preventDefault();
+        onClose();
+      }
+    };
+    window.addEventListener('keydown', onKey);
+    return () => window.removeEventListener('keydown', onKey);
+  }, [onClose]);
+  return (
+    <div className="velu-search__scrim" onClick={onClose} role="presentation">
+      <div
+        className="velu-search__palette"
+        role="dialog"
+        aria-modal="true"
+        aria-label="Search unavailable"
+        onClick={(e) => e.stopPropagation()}
+      >
+        <div className="velu-search__empty">
+          <span className="velu-search__empty-icon" aria-hidden="true">
+            {resolveIcon('search-x', { size: '1em' })}
+          </span>
+          <div className="velu-search__empty-title">
+            Search isn’t available in the dev preview
+          </div>
+          <div className="velu-search__empty-sub">{message}</div>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+export default function Search({
+  results = DEFAULT_RESULTS,
+  search,
+  placeholder = 'Search documentation',
+  onSelect,
+  unavailable = false,
+  unavailableMessage = 'Full-text search is generated when your site is deployed — it isn’t available in the local preview.',
+  className = '',
+  ...rest
+}) {
+  const [open, setOpen] = useState(false);
+  // Show ⌘ K on Mac, Ctrl K elsewhere. SSR-safe: default to the
+  // non-Mac label (so the server render matches the first client
+  // render), then switch on the client if it's actually Mac.
+  const [isMac, setIsMac] = useState(false);
+  useEffect(() => {
+    if (typeof navigator === 'undefined') return;
+    const ua = navigator.userAgent || '';
+    const plat = navigator.platform || '';
+    setIsMac(/Mac|iPhone|iPad|iPod/i.test(plat) || /Mac/i.test(ua));
+  }, []);
+
+  // Global ⌘K (Mac) / Ctrl+K (Win/Linux) opens the palette.
+  useEffect(() => {
+    const onKey = (e) => {
+      if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === 'k') {
+        e.preventDefault();
+        setOpen(true);
+      }
+    };
+    window.addEventListener('keydown', onKey);
+    return () => window.removeEventListener('keydown', onKey);
+  }, []);
+
+  return (
+    <>
+      <button
+        type="button"
+        className={`velu-search__trigger ${className}`.trim()}
+        onClick={() => setOpen(true)}
+        {...rest}
+      >
+        <span className="velu-search__trigger-icon" aria-hidden="true">
+          {resolveIcon('search', { size: '1.5em' })}
+        </span>
+        <span className="velu-search__trigger-label">Search…</span>
+        <span className="velu-search__kbd">{isMac ? '⌘ K' : 'Ctrl K'}</span>
+      </button>
+
+      {open &&
+        (unavailable ? (
+          <SearchUnavailable
+            message={unavailableMessage}
+            onClose={() => setOpen(false)}
+          />
+        ) : (
+          <SearchPalette
+            results={results}
+            search={search}
+            placeholder={placeholder}
+            onSelect={onSelect}
+            onClose={() => setOpen(false)}
+          />
+        ))}
+    </>
+  );
+}