@eqtylab/docs 0.3.0 → 0.3.1

package/dist/runtime/chrome/GlobalSearch.tsx

@@ -1,422 +0,0 @@
-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

@@ -1,105 +0,0 @@
----
-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

@@ -1,35 +0,0 @@
----
-/**
- * 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

@@ -1,60 +0,0 @@
----
-/**
- * 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>