@dxos/react-ui-editor 0.8.1-staging.9eaf14f → 0.8.2-main.10c050d

package/src/extensions/outliner/tree.ts

@@ -0,0 +1,315 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { syntaxTree } from '@codemirror/language';
+import { StateField, type Transaction, type Extension, type EditorState } 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 | void),
+    maybeCb?: (item: Item, level: number) => T | 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.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 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 2024 DXOS.org
+//
+
+export * from './preview';

package/src/extensions/preview/preview.ts

@@ -0,0 +1,271 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import '@dxos/lit-ui/dx-ref-tag.pcss';
+
+import { syntaxTree } from '@codemirror/language';
+import {
+  type EditorState,
+  type Extension,
+  type RangeSet,
+  RangeSetBuilder,
+  StateField,
+  type Transaction,
+} from '@codemirror/state';
+import { Decoration, type DecorationSet, EditorView, WidgetType } from '@codemirror/view';
+import { type SyntaxNode } from '@lezer/common';
+
+import { type RenderCallback } from '../../types';
+
+export type PreviewLinkRef = {
+  suggest?: boolean;
+  block?: boolean;
+  label: string;
+  ref: string;
+};
+
+export type PreviewLinkTarget = {
+  label: string;
+  text?: string;
+  object?: any;
+};
+
+export type PreviewAction =
+  | {
+      type: 'insert';
+      link: PreviewLinkRef;
+      target: PreviewLinkTarget;
+    }
+  | {
+      type: 'delete';
+      link: PreviewLinkRef;
+    };
+
+// TODO(burdon): Handle error.
+export type PreviewLookup = (link: PreviewLinkRef) => Promise<PreviewLinkTarget | null | undefined>;
+
+export type PreviewActionHandler = (action: PreviewAction) => void;
+
+export type PreviewRenderProps = {
+  readonly: boolean;
+  link: PreviewLinkRef;
+  onAction: PreviewActionHandler;
+  onLookup?: PreviewLookup;
+};
+
+export type PreviewOptions = {
+  renderBlock?: RenderCallback<PreviewRenderProps>;
+  onLookup?: PreviewLookup;
+};
+
+/**
+ * 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: (_: RangeSet<Decoration>, tr: Transaction) => buildDecorations(tr.state, options),
+      provide: (field) => [
+        EditorView.decorations.from(field),
+        EditorView.atomicRanges.of((view) => view.state.field(field)),
+      ],
+    }),
+
+    EditorView.theme({
+      '.cm-preview-block': {
+        marginLeft: '-1rem',
+        marginRight: '-1rem',
+        padding: '1rem',
+        borderRadius: '0.5rem',
+        background: 'var(--dx-modalSurface)',
+        border: '1px solid var(--dx-separator)',
+      },
+    }),
+  ];
+};
+
+/**
+ * Link references.
+ *
+ *  [Label][dxn:echo:123]    Inline reference
+ * ![Label][dxn:echo:123]    Block reference
+ * ![Label][?dxn:echo:123]   Suggestion
+ */
+const getLinkRef = (state: EditorState, node: SyntaxNode): PreviewLinkRef | undefined => {
+  const mark = node.getChild('LinkMark');
+  const label = node.getChild('LinkLabel');
+  if (mark && label) {
+    const ref = state.sliceDoc(label.from + 1, label.to - 1);
+    return {
+      suggest: ref.startsWith('?'),
+      block: state.sliceDoc(mark.from, mark.from + 1) === '!',
+      label: state.sliceDoc(mark.to, label.from - 1),
+      ref: ref.startsWith('?') ? ref.slice(1) : ref,
+    };
+  }
+};
+
+/**
+ * Echo references are represented as markdown reference links.
+ * https://www.markdownguide.org/basic-syntax/#reference-style-links
+ * [Label|block][dxn:echo:123]
+ * [Label|inline][dxn:echo:123]
+ */
+const buildDecorations = (state: EditorState, options: PreviewOptions) => {
+  const builder = new RangeSetBuilder<Decoration>();
+
+  syntaxTree(state).iterate({
+    enter: (node) => {
+      switch (node.name) {
+        //
+        // Decoration.
+        // [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),
+              }),
+            );
+          }
+          break;
+        }
+        //
+        // Block widget.
+        // ![Label][dxn:echo:123]
+        //
+        case 'Image': {
+          const link = getLinkRef(state, node.node);
+          if (options.renderBlock && link) {
+            builder.add(
+              node.from,
+              node.to,
+              Decoration.replace({
+                block: true,
+                // atomic: true,
+                widget: new PreviewBlockWidget(options, link),
+              }),
+            );
+          }
+          break;
+        }
+      }
+    },
+  });
+
+  return builder.finish();
+};
+
+/**
+ * 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): boolean {
+    return this._link.ref === other._link.ref && this._link.label === other._link.label;
+  }
+
+  override toDOM(view: EditorView): HTMLElement {
+    const root = document.createElement('dx-ref-tag');
+    root.textContent = this._link.label;
+    root.setAttribute('refId', this._link.ref);
+    return root;
+  }
+}
+
+/**
+ * Block widget.
+ * ![Label][dxn:echo:123]
+ */
+class PreviewBlockWidget extends WidgetType {
+  constructor(
+    readonly _options: PreviewOptions,
+    readonly _link: PreviewLinkRef,
+  ) {
+    super();
+  }
+
+  // override ignoreEvent() {
+  //   return true;
+  // }
+
+  override eq(other: this): boolean {
+    return this._link.ref === other._link.ref;
+  }
+
+  override toDOM(view: EditorView): HTMLDivElement {
+    const root = document.createElement('div');
+    root.classList.add('cm-preview-block');
+
+    // TODO(burdon): Inject handler.
+    const handleAction: PreviewActionHandler = (action) => {
+      const pos = view.posAtDOM(root);
+      const node = syntaxTree(view.state).resolve(pos + 1).node.parent;
+      if (!node) {
+        return;
+      }
+
+      const link = getLinkRef(view.state, node);
+      if (link?.ref !== action.link.ref) {
+        return;
+      }
+
+      switch (action.type) {
+        // TODO(burdon): Should we dispatch to the view or mutate the document? (i.e., handle externally?)
+        // Insert ref text.
+        case 'insert': {
+          view.dispatch({
+            changes: {
+              from: node.from,
+              to: node.to,
+              insert: action.target.text,
+            },
+          });
+          break;
+        }
+        // Remove ref.
+        case 'delete': {
+          view.dispatch({
+            changes: {
+              from: node.from,
+              to: node.to,
+            },
+          });
+          break;
+        }
+      }
+    };
+
+    this._options.renderBlock!(
+      root,
+      {
+        readonly: view.state.readOnly,
+        link: this._link,
+        onAction: handleAction,
+        onLookup: this._options.onLookup,
+      },
+      view,
+    );
+
+    return root;
+  }
+}

package/src/hooks/index.ts

@@ -2,5 +2,4 @@
 // Copyright 2023 DXOS.org
 //
 
-export * from './useActionHandler';
 export * from './useTextEditor';

package/src/hooks/useTextEditor.ts

@@ -2,7 +2,7 @@
 // Copyright 2024 DXOS.org
 //
 
-import { EditorState, type EditorStateConfig } from '@codemirror/state';
+import { EditorState, type EditorStateConfig, type Text } from '@codemirror/state';
 import { EditorView } from '@codemirror/view';
 import { useFocusableGroup, type TabsterTypes } from '@fluentui/react-tabster';
 import {
@@ -43,6 +43,7 @@ export type CursorInfo = {
 
 export type UseTextEditorProps = Pick<EditorStateConfig, 'extensions'> & {
   id?: string;
+  doc?: Text;
   initialValue?: string;
   className?: string;
   autoFocus?: boolean;
@@ -61,7 +62,7 @@ export const useTextEditor = (
   props: MaybeProvider<UseTextEditorProps> = {},
   deps: DependencyList = [],
 ): UseTextEditor => {
-  const { id, initialValue, extensions, autoFocus, scrollTo, selection, moveToEndOfLine, debug } =
+  const { id, doc, initialValue, extensions, autoFocus, scrollTo, selection, moveToEndOfLine, debug } =
     useMemo<UseTextEditorProps>(() => getProviderValue(props), deps ?? []);
 
   // NOTE: Increments by 2 in strict mode.
@@ -87,7 +88,7 @@ export const useTextEditor = (
 
       // https://codemirror.net/docs/ref/#state.EditorStateConfig
       const state = EditorState.create({
-        doc: initialValue,
+        doc: doc ?? initialValue,
         // selection: initialSelection,
         extensions: [
           id && documentId.of(id),