repl-sdk 0.0.0 → 1.0.1

package/src/compilers/markdown/parse.js

@@ -0,0 +1,22 @@
+/**
+ * @typedef {import('unified').Plugin} UPlugin
+ */
+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 }[] }>}
+ */
+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 || []
+  );
+  // @ts-ignore - processed is typed as unknown due to unified processor complexity
+  const templateOnly = processed.toString();
+
+  return { text: templateOnly, codeBlocks: liveCode };
+}

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

@@ -0,0 +1,363 @@
+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 { parseMarkdown } from './parse.js';
+import { buildCodeFenceMetaUtils } from './utils.js';
+
+import type { Element, Root as HastRoot } from 'hast';
+import type { Heading, Root as MdastRoot } from 'mdast';
+
+const expect = errorExpect.soft;
+
+function assertOutput(actual: string, expected: string) {
+  const _actual = actual?.split('\n')?.filter(Boolean)?.join('\n')?.trim();
+  const _expected = expected.split('\n').filter(Boolean).join('\n').trim();
+
+  expect(_actual).toBe(_expected);
+}
+
+function assertCodeBlocks(
+  actual: unknown,
+  expected: { code: string; format: string; meta: string }[]
+) {
+  expect(actual).toMatchObject(expected);
+}
+
+const ALLOWED_FORMATS = ['gjs', 'jsx', 'vue', 'svelte', 'hbs'];
+const defaults = {
+  ...buildCodeFenceMetaUtils({
+    getAllowedFormats: () => ALLOWED_FORMATS,
+    getFlavorsFor: (lang) => {
+      if (lang === 'jsx') {
+        return ['react'];
+      }
+
+      return [];
+    },
+    optionsFor: () => ({}),
+  }),
+  ALLOWED_FORMATS,
+};
+
+describe('options', () => {
+  describe('remarkPlugins', () => {
+    it('works', async () => {
+      const result = await parseMarkdown(`# Title`, {
+        ...defaults,
+        remarkPlugins: [
+          function noH1() {
+            return (tree: MdastRoot) => {
+              visit(tree, 'heading', function (node: Heading) {
+                if (node.depth === 1) {
+                  node.depth = 2;
+                }
+              });
+            };
+          },
+        ],
+      });
+
+      expect(result.text).toBe('<h2 id="title">Title</h2>');
+      expect(result.codeBlocks).to.deep.equal([]);
+    });
+
+    it('w/ options', async () => {
+      const result = await parseMarkdown(`# Title`, {
+        ...defaults,
+        remarkPlugins: [
+          [
+            function noH1(options: { depth: 1 | 2 | 3 | 4 | 5 | 6 }) {
+              return (tree: MdastRoot) => {
+                visit(tree, 'heading', function (node: Heading) {
+                  if (node.depth === 1) {
+                    node.depth = options.depth;
+                  }
+                });
+              };
+            },
+            { depth: 3 },
+          ],
+        ],
+      });
+
+      expect(result.text).toBe('<h3 id="title">Title</h3>');
+      expect(result.codeBlocks).to.deep.equal([]);
+    });
+  });
+
+  describe('rehypePlugins', () => {
+    it('works', async () => {
+      const result = await parseMarkdown(`# Title`, {
+        ...defaults,
+        rehypePlugins: [
+          function noH1() {
+            return (tree: HastRoot) => {
+              visit(tree, 'element', function (node: Element) {
+                if (node.tagName === 'h1') {
+                  node.tagName = 'h2';
+                }
+              });
+            };
+          },
+        ],
+      });
+
+      expect(result.text).toBe('<h2 id="title">Title</h2>');
+      expect(result.codeBlocks).to.deep.equal([]);
+    });
+
+    it('w/ options', async () => {
+      const result = await parseMarkdown(`# Title`, {
+        ...defaults,
+        rehypePlugins: [
+          [
+            function noH1(options: { depth: 1 | 2 | 3 | 4 | 5 | 6 }) {
+              return (tree: HastRoot) => {
+                visit(tree, 'element', function (node: Element) {
+                  if (node.tagName === 'h1') {
+                    node.tagName = `h${options.depth ?? 2}`;
+                  }
+                });
+              };
+            },
+            { depth: 3 },
+          ],
+        ],
+      });
+
+      expect(result.text).toBe('<h3 id="title">Title</h3>');
+      expect(result.codeBlocks).to.deep.equal([]);
+    });
+
+    it('retains {{ }} escaping', async () => {
+      const result = await parseMarkdown(
+        stripIndent`
+        # Title
+
+        \`\`\`gjs
+        const two = 2
+
+        <template>
+          {{two}}
+        </template>
+        \`\`\`
+      `,
+        {
+          ...defaults,
+          rehypePlugins: [[rehypeShiki, { theme: 'github-dark' }]],
+        }
+      );
+
+      assertOutput(
+        result.text,
+        `<h1 id="title">Title</h1>
+<div class="repl-sdk__snippet" data-repl-output><pre class="shiki github-dark" style="background-color:#24292e;color:#e1e4e8" tabindex="0"><code><span class="line"><span style="color:#F97583">const</span><span style="color:#79B8FF"> two</span><span style="color:#F97583"> =</span><span style="color:#79B8FF"> 2</span></span>
+<span class="line"></span>
+<span class="line"><span style="color:#E1E4E8">&#x3C;</span><span style="color:#85E89D">template</span><span style="color:#E1E4E8">></span></span>
+<span class="line"><span style="color:#F97583">  \\{{</span><span style="color:#79B8FF">two</span><span style="color:#F97583">}}</span></span>
+<span class="line"><span style="color:#E1E4E8">&#x3C;/</span><span style="color:#85E89D">template</span><span style="color:#E1E4E8">></span></span></code></pre></div>`
+      );
+    });
+  });
+
+  describe('codefences', () => {
+    describe('hbs', () => {
+      it('Code fence is live', async () => {
+        const snippet = `{{concat "hello" " " "there"}}`;
+        const result = await parseMarkdown(
+          stripIndent`
+          # Title
+
+          \`\`\`hbs live
+            ${snippet}
+          \`\`\`
+        `.trim(),
+          { ...defaults }
+        );
+
+        expect(result.text).toMatchInlineSnapshot(`
+          "<h1 id="title">Title</h1>
+          <div id="repl_1" class="repl-sdk__demo"></div>"
+        `);
+
+        assertCodeBlocks(result.codeBlocks, [
+          {
+            code: snippet,
+            format: 'hbs',
+            meta: 'live',
+          },
+        ]);
+      });
+    });
+
+    describe('gjs', () => {
+      it('Code fence does not have the "live" keyword', async function () {
+        const result = await parseMarkdown(
+          stripIndent`
+        # Title
+
+        \`\`\`gjs
+          const two = 2;
+        \`\`\`
+      `,
+          { ...defaults }
+        );
+
+        assertOutput(
+          result.text,
+          stripIndent`
+          <h1 id="title">Title</h1>
+
+          <div class=\"repl-sdk__snippet\" data-repl-output><pre><code class=\"language-gjs\">  const two = 2;
+          </code></pre></div>
+        `
+        );
+
+        expect(result.codeBlocks).to.deep.equal([]);
+      });
+
+      it('Code fence is live', async function () {
+        const snippet = `const two = 2`;
+        const result = await parseMarkdown(
+          stripIndent`
+        # Title
+
+        \`\`\`gjs live
+          ${snippet}
+        \`\`\`
+      `,
+          { ...defaults }
+        );
+
+        expect(result.text).toMatchInlineSnapshot(`
+          "<h1 id="title">Title</h1>
+          <div id="repl_2" class="repl-sdk__demo"></div>"
+        `);
+
+        assertCodeBlocks(result.codeBlocks, [
+          {
+            code: snippet,
+            format: 'gjs',
+            meta: 'live',
+          },
+        ]);
+      });
+
+      it('Code with preview fence has {{ }} tokens escaped', async function () {
+        const result = await parseMarkdown(
+          stripIndent`
+        # Title
+
+        \`\`\`gjs
+        const two = 2
+
+        <template>
+          {{two}}
+        </template>
+        \`\`\`
+      `,
+          { ...defaults }
+        );
+
+        assertOutput(
+          result.text,
+          stripIndent`
+          <h1 id="title">Title</h1>
+
+          <div class=\"repl-sdk__snippet\" data-repl-output><pre><code class=\"language-gjs\">const two = 2
+
+          &#x3C;template>
+            \\{{two}}
+          &#x3C;/template>
+          </code></pre></div>
+        `
+        );
+      });
+
+      it('Inline Code with {{ }} tokens is escaped', async function () {
+        const result = await parseMarkdown(
+          stripIndent`
+        # Title
+
+        \`{{ foo }}\`
+      `,
+          { ...defaults }
+        );
+
+        assertOutput(
+          result.text,
+          stripIndent`
+          <h1 id="title">Title</h1>
+          <p><code>\\{{ foo }}</code></p>
+        `
+        );
+      });
+
+      it('Can invoke a component again when defined in a live fence', async function () {
+        const snippet = `const two = 2`;
+        const result = await parseMarkdown(
+          stripIndent`
+      # Title
+
+      \`\`\`gjs live
+        ${snippet}
+      \`\`\`
+      <Demo />
+    `,
+          { ...defaults }
+        );
+
+        expect(result.text).toMatchInlineSnapshot(`
+          "<h1 id="title">Title</h1>
+          <div id="repl_3" class="repl-sdk__demo"></div>
+          <Demo />"
+        `);
+
+        assertCodeBlocks(result.codeBlocks, [
+          {
+            code: snippet,
+            format: 'gjs',
+            meta: 'live',
+          },
+        ]);
+      });
+
+      it('Code fence imports things', async function () {
+        const snippet = stripIndent`
+        import Component from '@glimmer/component';
+        import { on } from '@ember/modifier';
+
+        <template>
+          <button {{on "click" console.log}}>Click</button>
+        </template>
+      `;
+        const result = await parseMarkdown(
+          `hi\n` + `\n` + '```gjs live preview\n' + snippet + '\n```',
+          { ...defaults }
+        );
+
+        expect(result.text).toMatchInlineSnapshot(`
+          "<p>hi</p>
+          <div id="repl_4" 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';
+
+          &#x3C;template>
+            &#x3C;button \\{{on "click" console.log}}>Click&#x3C;/button>
+          &#x3C;/template>
+          </code></pre></div>"
+        `);
+
+        assertCodeBlocks(result.codeBlocks, [
+          {
+            code: snippet,
+            format: 'gjs',
+            meta: 'live preview',
+          },
+        ]);
+      });
+    });
+  });
+});

package/src/compilers/markdown/sanitize-for-glimmer.js

@@ -0,0 +1,26 @@
+import { visit } from 'unist-util-visit';
+
+/**
+ * @type {import('unified').Plugin<[], import('hast').Root>}
+ */
+export function sanitizeForGlimmer(/* options */) {
+  return function transformer(tree) {
+    visit(tree, 'element', function visitor(node) {
+      if (node.type === 'element' && 'tagName' in node) {
+        const element = /** @type {import('hast').Element} */ (node);
+
+        if (!['pre', 'code'].includes(element.tagName)) return;
+
+        visit(node, 'text', function textVisitor(textNode) {
+          if (textNode.type === 'text') {
+            const text = /** @type {import('hast').Text} */ (textNode);
+
+            text.value = text.value.replace(/{{/g, '\\{{');
+          }
+        });
+
+        return 'skip';
+      }
+    });
+  };
+}

package/src/compilers/markdown/types.ts

@@ -0,0 +1,21 @@
+export interface LiveCodeExtractionOptions {
+  isLive?: (meta: string, lang: string) => boolean;
+  ALLOWED_FORMATS?: string[];
+  isPreview?: (meta: string) => boolean;
+  isBelow?: (meta: string) => boolean;
+  needsLive?: (lang: string) => boolean;
+  getFlavorFromMeta?: (meta: string, lang: string) => string | undefined;
+}
+
+export interface PublicOptions {
+  code?: {
+    classList?: string[];
+  };
+  demo?: {
+    classList?: string[];
+  };
+  remarkPlugins?: unknown[];
+  rehypePlugins?: unknown[];
+}
+
+export type InternalOptions = PublicOptions & LiveCodeExtractionOptions;

package/src/compilers/markdown/utils.js

@@ -0,0 +1,78 @@
+/**
+ * @param {string} lang
+ */
+export function isNotMarkdownLike(lang) {
+  return lang !== 'md' && lang !== 'gmd' && lang !== 'mdx';
+}
+
+/**
+ * @param {string} meta
+ */
+export function isPreview(meta) {
+  if (!meta) return false;
+
+  return meta.includes('preview');
+}
+
+/**
+ * @param {string} meta
+ */
+export function isBelow(meta) {
+  if (!meta) return false;
+
+  return meta.includes('below');
+}
+
+/**
+ * @param {Pick<import('../../types').PublicMethods, 'getAllowedFormats' | 'getFlavorsFor' | 'optionsFor'>} api
+ */
+export function buildCodeFenceMetaUtils(api) {
+  const allowedFormats = api.getAllowedFormats().filter(isNotMarkdownLike);
+
+  /**
+   * @param {string} lang
+   * @param {string | undefined} [ flavor ]
+   */
+  function needsLive(lang, flavor) {
+    if (!allowedFormats.includes(lang)) return false;
+
+    return api.optionsFor(lang, flavor).needsLiveMeta ?? true;
+  }
+
+  /**
+   * @param {string} meta
+   * @param {string} lang
+   */
+  function getFlavorFromMeta(meta, lang) {
+    const flavors = api.getFlavorsFor(lang);
+
+    const flavor = meta
+      ?.trim()
+      .split(' ')
+      .find((metum) => flavors.includes(metum));
+
+    return flavor;
+  }
+
+  /**
+   * @param {string} meta
+   * @param {string} lang
+   */
+  function isLive(meta, lang) {
+    const flavor = getFlavorFromMeta(meta, lang);
+
+    if (!needsLive(lang, flavor)) return true;
+    if (!meta) return false;
+
+    return meta.includes('live');
+  }
+
+  return {
+    isPreview,
+    isBelow,
+    isLive,
+    needsLive,
+    allowedFormats,
+    getFlavorFromMeta,
+  };
+}

package/src/compilers/markdown.js

@@ -0,0 +1,125 @@
+/**
+ * @typedef {import('unified').Plugin} Plugin
+ */
+import { assert, isRecord } from '../utils.js';
+import { buildCodeFenceMetaUtils } from './markdown/utils.js';
+
+/**
+ * @param {unknown} [ options ]
+ * @returns {{ remarkPlugins: Plugin[], rehypePlugins: Plugin[] }}
+ */
+export function filterOptions(options) {
+  if (!isRecord(options)) {
+    return { remarkPlugins: [], rehypePlugins: [] };
+  }
+
+  return {
+    remarkPlugins: /** @type {Plugin[]}*/ (options?.remarkPlugins || []),
+    rehypePlugins: /** @type {Plugin[]}*/ (options?.rehypePlugins || []),
+  };
+}
+
+/**
+ * @type {import('../types.ts').CompilerConfig}
+ */
+export const md = {
+  codemirror: {
+    lang: async () => {
+      const { glimdown } = await import('codemirror-lang-glimdown');
+
+      /**
+       * pre-configured markdown with GFM, and a few other extensions
+       */
+      return glimdown();
+    },
+  },
+  compiler: async (config, api) => {
+    const { isLive, isPreview, needsLive, allowedFormats, isBelow, getFlavorFromMeta } =
+      buildCodeFenceMetaUtils(api);
+
+    // Try both possible structures
+    const userOptions = filterOptions(
+      /** @type {Record<string, unknown>} */ (config.userOptions)?.md || config
+    );
+
+    // No recursing for now.
+
+    const { parseMarkdown } = await import('./markdown/parse.js');
+
+    /**
+     * @type {import('../types.ts').Compiler}
+     */
+    return {
+      compile: async (text, options) => {
+        const compileOptions = filterOptions(options);
+        const result = await parseMarkdown(text, {
+          remarkPlugins: [...userOptions.remarkPlugins, ...compileOptions.remarkPlugins],
+          rehypePlugins: [...userOptions.rehypePlugins, ...compileOptions.rehypePlugins],
+          isLive,
+          isPreview,
+          isBelow,
+          needsLive,
+          ALLOWED_FORMATS: allowedFormats,
+          getFlavorFromMeta,
+        });
+        const escaped = result.text.replace(/`/g, '\\`');
+
+        return { compiled: `export default \`${escaped}\``, ...result };
+      },
+      render: async (element, compiled, extra, compiler) => {
+        element.innerHTML = /** @type {string} */ (compiled);
+
+        /**
+         * @type {(() => void)[]}
+         */
+        const destroyables = [];
+
+        await Promise.all(
+          /** @type {unknown[]} */ (extra.codeBlocks).map(async (/** @type {unknown} */ info) => {
+            /** @type {Record<string, unknown>} */
+            const infoObj = /** @type {Record<string, unknown>} */ (info);
+
+            if (
+              !api.canCompile(
+                /** @type {string} */ (infoObj.format),
+                /** @type {string} */ (infoObj.flavor)
+              )
+            ) {
+              return;
+            }
+
+            const flavor = /** @type {string} */ (infoObj.flavor);
+            const subRender = await compiler.compile(
+              /** @type {string} */ (infoObj.format),
+              /** @type {string} */ (infoObj.code),
+              {
+                ...compiler.optionsFor(/** @type {string} */ (infoObj.format), flavor),
+                flavor: flavor,
+              }
+            );
+
+            const selector = `#${/** @type {string} */ (infoObj.placeholderId)}`;
+            const target = element.querySelector(selector);
+
+            assert(
+              `Could not find placeholder / target element (using selector: \`${selector}\`). ` +
+                `Could not render ${/** @type {string} */ (infoObj.format)} block.`,
+              target
+            );
+
+            destroyables.push(subRender.destroy);
+            target.appendChild(subRender.element);
+          })
+        );
+
+        compiler.announce('info', 'Done');
+
+        return () => {
+          for (const subDestroy of destroyables) {
+            subDestroy();
+          }
+        };
+      },
+    };
+  },
+};

package/src/compilers/mermaid.js

@@ -0,0 +1,35 @@
+import { esmsh } from '../cdn.js';
+
+/**
+ * @type {import('../types.ts').CompilerConfig}
+ */
+export const mermaid = {
+  needsLiveMeta: false,
+  codemirror: {
+    lang: async () => {
+      const { mermaid } = await import('codemirror-lang-mermaid');
+
+      return mermaid();
+    },
+  },
+  compiler: async (config, api) => {
+    const versions = config.versions;
+    const { default: mermaid } = await api.tryResolve('mermaid', () => {
+      return esmsh.import(versions, 'mermaid');
+    });
+
+    let id = 0;
+
+    return {
+      compile: async (text) => {
+        return `export default \`${text}\`;`;
+      },
+      render: async (element, text, _, compiler) => {
+        const { svg } = await mermaid.render('graphDiv' + id++, text);
+
+        element.innerHTML = svg;
+        compiler.announce('info', 'Done');
+      },
+    };
+  },
+};