@dogsbay/format-dogsbay-md 0.2.0-beta.137 → 0.2.0-beta.138

package/dist/data-directives.js

@@ -192,9 +192,19 @@ export function literalCode(value) {
 }
 const list = (v) => typeof v === "string" && v.trim() ? v.split(",").map((s) => s.trim()) : undefined;
 function tableNode(rows, props, file) {
+    // A page never shows an empty table (docs/data-files.md): a file with no entries is reported.
+    if (rows.length === 0)
+        throw new DirectiveError(`${file} has no entries to show`);
     const columns = list(props.columns) ?? [...new Set(rows.flatMap((r) => Object.keys(r)))];
     if (columns.length === 0)
         throw new DirectiveError(`${file} has no columns to show`);
+    // A column no row has is a typo, not an optional field: it showed as an empty column.
+    const known = [...new Set(rows.flatMap((r) => Object.keys(r)))];
+    const missing = columns.filter((c) => !known.includes(c));
+    if (missing.length > 0) {
+        const has = known.length === 0 ? "it has no fields" : `it has ${known.slice(0, 12).join(", ")}${known.length > 12 ? `, … ${known.length - 12} more` : ""}`;
+        throw new DirectiveError(`${file} has no ${missing.map((c) => `"${c}"`).join(", ")} column (${has})`);
+    }
     const headers = list(props.headers) ?? columns;
     if (headers.length !== columns.length) {
         throw new DirectiveError(`headers names ${headers.length} column(s), columns ${columns.length}`);

package/dist/diagnostics.d.ts

@@ -2,7 +2,7 @@ export interface ParseDiagnostic {
     /** 1-based line in the source (front matter counted). */
     line: number;
     /** Stable kind, for filtering. */
-    code: "unclosed-container" | "stray-closer" | "unknown-container" | "unknown-inline" | "block-directive-inline" | "bad-attributes" | "closer-mismatch" | "dropped-attributes" | "missing-label" | "leaf-as-block" | "nesting-unchecked";
+    code: "unclosed-container" | "stray-closer" | "unknown-container" | "unknown-inline" | "block-directive-inline" | "bad-attributes" | "closer-mismatch" | "dropped-attributes" | "missing-label" | "leaf-as-block" | "nesting-unchecked" | "unknown-prop";
     message: string;
     /**
      * The directive's name, without colons, on `unknown-container` and `unknown-inline`: a host that

package/dist/diagnostics.js

@@ -10,6 +10,8 @@
  */
 import { BLOCK_LEAF_DIRECTIVES, GENERIC_CONTAINER } from "./plugin-containers.js";
 import { LABEL_PROP } from "./plugin-inline-directives.js";
+import { unknownProps } from "./directive-props.js";
+import * as yaml from "js-yaml";
 /**
  * Whether a source line closes a container opened with `colons` colons. The
  * line may sit in a blockquote or a list item: its `>` markers and
@@ -119,6 +121,22 @@ const clip = (line) => {
     const t = (line ?? "").trim();
     return t.length > 60 ? `${t.slice(0, 59)}…` : t;
 };
+/** The keys of a known container's parsed attrs (`tok.meta.attrs`), the lifted YAML block's included. */
+function propKeysOfAttrs(props) {
+    const keys = Object.keys(props).filter((k) => k !== "__yaml__");
+    const encoded = props.__yaml__;
+    if (typeof encoded === "string") {
+        try {
+            const loaded = yaml.load(decodeURIComponent(encoded));
+            if (loaded && typeof loaded === "object" && !Array.isArray(loaded))
+                keys.push(...Object.keys(loaded));
+        }
+        catch {
+            /* not YAML: nothing to check */
+        }
+    }
+    return keys;
+}
 export function collectDiagnostics(tokens, lines, lineOf) {
     const out = [];
     const add = (line0, code, message, name) => {
@@ -167,6 +185,16 @@ export function collectDiagnostics(tokens, lines, lineOf) {
                 else if (generic) {
                     add(tok.map[0], "unknown-container", `:::${name} is not a known directive — it is shown as a plain box`, name);
                 }
+                else {
+                    // A prop no renderer of this directive reads is carried, never drawn: say so (a typo
+                    // in a `{…}` or `---` block was silent). Keys from both forms; the YAML block arrives
+                    // lifted into `__yaml__` by preprocessYamlBodies.
+                    // markdown-it-attrs put the opener's `{…}` on the token's attrs; the lifted YAML block is `__yaml__`
+                    const pairs = (tok.attrs ?? []);
+                    for (const key of unknownProps(name, propKeysOfAttrs(Object.fromEntries(pairs)))) {
+                        add(tok.map[0], "unknown-prop", `${key} is not a prop of :::${name} — it is kept but not drawn`, name);
+                    }
+                }
                 if (tok.meta?.unverified) {
                     add(tok.map[0], "nesting-unchecked", `the parser stopped re-checking the nested blocks on this page here, so where :::${name} ends may be wrong — check that each block inside it has its own closer, or split the page`);
                 }

package/dist/directive-props.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The props each known directive DRAWS, for the `unknown-prop` diagnostic (2026-10-27): a key
+ * a renderer does not read is carried through every round trip but drawn by nothing, and a
+ * typo in a `{…}` block or a `---` props block was silent. The lists are the union of what
+ * docs/dogsbay-md.md documents and what format-astro's and render-html's renderers read; a
+ * directive not listed here is not checked (api-*, autodoc, openapi, config, theme, example:
+ * their props are open-ended or read from a spec).
+ *
+ * Always allowed on anything: `id`, `class`, `style`, `role`, `data-*`, `aria-*` (passed
+ * through to the element), and `type`/`title`/`icon` on the callout names.
+ */
+export declare const PASSTHROUGH_PROP: RegExp;
+export declare const DIRECTIVE_PROPS: Readonly<Record<string, readonly string[]>>;
+/** Keys of `props` that `name` does not draw; empty when the directive is not checked. */
+export declare function unknownProps(name: string, props: Iterable<string>): string[];

package/dist/directive-props.js

@@ -0,0 +1,50 @@
+/**
+ * The props each known directive DRAWS, for the `unknown-prop` diagnostic (2026-10-27): a key
+ * a renderer does not read is carried through every round trip but drawn by nothing, and a
+ * typo in a `{…}` block or a `---` props block was silent. The lists are the union of what
+ * docs/dogsbay-md.md documents and what format-astro's and render-html's renderers read; a
+ * directive not listed here is not checked (api-*, autodoc, openapi, config, theme, example:
+ * their props are open-ended or read from a spec).
+ *
+ * Always allowed on anything: `id`, `class`, `style`, `role`, `data-*`, `aria-*` (passed
+ * through to the element), and `type`/`title`/`icon` on the callout names.
+ */
+export const PASSTHROUGH_PROP = /^(?:id|class|style|role|data-[\w-]+|aria-[\w-]+)$/;
+const CALLOUT = ["type", "title", "icon", "collapsed", "collapsible", "open", "tone", "variant", "href"];
+const CALLOUT_NAMES = ["callout", "note", "tip", "info", "important", "warning", "caution", "danger", "success", "hint", "attention", "error", "failure", "bug", "question", "abstract", "quote"];
+export const DIRECTIVE_PROPS = {
+    ...Object.fromEntries(CALLOUT_NAMES.map((n) => [n, CALLOUT])),
+    details: ["title", "summary", "icon", "open", "variant", "type", "sheet"],
+    tabs: ["variant", "sync", "syncKey", "group", "title", "value", "label"],
+    tab: ["title", "label", "icon", "value"],
+    steps: ["title"],
+    step: ["title"],
+    cards: ["cols", "tone", "variant"],
+    card: ["title", "href", "icon", "description", "tone", "variant", "image", "alt"],
+    "link-card": ["href", "title", "description", "icon"],
+    grid: ["cols", "gap"],
+    "grid-item": ["span", "rowSpan", "label", "tone"],
+    figure: ["caption", "src", "alt"],
+    files: [],
+    button: ["href", "variant", "label", "size"],
+    youtube: ["id", "title", "poster"],
+    avatar: ["src", "alt", "fallback", "source", "size"],
+    accordion: ["type", "defaultValue", "variant"],
+    "accordion-item": ["title", "label", "value", "open"],
+    math: [],
+    "data-table": ["src", "columns", "caption", "sortable", "filter", "paginate"],
+    "data-cards": ["src", "cols", "tone"],
+    "child-links": ["depth", "title"],
+};
+/** Keys of `props` that `name` does not draw; empty when the directive is not checked. */
+export function unknownProps(name, props) {
+    const known = DIRECTIVE_PROPS[name];
+    if (!known)
+        return [];
+    const set = new Set(known);
+    const out = [];
+    for (const key of props)
+        if (!set.has(key) && !PASSTHROUGH_PROP.test(key) && key !== "__yaml__")
+            out.push(key);
+    return out;
+}

package/dist/index.d.ts

@@ -9,6 +9,7 @@ export { maskMinjaInCode, unmaskMinjaInCode, maskAllMinjaOpeners, isMinjaProcess
 export type { ParseResult, ParseOptions } from "./parse.js";
 export { KNOWN_INLINE_DIRECTIVES, type ParseDiagnostic } from "./diagnostics.js";
 export { KNOWN_BLOCK_DIRECTIVES, LEAF_ONLY_DIRECTIVES, BLOCK_LEAF_DIRECTIVES } from "./plugin-containers.js";
+export { DIRECTIVE_PROPS, PASSTHROUGH_PROP, unknownProps } from "./directive-props.js";
 export { buildNavFromDirectory } from "./nav.js";
 export type { BuildNavOptions } from "./nav.js";
 export { loadNavFile } from "./nav-file.js";

package/dist/index.js

@@ -12,6 +12,7 @@ export { maskMinjaInCode, unmaskMinjaInCode, maskAllMinjaOpeners, isMinjaProcess
 export { KNOWN_INLINE_DIRECTIVES } from "./diagnostics.js";
 // The `:::name` blocks the parser knows (an editor completes names from it)
 export { KNOWN_BLOCK_DIRECTIVES, LEAF_ONLY_DIRECTIVES, BLOCK_LEAF_DIRECTIVES } from "./plugin-containers.js";
+export { DIRECTIVE_PROPS, PASSTHROUGH_PROP, unknownProps } from "./directive-props.js";
 export { buildNavFromDirectory } from "./nav.js";
 export { loadNavFile } from "./nav-file.js";
 export { renderDiagrams } from "./renderers/diagrams.js";

package/dist/parse-attrs.d.ts

@@ -16,6 +16,12 @@ export interface ParsedAttrs {
     props: Record<string, string | boolean>;
 }
 export declare function parseAttrs(inner: string): ParsedAttrs;
+/**
+ * Whether `inner` is ONLY a list of attributes, as parseAttrs reads them. parseAttrs never fails,
+ * so text that only looks like a block (CSS in prose, `{--x: 1}`) comes out reordered; a reader
+ * that may meet such text (the label-less inline form) asks this first and leaves it as text.
+ */
+export declare function isAttrList(inner: string): boolean;
 /**
  * Merge ParsedAttrs into a props dict suitable for TreeNode.props.
  * `id` and `classes` become `id` and `class`; other props flow through.

package/dist/parse-attrs.js

@@ -99,6 +99,23 @@ export function parseAttrs(inner) {
     }
     return result;
 }
+/** One item of an attribute list: `#id`, `.class`, `key`, `key=bare`, `key="…"`, `key='…'`. */
+const ATTR_ITEM = /\s*(?:[#.][\w-]+|[A-Za-z_][\w-]*(?:=(?:"(?:[^"\\]|\\.)*"|'[^']*'|[^\s"'=]+))?)(?=\s|$)/y;
+/**
+ * Whether `inner` is ONLY a list of attributes, as parseAttrs reads them. parseAttrs never fails,
+ * so text that only looks like a block (CSS in prose, `{--x: 1}`) comes out reordered; a reader
+ * that may meet such text (the label-less inline form) asks this first and leaves it as text.
+ */
+export function isAttrList(inner) {
+    let pos = 0;
+    ATTR_ITEM.lastIndex = 0;
+    while (ATTR_ITEM.lastIndex < inner.length) {
+        if (!ATTR_ITEM.test(inner))
+            return /^\s*$/.test(inner.slice(pos));
+        pos = ATTR_ITEM.lastIndex;
+    }
+    return true;
+}
 /**
  * Merge ParsedAttrs into a props dict suitable for TreeNode.props.
  * `id` and `classes` become `id` and `class`; other props flow through.

package/dist/parse.js

@@ -1795,12 +1795,14 @@ function tokensToInline(tokens, inheritedFmt = []) {
                 }
                 const labelInline = tokensToInline(labelTokens);
                 const labelText = inlineText(labelInline);
-                const labelless = tok.meta?.labelless === true;
-                let node = inlineDirectiveToNode(name, labelText, labelInline, attrs, labelless);
-                // An unknown label-less directive stays as written (`:name{…}`), as TEXT: its attrs may carry
-                // a tag, and html-inline is written raw by every consumer
-                if (node?.type === "html-inline" && labelless && node.html.startsWith(`:${name}[]`))
-                    node = { type: "text", text: `:${name}${node.html.slice(name.length + 3)}` };
+                const meta = tok.meta;
+                const labelless = meta?.labelless === true;
+                let node = meta?.literal && meta.source ? { type: "text", text: meta.source } : inlineDirectiveToNode(name, labelText, labelInline, attrs, labelless);
+                // A label-less directive that makes nothing (unknown, or a known one without its naming
+                // prop) stays exactly as written, as TEXT: its attrs may carry a tag, html-inline is written
+                // raw by every consumer, and re-rendering the attrs reordered them
+                if (labelless && meta?.source && ((node?.type === "html-inline" && node.html.startsWith(`:${name}[]`)) || (node?.type === "text" && node.text.startsWith(`:${name}{`))))
+                    node = { type: "text", text: meta.source };
                 if (node)
                     result.push(node);
                 break;

package/dist/plugin-inline-directives.js

@@ -1,4 +1,4 @@
-import { attrBlockEnd, parseAttrs } from "./parse-attrs.js";
+import { attrBlockEnd, isAttrList, parseAttrs } from "./parse-attrs.js";
 /** A character a directive cannot follow directly (see inlineDirectiveRule). */
 export const PRECEDES_TEXT = /[\p{Script=Latin}\p{Script=Greek}\p{Script=Cyrillic}0-9:]/u;
 /** The prop that labels a known inline directive written without `[text]` (`:kbd{value="Ctrl"}`). */
@@ -115,7 +115,11 @@ function inlineDirectiveRule(state, silent) {
         state.pos = pos;
         return true;
     }
-    const parsedAttrs = parseAttrs(attrs);
+    // `:root{--x: 1}` in prose is CSS, not attributes: read leniently it came out reordered
+    // (`:root{1 --x:}`). It is still taken here, as literal text: left to the paragraph, a trailing
+    // `{…}` would be read as the paragraph's attributes and vanish.
+    const literal = labelless && !isAttrList(attrs);
+    const parsedAttrs = literal ? { classes: [], props: {} } : parseAttrs(attrs);
     const attrsStr = JSON.stringify(parsedAttrs);
     if (isLeaf) {
         const t = state.push("dogsbay_leaf_directive", "", 0);
@@ -126,8 +130,9 @@ function inlineDirectiveRule(state, silent) {
         const openT = state.push("dogsbay_inline_directive_open", "", 1);
         openT.tag = name;
         openT.info = attrsStr;
+        // the source as written: an unknown label-less directive stays these bytes, not a re-rendering
         if (labelless)
-            openT.meta = { labelless: true };
+            openT.meta = { labelless: true, literal, source: src.slice(start, pos) };
         if (!labelless) {
             // Parse label as inline content (recursive)
             const oldPos = state.pos;

package/dist/serialize.js

@@ -618,7 +618,8 @@ function renderCallout(node, ctx) {
     const labelled = typeof node.meta?.closer === "string";
     if (ctx.githubCallouts && hasOnlyTypeProp && !labelled && GITHUB_CALLOUT_TYPES.has(type)) {
         const tag = `[!${type.toUpperCase()}]`;
-        return [tag, body]
+        // a body opening with `---` under `[!NOTE]` made a setext heading of the tag: the callout was lost
+        return [tag, guardRule(body)]
             .join("\n")
             .split("\n")
             .map((l) => (l ? `> ${l}` : ">"))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dogsbay/format-dogsbay-md",
-  "version": "0.2.0-beta.137",
+  "version": "0.2.0-beta.138",
   "description": "Dogsbay Markdown dialect — canonical format for TreeNode[] with directives, YAML bodies, and intelligent fallbacks",
   "type": "module",
   "main": "dist/index.js",
@@ -40,10 +40,10 @@
     "markdown-it-footnote": "^4.0.0",
     "markdown-it-front-matter": "^0.2.4",
     "pele": "1.6.0",
-    "@dogsbay/corpus": "0.2.0-beta.137",
-    "@dogsbay/minja": "0.2.0-beta.137",
-    "@dogsbay/types": "0.2.0-beta.137",
-    "@dogsbay/serialize-core": "0.2.0-beta.137"
+    "@dogsbay/corpus": "0.2.0-beta.138",
+    "@dogsbay/minja": "0.2.0-beta.138",
+    "@dogsbay/serialize-core": "0.2.0-beta.138",
+    "@dogsbay/types": "0.2.0-beta.138"
   },
   "license": "MIT",
   "repository": {