fix(showcase/shell-docs): search modal types, load error, cleanup, dedupe, split loading states

- Replace useState<any> for registryData with typed Registry | null
- Surface registry-load failures: .catch logs + inline "Search index failed to load" banner
- Track the setTimeout focus id and clear it in effect cleanup
- Let static search-index matches render immediately; show a '[loading...]' hint until registry.json resolves; show 'no results' only after loading completes
- Use a ref for selectedIndex so Enter never reads a stale value after reset-on-input
- Dedupe results by type+href before slicing to 12 (stable key becomes type-href)
- Route navigation through a shared helper that detects external URLs (http(s)://, //) and uses window.location.assign for them, router.push otherwise
- Warn once in dev when an integration has no description so it gets fixed upstream

Author: jpr5

showcase/shell-docs/src/components/search-modal.tsx

@@ -1,8 +1,9 @@
 "use client";
 
-import { useState, useEffect, useRef, useMemo } from "react";
+import { useState, useEffect, useRef, useMemo, useCallback } from "react";
 import { useRouter } from "next/navigation";
 import searchIndex from "@/data/search-index.json";
+import type { Registry } from "@/lib/registry";
 
 interface SearchResult {
   type: "integration" | "feature" | "demo" | "page" | "reference" | "ag-ui";
@@ -12,16 +13,58 @@ interface SearchResult {
   href: string;
 }
 
+function isExternalHref(href: string): boolean {
+  return /^(https?:)?\/\//i.test(href);
+}
+
+function dedupeResults(items: SearchResult[]): SearchResult[] {
+  const seen = new Set<string>();
+  const out: SearchResult[] = [];
+  for (const item of items) {
+    const key = `${item.type}::${item.href}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(item);
+  }
+  return out;
+}
+
 export function SearchModal({ onClose }: { onClose: () => void }) {
   const [query, setQuery] = useState("");
   const [selectedIndex, setSelectedIndex] = useState(0);
-  const [registryData, setRegistryData] = useState<any>(null);
+  const [registryData, setRegistryData] = useState<Registry | null>(null);
+  const [registryError, setRegistryError] = useState(false);
   const inputRef = useRef<HTMLInputElement>(null);
+  const selectedIndexRef = useRef(0);
   const router = useRouter();
 
+  // Keep a ref in sync with selectedIndex so the Enter handler never reads
+  // a stale closure value (reset-on-input + key-handler race).
   useEffect(() => {
-    setTimeout(() => inputRef.current?.focus(), 50);
-    import("@/data/registry.json").then((mod) => setRegistryData(mod.default));
+    selectedIndexRef.current = selectedIndex;
+  }, [selectedIndex]);
+
+  useEffect(() => {
+    const focusId = window.setTimeout(
+      () => inputRef.current?.focus(),
+      50,
+    );
+    let cancelled = false;
+    import("@/data/registry.json")
+      .then((mod) => {
+        if (!cancelled) setRegistryData(mod.default as Registry);
+      })
+      .catch((err) => {
+        if (!cancelled) {
+          // eslint-disable-next-line no-console
+          console.error("[search-modal] failed to load registry", err);
+          setRegistryError(true);
+        }
+      });
+    return () => {
+      cancelled = true;
+      window.clearTimeout(focusId);
+    };
   }, []);
 
   useEffect(() => {
@@ -33,11 +76,13 @@ export function SearchModal({ onClose }: { onClose: () => void }) {
   }, [onClose]);
 
   const results = useMemo(() => {
-    if (!query.trim() || !registryData) return [];
+    if (!query.trim()) return [];
 
     const q = query.toLowerCase();
     const items: SearchResult[] = [];
 
+    // Static search index is available immediately — search it even before
+    // the dynamic registry.json has resolved.
     // Auto-generated by: npx tsx showcase/scripts/generate-search-index.ts
     const pages = searchIndex as SearchResult[];
 
@@ -51,64 +96,95 @@ export function SearchModal({ onClose }: { onClose: () => void }) {
       }
     }
 
-    for (const i of registryData.integrations || []) {
-      if (
-        i.name.toLowerCase().includes(q) ||
-        i.description?.toLowerCase().includes(q)
-      ) {
-        items.push({
-          type: "integration",
-          title: i.name,
-          subtitle: (i.description || "").slice(0, 80),
-          href: `/integrations/${i.slug}`,
-        });
-      }
-      for (const d of i.demos || []) {
+    if (registryData) {
+      for (const i of registryData.integrations || []) {
         if (
-          d.name.toLowerCase().includes(q) ||
-          d.description?.toLowerCase().includes(q) ||
-          d.tags?.some((t: string) => t.toLowerCase().includes(q))
+          process.env.NODE_ENV !== "production" &&
+          (!i.description || i.description.trim() === "")
+        ) {
+          // eslint-disable-next-line no-console
+          console.warn(
+            `[search-modal] integration "${i.slug}" has no description — fix upstream in registry`,
+          );
+        }
+        if (
+          i.name.toLowerCase().includes(q) ||
+          i.description?.toLowerCase().includes(q)
         ) {
           items.push({
-            type: "demo",
-            title: d.name,
-            subtitle: `${i.name} · ${d.description}`,
-            href: `/integrations/${i.slug}/${d.id}`,
+            type: "integration",
+            title: i.name,
+            subtitle: (i.description || "").slice(0, 80),
+            href: `/integrations/${i.slug}`,
           });
         }
+        for (const d of i.demos || []) {
+          if (
+            d.name.toLowerCase().includes(q) ||
+            d.description?.toLowerCase().includes(q) ||
+            d.tags?.some((t: string) => t.toLowerCase().includes(q))
+          ) {
+            items.push({
+              type: "demo",
+              title: d.name,
+              subtitle: `${i.name} · ${d.description}`,
+              href: `/integrations/${i.slug}/${d.id}`,
+            });
+          }
+        }
       }
-    }
 
-    for (const f of registryData.feature_registry?.features || []) {
-      if (
-        f.name.toLowerCase().includes(q) ||
-        f.description?.toLowerCase().includes(q)
-      ) {
-        items.push({
-          type: "feature",
-          title: f.name,
-          subtitle: f.description,
-          href: "/matrix",
-        });
+      for (const f of registryData.feature_registry?.features || []) {
+        if (
+          f.name.toLowerCase().includes(q) ||
+          f.description?.toLowerCase().includes(q)
+        ) {
+          items.push({
+            type: "feature",
+            title: f.name,
+            subtitle: f.description,
+            href: "/matrix",
+          });
+        }
       }
     }
 
-    return items.slice(0, 12);
+    return dedupeResults(items).slice(0, 12);
   }, [query, registryData]);
 
-  function onInputKeyDown(e: React.KeyboardEvent) {
-    if (e.key === "ArrowDown") {
-      e.preventDefault();
-      setSelectedIndex((i) => Math.min(i + 1, results.length - 1));
-    } else if (e.key === "ArrowUp") {
-      e.preventDefault();
-      setSelectedIndex((i) => Math.max(i - 1, 0));
-    } else if (e.key === "Enter" && results[selectedIndex]) {
-      e.preventDefault();
-      router.push(results[selectedIndex].href);
+  const navigateTo = useCallback(
+    (href: string) => {
+      if (isExternalHref(href)) {
+        window.location.assign(href);
+      } else {
+        router.push(href);
+      }
       onClose();
-    }
-  }
+    },
+    [router, onClose],
+  );
+
+  const onInputKeyDown = useCallback(
+    (e: React.KeyboardEvent) => {
+      if (e.key === "ArrowDown") {
+        e.preventDefault();
+        setSelectedIndex((i) => Math.min(i + 1, results.length - 1));
+      } else if (e.key === "ArrowUp") {
+        e.preventDefault();
+        setSelectedIndex((i) => Math.max(i - 1, 0));
+      } else if (e.key === "Enter") {
+        const idx = selectedIndexRef.current;
+        const chosen = results[idx];
+        if (chosen) {
+          e.preventDefault();
+          navigateTo(chosen.href);
+        }
+      }
+    },
+    [results, navigateTo],
+  );
+
+  const registryLoading = !registryData && !registryError;
 
   return (
     <>
@@ -137,20 +213,29 @@ export function SearchModal({ onClose }: { onClose: () => void }) {
             </kbd>
           </div>
 
+          {registryError && (
+            <div className="px-5 py-2.5 text-[12px] text-[var(--text-muted)] border-b border-[var(--border)] bg-[var(--bg-elevated)]">
+              Search index failed to load. Try refresh.
+            </div>
+          )}
+
+          {query.trim() && registryLoading && (
+            <div className="px-5 py-2 text-[11px] text-[var(--text-faint)] border-b border-[var(--border)]">
+              [loading integrations & features…]
+            </div>
+          )}
+
           {results.length > 0 && (
             <div className="max-h-[320px] overflow-y-auto py-2">
               {results.map((r, idx) => (
                 <button
-                  key={`${r.href}-${idx}`}
+                  key={`${r.type}-${r.href}`}
                   className={`w-full text-left px-5 py-3 flex items-center gap-3 transition-colors ${
                     idx === selectedIndex
                       ? "bg-[var(--bg-elevated)]"
                       : "hover:bg-[var(--bg-hover)]"
                   }`}
-                  onClick={() => {
-                    router.push(r.href);
-                    onClose();
-                  }}
+                  onClick={() => navigateTo(r.href)}
                   onMouseEnter={() => setSelectedIndex(idx)}
                 >
                   <span className="text-[10px] font-mono text-[var(--text-faint)] uppercase w-14 shrink-0">
@@ -174,7 +259,7 @@ export function SearchModal({ onClose }: { onClose: () => void }) {
             </div>
           )}
 
-          {query.trim() && results.length === 0 && (
+          {query.trim() && results.length === 0 && !registryLoading && (
             <div className="px-5 py-8 text-center text-[13px] text-[var(--text-muted)]">
               No results for &ldquo;{query}&rdquo;
             </div>