@dogsbay/docs-layout 0.2.0-beta.0

package/src/SearchDialog.astro

@@ -0,0 +1,529 @@
+---
+/**
+ * Search dialog wired to Pagefind.
+ *
+ * Loads `/{pagefindUrl}/pagefind.js` lazily on first open. No JavaScript ships
+ * to the page until the user actually opens search (Cmd+K / Ctrl+K / `/`),
+ * so the cost is paid only by users who search.
+ *
+ * Pagefind itself is generated by the post-build step
+ * `pagefind --site dist` declared in the project's package.json.
+ *
+ * Faceted filtering: when the indexed Pagefind data has filters
+ * (`<div data-pagefind-filter="...">` elements emitted by DocsLayout
+ * for tagged pages), the dialog grows a checkbox column on the left
+ * for narrowing results by tag / type / status / audience / category.
+ * Active filters mirror to URL params so a filtered search is
+ * shareable. When the corpus has no filters, the dialog renders the
+ * pre-facets layout — single column, byte-identical to the v1.
+ *
+ * Display labels for facet checkboxes flow from
+ * `siteConfig.taxonomyDisplay` — the same map that drives chip
+ * rendering, so "Concept: Accessibility" appears in both places.
+ *
+ * Styling: uses Dogsbay theme tokens (popover / accent / muted-foreground).
+ * Drop-in dark/light mode via the existing theme.
+ */
+import type { TaxonomyDisplay } from "@dogsbay/types";
+
+interface Props {
+  /**
+   * Path prefix where Pagefind's index lives. Default: "/pagefind/".
+   * Override when a site uses a non-root base path (e.g. "/docs/pagefind/").
+   */
+  pagefindUrl?: string;
+  /** Placeholder text for the search input */
+  placeholder?: string;
+  /**
+   * Per-taxonomy display config (`prefixes` + `labels`). When set,
+   * facet checkboxes render with human labels ("Concept:
+   * Accessibility") instead of raw slugs (`concept/a11y`). Fall
+   * back to slugs when undefined.
+   */
+  taxonomyDisplay?: Record<string, TaxonomyDisplay>;
+}
+
+const {
+  pagefindUrl = "/pagefind/",
+  placeholder = "Search docs...",
+  taxonomyDisplay,
+} = Astro.props;
+---
+
+<dialog
+  data-search-dialog
+  data-pagefind-url={pagefindUrl}
+  data-taxonomy-display={taxonomyDisplay ? JSON.stringify(taxonomyDisplay) : ""}
+  class="fixed left-1/2 top-[10vh] z-50 w-[calc(100vw-2rem)] max-w-4xl -translate-x-1/2 rounded-xl border border-border bg-popover p-0 text-popover-foreground shadow-2xl backdrop:bg-black/40 backdrop:backdrop-blur-sm"
+>
+  <form method="dialog" class="flex flex-col">
+    <div class="flex items-center gap-2 border-b border-border px-4">
+      <svg
+        xmlns="http://www.w3.org/2000/svg"
+        width="16"
+        height="16"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        stroke-width="2"
+        stroke-linecap="round"
+        stroke-linejoin="round"
+        class="size-4 shrink-0 text-muted-foreground"
+        aria-hidden="true"
+      >
+        <circle cx="11" cy="11" r="8" />
+        <path d="m21 21-4.3-4.3" />
+      </svg>
+
+      <input
+        type="search"
+        data-search-input
+        placeholder={placeholder}
+        autocomplete="off"
+        spellcheck="false"
+        class="flex h-12 w-full rounded-md bg-transparent text-sm outline-none placeholder:text-muted-foreground"
+        aria-label="Search documentation"
+      />
+
+      <kbd class="rounded border border-border px-1.5 py-0.5 font-mono text-xs text-muted-foreground">
+        Esc
+      </kbd>
+    </div>
+
+    {/*
+      Two-pane layout: facets column + results. The facets column
+      hides when no filters are present in the index (single-column
+      mode falls back to v1 behavior). Mobile: facets collapse into
+      a disclosure above the results.
+    */}
+    <div data-search-body class="flex max-h-[60vh]">
+      <aside
+        data-search-facets
+        class="hidden w-56 shrink-0 overflow-y-auto border-r border-border p-3 text-sm"
+        aria-label="Filter results"
+      >
+        {/* Populated at runtime once Pagefind reports filter list */}
+      </aside>
+
+      <div
+        data-search-results
+        class="flex-1 overflow-y-auto p-2 text-sm"
+        aria-live="polite"
+      >
+        <div data-search-empty class="px-3 py-8 text-center text-muted-foreground">
+          Start typing to search...
+        </div>
+      </div>
+    </div>
+  </form>
+</dialog>
+
+<button
+  type="button"
+  data-search-trigger
+  class="inline-flex h-9 items-center gap-2 rounded-md border border-border bg-background px-3 text-sm text-muted-foreground transition-colors hover:bg-accent hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+  aria-label="Open search"
+>
+  <svg
+    xmlns="http://www.w3.org/2000/svg"
+    width="14"
+    height="14"
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    stroke-width="2"
+    stroke-linecap="round"
+    stroke-linejoin="round"
+    aria-hidden="true"
+  >
+    <circle cx="11" cy="11" r="8" />
+    <path d="m21 21-4.3-4.3" />
+  </svg>
+  <span class="hidden sm:inline">Search</span>
+  <kbd class="hidden rounded border border-border px-1.5 py-0.5 font-mono text-[10px] sm:inline">
+    ⌘K
+  </kbd>
+</button>
+
+<script>
+  /**
+   * Pagefind search wiring.
+   *
+   * The pagefind module is loaded the first time the dialog opens. Subsequent
+   * opens reuse it. Nothing is loaded for users who never search.
+   */
+  import {
+    shapeFacets,
+    resolveFacetLabel,
+    resolveFacetTitle,
+    filterStateToUrlParams,
+    parseFiltersFromUrl,
+    filterStateToPagefindFilters,
+    toggleFilter,
+    countActiveFilters,
+    type FacetMap,
+    type FilterState,
+    type TaxonomyDisplayMap,
+  } from "./search-facets.js";
+
+  type PagefindResult = {
+    id: string;
+    data(): Promise<PagefindResultData>;
+  };
+  type PagefindResultData = {
+    url: string;
+    raw_url: string;
+    excerpt: string;
+    meta: { title?: string };
+    sub_results?: Array<{ title: string; url: string; excerpt: string }>;
+  };
+  type PagefindModule = {
+    search(
+      query: string,
+      options?: { filters?: Record<string, string[]> },
+    ): Promise<{ results: PagefindResult[] }>;
+    filters(): Promise<Record<string, Record<string, number>>>;
+  };
+
+  const dialog = document.querySelector<HTMLDialogElement>("[data-search-dialog]");
+  const trigger = document.querySelector<HTMLButtonElement>("[data-search-trigger]");
+  const input = dialog?.querySelector<HTMLInputElement>("[data-search-input]");
+  const resultsBox = dialog?.querySelector<HTMLDivElement>("[data-search-results]");
+  const emptyState = dialog?.querySelector<HTMLDivElement>("[data-search-empty]");
+  const facetsBox = dialog?.querySelector<HTMLElement>("[data-search-facets]");
+
+  if (!dialog || !trigger || !input || !resultsBox || !facetsBox) {
+    // Component not present on this page — bail.
+  } else {
+    let pagefind: PagefindModule | null = null;
+    let loadingPagefind: Promise<void> | null = null;
+    let activeQueryToken = 0;
+
+    // Active filter state. Updated by checkbox toggles, the
+    // URL-restore step on dialog open, and "Clear all".
+    let filters: FilterState = {};
+    let availableFacets: FacetMap = {};
+
+    // Display config baked into a data attribute by the Astro
+    // template — parsed lazily.
+    const taxonomyDisplay: TaxonomyDisplayMap = (() => {
+      try {
+        const raw = dialog!.dataset.taxonomyDisplay;
+        return raw ? (JSON.parse(raw) as TaxonomyDisplayMap) : {};
+      } catch {
+        return {};
+      }
+    })();
+
+    async function ensurePagefindLoaded() {
+      if (pagefind) return;
+      if (loadingPagefind) return loadingPagefind;
+      const url = (dialog!.dataset.pagefindUrl ?? "/pagefind/") + "pagefind.js";
+      loadingPagefind = (async () => {
+        try {
+          const mod = (await import(/* @vite-ignore */ url)) as PagefindModule;
+          pagefind = mod;
+          // Discover facets once, on first load. Pagefind builds
+          // this from the body-level data-pagefind-filter elements.
+          if (typeof mod.filters === "function") {
+            const raw = await mod.filters();
+            availableFacets = shapeFacets(raw);
+            renderFacets();
+          }
+        } catch (err) {
+          console.warn("[dogsbay] failed to load Pagefind:", err);
+        }
+      })();
+      return loadingPagefind;
+    }
+
+    function escapeHtml(s: string): string {
+      return s
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;");
+    }
+
+    /**
+     * Append a text fragment (`#:~:text=...`) so the browser highlights
+     * matched terms on arrival. If the URL already has a fragment (e.g.
+     * `#section-id` from Pagefind sub-results), append using `&text=` per
+     * the spec. Falls back to no fragment if the query is empty.
+     *
+     * Browser support: Chrome, Edge, Firefox 131+, Safari 18.2+.
+     * Where unsupported, the fragment is harmless — page just doesn't
+     * highlight.
+     */
+    function withTextFragment(url: string, query: string): string {
+      const trimmed = query.trim();
+      if (!trimmed) return url;
+      // Pagefind tokenizes the query; for highlighting we want whole-phrase
+      // matches plus individual terms. Browsers can take multiple text=
+      // fragments separated by `&`.
+      const terms = trimmed
+        .split(/\s+/)
+        .filter((t) => t.length >= 2)  // skip 1-char filler tokens
+        .slice(0, 5)                    // cap at 5 terms (URL length)
+        .map((t) => encodeURIComponent(t));
+      if (terms.length === 0) return url;
+      const fragment = "text=" + terms.join("&text=");
+      const sep = url.includes("#") ? "&" : "#:~:";
+      return url + sep + fragment;
+    }
+
+    function renderResults(results: Array<PagefindResultData>, query: string) {
+      if (!results.length) {
+        resultsBox!.innerHTML = `<div class="px-3 py-8 text-center text-muted-foreground">No results found.</div>`;
+        return;
+      }
+      const html = results
+        .map((r) => {
+          const title = escapeHtml(r.meta?.title ?? r.url);
+          // Page-level link with text fragment for top-of-page highlighting
+          const pageHref = withTextFragment(r.url, query);
+          // Sub-results: section-level matches with their own anchor URLs.
+          // We render them under the main result so users can jump straight
+          // to a specific heading. Each sub-result URL already has a fragment
+          // (e.g. /docs/foo/#section-id), so withTextFragment uses & instead
+          // of #:~: to combine the two.
+          const subHtml = (r.sub_results ?? [])
+            .slice(0, 3)
+            .map((sub) => `
+              <a href="${withTextFragment(sub.url, query)}" class="block rounded-md py-1.5 pl-6 pr-3 text-xs text-muted-foreground hover:bg-accent hover:text-foreground">
+                <div class="flex items-center gap-1.5">
+                  <svg xmlns="http://www.w3.org/2000/svg" width="10" height="10" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="shrink-0" aria-hidden="true">
+                    <polyline points="9 18 15 12 9 6"></polyline>
+                  </svg>
+                  <span class="truncate">${escapeHtml(sub.title)}</span>
+                </div>
+              </a>
+            `)
+            .join("");
+          return `
+            <div class="mb-1">
+              <a href="${pageHref}" class="block rounded-md p-3 hover:bg-accent">
+                <div class="font-medium">${title}</div>
+                <div class="mt-1 line-clamp-2 text-xs text-muted-foreground [&_mark]:rounded-sm [&_mark]:bg-primary/20 [&_mark]:px-0.5 [&_mark]:font-medium [&_mark]:text-foreground">${r.excerpt}</div>
+              </a>
+              ${subHtml}
+            </div>
+          `;
+        })
+        .join("");
+      resultsBox!.innerHTML = html;
+    }
+
+    /**
+     * Build the facets sidebar. Runs once after Pagefind discovers
+     * filters, then again whenever filter state changes (so checkbox
+     * `checked` reflects current selections). When the corpus has no
+     * filters, the sidebar stays hidden — single-column layout.
+     */
+    function renderFacets() {
+      const facetNames = Object.keys(availableFacets);
+      if (facetNames.length === 0) {
+        facetsBox!.classList.add("hidden");
+        return;
+      }
+      facetsBox!.classList.remove("hidden");
+
+      const activeCount = countActiveFilters(filters);
+      const clearAll = activeCount > 0
+        ? `<button type="button" data-clear-filters class="mb-3 w-full rounded-md border border-border px-2 py-1 text-xs text-muted-foreground transition-colors hover:bg-accent hover:text-foreground">Clear all (${activeCount})</button>`
+        : "";
+
+      const groups = facetNames
+        .map((name) => {
+          const entries = availableFacets[name];
+          const title = escapeHtml(resolveFacetTitle(name));
+          const items = entries
+            .map((entry) => {
+              const checked = (filters[name] ?? []).includes(entry.value);
+              const label = escapeHtml(
+                resolveFacetLabel(name, entry.value, taxonomyDisplay),
+              );
+              const id = `facet-${name}-${entry.value}`.replace(/[^a-z0-9-]/gi, "-");
+              return `
+                <li>
+                  <label for="${id}" class="flex cursor-pointer items-center gap-2 rounded-md px-2 py-1 hover:bg-accent">
+                    <input
+                      type="checkbox"
+                      id="${id}"
+                      data-facet-name="${escapeHtml(name)}"
+                      data-facet-value="${escapeHtml(entry.value)}"
+                      ${checked ? "checked" : ""}
+                      class="size-3.5 rounded border-border accent-primary"
+                    />
+                    <span class="flex-1 truncate">${label}</span>
+                    <span class="text-xs text-muted-foreground">${entry.count}</span>
+                  </label>
+                </li>
+              `;
+            })
+            .join("");
+          return `
+            <fieldset class="mb-3">
+              <legend class="mb-1 text-xs font-semibold uppercase tracking-wide text-muted-foreground">${title}</legend>
+              <ul class="space-y-0.5">${items}</ul>
+            </fieldset>
+          `;
+        })
+        .join("");
+
+      facetsBox!.innerHTML = clearAll + groups;
+    }
+
+    async function runSearch(query: string) {
+      const trimmed = query.trim();
+      const hasActiveFilters = countActiveFilters(filters) > 0;
+      if (!trimmed && !hasActiveFilters) {
+        if (emptyState) emptyState.style.display = "";
+        resultsBox!.innerHTML = "";
+        if (emptyState) resultsBox!.appendChild(emptyState);
+        return;
+      }
+      await ensurePagefindLoaded();
+      if (!pagefind) {
+        resultsBox!.innerHTML = `<div class="px-3 py-8 text-center text-muted-foreground">Search index unavailable. Run <code>pnpm build</code> to generate it.</div>`;
+        return;
+      }
+      const token = ++activeQueryToken;
+      // Filter-only searches (empty query, active filters): Pagefind
+      // accepts an empty / null query and returns the full filtered
+      // result set.
+      const search = await pagefind.search(trimmed || null as unknown as string, {
+        filters: filterStateToPagefindFilters(filters),
+      });
+      // Bail if a newer query has started while we were awaiting
+      if (token !== activeQueryToken) return;
+      const data = await Promise.all(search.results.slice(0, 8).map((r) => r.data()));
+      if (token !== activeQueryToken) return;
+      renderResults(data, trimmed);
+    }
+
+    /**
+     * Mirror current state to the URL via replaceState so reload /
+     * paste preserves it. Only mutates the URL while the dialog is
+     * open; closing the dialog leaves the state in place so users
+     * can copy the link AFTER searching.
+     */
+    function syncUrl() {
+      const params = filterStateToUrlParams(input!.value, filters);
+      const newUrl = params.toString().length > 0
+        ? `${window.location.pathname}?${params}${window.location.hash}`
+        : `${window.location.pathname}${window.location.hash}`;
+      window.history.replaceState({}, "", newUrl);
+    }
+
+    function openDialog() {
+      // Prefetch index in the background; user might be slow to type
+      ensurePagefindLoaded();
+      dialog!.showModal();
+
+      // Restore from URL params on open. Keeps the dialog roundtrippable
+      // — paste a saved URL, open search, see the prior query + filters.
+      const fromUrl = parseFiltersFromUrl(new URLSearchParams(window.location.search));
+      input!.value = fromUrl.query;
+      filters = fromUrl.filters;
+      renderFacets();
+
+      const hasInitial = input!.value.length > 0 || countActiveFilters(filters) > 0;
+      if (hasInitial) {
+        runSearch(input!.value);
+      } else {
+        if (emptyState) {
+          resultsBox!.innerHTML = "";
+          resultsBox!.appendChild(emptyState);
+          emptyState.style.display = "";
+        }
+      }
+      // Focus after the dialog is in the layout tree
+      requestAnimationFrame(() => input!.focus());
+    }
+
+    trigger.addEventListener("click", openDialog);
+
+    // Keyboard shortcut: Cmd+K / Ctrl+K / `/` (when not focused on a form field)
+    document.addEventListener("keydown", (e) => {
+      const target = e.target as HTMLElement;
+      const inField =
+        target.tagName === "INPUT" ||
+        target.tagName === "TEXTAREA" ||
+        target.isContentEditable;
+
+      if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === "k") {
+        e.preventDefault();
+        if (dialog!.open) {
+          dialog!.close();
+        } else {
+          openDialog();
+        }
+      } else if (e.key === "/" && !inField && !dialog!.open) {
+        e.preventDefault();
+        openDialog();
+      }
+    });
+
+    // Debounced query
+    let debounceTimer: number | undefined;
+    input.addEventListener("input", () => {
+      clearTimeout(debounceTimer);
+      debounceTimer = window.setTimeout(() => {
+        runSearch(input!.value);
+        syncUrl();
+      }, 120);
+    });
+
+    // Facet checkbox toggling — event delegation on the sidebar.
+    facetsBox.addEventListener("change", (e) => {
+      const target = e.target as HTMLInputElement;
+      if (target.tagName !== "INPUT" || target.type !== "checkbox") return;
+      const name = target.dataset.facetName;
+      const value = target.dataset.facetValue;
+      if (!name || !value) return;
+      filters = toggleFilter(filters, name, value);
+      renderFacets();
+      runSearch(input!.value);
+      syncUrl();
+    });
+
+    // "Clear all" button (rendered when filters are active).
+    facetsBox.addEventListener("click", (e) => {
+      const target = e.target as HTMLElement;
+      const clear = target.closest<HTMLButtonElement>("[data-clear-filters]");
+      if (!clear) return;
+      filters = {};
+      renderFacets();
+      runSearch(input!.value);
+      syncUrl();
+    });
+
+    // Click outside to close
+    dialog.addEventListener("click", (e) => {
+      if (e.target === dialog) dialog!.close();
+    });
+
+    // Close when a result is clicked. For cross-page links the browser
+    // unloads the dialog implicitly, but for same-page hash navigation
+    // (e.g. clicking a sub-result heading anchor on the current page) the
+    // dialog otherwise stays open with no visible state change.
+    // Don't preventDefault — let the browser handle the actual navigation.
+    resultsBox.addEventListener("click", (e) => {
+      const target = e.target as HTMLElement;
+      const link = target.closest("a");
+      if (link && resultsBox!.contains(link)) {
+        dialog!.close();
+      }
+    });
+  }
+</script>
+
+<style is:global>
+  /* Theme-matching highlight for text fragments arriving via #:~:text=...
+     The browser default is a flat yellow that clashes with custom themes;
+     this inherits from --primary so it adapts to light/dark. */
+  ::target-text {
+    background-color: oklch(from var(--primary) l c h / 0.3);
+    color: inherit;
+  }
+</style>

package/src/StatusBadge.astro

@@ -0,0 +1,79 @@
+---
+/**
+ * StatusBadge — surfaces page lifecycle state.
+ *
+ * Closed enum: `draft | preview | stable | deprecated`. Renders
+ * nothing for `stable` (the default state — no visual noise on
+ * shipped pages).
+ *
+ * `deprecated` and `draft` get strong colors; `preview` is muted.
+ *
+ * When `href` is set, the badge renders as a link (e.g. to a
+ * `/by-status/<value>/` browse page). `<DocsLayout>` computes the
+ * href from `siteConfig.taxonomyIndexPaths.status` when the user
+ * has declared `taxonomies.status:` in their config.
+ */
+type Status = "draft" | "preview" | "stable" | "deprecated";
+
+interface Props {
+  status?: Status;
+  /** Optional link target — renders the badge as `<a>` when set. */
+  href?: string;
+  class?: string;
+}
+
+const { status, href, class: className } = Astro.props;
+
+// Pre-compute the style + label strings in the script block. Doing
+// the lookup in JSX with a typed cast (e.g. `styles[status as Exclude<Status, "stable">]`)
+// trips esbuild — the `<` in the generic argument is parsed as JSX.
+function styleFor(s: Status): string {
+  switch (s) {
+    case "draft":
+      return "border-amber-500/40 bg-amber-500/15 text-amber-700 dark:text-amber-300";
+    case "preview":
+      return "border-blue-500/40 bg-blue-500/15 text-blue-700 dark:text-blue-300";
+    case "deprecated":
+      return "border-destructive/50 bg-destructive/15 text-destructive";
+    default:
+      return "";
+  }
+}
+
+function labelFor(s: Status): string {
+  switch (s) {
+    case "draft":
+      return "Draft";
+    case "preview":
+      return "Preview";
+    case "deprecated":
+      return "Deprecated";
+    default:
+      return "";
+  }
+}
+
+const visible = status !== undefined && status !== "stable";
+const style = status ? styleFor(status) : "";
+const label = status ? labelFor(status) : "";
+const baseClasses = "inline-flex items-center rounded-full border px-2 py-0.5 text-xs font-semibold uppercase tracking-wide";
+const linkClasses = "transition-colors hover:opacity-80";
+---
+
+{visible && href && (
+  <a
+    href={href}
+    class:list={[baseClasses, linkClasses, style, className]}
+    data-status={status}
+  >
+    {label}
+  </a>
+)}
+{visible && !href && (
+  <span
+    class:list={[baseClasses, style, className]}
+    data-status={status}
+  >
+    {label}
+  </span>
+)}