@dxos/react-ui-editor 0.8.3 → 0.8.4-main.1da679c

package/src/extensions/tags/streamer.ts

@@ -0,0 +1,244 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Extension, StateEffect, StateField } from '@codemirror/state';
+import { Decoration, type DecorationSet, EditorView, ViewPlugin, type ViewUpdate, WidgetType } from '@codemirror/view';
+
+import { isNotFalsy } from '@dxos/util';
+
+import { Domino } from '../../util';
+
+const BLINK_RATE = 2_000;
+
+export type StreamerOptions = {
+  cursor?: boolean;
+  // When true, uses defaults. When object, allows configuring removal delay.
+  fadeIn?: boolean | { removalDelay?: number };
+};
+
+/**
+ * Extension that adds a blinking cursor widget at the end of the document.
+ */
+export const streamer = (options: StreamerOptions = {}): Extension => {
+  return [
+    options.cursor && cursor(),
+    options.fadeIn && fadeIn(typeof options.fadeIn === 'object' ? options.fadeIn : {}),
+  ].filter(isNotFalsy);
+};
+
+/**
+ * State field to manage the cursor widget decoration.
+ */
+const cursor = (): Extension => {
+  const hideCursor = StateEffect.define();
+
+  // State field to track if cursor should be shown.
+  const showCursor = StateField.define<boolean>({
+    create: () => true,
+    update: (value, tr) => {
+      for (const effect of tr.effects) {
+        if (effect.is(hideCursor)) {
+          return false;
+        }
+      }
+      if (tr.docChanged) {
+        return true;
+      }
+
+      return value;
+    },
+  });
+
+  // View plugin to manage timer and dispatch effects.
+  const timerPlugin = ViewPlugin.fromClass(
+    class {
+      timer: any;
+
+      constructor(private view: EditorView) {}
+
+      update(update: ViewUpdate) {
+        if (update.docChanged) {
+          clearTimeout(this.timer);
+          this.timer = setTimeout(() => {
+            this.view.dispatch({
+              effects: hideCursor.of(null),
+            });
+          }, BLINK_RATE);
+        }
+      }
+
+      destroy() {
+        clearTimeout(this.timer);
+      }
+    },
+  );
+
+  // Decoration field that uses the showCursor state.
+  const cursorDecoration = StateField.define<DecorationSet>({
+    create: () => Decoration.none,
+    update: (_decorations, tr) => {
+      const show = tr.state.field(showCursor);
+      if (!show) {
+        return Decoration.none;
+      }
+
+      // Always place cursor at the end of the document.
+      const endPos = tr.state.doc.length;
+      return Decoration.set([
+        Decoration.widget({
+          widget: new CursorWidget(),
+          side: 1, // Place after the position.
+        }).range(endPos),
+      ]);
+    },
+    provide: (f) => EditorView.decorations.from(f),
+  });
+
+  return [showCursor, timerPlugin, cursorDecoration];
+};
+
+/**
+ * Widget class for the cursor at the end of the document.
+ * Half
+ */
+class CursorWidget extends WidgetType {
+  toDOM() {
+    return Domino.of('span')
+      .style({ opacity: '0.8' })
+      .child(Domino.of('span').text('\u258F').style({ animation: 'blink 2s infinite' }))
+      .build();
+  }
+}
+
+/**
+ * State field to detect and decorate appended text with a fade-in effect.
+ * Also schedules removal of the last appended decoration after a delay.
+ */
+const fadeIn = (options: { removalDelay?: number } = {}): Extension => {
+  const FADE_IN_DURATION = 1_000; // ms.
+  const DEFAULT_REMOVAL_DELAY = 5_000; // ms.
+  const removalDelay = options.removalDelay ?? DEFAULT_REMOVAL_DELAY;
+
+  // Effect to remove a specific decoration by range.
+  const removeDecoration = StateEffect.define<{ from: number; to: number }>();
+
+  // Decoration field that adds fade-in marks for appended content and responds to removal effects.
+  const fadeField = StateField.define<DecorationSet>({
+    create: () => Decoration.none,
+    update: (decorations, tr) => {
+      let next = decorations;
+
+      // Apply removals first, if any.
+      for (const effect of tr.effects) {
+        if (effect.is(removeDecoration)) {
+          const target = effect.value;
+          next = next.update({
+            filter: (from, to) => !(from === target.from && to === target.to),
+          });
+        }
+      }
+
+      if (!tr.docChanged) {
+        return next;
+      }
+
+      // Reset decorations if the entire content was replaced.
+      let isReset = tr.state.doc.length === 0;
+      if (!isReset) {
+        tr.changes.iterChanges((fromA, toA) => {
+          if (fromA === 0 && toA === tr.startState.doc.length) {
+            isReset = true;
+          }
+        });
+      }
+      if (isReset) {
+        return Decoration.none;
+      }
+
+      // Add fade-in decorations for appended content at the end only.
+      const add: any[] = [];
+      tr.changes.iterChanges((fromA, toA, fromB, toB, inserted) => {
+        // Don't fade in initial content.
+        if (fromB === 0 && toB === inserted.length) {
+          return;
+        }
+        // At-the-end append.
+        if (toA === tr.startState.doc.length && inserted.length > 0) {
+          add.push(Decoration.mark({ class: 'cm-fade-in' }).range(fromB, toB));
+        }
+      });
+
+      return next.update({ add });
+    },
+    provide: (f) => EditorView.decorations.from(f),
+  });
+
+  // View plugin that tracks appended ranges and schedules their removal.
+  const timerPlugin = ViewPlugin.fromClass(
+    class {
+      // Map a simple key "from-to" to timer id.
+      _timers = new Map<string, any>();
+
+      constructor(private view: EditorView) {}
+
+      update(update: ViewUpdate) {
+        if (!update.docChanged) {
+          return;
+        }
+
+        update.changes.iterChanges((fromA, toA, fromB, toB, inserted) => {
+          // Only consider appends at the end.
+          if (toA !== update.startState.doc.length || inserted.length === 0) {
+            return;
+          }
+
+          const key = `${fromB}-${toB}`;
+          // Clear any prior timer for this exact range.
+          if (this._timers.has(key)) {
+            clearTimeout(this._timers.get(key));
+          }
+
+          const totalDelay = FADE_IN_DURATION + removalDelay;
+          const id = setTimeout(() => {
+            this.view.dispatch({ effects: removeDecoration.of({ from: fromB, to: toB }) });
+            this._timers.delete(key);
+          }, totalDelay);
+
+          this._timers.set(key, id);
+        });
+      }
+
+      destroy() {
+        for (const id of this._timers.values()) {
+          clearTimeout(id);
+        }
+        this._timers.clear();
+      }
+    },
+  );
+
+  return [
+    fadeField,
+    timerPlugin,
+    EditorView.theme({
+      '.cm-line > span': {
+        opacity: '0.8',
+      },
+      '.cm-fade-in': {
+        animation: 'fade-in 3s ease-out forwards',
+      },
+      '@keyframes fade-in': {
+        '0%': {
+          opacity: '0',
+        },
+        '80%': {
+          opacity: '1',
+        },
+        '100%': {
+          opacity: '0.8',
+        },
+      },
+    }),
+  ];
+};

package/src/extensions/tags/xml-tags.ts

@@ -0,0 +1,335 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { syntaxTree } from '@codemirror/language';
+import { type EditorState, type Extension, RangeSetBuilder, StateEffect, StateField } from '@codemirror/state';
+import { Decoration, type DecorationSet, EditorView, WidgetType } from '@codemirror/view';
+import { type ComponentType, type FC } from 'react';
+
+import { invariant } from '@dxos/invariant';
+import { log } from '@dxos/log';
+
+import { decorationSetToArray } from '../../util';
+
+import { nodeToJson } from './xml-util';
+
+export type StateDispatch<T> = T | ((state: T) => T);
+
+/**
+ * Manages widget state.
+ */
+export interface XmlWidgetStateManager {
+  updateWidget<T>(id: string, props: StateDispatch<T>): void;
+}
+
+export type XmlEventHandler<TEvent = any> = (event: TEvent) => void;
+
+/**
+ * Widget component.
+ */
+export type XmlWidgetProps<TContext = any, TProps = any> = TProps & {
+  _tag: string;
+  context: TContext;
+  onEvent?: XmlEventHandler;
+};
+
+/**
+ * Factory for creating widgets.
+ */
+export type XmlWidgetFactory = (props: XmlWidgetProps, onEvent?: XmlEventHandler) => WidgetType | null;
+
+/**
+ * Widget registry definition.
+ */
+export type XmlWidgetDef = {
+  block?: boolean;
+  /** Native widget. */
+  factory?: XmlWidgetFactory;
+  /** React widget. */
+  Component?: FC<XmlWidgetProps>;
+};
+
+export type XmlWidgetRegistry = Record<string, XmlWidgetDef>;
+
+/**
+ * Update context.
+ */
+export const xmlTagContextEffect = StateEffect.define<any>();
+
+/**
+ * Update widget.
+ */
+export const xmlTagUpdateEffect = StateEffect.define<{ id: string; value: any }>();
+
+/**
+ * Reset all state.
+ */
+export const xmlTagResetEffect = StateEffect.define();
+
+type WidgetDecorationSet = {
+  from: number;
+  decorations: DecorationSet;
+};
+
+type XmlWidgetStateMap = Record<string, any>;
+
+export type XmlWidgetState = {
+  id: string;
+  props: any;
+  root: HTMLElement;
+  Component: ComponentType<any>;
+};
+
+export interface XmlWidgetNotifier {
+  mounted(widget: XmlWidgetState): void;
+  unmounted(id: string): void;
+}
+
+export type XmlTagsOptions = {
+  registry?: XmlWidgetRegistry;
+  /**
+   * Called when a widget is mounted or unmounted.
+   */
+  setWidgets?: (widgets: XmlWidgetState[]) => void;
+};
+
+/**
+ * Extension that adds thread-related functionality including XML tag decorations.
+ */
+export const xmlTags = (options: XmlTagsOptions = {}): Extension => {
+  //
+  // Context state.
+  //
+  const contextState = StateField.define<any>({
+    create: () => undefined,
+    update: (value, tr) => {
+      for (const effect of tr.effects) {
+        if (effect.is(xmlTagContextEffect)) {
+          return effect.value;
+        }
+      }
+
+      return value;
+    },
+  });
+
+  //
+  // Active widgets.
+  //
+  const widgets = new Map<string, XmlWidgetState>();
+  const notifier = {
+    mounted: (widget: XmlWidgetState) => {
+      widgets.set(widget.id, widget);
+      options.setWidgets?.([...widgets.values()]);
+    },
+    unmounted: (id: string) => {
+      widgets.delete(id);
+      options.setWidgets?.([...widgets.values()]);
+    },
+  } satisfies XmlWidgetNotifier;
+
+  //
+  // Widget decorations.
+  //
+  const decorationsState = StateField.define<WidgetDecorationSet>({
+    create: (state) => {
+      return buildDecorations(
+        state,
+        0,
+        state.doc.length,
+        state.field(contextState),
+        state.field(widgetState),
+        options,
+        notifier,
+      );
+    },
+    update: ({ from, decorations }, tr) => {
+      for (const effect of tr.effects) {
+        if (effect.is(xmlTagResetEffect)) {
+          return { from: 0, decorations: Decoration.none };
+        }
+      }
+
+      if (tr.docChanged) {
+        const { state } = tr;
+
+        // Flag if the transaction has modified the head of the document.
+        // (i.e., any changes that touch before the current `from` position).
+        const reset = tr.changes.touchesRange(0, from);
+
+        // Since append-only, rebuild decorations from after the last widget.
+        const result = buildDecorations(
+          state,
+          reset ? 0 : from,
+          state.doc.length,
+          state.field(contextState),
+          state.field(widgetState),
+          options,
+          notifier,
+        );
+
+        // Merge with existing decorations.
+        return {
+          from: result.from,
+          decorations: decorations.update({ add: decorationSetToArray(result.decorations) }),
+        };
+      }
+
+      // No document changes: avoid mapping decorations through an empty ChangeSet,
+      // which can throw when the decoration set was created for a different base length.
+      // Simply return the existing decorations unchanged.
+      return { from, decorations };
+    },
+    provide: (field) => [
+      EditorView.decorations.from(field, (v) => v.decorations),
+      EditorView.atomicRanges.of((view) => view.state.field(field).decorations || Decoration.none),
+    ],
+  });
+
+  //
+  // Widget state management.
+  //
+  const widgetState = StateField.define<XmlWidgetStateMap>({
+    create: () => ({}),
+    update: (map, tr) => {
+      for (const effect of tr.effects) {
+        if (effect.is(xmlTagResetEffect)) {
+          return {};
+        }
+
+        if (effect.is(xmlTagUpdateEffect)) {
+          // Update accumulated widget props by id.
+          const { id, value } = effect.value;
+          const state = typeof value === 'function' ? value(map[id]) : value;
+
+          // Find and render widget.
+          const { decorations } = tr.state.field(decorationsState);
+          for (const range of decorationSetToArray(decorations)) {
+            const deco = range.value;
+            const widget = deco?.spec?.widget;
+            if (widget && widget instanceof PlaceholderWidget && widget.id === effect.value.id && widget.root) {
+              const props = { ...widget.props, ...state };
+              notifier.mounted({ id: widget.id, props, root: widget.root, Component: widget.Component });
+            }
+          }
+
+          return { ...map, [id]: state };
+        }
+      }
+
+      return map;
+    },
+  });
+
+  return [contextState, decorationsState, widgetState];
+};
+
+/**
+ * Creates widget decorations for XML tags in the document using the syntax tree.
+ */
+const buildDecorations = (
+  state: EditorState,
+  from: number,
+  to: number,
+  context: any,
+  widgetState: XmlWidgetStateMap,
+  options: XmlTagsOptions,
+  notifier: XmlWidgetNotifier,
+): WidgetDecorationSet => {
+  const builder = new RangeSetBuilder<Decoration>();
+  const tree = syntaxTree(state);
+  if (!tree || (tree.type.name === 'Program' && tree.length === 0)) {
+    return { from, decorations: Decoration.none };
+  }
+
+  tree.iterate({
+    from,
+    to,
+    enter: (node) => {
+      switch (node.type.name) {
+        // XML Element.
+        case 'Element': {
+          try {
+            if (options.registry) {
+              const props = nodeToJson(state, node.node);
+              if (props) {
+                const def = options.registry[props._tag];
+                if (def) {
+                  const { block, factory, Component } = def;
+                  const state = props.id ? widgetState[props.id] : undefined;
+                  const args = { context, ...props, ...state };
+                  const widget: WidgetType | undefined = factory
+                    ? factory(args)
+                    : Component
+                      ? props.id && new PlaceholderWidget(props.id, Component, args, notifier)
+                      : undefined;
+
+                  if (widget) {
+                    from = node.node.to;
+                    builder.add(
+                      node.node.from,
+                      node.node.to,
+                      Decoration.replace({
+                        widget,
+                        block,
+                        atomic: true,
+                        inclusive: true,
+                      }),
+                    );
+                  }
+                }
+              }
+            }
+          } catch (err) {
+            log.catch(err);
+          }
+
+          return false; // Don't descend into children.
+        }
+      }
+    },
+  });
+
+  return { from, decorations: builder.finish() };
+};
+
+/**
+ * Placeholder for React widgets.
+ */
+class PlaceholderWidget<TProps = {}> extends WidgetType {
+  private _root: HTMLElement | null = null;
+
+  constructor(
+    public readonly id: string,
+    public readonly Component: FC<TProps>,
+    public readonly props: TProps,
+    private readonly notifier: XmlWidgetNotifier,
+  ) {
+    super();
+    invariant(id);
+  }
+
+  get root() {
+    return this._root;
+  }
+
+  override eq(other: WidgetType): boolean {
+    return other instanceof PlaceholderWidget && this.id === other.id;
+  }
+
+  override ignoreEvent() {
+    return true;
+  }
+
+  override toDOM(_view: EditorView): HTMLElement {
+    this._root = document.createElement('span');
+    this.notifier.mounted({ id: this.id, props: this.props, root: this._root, Component: this.Component });
+    return this._root;
+  }
+
+  override destroy(_dom: HTMLElement): void {
+    this.notifier.unmounted(this.id);
+    this._root = null;
+  }
+}

package/src/extensions/tags/xml-util.ts

@@ -0,0 +1,94 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type EditorState } from '@codemirror/state';
+import { type SyntaxNode } from '@lezer/common';
+
+import { invariant } from '@dxos/invariant';
+
+export type Tag = Record<string, any> & {
+  _tag: string;
+};
+
+/**
+ * Parse XML Element.
+ */
+export const nodeToJson = (state: EditorState, node: SyntaxNode): Tag | undefined => {
+  invariant(node.type.name === 'Element', 'Node is not an Element');
+
+  // Find the opening tag.
+  const openTag = node.node.getChild('OpenTag') || node.node.getChild('SelfClosingTag');
+  if (openTag) {
+    // Extract tag name.
+    const tagName = openTag.getChild('TagName');
+    if (!tagName) {
+      return;
+    }
+
+    const tag: Tag = {
+      _tag: state.doc.sliceString(tagName.from, tagName.to),
+    };
+
+    // Extract attributes.
+    let attributeNode = openTag.getChild('Attribute');
+    while (attributeNode) {
+      const attrName = attributeNode.getChild('AttributeName');
+      const attrValue = attributeNode.getChild('AttributeValue');
+      if (attrName) {
+        const attr = state.doc.sliceString(attrName.from, attrName.to);
+
+        // Default for attributes without values.
+        let value: string | boolean = true;
+
+        if (attrValue) {
+          const rawValue = state.doc.sliceString(attrValue.from, attrValue.to);
+          // Remove quotes if present.
+          if (
+            (rawValue.startsWith('"') && rawValue.endsWith('"')) ||
+            (rawValue.startsWith("'") && rawValue.endsWith("'"))
+          ) {
+            value = rawValue.slice(1, -1);
+          } else {
+            value = rawValue;
+          }
+        }
+
+        tag[attr] = value;
+      }
+
+      // Get next sibling attribute.
+      attributeNode = attributeNode.nextSibling;
+    }
+
+    // Extract children for non-self-closing tags.
+    if (node.type.name === 'Element' && openTag.type.name !== 'SelfClosingTag') {
+      const children: any[] = [];
+      let child = node.node.firstChild;
+
+      while (child) {
+        // Skip the opening and closing tags.
+        if (child.type.name !== 'OpenTag' && child.type.name !== 'CloseTag') {
+          if (child.type.name === 'Text') {
+            const text = state.doc.sliceString(child.from, child.to).trim();
+            if (text) {
+              children.push(text);
+            }
+          } else if (child.type.name === 'Element') {
+            const data = nodeToJson(state, child);
+            if (data) {
+              children.push(data);
+            }
+          }
+        }
+        child = child.nextSibling;
+      }
+
+      if (children.length > 0) {
+        tag.children = children;
+      }
+    }
+
+    return tag;
+  }
+};

package/src/hooks/useTextEditor.ts

@@ -4,7 +4,7 @@
 
 import { EditorState, type EditorStateConfig, type Text } from '@codemirror/state';
 import { EditorView } from '@codemirror/view';
-import { useFocusableGroup, type TabsterTypes } from '@fluentui/react-tabster';
+import { type TabsterTypes, useFocusableGroup } from '@fluentui/react-tabster';
 import {
   type DependencyList,
   type KeyboardEventHandler,
@@ -17,9 +17,9 @@ import {
 } from 'react';
 
 import { log } from '@dxos/log';
-import { getProviderValue, isNotFalsy, type MaybeProvider } from '@dxos/util';
+import { type MaybeProvider, getProviderValue, isNotFalsy } from '@dxos/util';
 
-import { type EditorSelection, documentId, createEditorStateTransaction, editorInputMode } from '../extensions';
+import { type EditorSelection, createEditorStateTransaction, documentId, editorInputMode } from '../extensions';
 import { debugDispatcher } from '../util';
 
 let instanceCount = 0;
@@ -96,18 +96,6 @@ export const useTextEditor = (
           EditorView.exceptionSink.of((err) => {
             log.catch(err);
           }),
-          // TODO(burdon): Factor out debug inspector.
-          // ViewPlugin.fromClass(
-          //   class {
-          //     constructor(_view: EditorView) {
-          //       log('construct', { id });
-          //     }
-          //
-          //     destroy() {
-          //       log('destroy', { id });
-          //     }
-          //   },
-          // ),
         ].filter(isNotFalsy),
       });