@dxos/ui-editor 0.0.0

package/src/extensions/outliner/tree.test.ts

@@ -0,0 +1,168 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { markdown, markdownLanguage } from '@codemirror/lang-markdown';
+import { EditorState } from '@codemirror/state';
+import { beforeEach, describe, test } from 'vitest';
+
+import { type Range } from '../../types';
+import { join } from '../../util';
+
+import { type Item, listItemToString, outlinerTree, treeFacet } from './tree';
+
+const lines = [
+  '- [ ] 1',
+  '- [ ] 2',
+  '  - [ ] 2.1',
+  '  - [ ] 2.2',
+  '    - 2.2.1',
+  '    - 2.2.2',
+  '    - 2.2.3',
+  '  - [ ] 2.3',
+  '- [ ] 3',
+];
+
+const getPos = (line: number) => {
+  return lines.slice(0, line).reduce((acc, line) => acc + line.length + 1, 0);
+};
+
+const extensions = [markdown({ base: markdownLanguage }), outlinerTree()];
+
+describe('tree (boundary conditions)', () => {
+  test('empty', ({ expect }) => {
+    const state = EditorState.create({ doc: join(''), extensions });
+    const tree = state.facet(treeFacet);
+    expect(tree).to.exist;
+  });
+
+  test('content range', ({ expect }) => {
+    const state = EditorState.create({ doc: '- [ ] A', extensions });
+    const tree = state.facet(treeFacet);
+    console.log(JSON.stringify(tree, null, 2));
+    expect(tree.toJSON()).to.deep.eq({
+      type: 'root',
+      index: -1,
+      level: -1,
+      lineRange: { from: 0, to: -1 },
+      contentRange: { from: 0, to: -1 },
+      children: [
+        {
+          type: 'task',
+          index: 0,
+          level: 0,
+          lineRange: { from: 0, to: 7 },
+          contentRange: { from: 6, to: 7 },
+          children: [],
+        },
+      ],
+    });
+
+    const item = tree.find(0);
+    expect(item?.contentRange).to.include({ from: 6, to: state.doc.length });
+  });
+
+  test('empty continuation', ({ expect }) => {
+    const state = EditorState.create({ doc: join('- [ ] A', '  '), extensions });
+    const tree = state.facet(treeFacet);
+    tree.traverse((item, level) => {
+      console.log(listItemToString(item, level));
+    });
+  });
+});
+
+describe('tree (advanced)', () => {
+  let state: EditorState;
+
+  beforeEach(() => {
+    state = EditorState.create({ doc: join(...lines), extensions });
+  });
+
+  test('traverse', ({ expect }) => {
+    const tree = state.facet(treeFacet);
+    let count = 0;
+    tree.traverse((item, level) => {
+      console.log(listItemToString(item, level));
+      count++;
+    });
+    expect(count).to.eq(9);
+  });
+
+  test('continguous', ({ expect }) => {
+    const tree = state.facet(treeFacet);
+    const ranges: Range[] = [];
+    tree.traverse((item) => {
+      console.log(listItemToString(item));
+      ranges.push(item.lineRange);
+    });
+
+    // Check no gaps between ranges.
+    expect(ranges[0].from).toBe(0);
+    expect(ranges[ranges.length - 1].to).toBe(state.doc.length);
+    for (let i = 0; i < ranges.length - 1; i++) {
+      const current = ranges[i];
+      const next = ranges[i + 1];
+      expect(current.to + 1).to.eq(next.from);
+    }
+  });
+
+  test('find', ({ expect }) => {
+    const tree = state.facet(treeFacet);
+    expect(tree.find(0)).to.include({ type: 'task' });
+    expect(tree.find(state.doc.length)).to.include({ type: 'task' });
+
+    expect(tree.find(getPos(1))).to.include({ type: 'task' });
+    expect(tree.find(getPos(1))).to.eq(tree.find(getPos(1) + 4));
+    expect(tree.find(getPos(5))).to.include({ type: 'bullet' });
+  });
+
+  test('siblings', ({ expect }) => {
+    const tree = state.facet(treeFacet);
+    const items: Item[] = [];
+    tree.traverse((item) => {
+      items.push(item);
+    });
+
+    expect(items[0].nextSibling).toBe(items[1]);
+    expect(items[1].prevSibling).toBe(items[0]);
+
+    expect(items[1].nextSibling).toBe(items[8]);
+    expect(items[8].prevSibling).toBe(items[1]);
+  });
+
+  test('next/previous', ({ expect }) => {
+    const tree = state.facet(treeFacet);
+    const items: Item[] = [];
+    tree.traverse((item) => {
+      items.push(item);
+    });
+
+    expect(tree.prev(items[0])).not.to.exist;
+    expect(tree.next(items[items.length - 1])).not.to.exist;
+
+    for (let i = 0; i < items.length - 1; i++) {
+      const current = items[i];
+      const next = items[i + 1];
+      expect(tree.next(current)?.index).toEqual(next.index);
+      expect(tree.prev(next)?.index).toEqual(current.index);
+    }
+  });
+
+  test('lastDescendant', ({ expect }) => {
+    const tree = state.facet(treeFacet);
+    {
+      const item = tree.find(getPos(0))!;
+      expect(tree.lastDescendant(item).index).to.eq(item.index);
+    }
+    {
+      const item = tree.find(getPos(1))!;
+      const last = tree.find(getPos(7))!;
+      expect(tree.lastDescendant(item).index).to.eq(last.index);
+    }
+    {
+      const item = tree.find(getPos(3))!;
+      const last = tree.find(getPos(6))!;
+      expect(tree.lastDescendant(item).index).to.eq(last.index);
+    }
+  });
+});

package/src/extensions/outliner/tree.ts

@@ -0,0 +1,317 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { syntaxTree } from '@codemirror/language';
+import { type EditorState, type Extension, StateField, type Transaction } from '@codemirror/state';
+import { Facet } from '@codemirror/state';
+import { type SyntaxNode } from '@lezer/common';
+
+import { invariant } from '@dxos/invariant';
+
+import { type Range } from '../../types';
+
+/**
+ * Represents a single item in the tree.
+ */
+export interface Item {
+  type: 'root' | 'bullet' | 'task' | 'unknown';
+  index: number;
+  level: number;
+  node: SyntaxNode;
+  parent?: Item;
+  nextSibling?: Item;
+  prevSibling?: Item;
+  children: Item[];
+  /**
+   * Actual range.
+   * Starts at the start of the line containing the item and ends at the end of the line before the
+   * first child or next sibling.
+   */
+  lineRange: Range;
+  /**
+   * Range of the editable content.
+   * This doesn't include the list or task marker or indentation.
+   */
+  contentRange: Range;
+}
+
+export const itemToJSON = ({ type, index, level, lineRange, contentRange, children }: Item): any => {
+  return { type, index, level, lineRange, contentRange, children: children.map(itemToJSON) };
+};
+
+/**
+ * Tree assumes the entire document is a single contiguous well-formed hierarchy of markdown LiteItem nodes.
+ */
+export class Tree implements Item {
+  type: Item['type'] = 'root';
+  index = -1;
+  level = -1;
+  node: Item['node'];
+  lineRange: Item['lineRange'];
+  contentRange: Item['contentRange'];
+  children: Item['children'] = [];
+
+  constructor(node: SyntaxNode) {
+    this.node = node;
+    this.lineRange = { from: node.from, to: node.to };
+    this.contentRange = this.lineRange;
+  }
+
+  toJSON() {
+    return itemToJSON(this);
+  }
+
+  get root(): Item {
+    return this;
+  }
+
+  traverse<T = any>(cb: (item: Item, level: number) => T | void): T | undefined;
+  traverse<T = any>(item: Item, cb: (item: Item, level: number) => T | void): T | undefined;
+  traverse<T = any>(
+    itemOrCb: Item | ((item: Item, level: number) => T | undefined | void),
+    maybeCb?: (item: Item, level: number) => T | undefined | void,
+  ): T | undefined {
+    if (typeof itemOrCb === 'function') {
+      return traverse<T>(this, itemOrCb);
+    } else {
+      return traverse<T>(itemOrCb, maybeCb!);
+    }
+  }
+
+  /**
+   * Return the closest item.
+   */
+  find(pos: number): Item | undefined {
+    return this.traverse<Item>((item) => (item.lineRange.from <= pos && item.lineRange.to >= pos ? item : undefined));
+  }
+
+  /**
+   * Return the first child, next sibling, or parent's next sibling.
+   */
+  next(item: Item, enter = true): Item | undefined {
+    if (enter && item.children.length > 0) {
+      return item.children[0];
+    }
+
+    if (item.nextSibling) {
+      return item.nextSibling;
+    }
+
+    if (item.parent) {
+      return this.next(item.parent, false);
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Return the previous sibling, or parent.
+   */
+  prev(item: Item): Item | undefined {
+    if (item.prevSibling) {
+      return this.lastDescendant(item.prevSibling);
+    }
+
+    return item.parent?.type === 'root' ? undefined : item.parent;
+  }
+
+  /**
+   * Return the last descendant of the item, or the item itself if it has no children.
+   */
+  lastDescendant(item: Item): Item {
+    return item.children.length > 0 ? this.lastDescendant(item.children.at(-1)!) : item;
+  }
+}
+
+export const getRange = (tree: Tree, item: Item): [number, number] => {
+  const lastDescendant = tree.lastDescendant(item);
+  return [item.lineRange.from, lastDescendant.lineRange.to];
+};
+
+/**
+ * Traverse the tree, calling the callback for each item.
+ * If the callback returns a value, the traversal is stopped and the value is returned.
+ */
+export const traverse = <T = any>(root: Item, cb: (item: Item, level: number) => T | void): T | undefined => {
+  const t = (item: Item, level: number): T | undefined => {
+    if (item.type !== 'root') {
+      const value = cb(item, level);
+      if (value != null) {
+        return value;
+      }
+    }
+
+    for (const child of item.children) {
+      const value = t(child, level + 1);
+      if (value != null) {
+        return value;
+      }
+    }
+
+    return undefined;
+  };
+
+  return t(root, root.type === 'root' ? -1 : 0);
+};
+
+export const getListItemContent = (state: EditorState, item: Item): string => {
+  return state.doc.sliceString(item.contentRange.from, item.contentRange.to);
+};
+
+export const listItemToString = (item: Item, level = 0) => {
+  const indent = '  '.repeat(level);
+  const data = {
+    i: item.index,
+    n: item.nextSibling?.index ?? '∅',
+    p: item.prevSibling?.index ?? '∅',
+    level: item.level,
+    node: format([item.node.from, item.node.to]),
+    line: format([item.lineRange.from, item.lineRange.to]),
+    content: format([item.contentRange.from, item.contentRange.to]),
+  };
+
+  return `${indent}${item.type[0].toUpperCase()}(${Object.entries(data)
+    .map(([k, v]) => `${k}=${v}`)
+    .join(', ')})`;
+};
+
+const format = (value: any) =>
+  JSON.stringify(value, (key: string, value: any) => {
+    if (typeof value === 'number') {
+      return value.toString().padStart(3, ' ');
+    }
+    return value;
+  }).replaceAll('"', '');
+
+export const treeFacet = Facet.define<Tree, Tree>({
+  combine: (values) => values[0],
+});
+
+export type TreeOptions = {};
+
+/**
+ * Creates a shadow tree of `ListItem` nodes whenever the document changes.
+ * This adds overhead relative to the markdown AST, but allows for efficient traversal of the list items.
+ * NOTE: Requires markdown parser to be enabled.
+ */
+export const outlinerTree = (_options: TreeOptions = {}): Extension => {
+  const buildTree = (state: EditorState): Tree => {
+    let tree: Tree | undefined;
+    let parent: Item | undefined;
+    let current: Item | undefined;
+    let prev: Item | undefined;
+    let level = -1;
+    let index = -1;
+
+    // Array to track previous siblings at each level.
+    const prevSiblings: (Item | undefined)[] = [];
+
+    syntaxTree(state).iterate({
+      enter: (node) => {
+        switch (node.name) {
+          case 'Document': {
+            tree = new Tree(node.node);
+            current = tree;
+            break;
+          }
+          case 'BulletList': {
+            invariant(current);
+            parent = current;
+            if (current) {
+              current.lineRange.to = current.node.from;
+            }
+            prevSiblings[++level] = undefined;
+            break;
+          }
+          case 'ListItem': {
+            invariant(parent);
+
+            // Include all content up to the next sibling or the end of the document.
+            const nextSibling = node.node.nextSibling ?? node.node.parent?.nextSibling;
+            const docRange: Range = {
+              from: state.doc.lineAt(node.from).from,
+              to: nextSibling ? nextSibling.from - 1 : state.doc.length,
+            };
+
+            current = {
+              type: 'unknown',
+              index: ++index,
+              level,
+              node: node.node,
+              lineRange: docRange,
+              contentRange: { ...docRange },
+              parent,
+              prevSibling: prevSiblings[level],
+              children: [],
+            };
+
+            // Update sibling refs.
+            if (current.prevSibling) {
+              current.prevSibling.nextSibling = current;
+            }
+
+            // Update previous siblings array at current level.
+            prevSiblings[level] = current;
+
+            // Update previous item (not sibling).
+            if (prev) {
+              prev.lineRange.to = prev.contentRange.to = current.lineRange.from - 1;
+            }
+            prev = current;
+
+            // Update parent.
+            parent.children.push(current);
+            if (parent.lineRange.to === parent.node.from) {
+              parent.lineRange.to = parent.contentRange.to = current.lineRange.from - 1;
+            }
+
+            break;
+          }
+          case 'ListMark': {
+            invariant(current);
+            current.type = 'bullet';
+            current.contentRange.from = node.from + '- '.length;
+            break;
+          }
+          case 'Task': {
+            invariant(current);
+            current.type = 'task';
+            break;
+          }
+          case 'TaskMarker': {
+            invariant(current);
+            current.contentRange.from = node.from + '[ ] '.length;
+            break;
+          }
+        }
+      },
+      leave: (node) => {
+        if (node.name === 'BulletList') {
+          invariant(parent);
+          prevSiblings[level--] = undefined;
+          parent = parent.parent;
+        }
+      },
+    });
+
+    invariant(tree);
+    return tree;
+  };
+
+  return [
+    StateField.define<Tree | undefined>({
+      create: (state) => {
+        return buildTree(state);
+      },
+      update: (value: Tree | undefined, tr: Transaction) => {
+        if (!tr.docChanged) {
+          return value;
+        }
+
+        return buildTree(tr.state);
+      },
+      provide: (field) => treeFacet.from(field),
+    }),
+  ];
+};

package/src/extensions/preview/index.ts

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

package/src/extensions/preview/preview.ts

@@ -0,0 +1,193 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { syntaxTree } from '@codemirror/language';
+import { type EditorState, type Extension, RangeSetBuilder, StateField } from '@codemirror/state';
+import { Decoration, type DecorationSet, EditorView, WidgetType } from '@codemirror/view';
+import { type SyntaxNode } from '@lezer/common';
+
+export type PreviewBlock = {
+  link: PreviewLinkRef;
+  el: HTMLElement;
+};
+
+export type PreviewLinkRef = {
+  suggest?: boolean;
+  block?: boolean;
+  label: string;
+  ref: string;
+};
+
+export type PreviewLinkTarget = {
+  label: string;
+  text?: string;
+  object?: any;
+};
+
+export type PreviewOptions = {
+  addBlockContainer?: (block: PreviewBlock) => void;
+  removeBlockContainer?: (block: PreviewBlock) => void;
+};
+
+/**
+ * Create preview decorations.
+ */
+export const preview = (options: PreviewOptions = {}): Extension => {
+  return [
+    // NOTE: Atomic block decorations must be created from a state field, now a widget, otherwise it results in the following error:
+    // "Block decorations may not be specified via plugins".
+    StateField.define<DecorationSet>({
+      create: (state) => buildDecorations(state, options),
+      update: (decorations, tr) => {
+        if (tr.docChanged) {
+          return buildDecorations(tr.state, options);
+        }
+
+        return decorations.map(tr.changes);
+      },
+      provide: (field) => [
+        EditorView.decorations.from(field),
+        EditorView.atomicRanges.of((view) => view.state.field(field)),
+      ],
+    }),
+  ];
+};
+
+/**
+ * Echo references are represented as markdown reference links.
+ * https://www.markdownguide.org/basic-syntax/#reference-style-links
+ */
+const buildDecorations = (state: EditorState, options: PreviewOptions): DecorationSet => {
+  const builder = new RangeSetBuilder<Decoration>();
+
+  syntaxTree(state).iterate({
+    enter: (node) => {
+      switch (node.name) {
+        //
+        // Inline widget.
+        // [Label](dxn:echo:123)
+        //
+        case 'Link': {
+          const link = getLinkRef(state, node.node);
+          if (link) {
+            builder.add(
+              node.from,
+              node.to,
+              Decoration.replace({
+                widget: new PreviewInlineWidget(options, link),
+                side: 1,
+              }),
+            );
+          }
+          return false;
+        }
+
+        //
+        // Block widget (transclusion).
+        // ![Label](dxn:echo:123)
+        //
+        case 'Image': {
+          if (options.addBlockContainer && options.removeBlockContainer) {
+            const link = getLinkRef(state, node.node);
+            if (link) {
+              builder.add(
+                node.from,
+                node.to,
+                Decoration.replace({
+                  block: true,
+                  widget: new PreviewBlockWidget(options, link),
+                }),
+              );
+            }
+          }
+          return false;
+        }
+      }
+    },
+  });
+
+  return builder.finish();
+};
+
+/**
+ * Link references.
+ *  [Label](dxn:echo:123) Inline reference
+ * ![Label](dxn:echo:123) Block reference
+ */
+export const getLinkRef = (state: EditorState, node: SyntaxNode): PreviewLinkRef | undefined => {
+  const mark = node.getChildren('LinkMark');
+  const urlNode = node.getChild('URL');
+  if (mark && urlNode) {
+    const url = state.sliceDoc(urlNode.from, urlNode.to);
+    if (url.startsWith('dxn:')) {
+      const label = state.sliceDoc(mark[0].to, mark[1].from);
+      return {
+        block: state.sliceDoc(mark[0].from, mark[0].from + 1) === '!',
+        label,
+        ref: url,
+      };
+    }
+  }
+};
+
+/**
+ * Inline widget.
+ *  [Label](dxn:echo:123)
+ */
+class PreviewInlineWidget extends WidgetType {
+  constructor(
+    readonly _options: PreviewOptions,
+    readonly _link: PreviewLinkRef,
+  ) {
+    super();
+  }
+
+  // override ignoreEvent() {
+  //   return false;
+  // }
+
+  override eq(other: this) {
+    return this._link.ref === other._link.ref && this._link.label === other._link.label;
+  }
+
+  override toDOM(_view: EditorView) {
+    const root = document.createElement('dx-anchor');
+    root.classList.add('dx-tag--anchor');
+    root.textContent = this._link.label;
+    root.setAttribute('refId', this._link.ref);
+    return root;
+  }
+}
+
+/**
+ * Block widget (e.g., for surfaces).
+ * ![Label][dxn:echo:123]
+ */
+class PreviewBlockWidget extends WidgetType {
+  constructor(
+    readonly _options: PreviewOptions,
+    readonly _link: PreviewLinkRef,
+  ) {
+    super();
+  }
+
+  // override ignoreEvent() {
+  //   return true;
+  // }
+
+  override eq(other: this) {
+    return this._link.ref === other._link.ref;
+  }
+
+  override toDOM(_view: EditorView) {
+    const root = document.createElement('div');
+    root.classList.add('cm-preview-block', 'density-fine');
+    this._options.addBlockContainer?.({ link: this._link, el: root });
+    return root;
+  }
+
+  override destroy(root: HTMLDivElement) {
+    this._options.removeBlockContainer?.({ link: this._link, el: root });
+  }
+}