@designtools/docs 0.0.0-stage → 0.2.0

package/src/next/index.tsx

@@ -0,0 +1,103 @@
+import "../styles.css";
+import type { Metadata } from "next";
+import { notFound } from "next/navigation";
+import type { ReactNode } from "react";
+import { findBySlug, slugOf } from "../lib/manifest";
+import { PreviewExample, PreviewSurface } from "../preview-frame";
+import { DocsShell } from "../shell";
+import type { DocsConfig } from "./config";
+import { manifestFiles, manifestRoute, markdownRoute } from "./markdown";
+import { DocsPageView } from "./pages";
+import { allSlugs, metaOf, navOf, resolve, siteOf } from "./site";
+
+export { Live } from "../lib/live";
+export { DocsSection } from "../shell";
+export type { BuiltInPage, DocsConfig, EditorialPage, WorkbenchSetup } from "./config";
+export { Markdown as Prose } from "./prose";
+export { markdownFor } from "./markdown";
+export { docsMatcher, docsProxy, prefersMarkdown } from "./proxy";
+
+type SlugParams = { params: Promise<{ slug?: string[] }> };
+
+/**
+ * A whole docs site from one config, for the Next App Router. Each export is
+ * what one route file re-exports, so a project's docs are a handful of
+ * one-line files:
+ *
+ * - `(docs)/layout.tsx`: `export default docs.Layout`
+ * - `(docs)/[[...slug]]/page.tsx`: `export default docs.Page`, with `generateStaticParams` and `generateMetadata`
+ * - `md/[[...path]]/route.ts`: `export const GET = docs.markdown`
+ * - `manifest/[file]/route.ts`: `export const GET = docs.manifest`, with `generateStaticParams = docs.manifestParams`
+ * - `preview/[slug]/[example]/page.tsx`: `export default docs.Preview`
+ *
+ * The same files serve the docs inside a product's app or as a standalone app.
+ */
+export function createDocs(config: DocsConfig) {
+  const site = siteOf(config);
+  const nav = navOf(site);
+  const Registry = config.registry;
+
+  function Layout({ children }: { children: ReactNode }) {
+    return (
+      <Registry>
+        <DocsShell
+          manifest={site.components}
+          rules={site.rules}
+          patterns={site.patterns}
+          terms={site.taxonomy}
+          title={site.title}
+          logo={config.logo}
+          basePath={site.base}
+          brand={nav.brand}
+          foundations={nav.foundations}
+          standards={nav.standards}
+          hero={config.hero}
+        >
+          {children}
+        </DocsShell>
+      </Registry>
+    );
+  }
+
+  async function Page({ params }: SlugParams) {
+    const page = resolve(site, (await params).slug);
+    if (!page) notFound();
+    return <DocsPageView site={site} page={page} />;
+  }
+
+  async function generateMetadata({ params }: SlugParams): Promise<Metadata> {
+    const page = resolve(site, (await params).slug);
+    return page ? metaOf(site, page) : {};
+  }
+
+  /** One example on its own, outside the shell: what the preview frame shows, and the target for visual regression. */
+  async function Preview({ params, searchParams }: { params: Promise<{ slug: string; example: string }>; searchParams: Promise<{ theme?: string }> }) {
+    const { slug, example } = await params;
+    const { theme } = await searchParams;
+    const entry = findBySlug(site.components, slug);
+    if (!entry?.examples) notFound();
+    return (
+      <Registry>
+        <PreviewSurface theme={theme}>
+          <PreviewExample entry={entry} example={decodeURIComponent(example)} />
+        </PreviewSurface>
+      </Registry>
+    );
+  }
+
+  return {
+    site,
+    Layout,
+    Page,
+    generateMetadata,
+    generateStaticParams: () => allSlugs(site).map((slug) => ({ slug })),
+    Preview,
+    previewParams: () =>
+      site.components.components.flatMap((c) =>
+        c.examples ? [c.examples.canonical, ...c.examples.do, ...c.examples.dont, ...c.examples.other].filter(Boolean).map((e) => ({ slug: slugOf(c), example: e!.name })) : [],
+      ),
+    markdown: markdownRoute(site),
+    manifest: manifestRoute(site),
+    manifestParams: () => Object.keys(manifestFiles(site)).map((name) => ({ file: `${name}.json` })),
+  };
+}

package/src/next/markdown.ts

@@ -0,0 +1,119 @@
+import { groupByCategory, slugOf } from "../lib/manifest";
+import {
+  adherenceMarkdown,
+  assetsMarkdown,
+  coloursMarkdown,
+  componentMarkdown,
+  editorialHeader,
+  generatedHeader,
+  glossaryMarkdown,
+  manifestLinks,
+  patternMarkdown,
+  ruleMarkdown,
+  scaleMarkdown,
+  standardsMarkdown,
+  systemMarkdown,
+  typeMarkdown,
+} from "../lib/markdown";
+import { navOf, resolve, type Site } from "./site";
+
+/**
+ * The markdown form of a docs page, generated from the manifest rather than
+ * converted from HTML, or nothing when there is no such page. `context` is the
+ * whole system in one file.
+ */
+export function markdownFor(site: Site, path: string): string | undefined {
+  const { base, title, components, tokens, rules, patterns, taxonomy, assets, config } = site;
+  const generated = (md: string) => generatedHeader(config.provenance ?? "") + md;
+  if (path === "context")
+    return systemMarkdown({ components, tokens, rules: rules.rules, patterns: patterns.patterns, terms: taxonomy.terms }, title, config.provenance ?? "");
+
+  const page = resolve(site, path ? path.split("/") : []);
+  if (!page) return undefined;
+  switch (page.kind) {
+    case "overview": {
+      const nav = navOf(site);
+      const links = (list: { label: string; href: string }[]) => list.map((l) => `[${l.label}](${l.href}.md)`).join(", ");
+      return generated(
+        [
+          `# ${title}`,
+          "",
+          "The brand and the design system in one place. Every page here has a markdown form: add `.md` to its URL.",
+          "",
+          "## Pages",
+          "",
+          ...(nav.brand.length ? [`- Brand: ${links(nav.brand)}`] : []),
+          `- Foundations: ${links(nav.foundations)}`,
+          ...(rules.rules.length ? [`- [Rules](${base}/rules.md)`] : []),
+          ...patterns.patterns.map((p) => `- Pattern: [${p.name}](${base}/patterns/${p.id}.md)`),
+          ...groupByCategory(components).flatMap((g) =>
+            g.components.map((c) => `- ${g.category}: [${c.name}](${base}/components/${slugOf(c)}.md), ${c.status ?? "status not set"}`),
+          ),
+          ...(nav.standards.length ? [`- Standards: ${links(nav.standards)}`] : []),
+          `- Everything in [one file](${base}/context.md)`,
+          "",
+          manifestLinks(`${base}/manifest`),
+        ].join("\n"),
+      );
+    }
+    case "editorial":
+      return `${editorialHeader(page.page.by)}# ${page.page.title}\n\n${page.page.lead ? `${page.page.lead}\n\n` : ""}${typeof page.page.body === "string" ? page.page.body : page.page.markdown}\n`;
+    case "logo":
+      return generated(
+        assetsMarkdown(assets.assets.filter((a) => a.kind === "logo")) +
+          "\n" +
+          rules.rules
+            .filter((r) => r.kind === "brand")
+            .map(ruleMarkdown)
+            .join("\n"),
+      );
+    case "imagery":
+      return generated(assetsMarkdown(assets.assets.filter((a) => a.kind !== "logo")));
+    case "voice":
+      return generated(glossaryMarkdown(taxonomy.terms.filter((t) => t.kind === "product" || t.wrong?.length)));
+    case "colour":
+      return generated(coloursMarkdown(tokens));
+    case "type":
+      return generated(typeMarkdown(tokens));
+    case "scale":
+      return generated(scaleMarkdown(tokens));
+    case "rules":
+      return generated(["# Rules", "", ...rules.rules.map(ruleMarkdown)].join("\n"));
+    case "pattern":
+      return generated(patternMarkdown(page.pattern, 1));
+    case "component":
+      return generated(componentMarkdown(page.entry, 1));
+    case "standards":
+      return generated(`${config.baselines ? standardsMarkdown(config.baselines) : ""}\n${config.adherence ? adherenceMarkdown(config.adherence) : ""}`);
+    case "vocabulary":
+      return generated(glossaryMarkdown(taxonomy.terms));
+  }
+}
+
+/** The route handler for `md/[[...path]]`: the page's markdown with `Vary: Accept` and its canonical link, or a markdown 404. */
+export function markdownRoute(site: Site) {
+  return async function GET(_: Request, { params }: { params: Promise<{ path?: string[] }> }) {
+    const path = ((await params).path ?? []).join("/").replace(/\.md$/, "");
+    const page = markdownFor(site, path);
+    const canonical = `${site.base}${path ? `/${path}` : ""}`;
+    return new Response(page ?? `# Not found\n\nThere is no page at \`${canonical}\`. The index is at [${site.base}.md](${site.base}.md).\n`, {
+      status: page ? 200 : 404,
+      headers: { "content-type": "text/markdown; charset=utf-8", vary: "Accept", link: `<${canonical}>; rel="canonical"` },
+    });
+  };
+}
+
+/** The route handler for `manifest/[file]`: each manifest file as JSON, so an agent outside the repo gets the exact data. */
+export function manifestRoute(site: Site) {
+  const files = manifestFiles(site);
+  return async function GET(_: Request, { params }: { params: Promise<{ file: string }> }) {
+    const { file } = await params;
+    const data = files[file.replace(/\.json$/, "")];
+    if (!data) return new Response(`# Not found\n\nNo manifest file called ${file}.\n`, { status: 404, headers: { "content-type": "text/markdown; charset=utf-8" } });
+    return Response.json(data);
+  };
+}
+
+export function manifestFiles(site: Site): Record<string, unknown> {
+  return Object.fromEntries(Object.entries(site.config.manifest).filter(([, v]) => v !== undefined));
+}