@dogsbay/format-dita 0.2.0-beta.121 → 0.2.0-beta.123

package/dist/blocks.js

@@ -1,7 +1,8 @@
-import { inlineToDogsbayMd } from "@dogsbay/format-dogsbay-md";
+import { inlineToDogsbayMd } from "@dogsbay/format-dogsbay-md/browser";
 import { convertInline, elementName, idAnchor, publishImage, trimInline, textOf, inlineSafeSnippet, conrefLedgerDetail, } from "./inline.js";
 import { publishHref, publishLabel, publishLanguage, publishString } from "./types.js";
 import { anchorId } from "./anchors.js";
+import { DB_QUALIFIERS, outputTokens, youtubeId } from "./qualifiers.js";
 const isElement = (node) => node.type === "tag";
 const isNonEmptyText = (node) => node.type === "text" && node.data.trim().length > 0;
 /** DITA note @type → callout type in the dogsbay-md vocabulary. */
@@ -224,6 +225,415 @@ const convertListItems = (el, ctx, itemTag) => el.children
         item.children = children;
     return withProvenance(item, li);
 });
+/** Components an `@outputclass` `db-*` token selects, per element. */
+const DB_COMPONENTS = {
+    dl: ["db-tabs", "db-accordion", "db-cards"],
+    section: ["db-details"],
+    // A section cannot nest, and cannot hold one: these can, so a details or
+    // sheet goes inside a section (or another div) through them
+    div: ["db-details", "db-grid"],
+    sectiondiv: ["db-details", "db-grid"],
+    bodydiv: ["db-details", "db-grid"],
+    ul: ["db-files"],
+    ol: ["db-steps"],
+    // Alone in a <p>: a block component (xrefComponent)
+    xref: ["db-link-card", "db-button", "db-video"],
+};
+/** Elements without a <title>: a `db-details` one takes it from a leading `<p outputclass="db-title">`. */
+const UNTITLED_DETAILS = new Set(["div", "sectiondiv", "bodydiv"]);
+/**
+ * A `db-details` element as a collapsible block. The modifiers: `sheet` opens
+ * it as a side sheet (`drawer`, the first name, is accepted with a note);
+ * other tokens are classes. The element's id stays on the block.
+ */
+const toDetails = (el, ctx, classes, title, skip, titleId) => {
+    const props = { title: title || "Details" };
+    // The title paragraph's id (a cross-reference to it) lands on the block,
+    // or, when the block has its own, as an anchor at the start of its body
+    const ownId = el.attribs?.id ?? titleId;
+    if (ownId)
+        props.id = anchorId(ctx, ownId);
+    const q = qualify("db-details", classes, ctx);
+    Object.assign(props, q.props);
+    const tokens = (q.classes ?? "").split(" ").filter(Boolean);
+    if (tokens.includes("drawer"))
+        ctx.note("@outputclass", `"drawer" on db-details is now "sheet" — converted as a sheet`);
+    if (tokens.includes("sheet") || tokens.includes("drawer"))
+        props.sheet = true;
+    const rest = tokens.filter((c) => c !== "sheet" && c !== "drawer");
+    if (rest.length)
+        props.class = rest.join(" ");
+    const inner = { ...ctx, headingLevel: Math.min(6, ctx.headingLevel + 1) };
+    let children = convertChildren(el, inner, skip);
+    if (titleId && el.attribs?.id) {
+        const anchors = anchorNodes([titleId], ctx);
+        if (anchors.length)
+            children = prependToFirstParagraph(children, anchors) ?? [{ type: "paragraph", inline: anchors }, ...children];
+    }
+    if (children.length === 0)
+        ctx.note("@outputclass", `db-details "${props.title}" has no content`);
+    return withProvenance({ type: "details", props, children }, el);
+};
+/**
+ * `<div outputclass="db-grid cols-3">`: each child `<div>` is a cell (its
+ * `span-N` token spans columns); any other child block is a cell of its own.
+ * DITA-OT shows the cells one after another.
+ */
+const toGrid = (el, ctx, classes) => {
+    const q = qualify("db-grid", classes, ctx);
+    const props = { ...q.props, ...(q.classes ? { class: q.classes } : {}) };
+    if (el.attribs?.id)
+        props.id = anchorId(ctx, el.attribs.id);
+    const cells = [];
+    for (const child of el.children) {
+        if (!isElement(child)) {
+            if (isNonEmptyText(child))
+                cells.push({ type: "grid-item", children: [{ type: "paragraph", inline: convertInline([child], ctx) }] });
+            continue;
+        }
+        if (blockName(child, ctx) === "div") {
+            const cellProps = {};
+            const rest = [];
+            for (const t of outputTokens(child.attribs?.outputclass)) {
+                const span = /^span-(\d+)$/.exec(t);
+                if (span && DB_QUALIFIERS.gridColumns.includes(Number(span[1])))
+                    cellProps.span = Number(span[1]);
+                else if (/^[a-z0-9][a-z0-9-]*$/.test(t) && !t.startsWith("db-"))
+                    rest.push(t);
+                else
+                    ctx.note("@outputclass", `"${t}" on a db-grid cell ignored: a cell takes span-2 to span-6`);
+            }
+            if (rest.length)
+                cellProps.class = rest.join(" ");
+            if (child.attribs?.id)
+                cellProps.id = anchorId(ctx, child.attribs.id);
+            cells.push(withProvenance({ type: "grid-item", ...(Object.keys(cellProps).length ? { props: cellProps } : {}), children: convertChildren(child, ctx) }, child));
+        }
+        else {
+            const blocks = convertBlock(child, ctx);
+            if (blocks.length)
+                cells.push({ type: "grid-item", children: blocks });
+        }
+    }
+    if (!cells.length)
+        ctx.note("@outputclass", `db-grid has no cells`);
+    return withProvenance({ type: "grid", props, children: cells }, el);
+};
+/**
+ * A `<p>` holding only an `<xref outputclass="db-link-card|db-button|db-video">`
+ * (and whitespace): the block component. The href resolves exactly as the
+ * xref's would (rename, fragment, key, publish paths), because the link is
+ * converted first and read back. Undefined when the paragraph is anything
+ * else; an xref component beside other text stays a link, with a note.
+ */
+const xrefComponent = (p, ctx) => {
+    const kids = p.children.filter((c) => isElement(c) || isNonEmptyText(c));
+    const xrefs = p.children.filter((c) => isElement(c) && c.name.toLowerCase() === "xref" && /(^|\s)db-/.test(c.attribs?.outputclass ?? ""));
+    if (!xrefs.length)
+        return undefined;
+    if (kids.length !== 1) {
+        ctx.note("@outputclass", `an <xref> component must be alone in its <p> — kept as a link`);
+        return undefined;
+    }
+    const x = xrefs[0];
+    const component = dbComponent(x, ctx);
+    if (!component)
+        return undefined;
+    if (ctx.inTableCell) {
+        // A cell holds inline content only: the component would lose its link
+        ctx.note("@outputclass", `${component.name} inside a table cell — kept as a link`);
+        return undefined;
+    }
+    const link = convertInline([x], ctx).find((n) => n.type === "link");
+    if (!link?.href) {
+        ctx.note("@outputclass", `${component.name} without a resolvable href — kept as text`);
+        return undefined;
+    }
+    const title = inlineLabel(link.children);
+    const q = qualify(component.name, component.classes, ctx);
+    const props = { ...q.props, ...(q.classes ? { class: q.classes } : {}) };
+    if (component.name === "db-link-card") {
+        const desc = x.children.find((c) => isElement(c) && c.name.toLowerCase() === "desc");
+        const description = desc ? inlineLabel(convertInline(desc.children, ctx)) : "";
+        return withProvenance({ type: "link-card", props: { ...props, title: title || link.href, href: link.href, ...(description ? { description } : {}) } }, x);
+    }
+    if (component.name === "db-button") {
+        return withProvenance({ type: "link-button", props: { ...props, href: link.href }, children: [{ type: "paragraph", inline: link.children }] }, x);
+    }
+    const id = youtubeId(link.href);
+    if (!id) {
+        ctx.note("@outputclass", `db-video "${link.href}" is not a YouTube URL — kept as a link`);
+        return undefined;
+    }
+    return withProvenance({ type: "youtube", props: { ...props, id, ...(title && title !== link.href ? { title } : {}) } }, x);
+};
+/**
+ * The component an element's `@outputclass` selects: its first `db-*` token,
+ * and the remaining tokens as classes. `db-` makes the token ours: other
+ * values (DITAVAL flagging, vendor CSS) pass through untouched. A class must
+ * be `[a-z0-9-]`, so a Tailwind arbitrary value (`bg-[url(…)]`) never reaches
+ * a site build that compiles the classes it finds; others are noted and
+ * dropped. An unknown or misplaced `db-*` is noted and the element converts
+ * as plain DITA.
+ */
+const dbComponent = (el, ctx) => {
+    // `db-theme-*` is a scope, not a component (themeOf): never picked or kept as a class
+    const tokens = outputTokens(el.attribs?.outputclass);
+    const at = tokens.findIndex((t) => t.startsWith("db-"));
+    if (at < 0)
+        return undefined;
+    const name = tokens[at].toLowerCase();
+    const element = el.name.toLowerCase();
+    if (!(DB_COMPONENTS[element] ?? []).includes(name)) {
+        ctx.note("@outputclass", `"${tokens[at]}" is not a component on <${element}> — converted as plain DITA`);
+        return undefined;
+    }
+    // One component per element: a second `db-*` token is noted, not a class
+    const extra = tokens.filter((t, i) => i !== at && t.startsWith("db-"));
+    if (extra.length)
+        ctx.note("@outputclass", `${extra.map((t) => `"${t}"`).join(", ")} ignored: <${element}> is already ${name}`);
+    const rest = tokens.filter((t, i) => i !== at && !t.startsWith("db-"));
+    const safe = rest.filter((t) => /^[a-z0-9][a-z0-9-]*$/.test(t));
+    const dropped = rest.filter((t) => !safe.includes(t));
+    if (dropped.length)
+        ctx.note("@outputclass", `class ${dropped.map((t) => `"${t}"`).join(", ")} on ${name} dropped: classes are lowercase letters, digits and hyphens`);
+    return { name, ...(safe.length ? { classes: safe.join(" ") } : {}) };
+};
+export { DB_QUALIFIERS };
+/**
+ * A component's qualifier tokens as props: `pills`/`underline` on db-tabs
+ * (`variant`), `tone-*` on db-cards (`tone`) and db-details (its colour,
+ * `variant`). Props, not classes: a sanitized single page strips classes, and
+ * every renderer and exporter can implement or declare a prop. Anything else
+ * stays a free class; a `tone-` token outside the tones is noted.
+ */
+const qualify = (component, classes, ctx) => {
+    const props = {};
+    const rest = [];
+    for (const t of (classes ?? "").split(" ").filter(Boolean)) {
+        if (component === "db-tabs" && DB_QUALIFIERS.tabVariants.includes(t)) {
+            props.variant = t;
+            continue;
+        }
+        if (component === "db-button" && DB_QUALIFIERS.buttonVariants.includes(t)) {
+            if (t !== "primary")
+                props.variant = t;
+            continue;
+        }
+        const cols = /^cols-(\d+)$/.exec(t);
+        if (component === "db-grid" && cols) {
+            if (DB_QUALIFIERS.gridColumns.includes(Number(cols[1])))
+                props.cols = Number(cols[1]);
+            else
+                ctx.note("@outputclass", `"${t}": db-grid takes cols-1 to cols-6 — ignored`);
+            continue;
+        }
+        const tone = /^tone-(.+)$/.exec(t);
+        if (tone && (component === "db-cards" || component === "db-details")) {
+            if (DB_QUALIFIERS.tones.includes(tone[1]))
+                props[component === "db-details" ? "variant" : "tone"] = tone[1];
+            else
+                ctx.note("@outputclass", `"${t}" is not a tone (${DB_QUALIFIERS.tones.join(", ")}) — ignored`);
+            continue;
+        }
+        if (tone) {
+            ctx.note("@outputclass", `"${t}": ${component} takes no tone (db-cards and db-details do) — ignored`);
+            continue;
+        }
+        rest.push(t);
+    }
+    return { props, ...(rest.length ? { classes: rest.join(" ") } : {}) };
+};
+/** Elements a scoped theme (`db-theme-<name>`) applies to: containers of blocks. */
+// section and its task/reference specialisations, plus the generic containers
+const THEMED = new Set(["section", "sectiondiv", "div", "bodydiv", "example", "context", "prereq", "result", "postreq", "refsyn"]);
+/**
+ * The scoped theme an element asks for (`outputclass="db-theme-dark"`),
+ * independent of its component token. Noted when it is unknown, on an element
+ * that is not a block container, or inside a table cell.
+ */
+const themeOf = (el, ctx) => {
+    const tokens = (el.attribs?.outputclass ?? "").split(/\s+/).filter((t) => /^db-theme-/i.test(t));
+    const token = tokens[0];
+    if (!token)
+        return undefined;
+    if (tokens.length > 1)
+        ctx.note("@outputclass", `${tokens.slice(1).map((t) => `"${t}"`).join(", ")} ignored: one theme per element`);
+    const name = token.slice("db-theme-".length).toLowerCase();
+    // By @class in publish mode, so a specialised section is still a section
+    const element = blockName(el, ctx).toLowerCase();
+    if (!THEMED.has(element)) {
+        ctx.note("@outputclass", `"${token}" applies to section, sectiondiv, div, bodydiv and example — not <${element}>`);
+        return undefined;
+    }
+    if (!DB_QUALIFIERS.themes.includes(name)) {
+        ctx.note("@outputclass", `"${token}" is not a theme (${DB_QUALIFIERS.themes.join(", ")}) — content kept, unthemed`);
+        return undefined;
+    }
+    if (ctx.inTableCell) {
+        ctx.note("@outputclass", `"${token}" inside a table cell — content kept, unthemed`);
+        return undefined;
+    }
+    return name;
+};
+/** An `id` anchor the converter wrote (`<a id="x"></a>`), as opposed to other inline HTML. */
+const isIdAnchor = (n) => n.type === "html-inline" && /^<a id="[^"]*"><\/a>$/.test(n.html);
+const decodeEntities = (s) => s.replace(/&(#x[0-9a-f]+|#\d+|amp|lt|gt|quot|apos);/gi, (m, e) => {
+    const named = { amp: "&", lt: "<", gt: ">", quot: '"', apos: "'" };
+    if (named[e.toLowerCase()])
+        return named[e.toLowerCase()];
+    const code = e[1] === "x" || e[1] === "X" ? parseInt(e.slice(2), 16) : parseInt(e.slice(1), 10);
+    return Number.isFinite(code) ? String.fromCodePoint(code) : m;
+});
+/**
+ * An inline run as plain text, for a label: markup is flattened, keys keep
+ * their `+`, an image gives its alt text, a line break a space, and inline
+ * HTML (`<sub>`, a code phrase holding a link) its text. Id anchors give
+ * nothing; the caller moves them.
+ */
+const inlineLabel = (inline) => (inline ?? [])
+    .map((n) => {
+    if (isIdAnchor(n))
+        return "";
+    if (n.type === "kbd")
+        return n.keys.join("+");
+    if (n.type === "image")
+        return n.alt ?? "";
+    if (n.type === "break")
+        return " ";
+    if (n.type === "html-inline")
+        return decodeEntities(n.html.replace(/<[^>]*>/g, ""));
+    const node = n;
+    if (typeof node.text === "string")
+        return node.text;
+    if (Array.isArray(node.children))
+        return inlineLabel(node.children);
+    return "";
+})
+    .join("")
+    .replace(/\s+/g, " ")
+    .trim();
+/**
+ * The entries of a component `<dl>` (`db-tabs`, `db-accordion`, `db-cards`),
+ * in the shape dogsbay-md's directives parse from a definition list. Each
+ * entry is converted on its own (as convertDefList converts it: conrefs,
+ * anchors, publish filtering), since the merged list loses where an entry
+ * whose definitions were filtered out ends. Id anchors in a term (an entry
+ * `@id`) move to the start of the entry's content; those of an entry that is
+ * dropped go to the next one, or the end of the last, so a cross-reference
+ * to them still lands. A second term in one entry is noted. An entry with no
+ * content is dropped unless `keepEmpty` (a card can be a bare link).
+ * `anchorsOut` collects the anchors instead (cards: a card's body sits inside
+ * its link, and an `<a id>` inside an `<a href>` splits the link).
+ */
+const dlComponentEntries = (el, ctx, component, keepEmpty = false, anchorsOut) => {
+    const out = [];
+    let pending = [];
+    const entries = el.children.filter((c) => isElement(c) && c.name.toLowerCase() === "dlentry");
+    for (const entry of entries) {
+        const items = convertDefList({ ...el, children: [entry] }, ctx).children ?? [];
+        const terms = items.filter((n) => n.type === "dt");
+        for (const t of terms)
+            (anchorsOut ?? pending).push(...(t.inline ?? []).filter(isIdAnchor));
+        for (const extra of terms.slice(1)) {
+            ctx.note("@outputclass", `${component} entry with several terms: "${inlineLabel(extra.inline)}" is not its label`);
+        }
+        const dt = terms[0];
+        const content = [];
+        for (const dd of items.filter((n) => n.type === "dd")) {
+            if (dd.inline?.length)
+                content.push({ type: "paragraph", inline: dd.inline });
+            content.push(...(dd.children ?? []));
+        }
+        if (!dt)
+            continue;
+        // A term whose definitions were all filtered out is not an entry
+        if (content.length === 0 && !keepEmpty)
+            continue;
+        const anchored = pending.length ? [{ type: "paragraph", inline: pending }, ...content] : content;
+        pending = [];
+        out.push({ term: (dt.inline ?? []).filter((n) => !isIdAnchor(n)), label: inlineLabel(dt.inline), content: anchored });
+    }
+    const last = out[out.length - 1];
+    if (pending.length && last)
+        last.content.push({ type: "paragraph", inline: pending });
+    return out;
+};
+/**
+ * Labels for tabs and accordion items, which a component matches by label
+ * (tabs) or value (accordion): an empty one is numbered, a repeated one
+ * suffixed, each with a note.
+ */
+const uniqueLabels = (entries, ctx, component, unit) => {
+    const used = new Set();
+    return entries.map((entry, i) => {
+        let label = entry.label;
+        if (!label) {
+            label = `${unit} ${i + 1}`;
+            ctx.note("@outputclass", `${component} term with no text — labelled "${label}"`);
+        }
+        if (used.has(label)) {
+            let n = 2;
+            while (used.has(`${label} (${n})`))
+                n++;
+            ctx.note("@outputclass", `${component} label "${label}" repeated — shown as "${label} (${n})"`);
+            label = `${label} (${n})`;
+        }
+        used.add(label);
+        return label;
+    });
+};
+/** `<dl outputclass="db-tabs">`: each entry is a tab, its term the label. */
+const dlToTabs = (el, ctx) => {
+    const entries = dlComponentEntries(el, ctx, "db-tabs");
+    const labels = uniqueLabels(entries, ctx, "db-tabs", "Tab");
+    const tabs = entries.map((e, i) => ({ type: "tab", props: { label: labels[i] }, children: e.content }));
+    return tabs.length ? tabs : undefined;
+};
+/**
+ * A value for an accordion item: its label as a slug, by the rule dogsbay-md's
+ * `:::accordion` uses (`uniqueAccordionValue` in its parse.ts), so a published
+ * page and a migrated one give an item the same value. Empty → `item-N`.
+ */
+const itemValue = (label) => label.toLowerCase().replace(/[^\w\s-]/g, "").trim().replace(/\s+/g, "-");
+/** `<dl outputclass="db-accordion">`: each entry is a collapsible item, its term the label. */
+const dlToAccordion = (el, ctx) => {
+    const entries = dlComponentEntries(el, ctx, "db-accordion");
+    const labels = uniqueLabels(entries, ctx, "db-accordion", "Item");
+    const values = new Set();
+    let fallback = 1;
+    const items = entries.map((e, i) => {
+        const slug = itemValue(labels[i]) || `item-${fallback++}`;
+        let value = slug;
+        for (let n = 2; values.has(value); n++)
+            value = `${slug}-${n}`;
+        values.add(value);
+        return { type: "accordion-item", props: { value, label: labels[i] }, children: e.content };
+    });
+    return items.length ? items : undefined;
+};
+/**
+ * `<dl outputclass="db-cards">`: each entry is a card, its term the title.
+ * A term that is exactly one link (`<dt><xref href="install.dita">Install</xref></dt>`)
+ * makes the card a link to that target; any other term is a title only. A
+ * card may have no definition (a bare link card), but not no title.
+ */
+const dlToCards = (el, ctx, anchors) => {
+    const cards = [];
+    for (const e of dlComponentEntries(el, ctx, "db-cards", true, anchors)) {
+        const parts = e.term.filter((n) => !(n.type === "text" && !n.text.trim()));
+        const link = parts.length === 1 && parts[0].type === "link" ? parts[0] : undefined;
+        if (!e.label) {
+            ctx.note("@outputclass", `db-cards term with no text — entry dropped`);
+            continue;
+        }
+        const props = { title: e.label };
+        if (link?.href)
+            props.href = link.href;
+        cards.push({ type: "card", props, ...(e.content.length ? { children: e.content } : {}) });
+    }
+    return cards.length ? cards : undefined;
+};
 const convertDefList = (el, ctx, tags = { entry: "dlentry", term: "dt", def: "dd" }) => {
     const children = [];
     for (const entry of el.children.filter(isElement)) {
@@ -354,7 +764,7 @@ const convertTable = (el, ctx) => {
             // Cell content always lives in children (leading inline wrapped as a
             // paragraph): the serializer's HTML-table path reads only children,
             // and its pipe path reads children paragraphs too
-            const { inline, children } = mixedContent(cellEl, { ...ctx, constrained: true });
+            const { inline, children } = mixedContent(cellEl, { ...ctx, constrained: true, inTableCell: true });
             const cellChildren = [];
             if (inline)
                 cellChildren.push({ type: "paragraph", inline });
@@ -709,6 +1119,17 @@ const ANCHORED_ELSEWHERE = new Set(["title", "related-links", "prolog", "data",
  * DITA-OT's pages. (Headings carry their own id.)
  */
 export function convertBlock(el, ctx) {
+    const out = convertBlockAnchored(el, ctx);
+    // A scoped theme wraps the element's whole output, its anchor included
+    const theme = /(^|\s)db-theme-/i.test(el.attribs?.outputclass ?? "") ? themeOf(el, ctx) : undefined;
+    if (!theme || !out.length)
+        return out;
+    // The element's own id anchor stays outside the band: inside, it would be
+    // the band's first child and take the first-child margin trim meant for content
+    const lead = out[0].type === "html" && /^<a id="[^"]*"><\/a>$/.test(out[0].html ?? "") ? [out[0]] : [];
+    return [...lead, { type: "theme", props: { name: theme }, children: out.slice(lead.length) }];
+}
+function convertBlockAnchored(el, ctx) {
     const out = convertBlockContent(el, ctx);
     const id = el.attribs?.id;
     if (!ctx.publish || !id || ANCHORED_ELSEWHERE.has(blockName(el, ctx)))
@@ -717,8 +1138,8 @@ export function convertBlock(el, ctx) {
     // An empty paragraph or division still keeps its id (DITA-OT writes the empty element)
     if (out.length === 0)
         return KEEPS_EMPTY.has(blockName(el, ctx)) ? [{ type: "html", html: idAnchor(anchor) }] : out;
-    // A titled section's heading carries the id
-    if (out.some((n) => n.type === "heading" && n.props?.id === anchor))
+    // A titled section's heading (or a db-details block) carries the id itself
+    if (out.some((n) => n.props?.id === anchor))
         return out;
     // Before a paragraph, the anchor is the start of its text (a separate block would be a paragraph of its own)
     if (out[0].type === "paragraph" && out[0].inline) {
@@ -816,6 +1237,33 @@ function convertBlockContent(el, ctx) {
             ];
         }
     }
+    // `<div|sectiondiv|bodydiv outputclass="db-details">`, titled by a leading
+    // `<p outputclass="db-title">` (a visible first line in DITA-OT's output)
+    if (UNTITLED_DETAILS.has(name) && /(^|\s)db-/.test(el.attribs?.outputclass ?? "")) {
+        const component = dbComponent(el, ctx);
+        if (component?.name === "db-details" && ctx.inTableCell) {
+            // A table cell cannot hold a collapsible block (the HTML-table form
+            // dropped it, title and all): keep its content, title included
+            ctx.note("@outputclass", `db-details inside a table cell — kept as its content`);
+        }
+        else if (component?.name === "db-details") {
+            // The first element, past whitespace, comments and processing
+            // instructions (an editor's <?oxy_comment_start?>), may be the title
+            const first = el.children.find((c) => isElement(c) || (c.type === "text" && (c.data ?? "").trim() !== ""));
+            const titleP = first && isElement(first) && blockName(first, ctx) === "p" && /(^|\s)db-title(\s|$)/.test(first.attribs?.outputclass ?? "") ? first : undefined;
+            // A conref'd title is pulled like a section title's
+            const title = titleP ? inlineLabel(constrainedConrefInline(titleP, ctx) ?? convertInline(titleP.children, ctx)) : "";
+            if (!title)
+                ctx.note("@outputclass", `db-details on <${name}> has no leading <p outputclass="db-title"> with text — titled "Details"`);
+            return [toDetails(el, ctx, component.classes, title, new Set(titleP ? [titleP] : []), titleP?.attribs?.id)];
+        }
+        else if (component?.name === "db-grid" && ctx.inTableCell) {
+            ctx.note("@outputclass", `db-grid inside a table cell — kept as its content`);
+        }
+        else if (component?.name === "db-grid") {
+            return [toGrid(el, ctx, component.classes)];
+        }
+    }
     if (TRANSPARENT_CONTAINERS.has(name)) {
         // Publishing: a topic body starts with the topic's "Prerequisites" links, when it has any
         const topicId = el.parent?.attribs?.id;
@@ -830,6 +1278,13 @@ function convertBlockContent(el, ctx) {
     switch (name) {
         case "p":
         case "shortdesc": {
+            // A link card, button or video: an xref component alone in its paragraph
+            const xc = name === "p" ? xrefComponent(el, ctx) : undefined;
+            if (xc) {
+                // Publishing: the xref's own id (a link target) as an anchor before the component
+                const anchors = anchorNodes([el.children.find((c) => isElement(c) && c.name.toLowerCase() === "xref")?.attribs?.id], ctx);
+                return anchors.length ? [{ type: "paragraph", inline: anchors }, xc] : [xc];
+            }
             // DITA allows blocks (ul, note, pre, …) inside <p>: leading inline
             // becomes the paragraph, block children follow as siblings
             const { inline, children } = mixedContent(el, ctx);
@@ -864,11 +1319,13 @@ function convertBlockContent(el, ctx) {
         case "screen":
         case "msgblock": {
             const outputclass = el.attribs?.outputclass ?? "";
-            // Publishing: DITA-OT's language classes (language-xml, syntax-bash)
-            // name the language; other output classes are not languages
-            const language = ctx.publish
-                ? (/(?:^|\s)(?:language|syntax)-(\S+)/.exec(outputclass)?.[1] ?? "")
-                : outputclass;
+            // DITA-OT's language classes (language-xml, syntax-bash) name the
+            // language in both modes. Publishing reads only those; migration also
+            // takes a bare first token (outputclass="python"), the older convention
+            const prefixed = /(?:^|\s)(?:language|syntax)-(\S+)/.exec(outputclass)?.[1];
+            const bare = outputclass.trim().split(/\s+/)[0] ?? "";
+            const language = prefixed
+                ?? (!ctx.publish && /^[A-Za-z0-9][\w+#.-]*$/.test(bare) ? bare : "");
             const content = textOf(el.children).replace(/^\n/, "").replace(/\s+$/, "");
             // Content in BOTH html and props.code: the serializer's block path
             // reads html, its HTML-table path (code inside cells) reads props.code
@@ -879,10 +1336,29 @@ function convertBlockContent(el, ctx) {
             };
             return [withProvenance(node, el)];
         }
-        case "ul":
-            return [withProvenance({ type: "unordered-list", children: convertListItems(el, ctx, "li") }, el)];
-        case "ol":
-            return [withProvenance({ type: "ordered-list", children: convertListItems(el, ctx, "li") }, el)];
+        case "ul": {
+            const list = withProvenance({ type: "unordered-list", children: convertListItems(el, ctx, "li") }, el);
+            // A file tree: folders are items with a nested list, or end in "/"
+            if (dbComponent(el, ctx)?.name === "db-files") {
+                if (!ctx.inTableCell)
+                    return [{ type: "files", children: [list] }];
+                ctx.note("@outputclass", `db-files inside a table cell — kept as a list`);
+            }
+            return [list];
+        }
+        case "ol": {
+            const items = convertListItems(el, ctx, "li");
+            // Steps outside a task: each item a numbered, connected step
+            if (dbComponent(el, ctx)?.name === "db-steps") {
+                if (!ctx.inTableCell) {
+                    // An item stays itself (its id, its provenance) as a step
+                    const steps = items.map((it) => ({ ...it, type: "step" }));
+                    return [withProvenance({ type: "steps", children: steps }, el)];
+                }
+                ctx.note("@outputclass", `db-steps inside a table cell — kept as a numbered list`);
+            }
+            return [withProvenance({ type: "ordered-list", children: items }, el)];
+        }
         case "sl": {
             // Simple list → unordered list of <sli> items (same conref hooks
             // as <li>: referencing items include or ledger, defining items
@@ -898,8 +1374,27 @@ function convertBlockContent(el, ctx) {
             });
             return [withProvenance({ type: "unordered-list", children: items }, el)];
         }
-        case "dl":
+        case "dl": {
+            const component = dbComponent(el, ctx);
+            if (component) {
+                // Card entries' id anchors go before the grid, not inside a card's link
+                const anchors = [];
+                const [type, build] = {
+                    "db-tabs": ["tabs", dlToTabs],
+                    "db-accordion": ["accordion", dlToAccordion],
+                    "db-cards": ["cards", (e, c) => dlToCards(e, c, anchors)],
+                }[component.name];
+                const children = build(el, ctx);
+                if (children) {
+                    const q = qualify(component.name, component.classes, ctx);
+                    const props = { ...q.props, ...(q.classes ? { class: q.classes } : {}) };
+                    const group = withProvenance({ type, ...(Object.keys(props).length ? { props } : {}), children }, el);
+                    return anchors.length ? [{ type: "paragraph", inline: anchors }, group] : [group];
+                }
+                ctx.note("@outputclass", `${component.name} on a <dl> with no usable entry — kept as a definition list`);
+            }
             return [withProvenance(convertDefList(el, ctx), el)];
+        }
         case "parml":
             // Parameter list — structurally a definition list
             return [withProvenance(convertDefList(el, ctx, { entry: "plentry", term: "pt", def: "pd" }), el)];
@@ -996,6 +1491,18 @@ function convertBlockContent(el, ctx) {
             const titleEl = el.children
                 .filter(isElement)
                 .find((c) => blockName(c, ctx) === "title");
+            // `<section outputclass="db-details">`: a collapsible block titled by
+            // the section title (flattened to text)
+            const component = name === "section" ? dbComponent(el, ctx) : undefined;
+            if (component?.name === "db-details") {
+                if (titleEl) {
+                    const title = inlineLabel(constrainedConrefInline(titleEl, ctx) ?? convertInline(titleEl.children, ctx));
+                    if (!title)
+                        ctx.note("@outputclass", `db-details section title has no text — titled "Details"`);
+                    return [toDetails(el, ctx, component.classes, title, new Set(["title"]))];
+                }
+                ctx.note("@outputclass", `db-details on a <section> with no <title> — converted as a plain section`);
+            }
             if (titleEl) {
                 // <title conref=…/> — heading text pulled from elsewhere
                 const titleConref = constrainedConrefInline(titleEl, ctx);
@@ -1098,7 +1605,9 @@ function convertBlockContent(el, ctx) {
         }
     }
 }
-export function convertChildren(el, ctx, skip = new Set()) {
+export function convertChildren(el, ctx, 
+/** Element names, or particular child nodes, to leave out */
+skip = new Set()) {
     const out = [];
     let inlineRun = [];
     const flushInline = () => {
@@ -1110,7 +1619,7 @@ export function convertChildren(el, ctx, skip = new Set()) {
     for (const child of el.children) {
         if (isElement(child)) {
             const name = blockName(child, ctx);
-            if (skip.has(name))
+            if (skip.has(name) || skip.has(child))
                 continue;
             if (isBlockChild(child, ctx) || TRANSPARENT_CONTAINERS.has(name) || name === "title" ||
                 name === "prolog" || name === "related-links" || name === "draft-comment") {
@@ -1128,4 +1637,3 @@ export function convertChildren(el, ctx, skip = new Set()) {
     flushInline();
     return out;
 }
-//# sourceMappingURL=blocks.js.map

package/dist/conref.d.ts

@@ -25,4 +25,3 @@ export interface ConrefPlan extends ConrefPlanApi {
  * snippet naming) follows sorted keys, not discovery order.
  */
 export declare function planConrefs(files: ConrefCorpusFile[]): ConrefPlan;
-//# sourceMappingURL=conref.d.ts.map

package/dist/conref.js

@@ -19,7 +19,7 @@
  * definition-list entries).
  */
 import { parseDocument } from "htmlparser2";
-import { treeToDogsbayMd } from "@dogsbay/format-dogsbay-md";
+import { treeToDogsbayMd } from "@dogsbay/format-dogsbay-md/browser";
 import { convertBlock, convertItemContent, isBlockTarget, } from "./blocks.js";
 import { convertInline, trimInline } from "./inline.js";
 import { DITA_TOPIC_TYPES, } from "./types.js";
@@ -300,4 +300,3 @@ export function planConrefs(files) {
         },
     };
 }
-//# sourceMappingURL=conref.js.map

package/dist/index.d.ts

@@ -16,4 +16,5 @@ export { DITA_TOPIC_TYPES, renameDitaHref, relativeIncludePath, type DitaConvers
 export { ditaTopicToTree } from "./parse.js";
 export { ditaTopicToDogsbayMd, type DitaMarkdownResult } from "./markdown.js";
 export { planConrefs, type ConrefCorpusFile, type ConrefPlan, type ConrefSnippet, } from "./conref.js";
-//# sourceMappingURL=index.d.ts.map
+export { DB_QUALIFIERS } from "./blocks.js";
+export { checkWellFormed, type WellFormedProblem } from "./well-formed.js";