@dogsbay/render-html 0.2.0-beta.117 → 0.2.0-beta.118

package/README.md

@@ -25,17 +25,31 @@ const html = renderBlocks(dogsbayMdToTree(markdown).tree, ctx);
 The output uses Tailwind utility classes and the theme tokens. Styling it needs the Dogsbay
 theme CSS, compiled for the classes the page uses.
 
+## API reference pages
+
+Autodoc symbols (`api-class`, `api-member`, `api-doc`, `api-params`,
+`api-source`) and OpenAPI operations (`endpoint`) render with the markup of the
+Astro API components. Set `ctx.embeddedEndpoints` from `apiPageLayout(tree)`
+(`@dogsbay/serialize-core`), which also says when the page should drop its
+reading width and table of contents. Include `css/api.css`.
+
+```ts
+import { apiPageLayout } from "@dogsbay/serialize-core";
+const layout = apiPageLayout(tree); // { wide, embeddedEndpoints }
+const html = renderBlocks(tree, { ...ctx, embeddedEndpoints: layout.embeddedEndpoints });
+```
+
 ## Stylesheets
 
 `css/` holds the stylesheets for this markup: the theme presets (`theme-default.css`,
-`theme-mintlify.css`), `docs.css`, `steps.css` and `code-rich.css`. Import them as
+`theme-mintlify.css`), `docs.css`, `steps.css`, `code-rich.css` and `api.css`. Import them as
 `@dogsbay/render-html/css/<file>`. They are Tailwind 4 sources (`@apply`, `@utility`,
 tokens), so compile them with the page's classes.
 
 ## Copied sources
 
 `alert-icons.ts`, `badge-variants.ts`, `kbd-variants.ts`, `file-tree.ts`,
-`code-markers.ts`, `tone-classes.ts` and everything in `css/` are copies from `@dogsbay/ui` and
+`code-markers.ts`, `tone-classes.ts`, `api-markdown.ts` and everything in `css/` are copies from `@dogsbay/ui` and
 `@dogsbay/format-astro`. Copying them keeps this package free of Astro.
 
 After changing them upstream, run `pnpm --filter @dogsbay/render-html sync-sources`.

package/css/api.css

@@ -0,0 +1,133 @@
+/* Generated by packages/render-html/scripts/sync-sources.mjs from @dogsbay/ui api-symbol.css, api-source.css, EndpointSection.astro, PropertyItem.astro. Do not edit. */
+/* API Symbol badges — colored by kind */
+.api-badge {
+  display: inline-flex;
+  align-items: center;
+  border-radius: 0.375rem;
+  padding: 0.125rem 0.5rem;
+  font-size: 0.7rem;
+  font-weight: 600;
+  letter-spacing: 0.025em;
+  text-transform: uppercase;
+  vertical-align: middle;
+  flex-shrink: 0;
+}
+
+.api-badge-class {
+  background-color: oklch(0.55 0.18 265 / 0.2);
+  color: oklch(0.55 0.18 265);
+}
+.dark .api-badge-class {
+  background-color: oklch(0.7 0.15 265 / 0.2);
+  color: oklch(0.7 0.15 265);
+}
+
+.api-badge-meth {
+  background-color: oklch(0.55 0.15 155 / 0.2);
+  color: oklch(0.55 0.15 155);
+}
+.dark .api-badge-meth {
+  background-color: oklch(0.7 0.15 155 / 0.2);
+  color: oklch(0.7 0.15 155);
+}
+
+.api-badge-attr {
+  background-color: oklch(0.6 0.15 55 / 0.2);
+  color: oklch(0.6 0.15 55);
+}
+.dark .api-badge-attr {
+  background-color: oklch(0.75 0.15 55 / 0.2);
+  color: oklch(0.75 0.15 55);
+}
+
+.api-badge-func {
+  background-color: oklch(0.55 0.18 330 / 0.2);
+  color: oklch(0.55 0.18 330);
+}
+.dark .api-badge-func {
+  background-color: oklch(0.7 0.15 330 / 0.2);
+  color: oklch(0.7 0.15 330);
+}
+
+.api-badge-module {
+  background-color: oklch(0.5 0.12 200 / 0.2);
+  color: oklch(0.5 0.12 200);
+}
+.dark .api-badge-module {
+  background-color: oklch(0.65 0.12 200 / 0.2);
+  color: oklch(0.65 0.12 200);
+}
+
+/* API Symbol container */
+.api-symbol {
+  margin-top: 2rem;
+  padding-top: 1.5rem;
+  border-top: 1px solid var(--border, oklch(0.5 0 0 / 0.15));
+}
+
+.api-symbol:first-child {
+  margin-top: 0;
+  padding-top: 0;
+  border-top: none;
+}
+
+.api-symbol-heading {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  margin-bottom: 0.75rem;
+}
+
+.api-symbol-heading code {
+  font-size: 1.25em;
+  font-weight: 600;
+}
+
+.api-symbol-bases {
+  font-size: 0.875rem;
+  color: var(--muted-foreground);
+  margin-bottom: 0.5rem;
+}
+
+.api-source {
+  margin-top: 0.75rem;
+  margin-bottom: 0.75rem;
+  border: 1px solid var(--color-border, oklch(0.85 0 0));
+  border-radius: 0.375rem;
+  overflow: hidden;
+}
+
+.api-source summary {
+  cursor: pointer;
+  padding: 0.5rem 0.75rem;
+  font-size: 0.8125rem;
+  font-weight: 500;
+  color: var(--color-muted-foreground, oklch(0.55 0 0));
+  background: var(--color-muted, oklch(0.96 0 0));
+  user-select: none;
+}
+
+.api-source summary:hover {
+  color: var(--color-foreground, oklch(0.15 0 0));
+}
+
+.api-source[open] summary {
+  border-bottom: 1px solid var(--color-border, oklch(0.85 0 0));
+}
+
+/* Remove extra margin from the code block inside */
+.api-source pre {
+  margin: 0 !important;
+  border-radius: 0 !important;
+  border: none !important;
+}
+
+
+  details[open] > summary [data-section-chevron] {
+    transform: rotate(90deg);
+  }
+
+
+  details[open] > summary [data-property-chevron] {
+    transform: rotate(90deg);
+  }

package/dist/api-markdown.d.ts

@@ -0,0 +1,7 @@
+/** Block Markdown → HTML (an operation's description). */
+export declare function apiBlockHtml(text: string): string;
+/** One line of Markdown → inline HTML (a parameter or property). */
+export declare function apiInlineHtml(text: string): string;
+/** A schema property list with every `description` rendered inline,
+ *  through nested `properties` / `items`. A copy; the node is untouched. */
+export declare function apiPropertiesHtml(list: unknown): unknown;

package/dist/api-markdown.js

@@ -0,0 +1,41 @@
+// Generated by packages/render-html/scripts/sync-sources.mjs from @dogsbay/format-astro/src/api-markdown.ts. Do not edit.
+/**
+ * API description text → HTML, for the API components that render it with
+ * `set:html` (EndpointCard, PropertyItem, ParameterTable).
+ *
+ * OpenAPI defines `description` as CommonMark, and every producer of an
+ * `endpoint` node (format-openapi, the MDX adapters) supplies text or
+ * Markdown, never HTML. It was passed through as HTML: a spec's markdown
+ * showed as `## Authentication` and `**Creating a token**`, and a spec from
+ * someone else's repository could put a `<script>` into the built site.
+ * Rendered here with raw HTML OFF (`<` is escaped) and markdown-it's link
+ * validation (no `javascript:` / `vbscript:` / `file:` / `data:` links).
+ */
+import MarkdownIt from "markdown-it";
+const md = new MarkdownIt({ html: false, linkify: false, typographer: false });
+/** Block Markdown → HTML (an operation's description). */
+export function apiBlockHtml(text) {
+    return md.render(text).trim();
+}
+/** One line of Markdown → inline HTML (a parameter or property). */
+export function apiInlineHtml(text) {
+    return md.renderInline(text.replace(/\s*\n\s*/g, " ")).trim();
+}
+/** A schema property list with every `description` rendered inline,
+ *  through nested `properties` / `items`. A copy; the node is untouched. */
+export function apiPropertiesHtml(list) {
+    if (!Array.isArray(list))
+        return list;
+    return list.map((p) => {
+        if (!p || typeof p !== "object")
+            return p;
+        const o = { ...p };
+        if (typeof o.description === "string")
+            o.description = apiInlineHtml(o.description);
+        if (o.properties)
+            o.properties = apiPropertiesHtml(o.properties);
+        if (o.items)
+            o.items = apiPropertiesHtml(o.items);
+        return o;
+    });
+}

package/dist/api.d.ts

@@ -0,0 +1,35 @@
+/**
+ * API reference nodes → HTML, with the markup and classes the Astro pipeline
+ * gets from format-astro's serializer and the @dogsbay/ui components:
+ *
+ * - code symbols (`api-class`, `api-member`, `api-doc`, `api-params`,
+ *   `api-source`): ApiSymbol, ApiDoc, ApiParams, ApiSource;
+ * - an OpenAPI operation (`endpoint`): ApiLayout with an EndpointCard
+ *   (ApiUrlBar, EndpointSection, PropertyList, SchemaViewer, ResponseTabs)
+ *   and an ApiCodePanel (CodeSamples, ExampleBlock).
+ *
+ * Class lists are the ones Astro writes after tailwind-variants merges them
+ * (apps/demo/dist/api/*), not the components' source strings: the merge
+ * drops `border-l-4` and `border-l-current` from the URL bar, for one.
+ *
+ * Content: operation descriptions are CommonMark rendered with raw HTML off
+ * (api-markdown.ts, copied from format-astro); autodoc's `html` / `docHtml`
+ * are author HTML and go through rewriteHtml, so the host's sanitizer and
+ * link rewriting apply to them as to any raw HTML. Behaviour needs no new
+ * script: sample and response tabs are db-tabs, sections are <details>,
+ * and the URL bar's copy button sits in a db-code-block.
+ */
+import type { TreeNode } from "@dogsbay/types";
+import { type RenderContext } from "./render.js";
+/** The node types this module renders. */
+export declare const API_NODE_TYPES: Set<string>;
+export declare function renderApiNode(n: TreeNode, ctx: RenderContext): string;
+/**
+ * The code an API node renders as code blocks, with the language each is
+ * highlighted in, for highlightInputs: a highlighter that loads grammars per
+ * language must see them before rendering.
+ */
+export declare function apiCodeInputs(n: TreeNode): Array<{
+    lang: string | undefined;
+    code: string;
+}>;

package/dist/api.js

@@ -0,0 +1,346 @@
+import { apiBlockHtml, apiPropertiesHtml } from "./api-markdown.js";
+import { attrs, esc } from "./html.js";
+import { CHECK_ICON, COPY_ICON, codeHtml, renderBlocks, rewriteHtml, tabGroup, uniqueId } from "./render.js";
+const str = (v) => (v == null || v === "" ? undefined : String(v));
+const list = (v) => (Array.isArray(v) ? v.filter((x) => x && typeof x === "object") : []);
+/** The node types this module renders. */
+export const API_NODE_TYPES = new Set(["api-class", "api-member", "api-doc", "api-params", "api-source", "endpoint"]);
+export function renderApiNode(n, ctx) {
+    switch (n.type) {
+        case "api-class":
+        case "api-member":
+            return apiSymbol(n, ctx);
+        case "api-doc":
+            return docSegments(str(n.props?.html) ?? "", "[&>p:first-child]:mt-0 [&>p:last-child]:mb-2", ctx);
+        case "api-params":
+            return apiParams(n, ctx);
+        case "api-source":
+            return apiSource(n, ctx);
+        case "endpoint":
+            return endpoint(n, ctx);
+        default:
+            return "";
+    }
+}
+// ─── Code symbols ────────────────────────────────────────────────────
+/** ApiSymbol.astro: kind badge, the name as a heading, signature, bases, then the body. */
+function apiSymbol(n, ctx) {
+    const p = (n.props ?? {});
+    const name = str(p.name) ?? "";
+    const kind = str(p.kind) ?? "func";
+    const signature = str(p.signature);
+    const bases = Array.isArray(p.bases) ? p.bases.map(String) : [];
+    const level = n.type === "api-class" ? 2 : 3;
+    const badgeKind = kind === "method" ? "meth" : kind;
+    // ApiSymbol's slug, so a link to #mypkg-client reaches the same symbol on both pipelines.
+    const id = uniqueId(ctx, name.toLowerCase().replace(/[^\w]/g, "-").replace(/-+/g, "-"));
+    if (ctx.apiSymbolHeadings)
+        ctx.headings.push({ depth: level, id, text: name });
+    return (`<div class="api-symbol not-prose" data-kind="${esc(kind)}">` +
+        `<div class="api-symbol-heading"><span class="api-badge api-badge-${esc(badgeKind)}">${esc(badgeKind)}</span>` +
+        `<h${level} id="${esc(id)}" class="!mt-0 !mb-0 !border-0"><code class="text-lg font-semibold">${esc(name)}</code></h${level}></div>` +
+        (signature ? codeHtml(signature, "python", ctx) : "") +
+        (bases.length ? `<p class="api-symbol-bases">Bases: ${bases.map((b) => `<code>${esc(b)}</code>`).join("")}</p>` : "") +
+        `<div class="mt-3">${renderBlocks(n.children, ctx)}</div></div>\n`);
+}
+const CODE_IN_HTML = /<pre><code(?:\s+class="language-(\w+)")?>([\s\S]*?)<\/code><\/pre>/g;
+const decodeCode = (s) => s.replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"');
+/** ApiDoc's and ApiParams' split: the code blocks in autodoc HTML become code blocks, the rest stays prose. */
+function splitCode(html) {
+    const out = [];
+    let last = 0;
+    for (const m of html.matchAll(CODE_IN_HTML)) {
+        if (m.index > last)
+            out.push({ html: html.slice(last, m.index) });
+        out.push({ code: decodeCode(m[2]), lang: m[1] || "python" });
+        last = m.index + m[0].length;
+    }
+    if (last < html.length)
+        out.push({ html: html.slice(last) });
+    return out;
+}
+function docSegments(html, edges, ctx) {
+    return splitCode(html)
+        .map((s) => "code" in s
+        ? codeHtml(s.code, s.lang, ctx)
+        : `<div class="prose prose-sm dark:prose-invert max-w-none ${edges}">${rewriteHtml(s.html, ctx)}</div>`)
+        .join("");
+}
+/** ApiParams.astro: a two-column table, the description with its type and default under it. */
+function apiParams(n, ctx) {
+    const rows = list(n.props?.params)
+        .map((p) => {
+        const type = str(p.type);
+        const dflt = str(p.default);
+        return (`<tr class="border-b border-border/50"><td class="py-3 px-4 align-top"><code class="text-sm font-medium">${esc(str(p.name) ?? "")}</code></td>` +
+            `<td class="py-3 px-4 align-top">${docSegments(str(p.docHtml) ?? "", "[&>p:first-child]:mt-0 [&>p:last-child]:mb-0", ctx)}` +
+            `<div class="flex items-center gap-4 mt-2 text-xs text-muted-foreground">` +
+            (type ? `<span><strong>TYPE:</strong> <code class="text-xs">${esc(type)}</code></span>` : "") +
+            (dflt ? `<span class="ml-auto"><strong>DEFAULT:</strong> <code class="text-xs">${esc(dflt)}</code></span>` : "") +
+            `</div></td></tr>`);
+    })
+        .join("");
+    const th = "py-3 px-4 text-left font-semibold text-muted-foreground uppercase tracking-wider text-xs";
+    return (`<table class="api-params w-full text-sm border-collapse not-prose"><thead><tr class="border-b border-border">` +
+        `<th class="${th} w-[140px]">Parameter</th><th class="${th}">Description</th></tr></thead><tbody>${rows}</tbody></table>\n`);
+}
+/** ApiSource.astro: the source in a closed disclosure. */
+function apiSource(n, ctx) {
+    const p = (n.props ?? {});
+    const file = str(p.file);
+    const line = Number(p.line) || undefined;
+    const label = file ? `Source code in ${file}${line ? `, line ${line}` : ""}` : "Source code";
+    return `<details class="api-source"><summary>${esc(label)}</summary>${codeHtml(str(p.code) ?? "", "python", ctx)}</details>\n`;
+}
+// ─── OpenAPI operation ───────────────────────────────────────────────
+const METHODS = ["get", "post", "put", "patch", "delete", "head"];
+function methodBadge(method) {
+    const v = METHODS.includes(method) ? ` bg-api-${method}/20 text-api-${method}` : method === "options" ? " bg-muted/20 text-muted-foreground" : "";
+    return `<span class="inline-flex items-center rounded-md px-2 py-0.5 text-xs font-bold uppercase tracking-wide font-mono${v}" data-method="${esc(method)}">${esc(method)}</span>`;
+}
+/** ApiUrlBar.astro: method, base URL, the path with {params} tinted, a copy button. */
+function urlBar(method, path, baseUrl) {
+    const tint = METHODS.includes(method)
+        ? `border px-4 py-3 bg-api-${method}/10 border-l-api-${method}`
+        : method === "options"
+            ? "border px-4 py-3 bg-muted/40 border-l-muted-foreground"
+            : "border border-l-current px-4 py-3";
+    const parts = path
+        .split(/(\{[^}]+\})/g)
+        .map((s) => (s.startsWith("{") ? `<span class="text-api-put">${esc(s)}</span>` : `<span>${esc(s)}</span>`))
+        .join("");
+    // The copy button sits in a db-code-block, whose behaviour copies data-copy-text: no script of its own.
+    const copy = `<db-code-block class="shrink-0" data-copy-text="${esc(baseUrl + path)}"><button type="button" data-part="copy" aria-label="Copy to clipboard" ` +
+        `class="inline-flex h-8 w-8 items-center justify-center rounded-md border border-border bg-background text-muted-foreground transition-colors hover:bg-accent hover:text-accent-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring">${COPY_ICON}${CHECK_ICON}</button></db-code-block>`;
+    return (`<div class="flex items-center gap-3 rounded-lg ${tint}">${methodBadge(method)}` +
+        `<code class="flex-1 truncate text-sm font-medium">${baseUrl ? `<span class="text-muted-foreground">${esc(baseUrl)}</span>` : ""}${parts}</code>${copy}</div>`);
+}
+const SECTION_CHEVRON = '<svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="size-3.5 shrink-0 text-muted-foreground transition-transform duration-200" data-section-chevron aria-hidden="true"><polyline points="9 18 15 12 9 6"></polyline></svg>';
+const PROPERTY_CHEVRON = '<svg xmlns="http://www.w3.org/2000/svg" width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="size-3 shrink-0 text-muted-foreground transition-transform duration-200" data-property-chevron aria-hidden="true"><polyline points="9 18 15 12 9 6"></polyline></svg>';
+const DEPRECATED_ICON = '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3Z"></path><path d="M12 9v4"></path><path d="M12 17h.01"></path></svg>';
+/** EndpointSection.astro: an open <details> with a turning chevron. */
+function section(title, body) {
+    return (`<details open class="rounded-lg border bg-card"><summary class="flex cursor-pointer items-center gap-2 px-4 py-3 text-sm font-semibold list-none [&::-webkit-details-marker]:hidden hover:bg-muted/50 select-none">` +
+        `${SECTION_CHEVRON}<span>${esc(title)}</span></summary><div class="px-4 pb-4 pt-1">${body}</div></details>`);
+}
+const TYPE_TINT = {
+    string: "bg-api-type-string/20 text-api-type-string",
+    number: "bg-api-type-number/20 text-api-type-number",
+    integer: "bg-api-type-number/20 text-api-type-number",
+    boolean: "bg-api-type-boolean/20 text-api-type-boolean",
+    object: "bg-api-type-object/20 text-api-type-object",
+    array: "bg-api-type-array/20 text-api-type-array",
+    null: "bg-muted/20 text-muted-foreground",
+};
+/** PropertyItem.astro: one parameter or schema property; nested properties/items open in a <details>. */
+function propertyItem(p, level, ctx) {
+    const name = esc(str(p.name) ?? "");
+    const type = str(p.type) ?? "";
+    const format = str(p.format);
+    const description = str(p.description);
+    const children = list(p.properties).length ? list(p.properties) : list(p.items);
+    const indent = level * 16;
+    const badge = `<span class="rounded px-1.5 py-0.5 text-[10px] font-medium ${Object.hasOwn(TYPE_TINT, type) ? TYPE_TINT[type] : TYPE_TINT.string}">${esc(type)}${format ? esc(` <${format}>`) : ""}</span>` +
+        (p.nullable === true ? '<span class="text-muted-foreground text-[10px]">nullable</span>' : "");
+    const required = p.required === true ? '<span class="text-[10px] font-semibold uppercase text-api-required">required</span>' : "";
+    const outer = `border-b border-border last:border-b-0${p.deprecated === true ? " opacity-60" : ""}`;
+    const pad = indent > 0 ? ` style="padding-left: ${16 + indent}px;"` : "";
+    // Descriptions are HTML from api-markdown (raw HTML off); rewriteHtml still resolves their links.
+    const desc = (cls, style = "") => (description ? `<p class="${cls}"${style}>${rewriteHtml(description, ctx)}</p>` : "");
+    if (children.length) {
+        return (`<div class="${outer}"><details><summary class="flex cursor-pointer items-start justify-between gap-4 px-4 py-3 list-none [&::-webkit-details-marker]:hidden hover:bg-muted/50 rounded"${pad}>` +
+            `<div class="flex items-center gap-2 min-w-0">${PROPERTY_CHEVRON}<code class="text-sm font-semibold">${name}</code>${badge}</div>` +
+            `<div class="flex shrink-0 items-center gap-2">${required}</div></summary>` +
+            desc("px-4 pb-1 text-sm text-muted-foreground", ` style="padding-left: ${32 + indent}px;"`) +
+            `<div class="border-l border-border" style="margin-left: ${24 + indent}px;">${children.map((c) => propertyItem(c, level + 1, ctx)).join("")}</div></details></div>`);
+    }
+    const sub = level > 0 ? " pl-5" : "";
+    const enums = Array.isArray(p.enum) ? p.enum : undefined;
+    return (`<div class="${outer}"><div class="flex items-start justify-between gap-4 px-4 py-3"${pad}><div class="min-w-0 flex-1">` +
+        `<div class="flex items-center gap-2">${level > 0 ? '<span class="size-3 shrink-0"></span>' : ""}<code class="text-sm font-semibold">${name}</code>${badge}</div>` +
+        desc(`mt-1 text-sm text-muted-foreground${sub}`) +
+        (enums
+            ? `<div class="mt-1.5 flex flex-wrap items-center gap-1 text-[10px]${sub}"><span class="text-muted-foreground">Enum:</span>${enums.map((v) => `<code class="rounded bg-muted px-1.5 py-0.5">${esc(v)}</code>`).join("")}</div>`
+            : "") +
+        (p.example !== undefined ? `<div class="mt-1 text-xs text-muted-foreground${sub}">Example: <code class="rounded bg-muted px-1 py-0.5">${esc(JSON.stringify(p.example))}</code></div>` : "") +
+        (p.default !== undefined ? `<div class="mt-1 text-xs text-muted-foreground${sub}">Default: <code class="rounded bg-muted px-1 py-0.5">${esc(JSON.stringify(p.default))}</code></div>` : "") +
+        `</div><div class="flex shrink-0 items-center gap-2 pt-0.5">${required}</div></div></div>`);
+}
+const LOCATIONS = [
+    ["path", "Path Parameters"],
+    ["query", "Query Parameters"],
+    ["header", "Header Parameters"],
+    ["cookie", "Cookie Parameters"],
+];
+/** PropertyList.astro: parameters grouped by location. */
+function propertyList(params, ctx) {
+    const groups = LOCATIONS.map(([loc, label]) => ({ label, items: params.filter((p) => p.in === loc) })).filter((g) => g.items.length);
+    return (`<div>` +
+        groups
+            .map((g) => `<div class="mb-4 last:mb-0"><h4 class="mb-1 text-[11px] font-semibold uppercase tracking-wider text-muted-foreground">${g.label}</h4>` +
+            `<div class="rounded-lg border bg-card">${g.items.map((p) => propertyItem(p, 0, ctx)).join("")}</div></div>`)
+            .join("") +
+        `</div>`);
+}
+/** SchemaViewer.astro. */
+function schemaViewer(props, ctx) {
+    return `<div class="rounded-lg border bg-card"><div>${props.map((p) => propertyItem(p, 0, ctx)).join("")}</div></div>`;
+}
+const TABS_ROOT = { class: "my-4 w-full overflow-hidden rounded-lg border border-border" };
+/** Distinct tab values: db-tabs selects by value, so two Python samples ("Sync", "Async") need two. */
+function distinct(values) {
+    const used = new Set();
+    return values.map((v, i) => {
+        while (used.has(v))
+            v += ` (${i + 1})`;
+        used.add(v);
+        return v;
+    });
+}
+function statusTint(status) {
+    const c = status[0];
+    return c >= "2" && c <= "5" ? `bg-api-status-${c}xx/20 text-api-status-${c}xx` : "bg-muted/20 text-muted-foreground";
+}
+/** ResponseTabs.astro: one tab per status, its description and schema. */
+function responseTabs(responses, ctx) {
+    const values = distinct(responses.map((r) => String(r.status ?? "")));
+    return tabGroup(responses.map((r, i) => {
+        const status = String(r.status ?? "");
+        const description = str(r.description);
+        return {
+            value: values[i],
+            label: `<span class="rounded px-1.5 py-0.5 text-xs font-mono font-bold ${statusTint(status)}">${esc(status)}</span>`,
+            body: () => (description ? `<p class="mb-3 text-sm text-muted-foreground">${esc(description)}</p>` : "") +
+                (Array.isArray(r.schema) ? schemaViewer(list(r.schema), ctx) : ""),
+        };
+    }), ctx, TABS_ROOT);
+}
+const SAMPLE_LABELS = {
+    curl: "cURL",
+    python: "Python",
+    typescript: "TypeScript",
+    javascript: "JavaScript",
+    go: "Go",
+    ruby: "Ruby",
+    java: "Java",
+    csharp: "C#",
+    php: "PHP",
+    rust: "Rust",
+};
+const sampleLang = (language) => (language === "curl" ? "bash" : language);
+/** CodeSamples.astro: one tab per language. */
+function codeSamples(samples, ctx) {
+    const values = distinct(samples.map((s) => str(s.language) ?? ""));
+    return tabGroup(samples.map((s, i) => {
+        const language = str(s.language) ?? "";
+        return {
+            value: values[i],
+            label: esc(str(s.label) ?? SAMPLE_LABELS[language] ?? language),
+            body: () => codeHtml(str(s.code) ?? "", sampleLang(language), ctx),
+        };
+    }), ctx, TABS_ROOT);
+}
+const CONTENT_TYPE_LANG = {
+    "application/json": "json",
+    "application/xml": "xml",
+    "application/x-www-form-urlencoded": "plaintext",
+    "text/xml": "xml",
+    "text/html": "html",
+    "text/plain": "plaintext",
+    "text/yaml": "yaml",
+    "application/yaml": "yaml",
+    "application/x-yaml": "yaml",
+    "multipart/form-data": "plaintext",
+};
+/** ExampleBlock.astro's language for a content type. */
+function exampleLang(contentType) {
+    if (!contentType)
+        return "json";
+    const base = contentType.split(";")[0].trim();
+    const known = CONTENT_TYPE_LANG[contentType] ?? CONTENT_TYPE_LANG[base];
+    if (known)
+        return known;
+    if (base.includes("json"))
+        return "json";
+    if (base.includes("xml"))
+        return "xml";
+    if (base.includes("yaml") || base.includes("yml"))
+        return "yaml";
+    return "json";
+}
+const PANEL_HEADING = "mb-3 text-xs font-semibold uppercase tracking-wider text-white/60";
+/** The code column's blocks, in format-astro's order: samples, the request body example, response examples. */
+function codePanels(p) {
+    const out = [];
+    const samples = list(p.codeSamples);
+    if (samples.length)
+        out.push({ title: "Code samples", samples });
+    if (p.requestBodyExample !== undefined)
+        out.push({ title: "Request body", code: JSON.stringify(p.requestBodyExample, null, 2), lang: "json" });
+    for (const r of list(p.responses)) {
+        if (r.example === undefined)
+            continue;
+        out.push({ title: `Response ${String(r.status ?? "")}`, code: JSON.stringify(r.example, null, 2), lang: exampleLang(str(r.contentType)) });
+    }
+    return out;
+}
+/** format-astro's endpointToAstro: ApiLayout, the EndpointCard on the left, the code panel on the right. */
+function endpoint(n, ctx) {
+    const p = (n.props ?? {});
+    const method = (str(p.method) ?? "get").toLowerCase();
+    const path = str(p.path) ?? "";
+    const baseUrl = str(p.baseUrl) ?? "";
+    const summary = str(p.summary);
+    // The card hides a description equal to the summary (compared as text: the rendered HTML never equals it).
+    const description = typeof p.description === "string" && p.description && p.description !== p.summary ? apiBlockHtml(p.description) : undefined;
+    const deprecated = p.deprecated === true;
+    const parameters = list(apiPropertiesHtml(p.parameters));
+    const requestBody = list(apiPropertiesHtml(p.requestBody));
+    const responses = list(p.responses).map((r) => (Array.isArray(r.schema) ? { ...r, schema: apiPropertiesHtml(r.schema) } : r));
+    const sections = (parameters.length ? section("Parameters", propertyList(parameters, ctx)) : "") +
+        (requestBody.length ? section("Request body", schemaViewer(requestBody, ctx)) : "") +
+        (responses.length ? section("Responses", responseTabs(responses, ctx)) : "");
+    const card = `<div${attrs({ class: "space-y-4", "data-component": "endpoint-card", "data-deprecated": deprecated })}>` +
+        urlBar(method, path, baseUrl) +
+        (deprecated
+            ? `<div class="flex items-center gap-2 rounded-lg border border-api-deprecated/30 bg-api-deprecated/10 px-4 py-2 text-sm text-api-deprecated">${DEPRECATED_ICON}<span>This endpoint is deprecated.</span></div>`
+            : "") +
+        (summary ? `<p class="text-sm text-muted-foreground">${esc(summary)}</p>` : "") +
+        (description ? `<div class="text-sm text-muted-foreground">${rewriteHtml(description, ctx)}</div>` : "") +
+        `<div class="space-y-3">${sections}</div></div>`;
+    const panels = codePanels(p)
+        .map((c) => c.samples
+        ? `<div><h3 class="${PANEL_HEADING}">${esc(c.title)}</h3>${codeSamples(c.samples, ctx)}</div>`
+        : `<div><h3 class="${PANEL_HEADING}">${esc(c.title)}</h3>${codeHtml(c.code, c.lang, ctx)}</div>`)
+        .join("");
+    // Embedded among prose unless the host says the page is an operation page (apiPageLayout in @dogsbay/serialize-core).
+    const page = ctx.embeddedEndpoints === false;
+    return (`<div class="dba-api grid grid-cols-1 lg:grid-cols-2 ${page ? "lg:min-h-[calc(100vh-3rem)]" : "my-6 rounded-lg border overflow-hidden"}">` +
+        `<div class="${page ? "px-6 py-10" : "p-6"} lg:border-r">${card}</div>` +
+        `<div class="bg-[var(--api-panel-bg)] text-[var(--api-panel-fg)]"><div class="${page ? "px-6 py-10 lg:sticky lg:top-12 lg:max-h-[calc(100vh-3rem)] lg:overflow-y-auto" : "p-6"}">` +
+        `<div class="space-y-8">${panels}</div></div></div></div>\n`);
+}
+/**
+ * The code an API node renders as code blocks, with the language each is
+ * highlighted in, for highlightInputs: a highlighter that loads grammars per
+ * language must see them before rendering.
+ */
+export function apiCodeInputs(n) {
+    const p = (n.props ?? {});
+    const fromHtml = (html) => splitCode(html ?? "").flatMap((s) => ("code" in s ? [{ lang: s.lang, code: s.code }] : []));
+    switch (n.type) {
+        case "api-class":
+        case "api-member":
+            return str(p.signature) ? [{ lang: "python", code: String(p.signature) }] : [];
+        case "api-source":
+            return [{ lang: "python", code: str(p.code) ?? "" }];
+        case "api-doc":
+            return fromHtml(str(p.html));
+        case "api-params":
+            return list(p.params).flatMap((x) => fromHtml(str(x.docHtml)));
+        case "endpoint":
+            return codePanels(p).flatMap((c) => c.samples ? c.samples.map((s) => ({ lang: sampleLang(str(s.language) ?? ""), code: str(s.code) ?? "" })) : [{ lang: c.lang, code: c.code }]);
+        default:
+            return [];
+    }
+}

package/dist/render.d.ts

@@ -62,6 +62,19 @@ export interface RenderContext {
      * sanitizer here; without one, raw HTML is written as authored.
      */
     rawHtml?: (html: string) => string;
+    /**
+     * OpenAPI operations sit inline among prose (true, the default) or fill an
+     * operation page (false): `apiPageLayout(tree).embeddedEndpoints` from
+     * @dogsbay/serialize-core, the rule format-astro applies.
+     */
+    embeddedEndpoints?: boolean;
+    /**
+     * List autodoc symbol names (api-class, api-member) in `headings`, for the
+     * table of contents. Off by default, as in the Astro pipeline, which lists
+     * them only when a live `:::autodoc` resolved: a 130-method module page
+     * would flood the TOC. Their ids are reserved either way.
+     */
+    apiSymbolHeadings?: boolean;
 }
 export { FOREIGN_END, FOREIGN_START };
 export { scriptUrl };
@@ -87,6 +100,8 @@ export declare function inlineText(nodes: InlineNode[] | undefined): string;
  */
 export declare function rewriteHtml(raw: string, ctx: RenderContext): string;
 export declare function renderBlocks(nodes: TreeNode[] | undefined, ctx: RenderContext): string;
+export declare const COPY_ICON = "<svg data-part=\"copy-icon\" xmlns=\"http://www.w3.org/2000/svg\" width=\"14\" height=\"14\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\" aria-hidden=\"true\" focusable=\"false\"><rect width=\"14\" height=\"14\" x=\"8\" y=\"8\" rx=\"2\" ry=\"2\"/><path d=\"M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2\"/></svg>";
+export declare const CHECK_ICON = "<svg data-part=\"check-icon\" hidden xmlns=\"http://www.w3.org/2000/svg\" width=\"14\" height=\"14\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\" aria-hidden=\"true\" focusable=\"false\"><path d=\"M20 6 9 17l-5-5\"/></svg>";
 /** What highlighting a code node asks of the highlighter; the look-ahead in `build` uses it to highlight blocks ahead of their page. */
 export interface CodeRequest {
     code: string;
@@ -112,3 +127,15 @@ export declare function highlightInputs(tree: unknown): Array<{
     lang: string | undefined;
     code: string;
 }>;
+/** A code block for code a component holds in a prop (an API signature, a sample), as CodeBlock.astro renders it. */
+export declare function codeHtml(code: string, lang: string | undefined, ctx: RenderContext): string;
+export interface TabItem {
+    /** The tab's value (db-tabs matches triggers, panels and synced groups by it). */
+    value: string;
+    /** The trigger's content, as HTML. */
+    label: string;
+    /** The panel's content, as HTML; rendered in order, after the earlier panels. */
+    body: () => string;
+}
+/** A `db-tabs` group with Tabs.astro's markup, the first tab selected. */
+export declare function tabGroup(items: TabItem[], ctx: RenderContext, rootAttrs: Record<string, unknown>, syncKey?: string): string;

package/dist/render.js

@@ -9,6 +9,7 @@ import { stripMarkersForCopy } from "./code-markers.js";
 import { icons as ALERT_ICONS, chevronSvg as ALERT_CHEVRON } from "./alert-icons.js";
 import { parseLineRanges, plainHighlighter } from "./lines.js";
 import { scriptUrl } from "./url.js";
+import { API_NODE_TYPES, apiCodeInputs, renderApiNode } from "./api.js";
 export { FOREIGN_END, FOREIGN_START };
 export { scriptUrl };
 /** ctx.link, unless the target is a script link: then "#", and it is reported. */
@@ -226,6 +227,24 @@ export function rewriteHtml(raw, ctx) {
         return `${sp}${attr}${eq}"${esc(out)}"`;
     }));
 }
+/**
+ * Headings with ids inside a block of HTML (an OpenAPI embed's descriptions,
+ * which format-openapi renders with ids): each id is made unique on the page
+ * and h2/h3 join the outline, as the CLI splices `embed.headings` into the
+ * Astro page's.
+ */
+function proseHeadings(html, ctx) {
+    return html.replace(/<h([1-6])\b([^>]*)>([\s\S]*?)<\/h\1>/gi, (m, lvl, at, inner) => {
+        const idm = /\sid="([^"]*)"/.exec(at);
+        if (!idm)
+            return m;
+        const id = uniqueId(ctx, unesc(idm[1]));
+        const depth = Number(lvl);
+        if (depth === 2 || depth === 3)
+            ctx.headings.push({ depth, id, text: unesc(inner.replace(/<[^>]*>/g, "")).trim() });
+        return `<h${lvl}${at.replace(idm[0], ` id="${esc(id)}"`)}>${inner}</h${lvl}>`;
+    });
+}
 // ─── Blocks ──────────────────────────────────────────────────────────
 export function renderBlocks(nodes, ctx) {
     if (!nodes)
@@ -436,6 +455,17 @@ function block(n, ctx) {
             return `<pre class="my-4 overflow-x-auto rounded-md border bg-muted p-4 text-sm"><code class="math-display">${esc(n.html ?? inlineText(n.inline))}</code></pre>\n`;
         case "related":
             return `<nav class="related-resources" aria-label="${esc(ctx.t("related"))}">${renderInline(n.inline, ctx)}${renderBlocks(n.children, ctx)}</nav>\n`;
+        case "prose":
+            // Inline content or a block of HTML with no wrapper (format-astro's proseToAstro): an OpenAPI
+            // embed's descriptions arrive this way, rendered by format-openapi with raw HTML off.
+            return n.inline ? renderInline(n.inline, ctx) : typeof n.html === "string" ? proseHeadings(rewriteHtml(n.html, ctx), ctx) + "\n" : "";
+        case "api-class":
+        case "api-member":
+        case "api-doc":
+        case "api-params":
+        case "api-source":
+        case "endpoint":
+            return renderApiNode(n, ctx);
         case "include": {
             const target = str(p.path) ?? str(p.src) ?? str(p.file) ?? "";
             const remote = /https?:\/\/\S+/.exec(target)?.[0];
@@ -495,8 +525,8 @@ const BUTTON_VARIANTS = {
     destructive: "bg-destructive text-destructive-foreground hover:bg-destructive/90",
 };
 // ─── Code (CodeBlock.astro, with db-code-block for copy) ────────────
-const COPY_ICON = '<svg data-part="copy-icon" xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><rect width="14" height="14" x="8" y="8" rx="2" ry="2"/><path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2"/></svg>';
-const CHECK_ICON = '<svg data-part="check-icon" hidden xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="M20 6 9 17l-5-5"/></svg>';
+export const COPY_ICON = '<svg data-part="copy-icon" xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><rect width="14" height="14" x="8" y="8" rx="2" ry="2"/><path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2"/></svg>';
+export const CHECK_ICON = '<svg data-part="check-icon" hidden xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="M20 6 9 17l-5-5"/></svg>';
 /** A rendered diagram, as `@dogsbay/ui`'s Diagram.astro: dark mode inverts it and turns the hues back. */
 function diagramFigure(lang, svg, title, p) {
     return (`<figure${attrs({ ...passthrough(p, "diagram not-prose my-4"), "data-lang": lang })}>` +
@@ -542,6 +572,9 @@ export function highlightInputs(tree) {
             const { lang, code } = codeRequest({ type: "code", props: { ...p, language: str(p.lang) ?? "mermaid" }, html: str(p.code) ?? "" });
             out.push({ lang, code });
         }
+        else if (API_NODE_TYPES.has(n.type)) {
+            out.push(...apiCodeInputs(n));
+        }
         if (n.children)
             walk(n.children);
         if (n.props)
@@ -552,6 +585,10 @@ export function highlightInputs(tree) {
     walk(tree);
     return out;
 }
+/** A code block for code a component holds in a prop (an API signature, a sample), as CodeBlock.astro renders it. */
+export function codeHtml(code, lang, ctx) {
+    return codeBlock({ type: "code", props: lang ? { language: lang } : {}, html: code }, ctx);
+}
 function codeBlock(n, ctx) {
     const p = (n.props ?? {});
     const rawLang = str(p.language) ?? str(p.lang);
@@ -690,27 +727,31 @@ function tabs(n, ctx) {
     const kids = (n.children ?? []).filter((c) => c.type === "tab");
     if (!kids.length)
         return renderBlocks(n.children, ctx);
-    const group = ++ctx.seq;
     const used = new Set();
     // The label itself: synced groups match by value, and a slug would merge C, C++ and C#.
-    const values = kids.map((k, i) => {
+    const items = kids.map((k, i) => {
         let v = (str(k.props?.label) ?? `Tab ${i + 1}`).trim();
         while (used.has(v))
             v += ` (${i + 1})`;
         used.add(v);
-        return v;
+        return { value: v, label: esc(str(k.props?.label) ?? `Tab ${i + 1}`), body: () => renderBlocks(k.children, ctx) };
     });
     const syncKey = str(p.syncKey) ?? str(p["sync-key"]) ?? str(p.group);
+    return tabGroup(items, ctx, passthrough(p, "my-4 w-full overflow-hidden rounded-lg border border-border"), syncKey);
+}
+/** A `db-tabs` group with Tabs.astro's markup, the first tab selected. */
+export function tabGroup(items, ctx, rootAttrs, syncKey) {
+    const group = ++ctx.seq;
     let list = "";
     let panels = "";
-    kids.forEach((k, i) => {
+    items.forEach((it, i) => {
         const tid = `tab-${group}-${i + 1}`;
         const pid = `tabpanel-${group}-${i + 1}`;
         const sel = i === 0;
-        list += `<button data-part="trigger" data-value="${esc(values[i])}" role="tab" type="button" id="${tid}" aria-controls="${pid}" aria-selected="${sel}" tabindex="${sel ? 0 : -1}"${sel ? ' data-state="active"' : ""} class="${TAB_TRIGGER}">${esc(str(k.props?.label) ?? `Tab ${i + 1}`)}</button>`;
-        panels += `<div data-part="content" data-value="${esc(values[i])}" role="tabpanel" id="${pid}" aria-labelledby="${tid}" tabindex="0"${sel ? ' data-state="active"' : " hidden"} class="${TAB_CONTENT}">${renderBlocks(k.children, ctx)}</div>`;
+        list += `<button data-part="trigger" data-value="${esc(it.value)}" role="tab" type="button" id="${tid}" aria-controls="${pid}" aria-selected="${sel}" tabindex="${sel ? 0 : -1}"${sel ? ' data-state="active"' : ""} class="${TAB_TRIGGER}">${it.label}</button>`;
+        panels += `<div data-part="content" data-value="${esc(it.value)}" role="tabpanel" id="${pid}" aria-labelledby="${tid}" tabindex="0"${sel ? ' data-state="active"' : " hidden"} class="${TAB_CONTENT}">${it.body()}</div>`;
     });
-    return `<db-tabs${attrs({ ...passthrough(p, "my-4 w-full overflow-hidden rounded-lg border border-border"), "default-value": values[0], "sync-key": syncKey })}><div data-part="list" role="tablist" aria-orientation="horizontal" class="flex items-center border-b border-border bg-muted p-1 text-muted-foreground">${list}</div>${panels}</db-tabs>\n`;
+    return `<db-tabs${attrs({ ...rootAttrs, "default-value": items[0]?.value, "sync-key": syncKey })}><div data-part="list" role="tablist" aria-orientation="horizontal" class="flex items-center border-b border-border bg-muted p-1 text-muted-foreground">${list}</div>${panels}</db-tabs>\n`;
 }
 // ─── Accordion (Accordion*.astro + db-accordion) ────────────────────
 function accordion(n, ctx) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dogsbay/render-html",
-  "version": "0.2.0-beta.117",
+  "version": "0.2.0-beta.118",
   "description": "Dogsbay MD TreeNode → HTML with the Astro components' markup and classes. No highlighter, math or CSS compiler unless you pass one; Worker- and browser-safe",
   "type": "module",
   "main": "./dist/index.js",
@@ -29,9 +29,10 @@
   ],
   "dependencies": {
     "htmlparser2": "^10.1.0",
-    "@dogsbay/format-dogsbay-md": "0.2.0-beta.117",
-    "@dogsbay/serialize-core": "0.2.0-beta.117",
-    "@dogsbay/types": "0.2.0-beta.117"
+    "markdown-it": "^14.3.0",
+    "@dogsbay/format-dogsbay-md": "0.2.0-beta.118",
+    "@dogsbay/types": "0.2.0-beta.118",
+    "@dogsbay/serialize-core": "0.2.0-beta.118"
   },
   "peerDependencies": {
     "katex": "^0.16.0"
@@ -42,6 +43,7 @@
     }
   },
   "devDependencies": {
+    "@types/markdown-it": "^14.1.2",
     "@types/node": "^22.20.1",
     "esbuild": "^0.25.0",
     "katex": "^0.16.47",