repl-sdk 1.1.2 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "repl-sdk",
-  "version": "1.1.2",
+  "version": "1.2.0",
   "type": "module",
   "exports": {
     ".": {
@@ -42,28 +42,28 @@
     "typescript": "^5.9.3",
     "vite": "^7.3.1",
     "vite-plugin-dts": "4.5.4",
-    "vitest": "^3.2.4"
+    "vitest": "^4.0.18"
   },
   "dependencies": {
-    "@codemirror/autocomplete": "6.20.0",
-    "@codemirror/commands": "6.10.1",
+    "@codemirror/autocomplete": "^6.20.0",
+    "@codemirror/commands": "^6.10.1",
     "@codemirror/lang-html": "^6.4.11",
-    "@codemirror/lang-javascript": "6.2.4",
-    "@codemirror/lang-markdown": "6.5.0",
+    "@codemirror/lang-javascript": "^6.2.4",
+    "@codemirror/lang-markdown": "^6.5.0",
     "@codemirror/lang-vue": "^0.1.3",
     "@codemirror/lang-yaml": "^6.1.2",
     "@codemirror/language": "^6.12.1",
     "@codemirror/language-data": "^6.5.2",
-    "@codemirror/lint": "^6.9.2",
-    "@codemirror/search": "6.5.11",
-    "@codemirror/state": "6.5.3",
-    "@codemirror/view": "6.39.9",
+    "@codemirror/lint": "^6.9.3",
+    "@codemirror/search": "^6.6.0",
+    "@codemirror/state": "^6.5.4",
+    "@codemirror/view": "^6.39.12",
     "@lezer/common": "^1.5.0",
     "@lezer/highlight": "^1.2.3",
     "@lezer/html": "^1.3.13",
     "@lezer/markdown": "^1.6.3",
     "@replit/codemirror-lang-svelte": "^6.0.0",
-    "@shikijs/rehype": "^3.7.0",
+    "@shikijs/rehype": "^3.22.0",
     "change-case": "^5.4.4",
     "codemirror": "^6.0.2",
     "codemirror-lang-mermaid": "^0.5.0",
@@ -73,7 +73,9 @@
     "mdast": "^3.0.0",
     "mime": "^4.0.7",
     "package-name-regex": "^5.0.0",
+    "rehype-autolink-headings": "^7.1.0",
     "rehype-raw": "^7.0.0",
+    "rehype-slug": "^6.0.0",
     "rehype-stringify": "^10.0.1",
     "remark-gfm": "^4.0.1",
     "remark-parse": "^11.0.0",
@@ -84,9 +86,9 @@
     "unified": "^11.0.5",
     "unist-util-visit": "^5.0.0",
     "vfile": "^6.0.3",
-    "codemirror-lang-glimdown": "2.0.2",
-    "codemirror-lang-glimmer-js": "2.0.2",
-    "codemirror-lang-glimmer": "2.0.2"
+    "codemirror-lang-glimdown": "^2.0.3",
+    "codemirror-lang-glimmer-js": "^2.0.3",
+    "codemirror-lang-glimmer": "^2.0.3"
   },
   "volta": {
     "extends": "../../package.json"

package/src/compilers/markdown/build-compiler.js

@@ -40,6 +40,39 @@ export function buildCompiler(options) {
     });
   }
 
+  // Mark raw HTML components (PascalCase) before remarkRehype processes them
+  // @ts-ignore - unified processor types are complex and change as plugins are added
+  compiler = compiler.use(() => (tree) => {
+    visit(tree, 'html', function (node) {
+      // Check if this html node is a PascalCase component
+      if (typeof node.value === 'string' && node.value.match(/^<[A-Z][a-zA-Z0-9]/)) {
+        // Add a marker to the node's data that remarkRehype will preserve
+        // remark-rehype with allowDangerousHtml will turn this into a text node,
+        // and the data should be preserved
+        if (!node.data) node.data = {};
+        node.data.isPascalCaseComponent = true;
+      }
+    });
+
+    // After markinghtml nodes, also visit paragraphs to mark their children
+    visit(tree, 'paragraph', (paragraph) => {
+      if (paragraph.children) {
+        for (let i = 0; i < paragraph.children.length; i++) {
+          const child = paragraph.children[i];
+
+          if (
+            child.type === 'html' &&
+            typeof child.value === 'string' &&
+            child.value.match(/^<[A-Z][a-zA-Z0-9]/)
+          ) {
+            if (!child.data) child.data = {};
+            child.data.isPascalCaseComponent = true;
+          }
+        }
+      }
+    });
+  });
+
   // TODO: we only want to do this when we have pre > code.
   //       code can exist inline.
   // @ts-ignore - unified processor types are complex and change as plugins are added
@@ -65,6 +98,10 @@ export function buildCompiler(options) {
   // However, it also changes all the nodes, so we need another pass
   // to make sure our Glimmer-aware nodes are in tact
   // @ts-ignore - unified processor types are complex and change as plugins are added
+  // remark rehype is needed to convert markdown to HTML
+  // However, it also changes all the nodes, so we need another pass
+  // to make sure our Glimmer-aware nodes are in tact
+  // @ts-ignore - unified processor types are complex and change as plugins are added
   compiler = compiler.use(remarkRehype, { allowDangerousHtml: true });
 
   // Convert invocables to raw format, so Glimmer can invoke them
@@ -81,6 +118,15 @@ export function buildCompiler(options) {
         return 'skip';
       }
 
+      // Check for PascalCase elements FIRST before checking for code elements
+      const tagName = /** @type {string | undefined} */ (nodeObj.tagName);
+
+      if (tagName && /^[A-Z]/.test(tagName)) {
+        nodeObj.type = 'glimmer_raw';
+
+        return 'skip';
+      }
+
       if (nodeObj.type === 'element' || ('tagName' in nodeObj && nodeObj.tagName === 'code')) {
         if (properties?.[/** @type {string} */ (/** @type {unknown} */ (GLIMDOWN_RENDER))]) {
           nodeObj.type = 'glimmer_raw';
@@ -91,19 +137,32 @@ export function buildCompiler(options) {
         return 'skip';
       }
 
-      if (nodeObj.type === 'text' || nodeObj.type === 'raw') {
-        // definitively not the better way, but this is supposed to detect "glimmer" nodes
+      // Check for nodes with values (text, raw, html, etc.)
+      if ('value' in nodeObj && typeof nodeObj.value === 'string') {
+        // Check if this raw node was marked as a PascalCase component in remark phase
+        const nodeData = /** @type {Record<string, unknown> | undefined} */ (
+          typeof node === 'object' && node !== null && 'data' in node ? node.data : undefined
+        );
+
+        if (nodeData?.isPascalCaseComponent) {
+          nodeObj.type = 'glimmer_raw';
+
+          return 'skip';
+        }
+
+        // Match raw PascalCase components in text that haven't been escaped yet
+        // Pattern: <PascalCaseName followed by whitespace, > or @
         if (
-          'value' in nodeObj &&
-          typeof nodeObj.value === 'string' &&
-          nodeObj.value.match(/<\/?[_A-Z:0-9].*>/g)
+          (nodeObj.type === 'text' || nodeObj.type === 'raw' || nodeObj.type === 'html') &&
+          nodeObj.value.match(/<[A-Z][a-zA-Z0-9]*(\s|>|@)/)
         ) {
           nodeObj.type = 'glimmer_raw';
-        }
 
-        nodeObj.type = 'glimmer_raw';
+          return 'skip';
+        }
 
-        return 'skip';
+        // Let normal nodes be processed for escaping
+        return;
       }
 
       return;

package/src/compilers/markdown/parse.js

@@ -1,22 +1,55 @@
 /**
- * @typedef {import('unified').Plugin} UPlugin
+ * @typedef {object} CodeBlock
+ * @property {string} lang
+ * @property {string} format
+ * @property {string} code
+ * @property {string} name
  */
+
+/**
+ * @typedef {object} ParseResult
+ * @property {string} text
+ * @property {CodeBlock[]} codeBlocks
+ */
+
 import { buildCompiler } from './build-compiler.js';
 
 /**
  * @param {string} input
  * @param {import('./types').InternalOptions} options
- *
- * @returns {Promise<{ text: string; codeBlocks: { lang: string; format: string; code: string; name: string }[] }>}
+ * @returns {Promise<ParseResult>}
  */
 export async function parseMarkdown(input, options) {
   const markdownCompiler = buildCompiler(options);
   const processed = await markdownCompiler.process(input);
-  const liveCode = /** @type {{ lang: string; format: string; code: string; name: string }[]} */ (
-    processed.data.liveCode || []
-  );
+  const liveCode = /** @type {CodeBlock[]} */ (processed.data.liveCode || []);
   // @ts-ignore - processed is typed as unknown due to unified processor complexity
-  const templateOnly = processed.toString();
+  let templateOnly = processed.toString();
+
+  // Unescape PascalCase components that had only the opening < HTML-entity escaped
+  // BUT only outside of <pre><code> blocks where escaping should be preserved
+  // (inline <code> tags should have components unescaped)
+  // Split by <pre><code>...</code></pre> to exclude only code blocks
+  const parts = templateOnly.split(/(<pre[^>]*>.*?<\/pre>)/is);
+
+  for (let i = 0; i < parts.length; i++) {
+    const part = parts[i];
+
+    // Only process parts that are NOT pre blocks (odd indices are pre blocks)
+    if (i % 2 === 0 && part) {
+      // Pattern: &#x3C;ComponentName ... / > (only < is escaped as &#x3C;)
+      parts[i] = part.replace(/&#x3C;([A-Z][a-zA-Z0-9]*\s[^<]*?)>/g, (match, content) => {
+        // Only unescape if it contains @ (attribute) indicating a component
+        if (content.includes('@')) {
+          return `<${content}>`;
+        }
+
+        return match;
+      });
+    }
+  }
+
+  templateOnly = parts.join('');
 
   return { text: templateOnly, codeBlocks: liveCode };
 }

package/src/compilers/markdown/parse.test.ts

@@ -1,8 +1,9 @@
 import rehypeShiki from '@shikijs/rehype';
 import { stripIndent } from 'common-tags';
 import { visit } from 'unist-util-visit';
-import { describe, expect as errorExpect, it } from 'vitest';
+import { beforeEach, describe, expect as errorExpect, it } from 'vitest';
 
+import { resetIdCounter } from '../../utils.js';
 import { parseMarkdown } from './parse.js';
 import { buildCodeFenceMetaUtils } from './utils.js';
 
@@ -41,6 +42,174 @@ const defaults = {
   ALLOWED_FORMATS,
 };
 
+beforeEach(() => {
+  resetIdCounter();
+});
+
+describe('default features', () => {
+  it('allows one-line-component invocation', { timeout: 10_000 }, async () => {
+    const result = await parseMarkdown(`<APIDocs @package="ember-primitives" @name="Avatar" />`, {
+      ...defaults,
+      rehypePlugins: [[rehypeShiki, { theme: 'github-dark' }]],
+    });
+
+    expect(result.codeBlocks).toMatchInlineSnapshot(`[]`);
+    expect(result.text).toMatchInlineSnapshot(
+      `"<p><APIDocs @package="ember-primitives" @name="Avatar" /></p>"`
+    );
+  });
+
+  it('allows multi-line-component invocation', async () => {
+    const result = await parseMarkdown(
+      [`<APIDocs`, `@package="ember-primitives"`, `@name="Avatar"`, `/>`].join('\n'),
+      {
+        ...defaults,
+        rehypePlugins: [[rehypeShiki, { theme: 'github-dark' }]],
+      }
+    );
+
+    expect(result.codeBlocks).toMatchInlineSnapshot(`[]`);
+    expect(result.text).toMatchInlineSnapshot(`
+      "<p><APIDocs
+      @package="ember-primitives"
+      @name="Avatar"
+      /></p>"
+    `);
+  });
+
+  it('allows components inside code blocks', async () => {
+    const result = await parseMarkdown(
+      [
+        '# Hello',
+        '',
+        '<code>',
+        '  <Shadowed @includeStyles={{true}}>',
+        '     the shadow realm',
+        '  </Shadowed>',
+        '</code>',
+      ].join('\n'),
+      {
+        ...defaults,
+      }
+    );
+
+    expect(result.codeBlocks).toMatchInlineSnapshot(`[]`);
+    expect(result.text).toMatchInlineSnapshot(`
+        "<h1 id="hello">Hello</h1>
+        <code>
+          <Shadowed @includeStyles={{true}}>
+             the shadow realm
+          </Shadowed>
+        </code>"
+      `);
+  });
+
+  describe('does not', () => {
+    it(`mistakenly transform text in codefences (previewed text is transformed though)`, async () => {
+      const result = await parseMarkdown(
+        [
+          '# Hello',
+          '',
+          '```gjs live preview',
+          "import { Shadowed, PortalTargets } from 'ember-primitives';",
+          '',
+          '<template>',
+          '  <Shadowed @includeStyles={{true}}>',
+          '     the shadow realm',
+          '  </Shadowed>',
+          '</template>',
+        ].join('\n'),
+        {
+          ...defaults,
+        }
+      );
+
+      expect(result.codeBlocks).toMatchInlineSnapshot(`
+        [
+          {
+            "code": "import { Shadowed, PortalTargets } from 'ember-primitives';
+
+        <template>
+          <Shadowed @includeStyles={{true}}>
+             the shadow realm
+          </Shadowed>
+        </template>",
+            "flavor": undefined,
+            "format": "gjs",
+            "meta": "live preview",
+            "placeholderId": "repl_1",
+          },
+        ]
+      `);
+      expect(result.text).toMatchInlineSnapshot(`
+        "<h1 id="hello">Hello</h1>
+        <div id="repl_1" class="repl-sdk__demo"></div>
+        <div class="repl-sdk__snippet" data-repl-output><pre><code class="language-gjs">import { Shadowed, PortalTargets } from 'ember-primitives';
+
+        &#x3C;template>
+          &#x3C;Shadowed @includeStyles=\\{{true}}>
+             the shadow realm
+          &#x3C;/Shadowed>
+        &#x3C;/template>
+        </code></pre></div>"
+      `);
+    });
+
+    it(`mistakenly transform text in codefences`, async () => {
+      const result = await parseMarkdown(
+        [
+          '# Hello',
+          '',
+          '```gjs live',
+          'import { Hello } from "somewhere";',
+          '',
+          '<template>',
+          '  <Hello />',
+          '</template>',
+        ].join('\n'),
+        {
+          ...defaults,
+          rehypePlugins: [[rehypeShiki, { theme: 'github-dark' }]],
+        }
+      );
+
+      expect(result.codeBlocks).toMatchInlineSnapshot(`
+        [
+          {
+            "code": "import { Hello } from "somewhere";
+
+        <template>
+          <Hello />
+        </template>",
+            "flavor": undefined,
+            "format": "gjs",
+            "meta": "live",
+            "placeholderId": "repl_1",
+          },
+        ]
+      `);
+      expect(result.text).toMatchInlineSnapshot(`
+        "<h1 id="hello">Hello</h1>
+        <div id="repl_1" class="repl-sdk__demo"></div>"
+      `);
+    });
+
+    it('mistakenly transform a component text in backticks', async () => {
+      const result = await parseMarkdown('## `<Hello @foo="two" />`', {
+        ...defaults,
+        rehypePlugins: [[rehypeShiki, { theme: 'github-dark' }]],
+      });
+
+      expect(result).toMatchInlineSnapshot(`
+        {
+          "codeBlocks": [],
+          "text": "<h2 id="hello-foo-two"><code><Hello @foo="two" /></code></h2>",
+        }
+      `);
+    });
+  });
+});
+
 describe('options', () => {
   describe('remarkPlugins', () => {
     it('works', async () => {
@@ -233,7 +402,7 @@ describe('options', () => {
 
         expect(result.text).toMatchInlineSnapshot(`
           "<h1 id="title">Title</h1>
-          <div id="repl_2" class="repl-sdk__demo"></div>"
+          <div id="repl_1" class="repl-sdk__demo"></div>"
         `);
 
         assertCodeBlocks(result.codeBlocks, [
@@ -311,7 +480,7 @@ describe('options', () => {
 
         expect(result.text).toMatchInlineSnapshot(`
           "<h1 id="title">Title</h1>
-          <div id="repl_3" class="repl-sdk__demo"></div>
+          <div id="repl_1" class="repl-sdk__demo"></div>
           <Demo />"
         `);
 
@@ -340,7 +509,7 @@ describe('options', () => {
 
         expect(result.text).toMatchInlineSnapshot(`
           "<p>hi</p>
-          <div id="repl_4" class="repl-sdk__demo"></div>
+          <div id="repl_1" class="repl-sdk__demo"></div>
           <div class="repl-sdk__snippet" data-repl-output><pre><code class="language-gjs">import Component from '@glimmer/component';
           import { on } from '@ember/modifier';
 

package/src/utils.js

@@ -17,6 +17,10 @@ export function nextId() {
   return `repl_${i}`;
 }
 
+export function resetIdCounter() {
+  i = 0;
+}
+
 export const fakeDomain = 'repl.sdk';
 export const tgzPrefix = 'file:///tgz.repl.sdk/';
 export const unzippedPrefix = 'file:///tgz.repl.sdk/unzipped';