@dogsbay/render-html 0.2.0-beta.121 → 0.2.0-beta.123

package/README.md

@@ -9,17 +9,19 @@ markup and Tailwind classes of the Dogsbay Astro components.
 
 ```ts
 import { dogsbayMdToTree } from "@dogsbay/format-dogsbay-md/browser";
-import { renderBlocks, type RenderContext } from "@dogsbay/render-html";
-
-const ctx: RenderContext = {
-  link: (href) => href,
-  asset: (src) => src,
-  headings: [], ids: new Set(), unknown: new Set(), seq: 0,
-  t: (key) => key,
+import { createRenderContext, renderBlocks } from "@dogsbay/render-html";
+
+// One context per page. Pass only what you choose; the renderer's own state
+// (headings, ids, …) is created for you, and UI strings default to English.
+const ctx = createRenderContext({
+  // link: (href) => …,                        // default: unchanged
+  // asset: (src) => …,                         // default: unchanged
+  // t: (key) => myStrings[key],                // empty answers fall back to UI_STRINGS
   // highlighter: await createHighlighter(),   // @dogsbay/highlight
   // math: katexMath,                           // @dogsbay/render-html/math (needs katex)
-};
+});
 const html = renderBlocks(dogsbayMdToTree(markdown).tree, ctx);
+// ctx.headings: the h2/h3 for a table of contents; ctx.unknown: node types it did not know
 ```
 
 The output uses Tailwind utility classes and the theme tokens. Styling it needs the Dogsbay

package/css/docs.css

@@ -51,8 +51,9 @@
      looked like a colour bug in one button rather than a cascade bug in both.
      (No backticks in this comment: the whole stylesheet is a template
      literal.) */
-  & a:not(.dba-api *):not([data-variant]) { color: var(--primary); text-decoration: underline; text-underline-offset: 2px; }
-  & a:hover:not(.dba-api *):not([data-variant]) { opacity: 0.8; }
+  /* Not a whole-card link (LinkCard, the video card: `a.not-prose`): its underline ran under every line of the card */
+  & a:not(.dba-api *):not([data-variant]):not(.not-prose) { color: var(--primary); text-decoration: underline; text-underline-offset: 2px; }
+  & a:hover:not(.dba-api *):not([data-variant]):not(.not-prose) { opacity: 0.8; }
 
   & strong:not(.dba-api *) { font-weight: 600; }
   & code:not(.dba-api *) { font-size: 0.875em; padding: 0.15em 0.35em; border-radius: 0.25rem; background: var(--muted); font-family: var(--font-code, ui-monospace, monospace); }
@@ -66,6 +67,9 @@
   & ol:not(.dba-api *) { list-style: decimal; padding-left: 1.5rem; margin: 0.75rem 0; }
   & li:not(.dba-api *) { margin: 0.25rem 0; }
   & li > ul:not(.dba-api *), & li > ol:not(.dba-api *) { margin: 0.25rem 0; }
+  /* A file tree draws its own folder and file icons (files/markup.ts): the list rules above gave it bullets too */
+  & [data-component="files"] ul:not(.dba-api *) { list-style: none; padding-left: 0; }
+  & [data-component="files"] li > ul:not(.dba-api *) { padding-left: 1rem; }
 
   & blockquote:not(.dba-api *) { border-left: 4px solid var(--border); padding-left: 1rem; color: var(--muted-foreground); font-style: italic; margin: 1rem 0; }
 
@@ -91,7 +95,11 @@
   & .heading-anchor { text-decoration: none; opacity: 0; margin-right: 0.25rem; transition: opacity 0.2s; }
   & h1:hover .heading-anchor, & h2:hover .heading-anchor, & h3:hover .heading-anchor, & h4:hover .heading-anchor { opacity: 0.4; }
 
-  & details:not(.dba-api *) { border: 1px solid var(--border); border-radius: 0.5rem; padding: 1rem; margin: 1rem 0; }
+  /* Raw HTML <details> only. CollapsibleAlert (:::details, collapsible
+     callouts) is a <details> too, with its own border and spacing; it
+     carries data-variant, and without the exclusion it got a second border
+     and 1rem of padding around its title bar. */
+  & details:not(.dba-api *):not([data-variant]) { border: 1px solid var(--border); border-radius: 0.5rem; padding: 1rem; margin: 1rem 0; }
   & summary:not(.dba-api *) { cursor: pointer; font-weight: 600; }
 
   /* mark is emitted by the highlight directive AND can arrive as raw HTML

package/dist/badge-variants.js

@@ -28,6 +28,8 @@ export const BADGE_VARIANTS = {
 };
 /** The class list for a variant; an unknown variant gets the base classes only. */
 export function badgeClass(variant) {
-    const v = BADGE_VARIANTS[(variant ?? "default")];
+    // Own keys only: `toString` or `__proto__` must not read Object.prototype
+    const key = variant ?? "default";
+    const v = Object.prototype.hasOwnProperty.call(BADGE_VARIANTS, key) ? BADGE_VARIANTS[key] : undefined;
     return v ? `${BADGE_BASE} ${v}` : BADGE_BASE;
 }

package/dist/capabilities.d.ts

@@ -0,0 +1,25 @@
+/**
+ * What the HTML renderer can and cannot represent — a CONTRACT (the
+ * format-docusaurus pattern): `validateCapabilities` rejects any non-full
+ * entry without a note, and `tests/capabilities.test.ts` asserts every
+ * `MATRIX_ROWS` type is declared exactly once. Measured against `render.ts`
+ * and `api.ts` by rendering real nodes, not read off the switch.
+ *
+ * This renderer has no export ledger. What it does record goes to the
+ * caller's RenderContext: `unknown` (node types and directives it has no
+ * case for, the example fallback panel, unresolved includes), `missingIcons`
+ * and `unsafeUrls`. dogsbay-ssg and @dogsbay/render turn those into build
+ * warnings. A degradation that lands in none of them is SILENT, and the
+ * notes below say so where it happens.
+ *
+ * Several cells depend on what the caller passes: math is `full` only with a
+ * `math` function (KaTeX), a diagram only with an `svg` prop or a `diagram`
+ * renderer, an icon only when the built-in Lucide set or the `icons`
+ * resolver knows it. Those are declared `partial`, because the renderer on
+ * its own does not guarantee them.
+ *
+ * Support levels: full — renders faithfully, with the Astro components'
+ * markup · partial — survives with reduced fidelity · none — dropped.
+ */
+import type { CapabilityDeclaration } from "@dogsbay/serialize-core";
+export declare const RENDER_HTML_CAPABILITIES: CapabilityDeclaration[];

package/dist/capabilities.js

@@ -0,0 +1,119 @@
+export const RENDER_HTML_CAPABILITIES = [
+    // ── Blocks ───────────────────────────────────────────────
+    { feature: "heading", support: "full", rendersAs: "`<hN>` with a unique id and a hover pilcrow; h2/h3 join the TOC" },
+    { feature: "paragraph", support: "full", rendersAs: "`<p>` (a lone titled image becomes a figure with `imageCaptions: \"title\"`)" },
+    { feature: "blockquote", support: "full", rendersAs: "`<blockquote>`" },
+    { feature: "unordered-list", support: "full", rendersAs: "`<ul>`, task items as disabled checkboxes" },
+    { feature: "ordered-list", support: "full", rendersAs: "`<ol>` with `start`" },
+    { feature: "hr", support: "full", rendersAs: "`<hr>`" },
+    { feature: "table", support: "full", rendersAs: "scrollable `<table>` with caption, alignment, colspan/rowspan" },
+    {
+        feature: "code",
+        support: "full",
+        rendersAs: "`<db-code-block>` (CodeBlock / CodeRich markup); highlighted only when a Highlighter is passed, plain text otherwise",
+    },
+    {
+        feature: "math-block",
+        support: "partial",
+        rendersAs: "KaTeX HTML + MathML when `ctx.math` is passed",
+        note: "Without a math renderer the LaTeX source is shown in a `<pre><code class=\"math-display\">` — readable, not typeset. Not recorded.",
+    },
+    { feature: "deflist", support: "full", rendersAs: "`<dl>` / `<dt>` / `<dd>`" },
+    { feature: "figure", support: "full", rendersAs: "`<figure>` with `<figcaption>`" },
+    { feature: "footnote-list", support: "full", rendersAs: "`<section role=\"doc-endnotes\">` with backlinks" },
+    {
+        feature: "html",
+        support: "full",
+        rendersAs: "the HTML as authored, links rewritten, script URLs refused (reported in `unsafeUrls`); filtered by `ctx.rawHtml` when the host passes a sanitizer",
+    },
+    { feature: "html-container", support: "full", rendersAs: "its HTML as authored, or a `div.db-html-container` around its children" },
+    {
+        feature: "diagram",
+        support: "partial",
+        rendersAs: "`<figure class=\"diagram\">` around the SVG",
+        note: "Rendered only when the node carries an `svg` prop or the host passes `ctx.diagram`; otherwise the diagram SOURCE is shown as a code block. Not recorded.",
+    },
+    {
+        feature: "youtube",
+        support: "partial",
+        rendersAs: "a link card to youtube.com/watch (optional local poster image)",
+        note: "Deliberately no embed: the page must work offline and make no request to YouTube. The Astro pipeline embeds on click.",
+    },
+    // ── Components ───────────────────────────────────────────
+    { feature: "callout", support: "full", rendersAs: "Alert markup (12 variants, aliases mapped); collapsible → CollapsibleAlert `<details>`" },
+    { feature: "details", support: "full", rendersAs: "CollapsibleAlert `<details>`, as the Astro serializer" },
+    { feature: "details-sheet", support: "full", rendersAs: "`<db-details-sheet>` around the CollapsibleAlert `<details>` (a right-hand native `<dialog>` when the element script runs; a collapsible block with `js: none`)" },
+    { feature: "theme", support: "full", rendersAs: "a `<div class=\"dark …\" data-theme>` (THEME_SCOPES); an unknown name keeps the content and is reported" },
+    { feature: "tabs-variant", support: "full", rendersAs: "the variant's complete list and trigger classes in place of the base ones (TAB_VARIANTS)" },
+    { feature: "tone", support: "full", rendersAs: "each card's border and tint from the tone (CARD_TONE_CLASSES)" },
+    {
+        feature: "tabs",
+        support: "full",
+        rendersAs: "`<db-tabs>` with Tabs.astro markup, synced groups by label; a child that is not a tab stays in reading order around the group",
+    },
+    { feature: "steps", support: "full", rendersAs: "`<ol class=\"steps-list\">`; a non-step child is wrapped in its own `<li>`" },
+    {
+        feature: "accordion",
+        support: "full",
+        rendersAs: "`<db-accordion>` with Accordion.astro markup; a child that is not an item stays in reading order around the group",
+    },
+    { feature: "cards", support: "full", rendersAs: "a responsive card grid `<div>`" },
+    { feature: "card", support: "full", rendersAs: "Card.astro markup; icon, title, description, body; linked when `href` is set" },
+    { feature: "link-card", support: "full", rendersAs: "LinkCard.astro markup; a body of several blocks renders as a linked Card" },
+    { feature: "files", support: "full", rendersAs: "FileTree's markup: folder and file icons, nested" },
+    { feature: "grid", support: "full", rendersAs: "a 1–6 column grid; grid-item spans and placeholder cells" },
+    { feature: "link-button", support: "full", rendersAs: "an `<a>` with Button.astro's classes and variant" },
+    { feature: "related", support: "full", rendersAs: "`<nav class=\"related-resources\">`" },
+    {
+        feature: "example",
+        support: "partial",
+        rendersAs: "a figure: the rendered content, then its source in a collapsed panel",
+        note: "The Astro component's optional plain-Markdown panel (`fallback=true`) needs a second Markdown renderer and is left out; reported in `ctx.unknown`.",
+    },
+    {
+        feature: "container",
+        support: "partial",
+        rendersAs: "`<div data-directive=\"name\">` with its title and content",
+        note: "A `:::name` directive no renderer knows: content kept, but no component behaviour or styling. Reported in `ctx.unknown` as `:::name`.",
+    },
+    {
+        feature: "annotation-list",
+        support: "partial",
+        rendersAs: "a tinted box holding the annotation list (format-astro's wrapBlock)",
+        note: "The annotations are not attached to the code block's `(1)` markers as pop-ups; they read as a list below the code, as in the Astro pipeline.",
+    },
+    // ── API reference ────────────────────────────────────────
+    { feature: "endpoint", support: "full", rendersAs: "ApiLayout + EndpointCard + code panel; descriptions are CommonMark with raw HTML off" },
+    { feature: "api-doc", support: "full", rendersAs: "ApiDoc: prose with its code blocks split out" },
+    { feature: "api-class", support: "full", rendersAs: "ApiSymbol: kind badge, heading, signature, bases, body" },
+    { feature: "api-member", support: "full", rendersAs: "ApiSymbol, one level below its parent" },
+    { feature: "api-params", support: "full", rendersAs: "ApiParams two-column table" },
+    { feature: "api-source", support: "full", rendersAs: "ApiSource: a `<details>` with the source code" },
+    // ── Inline ───────────────────────────────────────────────
+    { feature: "link", support: "full", rendersAs: "`<a>` via `ctx.link`; inline buttons with Button.astro classes; script URLs become `#` and are reported" },
+    { feature: "image", support: "full", rendersAs: "`<img>` via `ctx.asset`, lazy; optional zoom marker" },
+    { feature: "kbd", support: "full", rendersAs: "one `<kbd>` keycap per key, joined by `+`" },
+    {
+        feature: "math",
+        support: "partial",
+        rendersAs: "KaTeX HTML + MathML when `ctx.math` is passed",
+        note: "Without a math renderer the LaTeX source is shown as `<code class=\"db-math\">`. Not recorded.",
+    },
+    { feature: "highlight", support: "full", rendersAs: "`<mark>`" },
+    { feature: "badge", support: "full", rendersAs: "Badge.astro `<span>` with its variant" },
+    {
+        feature: "icon",
+        support: "partial",
+        rendersAs: "Icon.astro markup around the resolved SVG or emoji",
+        note: "Resolved by `ctx.icons` or the built-in Lucide subset only; an unknown name becomes an empty `span.db-icon-missing`, reported in `ctx.missingIcons`.",
+    },
+    { feature: "footnote-ref", support: "full", rendersAs: "`<sup>` noteref; repeat references get distinct ids" },
+    { feature: "html-inline", support: "full", rendersAs: "the HTML as authored, links rewritten, filtered by `ctx.rawHtml` when passed" },
+    // ── Concerns the renderer records ────────────────────────
+    {
+        feature: "unrecognised node types",
+        support: "partial",
+        rendersAs: "block: its HTML, or a `div.db-<type>` with its inline and children; inline: nothing",
+        note: "Reported in `ctx.unknown` (blocks by type, inline as `inline:<type>`). An unknown INLINE node is dropped; an unknown block keeps its content.",
+    },
+];

package/dist/context.d.ts

@@ -0,0 +1,24 @@
+/**
+ * A RenderContext with defaults. RenderContext mixes what a host chooses
+ * (links, assets, highlighter, math, icons, strings) with the renderer's own
+ * per-page state (headings, ids, seq, unknown …); hosts built it by hand,
+ * reading render.d.ts to get the internals right, and a new internal field
+ * broke every host silently. Build it here instead: pass only what you choose.
+ */
+import type { RenderContext } from "./render.js";
+/** The UI strings the renderer asks for (ctx.t), in English. */
+export declare const UI_STRINGS: Readonly<Record<string, string>>;
+/** The per-page state the renderer keeps in the context: always fresh, never passed. */
+type Internal = "headings" | "ids" | "unknown" | "seq" | "t" | "fnRefs" | "usedMath" | "inLink" | "lastHeadingLevel" | "apiParentLevel" | "missingIcons" | "unsafeUrls";
+export type RenderContextOptions = Partial<Omit<RenderContext, Internal>> & {
+    /**
+     * Localised UI strings. An empty or missing answer falls back to English
+     * (UI_STRINGS), then to the renderer's own label (callout titles).
+     */
+    t?: (key: string) => string | undefined;
+    /** Ids the page already uses outside the rendered content (a skip link's target): generated ids avoid them. */
+    reservedIds?: Iterable<string>;
+};
+/** A fresh context for one page: identity links and assets, English strings, empty state. */
+export declare function createRenderContext(options?: RenderContextOptions): RenderContext;
+export {};

package/dist/context.js

@@ -0,0 +1,25 @@
+/** The UI strings the renderer asks for (ctx.t), in English. */
+export const UI_STRINGS = {
+    backToContent: "Back to content",
+    close: "Close",
+    copyCode: "Copy code",
+    details: "Details",
+    related: "Related links",
+};
+/** A fresh context for one page: identity links and assets, English strings, empty state. */
+export function createRenderContext(options = {}) {
+    const { t, reservedIds, ...chosen } = options;
+    return {
+        ...chosen,
+        // An explicit `link: undefined` must not remove the default
+        link: chosen.link ?? ((href) => href),
+        asset: chosen.asset ?? ((src) => src),
+        headings: [],
+        ids: new Set(reservedIds ?? []),
+        unknown: new Set(),
+        missingIcons: new Set(),
+        unsafeUrls: new Set(),
+        seq: 0,
+        t: (key) => t?.(key) || UI_STRINGS[key] || "",
+    };
+}

package/dist/css-tools.d.ts

@@ -1,8 +1,3 @@
-/**
- * Every class name in the page's class attributes, entity-decoded. Markup
- * from other tools (KaTeX, Mermaid), between the foreign markers, is skipped:
- * its class names are not Tailwind utilities.
- */
 export declare function pageClasses(html: string, into?: Set<string>): Set<string>;
 /**
  * Whitespace and comment removal. Tailwind's own minifier (Lightning CSS)

package/dist/css-tools.js

@@ -11,11 +11,20 @@ const FOREIGN_BLOCK = new RegExp(`${FOREIGN_START}[\\s\\S]*?${FOREIGN_END}`, "g"
  * from other tools (KaTeX, Mermaid), between the foreign markers, is skipped:
  * its class names are not Tailwind utilities.
  */
+const TAG = /<[a-zA-Z][^\s/>]*(?:\s+[^\s"'>/=]+(?:\s*=\s*(?:"[^"]*"|'[^']*'|[^\s"'=<>`]+))?|\s*\/)*\s*>/g;
 export function pageClasses(html, into = new Set()) {
     const page = html.includes(FOREIGN_START) ? html.replace(FOREIGN_BLOCK, "") : html;
     // Only inside tags: text that merely looks like class="…" (escaped prose, code) must
     // not become CSS. A class compiled from text once wrote `</style>` into the stylesheet.
-    for (const tag of page.matchAll(/<[a-zA-Z][^<>]*>/g))
+    // A quoted attribute value may contain `>` (`[&>svg]:size-4`, valid HTML):
+    // a tag pattern that stopped at the first `>` cut the tag mid-class and lost
+    // the WHOLE class list (the accordion trigger, callout icons, diagrams).
+    // So tags are read with HTML's attribute grammar: a quote opens a value ONLY
+    // right after `=`. Allowing quotes anywhere let an unquoted value with an
+    // apostrophe (`title=it's`) run on past the real `>` into the text, and
+    // text after it became CSS (review). A tag that does not parse is skipped:
+    // a missing style, never text compiled as CSS.
+    for (const tag of page.matchAll(TAG))
         for (const m of tag[0].matchAll(/\sclass\s*=\s*(?:"([^"]*)"|'([^']*)')/g))
             for (const tok of (m[1] ?? m[2]).split(/\s+/))
                 if (tok)

package/dist/index.d.ts

@@ -6,6 +6,8 @@
  * imports neither, so it carries no Shiki, KaTeX or Node built-ins.
  */
 export * from "./render.js";
+export { createRenderContext, UI_STRINGS, type RenderContextOptions } from "./context.js";
 export * from "./lines.js";
 export { esc, attrs, passthrough, slugify, unesc } from "./html.js";
 export { icon, hasIcon, CALLOUTS } from "./icons.js";
+export { RENDER_HTML_CAPABILITIES } from "./capabilities.js";

package/dist/index.js

@@ -6,6 +6,8 @@
  * imports neither, so it carries no Shiki, KaTeX or Node built-ins.
  */
 export * from "./render.js";
+export { createRenderContext, UI_STRINGS } from "./context.js";
 export * from "./lines.js";
 export { esc, attrs, passthrough, slugify, unesc } from "./html.js";
 export { icon, hasIcon, CALLOUTS } from "./icons.js";
+export { RENDER_HTML_CAPABILITIES } from "./capabilities.js";

package/dist/render.d.ts

@@ -1,9 +1,3 @@
-/**
- * TreeNode → HTML. Emits plain semantic HTML plus light-DOM custom
- * elements (`db-tabs`, `db-accordion`, `db-code-block`) whose markup
- * contract comes from `@dogsbay/elements`. Everything is a string, so
- * rendering is synchronous and runs anywhere.
- */
 import type { InlineNode, TreeNode } from "@dogsbay/types";
 import { FOREIGN_END, FOREIGN_START } from "./html.js";
 import { type Highlighter } from "./lines.js";
@@ -142,4 +136,4 @@ export interface TabItem {
     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;
+export declare function tabGroup(items: TabItem[], ctx: RenderContext, rootAttrs: Record<string, unknown>, syncKey?: string, variant?: string): string;

package/dist/render.js

@@ -1,9 +1,16 @@
+/**
+ * TreeNode → HTML. Emits plain semantic HTML plus light-DOM custom
+ * elements (`db-tabs`, `db-accordion`, `db-code-block`) whose markup
+ * contract comes from `@dogsbay/elements`. Everything is a string, so
+ * rendering is synchronous and runs anywhere.
+ */
+import { isDetailsSheet, renderAroundGroup } from "@dogsbay/serialize-core";
 import { parseInline } from "@dogsbay/format-dogsbay-md/browser";
 import { attrs, esc, FOREIGN_END, FOREIGN_START, passthrough, slugify, unesc } from "./html.js";
 import { CALLOUTS, hasIcon, icon } from "./icons.js";
 import { badgeClass } from "./badge-variants.js";
 import { KBD_CLASS } from "./kbd-variants.js";
-import { TONE_CLASSES } from "./tone-classes.js";
+import { CARD_TONE_CLASSES, TAB_VARIANTS, THEME_SCOPES, TONE_CLASSES, lookup } from "./tone-classes.js";
 import { fileTreeHtml } from "./file-tree.js";
 import { stripMarkersForCopy } from "./code-markers.js";
 import { icons as ALERT_ICONS, chevronSvg as ALERT_CHEVRON } from "./alert-icons.js";
@@ -94,7 +101,7 @@ function inline(n, ctx) {
             const variant = n.button ? buttonVariant(n.button.variant) : undefined;
             const a = {
                 // Button.astro's small size, whose text-xs replaces the base text-sm (tailwind-merge in tv()).
-                ...passthrough(n.attrs, variant ? `${BUTTON_BASE.split(" ").filter((c) => c !== "text-sm").join(" ")} ${BUTTON_VARIANTS[variant] ?? BUTTON_VARIANTS.default} h-9 px-3 text-xs no-underline` : undefined),
+                ...passthrough(n.attrs, variant ? `${BUTTON_BASE.split(" ").filter((c) => c !== "text-sm").join(" ")} ${lookup(BUTTON_VARIANTS, variant) ?? BUTTON_VARIANTS.default} h-9 px-3 text-xs no-underline` : undefined),
                 href,
                 title: n.title,
                 "data-variant": variant,
@@ -246,9 +253,27 @@ function proseHeadings(html, ctx) {
     });
 }
 // ─── Blocks ──────────────────────────────────────────────────────────
+/**
+ * The heading ids a page will use, collected on the first (outermost)
+ * renderBlocks call for a context: a side sheet's title id must yield to a
+ * heading of the same name even when the sheet comes first, or the heading's
+ * TOC entry and links would open the sheet instead (#101).
+ */
+const plannedHeadingIds = new WeakMap();
+function planHeadingIds(nodes, out) {
+    for (const n of nodes) {
+        if (n.type === "heading")
+            out.add(str(n.props?.id) ?? str(n.props?.slug) ?? slugify(inlineText(n.inline)));
+        if (n.children)
+            planHeadingIds(n.children, out);
+    }
+    return out;
+}
 export function renderBlocks(nodes, ctx) {
     if (!nodes)
         return "";
+    if (!plannedHeadingIds.has(ctx))
+        plannedHeadingIds.set(ctx, planHeadingIds(nodes, new Set()));
     let out = "";
     for (const n of nodes)
         out += block(n, ctx);
@@ -359,11 +384,11 @@ function block(n, ctx) {
             // Tight, like the Astro Step: the lead text is not wrapped in <p>.
             return `<li>${renderInline(n.inline, ctx)}${renderBlocks(n.children, ctx)}</li>`;
         case "tabs":
-            return tabs(n, ctx);
+            return renderAroundGroup(n, "tab", (g) => tabs(g, ctx), (c) => renderBlocks([c], ctx), "");
         case "tab":
             return renderBlocks(n.children, ctx);
         case "accordion":
-            return accordion(n, ctx);
+            return renderAroundGroup(n, "accordion-item", (g) => accordion(g, ctx), (c) => renderBlocks([c], ctx), "");
         case "accordion-item":
             return accordion({ type: "accordion", children: [n] }, ctx);
         case "details":
@@ -382,8 +407,21 @@ function block(n, ctx) {
             return avatar(p, ctx);
         case "example":
             return example(n, ctx);
-        case "cards":
-            return `<div${attrs(passthrough(p, "not-prose my-4 grid grid-cols-1 gap-4 sm:grid-cols-2"))}>${renderBlocks(n.children, ctx)}</div>\n`;
+        case "cards": {
+            // A group tone applies to every card that has none of its own
+            const tone = str(p.tone);
+            const kids = tone ? (n.children ?? []).map((c) => (c.type === "card" && !c.props?.tone ? { ...c, props: { ...c.props, tone } } : c)) : n.children;
+            return `<div${attrs(passthrough(p, "not-prose my-4 grid grid-cols-1 gap-4 sm:grid-cols-2"))}>${renderBlocks(kids, ctx)}</div>\n`;
+        }
+        // A scoped theme: `.dark` re-declares the tokens for its subtree (THEME_SCOPES)
+        case "theme": {
+            const scope = lookup(THEME_SCOPES, str(p.name));
+            if (!scope) {
+                ctx.unknown.add(`theme "${str(p.name) ?? ""}"`);
+                return renderBlocks(n.children, ctx);
+            }
+            return `<div${attrs({ ...passthrough(p, scope), "data-theme": str(p.name) })}>${renderBlocks(n.children, ctx)}</div>\n`;
+        }
         case "card":
             return card(n, ctx);
         case "link-card":
@@ -399,7 +437,7 @@ function block(n, ctx) {
             // `label` draws a placeholder cell in the `tone` colours, as GridItem does in the Astro pipeline.
             const label = str(p.label);
             const inner = label !== undefined
-                ? `<div class="flex h-full min-h-16 items-center justify-center rounded-lg font-mono text-sm font-medium ${TONE_CLASSES[str(p.tone) ?? "primary-light"] ?? TONE_CLASSES["primary-light"]}">${esc(label)}</div>`
+                ? `<div class="flex h-full min-h-16 items-center justify-center rounded-lg font-mono text-sm font-medium ${lookup(TONE_CLASSES, str(p.tone)) ?? TONE_CLASSES["primary-light"]}">${esc(label)}</div>`
                 : renderBlocks(n.children, ctx);
             const { label: _l, tone: _t, rowSpan: _r, ...rest } = p;
             const pass = passthrough(rest);
@@ -423,7 +461,7 @@ function block(n, ctx) {
             const href = str(p.href);
             const variant = buttonVariant(str(p.variant));
             const label = insideLink(true, ctx, () => (n.children?.length === 1 && n.children[0].type === "paragraph" ? renderInline(n.children[0].inline, ctx) : renderBlocks(n.children, ctx)));
-            return `<p><a${attrs({ ...passthrough(p, `${BUTTON_BASE} ${BUTTON_VARIANTS[variant] ?? BUTTON_VARIANTS.default} h-10 px-4 py-2 no-underline`), "data-variant": variant, "data-size": "default", href: href ? linkUrl(href, ctx) : undefined })}>${label}</a></p>\n`;
+            return `<p><a${attrs({ ...passthrough(p, `${BUTTON_BASE} ${lookup(BUTTON_VARIANTS, variant) ?? BUTTON_VARIANTS.default} h-10 px-4 py-2 no-underline`), "data-variant": variant, "data-size": "default", href: href ? linkUrl(href, ctx) : undefined })}>${label}</a></p>\n`;
         }
         case "youtube": {
             // A card linking to the video, not an embed: the page must work offline, with no request to YouTube
@@ -478,6 +516,12 @@ function block(n, ctx) {
             ctx.unknown.add("include (unresolved)");
             return `<!-- unresolved include: ${esc(target)} -->\n`;
         }
+        // Raw HTML (a one-line `<details>` body) or an importer's wrapper: known,
+        // so not reported as unknown (that warned on content that rendered fine)
+        case "html-container":
+            if (n.html && !n.children?.length)
+                return rewriteHtml(n.html, ctx);
+            return `<div${attrs(passthrough(p, "db-html-container"))}>${renderBlocks(n.children, ctx)}</div>\n`;
         default: {
             ctx.unknown.add(n.type);
             if (n.html && !n.children?.length)
@@ -739,10 +783,12 @@ function tabs(n, ctx) {
         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);
+    return tabGroup(items, ctx, passthrough(p, "my-4 w-full overflow-hidden rounded-lg border border-border"), syncKey, str(p.variant));
 }
 /** A `db-tabs` group with Tabs.astro's markup, the first tab selected. */
-export function tabGroup(items, ctx, rootAttrs, syncKey) {
+export function tabGroup(items, ctx, rootAttrs, syncKey, variant) {
+    // A variant's class strings are complete: they replace the base ones (TAB_VARIANTS)
+    const v = lookup(TAB_VARIANTS, variant);
     const group = ++ctx.seq;
     let list = "";
     let panels = "";
@@ -750,10 +796,10 @@ export function tabGroup(items, ctx, rootAttrs, syncKey) {
         const tid = `tab-${group}-${i + 1}`;
         const pid = `tabpanel-${group}-${i + 1}`;
         const sel = i === 0;
-        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>`;
+        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="${v?.trigger ?? 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({ ...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`;
+    return `<db-tabs${attrs({ ...rootAttrs, "default-value": items[0]?.value, "sync-key": syncKey })}><div data-part="list" role="tablist" aria-orientation="horizontal" class="${v?.list ?? "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) {
@@ -781,12 +827,29 @@ function accordion(n, ctx) {
 }
 // `:::details` renders as a CollapsibleAlert, as in the Astro serializer.
 function details(n, ctx) {
-    const p = (n.props ?? {});
+    let p = (n.props ?? {});
+    // A side sheet with no id takes one from its title, so a link written as for
+    // a heading opens it (#101; extractHeadings does the same for a site build)
+    if (isDetailsSheet(p) && !str(p.id)) {
+        const base = slugify(str(p.title) ?? str(p.summary) ?? "");
+        if (base) {
+            const planned = plannedHeadingIds.get(ctx);
+            let id = base;
+            for (let k = 2; planned?.has(id) || ctx.ids.has(id); k++)
+                id = `${base}-${k}`;
+            p = { ...p, id: uniqueId(ctx, id) };
+        }
+    }
     const title = str(p.title) ?? str(p.summary) ?? ctx.t("details");
     // `variant` as documented, then `type`, as the Astro pipeline reads it.
     const type = (str(p.variant) ?? str(p.type) ?? "").toLowerCase();
     const variant = ALERT_VARIANT[VARIANT_ALIAS[type] ?? type] ? VARIANT_ALIAS[type] ?? type : "note";
-    return collapsibleAlert(variant, renderInline(parseInline(title), ctx), renderBlocks(n.children, ctx), p.open != null && p.open !== false, p);
+    const html = collapsibleAlert(variant, renderInline(parseInline(title), ctx), renderBlocks(n.children, ctx), p.open != null && p.open !== false, p);
+    // `sheet`: the same details, which <db-details-sheet> opens as a side
+    // sheet when its script runs (and which stays a details when it does not)
+    if (!isDetailsSheet(p))
+        return html;
+    return `<db-details-sheet${attrs({ "close-label": ctx.t("close") || "Close" })}>${html.trimEnd()}</db-details-sheet>\n`;
 }
 function figure(n, ctx) {
     const p = (n.props ?? {});
@@ -851,7 +914,9 @@ function card(n, ctx) {
         (desc ? `<p class="m-0 mt-1 text-sm text-muted-foreground [text-decoration:none]">${renderInline(parseInline(desc), ctx)}</p>` : "") +
         // Body blocks in the same description wrapper as the Astro pipeline's card (a <div>: they carry their own <p>).
         (n.children?.length ? `<div class="text-sm text-muted-foreground mt-1 [text-decoration:none]">${renderBlocks(n.children, ctx)}</div>` : ""));
-    const cls = `rounded-lg border bg-card p-4 text-card-foreground shadow-sm${href ? " transition-colors hover:border-foreground/20" : ""}`;
+    // A tone (TONES) replaces the card's background and border colour
+    const toned = lookup(CARD_TONE_CLASSES, str(p.tone));
+    const cls = `rounded-lg border ${toned ?? "bg-card"} p-4 text-card-foreground shadow-sm${href ? ` transition-colors ${toned ? "hover:shadow-md" : "hover:border-foreground/20"}` : ""}`;
     return href
         ? `<div${attrs(passthrough(p, cls))}><div class="p-0"><a href="${esc(linkUrl(href, ctx))}" class="block text-foreground [text-decoration:none]">${inner}</a></div></div>`
         : `<div${attrs(passthrough(p, cls))}><div class="p-0">${inner}</div></div>`;

package/dist/tone-classes.d.ts

@@ -1 +1,9 @@
 export declare const TONE_CLASSES: Record<string, string>;
+export declare const TONES: readonly ["info", "success", "warning", "danger"];
+export declare const CARD_TONE_CLASSES: Record<string, string>;
+export declare const TAB_VARIANTS: Record<string, {
+    list: string;
+    trigger: string;
+}>;
+export declare const THEME_SCOPES: Record<string, string>;
+export declare function lookup<T>(table: Record<string, T>, key: unknown): T | undefined;

package/dist/tone-classes.js

@@ -1,4 +1,4 @@
-// Generated by packages/render-html/scripts/sync-sources.mjs from @dogsbay/format-astro TONE_CLASSES. Do not edit.
+// Generated by packages/render-html/scripts/sync-sources.mjs from @dogsbay/format-astro tone-classes.ts. Do not edit.
 export const TONE_CLASSES = {
     "primary": "bg-primary text-primary-foreground",
     "primary-strong": "bg-primary/80 text-primary-foreground",
@@ -13,3 +13,26 @@ export const TONE_CLASSES = {
     "purple": "bg-purple-500/15 text-purple-700 dark:text-purple-300",
     "red": "bg-red-500/15 text-red-700 dark:text-red-300"
 };
+export const TONES = ["info", "success", "warning", "danger"];
+export const CARD_TONE_CLASSES = {
+    "info": "border-info/50 bg-info/5",
+    "success": "border-success/50 bg-success/5",
+    "warning": "border-warning/50 bg-warning/5",
+    "danger": "border-danger/50 bg-danger/5"
+};
+export const TAB_VARIANTS = {
+    "pills": {
+        "list": "flex flex-wrap items-center gap-2 border-b-0 border-transparent bg-transparent p-0 px-3 pt-3 pb-1 text-muted-foreground",
+        "trigger": "inline-flex items-center justify-center whitespace-nowrap rounded-full border border-border px-4 py-1.5 text-sm font-medium ring-offset-background transition-all focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50 aria-selected:border-primary aria-selected:bg-primary aria-selected:text-primary-foreground aria-selected:shadow-none"
+    },
+    "underline": {
+        "list": "flex items-center gap-6 border-b border-border bg-transparent p-0 px-4 text-muted-foreground",
+        "trigger": "-mb-px inline-flex items-center justify-center whitespace-nowrap rounded-none border-b-2 border-transparent p-0 px-0.5 pt-3 pb-2 text-sm font-medium ring-offset-background transition-all focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50 hover:text-foreground aria-selected:border-primary aria-selected:bg-transparent aria-selected:text-foreground aria-selected:shadow-none"
+    }
+};
+export const THEME_SCOPES = {
+    "dark": "dark my-6 rounded-xl border border-border bg-background p-6 text-foreground [&>:first-child]:mt-0! [&>:last-child]:mb-0!"
+};
+export function lookup(table, key) {
+    return typeof key === "string" && Object.prototype.hasOwnProperty.call(table, key) ? table[key] : undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dogsbay/render-html",
-  "version": "0.2.0-beta.121",
+  "version": "0.2.0-beta.123",
   "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",
@@ -30,9 +30,9 @@
   "dependencies": {
     "htmlparser2": "^10.1.0",
     "markdown-it": "^14.3.0",
-    "@dogsbay/format-dogsbay-md": "0.2.0-beta.121",
-    "@dogsbay/serialize-core": "0.2.0-beta.121",
-    "@dogsbay/types": "0.2.0-beta.121"
+    "@dogsbay/format-dogsbay-md": "0.2.0-beta.123",
+    "@dogsbay/serialize-core": "0.2.0-beta.123",
+    "@dogsbay/types": "0.2.0-beta.123"
   },
   "peerDependencies": {
     "katex": "^0.16.0"