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

package/css/docs.css

@@ -91,7 +91,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/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,115 @@
+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: "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: "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/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

@@ -9,3 +9,4 @@ export * from "./render.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

@@ -9,3 +9,4 @@ export * from "./render.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";

package/dist/render.js

@@ -1,3 +1,10 @@
+/**
+ * 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";
@@ -359,11 +366,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":
@@ -478,6 +485,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)
@@ -786,7 +799,12 @@ function details(n, ctx) {
     // `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 ?? {});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dogsbay/render-html",
-  "version": "0.2.0-beta.121",
+  "version": "0.2.0-beta.122",
   "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.122",
+    "@dogsbay/serialize-core": "0.2.0-beta.122",
+    "@dogsbay/types": "0.2.0-beta.122"
   },
   "peerDependencies": {
     "katex": "^0.16.0"