@eqtylab/docs 0.3.1 → 0.3.2

package/dist/runtime/chrome/GlobalSearch.module.css

@@ -0,0 +1,26 @@
+@reference '../styles/theme.css';
+
+/*
+ * All that is left here are the two rules that fight another package's styling. Neither
+ * can move inline: one has to outrank Equality's own dialog class at equal specificity,
+ * and the other styles an element this component never renders.
+ */
+
+/* Class doubled to beat Equality's centring, which sits at the same specificity.
+ * Never override `transform` here: the entrance animation uses it. */
+.dialog.dialog {
+  @apply p-0;
+  top: 10vh;
+  translate: -50% 0;
+}
+
+/**
+ * Two assumptions nothing enforces: `packages/ui` still generates an overlay class containing
+ * `dialog-overlay`, and Radix still renders that overlay as the dialog's previous sibling. Either
+ * changes and the blur silently disappears. `:has` keeps it off every other dialog on the site.
+ */
+:global([class*='dialog-overlay']):has(+ .dialog) {
+  @apply bg-background/25;
+  -webkit-backdrop-filter: blur(18px);
+  backdrop-filter: blur(6px);
+}

package/dist/runtime/chrome/GlobalSearch.tsx

@@ -0,0 +1,422 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import {
+  Button,
+  Command,
+  CommandGroup,
+  CommandInput,
+  CommandItem,
+  CommandList,
+  Dialog,
+  DialogContainer,
+  DialogDescription,
+  DialogTitle,
+  EmptyTableState,
+  Icon,
+} from '@eqtylab/equality';
+
+import styles from './GlobalSearch.module.css';
+
+/** The header sits outside `Command`: moving the query there costs a hidden input and key forwarding. */
+
+/**
+ * Equality ships unlayered CSS, and an unlayered declaration beats anything in
+ * `@layer utilities` whatever its specificity. So any utility here that has to
+ * overrule a value Equality already sets on the same element needs `!` — the list's
+ * own `max-height: 300px` is one, and without the `!` the results pane silently
+ * shrinks. Utilities setting a property Equality leaves alone need nothing.
+ */
+
+/** Equality styles the hover but not cmdk's selected row. */
+const ITEM =
+  'cursor-pointer data-[selected=true]:bg-lilac-300/50 dark:data-[selected=true]:bg-lilac-600/50';
+
+/**
+ * Equality has no highlight token, so these name steps off the option scale directly. Not
+ * `brand-primary`: it is the selected row's colour, so a mark painted with it vanishes exactly
+ * when a row is selected. Each theme names its own step because `lilac-*` carries no dark values.
+ */
+const MARK = 'rounded bg-lilac-200 px-0.5 text-lilac-800 dark:bg-lilac-700 dark:text-lilac-200';
+
+/** The same treatment, for the <mark>s inside Pagefind's own excerpt markup. */
+const HIT_SUMMARY =
+  'text-text-secondary line-clamp-1 text-xs [&_mark]:rounded [&_mark]:bg-lilac-200 [&_mark]:px-0.5 [&_mark]:text-lilac-800 dark:[&_mark]:bg-lilac-700 dark:[&_mark]:text-lilac-200';
+
+const MAX_RESULTS = 20;
+const PAGE_SIZE = 5;
+const RECENT_KEY = 'eq-docs-recent-pages';
+const MAX_RECENT = 5;
+
+/** Hand-written: Pagefind is fetched at runtime, so no package supplies types. */
+interface PagefindDoc {
+  url: string;
+  excerpt: string;
+  /** Stamped by Prose.astro; `crumbs` is the `_group.yaml` trail, not the URL. */
+  meta?: { title?: string; crumbs?: string; description?: string };
+}
+
+interface PagefindRawResult {
+  id: string;
+  data: () => Promise<PagefindDoc>;
+}
+
+interface PagefindApi {
+  options: (opts: Record<string, unknown>) => Promise<void>;
+  init: () => Promise<void>;
+  debouncedSearch: (query: string) => Promise<{ results: PagefindRawResult[] } | null>;
+}
+
+interface Props {
+  suggested?: Array<{ label: string; href: string }>;
+}
+
+function toRecent(item: { label: string; href: string }): RecentPage {
+  return { url: item.href, title: item.label };
+}
+
+interface Hit {
+  id: string;
+  url: string;
+  title: string;
+  summary: string;
+  isExcerpt: boolean;
+  crumbs?: string;
+}
+
+const BASE = import.meta.env.BASE_URL;
+const BUNDLE_PATH = `${BASE.replace(/\/+$/, '')}/pagefind/`;
+
+let apiPromise: Promise<PagefindApi> | null = null;
+
+/** Drop `@vite-ignore` and the build fails: this path exists only after the build runs. */
+function loadPagefind(): Promise<PagefindApi> {
+  if (!apiPromise) {
+    apiPromise = import(/* @vite-ignore */ `${BUNDLE_PATH}pagefind.js`).then(async (module) => {
+      const api = module as unknown as PagefindApi;
+      // Without `baseUrl` every result href misses the base on a versioned deploy.
+      await api.options({ baseUrl: BASE, bundlePath: BUNDLE_PATH });
+      await api.init();
+      return api;
+    });
+  }
+  return apiPromise;
+}
+
+interface RecentPage {
+  url: string;
+  title: string;
+  crumbs?: string;
+}
+
+function getRecentPages(): RecentPage[] {
+  try {
+    const stored = localStorage.getItem(RECENT_KEY);
+    return stored ? (JSON.parse(stored) as RecentPage[]) : [];
+  } catch {
+    return [];
+  }
+}
+
+/** Reads the page it is on from the same attributes the index is built from. */
+function recordCurrentPage(): RecentPage[] {
+  const heading = document.querySelector('h1[data-pagefind-meta="title"]');
+  const article = document.querySelector('article[data-pagefind-body]');
+  const title = heading?.textContent?.trim();
+  if (!title) return getRecentPages();
+
+  const meta = article?.getAttribute('data-pagefind-meta') ?? '';
+  const crumbs = meta.startsWith('crumbs:') ? meta.slice('crumbs:'.length) : undefined;
+  const entry: RecentPage = { url: window.location.pathname, title, crumbs };
+
+  try {
+    const kept = getRecentPages().filter((page) => page.url !== entry.url);
+    const updated = [entry, ...kept].slice(0, MAX_RECENT);
+    localStorage.setItem(RECENT_KEY, JSON.stringify(updated));
+    return updated;
+  } catch {
+    return getRecentPages();
+  }
+}
+
+function isTypingTarget(): boolean {
+  const el = document.activeElement;
+  if (!el) return false;
+  const tag = el.tagName.toLowerCase();
+  return tag === 'input' || tag === 'textarea' || (el as HTMLElement).isContentEditable;
+}
+
+function HighlightMatch({ text, query }: { text: string; query: string }) {
+  if (!query) return <>{text}</>;
+  const escaped = query.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const parts = text.split(new RegExp(`(${escaped})`, 'gi'));
+  return (
+    <>
+      {parts.map((part, i) =>
+        part.toLowerCase() === query.toLowerCase() ? (
+          <mark key={i} className={MARK}>
+            {part}
+          </mark>
+        ) : (
+          part
+        )
+      )}
+    </>
+  );
+}
+
+export default function GlobalSearch({ suggested = [] }: Props) {
+  const [isOpen, setIsOpen] = useState(false);
+  const [query, setQuery] = useState('');
+  const [hits, setHits] = useState<Hit[]>([]);
+  const [status, setStatus] = useState<'idle' | 'loading' | 'ready' | 'error'>('idle');
+  const [expanded, setExpanded] = useState(false);
+  // Lazy initializer, safe only because this island is client:only and never prerenders.
+  const [recentPages] = useState<RecentPage[]>(recordCurrentPage);
+  const triggerRef = useRef<HTMLButtonElement>(null);
+  const requestId = useRef(0);
+
+  const open = useCallback(() => setIsOpen(true), []);
+
+  const close = useCallback(() => {
+    setIsOpen(false);
+    setQuery('');
+    setHits([]);
+    setStatus('idle');
+    setExpanded(false);
+    requestId.current++;
+    // DialogContainer preventDefaults onCloseAutoFocus; drop this and a keyboard user lands on <body>.
+    requestAnimationFrame(() => triggerRef.current?.focus());
+  }, [setExpanded]);
+
+  useEffect(() => {
+    function handler(event: KeyboardEvent) {
+      if ((event.metaKey || event.ctrlKey) && event.key === 'k') {
+        event.preventDefault();
+        if (isOpen) close();
+        else open();
+      }
+      // Escape is handled by Radix once the dialog is open.
+      if (event.key === '/' && !isOpen && !isTypingTarget()) {
+        event.preventDefault();
+        open();
+      }
+    }
+    window.addEventListener('keydown', handler);
+    return () => window.removeEventListener('keydown', handler);
+  }, [isOpen, open, close]);
+
+  const runSearch = useCallback(async (value: string) => {
+    const id = ++requestId.current;
+    if (!value.trim()) {
+      setHits([]);
+      setStatus('idle');
+      return;
+    }
+    setStatus('loading');
+    try {
+      const api = await loadPagefind();
+      const search = await api.debouncedSearch(value);
+      // Null means a newer keystroke superseded this call.
+      if (search === null || id !== requestId.current) return;
+      const docs = await Promise.all(search.results.slice(0, MAX_RESULTS).map((r) => r.data()));
+      if (id !== requestId.current) return;
+      setHits(
+        docs.map((doc, index) => ({
+          id: search.results[index].id,
+          url: doc.url,
+          title: doc.meta?.title ?? doc.url,
+          summary: doc.meta?.description ?? doc.excerpt,
+          isExcerpt: !doc.meta?.description,
+          crumbs: doc.meta?.crumbs,
+        }))
+      );
+      setStatus('ready');
+    } catch {
+      if (id !== requestId.current) return;
+      // No index before the first build; say so rather than showing nothing.
+      setStatus('error');
+      setHits([]);
+    }
+  }, []);
+
+  const visible = useMemo(() => (expanded ? hits : hits.slice(0, PAGE_SIZE)), [hits, expanded]);
+
+  function onQueryChange(value: string) {
+    setQuery(value);
+    setExpanded(false);
+    void runSearch(value);
+  }
+
+  function handleSelect(hit: Hit) {
+    setIsOpen(false);
+    // assign(), not `location.href =`: the React compiler lint rejects the assignment form.
+    window.location.assign(hit.url);
+  }
+
+  // Excluding the current page is what makes a first visit fall through to `suggested`.
+  const elsewhere = recentPages.filter((page) => page.url !== window.location.pathname);
+  const landing = elsewhere.length > 0 ? elsewhere : suggested.map(toRecent);
+  const landingHeading = elsewhere.length > 0 ? 'Recently viewed' : 'Start here';
+  const showLanding = !query && landing.length > 0;
+  const showEmpty = status !== 'error' && hits.length === 0 && !showLanding;
+
+  return (
+    <>
+      {/* A button, not an Input: Enter, Space and the accessible name come free. */}
+      <div role="search" className="w-full min-w-0 max-sm:w-auto">
+        {/* Tokens, not a copy of Input: a theme change carries, an Input restyle does not. */}
+        <button
+          ref={triggerRef}
+          type="button"
+          className="border-border bg-background text-text-secondary focus-ring flex h-10 w-full min-w-0 cursor-pointer items-center gap-2 rounded-md border p-2 text-sm max-sm:w-10 max-sm:justify-center max-sm:border-transparent max-sm:bg-transparent max-sm:p-0"
+          aria-haspopup="dialog"
+          aria-label="Search documentation"
+          onClick={open}
+        >
+          <Icon icon="Search" size="xs" />
+          {/* min-w-0 so a long label truncates instead of pushing the shortcut out. */}
+          <span className="min-w-0 flex-1 truncate text-left max-sm:sr-only">
+            Search documentation...
+          </span>
+          {/* No room for it on a narrow header, and the shortcut still works. */}
+          <kbd
+            aria-hidden="true"
+            className="bg-background-raised text-text-secondary pointer-events-none hidden rounded border px-1.5 py-0.5 font-mono text-xs sm:inline-block"
+          >
+            ⌘K
+          </kbd>
+        </button>
+      </div>
+
+      <Dialog open={isOpen} onOpenChange={(next: boolean) => (next ? open() : close())}>
+        <DialogContainer className={styles.dialog} aria-describedby={undefined}>
+          <div className="sr-only">
+            <DialogTitle>Search documentation</DialogTitle>
+            <DialogDescription>
+              Type to search every page. Arrow keys move, Enter opens, Escape closes.
+            </DialogDescription>
+          </div>
+
+          {/* Pagefind has already ranked these. Let cmdk filter and it discards the good ones. */}
+          <Command shouldFilter={false} className="w-full border-none">
+            <CommandInput
+              value={query}
+              onValueChange={onQueryChange}
+              placeholder="Search documentation..."
+            />
+
+            <CommandList className="max-h-[min(60vh,28rem)]! overflow-y-auto pb-2">
+              {status === 'error' && (
+                <div className="flex flex-col items-center gap-3 px-4 py-10">
+                  <EmptyTableState icon="SearchX" title="Search needs a build to run first" />
+                </div>
+              )}
+
+              {/* Not CommandEmpty: its filter count never updates while shouldFilter is false. */}
+              {showEmpty && (
+                <div className="flex flex-col items-center gap-3 px-4 py-10">
+                  <EmptyTableState
+                    icon={query ? 'SearchX' : 'Search'}
+                    title={
+                      query
+                        ? status === 'loading'
+                          ? 'Searching...'
+                          : `No results for "${query}"`
+                        : 'Start typing to search'
+                    }
+                  />
+                  {query && status !== 'loading' && (
+                    <Button variant="tertiary" size="sm" onClick={() => onQueryChange('')}>
+                      Clear search
+                    </Button>
+                  )}
+                </div>
+              )}
+
+              {showLanding && (
+                <CommandGroup className="px-1 [&>*+*]:mt-1" heading={landingHeading}>
+                  {landing.map((page) => (
+                    <CommandItem
+                      key={page.url}
+                      value={page.url}
+                      onSelect={() => window.location.assign(page.url)}
+                      className={ITEM}
+                    >
+                      <Icon icon="FileText" size="sm" />
+                      <span className="flex min-w-0 flex-1 flex-col gap-0.5">
+                        <span className="text-text-primary truncate text-sm font-medium">
+                          {page.title}
+                        </span>
+                        {page.crumbs && (
+                          // Location, not identity: separated from the pair above it.
+                          <span className="text-text-tertiary mt-1 truncate text-xs">
+                            {page.crumbs}
+                          </span>
+                        )}
+                      </span>
+                    </CommandItem>
+                  ))}
+                </CommandGroup>
+              )}
+
+              {/* Flat and in Pagefind's order: grouping by section reordered the ranking. */}
+              {hits.length > 0 && (
+                <CommandGroup className="px-1 [&>*+*]:mt-1" heading="Results">
+                  {visible.map((hit) => (
+                    <CommandItem
+                      key={hit.id}
+                      value={hit.id}
+                      data-search-id={hit.id}
+                      onSelect={() => handleSelect(hit)}
+                      className={ITEM}
+                    >
+                      <Icon icon="FileText" size="sm" />
+                      <span className="flex min-w-0 flex-1 flex-col gap-0.5">
+                        <span className="text-text-primary truncate text-sm font-medium">
+                          <HighlightMatch text={hit.title} query={query} />
+                        </span>
+                        {hit.isExcerpt ? (
+                          // Pagefind's markup, built from our own content.
+                          <span
+                            className={HIT_SUMMARY}
+                            dangerouslySetInnerHTML={{ __html: hit.summary }}
+                          />
+                        ) : (
+                          <span className={HIT_SUMMARY}>
+                            <HighlightMatch text={hit.summary} query={query} />
+                          </span>
+                        )}
+                        {hit.crumbs && (
+                          // Location, not identity: separated from the pair above it.
+                          <span className="text-text-tertiary mt-1 truncate text-xs">
+                            {hit.crumbs}
+                          </span>
+                        )}
+                      </span>
+                    </CommandItem>
+                  ))}
+
+                  {hits.length > visible.length && (
+                    <CommandItem
+                      value="view-more"
+                      onSelect={() => setExpanded(true)}
+                      className="text-brand-primary cursor-pointer justify-center text-sm"
+                    >
+                      View more results
+                    </CommandItem>
+                  )}
+                </CommandGroup>
+              )}
+            </CommandList>
+
+            {/* Outside the list: inside it the note scrolls out of sight. */}
+            {import.meta.env.DEV && status !== 'error' && (
+              <p className="text-text-secondary border-border border-t px-4 py-2 text-xs">
+                Dev mode: results come from the last build.
+              </p>
+            )}
+          </Command>
+        </DialogContainer>
+      </Dialog>
+    </>
+  );
+}

package/dist/runtime/chrome/Header.astro

@@ -0,0 +1,105 @@
+---
+import CONFIG from 'virtual:eqty-docs/config';
+import { withBase } from '@eqtylab/docs/paths';
+import { Icon } from '@eqtylab/equality';
+import GlobalSearch from './GlobalSearch.tsx';
+import LinkIcon from './LinkIcon.astro';
+import ThemeToggle from './ThemeToggle.tsx';
+
+interface Props {
+  /** First page of each top-level section. Shown before a reader has any history. */
+  suggested?: Array<{ label: string; href: string }>;
+  /** False when the page forwards a consumer-provided `search` slot. */
+  showSearch?: boolean;
+}
+
+const { showSearch = true, suggested = [] } = Astro.props;
+
+const paths = { base: import.meta.env.BASE_URL, pathPrefix: CONFIG.pathPrefix };
+const homeHref = withBase(CONFIG.pathPrefix ? `/${CONFIG.pathPrefix}/` : '/', {
+  base: import.meta.env.BASE_URL,
+});
+
+const navLink = 'eq-nav-control flex';
+---
+
+<header
+  class="bg-background-raised border-border-raised sticky top-0 z-50 h-[var(--eq-docs-header-height)] border-b"
+  data-eq-chrome
+  data-pagefind-ignore
+>
+  {
+    /* Below sm the search becomes an icon in the control cluster. `order` moves it
+       among these three children, so it only works while all three stay siblings. */
+  }
+  <div class="flex h-full items-center justify-between gap-4 px-4 max-sm:gap-2">
+    {/* min-h-10: the mark alone leaves this link under the 24px minimum tap target. */}
+    <a
+      class="text-text-primary flex min-h-10 shrink-0 items-center gap-3 no-underline"
+      href={homeHref}
+    >
+      {
+        /* Only the height is set. An <img> keeps its own aspect ratio, so any logo
+           fits. The mark ships white, so light mode inverts it; invert only works for
+           a one-colour logo, and a coloured one needs a second file. */
+      }
+      {
+        CONFIG.logo ? (
+          <img
+            class="light:invert block h-[22px] w-auto shrink-0"
+            src={withBase(CONFIG.logo.src, paths)}
+            alt={CONFIG.logo.alt}
+            height="24"
+          />
+        ) : (
+          <span class="whitespace-nowrap text-xl font-bold">{CONFIG.title}</span>
+        )
+      }
+      <span class="eq-display-gradient whitespace-nowrap text-xl font-bold forced-colors:text-inherit">
+        {CONFIG.title}
+      </span>
+    </a>
+
+    {/* min-w-0: without it the search pushes the theme control off a narrow header. */}
+    <div class="flex min-w-0 max-w-[28rem] flex-1 justify-center max-sm:order-2 max-sm:ml-auto max-sm:max-w-none max-sm:flex-none">
+      <slot name="search" />
+      {
+        /* client:only: with no JS there is no search, and client:load would leave a dead control. */
+        showSearch && CONFIG.search.provider !== 'none' && <GlobalSearch suggested={suggested} client:only="react" />
+      }
+    </div>
+
+    <div class="flex shrink-0 items-center gap-2 max-sm:order-3">
+      <slot name="versions" />
+      <div class="hidden items-center gap-1 lg:flex">
+        {CONFIG.header.links.map((link) => (
+          <a
+            class={navLink}
+            href={link.href}
+            target={link.external ? '_blank' : undefined}
+            rel={link.external ? 'noopener noreferrer' : undefined}
+          >
+            {link.icon && <LinkIcon icon={link.icon} />}
+            {/* Always visible. Hiding it shipped a nameless link, because `icon` is
+                optional and Lucide has no brand marks, so a GitHub link had nothing
+                left to render. */}
+            <span class="inline">{link.label}</span>
+          </a>
+        ))}
+      </div>
+      {CONFIG.header.showThemeToggle && <ThemeToggle client:load className="eq-nav-control" />}
+      {
+        /* popovertarget: the browser handles opening, closing, Escape, a click
+           outside, and returning focus here. */
+      }
+      <button
+        class="text-text-secondary hover:text-text-primary flex size-10 items-center justify-center rounded-md lg:hidden"
+        type="button"
+        popovertarget="eq-nav-drawer"
+        aria-label="Open navigation"
+      >
+        <Icon icon="Menu" size="sm" />
+      </button>
+    </div>
+  </div>
+</header>

package/dist/runtime/chrome/LinkIcon.astro

@@ -0,0 +1,35 @@
+---
+/**
+ * The icon on a configured header link: a Lucide name, or a path to an SVG.
+ *
+ * The SVG branch exists because Lucide ships no brand marks, so a GitHub link has no
+ * name it could use.
+ */
+import CONFIG from 'virtual:eqty-docs/config';
+import { withBase } from '@eqtylab/docs/paths';
+import { Icon } from '@eqtylab/equality';
+
+interface Props {
+  icon: string;
+}
+const { icon } = Astro.props;
+const isFile = icon.endsWith('.svg');
+const paths = { base: import.meta.env.BASE_URL, pathPrefix: CONFIG.pathPrefix };
+---
+
+{
+  /* size-4 matches Equality's Icon at `sm`, which the Lucide branch renders.
+     The file ships white, so light mode is the theme that inverts it. */
+}
+{
+  isFile ? (
+    <img
+      class="light:invert block size-4 shrink-0"
+      src={withBase(icon, paths)}
+      alt=""
+      aria-hidden="true"
+    />
+  ) : (
+    <Icon icon={icon} size="sm" />
+  )
+}

package/dist/runtime/chrome/NavDrawer.astro

@@ -0,0 +1,60 @@
+---
+/**
+ * Mobile navigation, below `lg` where the sidebar is hidden.
+ *
+ * The Popover API, not a custom element. With no JavaScript it opens and closes,
+ * shuts on Escape or a click outside, returns focus to the button, and paints above
+ * everything else. It also avoids `DialogContainer`'s focus-restoration bug.
+ */
+import CONFIG from 'virtual:eqty-docs/config';
+import type { NavNode } from '@eqtylab/docs/types';
+import { Icon } from '@eqtylab/equality';
+
+import LinkIcon from './LinkIcon.astro';
+import NavTree from './NavTree.astro';
+
+interface Props {
+  nodes: NavNode[];
+}
+const { nodes } = Astro.props;
+---
+
+{
+  /*
+    A popover is `display:none` until opened, so no `hidden` is needed, and above lg
+    the sidebar is back so it must never open. Resetting the UA's margin, border and
+    padding is required: a popover is not a plain box.
+
+    The `::backdrop` pair is the scrim. It comes with the popover, so there is no extra
+    element and no scrim selector reaching into another package.
+  */
+}
+<div
+  id="eq-nav-drawer"
+  popover
+  class="bg-background-raised border-border-raised fixed inset-y-0 left-0 m-0 h-full w-[min(20rem,84vw)] overflow-y-auto border-r p-4 lg:hidden [&::backdrop]:bg-background/50 [&::backdrop]:backdrop-blur-[3px]"
+  data-eq-chrome
+  data-pagefind-ignore
+>
+  <nav class="block" aria-label="Documentation">
+    {
+      CONFIG.header.links.map((link) => (
+        <a
+          class="text-text-secondary hover:text-text-primary mb-1 flex max-h-10 items-center gap-2 rounded-md px-2 py-1.5 text-sm font-medium no-underline"
+          href={link.href}
+          target={link.external ? '_blank' : undefined}
+          rel={link.external ? 'noopener noreferrer' : undefined}
+        >
+          {link.icon && <LinkIcon icon={link.icon} />}
+          <span>{link.label}</span>
+          {link.external && <Icon icon="ArrowUpRight" size="xs" />}
+        </a>
+      ))
+    }
+    <NavTree nodes={nodes} />
+  </nav>
+</div>
+
+<script>
+  import '@eqtylab/docs/scripts/eq-nav-drawer.ts';
+</script>