@refrakt-md/runes 0.16.0 → 0.16.1

package/dist/xref-preview-resolve.js

@@ -0,0 +1,188 @@
+/**
+ * xref `preview="drawer"` resolver (SPEC-078, WORK-302).
+ *
+ * Runs BEFORE the drawer hoist pass. Walks the page renderable, finds
+ * xref placeholders carrying `data-xref-preview="drawer"`, and rewrites
+ * each as an inline `<a href="#drawer-{entityId}">` (with aria attrs)
+ * accompanied by a `hoist-drawer` sentinel that the drawer pipeline
+ * (WORK-300) picks up to render the actual drawer at the page root.
+ *
+ * Non-preview xref placeholders pass through unchanged — the existing
+ * `resolveXrefs` pass (later in the pipeline) handles those.
+ *
+ * Also registers a hoist builder for the `xref` source. The builder
+ * looks up the entity by id and emits a drawer whose body is an
+ * `expand-pending` placeholder for the entity — the `resolveExpands`
+ * pass that runs *after* the hoist substitutes the placeholder with
+ * the entity's actual content, so the drawer body ends up identical
+ * to a manual `{% drawer %}{% expand "X" /%}{% /drawer %}`.
+ */
+import Markdoc from '@markdoc/markdoc';
+import { HOIST_DRAWER_SENTINEL, registerHoistBuilder, } from './drawer-pipeline.js';
+import { XREF_RUNE_MARKER } from './tags/xref.js';
+import { EXPAND_PLACEHOLDER_MARKER } from './tags/expand.js';
+const { Tag } = Markdoc;
+function isTag(node) {
+    return Tag.isTag(node);
+}
+/**
+ * Walk a page's renderable. For each xref placeholder with
+ * `data-xref-preview="drawer"`:
+ *
+ *   - Replace the placeholder span with `<a href="#drawer-{id}">` carrying
+ *     `aria-controls`, `aria-expanded="false"`, `data-target-type="drawer"`.
+ *   - Emit a sibling `<meta data-field="hoist-drawer">` sentinel with
+ *     `data-source="xref"` + the entity id + the authored label, for the
+ *     drawer pipeline to consume.
+ *
+ * Non-preview xref placeholders are left for `resolveXrefs` to handle in
+ * its own pass.
+ */
+export function resolveXrefPreviews(renderable, pageUrl, registry, ctx) {
+    const walk = (node) => {
+        if (Array.isArray(node)) {
+            let mutated = false;
+            const out = [];
+            for (const c of node) {
+                const w = walk(c);
+                if (w !== c)
+                    mutated = true;
+                if (Array.isArray(w))
+                    out.push(...w);
+                else
+                    out.push(w);
+            }
+            return mutated ? out : node;
+        }
+        if (!isTag(node))
+            return node;
+        const tag = node;
+        if (tag.attributes?.['data-rune'] === XREF_RUNE_MARKER
+            && tag.attributes?.['data-xref-preview'] === 'drawer') {
+            return resolveOne(tag, registry, ctx, pageUrl);
+        }
+        if (!tag.children || tag.children.length === 0)
+            return tag;
+        let mutated = false;
+        const next = [];
+        for (const c of tag.children) {
+            const w = walk(c);
+            if (w !== c)
+                mutated = true;
+            if (Array.isArray(w))
+                next.push(...w);
+            else
+                next.push(w);
+        }
+        if (!mutated)
+            return tag;
+        return new Tag(tag.name, tag.attributes, next);
+    };
+    return walk(renderable);
+}
+function resolveOne(placeholder, registry, ctx, pageUrl) {
+    const attrs = placeholder.attributes;
+    const id = String(attrs['data-xref-id'] ?? '');
+    const authoredLabel = attrs['data-xref-label'];
+    if (!id) {
+        ctx.warn(`xref preview placeholder on ${pageUrl} has no entity id`, pageUrl);
+        return [placeholder];
+    }
+    // Try to resolve the entity title for the inline link label when the
+    // author didn't supply an explicit `label=`. Fall back to the id.
+    const entity = registry ? findEntity(registry, id) : undefined;
+    const label = authoredLabel
+        || (entity ? entityDisplayLabel(entity) : id);
+    const entityTitle = entity ? entityDisplayLabel(entity) : id;
+    const slug = id;
+    const anchor = new Tag('a', {
+        class: 'rf-xref',
+        href: `#drawer-${slug}`,
+        'aria-controls': `drawer-${slug}`,
+        'aria-expanded': 'false',
+        'data-target-type': 'drawer',
+        'data-xref-id': id,
+    }, [label]);
+    const sentinel = new Tag('meta', {
+        'data-field': HOIST_DRAWER_SENTINEL,
+        'data-source': 'xref',
+        'data-target-id': slug,
+        'data-title': entityTitle,
+        'data-entity-id': id,
+    });
+    return [anchor, sentinel];
+}
+function findEntity(registry, id) {
+    const types = registry.getTypes?.() ?? [];
+    for (const type of types) {
+        const e = registry.getById(type, id);
+        if (e)
+            return e;
+    }
+    return undefined;
+}
+function entityDisplayLabel(entity) {
+    const data = entity.data;
+    return String(data.title ?? data.name ?? entity.id);
+}
+// ─────────────────────────────────────────────────────────────────────
+// Hoist builder for the `xref` source — looks up the entity, builds a
+// drawer with an expand-pending body that `resolveExpands` resolves
+// downstream, and a chrome footer linking to the entity's page URL.
+// ─────────────────────────────────────────────────────────────────────
+function buildXrefHoist(payload, context) {
+    const entityId = payload['entity-id'] || payload['target-id'];
+    const targetId = payload['target-id'];
+    const title = payload.title || entityId;
+    if (!entityId || !targetId) {
+        context.ctx.warn(`xref hoist payload missing required entity-id or target-id`, context.pageUrl);
+        return null;
+    }
+    const entity = context.registry ? findEntity(context.registry, entityId) : undefined;
+    // Header — title + close button (same shape author-declared drawers use).
+    const titleHeading = new Tag('h3', { 'data-name': 'title', class: 'rf-drawer__title' }, [title]);
+    const closeButton = new Tag('button', {
+        type: 'button',
+        'aria-label': 'Close',
+        hidden: true,
+        'data-name': 'close',
+        class: 'rf-drawer__close',
+    }, ['×']);
+    const header = new Tag('header', {
+        'data-name': 'header',
+        class: 'rf-drawer__header',
+    }, [titleHeading, closeButton]);
+    // Body — an expand-pending placeholder. `resolveExpands` runs after
+    // `hoistPreviewDrawers` in the pipeline and substitutes this with the
+    // entity's actual content, identical to a hand-authored
+    // `{% drawer %}{% expand "X" /%}{% /drawer %}` composition.
+    const expandPlaceholder = new Tag('div', {
+        'data-rune': EXPAND_PLACEHOLDER_MARKER,
+        'data-expand-id': entityId,
+    }, []);
+    const bodyChildren = [expandPlaceholder];
+    const body = new Tag('div', { 'data-name': 'body', class: 'rf-drawer__body' }, bodyChildren);
+    // Footer — link to the entity's page URL (when one resolves). Hides
+    // silently for entities without a sourceUrl (heading entities,
+    // drawer-target entities).
+    const footerHref = entity?.sourceUrl ?? '';
+    const footer = footerHref
+        ? new Tag('footer', { 'data-name': 'footer', class: 'rf-drawer__footer' }, [
+            new Tag('a', { href: footerHref }, [`View full page →`]),
+        ])
+        : null;
+    const drawerChildren = [header, body];
+    if (footer)
+        drawerChildren.push(footer);
+    return new Tag('section', {
+        id: `drawer-${targetId}`,
+        class: 'rf-drawer',
+        'data-rune': 'drawer',
+        'data-drawer-id': targetId,
+        'data-side': 'right',
+        'data-size': 'md',
+    }, drawerChildren);
+}
+// Register at module load.
+registerHoistBuilder('xref', buildXrefHoist);
+//# sourceMappingURL=xref-preview-resolve.js.map

package/dist/xref-preview-resolve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"xref-preview-resolve.js","sourceRoot":"","sources":["../src/xref-preview-resolve.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@refrakt-md/runes",
   "description": "Semantic Markdoc runes for refrakt.md",
-  "version": "0.16.0",
+  "version": "0.16.1",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -29,8 +29,8 @@
     "build": "tsc"
   },
   "dependencies": {
-    "@refrakt-md/types": "0.16.0",
-    "@refrakt-md/transform": "0.16.0",
+    "@refrakt-md/types": "0.16.1",
+    "@refrakt-md/transform": "0.16.1",
     "@markdoc/markdoc": "0.4.0",
     "reflect-metadata": "^0.2.0",
     "fast-xml-parser": "4.5.1",