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

package/src/theme.ts

@@ -0,0 +1,219 @@
+// Copyright (c) Jupyter Development Team.
+// Distributed under the terms of the Modified BSD License.
+
+import {
+  defaultHighlightStyle,
+  HighlightStyle,
+  syntaxHighlighting
+} from '@codemirror/language';
+import { Extension } from '@codemirror/state';
+import { EditorView } from '@codemirror/view';
+import { ITranslator, nullTranslator } from '@jupyterlab/translation';
+import { tags as t } from '@lezer/highlight';
+import { IEditorTheme, IEditorThemeRegistry } from './token';
+
+export const jupyterEditorTheme = EditorView.theme({
+  /**
+   * CodeMirror themes are handling the background/color in this way. This works
+   * fine for CodeMirror editors outside the notebook, but the notebook styles
+   * these things differently.
+   */
+  '&': {
+    background: 'var(--jp-layout-color0)',
+    color: 'var(--jp-content-font-color1)'
+  },
+
+  /* In the notebook, we want this styling to be handled by its container */
+  '.jp-CodeConsole &, .jp-Notebook &': {
+    background: 'transparent'
+  },
+
+  '.cm-content': {
+    caretColor: 'var(--jp-editor-cursor-color)'
+  },
+
+  '.cm-cursor, .cm-dropCursor': {
+    borderLeft:
+      'var(--jp-code-cursor-width0) solid var(--jp-editor-cursor-color)'
+  },
+
+  '.cm-selectionBackground, .cm-content ::selection': {
+    backgroundColor: 'var(--jp-editor-selected-background)'
+  },
+
+  '&.cm-focused .cm-selectionBackground': {
+    backgroundColor: 'var(--jp-editor-selected-focused-background)'
+  },
+
+  '.cm-gutters': {
+    borderRight: '1px solid var(--jp-border-color2)',
+    backgroundColor: 'var(--jp-layout-color2)'
+  },
+
+  '.cm-gutter, .cm-activeLine': {
+    backgroundColor: 'var(--jp-layout-color2)'
+  },
+
+  '.cm-searchMatch': {
+    backgroundColor: 'var(--jp-search-unselected-match-background-color)',
+    color: 'var(--jp-search-unselected-match-color)'
+  },
+
+  '.cm-searchMatch.cm-searchMatch-selected': {
+    backgroundColor:
+      'var(--jp-search-selected-match-background-color) !important',
+    color: 'var(--jp-search-selected-match-color) !important'
+  }
+});
+
+// The list of available tags for syntax highlighting is available at
+// https://lezer.codemirror.net/docs/ref/#highlight.tags
+export const jupyterHighlightStyle = HighlightStyle.define([
+  // Order matters - a rule will override the previous ones; important for example for in headings styles.
+  { tag: t.meta, color: 'var(--jp-mirror-editor-meta-color)' },
+  { tag: t.heading, color: 'var(--jp-mirror-editor-header-color)' },
+  {
+    tag: [t.heading1, t.heading2, t.heading3, t.heading4],
+    color: 'var(--jp-mirror-editor-header-color)',
+    fontWeight: 'bold'
+  },
+  {
+    tag: t.keyword,
+    color: 'var(--jp-mirror-editor-keyword-color)',
+    fontWeight: 'bold'
+  },
+  { tag: t.atom, color: 'var(--jp-mirror-editor-atom-color)' },
+  { tag: t.number, color: 'var(--jp-mirror-editor-number-color)' },
+  {
+    tag: [t.definition(t.name), t.function(t.definition(t.variableName))],
+    color: 'var(--jp-mirror-editor-def-color)'
+  },
+  {
+    tag: t.standard(t.variableName),
+    color: 'var(--jp-mirror-editor-builtin-color)'
+  },
+  {
+    tag: [t.special(t.variableName), t.self],
+    color: 'var(--jp-mirror-editor-variable-2-color)'
+  },
+  { tag: t.punctuation, color: 'var(--jp-mirror-editor-punctuation-color)' },
+  { tag: t.propertyName, color: 'var(--jp-mirror-editor-property-color)' },
+  {
+    tag: t.operator,
+    color: 'var(--jp-mirror-editor-operator-color)',
+    fontWeight: 'bold'
+  },
+  {
+    tag: t.comment,
+    color: 'var(--jp-mirror-editor-comment-color)',
+    fontStyle: 'italic'
+  },
+  { tag: t.string, color: 'var(--jp-mirror-editor-string-color)' },
+  {
+    tag: [t.labelName, t.monospace, t.special(t.string)],
+    color: 'var(--jp-mirror-editor-string-2-color)'
+  },
+  { tag: t.bracket, color: 'var(--jp-mirror-editor-bracket-color)' },
+  { tag: t.tagName, color: 'var(--jp-mirror-editor-tag-color)' },
+  { tag: t.attributeName, color: 'var(--jp-mirror-editor-attribute-color)' },
+  { tag: t.quote, color: 'var(--jp-mirror-editor-quote-color)' },
+  {
+    tag: t.link,
+    color: 'var(--jp-mirror-editor-link-color)',
+    textDecoration: 'underline'
+  },
+  { tag: [t.separator, t.derefOperator, t.paren], color: '' },
+  { tag: t.strong, fontWeight: 'bold' },
+  { tag: t.emphasis, fontStyle: 'italic' },
+  { tag: t.strikethrough, textDecoration: 'line-through' }
+]);
+
+/**
+ * JupyterLab CodeMirror 6 theme
+ */
+export const jupyterTheme: Extension = [
+  jupyterEditorTheme,
+  syntaxHighlighting(jupyterHighlightStyle)
+];
+
+/**
+ * CodeMirror 6 theme registry
+ */
+export class EditorThemeRegistry implements IEditorThemeRegistry {
+  /**
+   * CodeMirror 6 themes
+   */
+  private _themeMap: Map<string, IEditorTheme> = new Map([
+    ['jupyter', Object.freeze({ name: 'jupyter', theme: jupyterTheme })]
+  ]);
+
+  /**
+   * Get all themes
+   */
+  get themes(): IEditorTheme[] {
+    return Array.from(this._themeMap.values());
+  }
+
+  /**
+   * Get the default CodeMirror 6 theme for JupyterLab
+   *
+   * @returns Default theme
+   */
+  defaultTheme(): Extension {
+    return this._themeMap.get('jupyter')!.theme;
+  }
+
+  /**
+   * Register a new theme.
+   *
+   * @param theme Codemirror 6 theme
+   */
+  addTheme(theme: IEditorTheme) {
+    if (this._themeMap.has(theme.name)) {
+      throw new Error(`A theme named '${theme.name}' is already registered.`);
+    }
+    this._themeMap.set(theme.name, { displayName: theme.name, ...theme });
+  }
+
+  /**
+   * Get a theme.
+   *
+   * #### Notes
+   * It falls back to the default theme
+   *
+   * @param name Theme name
+   * @returns Theme extension
+   */
+  getTheme(name: string): Extension {
+    const ext = this._themeMap.get(name)?.theme;
+
+    return ext ?? this.defaultTheme();
+  }
+}
+
+/**
+ * EditorThemeRegistry namespace
+ */
+export namespace EditorThemeRegistry {
+  /**
+   * Get the default editor themes.
+   *
+   * @param translator Application translator
+   * @returns Default CodeMirror 6 themes
+   */
+  export function getDefaultThemes(
+    translator?: ITranslator | null
+  ): ReadonlyArray<Readonly<IEditorTheme>> {
+    const trans = (translator ?? nullTranslator).load('jupyterlab');
+    return [
+      Object.freeze({
+        name: 'codemirror',
+        displayName: trans.__('codemirror'),
+        theme: [
+          EditorView.baseTheme({}),
+          syntaxHighlighting(defaultHighlightStyle)
+        ]
+      })
+    ];
+  }
+}

package/src/token.ts

@@ -0,0 +1,436 @@
+/*
+ * Copyright (c) Jupyter Development Team.
+ * Distributed under the terms of the Modified BSD License.
+ */
+
+import type { LanguageSupport } from '@codemirror/language';
+import type { Extension, StateEffect } from '@codemirror/state';
+import type { EditorView } from '@codemirror/view';
+import type { CodeEditor } from '@jupyterlab/codeeditor';
+import type { ITranslator } from '@jupyterlab/translation';
+import { ReadonlyJSONObject, Token } from '@lumino/coreutils';
+import type { IDisposable } from '@lumino/disposable';
+import type { ISignal } from '@lumino/signaling';
+
+/**
+ * Dynamically configurable editor extension interface.
+ */
+export interface IConfigurableExtension<T> {
+  /**
+   * Create an editor extension for the provided value.
+   *
+   * @param value Editor extension parameter value
+   * @returns The editor extension
+   */
+  instance(value: T): Extension;
+  /**
+   * Reconfigure an editor extension.
+   *
+   * ### Notes
+   * Return `null` if the value does not trigger
+   * a state effect. In particular for immutable extension.
+   *
+   * @param value Editor extension value
+   * @returns Editor state effect
+   */
+  reconfigure(value: T): StateEffect<T> | null;
+}
+
+/**
+ * Editor language token.
+ */
+export const IEditorExtensionRegistry = new Token<IEditorExtensionRegistry>(
+  '@jupyterlab/codemirror:IEditorExtensionRegistry'
+);
+
+/**
+ * Interface of CodeMirror editor extensions handler
+ *
+ * ### Notes
+ * This handler is instantiated for each editor to manage its own
+ * set of extensions.
+ */
+export interface IExtensionsHandler extends IDisposable {
+  /**
+   * Signal triggered when the editor configuration changes.
+   * It provides the mapping of the new configuration (only those that changed).
+   *
+   * It should result in a call to `IExtensionsHandler.reconfigureExtensions`.
+   */
+  readonly configChanged: ISignal<this, Record<string, any>>;
+
+  /**
+   * Get a config option for the editor.
+   */
+  getOption(option: string): unknown;
+
+  /**
+   * Whether the option exists or not.
+   */
+  hasOption(option: string): boolean;
+
+  /**
+   * Set a config option for the editor.
+   *
+   * You will need to reconfigure the editor extensions by listening
+   * to `IExtensionsHandler.configChanged`.
+   */
+  setOption(option: string, value: unknown): void;
+
+  /**
+   * Set config options for the editor.
+   *
+   * You will need to reconfigure the editor extensions by listening
+   * to `IExtensionsHandler.configChanged`.
+   *
+   * This method is preferred when setting several options. The
+   * options are set within an operation, which only performs
+   * the costly update at the end, and not after every option
+   * is set.
+   */
+  setOptions(options: Record<string, any>): void;
+
+  /**
+   * Returns the list of initial extensions of an editor.
+   *
+   * @returns The initial editor extensions
+   */
+  getInitialExtensions(): Extension[];
+
+  /**
+   * Appends extensions to the top-level configuration of the
+   * editor.
+   *
+   * @alpha
+   * @param view Editor view
+   * @param extension Editor extension to inject
+   */
+  injectExtension(view: EditorView, extension: Extension): void;
+
+  /**
+   * Reconfigures the extension mapped with key with the provided value.
+   *
+   * @param view Editor view
+   * @param key Parameter unique key
+   * @param value Parameter value to be applied
+   */
+  reconfigureExtension<T>(view: EditorView, key: string, value: T): void;
+
+  /**
+   * Reconfigures all the extensions mapped with the options from the
+   * provided partial configuration.
+   *
+   * @param view Editor view
+   * @param configuration Editor configuration
+   */
+  reconfigureExtensions(
+    view: EditorView,
+    configuration: Record<string, any>
+  ): void;
+}
+
+/**
+ * Editor extension factory interface.
+ *
+ * @template T Extension parameter type.
+ */
+export interface IEditorExtensionFactory<T = undefined> {
+  /**
+   * Editor extension unique identifier.
+   */
+  readonly name: string;
+  /**
+   * Extension factory.
+   *
+   * @param options
+   * @returns The extension builder or null if the extension is not active for that document
+   */
+  readonly factory: (
+    options: IEditorExtensionFactory.IOptions
+  ) => IConfigurableExtension<T> | null;
+  /**
+   * Extension default value
+   *
+   * ### Notes
+   * If undefined but has a schema, the default value will be `null` to be JSON serializable.
+   */
+  readonly default?: T;
+  /**
+   * JSON schema defining the configurable option through user settings.
+   *
+   * If this is defined, every time the setting changes, `IConfigurableExtension.reconfigure`
+   * will be called with the new setting value.
+   *
+   * ### Notes
+   * If no default value is provided, `IEditorExtensionFactory.default` will be used.
+   * If the extension is to be handled by the code only, this should not be defined.
+   */
+  readonly schema?: ReadonlyJSONObject;
+}
+
+/**
+ * CodeMirror extension factory namespace
+ */
+export namespace IEditorExtensionFactory {
+  /**
+   * CodeMirror extension factory options
+   */
+  export interface IOptions {
+    /**
+     * Whether the editor will be inline or not.
+     */
+    inline: boolean;
+    /**
+     * The model used by the editor.
+     */
+    model: CodeEditor.IModel;
+  }
+}
+
+/**
+ * Interface for generating editor configuration registry.
+ */
+export interface IEditorExtensionRegistry {
+  /**
+   * Base editor configuration
+   *
+   * This is the default configuration.
+   */
+  readonly baseConfiguration: Record<string, any>;
+
+  /**
+   * Add a default editor extension
+   *
+   * @template T Extension parameter type
+   * @param factory Extension factory
+   */
+  addExtension<T>(factory: IEditorExtensionFactory<T>): void;
+
+  /**
+   * Create a new extensions handler for an editor
+   *
+   * @param options Extensions options and initial editor configuration
+   */
+  createNew(
+    options: IEditorExtensionFactory.IOptions & {
+      /**
+       * The configuration options for the editor.
+       */
+      config?: Record<string, any>;
+    }
+  ): IExtensionsHandler;
+}
+
+/**
+ * Editor factory constructor options
+ */
+export interface IEditorFactoryOptions {
+  /**
+   * Editor extensions registry
+   */
+  extensions?: IEditorExtensionRegistry;
+  /**
+   * Editor languages registry
+   */
+  languages?: IEditorLanguageRegistry;
+  /**
+   * Application translation registry
+   */
+  translator?: ITranslator;
+}
+
+/**
+ * Editor language token.
+ */
+export const IEditorLanguageRegistry = new Token<IEditorLanguageRegistry>(
+  '@jupyterlab/codemirror:IEditorLanguageRegistry'
+);
+
+/**
+ * The interface of a codemirror language specification.
+ */
+export interface IEditorLanguage {
+  /**
+   * Language name.
+   */
+  readonly name: string;
+  /**
+   * Language displayed name.
+   */
+  readonly displayName?: string;
+  /**
+   * Language name alias.
+   */
+  readonly alias?: readonly string[];
+  /**
+   * Language mime types.
+   */
+  readonly mime: string | readonly string[];
+  /**
+   * Language support loader.
+   */
+  readonly load?: () => Promise<LanguageSupport>;
+  /**
+   * Supported file extensions.
+   */
+  readonly extensions?: readonly string[];
+  /**
+   * Filename expression supported by the language.
+   */
+  readonly filename?: RegExp;
+  /**
+   * CodeMirror language support.
+   *
+   * ### Notes
+   * It can provided directly or it will be obtained using `load`.
+   */
+  support?: LanguageSupport;
+}
+
+/**
+ * Editor language interface
+ */
+export interface IEditorLanguageRegistry {
+  /**
+   * Register a new language for CodeMirror
+   *
+   * @param language Language to register
+   */
+  addLanguage(language: IEditorLanguage): void;
+
+  /**
+   * Find a codemirror language by name or CodeMirror spec.
+   *
+   * @param language The CodeMirror language
+   * @param fallback Whether to fallback to default mimetype spec or not
+   * @returns The language or null
+   */
+  findBest(
+    language: string | IEditorLanguage,
+    fallback?: boolean
+  ): IEditorLanguage | null;
+
+  /**
+   * Find a codemirror language by MIME.
+   *
+   * @param mime Mime type to look for
+   * @returns The language or null
+   */
+  findByMIME(mime: string | readonly string[]): IEditorLanguage | null;
+
+  /**
+   * Find a codemirror language by name.
+   *
+   * @param name The language name
+   * @returns The language or null
+   */
+  findByName(name: string): IEditorLanguage | null;
+
+  /**
+   * Find a codemirror language by extension.
+   *
+   * @param ext The extension name
+   * @returns The language or null
+   */
+  findByExtension(ext: string | readonly string[]): IEditorLanguage | null;
+
+  /**
+   * Find a codemirror language by filename.
+   *
+   * @param name File name
+   * @returns The language or null
+   */
+  findByFileName(name: string): IEditorLanguage | null;
+
+  /**
+   * Load a CodeMirror language specified by name or Codemirror spec.
+   *
+   * @param language - The language to ensure.  If it is a string, uses {@link findBest}
+   *   to get the appropriate spec.
+   *
+   * @returns A promise that resolves when the language is available.
+   */
+  getLanguage(
+    language: string | IEditorLanguage
+  ): Promise<IEditorLanguage | null>;
+
+  /**
+   * Get the raw list of available languages specs.
+   *
+   * @returns The available languages
+   */
+  getLanguages(): IEditorLanguage[];
+
+  /**
+   * Parse and style a string.
+   *
+   * @param code Code to highlight
+   * @param language Code language
+   * @param el HTML element into which the highlighted code will be inserted
+   */
+  highlight(
+    code: string,
+    language: IEditorLanguage | null,
+    el: HTMLElement
+  ): Promise<void>;
+}
+
+/**
+ * Editor theme token.
+ */
+export const IEditorThemeRegistry = new Token<IEditorThemeRegistry>(
+  '@jupyterlab/codemirror:IEditorThemeRegistry'
+);
+
+/**
+ * Editor theme interface
+ */
+export interface IEditorTheme {
+  /**
+   * Theme unique identifier
+   */
+  readonly name: string;
+  /**
+   * Theme name
+   */
+  readonly displayName?: string;
+  /**
+   * Editor extension for the theme
+   */
+  readonly theme: Extension;
+}
+
+/**
+ * Theme editor registry interface
+ */
+export interface IEditorThemeRegistry {
+  /**
+   * Register a new theme.
+   *
+   * @param theme Codemirror 6 theme
+   */
+  addTheme(theme: IEditorTheme): void;
+
+  /**
+   * Get the default CodeMirror 6 theme for JupyterLab
+   *
+   * @returns Default theme as a CodeMirror extension
+   */
+  defaultTheme(): Extension;
+
+  /**
+   * Get a theme.
+   *
+   * #### Notes
+   * It falls back to the default theme
+   *
+   * @param name Theme name
+   * @returns Theme extension
+   */
+  getTheme(name: string): Extension;
+
+  /**
+   * Get all themes
+   */
+  readonly themes: IEditorTheme[];
+}

package/src/typings.d.ts

@@ -0,0 +1,13 @@
+/*
+ * Copyright (c) Jupyter Development Team.
+ * Distributed under the terms of the Modified BSD License.
+ */
+
+declare module '@codemirror/legacy-modes/mode/python' {
+  import { StreamParser } from '@codemirror/language';
+
+  export const python: StreamParser<unknown>;
+  export const cython: StreamParser<unknown>;
+
+  export function mkPython(parserConf: any): StreamParser<unknown>;
+}