@dogsbay/format-dita 0.2.0-beta.122 → 0.2.0-beta.124

package/README.md

@@ -3,6 +3,12 @@
 Convert DITA topic XML to Dogsbay's TreeNode model — and, composed with
 `@dogsbay/format-dogsbay-md`, straight to markdown.
 
+**Browser-safe:** the package imports no Node built-ins, so it bundles for a
+browser or a Worker (a test bundles it with esbuild for `platform: "browser"`).
+Malformed XML is reported, not repaired silently: the parser would close an
+unclosed element for you, so a `<xml>` note gives the first problem and its
+line (`checkWellFormed` is exported too).
+
 ```ts
 import { ditaTopicToDogsbayMd } from "@dogsbay/format-dita";
 
@@ -21,7 +27,7 @@ dogsbay import-dita   docs/            -o content    --report topics.md
 ```
 
 Tasks become native `:::steps`, notes become callouts, CALS and
-simpletables become tables, `<xref href="x.dita">` becomes `[…](x.md)`,
+simpletables (and a reference topic's `<properties>`) become tables, `<xref href="x.dita">` becomes `[…](x.md)`,
 and `keyref` links become `key:` links. Nested or sibling topics in
 multi-topic files are emitted inline as anchored sections.
 
@@ -32,6 +38,18 @@ emit `{% include %}` so one canonical copy of reused text survives. Use
 `dogsbay import-dita --no-conref-includes` to keep conrefs on the ledger
 instead.
 
+**Specializations in raw source:** a file as authored has no `@class`, so
+an element is known only by its name, and a specialization the converter
+does not know by name (a `<troubleshooting>` topic, a hazard statement's
+items) loses its markup. `{ classDefaults: true }` fills in each missing
+`@class` from the DITA 1.3 DTD defaults first (612 elements, the table
+`DITA_CLASS_DEFAULTS`, generated by `scripts/generate-class-defaults.mjs`
+from DITA-OT's `.mod` files), as parsing against the DTDs would; the
+element then converts as what it specializes. An existing `@class` is kept;
+a name the DTDs do not declare (custom or DITA 2.0) stays unclassed, with
+one note per topic. It is off by default for now because it changes the
+output for such elements.
+
 Everything that cannot map cleanly lands in the conversion ledger instead
 of disappearing: filter attributes, table spans, semantic-inline downgrades,
 `conkeyref`, conref ranges/pushes, whole-topic conrefs, unresolved targets,

package/dist/anchors.d.ts

@@ -17,4 +17,3 @@ export declare const anchorId: (ctx: {
     topicId?: string;
     anchorIds?: Map<string, string>;
 }, id: string) => string;
-//# sourceMappingURL=anchors.d.ts.map

package/dist/anchors.js

@@ -32,4 +32,3 @@ export const renamedElementIds = (nodes) => {
 };
 /** The anchor for an element id in a topic: the id, or `topicid__elementid` when an earlier topic has it. */
 export const anchorId = (ctx, id) => (ctx.topicId !== undefined && ctx.anchorIds?.get(`${ctx.topicId}/${id}`)) || id;
-//# sourceMappingURL=anchors.js.map

package/dist/blocks.d.ts

@@ -11,6 +11,7 @@ import type { Element, AnyNode } from "domhandler";
 import type { TreeNode } from "@dogsbay/types";
 import { type InlineContext } from "./inline.js";
 import { type ConrefSiteContext, type ConrefSnippetRef } from "./types.js";
+import { DB_QUALIFIERS } from "./qualifiers.js";
 export interface BlockContext extends InlineContext {
     /** Current heading depth for <section>/<example> titles. */
     headingLevel: number;
@@ -31,6 +32,7 @@ export interface BlockContext extends InlineContext {
  * from the snippet's baked-in base level.
  */
 export declare const includeDirective: (snippet: ConrefSnippetRef, site: ConrefSiteContext, headingLevel: number) => string;
+export { DB_QUALIFIERS };
 /**
  * One <step>/<substep>'s content: <cmd> as the leading inline run, the
  * rest as block children. Shared by convertSteps (constrained context)
@@ -61,4 +63,3 @@ export declare function convertBlock(el: Element, ctx: BlockContext): TreeNode[]
 export declare function convertChildren(el: Element, ctx: BlockContext, 
 /** Element names, or particular child nodes, to leave out */
 skip?: Set<string | AnyNode>): TreeNode[];
-//# sourceMappingURL=blocks.d.ts.map

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. */
@@ -209,8 +210,14 @@ const definingItemNode = (el, ctx, type) => {
     ctx.note("@conref", `<${el.name.toLowerCase()} id="${el.attribs.id}"> is reused elsewhere via "${snippet.file}" but its content is multi-line — replace it with the include manually to keep one copy`);
     return null;
 };
+/**
+ * Whether an element is a `tag` by name or, with @class, by what it
+ * specializes: a hazard statement's <typeofhazard> is an <li>. Matching the
+ * name alone dropped such items, and their text, without a note.
+ */
+const isPart = (el, ctx, tag) => isElement(el) && elementName(el, ctx, (n) => n === tag) === tag;
 const convertListItems = (el, ctx, itemTag) => el.children
-    .filter((c) => isElement(c) && c.name.toLowerCase() === itemTag)
+    .filter((c) => isPart(c, ctx, itemTag))
     .map((li) => {
     const viaConref = itemConref(li, ctx, "list-item") ?? definingItemNode(li, ctx, "list-item");
     if (viaConref)
@@ -230,9 +237,13 @@ const DB_COMPONENTS = {
     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"],
-    sectiondiv: ["db-details"],
-    bodydiv: ["db-details"],
+    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"]);
@@ -248,7 +259,9 @@ const toDetails = (el, ctx, classes, title, skip, titleId) => {
     const ownId = el.attribs?.id ?? titleId;
     if (ownId)
         props.id = anchorId(ctx, ownId);
-    const tokens = (classes ?? "").split(" ").filter(Boolean);
+    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"))
@@ -267,6 +280,99 @@ const toDetails = (el, ctx, classes, title, skip, titleId) => {
         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
@@ -277,7 +383,8 @@ const toDetails = (el, ctx, classes, title, skip, titleId) => {
  * as plain DITA.
  */
 const dbComponent = (el, ctx) => {
-    const tokens = (el.attribs?.outputclass ?? "").split(/\s+/).filter(Boolean);
+    // `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;
@@ -298,6 +405,83 @@ const dbComponent = (el, ctx) => {
         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) => {
@@ -351,7 +535,7 @@ const inlineLabel = (inline) => (inline ?? [])
 const dlComponentEntries = (el, ctx, component, keepEmpty = false, anchorsOut) => {
     const out = [];
     let pending = [];
-    const entries = el.children.filter((c) => isElement(c) && c.name.toLowerCase() === "dlentry");
+    const entries = el.children.filter((c) => isPart(c, ctx, "dlentry"));
     for (const entry of entries) {
         const items = convertDefList({ ...el, children: [entry] }, ctx).children ?? [];
         const terms = items.filter((n) => n.type === "dt");
@@ -459,7 +643,7 @@ const dlToCards = (el, ctx, anchors) => {
 const convertDefList = (el, ctx, tags = { entry: "dlentry", term: "dt", def: "dd" }) => {
     const children = [];
     for (const entry of el.children.filter(isElement)) {
-        if (entry.name.toLowerCase() !== tags.entry)
+        if (!isPart(entry, ctx, tags.entry))
             continue;
         // Entry-level conref (<dlentry conref>): a term/definition pair can't
         // splice as an include — ledger it so the loss is never silent
@@ -469,8 +653,7 @@ const convertDefList = (el, ctx, tags = { entry: "dlentry", term: "dt", def: "dd
         }
         let entryAnchored = false;
         for (const part of entry.children.filter(isElement)) {
-            const name = part.name.toLowerCase();
-            if (name === tags.term) {
+            if (isPart(part, ctx, tags.term)) {
                 // Term-level conref (<dt conref>/<pt conref>): single-line
                 // include or ledger — never a silent empty term
                 const viaConref = constrainedConrefInline(part, ctx);
@@ -481,7 +664,7 @@ const convertDefList = (el, ctx, tags = { entry: "dlentry", term: "dt", def: "dd
                 });
                 entryAnchored = true;
             }
-            else if (name === tags.def) {
+            else if (isPart(part, ctx, tags.def)) {
                 const viaConref = constrainedConrefInline(part, ctx);
                 if (viaConref) {
                     children.push({ type: "dd", inline: viaConref });
@@ -541,12 +724,23 @@ const TABLE_PARTS = new Set([
 const hasClassToken = (el, token) => ` ${el.attribs?.class ?? ""} `.includes(` ${token} `);
 const elementChildren = (el) => el.children.filter(isElement);
 const PROPERTY_KINDS = ["proptype", "propvalue", "propdesc"];
+/**
+ * Whether an element is the reference domain's `local` (`properties`, `property`, …):
+ * by @class when DITA-OT has filled it in, else by name, as authored source has none.
+ */
+const isReference = (el, local) => hasClassToken(el, `reference/${local}`) || el.name.toLowerCase() === local;
 /** A properties table cell's column: `proptype`, or with suffix "hd" a header cell (`proptypehd`). */
-const propertyKind = (cell, suffix = "") => PROPERTY_KINDS.find((k) => hasClassToken(cell, `reference/${k}${suffix}`));
+const propertyKind = (cell, suffix = "") => PROPERTY_KINDS.find((k) => isReference(cell, `${k}${suffix}`));
+/**
+ * A properties table's cells. Exactly the cells `propertyKind` recognizes (a
+ * published cell's @class names its kind before the stentry it specializes),
+ * so a row's converted cells and its cell elements line up index for index.
+ */
+const PROPERTY_CELLS = new Set([...PROPERTY_KINDS, ...PROPERTY_KINDS.map((k) => `${k}hd`)]);
 /** A properties table's columns in use, its properties that have cells, and its header row. */
 const propertiesColumns = (el) => {
-    const header = elementChildren(el).find((c) => hasClassToken(c, "reference/prophead"));
-    const propertyRows = elementChildren(el).filter((c) => hasClassToken(c, "reference/property") && elementChildren(c).some((cell) => !!propertyKind(cell)));
+    const header = elementChildren(el).find((c) => isReference(c, "prophead"));
+    const propertyRows = elementChildren(el).filter((c) => isReference(c, "property") && elementChildren(c).some((cell) => !!propertyKind(cell)));
     const used = PROPERTY_KINDS.filter((k) => propertyRows.some((r) => elementChildren(r).some((c) => propertyKind(c) === k)) ||
         (header ? elementChildren(header).some((c) => propertyKind(c, "hd") === k) : false));
     return { used, propertyRows, ...(header ? { header } : {}) };
@@ -651,15 +845,24 @@ const convertTable = (el, ctx) => {
         }
     };
     walk(el);
-    // Publishing: a properties table's columns are the type, value and description columns
+    // A properties table's columns are the type, value and description columns
     // its header or any property uses (DITA-OT's hasType, hasValue, hasDesc); each row
     // aligns its cells to them, a property with no cells is dropped, and a header cell
-    // missing for a column in use is DITA-OT's generated label ("Type", "Value", "Description")
-    if (ctx.publish && hasClassToken(el, "reference/properties")) {
+    // missing for a column in use is DITA-OT's generated label ("Type", "Value",
+    // "Description"; localized when publishing). Authored source has no @class, so
+    // the parts are matched by name too (the walk above sees no sthead/strow then).
+    if (isReference(el, "properties")) {
         const { used, propertyRows, header } = propertiesColumns(el);
+        // A property with no cells has no row; one that reuses a row by conref is noted, not lost
+        for (const row of elementChildren(el)) {
+            if (isReference(row, "property") && !propertyRows.includes(row) && (row.attribs?.conref || row.attribs?.conkeyref)) {
+                const ref = row.attribs.conref ?? row.attribs.conkeyref;
+                ctx.note(row.attribs.conref ? "@conref" : "@conkeyref", `<property> pulls content from "${ref}" — ${conrefLedgerDetail(row.attribs, undefined, ctx.conref !== undefined)}`);
+            }
+        }
         rows.length = 0;
         for (const row of propertyRows) {
-            const converted = convertRow(row, SIMPLE_CELLS);
+            const converted = convertRow(row, PROPERTY_CELLS);
             const cellEls = elementChildren(row).filter((c) => !!propertyKind(c));
             rows.push({
                 type: "tr",
@@ -669,13 +872,10 @@ const convertTable = (el, ctx) => {
                 }),
             });
         }
-        const lang = publishLanguage(el, ctx.publish);
-        const label = {
-            proptype: publishString(ctx.publish, lang, "Type"),
-            propvalue: publishString(ctx.publish, lang, "Value"),
-            propdesc: publishString(ctx.publish, lang, "Description"),
-        };
-        const authored = header ? convertRow(header, SIMPLE_CELLS, true) : undefined;
+        const lang = ctx.publish ? publishLanguage(el, ctx.publish) : undefined;
+        const word = (w) => (ctx.publish ? publishString(ctx.publish, lang, w) : w);
+        const label = { proptype: word("Type"), propvalue: word("Value"), propdesc: word("Description") };
+        const authored = header ? convertRow(header, PROPERTY_CELLS, true) : undefined;
         const headerCells = header ? elementChildren(header).filter((c) => !!propertyKind(c, "hd")) : [];
         headRows.length = 0;
         headRows.push({
@@ -762,7 +962,7 @@ export const convertStepContent = (stepEl, ctx) => {
 const convertSteps = (el, ctx, type) => {
     const stepTag = type === "steps" ? "step" : "substep";
     const children = el.children
-        .filter((c) => isElement(c) && c.name.toLowerCase() === stepTag)
+        .filter((c) => isPart(c, ctx, stepTag))
         .map((stepEl) => {
         const viaConref = itemConref(stepEl, ctx, "step") ?? definingItemNode(stepEl, ctx, "step");
         if (viaConref)
@@ -834,7 +1034,7 @@ const publishTaskLabel = (name, ctx, el) => ctx.publish?.taskLabels && TASK_LABE
 /** Block-level DITA elements (used to split mixed content). */
 const BLOCK_ELEMENTS = new Set([
     "p", "shortdesc", "note", "codeblock", "pre", "screen", "msgblock", "ul", "ol", "sl", "dl", "parml", "table", "simpletable",
-    "fig", "image", "section", "example", "steps", "steps-unordered", "substeps", "lq", "object",
+    "properties", "fig", "image", "section", "example", "steps", "steps-unordered", "substeps", "lq", "object",
     "prereq", "context", "result", "postreq", "tasktroubleshooting", "choices", "choicetable", "syntaxdiagram",
 ]);
 const SYNTAX_GROUPS = new Set(["groupseq", "groupchoice", "groupcomp"]);
@@ -941,6 +1141,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)))
@@ -1068,6 +1279,12 @@ function convertBlockContent(el, ctx) {
                 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
@@ -1083,6 +1300,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);
@@ -1134,16 +1358,35 @@ 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
             // hand their text to the snippet)
             const items = el.children
-                .filter((c) => isElement(c) && c.name.toLowerCase() === "sli")
+                .filter((c) => isPart(c, ctx, "sli"))
                 .map((sli) => {
                 const viaConref = itemConref(sli, ctx, "list-item") ?? definingItemNode(sli, ctx, "list-item");
                 if (viaConref)
@@ -1165,7 +1408,9 @@ function convertBlockContent(el, ctx) {
                 }[component.name];
                 const children = build(el, ctx);
                 if (children) {
-                    const group = withProvenance({ type, ...(component.classes ? { props: { class: component.classes } } : {}), children }, el);
+                    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`);
@@ -1177,9 +1422,17 @@ function convertBlockContent(el, ctx) {
             return [withProvenance(convertDefList(el, ctx, { entry: "plentry", term: "pt", def: "pd" }), el)];
         case "table":
         case "simpletable":
-            // Publishing: DITA-OT drops a properties table none of whose properties has a cell
-            if (ctx.publish && hasClassToken(el, "reference/properties") && propertiesColumns(el).propertyRows.length === 0)
+        case "properties":
+            // A properties table none of whose properties has a cell has no columns: DITA-OT drops it
+            if (isReference(el, "properties") && propertiesColumns(el).propertyRows.length === 0) {
+                if (!ctx.publish) {
+                    for (const row of elementChildren(el).filter((r) => r.attribs?.conref || r.attribs?.conkeyref)) {
+                        const ref = row.attribs.conref ?? row.attribs.conkeyref;
+                        ctx.note(row.attribs.conref ? "@conref" : "@conkeyref", `<${row.name.toLowerCase()}> pulls content from "${ref}" — ${conrefLedgerDetail(row.attribs, undefined, ctx.conref !== undefined)}`);
+                    }
+                }
                 return [];
+            }
             return [withProvenance(convertTable(el, ctx), el)];
         case "syntaxdiagram":
             if (ctx.publish)
@@ -1414,4 +1667,3 @@ skip = new Set()) {
     flushInline();
     return out;
 }
-//# sourceMappingURL=blocks.js.map

package/dist/class-defaults-apply.d.ts

@@ -0,0 +1,15 @@
+import type { AnyNode } from "domhandler";
+/** An element's DITA 1.3 default @class (`inMap`: inside a map document), or undefined for a name the DTDs do not declare. */
+export declare const classDefault: (name: string, inMap?: boolean) => string | undefined;
+/**
+ * Fill in the @class a DTD would have defaulted, on every element that has
+ * none, as parsing against the DTDs (or DITA-OT preprocessing) does. An
+ * existing @class is kept. Returns the element names the DITA 1.3 DTDs do not
+ * declare (custom specializations, DITA 2.0), in document order, each once;
+ * those stay unclassed. Not reported: the `<dita>` wrapper of a composite
+ * topic, which has no @class by design, and foreign vocabularies (a
+ * namespace prefix, or an undeclared name inside a `<foreign>`
+ * specialization: MathML, SVG), which are not DITA elements and are left
+ * untouched. A DITA element inside one (`<mathmlref>`, `<svgref>`) is classed.
+ */
+export declare function applyClassDefaults(nodes: AnyNode[]): string[];

package/dist/class-defaults-apply.js

@@ -0,0 +1,40 @@
+import { isTag } from "domhandler";
+import { DITA_CLASS_DEFAULTS, DITA_MAP_CLASS_DEFAULTS } from "./class-defaults.js";
+const own = (table, name) => Object.prototype.hasOwnProperty.call(table, name) ? table[name] : undefined;
+/** An element's DITA 1.3 default @class (`inMap`: inside a map document), or undefined for a name the DTDs do not declare. */
+export const classDefault = (name, inMap = false) => (inMap ? own(DITA_MAP_CLASS_DEFAULTS, name) : undefined) ?? own(DITA_CLASS_DEFAULTS, name);
+/**
+ * Fill in the @class a DTD would have defaulted, on every element that has
+ * none, as parsing against the DTDs (or DITA-OT preprocessing) does. An
+ * existing @class is kept. Returns the element names the DITA 1.3 DTDs do not
+ * declare (custom specializations, DITA 2.0), in document order, each once;
+ * those stay unclassed. Not reported: the `<dita>` wrapper of a composite
+ * topic, which has no @class by design, and foreign vocabularies (a
+ * namespace prefix, or an undeclared name inside a `<foreign>`
+ * specialization: MathML, SVG), which are not DITA elements and are left
+ * untouched. A DITA element inside one (`<mathmlref>`, `<svgref>`) is classed.
+ */
+export function applyClassDefaults(nodes) {
+    const root = nodes.find(isTag);
+    const inMap = !!root && (["map", "bookmap", "subjectScheme"].includes(root.name) || ` ${root.attribs?.class ?? ""} `.includes(" map/map "));
+    const unknown = new Set();
+    const visit = (el, inForeign) => {
+        if (el.name.includes(":"))
+            return;
+        if (!el.attribs?.class?.trim()) {
+            const value = classDefault(el.name, inMap);
+            if (value)
+                el.attribs = { ...el.attribs, class: value };
+            else if (el.name !== "dita" && !inForeign)
+                unknown.add(el.name);
+        }
+        const foreign = inForeign || ` ${el.attribs?.class ?? ""} `.includes(" topic/foreign ");
+        for (const child of el.children)
+            if (isTag(child))
+                visit(child, foreign);
+    };
+    for (const node of nodes)
+        if (isTag(node))
+            visit(node, false);
+    return [...unknown];
+}

package/dist/class-defaults.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Each DITA 1.3 element's default @class, as its DTD declares it. GENERATED by
+ * scripts/generate-class-defaults.mjs from the .mod files under dita-ot-4.3.5's
+ * plugins/org.oasis-open.dita.v1_3/dtd/ (612 elements); do not edit.
+ */
+export declare const DITA_CLASS_DEFAULTS: Readonly<Record<string, string>>;
+/** Elements whose class differs inside a map (map.mod declares them too). */
+export declare const DITA_MAP_CLASS_DEFAULTS: Readonly<Record<string, string>>;