@eqtylab/docs 0.3.1 → 0.3.3

package/dist/runtime/components/CodeFence.astro

@@ -0,0 +1,38 @@
+---
+/**
+ * Fenced code through Equality's CodeBlock with no client React. eq-copy drives
+ * the copy button and eq-highlight starts the highlight pass CodeBlock's own
+ * useEffect never runs here. The highlighter owns language aliasing.
+ */
+import { CodeBlock } from '@eqtylab/equality';
+
+interface Props {
+  code: string;
+  lang?: string;
+  title?: string;
+}
+
+const { code, lang = 'text', title } = Astro.props;
+
+const language = lang.toLowerCase();
+---
+
+{/*
+  `block` is load-bearing: the fence is a custom element, which is inline by default.
+
+  The descendant rule undoes CodeBlock's max-h-64, which is wrong for a docs sample.
+  `!` is load-bearing too: Equality ships unlayered CSS, and an unlayered declaration
+  beats anything in `@layer utilities` whatever its specificity, so a plain utility
+  loses to `.code-block` and the sample silently goes back to scrolling at 16rem.
+*/}
+<eq-highlight
+  class="mb-4 block [&_[class*=code-block]]:max-h-none!"
+  data-eq-chrome
+  data-eq-copy={code}
+>
+  <CodeBlock code={code} language={language} title={title} />
+</eq-highlight>
+<script>
+  import '@eqtylab/docs/scripts/eq-copy.ts';
+  import '@eqtylab/docs/scripts/eq-highlight.ts';
+</script>

package/dist/runtime/components/CodeFenceBridge.astro

@@ -0,0 +1,20 @@
+---
+/**
+ * Renders a fence from the props `rehypeCodeFence` lifted onto the `<pre>`.
+ * Do not re-parse the slot: its HTML is escaped in dev and raw in build.
+ */
+import CodeFence from './CodeFence.astro';
+
+interface Props {
+  'data-code'?: string;
+  'data-language'?: string;
+  'data-title'?: string;
+}
+
+const props = Astro.props as Props;
+const code = props['data-code'] ?? '';
+const lang = props['data-language'] ?? 'text';
+const title = props['data-title'];
+---
+
+<CodeFence code={code} lang={lang} title={title} />

package/dist/runtime/components/Link.astro

@@ -0,0 +1,21 @@
+---
+import { isExternalHref } from '@eqtylab/docs/paths';
+
+interface Props {
+  href?: string;
+  [key: string]: unknown;
+}
+
+const { href = '', ...rest } = Astro.props;
+const external = isExternalHref(href);
+---
+
+<a
+  href={href}
+  class="text-inherit"
+  target={external ? '_blank' : undefined}
+  rel={external ? 'noopener noreferrer' : undefined}
+  {...rest}
+>
+  <slot />
+</a>

package/dist/runtime/components/TabItem.astro

@@ -0,0 +1,16 @@
+---
+/**
+ * One panel of a `<Tabs>` set. Emits nothing but a marked section: `Tabs.astro` recovers the
+ * label from it and re-emits the body, because Astro hands a framework component its children
+ * as opaque pre-rendered HTML and nothing inside React could read this `label`.
+ */
+interface Props {
+  label: string;
+  /** Lucide icon name. */
+  icon?: string;
+}
+
+const { label, icon } = Astro.props;
+---
+
+<section data-eq-tab-panel data-label={label} data-icon={icon}><slot /></section>

package/dist/runtime/components/TableBridge.astro

@@ -0,0 +1,18 @@
+---
+/** Bridges a markdown table to Equality's `Table`; the column count comes from `rehypeTableColumns`. */
+import { TableContainer } from '@eqtylab/equality';
+
+interface Props {
+  'data-column-count'?: string;
+}
+
+const count = Number(Astro.props['data-column-count'] ?? 0);
+
+// minmax(0, auto): without a zero minimum, one long unbroken cell blows the grid past its container.
+const columns = count > 0 ? `repeat(${count}, minmax(0, auto))` : undefined;
+---
+
+{/* Flow spacing only; every visual property comes from Equality's Table. */}
+<TableContainer columns={columns} border className="mb-4" data-eq-chrome>
+  <slot />
+</TableContainer>

package/dist/runtime/components/Tabs.astro

@@ -0,0 +1,121 @@
+---
+/**
+ * `<Tabs><TabItem label="…">` for MDX, on top of Equality's `Tabs`.
+ *
+ * Labels are recovered from the rendered slot because Astro hands a framework component its
+ * children as opaque pre-rendered HTML - nothing inside React can read a `<TabItem>`'s
+ * `label`. Matching is on `data-eq-tab-panel`, this package's own marker, never on
+ * `data-label` alone, so authored content cannot be mistaken for a panel.
+ */
+import GithubSlugger from 'github-slugger';
+
+import TabsBridge from './TabsBridge.tsx';
+
+interface Props {
+  /** Tab sets sharing a key switch together, and the reader's choice is remembered. */
+  syncKey?: string;
+}
+
+const { syncKey } = Astro.props;
+
+const slotHtml = await Astro.slots.render('default');
+
+if (/\bdata-eq-tabs\b/.test(slotHtml)) {
+  throw new Error('[@eqtylab/docs] Nested <Tabs> are not supported.');
+}
+
+interface Panel {
+  label: string;
+  icon?: string;
+  html: string;
+}
+
+const OPEN = /<section\b([^>]*)>/gi;
+const SECTION = /<(\/?)section\b[^>]*>/gi;
+
+const NAMED: Record<string, string> = {
+  amp: '&',
+  lt: '<',
+  gt: '>',
+  quot: '"',
+  apos: "'",
+};
+
+/**
+ * Attribute values arrive escaped, and a label like "BIOS & Host Config" is ordinary. One
+ * pass, not chained replaces: decoding named then numeric would turn a literal `&amp;#38;`
+ * into a bare `&`.
+ */
+function decode(value: string): string {
+  return value.replace(
+    /&(?:#(\d+)|#x([0-9a-f]+)|(amp|lt|gt|quot|apos));/gi,
+    (match: string, dec?: string, hex?: string, name?: string) => {
+      if (dec) return String.fromCodePoint(Number(dec));
+      if (hex) return String.fromCodePoint(parseInt(hex, 16));
+      return (name && NAMED[name.toLowerCase()]) || match;
+    }
+  );
+}
+
+function attribute(attrs: string, name: string): string | undefined {
+  const match = new RegExp(`\\b${name}="([^"]*)"`, 'i').exec(attrs);
+  return match ? decode(match[1] as string) : undefined;
+}
+
+/** Depth-counted, so a panel may contain sections of its own. */
+function closeAt(source: string, from: number): number {
+  SECTION.lastIndex = from;
+  let depth = 1;
+  let match: RegExpExecArray | null;
+  while ((match = SECTION.exec(source))) {
+    depth += match[1] ? -1 : 1;
+    if (depth === 0) return match.index;
+  }
+  return -1;
+}
+
+function readPanels(source: string): Panel[] {
+  const found: Panel[] = [];
+  OPEN.lastIndex = 0;
+  let match: RegExpExecArray | null;
+  while ((match = OPEN.exec(source))) {
+    const attrs = match[1] ?? '';
+    if (!/\bdata-eq-tab-panel\b/.test(attrs)) continue;
+    const bodyStart = OPEN.lastIndex;
+    const bodyEnd = closeAt(source, bodyStart);
+    if (bodyEnd < 0) break;
+    found.push({
+      label: attribute(attrs, 'data-label') ?? '',
+      icon: attribute(attrs, 'data-icon'),
+      html: source.slice(bodyStart, bodyEnd),
+    });
+    OPEN.lastIndex = bodyEnd;
+  }
+  return found;
+}
+
+const panels = readPanels(slotHtml);
+
+if (panels.length === 0) {
+  throw new Error('[@eqtylab/docs] <Tabs> needs at least one <TabItem label="…"> child.');
+}
+
+const slugger = new GithubSlugger();
+const items = panels.map((panel) => ({
+  label: panel.label,
+  value: slugger.slug(panel.label || 'tab'),
+  icon: panel.icon,
+  html: panel.html,
+}));
+
+// Equality requires an id, but `staticRender` never renders the motion layoutId that uses it.
+const id = `eq-tabs-${items[0]?.value}`;
+---
+
+<div class="mb-4" data-eq-tabs data-sync-key={syncKey}>
+  <TabsBridge id={id} items={items} />
+</div>
+
+<script>
+  import '@eqtylab/docs/scripts/eq-tabs.ts';
+</script>

package/dist/runtime/components/TabsBridge.tsx

@@ -0,0 +1,41 @@
+/**
+ * Equality's `Tabs`, server-rendered with no client React.
+ *
+ * This exists as a React component, rather than as markup in `Tabs.astro`, because the whole
+ * Radix tree has to render inside one root: its context does not survive an Astro component
+ * boundary, which is why `TableBridge` can get away with a plain `<slot />` and this cannot.
+ */
+import { Tabs } from '@eqtylab/equality';
+
+export interface TabsBridgeItem {
+  label: string;
+  value: string;
+  icon?: string;
+  /** Panel body, already rendered by `Astro.slots.render`. */
+  html: string;
+}
+
+interface Props {
+  id: string;
+  items: TabsBridgeItem[];
+}
+
+export default function TabsBridge({ id, items }: Props) {
+  return (
+    <Tabs
+      id={id}
+      /* Mounts every panel and puts the indicator in every trigger, so `eq-tabs.ts` can
+         switch tabs by flipping `data-state` with no React on the page. */
+      staticRender
+      items={items.map(({ label, value, icon, html }) => ({
+        label,
+        value,
+        icon,
+        /* `eq-tabs.ts` pairs synced sets by label; reading it off the trigger's text would
+           break as soon as a tab carries an icon or a suffix. */
+        triggerProps: { 'data-eq-tab-label': label },
+        content: <div dangerouslySetInnerHTML={{ __html: html }} />,
+      }))}
+    />
+  );
+}

package/dist/runtime/components/index.ts

@@ -0,0 +1,4 @@
+/** Public components for MDX authors. `.astro` only: a React component here pulls React into every page. */
+export { default as Link } from './Link.astro';
+export { default as TabItem } from './TabItem.astro';
+export { default as Tabs } from './Tabs.astro';

package/dist/runtime/layouts/DocsPage.astro

@@ -0,0 +1,50 @@
+---
+/** Header + sidebar | prose | TOC. The `doc` template. */
+import type { NavNode, TocNode } from '@eqtylab/docs/types';
+import CONFIG from 'virtual:eqty-docs/config';
+import DocsShell from './DocsShell.astro';
+import Header from '../chrome/Header.astro';
+import NavDrawer from '../chrome/NavDrawer.astro';
+import Sidebar from '../chrome/Sidebar.astro';
+import TableOfContents from '../chrome/TableOfContents.astro';
+
+interface Props {
+  title: string;
+  description?: string;
+  nav: NavNode[];
+  toc: TocNode[];
+  showToc?: boolean;
+  splash?: boolean;
+}
+
+const { title, description, nav, toc, showToc = true, splash = false } = Astro.props;
+
+// A section's own index page if it has one, else its first child. Never the sidebar repeated.
+const suggested = nav
+  .map((node) => ({ label: node.label, href: node.href ?? node.children?.[0]?.href }))
+  .filter((item): item is { label: string; href: string } => !!item.href)
+  .slice(0, 4);
+---
+
+<DocsShell title={title} description={description}>
+  {/* A prop, not slot fallback: Astro registers a named slot at compile time, so a forwarded
+      slot always counts as filled and the fallback never runs. */}
+  <Header showSearch={!Astro.slots.has('search')} suggested={suggested}>
+    <slot name="search" slot="search" />
+    <slot name="versions" slot="versions" />
+  </Header>
+  <NavDrawer nodes={nav} />
+  <div class="flex items-start">
+    {!splash && <Sidebar nodes={nav} />}
+    {/* 128px of runway, so a page stops deliberately rather than at its last line. */}
+    <main
+      class="mx-auto flex w-full min-w-0 max-w-[calc(var(--eq-docs-content-max)+var(--eq-docs-toc-width)+8rem)] items-start gap-12 px-6 pb-32 pt-10 data-[splash]:max-w-none xl:gap-16"
+      data-splash={splash ? '' : undefined}
+    >
+      <div class="min-w-0 flex-1 [&>.eq-prose]:max-w-[var(--eq-docs-content-max)]">
+        <slot />
+      </div>
+      {!splash && showToc && toc.length > 0 && <TableOfContents items={toc} />}
+    </main>
+  </div>
+</DocsShell>

package/dist/runtime/layouts/DocsShell.astro

@@ -0,0 +1,92 @@
+---
+/** The <html> document: head, theme bootstrap, and a slot for the page body. */
+import CONFIG from 'virtual:eqty-docs/config';
+import { withBase } from '@eqtylab/docs/paths';
+
+import '../styles/docs.css';
+
+interface Props {
+  title?: string;
+  description?: string;
+  /** Emit robots noindex. Set for every pinned version build. */
+  noIndex?: boolean;
+  /** Canonical URL, when it differs from the current page. */
+  canonical?: string;
+}
+
+const { title, description, noIndex, canonical } = Astro.props;
+
+const paths = {
+  base: import.meta.env.BASE_URL,
+  pathPrefix: CONFIG.pathPrefix,
+};
+
+const pageTitle = title && title !== CONFIG.title ? `${title} · ${CONFIG.title}` : CONFIG.title;
+const pageDescription = description ?? CONFIG.description;
+
+// Pinned version builds are noindex: latest today is not latest tomorrow.
+const robots = noIndex ?? !CONFIG.env.isLatest;
+
+/**
+ * Blocking inline theme bootstrap, so the attribute is set before first paint.
+ * Do not also call Equality's `initializeTheme`: it knows only light and dark
+ * and its stored value would override this. Never write storage here, or
+ * 'system' becomes a resolved value permanently. Constants must match
+ * `runtime/lib/theme.ts`.
+ */
+const themeBootstrap = `
+  (() => {
+    const KEY = 'eqty-docs-theme';
+    const EVENT = 'eqty-docs-theme-change';
+    const PERSIST = ${JSON.stringify(CONFIG.theme.persist)};
+    const query = window.matchMedia('(prefers-color-scheme: dark)');
+
+    const read = () => {
+      if (!PERSIST) return window.__eqtyDocsTheme ?? null;
+      try {
+        return window.localStorage.getItem(KEY);
+      } catch {
+        return null;
+      }
+    };
+
+    const apply = () => {
+      const stored = read();
+      const preference =
+        stored === 'dark' || stored === 'light' || stored === 'system' ? stored : 'system';
+      const resolved = preference === 'system' ? (query.matches ? 'dark' : 'light') : preference;
+      const root = document.documentElement;
+      root.setAttribute('data-equality-theme', resolved);
+      root.setAttribute('data-eq-theme-pref', preference);
+      // Native UI follows this, not the attribute above.
+      root.style.colorScheme = resolved;
+    };
+
+    apply();
+    query.addEventListener('change', apply);
+    window.addEventListener(EVENT, apply);
+    // The React subscription never touches the attribute, so other tabs repaint here.
+    window.addEventListener('storage', (event) => {
+      if (event.key === KEY) apply();
+    });
+  })();
+`;
+---
+
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>{pageTitle}</title>
+    {pageDescription && <meta name="description" content={pageDescription} />}
+    {robots && <meta name="robots" content="noindex, follow" />}
+    {canonical && <link rel="canonical" href={canonical} />}
+    <link rel="icon" href={withBase(CONFIG.favicon, paths)} />
+    <script is:inline set:html={themeBootstrap} />
+    <slot name="head" />
+  </head>
+  <body>
+    <slot />
+  </body>
+</html>

package/dist/runtime/lib/mdx-components.ts

@@ -0,0 +1,49 @@
+/**
+ * Route-level MDX component map. Entries here OVERRIDE a page's own
+ * `export const components`, so keep it small.
+ */
+import {
+  TableBody,
+  TableCaption,
+  TableCell,
+  TableFooter,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from '@eqtylab/equality';
+import CONFIG from 'virtual:eqty-docs/config';
+
+import AlertBridge from '../components/AlertBridge.astro';
+import CodeFenceBridge from '../components/CodeFenceBridge.astro';
+import Link from '../components/Link.astro';
+import TabItem from '../components/TabItem.astro';
+import TableBridge from '../components/TableBridge.astro';
+import Tabs from '../components/Tabs.astro';
+
+const base: Record<string, unknown> = {
+  a: Link,
+
+  // An explicit import of Alert from @eqtylab/equality still wins.
+  Alert: AlertBridge,
+
+  // Equality's Tabs, server-rendered. A file-level import still wins, as with Alert.
+  Tabs,
+  TabItem,
+
+  // All hook-free, so they render statically with no client directive.
+  table: TableBridge,
+  thead: TableHeader,
+  tbody: TableBody,
+  tfoot: TableFooter,
+  tr: TableRow,
+  th: TableHead,
+  td: TableCell,
+  caption: TableCaption,
+};
+
+// With 'shiki', Astro has already rendered the block.
+if (CONFIG.code?.highlighter === 'codeblock') {
+  base.pre = CodeFenceBridge;
+}
+
+export const mdxComponents = base;

package/dist/runtime/lib/nav-data.ts

@@ -0,0 +1,74 @@
+/** Bridges the content collections into the pure nav builder. Needs `astro:content`, so it lives in the runtime tree. */
+import { breadcrumbsFor, buildNavTree, buildTocTree, prevNextFor } from '@eqtylab/docs/nav';
+import type { GroupConfig } from '@eqtylab/docs/nav';
+import type { DocsNavEntry, NavNode } from '@eqtylab/docs/types';
+import { getCollection } from 'astro:content';
+import CONFIG from 'virtual:eqty-docs/config';
+
+export { buildTocTree, breadcrumbsFor, prevNextFor };
+
+/** No `versionPrefix`: the version already lives in `base`, and adding it here doubles the segment. */
+export function pathContext() {
+  return {
+    base: import.meta.env.BASE_URL,
+    pathPrefix: CONFIG.pathPrefix,
+  };
+}
+
+/** All docs entries, with drafts filtered out unless we're in `astro dev`. */
+export async function docsEntries() {
+  return getCollection('docs', ({ data }: { data: { draft?: boolean } }) =>
+    import.meta.env.DEV ? true : !data.draft
+  );
+}
+
+async function groupMap(): Promise<Map<string, GroupConfig>> {
+  const map = new Map<string, GroupConfig>();
+  try {
+    const groups = await getCollection('docsGroups');
+    for (const group of groups) {
+      map.set(group.id, group.data as GroupConfig);
+    }
+  } catch {
+    // docsGroups is optional; no _group.yaml means alphabetical ordering.
+  }
+  return map;
+}
+
+export async function docsNav(currentPath: string): Promise<NavNode[]> {
+  const [entries, groups] = await Promise.all([docsEntries(), groupMap()]);
+
+  const navEntries: DocsNavEntry[] = entries.map((entry) => ({
+    id: entry.id,
+    filePath: entry.filePath,
+    label: entry.data.navLabel ?? entry.data.title,
+    icon: entry.data.icon,
+    badge: entry.data.badge ?? deprecationBadge(entry.data.deprecated),
+    hidden: entry.data.hidden,
+    draft: entry.data.draft,
+  }));
+
+  return buildNavTree({
+    entries: navEntries,
+    groups,
+    currentPath,
+    paths: pathContext(),
+    defaultCollapsed: CONFIG.sidebar.collapsed,
+    defaultSort: CONFIG.sidebar.sort,
+    extra: (CONFIG.sidebar.extra ?? []) as NavNode[],
+    onWarn: warnOnce,
+  });
+}
+
+// The nav is rebuilt per page; report each config problem once per build.
+const warned = new Set<string>();
+function warnOnce(message: string) {
+  if (warned.has(message)) return;
+  warned.add(message);
+  console.warn(`[@eqtylab/docs] ${message}`);
+}
+
+function deprecationBadge(deprecated: unknown) {
+  if (!deprecated) return undefined;
+  return { text: 'Deprecated', variant: 'warning' as const };
+}

package/dist/runtime/lib/summary.ts

@@ -0,0 +1,57 @@
+/** Fallback page summary for pages with no `description` frontmatter. Build time only. */
+
+const MAX_LENGTH = 140;
+
+function isSkippable(line: string): boolean {
+  return (
+    line === '' ||
+    line.startsWith('#') ||
+    line.startsWith('import ') ||
+    line.startsWith('export ') ||
+    line.startsWith('<') ||
+    line.startsWith('|') ||
+    line.startsWith('>') ||
+    line.startsWith('- ') ||
+    line.startsWith('* ') ||
+    /^\d+\.\s/.test(line)
+  );
+}
+
+/** Enough markdown to make one sentence readable; anything richer is not a summary anyway. */
+function stripMarkdown(text: string): string {
+  return text
+    .replace(/!\[[^\]]*\]\([^)]*\)/g, '')
+    .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1')
+    .replace(/[`*_]/g, '')
+    .replace(/<[^>]+>/g, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function truncate(text: string): string {
+  if (text.length <= MAX_LENGTH) return text;
+  const cut = text.slice(0, MAX_LENGTH);
+  const lastSpace = cut.lastIndexOf(' ');
+  return `${cut.slice(0, lastSpace > 0 ? lastSpace : MAX_LENGTH).trimEnd()}…`;
+}
+
+/** First paragraph of prose. Frontmatter is already stripped by the content loader. */
+export function firstParagraph(body: string | undefined): string | undefined {
+  if (!body) return undefined;
+
+  let inFence = false;
+  for (const raw of body.split('\n')) {
+    const line = raw.trim();
+
+    if (line.startsWith('```')) {
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence || isSkippable(line)) continue;
+
+    const text = stripMarkdown(line);
+    // A line that was nothing but a link or a tag strips to nothing; keep looking.
+    if (text) return truncate(text);
+  }
+  return undefined;
+}