@eqtylab/docs 0.3.0

package/README.md

@@ -0,0 +1,201 @@
+# @eqtylab/docs
+
+An Astro documentation framework built on the [Equality](https://equality.eqtylab.io) design system.
+One package to build every EQTY docs site — component library, product docs, and API reference —
+with folder-driven navigation and versioned deploys.
+
+## Quick start
+
+```bash
+pnpm add @eqtylab/docs @eqtylab/equality astro react react-dom
+```
+
+```js
+// astro.config.mjs
+import docs from '@eqtylab/docs';
+import { defineConfig } from 'astro/config';
+
+export default defineConfig({
+  site: 'https://docs.example.com',
+  base: process.env.DOCS_BASE ?? '/',
+  integrations: [docs({ title: 'My Docs' })],
+});
+```
+
+```ts
+// src/content.config.ts  — required; Astro cannot inject collections
+import { docsCollections } from '@eqtylab/docs/loaders';
+
+export const collections = docsCollections();
+```
+
+Then write MDX under `src/content/docs/`. That's the whole setup: the integration injects the
+page routes, a Markdown twin per page, `/llms.txt`, and a 404. Search is built separately, at the
+end of `astro build`; see [Search needs a build](#search-needs-a-build).
+
+Content is **MDX-only**. Component overrides apply exclusively to MDX, so a `.md` page would
+render its tables, code fences and callouts differently from every other page. A `.md` file in
+the content tree fails the build rather than going silently missing — renaming it is usually the
+only change needed, since MDX is a superset of Markdown.
+
+## Navigation comes from folders
+
+Ordering lives in one optional `_group.yaml` per directory — there is deliberately **no
+`sidebar.order` frontmatter** to hand-maintain.
+
+```yaml
+# src/content/docs/getting-started/_group.yaml
+label: Getting Started
+order: [installation, usage, themes] # filesystem names, not titles
+collapsed: false
+```
+
+- Children listed in `order` come first, in that order.
+- Everything unlisted appends alphabetically by sidebar label (`sort: filename` or `manual` to change that).
+- `index.mdx` in a folder becomes that folder's own landing page.
+- A typo in `order` produces a build **warning naming the file and the token** rather than silently
+  reordering, and the schema is `.strict()` so an unknown key fails the build.
+
+## Two conventions worth knowing
+
+**No Tailwind utility classes in this package's markup.** All styling goes through `@apply` in a
+co-located `*.module.css` with a `@reference` header, mirroring `packages/ui`. This is not a style
+preference: Tailwind v4's source detection skips `node_modules`, so utilities written literally in
+shipped markup would silently produce nothing in a consumer's build. `@apply` has no such
+dependency. `pnpm run check:no-utilities` enforces it and runs as part of `build`.
+
+**Route-level MDX components override page-level ones.** `@astrojs/mdx` builds the map as
+`{ Fragment, ...fileComponents, ...props.components }`, so the route's `<Content components={…} />`
+wins over a page's own `export const components`. The route map is therefore kept to element
+overrides (`a`, `pre`); everything richer is an explicit import from `@eqtylab/docs/components`, so
+per-page overrides stay possible.
+
+## Code blocks
+
+Fenced code renders through Equality's `CodeBlock`, server-side, so docs match product surfaces with
+**no client React**. The highlighter paints through the CSS Custom Highlight API rather than by
+wrapping tokens in markup, so the server-rendered DOM is the final DOM, the palette resolves through
+the normal cascade, and a static render gets correct light _and_ dark colours for free.
+
+Two small scripts do what would otherwise need hydration: `runtime/scripts/eq-copy.ts` for the copy
+button, and `runtime/scripts/eq-highlight.ts` to start the highlight pass. Fence tags are passed
+through as authored — the highlighter owns language resolution, including its alias table (`ts`,
+`jsx`, `sh`, `yml` and the rest), and renders plain rather than guessing at a tag it does not know.
+
+Set `code: { highlighter: 'shiki' }` to use Astro's Shiki instead: wider language coverage, line
+highlighting and `meta` support, at the cost of a different look from the product.
+
+## Everything renders through Equality
+
+The framework contributes layout, navigation and prose typography. Everything that renders
+_content_ is an Equality component, server-rendered with no client React, so docs and
+product surfaces cannot drift:
+
+| Authored as     | Renders as                                                                              |
+| --------------- | --------------------------------------------------------------------------------------- |
+| Code fences     | `CodeBlock`                                                                             |
+| Markdown tables | `TableContainer` / `TableHeader` / `TableBody` / `TableRow` / `TableHead` / `TableCell` |
+| `<Alert>`       | `Alert`, as an `aside`                                                                  |
+| Links           | base-aware `a` override                                                                 |
+
+**Authors write Equality's own components, with no imports.** The route-level component map
+supplies named components as well as element overrides, so this works in any page with
+nothing at the top of the file — there is no docs-specific component vocabulary to learn:
+
+```mdx
+---
+title: My page
+---
+
+<Alert variant="warning" title="Heads up">
+  Body content, with real block elements.
+</Alert>
+```
+
+The only thing the framework adds is a default: `as="aside"`. Alert's default `div` carries
+`role="alert"`, an assertive live region — right for a message responding to something the
+user did, wrong for a standing note in a document. Importing `Alert` from
+`@eqtylab/equality` explicitly opts out and gives you the raw component, because a
+file-level import wins over the component map.
+
+One detail worth knowing: **tables need a column count.** `TableContainer` is a CSS grid
+whose parts all use `subgrid`, so it needs an explicit track list or the table collapses
+to one column. Markdown has no syntax for that, so `rehypeTableColumns` derives the count
+from the first row at build time.
+
+This is also why content is MDX-only — these overrides are the mechanism, and Astro's
+plain-Markdown pipeline has no component substitution at all.
+
+## Search needs a build
+
+Search is full-text, over the built HTML, via [Pagefind](https://pagefind.app). The integration
+runs it in `astro:build:done` and writes the index to `dist/pagefind/`.
+
+**One `astro build` makes search work in `astro dev` too.** Dev serves `dist/pagefind/` off disk,
+so results describe the last build; rebuild while dev runs and the next search picks it up. Until
+that first build the palette says search needs one.
+
+What gets indexed is set by the markup, not by config:
+
+| Attribute              | Where                            | Effect                                |
+| ---------------------- | -------------------------------- | ------------------------------------- |
+| `data-pagefind-body`   | the `<article>`                  | Bounds the index to page content      |
+| `data-pagefind-ignore` | header, sidebar, TOC, action row | Keeps chrome out of every result      |
+| `data-pagefind-meta`   | the `<h1>` and the `<article>`   | Carries `title` and the `group` label |
+
+The `group` value is the section's `label` from `_group.yaml`, so search headings and the sidebar
+cannot drift apart.
+
+The control itself is a command palette in the header, opened by click, `⌘K` or `/`. Fill the
+header's `search` slot to replace it, or set `search.provider: 'none'` to drop it entirely.
+
+## Versioned deploys
+
+`base` must be literal in Astro's config at build time, so it is threaded by environment variable:
+
+| Variable            | Meaning                                                                    |
+| ------------------- | -------------------------------------------------------------------------- |
+| `DOCS_BASE`         | Astro's `base` — `/`, `/v3.1/`, `/repo/v3.1/`                              |
+| `DOCS_VERSION_ROOT` | Directory holding all version directories (tracked separately from `base`) |
+| `DOCS_VERSION`      | This build's version id, e.g. `3.1`                                        |
+| `DOCS_IS_LATEST`    | `true` for the canonical build served at root                              |
+
+Every internal URL flows through `@eqtylab/docs/paths`, and authored markdown links are rewritten by
+a rehype plugin — Astro does not do this itself, so without it every root-relative link in content
+would 404 in a sub-path build.
+
+## Development
+
+```bash
+pnpm build    # guard + node bundle + runtime copy + declarations
+pnpm test     # nav ordering, prev/next, breadcrumbs, TOC
+```
+
+`src/*.ts` is bundled for Node (it is loaded when Astro reads your config). `src/runtime/**` ships
+as **source** and is compiled by the consumer's Astro — `.astro` files cannot be bundled. The copy is
+verbatim, which is what keeps dev source-linking byte-equivalent to the published package.
+
+### The dev surface
+
+`packages/demo` — the Equality docs site — is the first-class consumer, so the framework is
+developed against the same site that ships. Run `pnpm dev` from the repo root: this package's
+`dev` keeps `dist/runtime` in sync while the demo serves on port 4321.
+
+The sync is what makes edits to `src/runtime/**` hot-reload. Astro resolves injected route
+entrypoints through the real exports map, so `dist/runtime` — not `src/runtime` — is what Vite
+actually serves. Changes to `src/*.ts` are a different matter: they are bundled by tsup and read
+by Astro at config time, so they need `pnpm build:node` and a dev-server restart.
+
+To exercise a versioned sub-path build:
+
+```bash
+DOCS_BASE=/v0.0/ pnpm --filter demo build
+```
+
+Then confirm nothing 404s when `packages/demo/dist` is served at `/v0.0/`.
+
+### Fixtures
+
+`tests/fixtures/basic` is a separate, deliberately minimal consumer used for assertions — it
+contains a misspelled `_group.yaml` key on purpose, which is why it is kept apart from the demo
+rather than doubling as the dev surface.

package/dist/chunk-55J6XMHW.js

@@ -0,0 +1,3 @@
+
+//# sourceMappingURL=chunk-55J6XMHW.js.map
+//# sourceMappingURL=chunk-55J6XMHW.js.map

package/dist/chunk-55J6XMHW.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"chunk-55J6XMHW.js"}

package/dist/chunk-ATIOPYKE.js

@@ -0,0 +1,102 @@
+import { z } from 'astro/zod';
+
+// src/config.ts
+var headerLink = z.object({
+  label: z.string(),
+  href: z.string(),
+  /**
+   * A Lucide name like `BookOpen`, or a path to an SVG in `public/` like
+   * `/github.svg`. An SVG must be white: light mode inverts it.
+   */
+  icon: z.string().optional(),
+  external: z.boolean().optional()
+});
+var docsConfigSchema = z.object({
+  /** Site name, shown in the header and used as the `<title>` suffix. */
+  title: z.string(),
+  description: z.string().optional(),
+  /** Path to a favicon, relative to `public/`. Base is applied automatically. */
+  favicon: z.string().default("/favicon.svg"),
+  /**
+   * The header mark. Without one the header falls back to `title` as text. Either
+   * way a constant "Docs" label follows it, and `title` heads the sidebar.
+   */
+  logo: z.object({
+    src: z.string(),
+    /** Name the company: the brand link reads as this plus "Docs". */
+    alt: z.string().default("")
+  }).optional(),
+  /** Content directory, relative to `src/`. */
+  contentDir: z.string().default("content/docs"),
+  /** Mount docs under a sub-path, e.g. 'docs' for /docs/*. Empty means the site root. */
+  pathPrefix: z.string().default(""),
+  sidebar: z.object({
+    /** Default collapse state for groups with no explicit `collapsed`. */
+    collapsed: z.boolean().default(false),
+    /** Default append order for children absent from a group's `order`. */
+    sort: z.enum(["alpha", "filename", "manual"]).default("alpha"),
+    /** Extra top-level nodes, appended after folder-derived ones. */
+    extra: z.array(z.any()).default([])
+  }).prefault({}),
+  header: z.object({
+    links: z.array(headerLink).default([]),
+    showThemeToggle: z.boolean().default(true)
+  }).prefault({}),
+  footer: z.object({
+    /** Base URL for "Edit this page"; the content path is appended. */
+    editUrl: z.string().optional(),
+    showPrevNext: z.boolean().default(true),
+    text: z.string().optional()
+  }).prefault({}),
+  tableOfContents: z.union([
+    z.object({
+      minLevel: z.number().int().min(1).max(6).default(2),
+      maxLevel: z.number().int().min(1).max(6).default(3)
+    }),
+    z.literal(false)
+  ]).prefault({}),
+  code: z.object({
+    /** 'codeblock' renders fences through Equality's CodeBlock; 'shiki' uses Astro's Shiki. */
+    highlighter: z.enum(["codeblock", "shiki"]).default("codeblock"),
+    /** Shiki themes; only consulted when `highlighter` is 'shiki'. */
+    themes: z.object({ light: z.string(), dark: z.string() }).default({ light: "github-light", dark: "github-dark" }),
+    wrap: z.boolean().default(false),
+    langs: z.array(z.string()).default([])
+  }).prefault({}),
+  search: z.object({
+    /** 'pagefind' indexes the built HTML. Dev serves that index, so it needs one build. */
+    provider: z.enum(["pagefind", "none"]).default("pagefind")
+  }).prefault({}),
+  routing: z.object({
+    /** Inject the catch-all docs route. Disable to own routing entirely. */
+    injectPages: z.boolean().default(true),
+    /** Emit a `.md` twin per page plus `/llms.txt`. */
+    markdownTwins: z.boolean().default(true),
+    notFound: z.boolean().default(true)
+  }).prefault({}),
+  theme: z.object({
+    /** 'global' puts tokens on <html>; 'scoped' wraps in a ThemeProvider. */
+    mode: z.enum(["global", "scoped"]).default("global"),
+    /** Persist the reader's choice to localStorage. */
+    persist: z.boolean().default(true)
+  }).prefault({}),
+  /** Install @astrojs/mdx, @astrojs/react and Tailwind when absent. */
+  autoIntegrations: z.boolean().default(true),
+  /** Versioning. Left permissive here; the versioning workstream owns the shape. */
+  versions: z.any().optional(),
+  /** Generated-section plugins (OpenAPI reference, changelogs, ...). */
+  plugins: z.array(z.any()).default([])
+});
+function resolveConfig(user) {
+  const result = docsConfigSchema.safeParse(user);
+  if (!result.success) {
+    const issues = result.error.issues.map((i) => `  - ${i.path.join(".") || "(root)"}: ${i.message}`).join("\n");
+    throw new Error(`[@eqtylab/docs] Invalid configuration:
+${issues}`);
+  }
+  return result.data;
+}
+
+export { docsConfigSchema, resolveConfig };
+//# sourceMappingURL=chunk-ATIOPYKE.js.map
+//# sourceMappingURL=chunk-ATIOPYKE.js.map

package/dist/chunk-ATIOPYKE.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/config.ts"],"names":[],"mappings":"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","file":"chunk-ATIOPYKE.js","sourcesContent":["/** Integration options: the whole consumer-facing configuration surface. */\nimport { z } from 'astro/zod';\n\nconst headerLink = z.object({\n  label: z.string(),\n  href: z.string(),\n  /**\n   * A Lucide name like `BookOpen`, or a path to an SVG in `public/` like\n   * `/github.svg`. An SVG must be white: light mode inverts it.\n   */\n  icon: z.string().optional(),\n  external: z.boolean().optional(),\n});\n\nexport const docsConfigSchema = z.object({\n  /** Site name, shown in the header and used as the `<title>` suffix. */\n  title: z.string(),\n  description: z.string().optional(),\n  /** Path to a favicon, relative to `public/`. Base is applied automatically. */\n  favicon: z.string().default('/favicon.svg'),\n\n  /**\n   * The header mark. Without one the header falls back to `title` as text. Either\n   * way a constant \"Docs\" label follows it, and `title` heads the sidebar.\n   */\n  logo: z\n    .object({\n      src: z.string(),\n      /** Name the company: the brand link reads as this plus \"Docs\". */\n      alt: z.string().default(''),\n    })\n    .optional(),\n\n  /** Content directory, relative to `src/`. */\n  contentDir: z.string().default('content/docs'),\n\n  /** Mount docs under a sub-path, e.g. 'docs' for /docs/*. Empty means the site root. */\n  pathPrefix: z.string().default(''),\n\n  sidebar: z\n    .object({\n      /** Default collapse state for groups with no explicit `collapsed`. */\n      collapsed: z.boolean().default(false),\n      /** Default append order for children absent from a group's `order`. */\n      sort: z.enum(['alpha', 'filename', 'manual']).default('alpha'),\n      /** Extra top-level nodes, appended after folder-derived ones. */\n      extra: z.array(z.any()).default([]),\n    })\n    .prefault({}),\n\n  header: z\n    .object({\n      links: z.array(headerLink).default([]),\n      showThemeToggle: z.boolean().default(true),\n    })\n    .prefault({}),\n\n  footer: z\n    .object({\n      /** Base URL for \"Edit this page\"; the content path is appended. */\n      editUrl: z.string().optional(),\n      showPrevNext: z.boolean().default(true),\n      text: z.string().optional(),\n    })\n    .prefault({}),\n\n  tableOfContents: z\n    .union([\n      z.object({\n        minLevel: z.number().int().min(1).max(6).default(2),\n        maxLevel: z.number().int().min(1).max(6).default(3),\n      }),\n      z.literal(false),\n    ])\n    .prefault({}),\n\n  code: z\n    .object({\n      /** 'codeblock' renders fences through Equality's CodeBlock; 'shiki' uses Astro's Shiki. */\n      highlighter: z.enum(['codeblock', 'shiki']).default('codeblock'),\n      /** Shiki themes; only consulted when `highlighter` is 'shiki'. */\n      themes: z\n        .object({ light: z.string(), dark: z.string() })\n        .default({ light: 'github-light', dark: 'github-dark' }),\n      wrap: z.boolean().default(false),\n      langs: z.array(z.string()).default([]),\n    })\n    .prefault({}),\n\n  search: z\n    .object({\n      /** 'pagefind' indexes the built HTML. Dev serves that index, so it needs one build. */\n      provider: z.enum(['pagefind', 'none']).default('pagefind'),\n    })\n    .prefault({}),\n\n  routing: z\n    .object({\n      /** Inject the catch-all docs route. Disable to own routing entirely. */\n      injectPages: z.boolean().default(true),\n      /** Emit a `.md` twin per page plus `/llms.txt`. */\n      markdownTwins: z.boolean().default(true),\n      notFound: z.boolean().default(true),\n    })\n    .prefault({}),\n\n  theme: z\n    .object({\n      /** 'global' puts tokens on <html>; 'scoped' wraps in a ThemeProvider. */\n      mode: z.enum(['global', 'scoped']).default('global'),\n      /** Persist the reader's choice to localStorage. */\n      persist: z.boolean().default(true),\n    })\n    .prefault({}),\n\n  /** Install @astrojs/mdx, @astrojs/react and Tailwind when absent. */\n  autoIntegrations: z.boolean().default(true),\n\n  /** Versioning. Left permissive here; the versioning workstream owns the shape. */\n  versions: z.any().optional(),\n\n  /** Generated-section plugins (OpenAPI reference, changelogs, ...). */\n  plugins: z.array(z.any()).default([]),\n});\n\nexport type DocsUserConfig = z.input<typeof docsConfigSchema>;\nexport type DocsConfig = z.output<typeof docsConfigSchema>;\n\nexport function resolveConfig(user: DocsUserConfig): DocsConfig {\n  const result = docsConfigSchema.safeParse(user);\n  if (!result.success) {\n    const issues = result.error.issues\n      .map((i) => `  - ${i.path.join('.') || '(root)'}: ${i.message}`)\n      .join('\\n');\n    throw new Error(`[@eqtylab/docs] Invalid configuration:\\n${issues}`);\n  }\n  return result.data;\n}\n"]}

package/dist/chunk-GSSSQTEV.js

@@ -0,0 +1,51 @@
+import { visit } from 'unist-util-visit';
+
+// src/internal/rehype-base-url.ts
+var URL_ATTRS = ["href", "src", "poster"];
+var SRCSET_ATTRS = ["srcSet", "srcset"];
+function shouldRewrite(value, base) {
+  if (!value.startsWith("/")) return false;
+  if (value.startsWith("//")) return false;
+  if (base !== "/" && (value === base.replace(/\/$/, "") || value.startsWith(base))) return false;
+  return true;
+}
+function rewrite(value, base) {
+  return shouldRewrite(value, base) ? base.replace(/\/$/, "") + value : value;
+}
+function rewriteSrcset(value, base) {
+  return value.split(",").map((candidate) => {
+    const trimmed = candidate.trim();
+    if (!trimmed) return candidate;
+    const [url, ...descriptors] = trimmed.split(/\s+/);
+    return [rewrite(url, base), ...descriptors].join(" ");
+  }).join(", ");
+}
+function rehypeBaseUrl(options) {
+  const base = options.base || "/";
+  return function transformer(tree) {
+    if (base === "/") return;
+    visit(tree, "element", (node) => {
+      const props = node.properties;
+      if (!props) return;
+      for (const attr of URL_ATTRS) {
+        const value = props[attr];
+        if (typeof value === "string") props[attr] = rewrite(value, base);
+      }
+      for (const attr of SRCSET_ATTRS) {
+        const value = props[attr];
+        if (typeof value === "string") props[attr] = rewriteSrcset(value, base);
+      }
+    });
+  };
+}
+function rewriteHtmlBase(html, base) {
+  if (!base || base === "/") return html;
+  return html.replace(
+    /\b(href|src)=("|')(\/(?!\/)[^"']*)\2/g,
+    (_match, attr, quote, url) => `${attr}=${quote}${rewrite(url, base)}${quote}`
+  );
+}
+
+export { rehypeBaseUrl, rewriteHtmlBase };
+//# sourceMappingURL=chunk-GSSSQTEV.js.map
+//# sourceMappingURL=chunk-GSSSQTEV.js.map

package/dist/chunk-GSSSQTEV.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/internal/rehype-base-url.ts"],"names":[],"mappings":";;;AAQA,IAAM,SAAA,GAAY,CAAC,MAAA,EAAQ,KAAA,EAAO,QAAQ,CAAA;AAC1C,IAAM,YAAA,GAAe,CAAC,QAAA,EAAU,QAAQ,CAAA;AAExC,SAAS,aAAA,CAAc,OAAe,IAAA,EAAuB;AAC3D,EAAA,IAAI,CAAC,KAAA,CAAM,UAAA,CAAW,GAAG,GAAG,OAAO,KAAA;AACnC,EAAA,IAAI,KAAA,CAAM,UAAA,CAAW,IAAI,CAAA,EAAG,OAAO,KAAA;AACnC,EAAA,IAAI,IAAA,KAAS,GAAA,KAAQ,KAAA,KAAU,IAAA,CAAK,OAAA,CAAQ,KAAA,EAAO,EAAE,CAAA,IAAK,KAAA,CAAM,UAAA,CAAW,IAAI,CAAA,CAAA,EAAI,OAAO,KAAA;AAC1F,EAAA,OAAO,IAAA;AACT;AAEA,SAAS,OAAA,CAAQ,OAAe,IAAA,EAAsB;AACpD,EAAA,OAAO,aAAA,CAAc,OAAO,IAAI,CAAA,GAAI,KAAK,OAAA,CAAQ,KAAA,EAAO,EAAE,CAAA,GAAI,KAAA,GAAQ,KAAA;AACxE;AAEA,SAAS,aAAA,CAAc,OAAe,IAAA,EAAsB;AAC1D,EAAA,OAAO,MACJ,KAAA,CAAM,GAAG,CAAA,CACT,GAAA,CAAI,CAAC,SAAA,KAAc;AAClB,IAAA,MAAM,OAAA,GAAU,UAAU,IAAA,EAAK;AAC/B,IAAA,IAAI,CAAC,SAAS,OAAO,SAAA;AACrB,IAAA,MAAM,CAAC,GAAA,EAAK,GAAG,WAAW,CAAA,GAAI,OAAA,CAAQ,MAAM,KAAK,CAAA;AACjD,IAAA,OAAO,CAAC,QAAQ,GAAA,EAAe,IAAI,GAAG,GAAG,WAAW,CAAA,CAAE,IAAA,CAAK,GAAG,CAAA;AAAA,EAChE,CAAC,CAAA,CACA,IAAA,CAAK,IAAI,CAAA;AACd;AAEO,SAAS,cAAc,OAAA,EAA2B;AACvD,EAAA,MAAM,IAAA,GAAO,QAAQ,IAAA,IAAQ,GAAA;AAE7B,EAAA,OAAO,SAAS,YAAY,IAAA,EAAe;AACzC,IAAA,IAAI,SAAS,GAAA,EAAK;AAElB,IAAA,KAAA,CAAM,IAAA,EAAe,SAAA,EAAW,CAAC,IAAA,KAAsB;AACrD,MAAA,MAAM,QAAQ,IAAA,CAAK,UAAA;AACnB,MAAA,IAAI,CAAC,KAAA,EAAO;AAEZ,MAAA,KAAA,MAAW,QAAQ,SAAA,EAAW;AAC5B,QAAA,MAAM,KAAA,GAAQ,MAAM,IAAI,CAAA;AACxB,QAAA,IAAI,OAAO,UAAU,QAAA,EAAU,KAAA,CAAM,IAAI,CAAA,GAAI,OAAA,CAAQ,OAAO,IAAI,CAAA;AAAA,MAClE;AAEA,MAAA,KAAA,MAAW,QAAQ,YAAA,EAAc;AAC/B,QAAA,MAAM,KAAA,GAAQ,MAAM,IAAI,CAAA;AACxB,QAAA,IAAI,OAAO,UAAU,QAAA,EAAU,KAAA,CAAM,IAAI,CAAA,GAAI,aAAA,CAAc,OAAO,IAAI,CAAA;AAAA,MACxE;AAAA,IACF,CAAC,CAAA;AAAA,EACH,CAAA;AACF;AAGO,SAAS,eAAA,CAAgB,MAAc,IAAA,EAAsB;AAClE,EAAA,IAAI,CAAC,IAAA,IAAQ,IAAA,KAAS,GAAA,EAAK,OAAO,IAAA;AAClC,EAAA,OAAO,IAAA,CAAK,OAAA;AAAA,IACV,uCAAA;AAAA,IACA,CAAC,MAAA,EAAQ,IAAA,EAAc,KAAA,EAAe,QACpC,CAAA,EAAG,IAAI,CAAA,CAAA,EAAI,KAAK,GAAG,OAAA,CAAQ,GAAA,EAAK,IAAI,CAAC,GAAG,KAAK,CAAA;AAAA,GACjD;AACF","file":"chunk-GSSSQTEV.js","sourcesContent":["/** Prefixes root-relative URLs with Astro's `base`, which Astro does not do for authored markdown links. */\nimport { visit } from 'unist-util-visit';\n\ninterface ElementNode {\n  type: string;\n  properties?: Record<string, unknown>;\n}\n\nconst URL_ATTRS = ['href', 'src', 'poster'];\nconst SRCSET_ATTRS = ['srcSet', 'srcset'];\n\nfunction shouldRewrite(value: string, base: string): boolean {\n  if (!value.startsWith('/')) return false;\n  if (value.startsWith('//')) return false; // protocol-relative\n  if (base !== '/' && (value === base.replace(/\\/$/, '') || value.startsWith(base))) return false;\n  return true;\n}\n\nfunction rewrite(value: string, base: string): string {\n  return shouldRewrite(value, base) ? base.replace(/\\/$/, '') + value : value;\n}\n\nfunction rewriteSrcset(value: string, base: string): string {\n  return value\n    .split(',')\n    .map((candidate) => {\n      const trimmed = candidate.trim();\n      if (!trimmed) return candidate;\n      const [url, ...descriptors] = trimmed.split(/\\s+/);\n      return [rewrite(url as string, base), ...descriptors].join(' ');\n    })\n    .join(', ');\n}\n\nexport function rehypeBaseUrl(options: { base: string }) {\n  const base = options.base || '/';\n\n  return function transformer(tree: unknown) {\n    if (base === '/') return;\n\n    visit(tree as never, 'element', (node: ElementNode) => {\n      const props = node.properties;\n      if (!props) return;\n\n      for (const attr of URL_ATTRS) {\n        const value = props[attr];\n        if (typeof value === 'string') props[attr] = rewrite(value, base);\n      }\n\n      for (const attr of SRCSET_ATTRS) {\n        const value = props[attr];\n        if (typeof value === 'string') props[attr] = rewriteSrcset(value, base);\n      }\n    });\n  };\n}\n\n/** Same, for authored HTML strings in frontmatter. */\nexport function rewriteHtmlBase(html: string, base: string): string {\n  if (!base || base === '/') return html;\n  return html.replace(\n    /\\b(href|src)=(\"|')(\\/(?!\\/)[^\"']*)\\2/g,\n    (_match, attr: string, quote: string, url: string) =>\n      `${attr}=${quote}${rewrite(url, base)}${quote}`\n  );\n}\n"]}

package/dist/chunk-IWKZQ4CW.js

@@ -0,0 +1,68 @@
+import { z } from 'astro/zod';
+
+// src/schema.ts
+var badgeSchema = () => z.object({
+  text: z.string(),
+  variant: z.enum(["primary", "secondary", "neutral", "success", "warning", "danger"]).default("neutral")
+});
+var deprecatedSchema = () => z.union([
+  z.boolean(),
+  z.object({
+    message: z.string().optional(),
+    replacedBy: z.string().optional()
+  })
+]);
+var tocSchema = () => z.object({
+  minLevel: z.number().int().min(1).max(6).default(2),
+  maxLevel: z.number().int().min(1).max(6).default(3)
+});
+function docsSchema() {
+  return z.object({
+    title: z.string(),
+    description: z.string().optional(),
+    /** Overrides `title` in the sidebar only. */
+    navLabel: z.string().optional(),
+    /** Lucide icon name. */
+    icon: z.string().optional(),
+    badge: badgeSchema().optional(),
+    /** Omit from the sidebar. The page still builds and is still reachable. */
+    hidden: z.boolean().default(false),
+    /** Excluded from builds entirely, but visible in `astro dev`. */
+    draft: z.boolean().default(false),
+    deprecated: deprecatedSchema().default(false),
+    /** 'doc' gets sidebar + TOC; 'splash' is full-bleed with neither. */
+    template: z.enum(["doc", "splash"]).default("doc"),
+    tableOfContents: z.union([tocSchema(), z.literal(false)]).optional(),
+    /** Opt out of the markdown twin and the search index for this page. */
+    noIndex: z.boolean().default(false),
+    prev: z.union([z.boolean(), z.string()]).optional(),
+    next: z.union([z.boolean(), z.string()]).optional()
+  });
+}
+var groupLinkSchema = () => z.object({
+  label: z.string(),
+  href: z.string(),
+  /** Inferred from the href when omitted. */
+  external: z.boolean().optional(),
+  icon: z.string().optional(),
+  badge: badgeSchema().optional(),
+  attrs: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).default({})
+});
+function groupSchema() {
+  return z.object({
+    label: z.string().optional(),
+    icon: z.string().optional(),
+    /** Immediate-child filesystem names (not titles), in display order. */
+    order: z.array(z.string()).default([]),
+    /** Children absent from `order`: alpha by label (default), by filename, or manual (dropped from the sidebar). */
+    sort: z.enum(["alpha", "filename", "manual"]).optional(),
+    collapsed: z.boolean().optional(),
+    hidden: z.boolean().default(false),
+    badge: badgeSchema().optional(),
+    links: z.array(groupLinkSchema()).default([])
+  }).strict();
+}
+
+export { badgeSchema, docsSchema, groupLinkSchema, groupSchema };
+//# sourceMappingURL=chunk-IWKZQ4CW.js.map
+//# sourceMappingURL=chunk-IWKZQ4CW.js.map

package/dist/chunk-IWKZQ4CW.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/schema.ts"],"names":[],"mappings":"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","file":"chunk-IWKZQ4CW.js","sourcesContent":["/** `z` must come from `astro/zod`: a different zod instance breaks Astro's collection validation. */\nimport { z } from 'astro/zod';\n\nexport const badgeSchema = () =>\n  z.object({\n    text: z.string(),\n    variant: z\n      .enum(['primary', 'secondary', 'neutral', 'success', 'warning', 'danger'])\n      .default('neutral'),\n  });\n\nconst deprecatedSchema = () =>\n  z.union([\n    z.boolean(),\n    z.object({\n      message: z.string().optional(),\n      replacedBy: z.string().optional(),\n    }),\n  ]);\n\nconst tocSchema = () =>\n  z.object({\n    minLevel: z.number().int().min(1).max(6).default(2),\n    maxLevel: z.number().int().min(1).max(6).default(3),\n  });\n\n/** Page frontmatter. Ordering lives in `_group.yaml`, not here. */\nexport function docsSchema() {\n  return z.object({\n    title: z.string(),\n    description: z.string().optional(),\n    /** Overrides `title` in the sidebar only. */\n    navLabel: z.string().optional(),\n    /** Lucide icon name. */\n    icon: z.string().optional(),\n    badge: badgeSchema().optional(),\n    /** Omit from the sidebar. The page still builds and is still reachable. */\n    hidden: z.boolean().default(false),\n    /** Excluded from builds entirely, but visible in `astro dev`. */\n    draft: z.boolean().default(false),\n    deprecated: deprecatedSchema().default(false),\n    /** 'doc' gets sidebar + TOC; 'splash' is full-bleed with neither. */\n    template: z.enum(['doc', 'splash']).default('doc'),\n    tableOfContents: z.union([tocSchema(), z.literal(false)]).optional(),\n    /** Opt out of the markdown twin and the search index for this page. */\n    noIndex: z.boolean().default(false),\n    prev: z.union([z.boolean(), z.string()]).optional(),\n    next: z.union([z.boolean(), z.string()]).optional(),\n  });\n}\n\nexport const groupLinkSchema = () =>\n  z.object({\n    label: z.string(),\n    href: z.string(),\n    /** Inferred from the href when omitted. */\n    external: z.boolean().optional(),\n    icon: z.string().optional(),\n    badge: badgeSchema().optional(),\n    attrs: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).default({}),\n  });\n\n/** `_group.yaml`. `.strict()` is load-bearing: a typo in an ordering file must fail, not be ignored. */\nexport function groupSchema() {\n  return z\n    .object({\n      label: z.string().optional(),\n      icon: z.string().optional(),\n      /** Immediate-child filesystem names (not titles), in display order. */\n      order: z.array(z.string()).default([]),\n      /** Children absent from `order`: alpha by label (default), by filename, or manual (dropped from the sidebar). */\n      sort: z.enum(['alpha', 'filename', 'manual']).optional(),\n      collapsed: z.boolean().optional(),\n      hidden: z.boolean().default(false),\n      badge: badgeSchema().optional(),\n      links: z.array(groupLinkSchema()).default([]),\n    })\n    .strict();\n}\n\nexport type DocsFrontmatter = z.infer<ReturnType<typeof docsSchema>>;\nexport type GroupFrontmatter = z.infer<ReturnType<typeof groupSchema>>;\n"]}

package/dist/chunk-K7PJRTK3.js

@@ -0,0 +1,113 @@
+import { z } from 'astro/zod';
+
+// src/config.ts
+var headerLink = z.object({
+  label: z.string(),
+  href: z.string(),
+  /**
+   * A Lucide name like `BookOpen`, or a path to an SVG in `public/` like
+   * `/github.svg`. An SVG must be white: light mode inverts it.
+   */
+  icon: z.string().optional(),
+  external: z.boolean().optional()
+});
+var docsConfigSchema = z.object({
+  /** Site name, shown in the header and used as the `<title>` suffix. */
+  title: z.string(),
+  description: z.string().optional(),
+  /** Path to a favicon, relative to `public/`. Base is applied automatically. */
+  favicon: z.string().default("/favicon.svg"),
+  /**
+   * The header mark. Without one the header falls back to `title` as text. Either
+   * way a constant "Docs" label follows it, and `title` heads the sidebar.
+   */
+  logo: z.object({
+    src: z.string(),
+    /** Name the company: the brand link reads as this plus "Docs". */
+    alt: z.string().default("")
+  }).optional(),
+  /** Content directory, relative to `src/`. */
+  contentDir: z.string().default("content/docs"),
+  /** Mount docs under a sub-path, e.g. 'docs' for /docs/*. Empty means the site root. */
+  pathPrefix: z.string().default(""),
+  sidebar: z.object({
+    /** Default collapse state for groups with no explicit `collapsed`. */
+    collapsed: z.boolean().default(false),
+    /** Default append order for children absent from a group's `order`. */
+    sort: z.enum(["alpha", "filename", "manual"]).default("alpha"),
+    /** Extra top-level nodes, appended after folder-derived ones. */
+    extra: z.array(z.any()).default([])
+  }).prefault({}),
+  header: z.object({
+    links: z.array(headerLink).default([]),
+    showThemeToggle: z.boolean().default(true)
+  }).prefault({}),
+  footer: z.object({
+    /** Base URL for "Edit this page"; the content path is appended. */
+    editUrl: z.string().optional(),
+    showPrevNext: z.boolean().default(true),
+    text: z.string().optional()
+  }).prefault({}),
+  tableOfContents: z.union([
+    z.object({
+      minLevel: z.number().int().min(1).max(6).default(2),
+      maxLevel: z.number().int().min(1).max(6).default(3)
+    }),
+    z.literal(false)
+  ]).prefault({}),
+  code: z.object({
+    /** 'codeblock' renders fences through Equality's CodeBlock; 'shiki' uses Astro's Shiki. */
+    highlighter: z.enum(["codeblock", "shiki"]).default("codeblock"),
+    /** Shiki themes; only consulted when `highlighter` is 'shiki'. */
+    themes: z.object({ light: z.string(), dark: z.string() }).default({ light: "github-light", dark: "github-dark" }),
+    wrap: z.boolean().default(false),
+    langs: z.array(z.string()).default([])
+  }).prefault({}),
+  search: z.object({
+    /** 'pagefind' indexes the built HTML. Dev serves that index, so it needs one build. */
+    provider: z.enum(["pagefind", "none"]).default("pagefind")
+  }).prefault({}),
+  routing: z.object({
+    /** Inject the catch-all docs route. Disable to own routing entirely. */
+    injectPages: z.boolean().default(true),
+    /** Emit a `.md` twin per page plus `/llms.txt`. */
+    markdownTwins: z.boolean().default(true),
+    notFound: z.boolean().default(true)
+  }).prefault({}),
+  theme: z.object({
+    /** 'global' puts tokens on <html>; 'scoped' wraps in a ThemeProvider. */
+    mode: z.enum(["global", "scoped"]).default("global"),
+    /** Persist the reader's choice to localStorage. */
+    persist: z.boolean().default(true)
+  }).prefault({}),
+  /**
+   * Stylesheets loaded on every docs page. A project-relative path ('./src/styles/site.css')
+   * or a package specifier. Resolved against the project root, so dev and build agree.
+   */
+  customCss: z.array(z.string()).default([]),
+  /**
+   * Client modules loaded on every docs page. Bundled rather than served as-is, so they may
+   * import from node_modules - which is what a script mutating rendered text needs, since it
+   * has to call Equality's `scheduleHighlight` afterwards to repaint code blocks.
+   */
+  clientScripts: z.array(z.string()).default([]),
+  /** Install @astrojs/mdx, @astrojs/react and Tailwind when absent. */
+  autoIntegrations: z.boolean().default(true),
+  /** Versioning. Left permissive here; the versioning workstream owns the shape. */
+  versions: z.any().optional(),
+  /** Generated-section plugins (OpenAPI reference, changelogs, ...). */
+  plugins: z.array(z.any()).default([])
+});
+function resolveConfig(user) {
+  const result = docsConfigSchema.safeParse(user);
+  if (!result.success) {
+    const issues = result.error.issues.map((i) => `  - ${i.path.join(".") || "(root)"}: ${i.message}`).join("\n");
+    throw new Error(`[@eqtylab/docs] Invalid configuration:
+${issues}`);
+  }
+  return result.data;
+}
+
+export { docsConfigSchema, resolveConfig };
+//# sourceMappingURL=chunk-K7PJRTK3.js.map
+//# sourceMappingURL=chunk-K7PJRTK3.js.map

package/dist/chunk-K7PJRTK3.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/config.ts"],"names":[],"mappings":"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","file":"chunk-K7PJRTK3.js","sourcesContent":["/** Integration options: the whole consumer-facing configuration surface. */\nimport { z } from 'astro/zod';\n\nconst headerLink = z.object({\n  label: z.string(),\n  href: z.string(),\n  /**\n   * A Lucide name like `BookOpen`, or a path to an SVG in `public/` like\n   * `/github.svg`. An SVG must be white: light mode inverts it.\n   */\n  icon: z.string().optional(),\n  external: z.boolean().optional(),\n});\n\nexport const docsConfigSchema = z.object({\n  /** Site name, shown in the header and used as the `<title>` suffix. */\n  title: z.string(),\n  description: z.string().optional(),\n  /** Path to a favicon, relative to `public/`. Base is applied automatically. */\n  favicon: z.string().default('/favicon.svg'),\n\n  /**\n   * The header mark. Without one the header falls back to `title` as text. Either\n   * way a constant \"Docs\" label follows it, and `title` heads the sidebar.\n   */\n  logo: z\n    .object({\n      src: z.string(),\n      /** Name the company: the brand link reads as this plus \"Docs\". */\n      alt: z.string().default(''),\n    })\n    .optional(),\n\n  /** Content directory, relative to `src/`. */\n  contentDir: z.string().default('content/docs'),\n\n  /** Mount docs under a sub-path, e.g. 'docs' for /docs/*. Empty means the site root. */\n  pathPrefix: z.string().default(''),\n\n  sidebar: z\n    .object({\n      /** Default collapse state for groups with no explicit `collapsed`. */\n      collapsed: z.boolean().default(false),\n      /** Default append order for children absent from a group's `order`. */\n      sort: z.enum(['alpha', 'filename', 'manual']).default('alpha'),\n      /** Extra top-level nodes, appended after folder-derived ones. */\n      extra: z.array(z.any()).default([]),\n    })\n    .prefault({}),\n\n  header: z\n    .object({\n      links: z.array(headerLink).default([]),\n      showThemeToggle: z.boolean().default(true),\n    })\n    .prefault({}),\n\n  footer: z\n    .object({\n      /** Base URL for \"Edit this page\"; the content path is appended. */\n      editUrl: z.string().optional(),\n      showPrevNext: z.boolean().default(true),\n      text: z.string().optional(),\n    })\n    .prefault({}),\n\n  tableOfContents: z\n    .union([\n      z.object({\n        minLevel: z.number().int().min(1).max(6).default(2),\n        maxLevel: z.number().int().min(1).max(6).default(3),\n      }),\n      z.literal(false),\n    ])\n    .prefault({}),\n\n  code: z\n    .object({\n      /** 'codeblock' renders fences through Equality's CodeBlock; 'shiki' uses Astro's Shiki. */\n      highlighter: z.enum(['codeblock', 'shiki']).default('codeblock'),\n      /** Shiki themes; only consulted when `highlighter` is 'shiki'. */\n      themes: z\n        .object({ light: z.string(), dark: z.string() })\n        .default({ light: 'github-light', dark: 'github-dark' }),\n      wrap: z.boolean().default(false),\n      langs: z.array(z.string()).default([]),\n    })\n    .prefault({}),\n\n  search: z\n    .object({\n      /** 'pagefind' indexes the built HTML. Dev serves that index, so it needs one build. */\n      provider: z.enum(['pagefind', 'none']).default('pagefind'),\n    })\n    .prefault({}),\n\n  routing: z\n    .object({\n      /** Inject the catch-all docs route. Disable to own routing entirely. */\n      injectPages: z.boolean().default(true),\n      /** Emit a `.md` twin per page plus `/llms.txt`. */\n      markdownTwins: z.boolean().default(true),\n      notFound: z.boolean().default(true),\n    })\n    .prefault({}),\n\n  theme: z\n    .object({\n      /** 'global' puts tokens on <html>; 'scoped' wraps in a ThemeProvider. */\n      mode: z.enum(['global', 'scoped']).default('global'),\n      /** Persist the reader's choice to localStorage. */\n      persist: z.boolean().default(true),\n    })\n    .prefault({}),\n\n  /**\n   * Stylesheets loaded on every docs page. A project-relative path ('./src/styles/site.css')\n   * or a package specifier. Resolved against the project root, so dev and build agree.\n   */\n  customCss: z.array(z.string()).default([]),\n\n  /**\n   * Client modules loaded on every docs page. Bundled rather than served as-is, so they may\n   * import from node_modules - which is what a script mutating rendered text needs, since it\n   * has to call Equality's `scheduleHighlight` afterwards to repaint code blocks.\n   */\n  clientScripts: z.array(z.string()).default([]),\n\n  /** Install @astrojs/mdx, @astrojs/react and Tailwind when absent. */\n  autoIntegrations: z.boolean().default(true),\n\n  /** Versioning. Left permissive here; the versioning workstream owns the shape. */\n  versions: z.any().optional(),\n\n  /** Generated-section plugins (OpenAPI reference, changelogs, ...). */\n  plugins: z.array(z.any()).default([]),\n});\n\nexport type DocsUserConfig = z.input<typeof docsConfigSchema>;\nexport type DocsConfig = z.output<typeof docsConfigSchema>;\n\nexport function resolveConfig(user: DocsUserConfig): DocsConfig {\n  const result = docsConfigSchema.safeParse(user);\n  if (!result.success) {\n    const issues = result.error.issues\n      .map((i) => `  - ${i.path.join('.') || '(root)'}: ${i.message}`)\n      .join('\\n');\n    throw new Error(`[@eqtylab/docs] Invalid configuration:\\n${issues}`);\n  }\n  return result.data;\n}\n"]}