@refrakt-md/runes 0.8.5 → 0.9.0

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAA+B,MAAM,uBAAuB,CAAC;AAEtF,OAAO,KAAK,EAAE,oBAAoB,EAAoE,MAAM,mBAAmB,CAAC;AA+EhI;gFACgF;AAChF,eAAO,MAAM,UAAU,EAAE,WAqoBxB,CAAC;AAEF,sGAAsG;AACtG,eAAO,MAAM,UAAU,aAAa,CAAC;AAIrC,gEAAgE;AAChE,MAAM,WAAW,YAAY;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,YAAY,EAAE,CAAC;CACzB;AAgbD;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,EAAE,oBAsH/B,CAAC"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAA+B,MAAM,uBAAuB,CAAC;AAEtF,OAAO,KAAK,EAAE,oBAAoB,EAAoE,MAAM,mBAAmB,CAAC;AAgFhI;gFACgF;AAChF,eAAO,MAAM,UAAU,EAAE,WAqrBxB,CAAC;AAEF,sGAAsG;AACtG,eAAO,MAAM,UAAU,aAAa,CAAC;AAIrC,gEAAgE;AAChE,MAAM,WAAW,YAAY;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,YAAY,EAAE,CAAC;CACzB;AA4kBD;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,EAAE,oBA8H/B,CAAC"}

package/dist/config.js

@@ -5,6 +5,7 @@ import { createComponentRenderable } from './lib/index.js';
 import { schema } from './registry.js';
 import { BREADCRUMB_AUTO_SENTINEL } from './tags/breadcrumb.js';
 import { NAV_AUTO_SENTINEL } from './tags/nav.js';
+import { XREF_RUNE_MARKER } from './tags/xref.js';
 // ─── Budget postTransform helpers ───
 const BUDGET_CURRENCY_SYMBOLS = {
     USD: '$', EUR: '€', GBP: '£', JPY: '¥', CNY: '¥',
@@ -68,7 +69,7 @@ function readPropText(node, prop) {
 }
 /** autoLabel entries shared by all PageSection-based runes */
 const pageSectionAutoLabel = {
-    header: 'header', // <header> wrapper element
+    header: 'preamble', // <header> wrapper element → data-name="preamble"
     eyebrow: 'eyebrow', // property="eyebrow"
     headline: 'headline', // property="headline"
     blurb: 'blurb', // property="blurb"
@@ -82,11 +83,12 @@ export const coreConfig = {
     icons: {},
     runes: {
         // ─── Simple runes (block name only, engine adds BEM classes) ───
-        Accordion: { block: 'accordion', autoLabel: pageSectionAutoLabel, editHints: { headline: 'inline', eyebrow: 'inline', blurb: 'inline' } },
-        AccordionItem: { block: 'accordion-item', parent: 'Accordion', autoLabel: { name: 'header' }, editHints: { header: 'inline', body: 'none' } },
-        Details: { block: 'details', autoLabel: { summary: 'summary' }, editHints: { summary: 'inline', body: 'none' } },
+        Accordion: { block: 'accordion', defaultDensity: 'full', sections: { preamble: 'preamble', headline: 'title', blurb: 'description' }, autoLabel: pageSectionAutoLabel, editHints: { headline: 'inline', eyebrow: 'inline', blurb: 'inline' } },
+        AccordionItem: { block: 'accordion-item', parent: 'Accordion', rootAttributes: { 'data-state': 'closed' }, autoLabel: { name: 'header' }, editHints: { header: 'inline', body: 'none' } },
+        Details: { block: 'details', defaultDensity: 'compact', sections: { summary: 'title' }, autoLabel: { summary: 'summary' }, editHints: { summary: 'inline', body: 'none' } },
         Grid: {
             block: 'grid',
+            defaultDensity: 'full',
             modifiers: {
                 mode: { source: 'meta', default: 'columns' },
                 collapse: { source: 'meta', noBemClass: true },
@@ -108,6 +110,7 @@ export const coreConfig = {
         },
         CodeGroup: {
             block: 'codegroup',
+            defaultDensity: 'compact',
             modifiers: { title: { source: 'meta' }, overflow: { source: 'meta', default: 'scroll' } },
             structure: {
                 topbar: {
@@ -120,12 +123,14 @@ export const coreConfig = {
                     ],
                 },
             },
+            sections: { topbar: 'header', title: 'title' },
             editHints: { panel: 'code', title: 'none' },
         },
         PageSection: { block: 'page-section' },
         TableOfContents: { block: 'toc' },
         Embed: {
             block: 'embed',
+            defaultDensity: 'compact',
             editHints: { fallback: 'none' },
             postTransform(node) {
                 const block = node.attributes.class?.split(' ')[0] || 'rf-embed';
@@ -166,10 +171,12 @@ export const coreConfig = {
                 };
             },
         },
-        Breadcrumb: { block: 'breadcrumb', editHints: { items: 'none' } },
+        Breadcrumb: { block: 'breadcrumb', defaultDensity: 'minimal', sections: { items: 'body' }, editHints: { items: 'none' } },
         BreadcrumbItem: { block: 'breadcrumb-item', parent: 'Breadcrumb' },
         Blog: {
             block: 'blog',
+            defaultDensity: 'full',
+            sections: { preamble: 'preamble', headline: 'title', blurb: 'description', content: 'body' },
             contentWrapper: { tag: 'div', ref: 'content' },
             modifiers: {
                 layout: { source: 'meta', default: 'list' },
@@ -183,6 +190,8 @@ export const coreConfig = {
         },
         Budget: {
             block: 'budget',
+            defaultDensity: 'full',
+            sections: { header: 'header', title: 'title', footer: 'footer' },
             editHints: { title: 'none', meta: 'none', 'meta-item': 'none' },
             modifiers: {
                 title: { source: 'meta' },
@@ -202,9 +211,9 @@ export const coreConfig = {
                         {
                             tag: 'div', ref: 'meta',
                             children: [
-                                { tag: 'span', ref: 'meta-item', metaText: 'currency', condition: 'currency' },
-                                { tag: 'span', ref: 'meta-item', metaText: 'travelers', textPrefix: 'Travelers: ', condition: 'travelers' },
-                                { tag: 'span', ref: 'meta-item', metaText: 'duration', textPrefix: 'Duration: ', condition: 'duration' },
+                                { tag: 'span', ref: 'meta-item', metaText: 'currency', condition: 'currency', metaType: 'category', metaRank: 'primary' },
+                                { tag: 'span', ref: 'meta-item', metaText: 'travelers', label: 'Travelers:', condition: 'travelers', metaType: 'quantity', metaRank: 'primary' },
+                                { tag: 'span', ref: 'meta-item', metaText: 'duration', label: 'Duration:', condition: 'duration', metaType: 'temporal', metaRank: 'secondary' },
                             ],
                         },
                     ],
@@ -282,8 +291,10 @@ export const coreConfig = {
         // ─── Runes with modifier meta tags ───
         Hint: {
             block: 'hint',
+            defaultDensity: 'compact',
             modifiers: { hintType: { source: 'meta', default: 'note' } },
             contextModifiers: { 'hero': 'in-hero', 'feature': 'in-feature' },
+            sections: { header: 'header' },
             editHints: { icon: 'none', title: 'none' },
             structure: {
                 header: {
@@ -297,14 +308,17 @@ export const coreConfig = {
         },
         Figure: {
             block: 'figure',
+            defaultDensity: 'compact',
             modifiers: {
                 size: { source: 'meta', default: 'default' },
                 align: { source: 'meta', default: 'center' },
             },
+            sections: { caption: 'description' },
             editHints: { caption: 'inline' },
         },
         Gallery: {
             block: 'gallery',
+            defaultDensity: 'full',
             modifiers: {
                 layout: { source: 'meta', default: 'grid' },
                 lightbox: { source: 'meta', default: 'true', noBemClass: true },
@@ -319,15 +333,18 @@ export const coreConfig = {
         },
         Sidenote: {
             block: 'sidenote',
+            defaultDensity: 'minimal',
             modifiers: { variant: { source: 'meta', default: 'sidenote' } },
+            sections: { body: 'body' },
             editHints: { body: 'inline' },
         },
         Compare: {
             block: 'compare',
+            defaultDensity: 'full',
             modifiers: { layout: { source: 'meta', default: 'side-by-side' } },
             editHints: { panels: 'none' },
         },
-        Conversation: { block: 'conversation', editHints: { messages: 'none' } },
+        Conversation: { block: 'conversation', defaultDensity: 'compact', editHints: { messages: 'none' } },
         ConversationMessage: {
             block: 'conversation-message',
             parent: 'Conversation',
@@ -336,12 +353,15 @@ export const coreConfig = {
         },
         Annotate: {
             block: 'annotate',
+            defaultDensity: 'full',
             modifiers: { variant: { source: 'meta', default: 'margin' } },
+            sections: { body: 'body' },
             editHints: { body: 'none', notes: 'none' },
         },
         AnnotateNote: { block: 'annotate-note', parent: 'Annotate', editHints: { body: 'inline' } },
         Nav: {
             block: 'nav',
+            defaultDensity: 'compact',
             postTransform(node) {
                 return { ...node, name: 'rf-nav' };
             },
@@ -377,11 +397,13 @@ export const coreConfig = {
         },
         Diff: {
             block: 'diff',
+            defaultDensity: 'compact',
             modifiers: { mode: { source: 'meta', default: 'unified' } },
             editHints: { line: 'none', 'gutter-num': 'none', 'gutter-prefix': 'none', 'line-content': 'none' },
         },
         Chart: {
             block: 'chart',
+            defaultDensity: 'compact',
             editHints: { data: 'none' },
             postTransform(node) {
                 const block = node.attributes.class?.split(' ')[0] || 'rf-chart';
@@ -495,33 +517,42 @@ export const coreConfig = {
         // ─── Text formatting & layout runes ───
         PullQuote: {
             block: 'pullquote',
+            defaultDensity: 'compact',
             modifiers: {
                 align: { source: 'meta', default: 'center' },
                 variant: { source: 'meta', default: 'default' },
             },
+            sections: { body: 'body' },
             editHints: { body: 'inline' },
         },
         TextBlock: {
             block: 'textblock',
+            defaultDensity: 'full',
             modifiers: {
                 dropcap: { source: 'meta' },
                 columns: { source: 'meta' },
                 lead: { source: 'meta' },
                 align: { source: 'meta', default: 'left' },
             },
+            sections: { body: 'body' },
             editHints: { body: 'none' },
         },
         MediaText: {
             block: 'mediatext',
+            defaultDensity: 'full',
             modifiers: {
                 align: { source: 'meta', default: 'left' },
                 ratio: { source: 'meta', default: '1:1' },
                 wrap: { source: 'meta' },
             },
+            sections: { body: 'body', media: 'media' },
+            mediaSlots: { media: 'cover' },
             editHints: { media: 'image', body: 'none' },
         },
         Showcase: {
             block: 'showcase',
+            defaultDensity: 'compact',
+            sections: { viewport: 'body' },
             modifiers: {
                 shadow: { source: 'meta', default: 'none' },
                 bleed: { source: 'meta', default: 'none' },
@@ -547,11 +578,13 @@ export const coreConfig = {
             },
         },
         // ─── Interactive runes (still get BEM classes, components add behavior) ───
-        TabGroup: { block: 'tabs', autoLabel: pageSectionAutoLabel, editHints: { headline: 'inline', eyebrow: 'inline', blurb: 'inline' } },
-        Tab: { block: 'tab', parent: 'TabGroup', editHints: { name: 'inline' } },
-        TabPanel: { block: 'tab-panel', parent: 'TabGroup' },
+        TabGroup: { block: 'tabs', defaultDensity: 'full', sections: { preamble: 'preamble', headline: 'title', blurb: 'description' }, autoLabel: pageSectionAutoLabel, editHints: { headline: 'inline', eyebrow: 'inline', blurb: 'inline' } },
+        Tab: { block: 'tab', parent: 'TabGroup', rootAttributes: { 'data-state': 'inactive' }, editHints: { name: 'inline' } },
+        TabPanel: { block: 'tab-panel', parent: 'TabGroup', rootAttributes: { 'data-state': 'inactive' } },
         DataTable: {
             block: 'datatable',
+            defaultDensity: 'compact',
+            sections: { table: 'body' },
             modifiers: {
                 searchable: { source: 'meta', default: 'false' },
                 sortable: { source: 'meta' },
@@ -562,6 +595,8 @@ export const coreConfig = {
         },
         Form: {
             block: 'form',
+            defaultDensity: 'full',
+            sections: { body: 'body' },
             modifiers: {
                 variant: { source: 'meta', default: 'stacked' },
                 action: { source: 'meta' },
@@ -581,15 +616,18 @@ export const coreConfig = {
         },
         Reveal: {
             block: 'reveal',
+            defaultDensity: 'full',
             modifiers: {
                 mode: { source: 'meta', default: 'click' },
             },
+            sections: { preamble: 'preamble', headline: 'title', blurb: 'description' },
             autoLabel: pageSectionAutoLabel,
             editHints: { headline: 'inline', eyebrow: 'inline', blurb: 'inline', steps: 'none' },
         },
-        RevealStep: { block: 'reveal-step', parent: 'Reveal', editHints: { body: 'none' } },
+        RevealStep: { block: 'reveal-step', parent: 'Reveal', rootAttributes: { 'data-state': 'closed' }, editHints: { body: 'none' } },
         Juxtapose: {
             block: 'juxtapose',
+            defaultDensity: 'compact',
             modifiers: {
                 variant: { source: 'meta', default: 'slider' },
                 orientation: { source: 'meta', default: 'vertical', noBemClass: true },
@@ -602,9 +640,10 @@ export const coreConfig = {
             },
             editHints: { panels: 'none' },
         },
-        JuxtaposePanel: { block: 'juxtapose-panel', parent: 'Juxtapose', editHints: { body: 'none' } },
+        JuxtaposePanel: { block: 'juxtapose-panel', parent: 'Juxtapose', rootAttributes: { 'data-state': 'inactive' }, editHints: { body: 'none' } },
         Diagram: {
             block: 'diagram',
+            defaultDensity: 'compact',
             editHints: { source: 'code' },
             postTransform(node) {
                 const block = node.attributes.class?.split(' ')[0] || 'rf-diagram';
@@ -638,6 +677,7 @@ export const coreConfig = {
         Region: { block: 'region', parent: 'Layout' },
         Sandbox: {
             block: 'sandbox',
+            defaultDensity: 'compact',
             editHints: { source: 'code' },
             postTransform(node) {
                 // Read meta values
@@ -647,14 +687,23 @@ export const coreConfig = {
                 const label = readMeta(node, 'label') || '';
                 const height = readMeta(node, 'height') || 'auto';
                 const designTokens = readMeta(node, 'design-tokens') || '';
-                // Keep non-meta children (fallback pre, source panels)
-                const fallbackChildren = node.children.filter(child => {
-                    if (!isTag(child))
-                        return true;
-                    if (child.name === 'meta')
-                        return false;
-                    return true;
-                });
+                // Keep non-meta children (fallback pre) and extract source panels
+                const fallbackChildren = [];
+                const sourcePanelOrigins = [];
+                for (const child of node.children) {
+                    if (!isTag(child)) {
+                        fallbackChildren.push(child);
+                        continue;
+                    }
+                    if (child.name === 'meta') {
+                        // Collect origin data from source panels
+                        if (child.attributes?.['data-field'] === 'source-panel' && child.attributes?.['data-origin']) {
+                            sourcePanelOrigins.push(`${child.attributes['data-label'] || ''}\t${child.attributes['data-origin']}`);
+                        }
+                        continue;
+                    }
+                    fallbackChildren.push(child);
+                }
                 // Add hidden content div for web component
                 const children = [
                     ...fallbackChildren,
@@ -671,6 +720,7 @@ export const coreConfig = {
                         ...(label ? { 'data-label': label } : {}),
                         'data-height': height,
                         ...(designTokens ? { 'data-design-tokens': designTokens } : {}),
+                        ...(sourcePanelOrigins.length > 0 ? { 'data-source-origins': sourcePanelOrigins.join('\n') } : {}),
                     },
                     children,
                 };
@@ -1004,6 +1054,125 @@ function resolveBlogPosts(renderable, allPosts, ctx, pageUrl) {
     });
     return modified ? result : renderable;
 }
+// ─── Xref resolution helpers ───
+/**
+ * Find an entity by exact ID across all types in the registry.
+ * If typeHint is provided, only search that type.
+ */
+function findEntityById(registry, id, typeHint) {
+    const types = typeHint ? [typeHint] : registry.getTypes();
+    for (const type of types) {
+        const entity = registry.getById(type, id);
+        if (entity)
+            return { entity, ambiguous: false };
+    }
+    return undefined;
+}
+/**
+ * Find entities by name/title match (case-insensitive) across all types.
+ * If typeHint is provided, only search that type.
+ */
+function findEntitiesByName(registry, name, typeHint) {
+    const nameLower = name.toLowerCase();
+    const types = typeHint ? [typeHint] : registry.getTypes();
+    const matches = [];
+    for (const type of types) {
+        for (const entity of registry.getAll(type)) {
+            const entityName = entity.data.name ?? '';
+            const entityTitle = entity.data.title ?? '';
+            if (entityName.toLowerCase() === nameLower || entityTitle.toLowerCase() === nameLower) {
+                matches.push(entity);
+            }
+        }
+    }
+    return matches;
+}
+/** Resolve an entity's URL for use as an href */
+function resolveEntityHref(entity) {
+    const baseUrl = entity.data.url || entity.sourceUrl;
+    const headingId = entity.data.headingId;
+    if (headingId)
+        return `${baseUrl}#${headingId}`;
+    return baseUrl;
+}
+/** Walk a Markdoc renderable tree, resolving any xref placeholders */
+function resolveXrefs(renderable, pageUrl, registry, ctx) {
+    if (!Tag.isTag(renderable)) {
+        if (Array.isArray(renderable)) {
+            const newChildren = renderable.map(c => resolveXrefs(c, pageUrl, registry, ctx));
+            if (newChildren.every((c, i) => c === renderable[i]))
+                return renderable;
+            return newChildren;
+        }
+        return renderable;
+    }
+    const tag = renderable;
+    // Check if this is an xref placeholder
+    if (tag.attributes?.['data-rune'] === XREF_RUNE_MARKER) {
+        const id = tag.attributes['data-xref-id'];
+        const label = tag.attributes['data-xref-label'];
+        const typeHint = tag.attributes['data-xref-type'];
+        // Try exact ID match first
+        const idMatch = findEntityById(registry, id, typeHint);
+        if (idMatch) {
+            const entity = idMatch.entity;
+            const href = resolveEntityHref(entity);
+            const text = label || entity.data.title || entity.data.name || entity.data.text || id;
+            if (entity.sourceUrl === pageUrl) {
+                ctx.info(`xref "${id}" on ${pageUrl} — references itself`, pageUrl);
+            }
+            return new Tag('a', {
+                class: `rf-xref rf-xref--${entity.type}`,
+                href,
+                'data-entity-type': entity.type,
+                'data-entity-id': entity.id,
+            }, [text]);
+        }
+        // Try name/title match
+        const nameMatches = findEntitiesByName(registry, id, typeHint);
+        if (nameMatches.length === 1) {
+            const entity = nameMatches[0];
+            const href = resolveEntityHref(entity);
+            const text = label || entity.data.title || entity.data.name || entity.data.text || id;
+            if (entity.sourceUrl === pageUrl) {
+                ctx.info(`xref "${id}" on ${pageUrl} — references itself`, pageUrl);
+            }
+            return new Tag('a', {
+                class: `rf-xref rf-xref--${entity.type}`,
+                href,
+                'data-entity-type': entity.type,
+                'data-entity-id': entity.id,
+            }, [text]);
+        }
+        if (nameMatches.length > 1) {
+            const matchList = nameMatches
+                .map(e => `${e.type} "${e.data.title || e.data.name || e.id}" on ${e.sourceUrl}`)
+                .join(', ');
+            ctx.warn(`xref "${id}" on ${pageUrl} — matches ${nameMatches.length} entities (${matchList}). Add type hint to disambiguate.`, pageUrl);
+            // Use first match
+            const entity = nameMatches[0];
+            const href = resolveEntityHref(entity);
+            const text = label || entity.data.title || entity.data.name || entity.data.text || id;
+            return new Tag('a', {
+                class: `rf-xref rf-xref--${entity.type}`,
+                href,
+                'data-entity-type': entity.type,
+                'data-entity-id': entity.id,
+            }, [text]);
+        }
+        // No match — unresolved
+        ctx.warn(`xref "${id}" on ${pageUrl} — entity not found`, pageUrl);
+        return new Tag('span', {
+            class: 'rf-xref rf-xref--unresolved',
+            'data-entity-id': id,
+        }, [label || id]);
+    }
+    // Recurse into children
+    const newChildren = (tag.children ?? []).map((c) => resolveXrefs(c, pageUrl, registry, ctx));
+    if (newChildren.every((c, i) => c === tag.children[i]))
+        return tag;
+    return { ...tag, children: newChildren };
+}
 /**
  * Core cross-page pipeline hooks.
  * Run for every site, before any community package hooks.
@@ -1072,7 +1241,7 @@ export const corePipelineHooks = {
             draft: e.data.draft || false,
             frontmatter: e.data,
         }));
-        return { pageTree, breadcrumbPaths, pagesByUrl, headingIndex, allPosts };
+        return { pageTree, breadcrumbPaths, pagesByUrl, headingIndex, allPosts, registry };
     },
     postProcess(page, aggregated, ctx) {
         const coreData = aggregated['__core__'];
@@ -1081,6 +1250,7 @@ export const corePipelineHooks = {
         let renderable = resolveAutoBreadcrumbs(page.renderable, page.url, coreData.breadcrumbPaths, coreData.pagesByUrl, ctx);
         renderable = resolveAutoNavs(renderable, page.url, coreData.pagesByUrl, ctx);
         renderable = resolveBlogPosts(renderable, coreData.allPosts, ctx, page.url);
+        renderable = resolveXrefs(renderable, page.url, coreData.registry, ctx);
         if (renderable === page.renderable)
             return page;
         return { ...page, renderable };