@jupyterlab/codemirror 4.0.0-alpha.9 → 4.0.0-beta.0

package/src/extensions/customStyle.ts

@@ -0,0 +1,79 @@
+/*
+ * Copyright (c) Jupyter Development Team.
+ * Distributed under the terms of the Modified BSD License.
+ */
+
+import { combineConfig, Extension, Facet } from '@codemirror/state';
+import { EditorView } from '@codemirror/view';
+
+/**
+ * Editor customizable styles
+ */
+export type CustomTheme = {
+  /**
+   * Font family
+   */
+  fontFamily: string | null;
+  /**
+   * Font size
+   */
+  fontSize: number | null;
+  /**
+   * Line height
+   */
+  lineHeight: number | null;
+};
+
+/**
+ * Custom theme configuration
+ *
+ * The first non-null value takes precedence
+ */
+const customThemeConfig = Facet.define<CustomTheme, CustomTheme>({
+  combine(configs: CustomTheme[]) {
+    return combineConfig(
+      configs,
+      {
+        fontFamily: null,
+        fontSize: null,
+        lineHeight: null
+      },
+      {
+        fontFamily: (a, b) => a ?? b,
+        fontSize: (a, b) => a ?? b,
+        lineHeight: (a, b) => a ?? b
+      }
+    );
+  }
+});
+
+function setEditorStyle(view: EditorView): Record<string, string> | null {
+  const { fontFamily, fontSize, lineHeight } =
+    view.state.facet(customThemeConfig);
+
+  let style = '';
+  if (fontSize) {
+    style += `font-size: ${fontSize}px !important;`;
+  }
+  if (fontFamily) {
+    style += `font-family: ${fontFamily} !important;`;
+  }
+  if (lineHeight) {
+    style += `line-height: ${lineHeight.toString()} !important`;
+  }
+
+  return { style: style };
+}
+
+/**
+ * Get the extension to customize an editor theme.
+ *
+ * @param config Theme customization
+ * @returns Editor extension
+ */
+export function customTheme(config: CustomTheme): Extension {
+  return [
+    customThemeConfig.of(config),
+    EditorView.editorAttributes.of(setEditorStyle)
+  ];
+}

package/src/extensions/index.ts

@@ -0,0 +1,8 @@
+/*
+ * Copyright (c) Jupyter Development Team.
+ * Distributed under the terms of the Modified BSD License.
+ */
+
+export * from './customStyle';
+export * from './rulers';
+export * from './ybinding';

package/src/extensions/rulers.ts

@@ -0,0 +1,112 @@
+/*
+ * Copyright (c) Jupyter Development Team.
+ * Distributed under the terms of the Modified BSD License.
+ */
+
+// Inspired by https://discuss.codemirror.net/t/how-to-implement-ruler/4616/
+
+import { Extension, Facet } from '@codemirror/state';
+import { EditorView, ViewPlugin, ViewUpdate } from '@codemirror/view';
+import { JSONExt } from '@lumino/coreutils';
+
+const RULERS_CLASSNAME = 'cm-rulers';
+
+/**
+ * Rulers style
+ */
+const baseTheme = EditorView.baseTheme({
+  [`.${RULERS_CLASSNAME}`]: { borderRight: '1px dotted gray', opacity: 0.7 }
+});
+
+/**
+ * Rulers facet
+ */
+const rulerConfig = Facet.define<number[], number[]>({
+  // Merge all unique values
+  combine(value) {
+    const final = value.reduce(
+      (agg, arr) =>
+        agg.concat(
+          // Check value is not in aggregate nor multiple time in the array.
+          arr.filter((v, idx) => !agg.includes(v) && idx == arr.lastIndexOf(v))
+        ),
+      []
+    );
+    return final;
+  }
+});
+
+/**
+ * View plugin displaying the rulers
+ */
+const plugin = ViewPlugin.fromClass(
+  class {
+    constructor(view: EditorView) {
+      this.rulersContainer = view.dom.appendChild(
+        document.createElement('div')
+      );
+      this.rulersContainer.style.cssText = `
+                position: absolute;
+                left: 0;
+                top: 0;
+                width: 100%;
+                height: 100%;
+                pointer-events: none;
+                overflow: hidden;
+            `;
+
+      const defaultCharacterWidth = view.defaultCharacterWidth;
+      const widths = view.state.facet(rulerConfig);
+      this.rulers = widths.map(width => {
+        const ruler = this.rulersContainer.appendChild(
+          document.createElement('div')
+        );
+        ruler.classList.add(RULERS_CLASSNAME);
+        ruler.style.cssText = `
+                position: absolute;
+                left: ${width * defaultCharacterWidth}px;
+                height: 100%;
+            `;
+        // FIXME: This should be equal to the amount of padding on a line.
+        // This value should be extracted from CodeMirror rather than hardcoded.
+        ruler.style.width = '6px';
+
+        return ruler;
+      });
+    }
+
+    update(update: ViewUpdate) {
+      const widths = update.view.state.facet(rulerConfig);
+
+      if (
+        update.viewportChanged ||
+        !JSONExt.deepEqual(widths, update.startState.facet(rulerConfig))
+      ) {
+        const defaultCharacterWidth = update.view.defaultCharacterWidth;
+        this.rulers.forEach((ruler, rulerIdx) => {
+          ruler.style.left = `${widths[rulerIdx] * defaultCharacterWidth}px`;
+        });
+      }
+    }
+
+    destroy() {
+      this.rulers.forEach(ruler => {
+        ruler.remove();
+      });
+      this.rulersContainer.remove();
+    }
+
+    rulersContainer: HTMLDivElement;
+    rulers: HTMLDivElement[];
+  }
+);
+
+/**
+ * Extension for CodeMirror 6 displaying rulers.
+ *
+ * @param value Rulers position
+ * @returns CodeMirror 6 extension
+ */
+export function rulers(value: number[]): Extension {
+  return [baseTheme, rulerConfig.of(value), plugin];
+}

package/src/extensions/ybinding.ts

@@ -0,0 +1,295 @@
+/*
+ * Copyright (c) Jupyter Development Team.
+ * Distributed under the terms of the Modified BSD License.
+ *
+ * Binding for yjs and codemirror
+ *
+ * It is a simplification of https://github.com/yjs/y-codemirror.next
+ * licensed under MIT License by Kevin Jahns
+ */
+import {
+  Annotation,
+  EditorSelection,
+  Extension,
+  Facet,
+  SelectionRange
+} from '@codemirror/state';
+import { EditorView, ViewPlugin, ViewUpdate } from '@codemirror/view';
+import type {
+  RelativePosition,
+  Text,
+  Transaction,
+  UndoManager,
+  YTextEvent
+} from 'yjs';
+import {
+  createAbsolutePositionFromRelativePosition,
+  createRelativePositionFromJSON,
+  createRelativePositionFromTypeIndex,
+  relativePositionToJSON
+} from 'yjs';
+
+export type ID = {
+  client: number;
+  clock: number;
+};
+
+export type Position = {
+  type: ID | null;
+  tname: string | null;
+  item: ID | null;
+  assoc: number;
+};
+
+export type Range = {
+  yanchor: Position;
+  yhead: Position;
+};
+
+/**
+ * Defines a range on text using relative positions that can be transformed back to
+ * absolute positions. (https://docs.yjs.dev/api/relative-positions)
+ */
+export class YRange {
+  /**
+   * @param yanchor
+   * @param yhead
+   */
+  constructor(
+    public yanchor: RelativePosition,
+    public yhead: RelativePosition
+  ) {}
+
+  /**
+   * Convert the position to JSON
+   */
+  toJSON(): Range {
+    return {
+      yanchor: relativePositionToJSON(this.yanchor),
+      yhead: relativePositionToJSON(this.yhead)
+    };
+  }
+
+  /**
+   * Convert a JSON range to a YRange
+   * @param json Range to convert
+   * @return The range as YRange
+   */
+  static fromJSON(json: Range): YRange {
+    return new YRange(
+      createRelativePositionFromJSON(json.yanchor),
+      createRelativePositionFromJSON(json.yhead)
+    );
+  }
+}
+
+/**
+ * Yjs binding configuration
+ */
+export class YSyncConfig {
+  /**
+   * Create a new binding configuration
+   *
+   * @param ytext Yjs text to synchronize
+   */
+  constructor(public ytext: Text) {}
+
+  /**
+   * Helper function to transform an absolute index position to a Yjs-based relative position
+   * (https://docs.yjs.dev/api/relative-positions).
+   *
+   * A relative position can be transformed back to an absolute position even after the document has changed. The position is
+   * automatically adapted. This does not require any position transformations. Relative positions are computed based on
+   * the internal Yjs document model. Peers that share content through Yjs are guaranteed that their positions will always
+   * synced up when using relative positions.
+   *
+   * ```js
+   * import { ySyncFacet } from 'y-codemirror'
+   *
+   * ..
+   * const ysync = view.state.facet(ySyncFacet)
+   * // transform an absolute index position to a ypos
+   * const ypos = ysync.getYPos(3)
+   * // transform the ypos back to an absolute position
+   * ysync.fromYPos(ypos) // => 3
+   * ```
+   *
+   * It cannot be guaranteed that absolute index positions can be synced up between peers.
+   * This might lead to undesired behavior when implementing features that require that all peers see the
+   * same marked range (e.g. a comment plugin).
+   *
+   * @param pos
+   * @param assoc
+   */
+  toYPos(pos: number, assoc = 0): RelativePosition {
+    return createRelativePositionFromTypeIndex(this.ytext, pos, assoc);
+  }
+
+  /**
+   * @param rpos
+   */
+  fromYPos(rpos: RelativePosition | Record<string, any>) {
+    const pos = createAbsolutePositionFromRelativePosition(
+      createRelativePositionFromJSON(rpos),
+      this.ytext.doc!
+    );
+    if (pos == null || pos.type !== this.ytext) {
+      throw new Error(
+        '[y-codemirror] The position you want to retrieve was created by a different document'
+      );
+    }
+    return {
+      pos: pos.index,
+      assoc: pos.assoc
+    };
+  }
+
+  /**
+   * @param range
+   * @return
+   */
+  toYRange(range: SelectionRange): YRange {
+    const assoc = range.assoc;
+    const yanchor = this.toYPos(range.anchor, assoc);
+    const yhead = this.toYPos(range.head, assoc);
+    return new YRange(yanchor, yhead);
+  }
+
+  /**
+   * @param yrange
+   */
+  fromYRange(yrange: YRange): SelectionRange {
+    const anchor = this.fromYPos(yrange.yanchor);
+    const head = this.fromYPos(yrange.yhead);
+    if (anchor.pos === head.pos) {
+      return EditorSelection.cursor(head.pos, head.assoc);
+    }
+    return EditorSelection.range(anchor.pos, head.pos);
+  }
+}
+
+/**
+ * Yjs binding facet
+ */
+export const ySyncFacet = Facet.define<YSyncConfig, YSyncConfig>({
+  combine(inputs) {
+    return inputs[inputs.length - 1];
+  }
+});
+
+/**
+ * Yjs binding annotation
+ *
+ * It is used to track the origin of the document changes
+ */
+export const ySyncAnnotation = Annotation.define<YSyncConfig>();
+
+/**
+ * Yjs binding view plugin to synchronize the
+ * editor state with the Yjs document.
+ */
+export const ySync = ViewPlugin.fromClass(
+  class {
+    constructor(view: EditorView) {
+      this.conf = view.state.facet(ySyncFacet);
+      this._observer = (event: YTextEvent, tr: Transaction) => {
+        if (tr.origin !== this.conf) {
+          const delta = event.delta;
+          const changes: any[] = [];
+          let pos = 0;
+          for (let i = 0; i < delta.length; i++) {
+            const d = delta[i];
+            if (d.insert != null) {
+              changes.push({ from: pos, to: pos, insert: d.insert });
+            } else if (d.delete != null) {
+              changes.push({ from: pos, to: pos + d.delete, insert: '' });
+              pos += d.delete;
+            } else {
+              pos += d.retain ?? 0;
+            }
+          }
+          view.dispatch({
+            changes,
+            // Specified the changes origin to not loop when synchronizing
+            annotations: [ySyncAnnotation.of(this.conf)]
+          });
+        }
+      };
+      this._ytext = this.conf.ytext;
+      this._ytext.observe(this._observer);
+    }
+
+    update(update: ViewUpdate) {
+      if (
+        !update.docChanged ||
+        (update.transactions.length > 0 &&
+          update.transactions[0].annotation(ySyncAnnotation) === this.conf)
+      ) {
+        return;
+      }
+
+      const ytext = this.conf.ytext;
+      ytext.doc!.transact(() => {
+        /**
+         * This variable adjusts the fromA position to the current position in the Y.Text type.
+         */
+        let adj = 0;
+        update.changes.iterChanges((fromA, toA, fromB, toB, insert) => {
+          const insertText = insert.sliceString(0, insert.length, '\n');
+          if (fromA !== toA) {
+            ytext.delete(fromA + adj, toA - fromA);
+          }
+          if (insertText.length > 0) {
+            ytext.insert(fromA + adj, insertText);
+          }
+          adj += insertText.length - (toA - fromA);
+        });
+        // Set the configuration as origin to not loop when synchronizing
+      }, this.conf);
+    }
+
+    destroy() {
+      this._ytext.unobserve(this._observer);
+    }
+
+    conf: YSyncConfig;
+    _observer: (event: YTextEvent, tr: Transaction) => void;
+    _ytext: Text;
+  }
+);
+
+/**
+ * Extension for CodeMirror 6 binding the Yjs text (source of truth)
+ * and the editor state.
+ *
+ * @param ytext Yjs text to bind
+ * @param undoManager Yjs text undo manager
+ * @returns CodeMirror 6 extension
+ */
+export function ybinding({
+  ytext,
+  undoManager
+}: {
+  ytext: Text;
+  undoManager?: UndoManager;
+}): Extension {
+  const ySyncConfig = new YSyncConfig(ytext);
+  // We don't need the undo manager extension as in y-codemirror.next
+  // because we deal with undo/redo with our own keyboard shortcut mechanism.
+  return [
+    ySyncFacet.of(ySyncConfig),
+    ySync,
+    // We need to add a new origin to the undo manager to ensure text updates
+    // are tracked.
+    undoManager
+      ? ViewPlugin.define(() => {
+          undoManager.addTrackedOrigin(ySyncConfig);
+          return {
+            destroy: () => {
+              undoManager.removeTrackedOrigin(ySyncConfig);
+            }
+          };
+        })
+      : []
+  ];
+}

package/src/factory.ts

@@ -0,0 +1,100 @@
+// Copyright (c) Jupyter Development Team.
+// Distributed under the terms of the Modified BSD License.
+
+import { CodeEditor, IEditorFactoryService } from '@jupyterlab/codeeditor';
+import { ITranslator, nullTranslator } from '@jupyterlab/translation';
+import { EditorExtensionRegistry } from './extension';
+import { CodeMirrorEditor } from './editor';
+import { EditorLanguageRegistry } from './language';
+import {
+  IEditorExtensionFactory,
+  IEditorExtensionRegistry,
+  IEditorFactoryOptions,
+  IEditorLanguageRegistry
+} from './token';
+import { EditorView, keymap } from '@codemirror/view';
+import { searchKeymap } from '@codemirror/search';
+
+/**
+ * CodeMirror editor factory.
+ */
+export class CodeMirrorEditorFactory implements IEditorFactoryService {
+  /**
+   * Construct an IEditorFactoryService for CodeMirrorEditors.
+   */
+  constructor(options: IEditorFactoryOptions = {}) {
+    this.languages = options.languages ?? new EditorLanguageRegistry();
+    this.extensions = options.extensions ?? new EditorExtensionRegistry();
+    this.translator = options.translator ?? nullTranslator;
+    this.inlineCodeMirrorConfig = {};
+    this.documentCodeMirrorConfig = {
+      lineNumbers: true,
+      scrollPastEnd: true
+    };
+  }
+
+  /**
+   * Create a new editor for inline code.
+   */
+  readonly newInlineEditor = (
+    options: CodeEditor.IOptions
+  ): CodeMirrorEditor => {
+    options.host.dataset.type = 'inline';
+    return this.newEditor({
+      ...options,
+      config: { ...this.inlineCodeMirrorConfig, ...(options.config || {}) },
+      inline: true,
+      // FIXME the search keymap should be added in the search plugin
+      extensions: [keymap.of(searchKeymap)].concat(options.extensions ?? [])
+    });
+  };
+
+  /**
+   * Create a new editor for a full document.
+   */
+  readonly newDocumentEditor = (
+    options: CodeEditor.IOptions
+  ): CodeMirrorEditor => {
+    options.host.dataset.type = 'document';
+    return this.newEditor({
+      ...options,
+      config: { ...this.documentCodeMirrorConfig, ...(options.config ?? {}) },
+      inline: false,
+      extensions: [
+        keymap.of([
+          {
+            key: 'Shift-Enter',
+            run: (target: EditorView) => {
+              return true;
+            }
+          }
+        ])
+      ].concat(options.extensions ?? [])
+    });
+  };
+
+  /**
+   * Create a new editor
+   *
+   * @param options Editor options
+   * @returns The editor
+   */
+  protected newEditor(
+    options: CodeEditor.IOptions & IEditorExtensionFactory.IOptions
+  ): CodeMirrorEditor {
+    const editor = new CodeMirrorEditor({
+      extensionsRegistry: this.extensions,
+      languages: this.languages,
+      translator: this.translator,
+      ...options
+    });
+
+    return editor;
+  }
+
+  protected extensions: IEditorExtensionRegistry;
+  protected languages: IEditorLanguageRegistry;
+  protected translator: ITranslator;
+  protected inlineCodeMirrorConfig: Record<string, any>;
+  protected documentCodeMirrorConfig: Record<string, any>;
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+// Copyright (c) Jupyter Development Team.
+// Distributed under the terms of the Modified BSD License.
+/**
+ * @packageDocumentation
+ * @module codemirror
+ */
+
+export * from './commands';
+export * from './editor';
+export * from './extension';
+export * from './extensions';
+export * from './factory';
+export * from './language';
+export * from './mimetype';
+export * from './searchprovider';
+export * from './theme';
+export * from './token';