@eqtylab/docs 0.3.1 → 0.3.2

package/dist/runtime/chrome/NavTree.astro

@@ -0,0 +1,112 @@
+---
+/**
+ * Recursive sidebar list. Groups are <details>, so they open with no script and
+ * nothing remounts on a page load. `eq-nav-group.ts` adds the animation.
+ *
+ * Every value here comes from Equality: the dropdown item's geometry and hover, and
+ * the Separator's colour for the rails.
+ */
+import type { NavNode } from '@eqtylab/docs/types';
+import { Badge, Icon } from '@eqtylab/equality';
+
+interface Props {
+  nodes: NavNode[];
+  depth?: number;
+}
+
+const { nodes, depth = 0 } = Astro.props;
+const NavTree = Astro.self;
+
+// 25px per level. A Tailwind default, not a token: Equality has no nesting value.
+const list =
+  depth === 0 ? 'space-y-1' : 'border-border ml-3 mt-1 space-y-0.5 border-l pl-3';
+
+// Equality's dropdown item, minus its `outline-hidden`: a link list needs keyboard
+// focus visible, so `focus-ring` stands in.
+const row =
+  'dropdown-item-hover focus-ring flex cursor-pointer select-none items-center gap-2 rounded-sm px-2 py-1.5 text-sm no-underline transition-colors';
+
+// Equality has no selected-row colour, so the current page borrows the hover one.
+// Search's selected row must keep matching it. The idle colour is left off a current
+// row rather than overridden: two unvariated colour utilities on one element resolve
+// by Tailwind's own order, not by the order they are written.
+const current =
+  'bg-lilac-300/50 text-lilac-700 dark:bg-lilac-600/50 dark:text-lilac-100 font-medium shadow-sm';
+---
+
+<ul class={list} data-depth={depth}>
+  {
+    nodes.map((node) => (
+      <li class="list-none">
+        {node.kind === 'group' && node.children?.length ? (
+          <details class="block" data-eq-nav-group open={node.open}>
+            {/* pointer-focus undoes Equality's hover firing on plain `:focus`, which
+                left a clicked header filled as if it were the current page. */}
+            <summary
+              class={`${row} text-text-primary justify-between [&::-webkit-details-marker]:hidden pointer-focus:bg-transparent! pointer-focus:text-text-primary! pointer-focus:shadow-none!`}
+            >
+              <span class="flex min-w-0 flex-1 items-center gap-2 truncate">
+                {node.icon && <Icon icon={node.icon} size="sm" />}
+                {node.href ? (
+                  <a
+                    class="text-inherit no-underline"
+                    href={node.href}
+                    aria-current={node.current ? 'page' : undefined}
+                  >
+                    {node.label}
+                  </a>
+                ) : (
+                  <span>{node.label}</span>
+                )}
+                {node.badge && (
+                  <Badge variant={node.badge.variant} size="sm" className="shrink-0">
+                    {node.badge.text}
+                  </Badge>
+                )}
+              </span>
+              {/* The direct-child selector is load-bearing: a plain `group-open`
+                  would also rotate a closed child's chevron inside an open parent. */}
+              <span
+                class="text-text-secondary shrink-0 transition-transform duration-200 [details[open]>summary_&]:rotate-90"
+                aria-hidden="true"
+              >
+                <Icon icon="ChevronRight" size="xs" />
+              </span>
+            </summary>
+            <NavTree nodes={node.children} depth={depth + 1} />
+          </details>
+        ) : (
+          <a
+            class={`${row} ${node.current ? current : 'text-text-secondary'}`}
+            href={node.href}
+            aria-current={node.current ? 'page' : undefined}
+            data-current={node.current ? '' : undefined}
+            target={node.external ? '_blank' : undefined}
+            rel={node.external ? 'noopener noreferrer' : undefined}
+            {...(node.attrs ?? {})}
+          >
+            {node.icon && <Icon icon={node.icon} size="sm" />}
+            <span class="min-w-0 flex-1 truncate">{node.label}</span>
+            {node.badge && (
+              <Badge variant={node.badge.variant} size="sm" className="shrink-0">
+                {node.badge.text}
+              </Badge>
+            )}
+            {node.external && (
+              <span class="text-text-secondary shrink-0 opacity-60" aria-hidden="true">
+                <Icon icon="ArrowUpRight" size="xs" />
+              </span>
+            )}
+          </a>
+        )}
+      </li>
+    ))
+  }
+</ul>
+
+{
+  /** Imported here, so one import covers both the sidebar and the drawer. */
+}
+<script>
+  import '@eqtylab/docs/scripts/eq-nav-group.ts';
+</script>

package/dist/runtime/chrome/NotFoundBody.tsx

@@ -0,0 +1,12 @@
+import { NotFound } from '@eqtylab/equality';
+
+/** `NotFound`'s default onHomeClick ignores `base`, so pass the href explicitly. */
+export default function NotFoundBody({ homeHref }: { homeHref: string }) {
+  return (
+    <NotFound
+      onHomeClick={() => {
+        window.location.href = homeHref;
+      }}
+    />
+  );
+}

package/dist/runtime/chrome/PageFooter.astro

@@ -0,0 +1,80 @@
+---
+/** The end of a page: where to go next, and how to fix what you just read. */
+import type { NavNode } from '@eqtylab/docs/types';
+import { Icon } from '@eqtylab/equality';
+
+interface Props {
+  prev?: NavNode;
+  next?: NavNode;
+  editHref?: string;
+  text?: string;
+}
+
+const { prev, next, editHref, text } = Astro.props;
+const hasPager = Boolean(prev?.href || next?.href);
+
+const page = 'group inline-flex flex-col gap-1 no-underline';
+const direction = 'text-text-tertiary inline-flex items-center gap-1.5 text-sm';
+const pageLabel = 'text-text-secondary group-hover:text-text-primary text-base font-medium';
+---
+
+{
+  /* 96px, a step above the 64px under the page header, so the footer sits further out
+     than anything inside the prose. Capped to the prose width so it does not run under
+     the table of contents. */
+}
+{
+  (hasPager || editHref || text) && (
+    <footer
+      class="mt-24 max-w-[var(--eq-docs-content-max)]"
+      data-eq-chrome
+      data-pagefind-ignore
+    >
+      {hasPager && (
+        <nav class="grid grid-cols-2 gap-4" aria-label="Previous and next page">
+          {/* Both cells always, so a page with only a next link keeps it on the right. */}
+          <div>
+            {prev?.href && (
+              <a class={page} href={prev.href} rel="prev">
+                <span class={direction}>
+                  <Icon icon="ArrowLeft" size="xs" />
+                  Previous
+                </span>
+                <span class={pageLabel}>{prev.label}</span>
+              </a>
+            )}
+          </div>
+          <div class="text-right">
+            {next?.href && (
+              <a class={page} href={next.href} rel="next">
+                <span class={`${direction} justify-end`}>
+                  Next
+                  <Icon icon="ArrowRight" size="xs" />
+                </span>
+                <span class={pageLabel}>{next.label}</span>
+              </a>
+            )}
+          </div>
+        </nav>
+      )}
+
+      {/* 32px: inside the footer's own group, so tighter than the 96px around it. */}
+      {(editHref || text) && (
+        <div class="text-text-tertiary mt-8 flex flex-wrap items-center justify-center gap-x-4 gap-y-1 text-sm">
+          {editHref && (
+            <a
+              class="hover:text-text-primary inline-flex items-center gap-1.5 text-inherit no-underline"
+              href={editHref}
+              target="_blank"
+              rel="noopener noreferrer"
+            >
+              <Icon icon="Pencil" size="xs" />
+              Edit this page
+            </a>
+          )}
+          {text && <p class="m-0">{text}</p>}
+        </div>
+      )}
+    </footer>
+  )
+}

package/dist/runtime/chrome/Prose.astro

@@ -0,0 +1,169 @@
+---
+/** Article wrapper. `data-pagefind-body` bounds the search index to content. */
+import { rewriteHtmlBase } from '@eqtylab/docs/internal/rehype-base-url';
+import { Icon } from '@eqtylab/equality';
+
+import AlertBridge from '../components/AlertBridge.astro';
+
+interface Props {
+  title: string;
+  description?: string;
+  deprecated?: boolean | { message?: string; replacedBy?: string };
+  /** URL of the page's markdown twin. Absent when `routing.markdownTwins` is off. */
+  markdownHref?: string;
+  /** The page's authored MDX, inlined for the copy action. */
+  source?: string;
+  /** Ancestor trail ending in this page, published to the search index. */
+  crumbs?: string;
+  /** Ancestors only, for the rendered breadcrumb. Deliberately excludes this page. */
+  trail?: Array<{ label: string; href?: string }>;
+  /** Stands in for `description` in the search index when a page has none. Not rendered. */
+  fallbackSummary?: string;
+}
+
+const { title, description, deprecated, markdownHref, source, crumbs, trail, fallbackSummary } =
+  Astro.props;
+
+const deprecation =
+  deprecated === true ? {} : deprecated && typeof deprecated === 'object' ? deprecated : null;
+
+// Authored frontmatter HTML bypasses rehype entirely, so base-prefix it here.
+const deprecationMessage = deprecation?.message
+  ? rewriteHtmlBase(deprecation.message, import.meta.env.BASE_URL)
+  : undefined;
+
+// Hand-rolled: every Button variant is coloured or filled, and this row is neither.
+const action =
+  'text-text-secondary hover:text-text-primary flex cursor-pointer items-center gap-1.5 rounded-md px-2.5 py-1.5 text-sm font-medium no-underline transition-colors';
+---
+
+<article
+  class="eq-prose"
+  data-eq-prose
+  data-pagefind-body
+  data-pagefind-meta={crumbs ? `crumbs:${crumbs}` : undefined}
+>
+  {
+    /* Ancestors only: ending the trail in a copy of the h1 repeats the page name in
+       two consecutive lines for a screen reader and competes with the only emphasis
+       on the page. */
+    trail && trail.length > 0 && (
+      <nav
+        class="text-text-tertiary mb-6 flex items-center text-sm"
+        data-eq-crumbs
+        data-eq-chrome
+        data-pagefind-ignore
+        aria-label="Breadcrumb"
+      >
+        {trail.map((node, index) => (
+          <Fragment>
+            {index > 0 && (
+              <span class="px-1.5" aria-hidden="true">
+                /
+              </span>
+            )}
+            {node.href ? (
+              <a
+                class="hover:text-text-secondary text-inherit no-underline hover:underline"
+                href={node.href}
+              >
+                {node.label}
+              </a>
+            ) : (
+              <span>{node.label}</span>
+            )}
+          </Fragment>
+        ))}
+      </nav>
+    )
+  }
+
+  {/* 64px, a step above the 48px between sections, so the header reads as further out. */}
+  <header
+    class="mb-16"
+    data-eq-chrome
+    data-pagefind-meta={fallbackSummary ? `description:${fallbackSummary}` : undefined}
+  >
+    {
+      /* `w-fit` is load-bearing. The gradient spans the box, so at full width a short
+         title sits entirely in the gradient's flat start. */
+    }
+    <h1
+      class="eq-display-gradient w-fit text-4xl font-bold forced-colors:text-text-primary"
+      data-pagefind-meta="title"
+    >
+      {title}
+    </h1>
+    {description && (
+      <p class="text-text-secondary mt-3 text-lg/7" data-pagefind-meta="description">
+        {description}
+      </p>
+    )}
+    {
+      /**
+       * Inside the header, so one margin governs the gap to the content whether or
+       * not this row renders. The closing rule is Equality's own SectionHeading pattern.
+       *
+       * `data-pagefind-ignore` is load-bearing. Without it every page matches "copy".
+       */
+      (source || markdownHref) && (
+        <div
+          class="border-border mt-4 flex items-center border-b pb-2"
+          data-eq-actions
+          data-eq-chrome
+          data-pagefind-ignore
+        >
+          {markdownHref && (
+            <a class={action} href={markdownHref} target="_blank">
+              <Icon icon="FileText" size="xs" />
+              View as Markdown
+            </a>
+          )}
+          {source && markdownHref && (
+            <span class="text-border-raised select-none" data-eq-action-sep aria-hidden="true">
+              |
+            </span>
+          )}
+          {source && (
+            /* Both labels render and swap on `data-copied` so the button does not resize. */
+            <button
+              type="button"
+              class={`group ${action}`}
+              data-eq-copy={source}
+              title="Copies the page source as Markdown"
+            >
+              <Icon icon="Copy" size="xs" />
+              <span class="inline-flex group-data-[copied]:hidden" data-eq-copy-idle>
+                Copy as Markdown
+              </span>
+              <span class="hidden group-data-[copied]:inline-flex" data-eq-copy-done>
+                Copied
+              </span>
+            </button>
+          )}
+        </div>
+      )
+    }
+  </header>
+
+  {
+    deprecation && (
+      <AlertBridge variant="warning" title="Deprecated">
+        {deprecationMessage ? (
+          <p set:html={deprecationMessage} />
+        ) : (
+          <p>This page documents a deprecated feature.</p>
+        )}
+      </AlertBridge>
+    )
+  }
+
+  <slot />
+</article>
+
+{
+  /** Imported here too so a page with no fenced code still drives the copy button. */
+}
+<script>
+  import '@eqtylab/docs/scripts/eq-copy.ts';
+</script>

package/dist/runtime/chrome/Sidebar.astro

@@ -0,0 +1,21 @@
+---
+import type { NavNode } from '@eqtylab/docs/types';
+
+import NavTree from './NavTree.astro';
+
+interface Props {
+  nodes: NavNode[];
+}
+const { nodes } = Astro.props;
+---
+
+{/* border-raised pairs with the raised fill, as Gov Studio does. */}
+<aside
+  class="bg-background-raised border-border-raised top-[var(--eq-docs-header-height)] hidden w-[var(--eq-docs-sidebar-width)] shrink-0 border-r lg:sticky lg:block lg:h-[calc(100vh-var(--eq-docs-header-height))] lg:overflow-y-auto"
+  data-eq-chrome
+  data-pagefind-ignore
+>
+  <nav class="px-4 py-6" aria-label="Documentation">
+    <NavTree nodes={nodes} />
+  </nav>
+</aside>

package/dist/runtime/chrome/TableOfContents.astro

@@ -0,0 +1,86 @@
+---
+/** On-this-page navigation. SSR'd so it works without JS; <eq-toc> only adds scroll-spy. */
+import type { TocNode } from '@eqtylab/docs/types';
+
+import TocList from './TocList.astro';
+
+interface Props {
+  items: TocNode[];
+  label?: string;
+}
+
+const { items, label = 'On this page' } = Astro.props;
+
+function flatten(nodes: TocNode[]): TocNode[] {
+  return nodes.flatMap((node) => [node, ...flatten(node.children)]);
+}
+const slugs = flatten(items).map((n) => n.slug);
+---
+
+{
+  /* The elbow reads `--eq-toc-indent` as its width too. Change one and the rail stops
+     meeting the level below. */
+}
+{
+  items.length > 0 && (
+    <eq-toc
+      class="[--eq-toc-indent:0.75rem] top-[calc(var(--eq-docs-header-height)+2rem)] hidden w-[var(--eq-docs-toc-width)] shrink-0 xl:sticky xl:block xl:max-h-[calc(100vh-var(--eq-docs-header-height))] xl:overflow-y-auto"
+      data-slugs={slugs.join(',')}
+      data-eq-chrome
+      data-pagefind-ignore
+    >
+      <nav aria-labelledby="eq-toc-heading">
+        <p class="text-text-primary mb-3 text-sm font-semibold" id="eq-toc-heading">
+          {label}
+        </p>
+        <div class="relative" data-eq-toc-rails>
+          {
+            /* The lit segment. `eq-toc.ts` measures its path from the rendered rows and
+               raises the opacity once it has. With no JavaScript it stays empty and the
+               rail is simply unlit.
+
+               Absolute with no z-index paints above the rows, so the segment covers the
+               grey border. */
+          }
+          <svg
+            class="pointer-events-none absolute inset-0 h-full w-full overflow-visible [&_path]:opacity-0 [&_path]:[transition:opacity_300ms_ease]"
+            aria-hidden="true"
+            fill="none"
+          >
+            {
+              /* Keyed to the path's box, so the colour depends on how far down the rail
+                 the segment has reached. Nothing recomputes as it moves.
+
+                 Each theme needs its own pair: `lilac-*` has no dark values, and one
+                 pair for both fails contrast. A flat lilac-600 measures 2.42:1 on dark,
+                 under the 3:1 minimum. */
+            }
+            <defs>
+              <linearGradient id="eq-toc-rail" x1="0" y1="0" x2="0" y2="1">
+                <stop
+                  class="[stop-color:var(--color-lilac-600)] dark:[stop-color:var(--color-lilac-300)]"
+                  offset="0%"
+                />
+                <stop
+                  class="[stop-color:var(--color-lilac-400)] dark:[stop-color:var(--color-lilac-500)]"
+                  offset="100%"
+                />
+              </linearGradient>
+            </defs>
+            <path
+              data-eq-toc-rail
+              stroke="url(#eq-toc-rail)"
+              stroke-width="2"
+              stroke-linecap="round"
+            />
+          </svg>
+          <TocList items={items} />
+        </div>
+      </nav>
+    </eq-toc>
+  )
+}
+
+<script>
+  import '@eqtylab/docs/scripts/eq-toc.ts';
+</script>

package/dist/runtime/chrome/ThemeToggle.tsx

@@ -0,0 +1,85 @@
+import { useSyncExternalStore } from 'react';
+import { Icon } from '@eqtylab/equality';
+
+import {
+  getThemePreference,
+  setThemePreference,
+  subscribeToThemePreference,
+  type ThemePreference,
+} from '../lib/theme.ts';
+
+/**
+ * One button that cycles System, Light, Dark.
+ *
+ * Do not reduce this to the current state, or to an `aria-label`. All three render and
+ * CSS picks one, which is what keeps the button correct before React hydrates.
+ */
+/** System first, so it is never more than one press away. */
+const CYCLE: ThemePreference[] = ['system', 'light', 'dark'];
+const LABEL: Record<ThemePreference, string> = { system: 'System', light: 'Light', dark: 'Dark' };
+const ICON: Record<ThemePreference, string> = { system: 'Monitor', light: 'Sun', dark: 'Moon' };
+
+/**
+ * Which state is showing. The root attribute picks one; with no JS it is absent, so
+ * System shows. These outrank the `invisible` default on their own, because an
+ * ancestor-qualified selector is the more specific of the two.
+ */
+const VISIBLE: Record<ThemePreference, string> = {
+  system: '[html:not([data-eq-theme-pref])_&]:visible [html[data-eq-theme-pref=system]_&]:visible',
+  light: '[html[data-eq-theme-pref=light]_&]:visible',
+  dark: '[html[data-eq-theme-pref=dark]_&]:visible',
+};
+
+const after = (preference: ThemePreference) =>
+  CYCLE[(CYCLE.indexOf(preference) + 1) % CYCLE.length];
+
+function usePreference() {
+  return useSyncExternalStore(
+    subscribeToThemePreference,
+    getThemePreference,
+    () => 'system' as const
+  );
+}
+
+interface Props {
+  /** The bar's control recipe, passed by Header so this cannot drift from the links. */
+  className?: string;
+}
+
+export default function ThemeToggle({ className }: Props) {
+  const preference = usePreference();
+
+  return (
+    /*
+     * All three states share one grid cell, so the button is always as wide as the
+     * widest and the bar never shifts. `visibility`, not `display`: a hidden state
+     * must still be sized. No room for a label below lg, and hiding it outright is
+     * safe because the sentence beside it is the accessible name.
+     */
+    <button
+      type="button"
+      className={[className, 'grid cursor-pointer max-lg:w-10 max-lg:justify-center max-lg:px-0']
+        .filter(Boolean)
+        .join(' ')}
+      onClick={() => setThemePreference(after(preference))}
+    >
+      {CYCLE.map((value) => (
+        <span
+          key={value}
+          className={`invisible col-start-1 row-start-1 flex items-center gap-2 ${VISIBLE[value]}`}
+          data-eq-pref={value}
+        >
+          <span aria-hidden="true" className="inline-flex">
+            <Icon icon={ICON[value]} size="xs" />
+          </span>
+          <span aria-hidden="true" className="text-sm max-lg:hidden">
+            {LABEL[value]}
+          </span>
+          <span className="sr-only">
+            Theme: {LABEL[value]}. Activate to switch to {LABEL[after(value)]}.
+          </span>
+        </span>
+      ))}
+    </button>
+  );
+}

package/dist/runtime/chrome/TocElbow.astro

@@ -0,0 +1,30 @@
+---
+/**
+ * One corner of the table-of-contents rail. `in` descends a level, `out` returns.
+ *
+ * An SVG, not a CSS corner. `border-radius` arrives horizontal; the rail has to arrive
+ * vertical to meet the child's border. The 1px offset centres it on that border.
+ *
+ * `vector-effect` is load-bearing: the viewBox is stretched to the indent width, and
+ * without it the stroke stretches too.
+ */
+interface Props {
+  direction: 'in' | 'out';
+}
+const { direction } = Astro.props;
+const d = direction === 'in' ? 'M 0 0 C 0 0.5, 1 0.5, 1 1' : 'M 1 0 C 1 0.5, 0 0.5, 0 1';
+---
+
+<svg
+  class="text-border-raised ml-px block h-2 w-[var(--eq-toc-indent)]"
+  data-eq-elbow={direction}
+  aria-hidden="true"
+  viewBox="0 0 1 1"
+  preserveAspectRatio="none"
+  fill="none"
+  stroke="currentColor"
+  stroke-width="2"
+  overflow="visible"
+>
+  <path d={d} vector-effect="non-scaling-stroke"></path>
+</svg>

package/dist/runtime/chrome/TocList.astro

@@ -0,0 +1,43 @@
+---
+/** Split out so recursion repeats only the list, not the <eq-toc>, <nav>, or heading id. */
+import type { TocNode } from '@eqtylab/docs/types';
+
+import TocElbow from './TocElbow.astro';
+
+interface Props {
+  items: TocNode[];
+}
+
+const { items } = Astro.props;
+const TocList = Astro.self;
+---
+
+{
+  /* No gap: each link's left border forms the rail, and a gap breaks it into dashes.
+     The nested-list indent is a descendant rule, so one class covers every level.
+     The border stays grey on the active row: the lit rail above is what marks it. */
+}
+<ol class="list-none p-0 [&_ol]:ml-[var(--eq-toc-indent)]">
+  {
+    items.map((item, index) => (
+      <li class="list-none">
+        <a
+          class="text-text-secondary hover:border-text-primary hover:text-text-primary border-border-raised data-[active]:text-text-primary block border-l-2 py-1.5 pl-3 text-sm no-underline transition-all duration-300"
+          href={`#${item.slug}`}
+          data-slug={item.slug}
+        >
+          {item.text}
+        </a>
+        {item.children.length > 0 && (
+          <Fragment>
+            <TocElbow direction="in" />
+            <TocList items={item.children} />
+            {/* Only when something follows at this level: otherwise the rail would
+                turn back out towards nothing. */}
+            {index < items.length - 1 && <TocElbow direction="out" />}
+          </Fragment>
+        )}
+      </li>
+    ))
+  }
+</ol>

package/dist/runtime/components/AlertBridge.astro

@@ -0,0 +1,16 @@
+---
+/**
+ * Equality's `Alert`, supplied to MDX as `Alert`. Keep `as="aside"`: the default
+ * `div` carries role="alert", which screen readers announce on page load.
+ */
+import { Alert } from '@eqtylab/equality';
+
+type Props = Record<string, unknown>;
+
+const { class: className, ...rest } = Astro.props as Props & { class?: string };
+---
+
+{/* Flow spacing only; every visual property comes from Alert. */}
+<Alert as="aside" {...rest} className={['mb-4', className].filter(Boolean).join(' ')} data-eq-chrome>
+  <slot />
+</Alert>