@fusion.dev/helix 0.106.0 → 0.108.0

package/custom-elements.json

@@ -112209,6 +112209,21 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "src/rehype.ts",
+      "declarations": [],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "rehypeHelix",
+          "declaration": {
+            "name": "rehypeHelix",
+            "module": "src/rehype.ts"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "src/sandbox/index.ts",

package/dist/rehype.d.ts

@@ -0,0 +1,54 @@
+/**
+ * **A rehype plugin that gives Markdown's two missing constructs their Helix
+ * elements, and parses nothing.** Your Markdown library turns `###` into
+ * `<h3>`, and `data-prose` styles the HTML it writes. Two constructs carry
+ * what plain HTML cannot: a code fence, which a reader copies and which has a
+ * language, and a GitHub alert, which says how much a passage matters. This
+ * rewrites those two in the tree your parser already built, after your own
+ * sanitizing, and leaves everything else as it is.
+ *
+ * - A fence becomes `helix-code-block`, labeled with its language. What is
+ *   inside the code is kept, so a highlighter that ran before this has its
+ *   colors kept too.
+ * - An alert, `> [!NOTE]` through `> [!CAUTION]`, becomes `helix-callout`: a
+ *   note is `info`, a tip `success`, a warning `warning`, and a caution
+ *   `danger`. An important passage has no tone, since none of the four says
+ *   it. Each keeps its kind as its heading, as GitHub shows it.
+ *
+ * Any pipeline that reaches rehype takes it: `remark` with `remark-rehype`,
+ * `react-markdown`, and MDX.
+ *
+ * ```js
+ * import rehypeHelix from '@fusion.dev/helix/rehype'
+ *
+ * unified().use(remarkParse).use(remarkRehype).use(rehypeHelix).use(rehypeStringify)
+ * ```
+ */
+/** A node of the HTML tree, as far as this plugin reads one. */
+interface HastNode {
+    children?: HastNode[];
+    properties?: Record<string, unknown>;
+    tagName?: string;
+    type: string;
+    value?: string;
+}
+/** The five kinds of GitHub alert. */
+export type AlertKind = 'caution' | 'important' | 'note' | 'tip' | 'warning';
+/** What the plugin rewrites, and what it calls each alert. */
+export interface RehypeHelixOptions {
+    /** Whether alerts become callouts. `true` by default. */
+    alerts?: boolean | undefined;
+    /**
+     * Whether fences become code blocks. `true` by default; `false` where the
+     * page draws its own fences, as a site that highlights them itself does.
+     */
+    fences?: boolean | undefined;
+    /** An alert's heading by its kind, for a page in another language. English by default. */
+    headings?: Partial<Record<AlertKind, string>> | undefined;
+}
+/**
+ * The plugin: rewrites the tree in place, from the top down, so a fence
+ * inside an alert becomes a code block inside a callout.
+ */
+export default function rehypeHelix(options?: RehypeHelixOptions): (tree: HastNode) => void;
+export { rehypeHelix };

package/dist/rehype.js

@@ -0,0 +1,100 @@
+const TONES = {
+    caution: 'danger',
+    important: undefined,
+    note: 'info',
+    tip: 'success',
+    warning: 'warning',
+};
+const HEADINGS = {
+    caution: 'Caution',
+    important: 'Important',
+    note: 'Note',
+    tip: 'Tip',
+    warning: 'Warning',
+};
+const MARKER = /^\s*\[!(caution|important|note|tip|warning)\][ \t]*(?:\r?\n|$)/i;
+const blank = (node) => node.type === 'text' && !node.value?.trim();
+const elements = (node) => (node.children ?? []).filter((child) => !blank(child));
+const languageOf = (code) => {
+    const names = code.properties?.className;
+    const list = Array.isArray(names) ? names : typeof names === 'string' ? names.split(/\s+/) : [];
+    const found = list.find((name) => typeof name === 'string' && name.startsWith('language-'));
+    return typeof found === 'string' ? found.slice('language-'.length) : undefined;
+};
+const codeBlockOf = (node) => {
+    const inside = elements(node);
+    const code = inside[0];
+    if (node.tagName !== 'pre' || inside.length !== 1 || code?.tagName !== 'code') {
+        return undefined;
+    }
+    const children = [...(code.children ?? [])];
+    const last = children.at(-1);
+    if (last?.type === 'text' && last.value?.endsWith('\n')) {
+        children[children.length - 1] = { ...last, value: last.value.slice(0, -1) };
+    }
+    const language = languageOf(code);
+    return {
+        children,
+        properties: language ? { label: language } : {},
+        tagName: 'helix-code-block',
+        type: 'element',
+    };
+};
+const calloutOf = (node, headings) => {
+    if (node.tagName !== 'blockquote') {
+        return undefined;
+    }
+    const inside = elements(node);
+    const first = inside[0];
+    const text = first?.tagName === 'p' ? first.children?.[0] : undefined;
+    const match = text?.type === 'text' ? MARKER.exec(text.value ?? '') : null;
+    if (!first || !text || !match) {
+        return undefined;
+    }
+    const kind = (match[1] ?? '').toLowerCase();
+    const rest = (text.value ?? '').slice(match[0].length);
+    const paragraph = {
+        ...first,
+        children: [...(rest ? [{ ...text, value: rest }] : []), ...(first.children ?? []).slice(1)],
+    };
+    if (paragraph.children?.[0]?.tagName === 'br') {
+        paragraph.children = paragraph.children.slice(1);
+    }
+    const body = [...(elements(paragraph).length > 0 ? [paragraph] : []), ...inside.slice(1)];
+    const tone = TONES[kind];
+    return {
+        children: [
+            {
+                children: [{ type: 'text', value: headings[kind] }],
+                properties: { slot: 'heading' },
+                tagName: 'span',
+                type: 'element',
+            },
+            ...body,
+        ],
+        properties: tone ? { tone } : {},
+        tagName: 'helix-callout',
+        type: 'element',
+    };
+};
+export default function rehypeHelix(options = {}) {
+    const headings = { ...HEADINGS, ...options.headings };
+    const rewrite = (node) => {
+        const children = node.children;
+        if (!children) {
+            return;
+        }
+        children.forEach((child, index) => {
+            const replaced = (options.fences !== false ? codeBlockOf(child) : undefined) ??
+                (options.alerts !== false ? calloutOf(child, headings) : undefined);
+            if (replaced) {
+                children[index] = replaced;
+            }
+            rewrite(children[index]);
+        });
+    };
+    return (tree) => {
+        rewrite(tree);
+    };
+}
+export { rehypeHelix };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix",
   "description": "Styled component tier. Extends the headless tier with token-driven presentation.",
-  "version": "0.106.0",
+  "version": "0.108.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -23,6 +23,10 @@
     },
     "./custom-elements.json": "./custom-elements.json",
     "./jsx": "./types/jsx.d.ts",
+    "./rehype": {
+      "types": "./dist/rehype.d.ts",
+      "default": "./dist/rehype.js"
+    },
     "./svelte": "./types/svelte.d.ts",
     "./vue": "./types/vue.d.ts"
   },
@@ -47,18 +51,21 @@
   },
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "dependencies": {
-    "@fusion.dev/helix-core": "0.106.0",
-    "@fusion.dev/helix-headless": "0.106.0",
-    "@fusion.dev/helix-styles": "0.106.0"
+    "@fusion.dev/helix-core": "0.108.0",
+    "@fusion.dev/helix-headless": "0.108.0",
+    "@fusion.dev/helix-styles": "0.108.0"
   },
   "devDependencies": {
-    "@fusion.dev/helix-cem": "0.106.0",
-    "@fusion.dev/helix-testing": "0.106.0",
+    "@fusion.dev/helix-cem": "0.108.0",
+    "@fusion.dev/helix-testing": "0.108.0",
     "@fusion.dev/scripts": "0.0.0-dev",
     "@happy-dom/global-registrator": "^20.0.0",
     "@lit-labs/ssr": "^4.1.0",
     "@types/bun": "^1.3.0",
-    "lit": "^3.2.1"
+    "lit": "^3.2.1",
+    "remark-parse": "^11.0.0",
+    "remark-rehype": "^11.1.2",
+    "unified": "^11.0.5"
   },
   "homepage": "https://fusion.dev",
   "keywords": [