@specglass/theme-default 0.0.2

package/src/islands/SearchPalette.tsx

@@ -0,0 +1,307 @@
+import { useState, useCallback, useEffect, useRef } from "react";
+
+import { cn } from "../lib/utils";
+import {
+  CommandDialog,
+  CommandInput,
+  CommandList,
+  CommandEmpty,
+  CommandItem,
+} from "../ui/command";
+
+/**
+ * SearchPalette — Cmd+K command palette using shadcn/ui CommandDialog.
+ *
+ * Uses the proper shadcn/ui Command + Dialog composition:
+ * - CommandDialog wraps Radix Dialog for overlay, portal, focus trap, ARIA
+ * - CommandInput, CommandList, CommandItem from shadcn command component
+ * - Pagefind provides search (cmdk's shouldFilter disabled)
+ *
+ * Designed for `client:idle` hydration.
+ */
+
+/** Shape of a Pagefind search result */
+interface PagefindResult {
+  id: string;
+  url: string;
+  excerpt: string;
+  meta: {
+    title?: string;
+    image?: string;
+  };
+  sub_results?: Array<{
+    title: string;
+    url: string;
+    excerpt: string;
+  }>;
+}
+
+interface PagefindResponse {
+  results: Array<{
+    id: string;
+    data: () => Promise<PagefindResult>;
+  }>;
+}
+
+interface PagefindAPI {
+  init: () => Promise<void>;
+  search: (query: string) => Promise<PagefindResponse>;
+}
+
+const DEBOUNCE_MS = 150;
+const MAX_RESULTS = 8;
+
+export function SearchPalette() {
+  const [open, setOpen] = useState(false);
+  const [query, setQuery] = useState("");
+  const [results, setResults] = useState<PagefindResult[]>([]);
+  const [isLoading, setIsLoading] = useState(false);
+  const [isUnavailable, setIsUnavailable] = useState(false);
+  const pagefindRef = useRef<PagefindAPI | null>(null);
+  const debounceRef = useRef<ReturnType<typeof setTimeout>>(null);
+
+  // Load Pagefind JS lazily on palette open
+  const loadPagefind = useCallback(async () => {
+    if (pagefindRef.current) return;
+
+    try {
+      const pagefindPath = `/pagefind/pagefind.js`;
+      const pf = await import(/* @vite-ignore */ pagefindPath);
+      await pf.init();
+      pagefindRef.current = pf as PagefindAPI;
+    } catch {
+      setIsUnavailable(true);
+    }
+  }, []);
+
+  // Perform search
+  const performSearch = useCallback(
+    async (searchQuery: string) => {
+      if (!searchQuery.trim()) {
+        setResults([]);
+        return;
+      }
+
+      if (!pagefindRef.current) {
+        await loadPagefind();
+        if (!pagefindRef.current) return;
+      }
+
+      setIsLoading(true);
+      try {
+        const response = await pagefindRef.current.search(searchQuery);
+        const loaded = await Promise.all(
+          response.results.slice(0, MAX_RESULTS).map((r) => r.data()),
+        );
+        setResults(loaded);
+      } catch {
+        setResults([]);
+      } finally {
+        setIsLoading(false);
+      }
+    },
+    [loadPagefind],
+  );
+
+  // Handle input changes with debounce
+  const handleValueChange = useCallback(
+    (value: string) => {
+      setQuery(value);
+      if (debounceRef.current) {
+        clearTimeout(debounceRef.current);
+      }
+      debounceRef.current = setTimeout(() => {
+        performSearch(value);
+      }, DEBOUNCE_MS);
+    },
+    [performSearch],
+  );
+
+  // Global Cmd+K / Ctrl+K keyboard shortcut
+  useEffect(() => {
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if ((e.metaKey || e.ctrlKey) && e.key === "k") {
+        e.preventDefault();
+        setOpen((prev) => !prev);
+      }
+    };
+
+    document.addEventListener("keydown", handleKeyDown);
+    return () => document.removeEventListener("keydown", handleKeyDown);
+  }, []);
+
+  // Load Pagefind when palette opens
+  useEffect(() => {
+    if (open) {
+      loadPagefind();
+    }
+  }, [open, loadPagefind]);
+
+  // Reset state when closing
+  const handleOpenChange = useCallback((isOpen: boolean) => {
+    setOpen(isOpen);
+    if (!isOpen) {
+      setTimeout(() => {
+        setQuery("");
+        setResults([]);
+      }, 150);
+    }
+  }, []);
+
+  // Navigate to a search result
+  const handleSelect = useCallback(
+    (url: string) => {
+      handleOpenChange(false);
+      window.location.href = url;
+    },
+    [handleOpenChange],
+  );
+
+  // Cleanup debounce on unmount
+  useEffect(() => {
+    return () => {
+      if (debounceRef.current) {
+        clearTimeout(debounceRef.current);
+      }
+    };
+  }, []);
+
+  return (
+    <div data-pagefind-ignore="">
+      {/* Trigger button */}
+      <button
+        type="button"
+        onClick={() => setOpen(true)}
+        className={cn(
+          "inline-flex items-center gap-2 px-3 py-1.5 text-sm rounded-md",
+          "border border-border bg-surface text-text-muted",
+          "hover:bg-hover-bg hover:text-text transition-colors",
+          "focus:outline-none focus-visible:ring-2 focus-visible:ring-primary",
+        )}
+        aria-label="Search documentation (⌘K)"
+      >
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          width="14"
+          height="14"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="2"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+          aria-hidden="true"
+          className="shrink-0"
+        >
+          <circle cx="11" cy="11" r="8" />
+          <path d="m21 21-4.3-4.3" />
+        </svg>
+        <span className="hidden sm:inline">Search…</span>
+        <kbd
+          className={cn(
+            "hidden sm:inline-flex items-center gap-0.5",
+            "rounded border border-border bg-surface-raised px-1.5 py-0.5",
+            "font-mono text-[10px] text-text-muted",
+          )}
+        >
+          ⌘K
+        </kbd>
+      </button>
+
+      {/* shadcn/ui CommandDialog */}
+      <CommandDialog open={open} onOpenChange={handleOpenChange} shouldFilter={false} dialogTitle="Search documentation">
+        <CommandInput
+          value={query}
+          onValueChange={handleValueChange}
+          placeholder="Search documentation…"
+        />
+
+        <CommandList>
+          {/* Dev-mode unavailable state */}
+          {isUnavailable && (
+            <div className="px-4 py-6 text-center text-sm text-text-muted">
+              <p className="mb-1">Search available after build</p>
+              <p className="text-xs opacity-70">
+                Run <code className="bg-surface-raised px-1 rounded">npx turbo build</code> to generate the search index
+              </p>
+            </div>
+          )}
+
+          {/* Loading state */}
+          {isLoading && !isUnavailable && (
+            <div className="px-4 py-6 text-center text-sm text-text-muted">
+              Searching…
+            </div>
+          )}
+
+          {/* Empty state */}
+          {!isLoading && !isUnavailable && query.trim().length > 0 && (
+            <CommandEmpty>
+              No results found for &ldquo;{query}&rdquo;
+            </CommandEmpty>
+          )}
+
+          {/* Prompt state */}
+          {!isUnavailable && !isLoading && query.trim().length === 0 && results.length === 0 && (
+            <div className="px-4 py-6 text-center text-sm text-text-muted">
+              Type to search documentation…
+            </div>
+          )}
+
+          {/* Results */}
+          {!isUnavailable &&
+            results.map((result) => (
+              <CommandItem
+                key={result.id}
+                value={result.id}
+                onSelect={() => handleSelect(result.url)}
+                className="flex flex-col items-start gap-1 px-3 py-2.5"
+              >
+                {/* Page title */}
+                <div className="font-medium text-text">
+                  {result.meta?.title ?? "Untitled"}
+                </div>
+
+                {/* Sub-result heading */}
+                {result.sub_results?.[0]?.title &&
+                  result.sub_results[0].title !== result.meta?.title && (
+                    <div className="text-xs text-text-muted">
+                      {result.sub_results[0].title}
+                    </div>
+                  )}
+
+                {/* Content snippet */}
+                <div
+                  className="text-xs text-text-muted line-clamp-2 [&_mark]:bg-primary/20 [&_mark]:text-text [&_mark]:rounded-sm [&_mark]:px-0.5"
+                  dangerouslySetInnerHTML={{
+                    __html:
+                      result.sub_results?.[0]?.excerpt ?? result.excerpt ?? "",
+                  }}
+                />
+              </CommandItem>
+            ))}
+        </CommandList>
+
+        {/* Footer with keyboard hints */}
+        {(results.length > 0 || query.trim().length > 0) && !isUnavailable && (
+          <div className="flex items-center justify-between border-t border-border px-3 py-2 text-xs text-text-muted">
+            <div className="flex items-center gap-3">
+              <span className="inline-flex items-center gap-1">
+                <kbd className="rounded border border-border bg-surface-raised px-1 py-0.5 font-mono text-[10px]">↑↓</kbd>
+                navigate
+              </span>
+              <span className="inline-flex items-center gap-1">
+                <kbd className="rounded border border-border bg-surface-raised px-1 py-0.5 font-mono text-[10px]">↵</kbd>
+                open
+              </span>
+              <span className="inline-flex items-center gap-1">
+                <kbd className="rounded border border-border bg-surface-raised px-1 py-0.5 font-mono text-[10px]">esc</kbd>
+                close
+              </span>
+            </div>
+          </div>
+        )}
+      </CommandDialog>
+    </div>
+  );
+}

package/src/islands/SearchResults.tsx

@@ -0,0 +1,301 @@
+import { useState, useCallback, useEffect, useRef } from "react";
+
+/**
+ * SearchResults — React island for Pagefind-powered documentation search.
+ *
+ * Provides a search input with debounced querying against the Pagefind index.
+ * Results display page title, section heading, and highlighted content snippets.
+ * Designed for `client:idle` hydration — search isn't needed immediately on load.
+ *
+ * Pagefind JS is loaded dynamically at runtime from /pagefind/pagefind.js
+ * (generated at build time by the Pagefind integration in @specglass/core).
+ *
+ * During dev server, the Pagefind index doesn't exist — handled gracefully
+ * with a "Search available after build" message.
+ */
+
+/** Shape of a Pagefind search result (subset of the Pagefind API) */
+interface PagefindResult {
+  id: string;
+  url: string;
+  excerpt: string;
+  meta: {
+    title?: string;
+    image?: string;
+  };
+  sub_results?: Array<{
+    title: string;
+    url: string;
+    excerpt: string;
+  }>;
+}
+
+interface PagefindResponse {
+  results: Array<{
+    id: string;
+    data: () => Promise<PagefindResult>;
+  }>;
+}
+
+interface PagefindAPI {
+  init: () => Promise<void>;
+  search: (query: string) => Promise<PagefindResponse>;
+}
+
+const DEBOUNCE_MS = 150;
+const MAX_RESULTS = 8;
+
+export function SearchResults() {
+  const [query, setQuery] = useState("");
+  const [results, setResults] = useState<PagefindResult[]>([]);
+  const [isLoading, setIsLoading] = useState(false);
+  const [isUnavailable, setIsUnavailable] = useState(false);
+  const [isFocused, setIsFocused] = useState(false);
+  const pagefindRef = useRef<PagefindAPI | null>(null);
+  const debounceRef = useRef<ReturnType<typeof setTimeout>>(null);
+  const inputRef = useRef<HTMLInputElement>(null);
+  const resultsRef = useRef<HTMLDivElement>(null);
+  const [selectedIndex, setSelectedIndex] = useState(-1);
+
+  // Load Pagefind JS lazily on first focus
+  const loadPagefind = useCallback(async () => {
+    if (pagefindRef.current) return;
+
+    try {
+      // Pagefind generates this file at build time in the output directory.
+      // Dynamic concatenation prevents Vite from statically analyzing the path
+      // (the index only exists after `astro build`, not during dev).
+      const pagefindPath = `/pagefind/pagefind.js`;
+      const pf = await import(/* @vite-ignore */ pagefindPath);
+      await pf.init();
+      pagefindRef.current = pf as PagefindAPI;
+    } catch {
+      // During dev server, the index doesn't exist
+      setIsUnavailable(true);
+    }
+  }, []);
+
+  // Perform search with debouncing
+  const performSearch = useCallback(
+    async (searchQuery: string) => {
+      if (!searchQuery.trim()) {
+        setResults([]);
+        setSelectedIndex(-1);
+        return;
+      }
+
+      if (!pagefindRef.current) {
+        await loadPagefind();
+        if (!pagefindRef.current) return;
+      }
+
+      setIsLoading(true);
+      try {
+        const response = await pagefindRef.current.search(searchQuery);
+
+        // Load full data for top results
+        const loaded = await Promise.all(
+          response.results.slice(0, MAX_RESULTS).map((r) => r.data()),
+        );
+
+        setResults(loaded);
+        setSelectedIndex(-1);
+      } catch {
+        setResults([]);
+      } finally {
+        setIsLoading(false);
+      }
+    },
+    [loadPagefind],
+  );
+
+  // Handle input changes with debounce
+  const handleInputChange = useCallback(
+    (value: string) => {
+      setQuery(value);
+
+      if (debounceRef.current) {
+        clearTimeout(debounceRef.current);
+      }
+
+      debounceRef.current = setTimeout(() => {
+        performSearch(value);
+      }, DEBOUNCE_MS);
+    },
+    [performSearch],
+  );
+
+  // Keyboard navigation
+  const handleKeyDown = useCallback(
+    (e: React.KeyboardEvent) => {
+      if (e.key === "ArrowDown") {
+        e.preventDefault();
+        setSelectedIndex((prev) => Math.min(prev + 1, results.length - 1));
+      } else if (e.key === "ArrowUp") {
+        e.preventDefault();
+        setSelectedIndex((prev) => Math.max(prev - 1, -1));
+      } else if (e.key === "Enter" && selectedIndex >= 0) {
+        e.preventDefault();
+        const result = results[selectedIndex];
+        if (result) {
+          window.location.href = result.url;
+        }
+      } else if (e.key === "Escape") {
+        setQuery("");
+        setResults([]);
+        setSelectedIndex(-1);
+        inputRef.current?.blur();
+      }
+    },
+    [results, selectedIndex],
+  );
+
+  // Click outside to close
+  useEffect(() => {
+    const handleClickOutside = (e: MouseEvent) => {
+      if (
+        resultsRef.current &&
+        !resultsRef.current.contains(e.target as Node) &&
+        inputRef.current &&
+        !inputRef.current.contains(e.target as Node)
+      ) {
+        setIsFocused(false);
+      }
+    };
+
+    document.addEventListener("mousedown", handleClickOutside);
+    return () => document.removeEventListener("mousedown", handleClickOutside);
+  }, []);
+
+  // Cleanup debounce on unmount
+  useEffect(() => {
+    return () => {
+      if (debounceRef.current) {
+        clearTimeout(debounceRef.current);
+      }
+    };
+  }, []);
+
+  const showResults = isFocused && query.trim().length > 0;
+
+  return (
+    <div className="relative" data-pagefind-ignore="">
+      {/* Search input */}
+      <div className="relative">
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          width="16"
+          height="16"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="2"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+          aria-hidden="true"
+          className="absolute left-3 top-1/2 -translate-y-1/2 text-text-muted pointer-events-none"
+        >
+          <circle cx="11" cy="11" r="8" />
+          <path d="m21 21-4.3-4.3" />
+        </svg>
+        <input
+          ref={inputRef}
+          type="search"
+          value={query}
+          onChange={(e) => handleInputChange(e.target.value)}
+          onFocus={() => {
+            setIsFocused(true);
+            loadPagefind();
+          }}
+          onKeyDown={handleKeyDown}
+          placeholder="Search docs…"
+          aria-label="Search documentation"
+          aria-expanded={showResults}
+          aria-controls="search-results"
+          aria-autocomplete="list"
+          aria-activedescendant={
+            selectedIndex >= 0
+              ? `search-result-${results[selectedIndex]?.id}`
+              : undefined
+          }
+          role="combobox"
+          className="w-full pl-9 pr-3 py-1.5 text-sm rounded-md border border-border bg-surface text-text placeholder-text-muted focus:outline-none focus:ring-2 focus:ring-primary transition-colors"
+        />
+      </div>
+
+      {/* Results dropdown */}
+      {showResults && (
+        <div
+          ref={resultsRef}
+          id="search-results"
+          role="listbox"
+          aria-label="Search results"
+          className="absolute top-full left-0 right-0 mt-1 max-h-80 overflow-y-auto rounded-lg border border-border bg-surface shadow-lg z-50"
+          style={{ minWidth: "320px" }}
+        >
+          {/* Unavailable state (dev server) */}
+          {isUnavailable && (
+            <div className="px-4 py-3 text-sm text-text-muted">
+              Search available after build
+            </div>
+          )}
+
+          {/* Loading state */}
+          {isLoading && !isUnavailable && (
+            <div className="px-4 py-3 text-sm text-text-muted">
+              Searching…
+            </div>
+          )}
+
+          {/* No results */}
+          {!isLoading && !isUnavailable && results.length === 0 && (
+            <div className="px-4 py-3 text-sm text-text-muted">
+              No results found
+            </div>
+          )}
+
+          {/* Results list */}
+          {!isUnavailable &&
+            results.map((result, index) => (
+              <a
+                key={result.id}
+                id={`search-result-${result.id}`}
+                href={result.url}
+                role="option"
+                aria-selected={index === selectedIndex}
+                className={`block px-4 py-3 text-sm no-underline border-b border-border last:border-b-0 transition-colors ${
+                  index === selectedIndex
+                    ? "bg-hover-bg"
+                    : "hover:bg-hover-bg"
+                }`}
+              >
+                {/* Page title */}
+                <div className="font-medium text-text mb-0.5">
+                  {result.meta?.title ?? "Untitled"}
+                </div>
+
+                {/* Sub-result heading (section) */}
+                {result.sub_results?.[0]?.title &&
+                  result.sub_results[0].title !== result.meta?.title && (
+                    <div className="text-xs text-text-muted mb-1">
+                      {result.sub_results[0].title}
+                    </div>
+                  )}
+
+                {/* Content snippet with highlighted terms.
+                    Pagefind generates sanitized HTML with <mark> tags for term highlighting.
+                    ACCEPTED RISK: trusting Pagefind's build-time sanitization. */}
+                <div
+                  className="text-xs text-text-muted line-clamp-2 [&_mark]:bg-primary/20 [&_mark]:text-text [&_mark]:rounded-sm [&_mark]:px-0.5"
+                  dangerouslySetInnerHTML={{
+                    __html:
+                      result.sub_results?.[0]?.excerpt ?? result.excerpt ?? "",
+                  }}
+                />
+              </a>
+            ))}
+        </div>
+      )}
+    </div>
+  );
+}