@dogsbay/format-astro 0.2.0-beta.127 → 0.2.0-beta.129

package/dist/capabilities.js

@@ -27,8 +27,8 @@ export const ASTRO_CAPABILITIES = [
     { feature: "diagram", support: "full", rendersAs: "`<Diagram>` (source + pre-rendered SVG)" },
     { feature: "youtube", support: "full", rendersAs: "`<YouTube>`" },
     // ── Components ───────────────────────────────────────────
-    { feature: "callout", support: "full", rendersAs: "`<Alert variant>` with the authored type kept as `data-type`" },
-    { feature: "details", support: "full", rendersAs: "`<CollapsibleAlert variant title open icon>` (`title`, or its alias `summary`)" },
+    { feature: "callout", support: "full", rendersAs: "`<Alert variant icon>` with the authored type kept as `data-type`; `collapsed`/`collapsible` → `<CollapsibleAlert>` (a `<details>`), as render-html; the title is inline Markdown" },
+    { feature: "details", support: "full", rendersAs: "`<CollapsibleAlert variant title open icon>` (`title`, or its alias `summary`, inline Markdown in a `title` slot)" },
     { feature: "details-sheet", support: "full", rendersAs: "`<DetailsSheet>` around the CollapsibleAlert: `<db-details-sheet>` opens it as a right-hand native `<dialog>`; without the script it stays a collapsible block" },
     { feature: "theme", support: "full", rendersAs: "a `<div class=\"dark …\" data-theme>`: the theme re-declares its tokens on `.dark`, so the subtree turns dark" },
     { feature: "tabs-variant", support: "full", rendersAs: "TabsList/TabsTrigger given the variant's classes (TAB_VARIANTS), merged over their base" },

package/dist/serialize.js

@@ -176,6 +176,7 @@ export function escapeTemplate(s) {
 export function treeToAstro(nodes, options) {
     const ctx = {
         imports: new Set(),
+        diagramIds: new Map(),
         indent: 0,
         scripts: new Set(),
         mode: options?.mode ?? "template",
@@ -495,6 +496,9 @@ function templateInlineEmitters() {
             strike: (s) => `<s>${s}</s>`,
         }),
         link: (node, ctx) => {
+            // Inside a whole-card link, a link is its text (wholeCardLink)
+            if (cardLinkDepth > 0)
+                return ctx.recurse(node.children);
             // A link node an importer built directly never passed markdown-it's
             // scheme check: a `javascript:` href keeps its text and loses the link.
             if (!isSafeHref(node.href)) {
@@ -565,6 +569,8 @@ function htmlModeInlineEmitters() {
         // EXPRESSION, inside a string that becomes a `set:html` value. Astro never
         // parses it as markup, so the reader saw the braces and quotes.
         link: (node, ctx) => {
+            if (cardLinkDepth > 0)
+                return ctx.recurse(node.children);
             if (!isSafeHref(node.href)) {
                 ctx.report("link", `unsafe link target dropped (${node.href.slice(0, 40)})`);
                 return ctx.recurse(node.children);
@@ -869,13 +875,54 @@ function calloutToAstro(node, ctx) {
         "type", "variant", "title", "icon", "class",
     ]);
     const inner = childrenToAstro(node, ctx);
+    // An authored title is inline Markdown (`Before \`harbor init\``), as render-html reads it (MD-002);
+    // the default label is text
+    const titleNodes = explicitTitle && explicitTitle.length > 0 ? titleInline(title) : [{ type: "text", text: title }];
+    const plainTitle = isPlainCaption(titleNodes);
+    // `collapsed` / `collapsible`: a disclosure, as render-html draws it (MD-001)
+    if (isCollapsibleCallout(node.props)) {
+        ctx.imports.add("details");
+        const attrs = [`variant="${escapeAttr(collapsibleVariant(variant))}"`, componentAttr("title", plainTitle ? captionText(titleNodes) : title).trimStart()];
+        if (calloutStartsOpen(node.props))
+            attrs.push("open");
+        const slot = plainTitle ? "" : `\n  <Fragment slot="title">${renderInline(titleNodes, ctx)}</Fragment>`;
+        const collapsiblePassthrough = renderPassthroughAttrs(node.props, ["type", "variant", "title", "icon", "class", "collapsed", "collapsible", "open"]);
+        return `<CollapsibleAlert ${attrs.join(" ")}${iconAttr}${classAttr}${collapsiblePassthrough}>${slot}
+${indentStr(inner, 2)}
+</CollapsibleAlert>`;
+    }
     return `<Alert variant="${escapeAttr(variant)}"${iconAttr}${classAttr}${passthrough}>
-  <AlertTitle>${escapeTemplate(title)}</AlertTitle>
+  <AlertTitle>${plainTitle ? escapeTemplate(captionText(titleNodes)) : renderInline(titleNodes, ctx)}</AlertTitle>
   <AlertDescription>
 ${indentStr(inner, 4)}
   </AlertDescription>
 </Alert>`;
 }
+/**
+ * A presence flag: `open`, `open=""`, `open="true"` and `true` are on; absent, `false` and `"false"` are
+ * off. A bare `{open}` parses as "" (falsy), and "false" is truthy, so a plain truth test got both wrong
+ * (MD-003). render-html reads flags with the same rule (`flagOn`).
+ */
+function flagOn(v) {
+    return v !== undefined && v !== null && v !== false && v !== "false";
+}
+/** CollapsibleAlert's variants; `plain` is chrome (no tint, icon or role). */
+const COLLAPSIBLE_VARIANTS = new Set(["plain", "destructive", "note", "abstract", "info", "tip", "success", "question", "warning", "failure", "danger", "bug", "example", "quote"]);
+/** A disclosure's variant: lower-cased, aliases mapped, anything CollapsibleAlert does not draw → note. */
+function collapsibleVariant(raw) {
+    const v = raw.toLowerCase();
+    const mapped = CALLOUT_VARIANT_MAP[v] ?? v;
+    return COLLAPSIBLE_VARIANTS.has(mapped) ? mapped : "note";
+}
+/** A callout with `collapsible` on or any `collapsed` is a disclosure (render-html's `callout`). */
+function isCollapsibleCallout(props) {
+    return flagOn(props?.collapsible) || (props?.collapsed !== undefined && props?.collapsed !== null);
+}
+/** It starts open when `collapsed` is off (`collapsed="false"`) or `open` is on. */
+function calloutStartsOpen(props) {
+    const c = props?.collapsed;
+    return c === false || c === "false" || flagOn(props?.open);
+}
 /**
  * Merge a default class string with an optional user-provided class string.
  * Concatenates (user classes appended) so utility frameworks like Tailwind
@@ -1016,13 +1063,17 @@ function genericContainerToAstro(node, ctx) {
 function detailsToAstro(node, ctx) {
     ctx.imports.add("details");
     // `variant` as documented; `type` as dogsbay-ssg (and callouts) read it.
-    const variant = node.props?.variant ?? node.props?.type ?? "note";
+    // Aliases (`caution` → danger) and unknown names (→ note) as render-html maps them
+    const variant = collapsibleVariant(node.props?.variant ?? node.props?.type ?? "note");
     // `summary` is dogsbay-md's alias for the title (`:::details{summary="…"}`)
     const title = node.props?.title ?? node.props?.summary ?? "Details";
-    const open = node.props?.open;
+    const open = flagOn(node.props?.open);
     const icon = node.props?.icon;
     const inner = childrenToAstro(node, ctx);
-    const attrs = [`variant="${escapeAttr(variant)}"`, componentAttr("title", title).trimStart()];
+    // The title is inline Markdown, as in render-html: plain text stays the `title` prop
+    const titleNodes = titleInline(title);
+    const plainTitle = isPlainCaption(titleNodes);
+    const attrs = [`variant="${escapeAttr(variant)}"`, componentAttr("title", plainTitle ? captionText(titleNodes) : title).trimStart()];
     if (open)
         attrs.push("open");
     if (icon)
@@ -1031,7 +1082,8 @@ function detailsToAstro(node, ctx) {
     const passthrough = renderPassthroughAttrs(node.props, [
         "variant", "type", "title", "open", "icon", "class", "summary", "sheet",
     ]);
-    const alert = `<CollapsibleAlert ${attrs.join(" ")}${classAttr}${passthrough}>
+    const slot = plainTitle ? "" : `\n  <Fragment slot="title">${renderInline(titleNodes, ctx)}</Fragment>`;
+    const alert = `<CollapsibleAlert ${attrs.join(" ")}${classAttr}${passthrough}>${slot}
 ${indentStr(inner, 2)}
 </CollapsibleAlert>`;
     // `sheet`: the same details, opened as a side sheet by <db-details-sheet>
@@ -1117,10 +1169,25 @@ function captionInline(caption) {
     return parseInline(caption);
 }
 const isPlainCaption = (nodes) => nodes.every((n) => n.type === "text" && !n.bold && !n.italic && !n.strikethrough);
+/**
+ * Formatting tags with no attributes, the HTML a title keeps (a raw `<details><summary><code>x</code>`
+ * becomes the title `<code>x</code>`). render-html has the same list.
+ */
+const TITLE_TAG = /^<\/?(?:code|kbd|b|strong|i|em|s|del|mark|sub|sup|br)\s*\/?>$/i;
+/**
+ * A callout or details title: inline Markdown, and any other raw HTML is TEXT. Importers write
+ * plain-text titles with angle brackets (`Map<K, V>`, `List<String>`), which as HTML dropped words,
+ * and a title with `<img onerror=…>` ran a script in the summary. render-html reads titles the same way.
+ */
+function titleInline(title) {
+    return captionInline(title).map((n) => (n.type === "html-inline" && !TITLE_TAG.test(n.html.trim()) ? { type: "text", text: n.html } : n));
+}
+/** A plain caption's text (escapes undone by the parse). */
+const captionText = (nodes) => nodes.map((n) => (n.type === "text" ? n.text : "")).join("");
 function captionToAstro(caption, ctx) {
     const nodes = captionInline(caption);
     return isPlainCaption(nodes)
-        ? escapeTemplate(nodes.map((n) => (n.type === "text" ? n.text : "")).join(""))
+        ? escapeTemplate(captionText(nodes))
         : renderInline(nodes, ctx);
 }
 function tableToAstro(node, ctx) {
@@ -1141,8 +1208,18 @@ function diagramToAstro(node, ctx) {
     ctx.imports.add("diagram");
     const lang = node.props?.lang || "mermaid";
     const code = node.props?.code ?? "";
-    const svg = node.props?.svg ?? "";
+    let svg = node.props?.svg ?? "";
     const title = node.props?.title;
+    // A Pele SVG's ids (`<prefix>-title`, `<prefix>-desc`, for aria-labelledby) are unique within
+    // its source page. A book view or an include can show the same diagram twice on one page, so
+    // the later copies are renamed; the prefix appears nowhere else in the SVG.
+    const prefix = /^<svg[^>]*\bclass="pele\b/.test(svg) ? /\sid="(dg-[0-9a-f]{12}(?:-\d+)?)-/.exec(svg)?.[1] : undefined;
+    if (prefix) {
+        const n = (ctx.diagramIds.get(prefix) ?? 0) + 1;
+        ctx.diagramIds.set(prefix, n);
+        if (n > 1)
+            svg = svg.split(prefix).join(`${prefix}-p${n}`);
+    }
     const attrs = [`lang="${escapeAttr(lang)}"`, `code={${escapeExpr(code)}}`, `svg={${escapeExpr(svg)}}`];
     if (title)
         attrs.push(componentAttr("title", title).trimStart());
@@ -1364,6 +1441,25 @@ function endpointToAstro(node, ctx) {
         `  <ApiCodePanel slot="code">${codeBody}</ApiCodePanel>\n` +
         `</ApiLayout>`);
 }
+/**
+ * Whole-card links being emitted. Inside one, a link in the card's body is its text: a browser
+ * ends the outer <a> at an inner one, so the rest of the card fell out of the link (and lost
+ * not-prose). The serializer is synchronous, so a depth count is enough.
+ */
+let cardLinkDepth = 0;
+function wholeCardLink(yes, fn) {
+    if (!yes)
+        return fn();
+    cardLinkDepth++;
+    try {
+        return fn();
+    }
+    finally {
+        cardLinkDepth--;
+    }
+}
+/** A card's title: not-prose, or docs.css's h3 rule (1.25rem, 2rem above) applies inside the card. */
+const CARD_TITLE_CLASS = "not-prose m-0 border-0 p-0 text-base font-semibold";
 function cardsToAstro(node, ctx) {
     ctx.imports.add("grid");
     ctx.imports.add("card");
@@ -1382,9 +1478,9 @@ function cardsToAstro(node, ctx) {
             const icon = card.props?.icon;
             // Description sources: inline content, children, or props.description.
             // Child blocks carry their own <p>, so they get a <div>: <p><p>…</p></p> is invalid HTML.
-            const blocks = childrenToAstro(card, ctx);
+            const blocks = wholeCardLink(!!href, () => childrenToAstro(card, ctx));
             const inner = blocks
-                || (card.inline ? inlineToTemplate(card.inline) : "")
+                || (card.inline ? wholeCardLink(!!href, () => inlineToTemplate(card.inline)) : "")
                 || (description ? escapeTemplate(description) : "");
             const descTag = blocks ? "div" : "p";
             // Icon renders inline before the title — picks up Lucide
@@ -1396,7 +1492,7 @@ function cardsToAstro(node, ctx) {
             if (icon) {
                 iconHtml = cardIconHtml(icon, title, ctx);
             }
-            const titleHtml = title ? `<h3 class="text-base font-semibold">${escapeTemplate(title)}</h3>` : "";
+            const titleHtml = title ? `<h3 class="${CARD_TITLE_CLASS}">${escapeTemplate(title)}</h3>` : "";
             // A description and a body are both shown (the description used to be dropped when a body existed).
             const lead = blocks && description
                 ? `<p class="text-sm text-muted-foreground mt-1 [text-decoration:none]">${escapeTemplate(description)}</p>`
@@ -1415,7 +1511,7 @@ function cardsToAstro(node, ctx) {
                 "title", "href", "description", "icon", "variant", "class", "tone",
             ]);
             if (href) {
-                return `<Card${cardClassAttr}${cardPass}>\n<CardContent class="p-0">\n<a href="${escapeAttr(href)}" class="[text-decoration:none] text-foreground">\n${iconHtml}\n${titleHtml}\n${desc}\n</a>\n</CardContent>\n</Card>`;
+                return `<Card${cardClassAttr}${cardPass}>\n<CardContent class="p-0">\n<a href="${escapeAttr(href)}" class="not-prose [text-decoration:none] text-foreground">\n${iconHtml}\n${titleHtml}\n${desc}\n</a>\n</CardContent>\n</Card>`;
             }
             return `<Card${cardClassAttr}${cardPass}>\n<CardContent class="p-0">\n${iconHtml}\n${titleHtml}\n${desc}\n</CardContent>\n</Card>`;
         }).join("\n");
@@ -1448,9 +1544,9 @@ function standaloneCardToAstro(node, ctx) {
     const description = node.props?.description;
     const icon = node.props?.icon;
     // Child blocks carry their own <p>, so they get a <div>: <p><p>…</p></p> is invalid HTML.
-    const blocks = childrenToAstro(node, ctx);
+    const blocks = wholeCardLink(!!href, () => childrenToAstro(node, ctx));
     const inner = blocks
-        || (node.inline ? inlineToTemplate(node.inline) : "")
+        || (node.inline ? wholeCardLink(!!href, () => inlineToTemplate(node.inline)) : "")
         || (description ? escapeTemplate(description) : "");
     const descTag = blocks ? "div" : "p";
     // Icon renders inline before the title (same shape as the
@@ -1461,7 +1557,7 @@ function standaloneCardToAstro(node, ctx) {
         iconHtml = `<Icon name="${escapeAttr(icon)}" class="size-5 mb-2 text-muted-foreground" />`;
     }
     const titleHtml = title
-        ? `<h3 class="text-base font-semibold">${escapeTemplate(title)}</h3>`
+        ? `<h3 class="${CARD_TITLE_CLASS}">${escapeTemplate(title)}</h3>`
         : "";
     // A description and a body are both shown (the description used to be dropped when a body existed).
     const lead = blocks && description
@@ -1480,7 +1576,7 @@ function standaloneCardToAstro(node, ctx) {
         "title", "href", "description", "icon", "variant", "class", "tone",
     ]);
     if (href) {
-        return `<Card${classAttr}${passthrough}>\n<CardContent class="p-0">\n<a href="${escapeAttr(href)}" class="[text-decoration:none] text-foreground">\n${iconHtml}\n${titleHtml}\n${desc}\n</a>\n</CardContent>\n</Card>`;
+        return `<Card${classAttr}${passthrough}>\n<CardContent class="p-0">\n<a href="${escapeAttr(href)}" class="not-prose [text-decoration:none] text-foreground">\n${iconHtml}\n${titleHtml}\n${desc}\n</a>\n</CardContent>\n</Card>`;
     }
     return `<Card${classAttr}${passthrough}>\n<CardContent class="p-0">\n${iconHtml}\n${titleHtml}\n${desc}\n</CardContent>\n</Card>`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dogsbay/format-astro",
-  "version": "0.2.0-beta.127",
+  "version": "0.2.0-beta.129",
   "description": "Astro format plugin for Dogsbay — export TreeNode[] to Astro component markup",
   "type": "module",
   "main": "dist/index.js",
@@ -32,12 +32,12 @@
   "license": "MIT",
   "dependencies": {
     "markdown-it": "^14.3.0",
-    "@dogsbay/format-dogsbay-md": "0.2.0-beta.127",
-    "@dogsbay/serialize-core": "0.2.0-beta.127",
-    "@dogsbay/site-files": "0.2.0-beta.127",
-    "@dogsbay/render-html": "0.2.0-beta.127",
-    "@dogsbay/types": "0.2.0-beta.127",
-    "@dogsbay/ui": "0.2.0-beta.127"
+    "@dogsbay/format-dogsbay-md": "0.2.0-beta.129",
+    "@dogsbay/serialize-core": "0.2.0-beta.129",
+    "@dogsbay/render-html": "0.2.0-beta.129",
+    "@dogsbay/site-files": "0.2.0-beta.129",
+    "@dogsbay/types": "0.2.0-beta.129",
+    "@dogsbay/ui": "0.2.0-beta.129"
   },
   "repository": {
     "type": "git",