@refrakt-md/runes 0.42.0 → 0.44.0

package/dist/lib/composition.js

@@ -68,6 +68,8 @@ import { SchemaSideTable } from './schema-side-table.js';
 import { declareSlotMarkers, declareSlotMarkersOnNodes } from './slot-markers.js';
 import { registersSources } from './registers.js';
 import { parse } from '../parse.js';
+import { universalAttributeDefinition } from './universal-attribute-defs.js';
+import { moveAttributes, resolvePlacements } from './composition-placement.js';
 const { Ast, Tag: MarkdocTag } = Markdoc;
 /** Compositions by schema — the same pattern as `schemaTables`: tooling has only
  *  the schema to read from. */
@@ -212,6 +214,8 @@ function slotFields(model, fail) {
             refs,
             ...(listItems ? { listItems } : {}),
             ...(ambiguousList ? { ambiguousList } : {}),
+            ...(f.fills ? { fills: f.fills } : {}),
+            ...(f.itemModel ? { itemFields: f.itemModel.fields.map((i) => i.name) } : {}),
         });
     };
     if (s.type === 'sequence') {
@@ -259,47 +263,56 @@ function slotValues(model, resolved) {
 // Template parsing and the construction-time checks
 // ---------------------------------------------------------------------------
 /**
- * `{% slot name="x" each %}` is the spec's spelling, and Markdoc's tag grammar
- * has no bare boolean attribute. Rewrite it to `each=true` inside slot tags
- * only, outside quoted values, before parsing.
+ * `{% slot name="x" each %}` and `{% section chrome %}` are the spec's
+ * spellings (D26, D31), and Markdoc's tag grammar has no bare boolean
+ * attribute. Rewrite `each` inside slot tags, and `chrome` inside any tag, to
+ * `=true`, outside quoted values, before parsing.
  */
 export function normaliseEach(body) {
-    return body.replace(/\{%-?\s*slot\b([^%]*?)(-?%\})/g, (whole, inner, close) => {
-        let out = '';
-        let quote = null;
-        let i = 0;
-        while (i < inner.length) {
-            const ch = inner[i];
-            if (quote) {
-                if (ch === '\\') {
-                    out += inner.slice(i, i + 2);
-                    i += 2;
-                    continue;
-                }
-                if (ch === quote)
-                    quote = null;
-                out += ch;
-                i++;
-                continue;
-            }
-            if (ch === '"' || ch === "'") {
-                quote = ch;
-                out += ch;
-                i++;
+    return body.replace(/\{%-?\s*([a-z][\w-]*)\b([^%]*?)(-?%\})/g, (whole, tag, inner, close) => {
+        const bare = tag === 'slot' ? ['each', 'chrome'] : ['chrome'];
+        const out = bareToTrue(inner, bare);
+        return out === inner ? whole : whole.replace(inner + close, out + close);
+    });
+}
+/** Rewrite each bare word in `words` to `word=true`, outside quoted values. */
+function bareToTrue(inner, words) {
+    let out = '';
+    let quote = null;
+    let i = 0;
+    while (i < inner.length) {
+        const ch = inner[i];
+        if (quote) {
+            if (ch === '\\') {
+                out += inner.slice(i, i + 2);
+                i += 2;
                 continue;
             }
+            if (ch === quote)
+                quote = null;
+            out += ch;
+            i++;
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            quote = ch;
+            out += ch;
+            i++;
+            continue;
+        }
+        if (i === 0 || /\s/.test(inner[i - 1])) {
             const rest = inner.slice(i);
-            const m = /^each(?![\w=-])/.exec(rest);
-            if (m && (i === 0 || /\s/.test(inner[i - 1]))) {
-                out += 'each=true';
-                i += m[0].length;
+            const word = words.find((w) => new RegExp(`^${w}(?![\\w=-])`).test(rest));
+            if (word) {
+                out += `${word}=true`;
+                i += word.length;
                 continue;
             }
-            out += ch;
-            i++;
         }
-        return whole.replace(inner + close, out + close);
-    });
+        out += ch;
+        i++;
+    }
+    return out;
 }
 /** Variables a template node reads, by path, in attribute or content position. */
 function variablePaths(value, out = []) {
@@ -370,6 +383,8 @@ export function compileComposition(template, options) {
     const placedSlots = new Map();
     const slotOrder = [];
     const placements = [];
+    /** Every rune the template places, for the paint carrier and role owners. */
+    const templateRunes = [];
     const checkVariables = (n, scope) => {
         for (const path of variablePaths(n.attributes)) {
             const [root, name] = path;
@@ -438,6 +453,7 @@ export function compileComposition(template, options) {
                 fail('composition-cycle', `it places \`{% ${n.tag} %}\`, which is the rune itself — a composition cycle.`);
             }
             placements.push({ rune: n.tag, ...(scope.parentRune ? { parent: scope.parentRune } : {}) });
+            templateRunes.push({ node: n, top: !scope.parentRune, inEach: !!scope.each });
             const children = outlineOf(n.children, { ...scope, parentRune: n.tag });
             return [{ rune: n.tag, ...(children.length > 0 ? { children } : {}) }];
         }
@@ -476,6 +492,11 @@ export function compileComposition(template, options) {
         if (!field) {
             fail('slot-unknown-field', `slot \`${name}\` names no field of the content model (fields: ${[...fields.keys()].join(', ') || 'none'}) (D26).`);
         }
+        if (field?.fills) {
+            fail('fill-placed', `slot \`${name}\` places field \`${name}\`, which fills ${Object.keys(field.fills)
+                .map((a) => `\`${a}\``)
+                .join(', ')}. A filling field is placed into the rune's values, which the template places through a meta block or \`$attrs\`; a slot as well would render it twice. Remove the slot (SPEC-182 D5).`);
+        }
         if (placedSlots.has(name)) {
             fail('slot-placed-twice', `slot \`${name}\` is placed twice. A slot is placed exactly once; two positions are two declared fields, or a theme's concern (D26).`);
         }
@@ -538,8 +559,63 @@ export function compileComposition(template, options) {
         return { metablock: name };
     }
     const outline = outlineOf(ast.children, {});
-    // D11 — a field no slot places parses and then silently does not render.
-    const unplaced = [...fields.keys()].filter((f) => !placedSlots.has(f));
+    // D14, D31, D33 — the paint carrier and every axis's target.
+    const plan = resolvePlacements(rune, templateRunes, (code, msg, at) => {
+        current = at ?? current;
+        return fail(code, msg);
+    });
+    current = undefined;
+    // D34 — each default lands where the author's attribute would. One that
+    // lands nowhere is a definition error, not a silent no-op.
+    const defaultsByNode = new Map();
+    const defaultInfo = {};
+    for (const [name, value] of Object.entries(template.defaults ?? {})) {
+        const target = name === 'density'
+            ? plan.carrier
+                ? { placement: 'carrier', node: plan.carrier, rune: plan.carrier.tag }
+                : { placement: 'carrier', dropped: `\`${rune}\` places no rune to carry it` }
+            : plan.axes[plan.axisOf[name]];
+        if (!target)
+            continue;
+        if (target.placement === 'root') {
+            defaultInfo[name] = { value, placement: 'root' };
+            continue;
+        }
+        if (!('node' in target)) {
+            const why = 'dropped' in target ? target.dropped : target.unavailable;
+            throw new CompositionError('defaults-invalid', `Rune "${rune}": \`defaults.${name}\` lands nowhere: ${why} (D34).`);
+        }
+        const into = defaultsByNode.get(target.node) ?? {};
+        into[name] = value;
+        defaultsByNode.set(target.node, into);
+        const literal = target.node.attributes[name];
+        defaultInfo[name] = {
+            value,
+            placement: target.placement,
+            rune: target.rune,
+            ...(literal !== undefined && typeof literal !== 'object' ? { literal: String(literal) } : {}),
+        };
+    }
+    // SPEC-182 D2 — `fills` names declared attributes and item-model fields.
+    for (const [name, field] of fields) {
+        if (!field.fills)
+            continue;
+        if (!field.itemFields) {
+            fail('fills-invalid', `field \`${name}\` declares \`fills\` but no \`itemModel\`: there is nothing to fill from. Give it an item model that reads the values (SPEC-182 D1).`);
+        }
+        for (const [attr, ref] of Object.entries(field.fills)) {
+            if (!declared.has(attr)) {
+                fail('fills-invalid', `field \`${name}\` fills \`${attr}\`, which the rune does not declare (declared: ${[...declared].join(', ') || 'none'}). Declare it under \`attributes\` (SPEC-182 D2).`);
+            }
+            const source = typeof ref === 'string' && ref.startsWith('$') ? ref.slice(1) : undefined;
+            if (!source || !field.itemFields.includes(source)) {
+                fail('fills-invalid', `field \`${name}\` fills \`${attr}\` from \`${ref}\`, which names no field of its item model (fields: ${field.itemFields.join(', ')}). Write it as \`$<field>\` (SPEC-182 D2).`);
+            }
+        }
+    }
+    // D11 — a field no slot places parses and then silently does not render. A
+    // filling field is placed into the rune's values (SPEC-182 D5).
+    const unplaced = [...fields.keys()].filter((f) => !placedSlots.has(f) && !fields.get(f).fills);
     if (unplaced.length > 0) {
         fail('field-unplaced', `content-model field${unplaced.length > 1 ? 's' : ''} ${unplaced.map((f) => `\`${f}\``).join(', ')} ${unplaced.length > 1 ? 'are' : 'is'} placed by no slot, so authored content would be dropped. Place ${unplaced.length > 1 ? 'each' : 'it'} with \`{% slot name="…" /%}\` (D11).`);
     }
@@ -548,15 +624,26 @@ export function compileComposition(template, options) {
         options.schema?.fallback?.type ??
         Object.values(options.schema?.rows ?? {}).find((r) => r.type)?.type;
     const nodeSources = registersNodeSources(options.registers, fields, declared);
+    const axes = {};
+    for (const [axis, target] of Object.entries(plan.axes)) {
+        axes[axis] = {
+            placement: target.placement,
+            ...('rune' in target ? { rune: target.rune } : {}),
+            ...('dropped' in target ? { dropped: target.dropped } : {}),
+            ...('unavailable' in target ? { unavailable: target.unavailable } : {}),
+        };
+    }
     const info = {
         rune,
         slots: slotOrder,
         placements,
         outline,
+        axes,
+        ...(Object.keys(defaultInfo).length > 0 ? { defaults: defaultInfo } : {}),
         ...(schemaType ? { schemaType } : {}),
     };
     const attributeNames = [...declared];
-    const transform = (resolved, attrs, config) => {
+    const place = (resolved, attrs) => {
         const bound = {};
         for (const name of attributeNames)
             bound[name] = attrs[name];
@@ -565,6 +652,8 @@ export function compileComposition(template, options) {
             resolved: slotValues(structural, resolved),
             attrs: bound,
             fields,
+            moves: moveAttributes(plan, attrs).moves,
+            defaults: defaultsByNode,
         };
         const placed = expand(ast.children, ctx);
         // Top-level template nodes are the composed rune's own (D10). A slot
@@ -573,6 +662,14 @@ export function compileComposition(template, options) {
             if (n.attributes[OWNER_ATTR] === undefined)
                 n.attributes[OWNER_ATTR] = rune;
         }
+        return placed;
+    };
+    const transform = (resolved, attrs, config, node) => {
+        // SPEC-182 D2 — values a paragraph fills become the rune's own, before
+        // anything reads them. `attrs` is the caller's object, filled in place, so
+        // the schema table applied after this transform reads them too.
+        Object.assign(attrs, filledAttributes(resolved, node?.attributes ?? {}));
+        const placed = place(resolved, attrs);
         const children = Markdoc.transform(placed, templateConfig(config));
         // The field bag holds every attribute the author set (or that defaulted):
         // it is what `modifiers`, the schema row's attribute sources and
@@ -593,7 +690,61 @@ export function compileComposition(template, options) {
         copyRegisteredNodes(root, nodeSources);
         return root;
     };
-    return { transform, info };
+    /** SPEC-182 D2, D4 — what the filling fields supply, for the attributes the
+     *  author did not write. The author's attribute always wins. */
+    const filledAttributes = (resolved, written) => {
+        const out = {};
+        const values = slotValues(structural, resolved);
+        for (const [name, field] of fields) {
+            if (!field.fills)
+                continue;
+            const record = values[`${name}Data`];
+            if (!record)
+                continue;
+            for (const [attr, ref] of Object.entries(field.fills)) {
+                if (written[attr] !== undefined)
+                    continue;
+                const value = record[ref.slice(1)];
+                if (value !== undefined && value !== '')
+                    out[attr] = value;
+            }
+        }
+        return out;
+    };
+    /** SPEC-182 D4 — attributes the author wrote that a paragraph would also have
+     *  filled: the paragraph is consumed and does not render. */
+    const overriddenFills = (resolved, written) => {
+        const out = [];
+        const values = slotValues(structural, resolved);
+        for (const [name, field] of fields) {
+            if (!field.fills || !values[`${name}Data`])
+                continue;
+            for (const attr of Object.keys(field.fills)) {
+                if (written[attr] !== undefined)
+                    out.push({ attribute: attr, field: name });
+            }
+        }
+        return out;
+    };
+    const rootAttributes = (attrs) => {
+        const { moved } = moveAttributes(plan, attrs);
+        if (moved.size === 0)
+            return attrs;
+        const out = {};
+        for (const [name, value] of Object.entries(attrs))
+            if (!moved.has(name))
+                out[name] = value;
+        return out;
+    };
+    return {
+        transform,
+        info,
+        place,
+        placements: plan,
+        rootAttributes,
+        overriddenFills,
+        templateNodes: ast.children,
+    };
 }
 function asNodes(value) {
     if (Array.isArray(value))
@@ -663,6 +814,19 @@ function substituteNode(node, ctx) {
         }
         attributes[key] = resolved;
     }
+    if (node.type === 'tag') {
+        // D31 — the marker is the template's, consumed here: it reaches neither
+        // the placed rune's attributes nor the HTML.
+        delete attributes.chrome;
+        // D34.3 — author > template literal > definition default.
+        for (const [name, value] of Object.entries(ctx.defaults?.get(node) ?? {})) {
+            if (attributes[name] === undefined)
+                attributes[name] = value;
+        }
+        const moved = ctx.moves?.get(node);
+        if (moved)
+            Object.assign(attributes, moved);
+    }
     return cloneNode(node, attributes, expand(node.children, ctx));
 }
 /** The items a list field resolved to, each with its `$each` binding and content. */
@@ -858,6 +1022,7 @@ const DEFINITION_KEYS = new Set([
     'metaFields',
     'blocks',
     'provides',
+    'defaults',
 ]);
 /** Keys that would give a composed rune styles of its own (D2). */
 const STYLE_KEYS = new Set(['css', 'style', 'styles', 'stylesheet', 'block', 'class']);
@@ -970,6 +1135,7 @@ export function parseCompositionDefinition(rune, source) {
         (!Array.isArray(fm.provides) || !fm.provides.every((p) => typeof p === 'string'))) {
         fail('invalid-value', '`provides` must be a list of names.', ['provides']);
     }
+    const defaults = parseDefaults(fm.defaults, (code, msg, at) => fail(code, msg, ['defaults', ...(at ?? [])]));
     return {
         rune,
         tag,
@@ -982,12 +1148,46 @@ export function parseCompositionDefinition(rune, source) {
         ...(fm.metaFields ? { metaFields: fm.metaFields } : {}),
         ...(fm.blocks ? { blocks: fm.blocks } : {}),
         ...(fm.provides ? { provides: fm.provides } : {}),
+        ...(defaults ? { defaults } : {}),
         template: match[2],
         // `---`, the frontmatter's lines, `---`: the body starts on the next.
         templateLine: frontmatter.split(/\r?\n/).length + 3,
         frontmatter,
     };
 }
+/** D34.6 — `density` has no author-facing attribute, so its scale is stated here. */
+const DENSITY_VALUES = ['full', 'compact', 'minimal'];
+/**
+ * D34 — `defaults`: universal axes only, each with a value the axis accepts.
+ * A rune's own attribute takes its default where it is declared.
+ */
+function parseDefaults(raw, fail) {
+    if (raw === undefined)
+        return undefined;
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        fail('defaults-invalid', '`defaults` must be a mapping of universal attributes to values.');
+    }
+    const out = {};
+    for (const [key, value] of Object.entries(raw)) {
+        if (value === null || typeof value === 'object') {
+            fail('defaults-invalid', `\`defaults.${key}\` must be a single value.`, [key]);
+        }
+        const text = String(value);
+        const accepted = key === 'density'
+            ? DENSITY_VALUES
+            : universalAttributeDefinition(key) === undefined
+                ? undefined
+                : universalAttributeDefinition(key).matches;
+        if (key !== 'density' && universalAttributeDefinition(key) === undefined) {
+            fail('defaults-invalid', `\`defaults\` takes universal attributes only, and \`${key}\` is not one. A rune's own attribute takes its default where it is declared, under \`attributes\` (D34).`, [key]);
+        }
+        if (Array.isArray(accepted) && !accepted.includes(text)) {
+            fail('defaults-invalid', `\`defaults.${key}\` is \`${text}\`, which \`${key}\` does not accept (${accepted.join(', ')}).`, [key]);
+        }
+        out[key] = text;
+    }
+    return out;
+}
 function parseAttributes(raw, sectionFail) {
     const fail = (code, msg) => sectionFail(code, msg);
     if (raw === undefined)
@@ -1038,6 +1238,7 @@ const FIELD_KEYS = new Set([
     'itemModel',
     'emitTag',
     'emitAttributes',
+    'fills',
 ]);
 /** A field list as YAML writes it: a mapping keyed by name, or a list with `name`. */
 function parseFields(raw, where, fail) {
@@ -1302,6 +1503,13 @@ function parseDelimitedModel(c, fail) {
  * resolves a field against the rune's modifier values, exactly as it does for a
  * tree-owning rune — which must declare the same attributes as modifiers for
  * its own blocks to fill.
+ *
+ * An enum attribute the template only forwards to a placed rune
+ * (`{% section media-position=$attrs["media-position"] %}`) is that rune's
+ * input, not a modifier of the composition: as a `data-*` on the empty root it
+ * would match the dimension rules meant for the rune it is forwarded to — a
+ * `data-media-position="cover"` root is laid out as a cover well. It stays in
+ * the field bag, which the schema row and registration read.
  */
 export function composedRuneConfig(def) {
     const read = new Set();
@@ -1313,22 +1521,39 @@ export function composedRuneConfig(def) {
                 read.add(ref);
         }
     }
+    const forwarded = forwardedAttributes(def.template);
     const modifiers = {};
     for (const [name, attr] of Object.entries(def.attributes)) {
-        if (!attr.matches && !read.has(name))
+        if (!read.has(name) && (!attr.matches || forwarded.has(name)))
             continue;
         modifiers[name] = {
             source: 'meta',
             ...(attr.default !== undefined ? { default: String(attr.default) } : {}),
         };
     }
+    // D34 — a root-placed axis's default is the generated config's, since a
+    // template never writes on the root.
+    const d = def.defaults ?? {};
     return {
+        composed: true,
+        ...(d.width ? { defaultWidth: d.width } : {}),
+        ...(d.spacing ? { defaultSpacing: d.spacing } : {}),
+        ...(d.inset ? { defaultInset: d.inset } : {}),
         ...(Object.keys(modifiers).length > 0 ? { modifiers } : {}),
         ...(def.metaFields ? { metaFields: def.metaFields } : {}),
         ...(def.blocks ? { blocks: def.blocks } : {}),
         ...(def.provides ? { provides: def.provides } : {}),
     };
 }
+/** The attributes a template passes to a placed rune as an attribute value:
+ *  `name=$attrs.x` or `name=$attrs["x"]`. */
+function forwardedAttributes(template) {
+    const out = new Set();
+    for (const m of template.matchAll(/[\w-]+\s*=\s*\$attrs(?:\.([\w-]+)|\[\s*["']([^"']+)["']\s*\])/g)) {
+        out.add(m[1] ?? m[2]);
+    }
+    return out;
+}
 /** The schema types a rune can emit at its root — its table's, and its `seoType`. */
 function emittedTypes(entry, table) {
     return [