feat: add full text search support and async capability for command component

docs/css/custom.css

@@ -89,4 +89,26 @@
       @apply max-md:ml-10 min-h-8 flex items-center;
     }
   }
+}
+
+/* Search dialog - larger size for search results */
+#site-search > .command {
+  @apply sm:max-w-xl;
+}
+#site-search [role="menu"] {
+  @apply p-2 max-h-[500px];
+}
+
+/* Search results */
+.search-result {
+  @apply flex flex-col items-start gap-0.5 py-2 whitespace-normal overflow-visible text-wrap;
+}
+.search-result-title {
+  @apply font-medium text-foreground truncate;
+}
+.search-result-excerpt {
+  @apply text-sm text-muted-foreground line-clamp-2;
+}
+.search-result-excerpt mark {
+  @apply bg-yellow-200/60 dark:bg-yellow-500/30 text-inherit rounded-sm px-0.5;
 }

docs/src/_includes/layouts/base.njk

@@ -77,6 +77,7 @@
   <script src="/assets/js/sidebar.js" defer></script>
   <script src="/assets/js/tabs.js" defer></script>
   <script src="/assets/js/toast.js" defer></script>
+  <script src="/assets/js/pagefind-search.js" defer></script>
   {# HTMX #}
   <script src="https://unpkg.com/htmx.org@2.0.4"></script>
   {# Highlight.js #}

docs/src/_includes/layouts/layout.njk

@@ -5,11 +5,11 @@ layout: layouts/base.njk
 {% include "partials/sidebar.njk" %}
 
 <main id="content">
-  <header class="bg-background sticky inset-x-0 top-0 isolate flex shrink-0 items-center gap-2 border-b z-10">
+  <header class="bg-background sticky inset-x-0 top-0 isolate flex shrink-0 items-center gap-2 border-b z-10" data-pagefind-ignore>
     {% include "partials/header.njk" %}
   </header>
 
-  <div class="p-4 md:p-6 xl:p-12">
+  <div class="p-4 md:p-6 xl:p-12" data-pagefind-body>
     {{ content | safe }}
   </div>
 </main>

docs/src/_includes/partials/header.njk

@@ -1,3 +1,5 @@
+{% from "command.njk" import command_dialog %}
+
 <div class="flex h-14 w-full items-center gap-2 px-4">
   <button
     type="button"
@@ -6,10 +8,27 @@
     data-tooltip="Toggle sidebar"
     data-side="bottom"
     data-align="start"
-    class="btn-sm-icon-ghost mr-auto size-7 -ml-1.5"
+    class="btn-sm-icon-ghost size-7 -ml-1.5"
   >
     {% lucide "panel-left" %}
   </button>
+  <button
+    type="button"
+    onclick="document.getElementById('site-search').showModal(); document.getElementById('site-search-input').focus();"
+    class="btn-outline h-8 px-3 gap-2 text-muted-foreground font-normal mr-auto hidden sm:flex"
+  >
+    {% lucide "search", { "class": "size-4" } %}
+    <span>Search docs...</span>
+    <kbd class="kbd text-xs">⌘K</kbd>
+  </button>
+  <button
+    type="button"
+    onclick="document.getElementById('site-search').showModal(); document.getElementById('site-search-input').focus();"
+    aria-label="Search documentation"
+    class="btn-sm-icon-ghost size-7 sm:hidden"
+  >
+    {% lucide "search" %}
+  </button>
   <select
     class="select h-8 leading-none"
     id="theme-select"
@@ -61,4 +80,25 @@
   >
     {% lucide "github" %}
   </a>
-</div>
+</div>
+
+{{ command_dialog(
+  id="site-search",
+  placeholder="Search documentation...",
+  empty_text="No results found. Try a different search term.",
+  main_attrs={ "data-command-async": "true" },
+  input_attrs={ "id": "site-search-input" }
+) }}
+
+<script>
+  document.addEventListener('keydown', (e) => {
+    if ((e.metaKey || e.ctrlKey) && e.key === 'k') {
+      e.preventDefault();
+      const dialog = document.getElementById('site-search');
+      if (dialog) {
+        dialog.showModal();
+        document.getElementById('site-search-input')?.focus();
+      }
+    }
+  });
+</script>

docs/src/_includes/partials/sidebar.njk

@@ -134,6 +134,7 @@
   label="Sidebar navigation",
   header=header,
   footer=footer,
+  main_attrs={ "data-pagefind-ignore": "" },
   content_attrs={ "class": "scrollbar [&_[data-new-link]::after]:content-['New'] [&_[data-new-link]::after]:ml-auto [&_[data-new-link]::after]:text-xs [&_[data-new-link]::after]:font-medium [&_[data-new-link]::after]:bg-sidebar-primary [&_[data-new-link]::after]:text-sidebar-primary-foreground [&_[data-new-link]::after]:px-2 [&_[data-new-link]::after]:py-0.5 [&_[data-new-link]::after]:rounded-md" },
   menu=menu
 ) }}

docs/src/assets/js/pagefind-search.js

@@ -0,0 +1,92 @@
+// Pagefind search integration for docs site
+(() => {
+  let pagefindPromise = null;
+
+  const loadPagefind = () => {
+    if (!pagefindPromise) {
+      pagefindPromise = import('/pagefind/pagefind.js')
+        .then(async (pf) => {
+          await pf.init();
+          return pf;
+        })
+        .catch((error) => {
+          pagefindPromise = null;
+          console.error('Failed to load Pagefind:', error);
+          throw new Error('Search is not available');
+        });
+    }
+    return pagefindPromise;
+  };
+
+  // Sanitize HTML, allowing only <mark> tags for search highlighting
+  const sanitizeExcerpt = (html) => {
+    if (!html) return '';
+    const div = document.createElement('div');
+    div.innerHTML = html;
+    // Walk all nodes and only keep text and <mark> elements
+    const sanitize = (node) => {
+      const result = [];
+      node.childNodes.forEach((child) => {
+        if (child.nodeType === Node.TEXT_NODE) {
+          result.push(document.createTextNode(child.textContent));
+        } else if (child.nodeType === Node.ELEMENT_NODE && child.tagName === 'MARK') {
+          const mark = document.createElement('mark');
+          mark.textContent = child.textContent;
+          result.push(mark);
+        } else if (child.nodeType === Node.ELEMENT_NODE) {
+          result.push(...sanitize(child));
+        }
+      });
+      return result;
+    };
+    const container = document.createElement('span');
+    sanitize(div).forEach((n) => container.appendChild(n));
+    return container.innerHTML;
+  };
+
+  // Wait for basecoat to be available
+  const init = () => {
+    if (!window.basecoat?.commandAsync || !window.basecoat?.utils?.escapeHtml) {
+      setTimeout(init, 50);
+      return;
+    }
+
+    window.basecoat.commandAsync.register('site-search', {
+      minLength: 2,
+      debounce: 150,
+      maxResults: 8,
+      onSearch: async (query, signal) => {
+        const pf = await loadPagefind();
+        const search = await pf.search(query);
+
+        if (signal?.aborted) return [];
+
+        const results = await Promise.all(
+          search.results.slice(0, 8).map(r => r.data())
+        );
+
+        return results.map(r => ({
+          label: r.meta?.title || 'Untitled',
+          excerpt: r.excerpt || '',
+          url: r.url
+        }));
+      },
+      renderItem: (item, id) => {
+        const { escapeHtml } = window.basecoat.utils;
+        const safeExcerpt = sanitizeExcerpt(item.excerpt);
+        const safeLabel = escapeHtml(item.label);
+        const safeUrl = escapeHtml(item.url);
+        return `<a id="${id}" href="${safeUrl}" role="menuitem" class="search-result">
+          <span class="search-result-title">${safeLabel}</span>
+          <span class="search-result-excerpt">${safeExcerpt}</span>
+        </a>`;
+      }
+    });
+  };
+
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', init);
+  } else {
+    init();
+  }
+})();