Merge pull request #917 from Godefroy/feat/codemirror-language-support

feat: support pre-loaded language support in codeMirrorPlugin

Author: petyosi

docs/code-blocks.md

@@ -133,6 +133,60 @@ import { languages } from '@codemirror/language-data'
 codeMirrorPlugin({ codeBlockLanguages: languages })
 ```
 
+### Pre-loaded language support
+
+When using the array format, you can provide a `support` property with a pre-loaded `LanguageSupport` instance. This is useful for languages that are not included in `@codemirror/language-data` and cannot be auto-loaded.
+
+When `support` is provided for a language, it takes priority over auto-loading. Languages without a `support` property will still be auto-loaded as usual, unless `autoLoadLanguageSupport` is set to `false` (see below).
+
+```tsx
+import { graphql } from 'cm6-graphql'
+
+codeMirrorPlugin({
+  codeBlockLanguages: [
+    { name: 'JavaScript', alias: ['js', 'javascript'] },
+    { name: 'CSS', alias: ['css'] },
+    { name: 'GraphQL', alias: ['graphql', 'gql'], support: graphql() }
+  ]
+})
+```
+
+### Custom CodeMirror extensions
+
+The `codeMirrorExtensions` option lets you pass additional CodeMirror extensions that will be applied to all code block editors. This can be used to add custom keymaps, themes, or other CodeMirror plugins.
+
+```tsx
+import { keymap, EditorView } from '@codemirror/view'
+import { toggleLineComment } from '@codemirror/commands'
+
+codeMirrorPlugin({
+  codeBlockLanguages: { js: 'JavaScript', css: 'CSS' },
+  codeMirrorExtensions: [
+    EditorView.theme({
+      '&': { backgroundColor: '#f5f5f5' },
+      '.cm-gutters': { backgroundColor: '#e8e8e8 !important' }
+    }),
+    keymap.of([{
+     key: 'Cmd-:', run: toggleLineComment
+    }]),
+  ]
+})
+```
+
+### Auto-loading language support
+
+By default, the plugin dynamically loads language support from `@codemirror/language-data` when a code block's language is recognized. You can disable this by setting `autoLoadLanguageSupport` to `false`. This is useful if you provide all language support manually via the `support` property or through `codeMirrorExtensions`.
+
+```tsx
+codeMirrorPlugin({
+  codeBlockLanguages: [
+    { name: 'Python', alias: ['py', 'python'], support: python() },
+    { name: 'GraphQL', alias: ['graphql', 'gql'], support: graphql() }
+  ],
+  autoLoadLanguageSupport: false
+})
+```
+
 ## Configuring the Sandpack editor
 
 Compared to the code mirror editor, the Sandpack one is a bit more complex, as Sandpack needs to know the context of the code block in order to execute it correctly. Before diving in, it's good to [understand Sandpack configuration](https://sandpack.codesandbox.io/) itself. MDXEditor supports multiple Sandpack configurations, based on the meta data of the code block. To configure the supported presets, pass a `sandpackConfig` option in the plugin initialization. For more details, refer to the [SandpackConfig interface](../api/editor.sandpackconfig) and the [SandpackPreset interface](../api/editor.sandpackpreset).

src/examples/codemirror-languages.tsx

@@ -1,22 +1,63 @@
 import React from 'react'
-import { MDXEditor, codeBlockPlugin, codeMirrorPlugin, diffSourcePlugin, toolbarPlugin, DiffSourceToggleWrapper, UndoRedo } from '../'
+import { MDXEditor, codeBlockPlugin, codeMirrorPlugin } from '../'
 import { languages } from '@codemirror/language-data'
+import { python } from '@codemirror/lang-python'
+import { EditorView, keymap } from '@codemirror/view'
+import { toggleLineComment } from '@codemirror/commands'
+
+const simpleSampleMarkdown = `
+With \`js\` language:
+
+\`\`\`js
+const x = 1
+\`\`\`
+
+With \`ts\` language:
+
+\`\`\`ts
+const z: number = 3
+\`\`\`
+`
+
+const aliasSampleMarkdown = `
+With \`js\` language:
 
-const sampleMarkdown = `
 \`\`\`js
 const x = 1
 \`\`\`
 
+With \`javascript\` (alias) language:
+
 \`\`\`javascript
 const y = 2
 \`\`\`
 
+With \`ts\` language:
+
 \`\`\`ts
 const z: number = 3
 \`\`\`
 
-\`\`\`css
-body { color: red; }
+With \`typescript\` (alias) language:
+
+\`\`\`typescript
+const z: number = 3
+\`\`\`
+`
+
+const supportSampleMarkdown = `
+JS is **not** loaded:
+
+\`\`\`js
+const x = 1
+\`\`\`
+
+Python support is loaded:
+
+\`\`\`python
+def greet(name):
+    message = f"Hello, {name}!"
+    print(message)
 \`\`\`
 `
 
@@ -28,19 +69,11 @@ export function CodeMirrorLanguageData() {
   return (
     <MDXEditor
       onChange={console.log}
-      markdown={sampleMarkdown}
+      markdown={aliasSampleMarkdown}
       plugins={[
         codeBlockPlugin(),
         codeMirrorPlugin({
           codeBlockLanguages: languages
-        }),
-        diffSourcePlugin(),
-        toolbarPlugin({
-          toolbarContents: () => (
-            <DiffSourceToggleWrapper>
-              <UndoRedo />
-            </DiffSourceToggleWrapper>
-          )
         })
       ]}
     />
@@ -55,23 +88,66 @@ export function CodeMirrorLanguageArray() {
   return (
     <MDXEditor
       onChange={console.log}
-      markdown={sampleMarkdown}
+      markdown={aliasSampleMarkdown}
+      plugins={[
+        codeBlockPlugin(),
+        codeMirrorPlugin({
+          codeBlockLanguages: [
+            { name: 'JavaScript', alias: ['js', 'javascript'] },
+            { name: 'TypeScript', alias: ['ts', 'typescript'] }
+          ]
+        })
+      ]}
+    />
+  )
+}
+
+/**
+ * Uses `CodeBlockLanguage[]` with pre-loaded `support` for Python.
+ * JavaScript and CSS have no `support` and are auto-loaded as usual.
+ */
+export function CodeMirrorLanguageWithSupport() {
+  return (
+    <MDXEditor
+      onChange={console.log}
+      markdown={supportSampleMarkdown}
       plugins={[
         codeBlockPlugin(),
         codeMirrorPlugin({
           codeBlockLanguages: [
             { name: 'JavaScript', alias: ['js', 'javascript'] },
-            { name: 'TypeScript', alias: ['ts', 'typescript'], extensions: ['ts', 'mts'] },
-            { name: 'CSS', alias: ['css'] }
+            { name: 'Python', alias: ['py', 'python'], support: python() }
+          ],
+          // Disable auto-load to test support load is working well
+          autoLoadLanguageSupport: false
+        })
+      ]}
+    />
+  )
+}
+
+/**
+ * Passes custom CodeMirror extensions to all code block editors.
+ * Here we add a custom tab size and a custom theme via EditorView.theme.
+ */
+export function CodeMirrorExtensions() {
+  return (
+    <MDXEditor
+      onChange={console.log}
+      markdown={simpleSampleMarkdown}
+      plugins={[
+        codeBlockPlugin(),
+        codeMirrorPlugin({
+          codeBlockLanguages: { js: 'JavaScript', ts: 'TypeScript' },
+          codeMirrorExtensions: [
+            keymap.of([{ key: 'Cmd-:', run: toggleLineComment }]),
+            EditorView.theme({
+              '&': { backgroundColor: '#f5f5f5' },
+              '.cm-content': { fontFamily: '"Fira Code", monospace' },
+              '.cm-gutters': { backgroundColor: 'orange !important' },
+              '.cm-activeLineGutter': { backgroundColor: 'yellow !important' }
+            })
           ]
-        }),
-        diffSourcePlugin(),
-        toolbarPlugin({
-          toolbarContents: () => (
-            <DiffSourceToggleWrapper>
-              <UndoRedo />
-            </DiffSourceToggleWrapper>
-          )
         })
       ]}
     />
@@ -85,11 +161,11 @@ export function CodeMirrorLanguageRecord() {
   return (
     <MDXEditor
       onChange={console.log}
-      markdown={sampleMarkdown}
+      markdown={aliasSampleMarkdown}
       plugins={[
         codeBlockPlugin(),
         codeMirrorPlugin({
-          codeBlockLanguages: { jsx: 'JavaScript (React)', js: 'JavaScript', javascript: 'JavaScript', css: 'CSS' }
+          codeBlockLanguages: { js: 'JavaScript', javascript: 'JavaScript', ts: 'TypeScript', typescript: 'TypeScript' }
         })
       ]}
     />

src/plugins/codemirror/CodeMirrorEditor.tsx

@@ -64,16 +64,22 @@ export const CodeMirrorEditor = ({ language, nodeKey, code, focusEmitter }: Code
       if (readOnly) {
         extensions.push(EditorState.readOnly.of(true))
       }
-      if (language !== '' && autoLoadLanguageSupport) {
-        const languageData = languages.find((l) => {
-          return l.name === language || l.alias.includes(language) || l.extensions.includes(language)
-        })
-        if (languageData) {
-          try {
-            const languageSupport = await languageData.load()
-            extensions.push(languageSupport.extension)
-          } catch (_e) {
-            console.warn('failed to load language support for', language)
+      if (language !== '') {
+        const canonical = codeBlockLanguages.keyMap[language] ?? language
+        const providedSupport = codeBlockLanguages.supportMap[canonical]
+        if (providedSupport) {
+          extensions.push(providedSupport.extension)
+        } else if (autoLoadLanguageSupport) {
+          const languageData = languages.find((l) => {
+            return l.name === language || l.alias.includes(language) || l.extensions.includes(language)
+          })
+          if (languageData) {
+            try {
+              const languageSupport = await languageData.load()
+              extensions.push(languageSupport.extension)
+            } catch (_e) {
+              console.warn('failed to load language support for', language)
+            }
           }
         }
       }

src/plugins/codemirror/index.tsx

@@ -3,6 +3,7 @@ import { Cell, Signal, map } from '@mdxeditor/gurx'
 import { CodeBlockEditorDescriptor, appendCodeBlockEditorDescriptor$, insertCodeBlock$ } from '../codeblock'
 import { CodeMirrorEditor } from './CodeMirrorEditor'
 import { Extension } from '@codemirror/state'
+import { LanguageSupport } from '@codemirror/language'
 
 /**
  * @internal
@@ -21,6 +22,8 @@ export interface CodeBlockLanguage {
   alias?: readonly string[]
   /** File extensions associated with this language (e.g. `["js", "mjs"]`). */
   extensions?: readonly string[]
+  /** Pre-loaded language support. When provided, this is used directly instead of auto-loading. */
+  support?: LanguageSupport
 }
 
 /**
@@ -32,6 +35,8 @@ export interface NormalizedCodeBlockLanguages {
   items: { value: string; label: string }[]
   /** Maps any known key (canonical, alias, extension) to the canonical key. */
   keyMap: Record<string, string>
+  /** Maps canonical keys to pre-loaded language support, when provided. */
+  supportMap: Record<string, LanguageSupport>
 }
 
 /**
@@ -41,6 +46,7 @@ export interface NormalizedCodeBlockLanguages {
 export function normalizeCodeBlockLanguages(input: Record<string, string> | CodeBlockLanguage[]): NormalizedCodeBlockLanguages {
   const items: { value: string; label: string }[] = []
   const keyMap: Record<string, string> = {}
+  const supportMap: Record<string, LanguageSupport> = {}
 
   if (Array.isArray(input)) {
     for (const lang of input) {
@@ -60,6 +66,9 @@ export function normalizeCodeBlockLanguages(input: Record<string, string> | Code
       }
       // Also map the lowercased name
       keyMap[lang.name.toLowerCase()] = canonical
+      if (lang.support) {
+        supportMap[canonical] = lang.support
+      }
     }
   } else {
     const firstKeyByLabel: Record<string, string> = {}
@@ -72,7 +81,7 @@ export function normalizeCodeBlockLanguages(input: Record<string, string> | Code
     }
   }
 
-  return { items, keyMap }
+  return { items, keyMap, supportMap }
 }
 
 /**

src/test/codemirror.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it } from 'vitest'
 import { normalizeCodeBlockLanguages, EMPTY_VALUE } from '../plugins/codemirror'
+import { LanguageSupport } from '@codemirror/language'
 
 describe('normalizeCodeBlockLanguages', () => {
   describe('record format', () => {
@@ -70,6 +71,36 @@ describe('normalizeCodeBlockLanguages', () => {
     })
   })
 
+  describe('supportMap', () => {
+    it('stores support keyed by canonical key', () => {
+      const mockSupport = {} as LanguageSupport
+      const result = normalizeCodeBlockLanguages([
+        { name: 'JavaScript', alias: ['js', 'javascript'], support: mockSupport }
+      ])
+      expect(result.supportMap.js).toBe(mockSupport)
+    })
+
+    it('does not add entry when support is not provided', () => {
+      const result = normalizeCodeBlockLanguages([
+        { name: 'JavaScript', alias: ['js'] }
+      ])
+      expect(result.supportMap).toEqual({})
+    })
+
+    it('stores support using lowercased name when no aliases', () => {
+      const mockSupport = {} as LanguageSupport
+      const result = normalizeCodeBlockLanguages([
+        { name: 'Python', support: mockSupport }
+      ])
+      expect(result.supportMap.python).toBe(mockSupport)
+    })
+
+    it('is empty for record format', () => {
+      const result = normalizeCodeBlockLanguages({ js: 'JavaScript' })
+      expect(result.supportMap).toEqual({})
+    })
+  })
+
   describe('empty input', () => {
     it('handles empty record', () => {
       const result = normalizeCodeBlockLanguages({})