@dxos/ui-editor 0.0.0

package/src/index.ts

@@ -0,0 +1,14 @@
+//
+// Copyright 2022 DXOS.org
+//
+
+export { type Extension, EditorState } from '@codemirror/state';
+export { EditorView, keymap } from '@codemirror/view';
+export { tags } from '@lezer/highlight';
+
+export { TextKind } from '@dxos/protocols/proto/dxos/echo/model/text';
+
+export * from './defaults';
+export * from './extensions';
+export * from './types';
+export * from './util';

package/src/styles/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+export * from './markdown';
+export * from './theme';
+export * from './tokens';

package/src/styles/markdown.ts

@@ -0,0 +1,26 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { mx } from '@dxos/ui-theme';
+
+export type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
+
+// https://tailwindcss.com/docs/font-weight
+const headings: Record<HeadingLevel, string> = {
+  1: 'text-4xl',
+  2: 'text-3xl',
+  3: 'text-2xl',
+  4: 'text-xl',
+  5: 'text-lg',
+  6: '', // TODO(burdon): Should be text-base, but that's a color in our system.
+};
+
+export const markdownTheme = {
+  code: 'font-mono !no-underline text-neutral-700 dark:text-neutral-300',
+  codeMark: 'font-mono text-primary-500',
+  mark: 'opacity-50',
+  heading: (level: HeadingLevel) => {
+    return mx(headings[level], 'dark:text-neutral-400');
+  },
+};

package/src/styles/theme.ts

@@ -0,0 +1,293 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { type Extension } from '@codemirror/state';
+import { EditorView } from '@codemirror/view';
+
+import { fontBody, fontMono } from './tokens';
+
+/**
+ * Global base theme.
+ *
+ * NOTE: The base theme is GLOBAL and is applied to ALL editors.
+ * NOTE: `light` and `dark` selectors are preprocessed by CodeMirror and can only be in the base theme.
+ * NOTE: Use 'unset' to remove default CM style.
+ *
+ * Examples:
+ * - https://codemirror.net/examples/styling
+ * - https://github.com/codemirror/view/blob/main/src/theme.ts
+ * - https://github.com/codemirror/theme-one-dark/blob/main/src/one-dark.ts
+ *
+ * Main layout:
+ * - https://codemirror.net/examples/styling
+ * - https://codemirror.net/docs/guide (DOM Structure).
+ *
+ * <div class="cm-editor [cm-focused] [generated classes]">
+ *   <div class="cm-scroller">
+ *     <div class="cm-gutters">
+ *       <div class="cm-gutter [...]">
+ *         <div class="cm-gutterElement">...</div>
+ *       </div>
+ *     </div>
+ *     <div class="cm-content" role="textbox" contenteditable="true">
+ *       <div class="cm-line"></div>
+ *     </div>
+ *     <div class="cm-selectionLayer">
+ *       <div class="cm-selectionBackground"></div>
+ *     </div>
+ *     <div class="cm-cursorLayer">
+ *       <div class="cm-cursor"></div>
+ *     </div>
+ *   </div>
+ * </div>
+ */
+export const baseTheme = EditorView.baseTheme({
+  '&': {},
+  '&.cm-focused': {
+    outline: 'none',
+  },
+
+  /**
+   * Scroller
+   */
+  '.cm-scroller': {
+    overflowY: 'auto',
+  },
+
+  /**
+   * Content
+   * NOTE: Apply margins to content so that scrollbar is at the edge of the container.
+   */
+  '.cm-content': {
+    padding: 'unset',
+    lineHeight: '24px',
+    color: 'unset',
+  },
+
+  /**
+   * Gutters
+   * NOTE: Gutters should have the same top margin as the content.
+   */
+  '.cm-gutters': {
+    background: 'transparent',
+    borderRight: 'none',
+  },
+  '.cm-gutter': {},
+  '.cm-gutter.cm-lineNumbers': {
+    paddingRight: '4px',
+    borderRight: '1px solid var(--dx-subduedSeparator)',
+    color: 'var(--dx-subduedText)',
+  },
+  '.cm-gutter.cm-lineNumbers .cm-gutterElement': {
+    minWidth: '40px',
+  },
+  /**
+   * Height is set to match the corresponding line (which may have wrapped).
+   */
+  '.cm-gutterElement': {
+    lineHeight: '24px',
+    fontSize: '12px',
+  },
+
+  /**
+   * Line.
+   */
+  '.cm-line': {
+    lineHeight: '24px',
+    paddingInline: 0,
+  },
+  '.cm-activeLine': {
+    background: 'var(--dx-cmActiveLine)',
+  },
+
+  /**
+   * Cursor (layer).
+   */
+  '.cm-cursor, .cm-dropCursor': {
+    borderLeft: '2px solid var(--dx-cmCursor)',
+  },
+  '.cm-placeholder': {
+    color: 'var(--dx-placeholder)',
+  },
+
+  /**
+   * Selection (layer).
+   */
+  '.cm-selectionBackground': {
+    background: 'var(--dx-cmSelection)',
+  },
+  '&.cm-focused > .cm-scroller > .cm-selectionLayer .cm-selectionBackground': {
+    background: 'var(--dx-cmFocusedSelection)',
+  },
+
+  /**
+   * Search.
+   * NOTE: Matches comment.
+   */
+  '.cm-searchMatch': {
+    margin: '0 -3px',
+    padding: '3px',
+    borderRadius: '3px',
+    background: 'var(--dx-cmHighlightSurface)',
+    color: 'var(--dx-cmHighlight)',
+  },
+  '.cm-searchMatch-selected': {
+    textDecoration: 'underline',
+  },
+
+  /**
+   * Link.
+   */
+  '.cm-link': {
+    textDecorationLine: 'underline',
+    textDecorationThickness: '1px',
+    textDecorationColor: 'var(--dx-separator)',
+    textUnderlineOffset: '2px',
+    borderRadius: '.125rem',
+  },
+  '.cm-link > span': {
+    color: 'var(--dx-accentText)',
+  },
+
+  /**
+   * Tooltip.
+   */
+  '.cm-tooltip': {
+    background: 'var(--dx-baseSurface)',
+  },
+  '.cm-tooltip-below': {},
+
+  /**
+   * Autocomplete.
+   * https://github.com/codemirror/autocomplete/blob/main/src/completion.ts
+   */
+  '.cm-tooltip.cm-tooltip-autocomplete': {
+    marginTop: '6px',
+    marginLeft: '-10px',
+    border: '2px solid var(--dx-separator)',
+    borderRadius: '4px',
+  },
+  '.cm-tooltip.cm-tooltip-autocomplete > ul': {
+    maxHeight: '20em',
+  },
+  '.cm-tooltip.cm-tooltip-autocomplete > ul > li': {
+    padding: '4px',
+  },
+  '.cm-tooltip.cm-tooltip-autocomplete > ul > li[aria-selected]': {
+    background: 'var(--dx-activeSurface)',
+    color: 'var(--dx-activeSurfaceText)',
+  },
+  '.cm-tooltip.cm-tooltip-autocomplete > ul > completion-section': {
+    paddingLeft: '4px !important',
+    color: 'var(--dx-hoverSurfaceText)',
+  },
+
+  /**
+   * Completion info.
+   */
+  '.cm-completionInfo': {
+    width: '360px !important',
+    margin: '-10px 1px 0 1px',
+    padding: '8px !important',
+    borderColor: 'var(--dx-separator)',
+  },
+  '.cm-completionIcon': {
+    display: 'none',
+  },
+  '.cm-completionLabel': {
+    color: 'var(--dx-description)',
+    padding: '0 4px',
+  },
+  '.cm-completionMatchedText': {
+    color: 'var(--dx-baseText)',
+    textDecoration: 'none !important',
+  },
+
+  /**
+   * Panels
+   * https://github.com/codemirror/search/blob/main/src/search.ts#L745
+   *
+   * Find/replace panel.
+   * <div class="cm-announced">...</div>
+   * <div class="cm-scroller">...</div>
+   * <div class="cm-panels cm-panels-bottom">
+   *   <div class="cm-search cm-panel">
+   *     <input class="cm-textfield" />
+   *     <button class="cm-button">...</button>
+   *     <label><input type="checkbox" />...</label>
+   *   </div>
+   * </div
+   */
+  // TODO(burdon): Implement custom panel (with icon buttons).
+  '.cm-panels': {},
+  '.cm-panel': {
+    backgroundColor: 'var(--surface-bg)',
+  },
+  '.cm-panel input, .cm-panel button, .cm-panel label': {
+    color: 'var(--dx-subdued)',
+    fontSize: '14px',
+    all: 'unset',
+    margin: '3px !important',
+    padding: '2px 6px !important',
+    outline: '1px solid transparent',
+  },
+  '.cm-panel input, .cm-panel button': {
+    backgroundColor: 'var(--dx-inputSurface)',
+  },
+  '.cm-panel input:focus, .cm-panel button:focus': {
+    outline: '1px solid var(--dx-neutralFocusIndicator)',
+  },
+  '.cm-panel label': {
+    display: 'inline-flex',
+    alignItems: 'center',
+    cursor: 'pointer',
+  },
+  '.cm-panel input.cm-textfield': {},
+  '.cm-panel input[type=checkbox]': {
+    width: '8px',
+    height: '8px',
+    marginRight: '6px !important',
+    padding: '2px !important',
+    color: 'var(--dx-neutralFocusIndicator)',
+  },
+  '.cm-panel button': {
+    '&:hover': {
+      backgroundColor: 'var(--dx-accentSurfaceHover) !important',
+    },
+    '&:active': {
+      backgroundColor: 'var(--dx-accentSurfaceHover)',
+    },
+  },
+  '.cm-panel.cm-search': {
+    padding: '4px',
+    borderTop: '1px solid var(--dx-separator)',
+  },
+});
+
+export const editorGutter: Extension = EditorView.theme({
+  '.cm-gutters': {
+    // NOTE: Non-transparent background required to cover content if scrolling horizontally.
+    background: 'var(--dx-baseSurface) !important',
+    paddingRight: '1rem',
+  },
+});
+
+export type FontOptions = {
+  monospace?: boolean;
+};
+
+export const createFontTheme = ({ monospace }: FontOptions = {}) =>
+  EditorView.theme({
+    // Set metrics on the scroller (this is often what CM uses for layout).
+    '.cm-scroller': {
+      fontFamily: monospace ? fontMono : fontBody,
+      fontSize: '16px',
+    },
+
+    // Maintain defaults for UI components.
+    '.cm-content, .cm-gutters, .cm-panel': {
+      fontFamily: 'inherit',
+      fontSize: 'inherit',
+    },
+  });

package/src/styles/tokens.ts

@@ -0,0 +1,17 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { tokens } from '@dxos/ui-theme';
+import { get } from '@dxos/util';
+
+/**
+ * Returns the tailwind token value.
+ */
+const getToken = (path: string, defaultValue?: string | string[]): string => {
+  const value = get(tokens, path, defaultValue);
+  return value?.toString() ?? '';
+};
+
+export const fontBody = getToken('fontFamily.body');
+export const fontMono = getToken('fontFamily.mono');

package/src/types/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './types';

package/src/types/types.ts

@@ -0,0 +1,32 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { type EditorView } from '@codemirror/view';
+import * as Schema from 'effect/Schema';
+
+// Runtime data structure.
+export type Range = {
+  from: number;
+  to: number;
+};
+
+// Persistent data structure.
+// TODO(burdon): Rename annotation?
+export type Comment = {
+  id: string;
+  cursor?: string;
+};
+
+/**
+ * Callback that renders into a DOM element within the editor.
+ */
+export type RenderCallback<Props extends object> = (el: HTMLElement, props: Props, view: EditorView) => void;
+
+export const EditorViewModes = ['preview', 'readonly', 'source'] as const;
+export const EditorViewMode = Schema.Union(...EditorViewModes.map((mode) => Schema.Literal(mode)));
+export type EditorViewMode = Schema.Schema.Type<typeof EditorViewMode>;
+
+export const EditorInputModes = ['default', 'vim', 'vscode'] as const;
+export const EditorInputMode = Schema.Union(...EditorInputModes.map((mode) => Schema.Literal(mode)));
+export type EditorInputMode = Schema.Schema.Type<typeof EditorInputMode>;

package/src/util/cursor.ts

@@ -0,0 +1,56 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { type EditorState } from '@codemirror/state';
+
+import { type Range } from '../types';
+
+import { singleValueFacet } from './facet';
+
+/**
+ * Determines if two ranges overlap.
+ * A range is considered to overlap if there is any intersection
+ * between the two ranges, inclusive of their boundaries.
+ */
+export const overlap = (a: Range, b: Range): boolean => a.from <= b.to && a.to >= b.from;
+
+/**
+ * Converts indexes into the text document into stable peer-independent cursors.
+ *
+ * See:
+ *  - https://automerge.org/automerge/api-docs/js/functions/next.getCursor.html
+ *  - https://github.com/yjs/yjs?tab=readme-ov-file#relative-positions
+ *
+ * @param {assoc} number Negative values will associate the cursor with the previous character
+ *  while positive - with the next one.
+ */
+export interface CursorConverter {
+  toCursor(position: number, assoc?: -1 | 1 | undefined): string;
+  fromCursor(cursor: string): number;
+}
+
+const defaultCursorConverter: CursorConverter = {
+  toCursor: (position) => position.toString(),
+  fromCursor: (cursor) => parseInt(cursor),
+};
+
+export class Cursor {
+  static readonly converter = singleValueFacet(defaultCursorConverter);
+
+  static readonly getCursorFromRange = (state: EditorState, range: Range) => {
+    const cursorConverter = state.facet(Cursor.converter);
+    const from = cursorConverter.toCursor(range.from);
+    const to = cursorConverter.toCursor(range.to, -1);
+    return [from, to].join(':');
+  };
+
+  static readonly getRangeFromCursor = (state: EditorState, cursor: string) => {
+    const cursorConverter = state.facet(Cursor.converter);
+
+    const parts = cursor.split(':');
+    const from = cursorConverter.fromCursor(parts[0]);
+    const to = cursorConverter.fromCursor(parts[1]);
+    return from !== undefined && to !== undefined ? { from, to } : undefined;
+  };
+}

package/src/util/debug.ts

@@ -0,0 +1,56 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { type Transaction } from '@codemirror/state';
+import { type EditorView } from '@codemirror/view';
+
+import { log } from '@dxos/log';
+
+export const join = (...lines: string[]) => lines.join('\n');
+
+/**
+ * CodeMirror callbacks swallow errors so wrap handlers.
+ */
+export const wrapWithCatch = (fn: (...args: any[]) => any, label?: string) => {
+  return (...args: any[]) => {
+    try {
+      return fn(...args);
+    } catch (err) {
+      log.catch(err, { label });
+    }
+  };
+};
+
+/**
+ * Log all changes before dispatching them to the view.
+ * https://codemirror.net/docs/ref/#view.EditorView.dispatch
+ */
+export const debugDispatcher = (trs: readonly Transaction[], view: EditorView) => {
+  logChanges(trs);
+  view.update(trs);
+};
+
+/**
+ * Util to log transactions in update listener.
+ */
+export const logChanges = (trs: readonly Transaction[]) => {
+  const changes = trs
+    .flatMap((tr) => {
+      if (tr.changes.empty) {
+        return undefined;
+      }
+
+      const changes: any[] = [];
+      tr.changes.iterChanges((fromA, toA, fromB, toB, inserted) =>
+        changes.push(JSON.stringify({ fromA, toA, fromB, toB, inserted: inserted.toString() })),
+      );
+
+      return changes;
+    })
+    .filter(Boolean);
+
+  if (changes.length) {
+    log('changes', { changes });
+  }
+};

package/src/util/decorations.ts

@@ -0,0 +1,21 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Range } from '@codemirror/state';
+import { type Decoration, type DecorationSet } from '@codemirror/view';
+
+export const decorationSetToArray = (deco: DecorationSet): readonly Range<Decoration>[] => {
+  const ranges: Range<Decoration>[] = [];
+  const iter = deco.iter();
+  while (iter.value) {
+    ranges.push({
+      from: iter.from,
+      to: iter.to,
+      value: iter.value,
+    });
+    iter.next();
+  }
+
+  return ranges;
+};

package/src/util/dom.ts

@@ -0,0 +1,36 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+// TODO(burdon): Factor out to @dxos/ui
+
+export type Rect = {
+  readonly left: number;
+  readonly right: number;
+  readonly top: number;
+  readonly bottom: number;
+};
+
+export const flattenRect = (rect: Rect, left: boolean): Rect => {
+  const x = left ? rect.left : rect.right;
+  return { left: x, right: x, top: rect.top, bottom: rect.bottom };
+};
+
+let scratchRange: Range | null;
+
+export const textRange = (node: Text, from: number, to = from): Range => {
+  const range = scratchRange || (scratchRange = document.createRange());
+  range.setEnd(node, to);
+  range.setStart(node, from);
+  return range;
+};
+
+export const clientRectsFor = (dom: Node): DOMRectList => {
+  if (dom.nodeType === 3) {
+    return textRange(dom as Text, 0, dom.nodeValue!.length).getClientRects();
+  } else if (dom.nodeType === 1) {
+    return (dom as HTMLElement).getClientRects();
+  } else {
+    return [] as any as DOMRectList;
+  }
+};

package/src/util/facet.ts

@@ -0,0 +1,13 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { Facet } from '@codemirror/state';
+
+export const singleValueFacet = <I, O = I>(defaultValue?: O) =>
+  Facet.define<I, O>({
+    // Called immediately.
+    combine: (providers) => {
+      return (providers[0] ?? defaultValue) as O;
+    },
+  });

package/src/util/index.ts

@@ -0,0 +1,10 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export * from './cursor';
+export * from './decorations';
+export * from './debug';
+export * from './dom';
+export * from './facet';
+export * from './util';

package/src/util/util.ts

@@ -0,0 +1,29 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type EditorView } from '@codemirror/view';
+
+export const insertAtCursor = (view: EditorView, from: number, insert: string) => {
+  view.dispatch({
+    changes: { from, to: from, insert },
+    selection: { anchor: from + insert.length, head: from + insert.length },
+  });
+};
+
+/**
+ * If the cursor is at the start of a line, insert the text at the cursor.
+ * Otherwise, insert the text on a new line.
+ */
+export const insertAtLineStart = (view: EditorView, from: number, insert: string) => {
+  const line = view.state.doc.lineAt(from);
+  if (line.from === from) {
+    insertAtCursor(view, from, insert);
+  } else {
+    insert = '\n' + insert;
+    view.dispatch({
+      changes: { from: line.to, to: line.to, insert },
+      selection: { anchor: line.to + insert.length, head: line.to + insert.length },
+    });
+  }
+};