@bendyline/squisq-editor-react 2.0.1 → 2.1.0

package/src/codeSnippet/CodeSnippetExtension.ts

@@ -0,0 +1,205 @@
+/**
+ * Tiptap extension for ordinary explicit-language code fences.
+ *
+ * The ProseMirror code block remains authoritative. This plugin hides it and
+ * mounts a Monaco editor whose edits rewrite only the node's text content, so
+ * fence language and source round-trip through Markdown without a parallel model.
+ */
+
+import { Extension } from '@tiptap/core';
+import type { Node as PMNode } from '@tiptap/pm/model';
+import { Plugin, PluginKey, type Transaction } from '@tiptap/pm/state';
+import { Decoration, DecorationSet } from '@tiptap/pm/view';
+import type { Editor } from '@tiptap/react';
+import { createElement } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { CodeSnippetWidget } from './CodeSnippetWidget';
+import { isCodeSnippetFenceLanguage } from './codeSnippetLanguages';
+
+export interface CodeSnippetBlockEntry {
+  /** Synthetic session id, stable while this code block remains in the doc. */
+  id: string;
+  /** Current ProseMirror position of the `codeBlock`. */
+  pos: number;
+}
+
+export interface CodeSnippetPluginState {
+  entries: CodeSnippetBlockEntry[];
+  decorations: DecorationSet;
+  seq: number;
+}
+
+export interface CodeSnippetExtensionOptions {
+  /** When false, leave all ordinary language-tagged fences as code blocks. */
+  enabled?: boolean;
+}
+
+export const CODE_SNIPPET_KEY = new PluginKey<CodeSnippetPluginState>('squisq-code-snippet');
+
+export function isCodeSnippetNode(node: PMNode): boolean {
+  const language = (node.attrs as { language?: unknown }).language;
+  return (
+    node.type.name === 'codeBlock' &&
+    isCodeSnippetFenceLanguage(typeof language === 'string' ? language : null)
+  );
+}
+
+export function findCodeSnippetBlockPos(editor: Editor, blockId: string): number | null {
+  const state = CODE_SNIPPET_KEY.getState(editor.state);
+  return state?.entries.find((entry) => entry.id === blockId)?.pos ?? null;
+}
+
+interface WidgetRootRef {
+  root: Root;
+}
+
+function buildDecorations(
+  doc: PMNode,
+  entries: readonly CodeSnippetBlockEntry[],
+  editor: Editor,
+): DecorationSet {
+  const decorations: Decoration[] = [];
+  for (const entry of entries) {
+    const node = doc.nodeAt(entry.pos);
+    if (!node || !isCodeSnippetNode(node)) continue;
+    decorations.push(
+      Decoration.node(entry.pos, entry.pos + node.nodeSize, {
+        class: 'squisq-code-snippet-fence-hidden',
+      }),
+    );
+    const blockId = entry.id;
+    decorations.push(
+      Decoration.widget(
+        entry.pos + node.nodeSize,
+        (view) => {
+          const container = document.createElement('div');
+          container.className = 'squisq-code-snippet-widget-host';
+          container.contentEditable = 'false';
+          container.addEventListener('mousedown', (event) => event.stopPropagation());
+          container.addEventListener('keydown', (event) => event.stopPropagation());
+          const root = createRoot(container);
+          root.render(
+            createElement(CodeSnippetWidget, {
+              editor,
+              blockId,
+              host: view.dom.parentElement ?? view.dom,
+            }),
+          );
+          (
+            container as HTMLElement & { __squisqCodeSnippetRoot?: WidgetRootRef }
+          ).__squisqCodeSnippetRoot = { root };
+          return container;
+        },
+        {
+          destroy: (dom) => {
+            const ref = (dom as HTMLElement & { __squisqCodeSnippetRoot?: WidgetRootRef })
+              .__squisqCodeSnippetRoot;
+            if (ref) setTimeout(() => ref.root.unmount(), 0);
+          },
+          ignoreSelection: true,
+          key: `squisq-code-snippet-${entry.id}`,
+          side: 1,
+        },
+      ),
+    );
+  }
+  return DecorationSet.create(doc, decorations);
+}
+
+function remapEntries(
+  tr: Transaction,
+  previous: CodeSnippetPluginState,
+  doc: PMNode,
+): { entries: CodeSnippetBlockEntry[]; seq: number } {
+  const mapped = new Map<number, string>();
+  const claimed = new Set<string>();
+
+  for (const entry of previous.entries) {
+    const result = tr.mapping.mapResult(entry.pos, 1);
+    if (!result.deleted) {
+      mapped.set(result.pos, entry.id);
+      claimed.add(entry.id);
+    }
+  }
+
+  // Replacing node content can mark its opening token as replaced even though
+  // the same language-tagged code block still occupies the mapped position.
+  for (const entry of previous.entries) {
+    if (claimed.has(entry.id)) continue;
+    const result = tr.mapping.mapResult(entry.pos, 1);
+    if (mapped.has(result.pos)) continue;
+    if (doc.nodeAt(result.pos)?.type.name === 'codeBlock') {
+      mapped.set(result.pos, entry.id);
+      claimed.add(entry.id);
+    }
+  }
+
+  let seq = previous.seq;
+  const entries: CodeSnippetBlockEntry[] = [];
+  doc.descendants((node, pos) => {
+    if (node.type.name !== 'codeBlock') return;
+    if (!isCodeSnippetNode(node)) return false;
+    entries.push({ id: mapped.get(pos) ?? `code-snippet-${++seq}`, pos });
+    return false;
+  });
+  return { entries, seq };
+}
+
+function applyState(
+  tr: Transaction,
+  previous: CodeSnippetPluginState,
+  editor: Editor,
+  doc: PMNode,
+): CodeSnippetPluginState {
+  if (!tr.docChanged) return previous;
+  const { entries, seq } = remapEntries(tr, previous, doc);
+  return {
+    entries,
+    seq,
+    decorations: buildDecorations(doc, entries, editor),
+  };
+}
+
+export const CodeSnippetExtension = Extension.create<CodeSnippetExtensionOptions>({
+  name: 'squisqCodeSnippet',
+
+  addOptions() {
+    return { enabled: true };
+  },
+
+  addProseMirrorPlugins() {
+    if (this.options.enabled === false) return [];
+    const editor = this.editor as Editor;
+    return [
+      new Plugin<CodeSnippetPluginState>({
+        key: CODE_SNIPPET_KEY,
+        state: {
+          init: (_config, state) => {
+            let seq = 0;
+            const entries: CodeSnippetBlockEntry[] = [];
+            state.doc.descendants((node, pos) => {
+              if (node.type.name !== 'codeBlock') return;
+              if (!isCodeSnippetNode(node)) return false;
+              entries.push({ id: `code-snippet-${++seq}`, pos });
+              return false;
+            });
+            return {
+              entries,
+              seq,
+              decorations: buildDecorations(state.doc, entries, editor),
+            };
+          },
+          apply: (tr, previous, _oldState, newState) =>
+            applyState(tr, previous, editor, newState.doc),
+        },
+        props: {
+          decorations(state) {
+            return this.getState(state)?.decorations ?? DecorationSet.empty;
+          },
+        },
+      }),
+    ];
+  },
+});
+
+export default CodeSnippetExtension;

package/src/codeSnippet/CodeSnippetWidget.tsx

@@ -0,0 +1,109 @@
+/** Monaco inset mounted in place of an ordinary language-tagged code fence. */
+
+import { useCallback, useEffect, useState } from 'react';
+import MonacoEditor, { type OnChange } from '@monaco-editor/react';
+import type { Editor } from '@tiptap/react';
+import { Icon } from '../Icon';
+import { useMonacoLoader } from '../useMonacoLoader';
+import { replaceCodeSnippetText } from './codeSnippetCommands';
+import { useCodeSnippetData } from './codeSnippetData';
+import { codeSnippetFenceLanguageToken } from './codeSnippetLanguages';
+
+export interface CodeSnippetWidgetProps {
+  editor: Editor;
+  blockId: string;
+  host?: HTMLElement | null;
+}
+
+function schemeFromHost(host: HTMLElement | null | undefined): 'light' | 'dark' {
+  return host?.closest<HTMLElement>('[data-theme]')?.dataset.theme === 'dark' ? 'dark' : 'light';
+}
+
+function useHostColorScheme(host: HTMLElement | null | undefined): 'light' | 'dark' {
+  const [scheme, setScheme] = useState<'light' | 'dark'>(() => schemeFromHost(host));
+  useEffect(() => {
+    const themedAncestor = host?.closest<HTMLElement>('[data-theme]');
+    setScheme(schemeFromHost(host));
+    if (!themedAncestor || typeof MutationObserver === 'undefined') return;
+    const observer = new MutationObserver(() => setScheme(schemeFromHost(host)));
+    observer.observe(themedAncestor, { attributes: true, attributeFilter: ['data-theme'] });
+    return () => observer.disconnect();
+  }, [host]);
+  return scheme;
+}
+
+function useEditorEditable(editor: Editor): boolean {
+  const [editable, setEditable] = useState(editor.isEditable);
+  useEffect(() => {
+    const sync = () => setEditable(editor.isEditable);
+    editor.on('update', sync);
+    editor.on('transaction', sync);
+    return () => {
+      editor.off('update', sync);
+      editor.off('transaction', sync);
+    };
+  }, [editor]);
+  return editable;
+}
+
+export function CodeSnippetWidget({ editor, blockId, host }: CodeSnippetWidgetProps) {
+  const data = useCodeSnippetData(editor, blockId);
+  const { ready } = useMonacoLoader();
+  const colorScheme = useHostColorScheme(host);
+  const editable = useEditorEditable(editor);
+
+  const handleChange: OnChange = useCallback(
+    (value) => {
+      if (!editable) return;
+      replaceCodeSnippetText(editor, blockId, value ?? '');
+    },
+    [blockId, editable, editor],
+  );
+
+  if (!data) return null;
+  const modelSuffix = codeSnippetFenceLanguageToken(data.fenceLanguage).replace(
+    /[^a-z0-9_-]/g,
+    '-',
+  );
+
+  return (
+    <div className="squisq-code-snippet-shell" data-language={data.fenceLanguage}>
+      <div className="squisq-code-snippet-header">
+        <span className="squisq-code-snippet-title">
+          <Icon icon="fa-solid fa-file-code" />
+          <span>{data.label}</span>
+        </span>
+        <code>{`\`\`\`${data.fenceLanguage}`}</code>
+      </div>
+      <div className="squisq-code-snippet-editor" aria-label={`${data.label} code editor`}>
+        {ready ? (
+          <MonacoEditor
+            path={`inmemory://squisq/code-snippet/${blockId}.${modelSuffix || 'txt'}`}
+            language={data.monacoLanguage}
+            theme={colorScheme === 'dark' ? 'vs-dark' : 'vs'}
+            value={data.source}
+            onChange={handleChange}
+            options={{
+              automaticLayout: true,
+              contextmenu: true,
+              folding: true,
+              fontSize: 13,
+              lineNumbers: 'on',
+              minimap: { enabled: false },
+              padding: { top: 10, bottom: 10 },
+              readOnly: !editable,
+              renderLineHighlight: 'line',
+              scrollBeyondLastLine: false,
+              tabSize: 2,
+              wordWrap: 'off',
+            }}
+          />
+        ) : (
+          <div className="squisq-code-snippet-loading">Loading code editor…</div>
+        )}
+      </div>
+    </div>
+  );
+}
+
+export default CodeSnippetWidget;

package/src/codeSnippet/__tests__/CodeSnippetExtension.test.ts

@@ -0,0 +1,95 @@
+/** @vitest-environment jsdom */
+
+import { Editor } from '@tiptap/core';
+import StarterKit from '@tiptap/starter-kit';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { markdownToTiptap, tiptapToMarkdown } from '../../tiptapBridge';
+import { replaceCodeSnippetText } from '../codeSnippetCommands';
+import {
+  CODE_SNIPPET_KEY,
+  CodeSnippetExtension,
+  findCodeSnippetBlockPos,
+} from '../CodeSnippetExtension';
+
+vi.mock('../CodeSnippetWidget', () => ({
+  CodeSnippetWidget: () => null,
+}));
+
+const editors: Editor[] = [];
+
+function makeEditor(markdown: string, enabled = true): Editor {
+  const editor = new Editor({
+    extensions: [StarterKit, CodeSnippetExtension.configure({ enabled })],
+    content: markdownToTiptap(markdown),
+  });
+  editors.push(editor);
+  return editor;
+}
+
+function entriesOf(editor: Editor) {
+  return CODE_SNIPPET_KEY.getState(editor.state)?.entries ?? [];
+}
+
+afterEach(() => {
+  for (const editor of editors) editor.destroy();
+  editors.length = 0;
+});
+
+describe('CodeSnippetExtension', () => {
+  it('claims all explicit ordinary code languages, including unknown ones', () => {
+    const editor = makeEditor(
+      '```typescript\nconst n = 1;\n```\n\n```kusto\nTable | take 5\n```\n',
+    );
+    expect(entriesOf(editor)).toHaveLength(2);
+  });
+
+  it('does not steal plain, Mermaid, diagram, tree, or timeline fences', () => {
+    const editor = makeEditor(
+      [
+        '```text\nplain\n```',
+        '```mermaid\nflowchart LR\n  a --> b\n```',
+        '```diagram\n+---+\n| A |\n+---+\n```',
+        '```tree\nsrc/\n└── index.ts\n```',
+        '```timeline\nMilestones: ● Start ─►\n```',
+        '```\nuntagged\n```',
+        '',
+      ].join('\n\n'),
+    );
+    expect(entriesOf(editor)).toHaveLength(0);
+  });
+
+  it('keeps a stable block id and rewrites only the fence body', () => {
+    const editor = makeEditor('```typescript\nconst before = true;\n```\n');
+    const [before] = entriesOf(editor);
+    editor.commands.insertContentAt(0, '<p>Intro</p>');
+    const [shifted] = entriesOf(editor);
+    expect(shifted.id).toBe(before.id);
+    expect(shifted.pos).toBeGreaterThan(before.pos);
+    expect(findCodeSnippetBlockPos(editor, before.id)).toBe(shifted.pos);
+
+    expect(replaceCodeSnippetText(editor, before.id, 'const after: number = 2;')).toBe(true);
+    expect(tiptapToMarkdown(editor.getHTML())).toContain(
+      '```typescript\nconst after: number = 2;\n```',
+    );
+  });
+
+  it('supports clearing the Monaco model without losing the fence language', () => {
+    const editor = makeEditor('```json\n{"key": true}\n```\n');
+    const [entry] = entriesOf(editor);
+    expect(replaceCodeSnippetText(editor, entry.id, '')).toBe(true);
+    const node = editor.state.doc.nodeAt(findCodeSnippetBlockPos(editor, entry.id) ?? -1);
+    expect(node?.textContent).toBe('');
+    expect(node?.attrs.language).toBe('json');
+  });
+
+  it('round-trips the language tag and source byte-for-byte', () => {
+    const markdown = '```typescript\nconst n: number = 1;\n```\n';
+    const editor = makeEditor(markdown);
+    expect(tiptapToMarkdown(editor.getHTML())).toBe(markdown);
+  });
+
+  it('can be disabled', () => {
+    const editor = makeEditor('```typescript\nconst n = 1;\n```\n', false);
+    expect(CODE_SNIPPET_KEY.getState(editor.state)).toBeUndefined();
+  });
+});

package/src/codeSnippet/__tests__/codeSnippetLanguages.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from 'vitest';
+import {
+  CODE_SNIPPET_LANGUAGES,
+  codeSnippetFenceLanguageToken,
+  codeSnippetLanguageLabel,
+  codeSnippetMarkdown,
+  isCodeSnippetFenceLanguage,
+  monacoLanguageForFence,
+} from '../codeSnippetLanguages';
+
+describe('code snippet languages', () => {
+  it('offers unique explicit fence languages', () => {
+    const languages = CODE_SNIPPET_LANGUAGES.map((entry) => entry.fenceLanguage);
+    expect(new Set(languages).size).toBe(languages.length);
+    expect(languages).toContain('typescript');
+    expect(languages).toContain('json');
+    expect(languages).toContain('python');
+  });
+
+  it('keeps specialized authored-view languages out of the Monaco inset', () => {
+    for (const language of [
+      '',
+      'text',
+      'txt',
+      'plaintext',
+      'ascii',
+      'diagram',
+      'tree',
+      'timeline',
+      'mermaid',
+    ]) {
+      expect(isCodeSnippetFenceLanguage(language), language).toBe(false);
+    }
+    expect(isCodeSnippetFenceLanguage('typescript')).toBe(true);
+    expect(isCodeSnippetFenceLanguage('kusto')).toBe(true);
+  });
+
+  it('uses the first fence token for Monaco while preserving metadata for round trips', () => {
+    expect(codeSnippetFenceLanguageToken('  json data  ')).toBe('json');
+    expect(monacoLanguageForFence('ts highlight-lines')).toBe('typescript');
+    expect(monacoLanguageForFence('yml')).toBe('yaml');
+    expect(codeSnippetLanguageLabel('csharp')).toBe('C#');
+  });
+
+  it('creates an explicit language-tagged Markdown fence', () => {
+    expect(codeSnippetMarkdown('typescript', 'const n: number = 1;')).toBe(
+      '\n```typescript\nconst n: number = 1;\n```\n',
+    );
+  });
+});

package/src/codeSnippet/codeSnippetCommands.ts

@@ -0,0 +1,21 @@
+/** Lossless edits for language-tagged code fences. */
+
+import type { Editor } from '@tiptap/react';
+import { findCodeSnippetBlockPos, isCodeSnippetNode } from './CodeSnippetExtension';
+
+export function replaceCodeSnippetText(editor: Editor, blockId: string, nextText: string): boolean {
+  const pos = findCodeSnippetBlockPos(editor, blockId);
+  if (pos === null) return false;
+  const node = editor.state.doc.nodeAt(pos);
+  if (!node || !isCodeSnippetNode(node)) return false;
+  if (node.textContent === nextText) return true;
+
+  const from = pos + 1;
+  const to = pos + node.nodeSize - 1;
+  const tr =
+    nextText.length > 0
+      ? editor.state.tr.replaceWith(from, to, editor.state.schema.text(nextText))
+      : editor.state.tr.delete(from, to);
+  editor.view.dispatch(tr);
+  return true;
+}

package/src/codeSnippet/codeSnippetData.ts

@@ -0,0 +1,43 @@
+/** Live source/language view for one registered code snippet fence. */
+
+import { useEffect, useMemo, useState } from 'react';
+import type { Editor } from '@tiptap/react';
+import { findCodeSnippetBlockPos, isCodeSnippetNode } from './CodeSnippetExtension';
+import { codeSnippetLanguageLabel, monacoLanguageForFence } from './codeSnippetLanguages';
+
+export interface CodeSnippetData {
+  /** Fence language exactly as stored in the ProseMirror node. */
+  fenceLanguage: string;
+  label: string;
+  monacoLanguage: string;
+  /** Source exactly as stored inside the code block. */
+  source: string;
+}
+
+export function useCodeSnippetData(editor: Editor, blockId: string): CodeSnippetData | null {
+  const [version, setVersion] = useState(0);
+  useEffect(() => {
+    const onTransaction = () => setVersion((value) => value + 1);
+    editor.on('transaction', onTransaction);
+    return () => {
+      editor.off('transaction', onTransaction);
+    };
+  }, [editor]);
+
+  return useMemo(() => {
+    const pos = findCodeSnippetBlockPos(editor, blockId);
+    if (pos === null) return null;
+    const node = editor.state.doc.nodeAt(pos);
+    if (!node || !isCodeSnippetNode(node)) return null;
+    const rawLanguage = (node.attrs as { language?: unknown }).language;
+    const fenceLanguage = typeof rawLanguage === 'string' ? rawLanguage : '';
+    return {
+      fenceLanguage,
+      label: codeSnippetLanguageLabel(fenceLanguage),
+      monacoLanguage: monacoLanguageForFence(fenceLanguage),
+      source: node.textContent,
+    };
+    // `version` is the transaction-backed invalidation token.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [editor, blockId, version]);
+}