@dxos/ui-editor 0.0.0 → 0.8.4-main.03d5cd7b56

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

@@ -0,0 +1,123 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { xmlLanguage } from '@codemirror/lang-xml';
+import { type Extension, type Range } from '@codemirror/state';
+import { Decoration, type DecorationSet, EditorView, ViewPlugin, type ViewUpdate } from '@codemirror/view';
+
+export type XmlBlockDecorationOptions = {
+  /**
+   * Tag name to match (e.g. `'prompt'`).
+   */
+  tag: string;
+
+  /**
+   * Class added via `Decoration.line` to each line that intersects the element's content
+   * range. Use to style the bubble container (e.g. flex alignment, vertical margin).
+   */
+  lineClass?: string;
+
+  /**
+   * Class added via `Decoration.mark` covering the inner content (between the open and
+   * close tags). Use to style the bubble surface (background, padding, rounding).
+   */
+  contentClass?: string;
+
+  /**
+   * When true, the open and close tag delimiters are hidden via `Decoration.replace`
+   * with no widget, so the rendered text is the inner content only.
+   */
+  hideTags?: boolean;
+};
+
+/**
+ * Walks the doc with the Lezer XML parser and decorates `<tag>…</tag>` elements without
+ * replacing them with a widget — the source text remains in the document and can still
+ * be matched by other extensions (e.g. `xmlFormatting`). Use this for "bubble"-style
+ * styling of XML blocks (chat prompts, callouts, etc.) where the inner content should
+ * stay editable/copyable rather than living inside a CodeMirror widget.
+ */
+export const xmlBlockDecoration = ({
+  tag,
+  lineClass,
+  contentClass,
+  hideTags,
+}: XmlBlockDecorationOptions): Extension => {
+  const lineDecoration = lineClass ? Decoration.line({ class: lineClass }) : undefined;
+  const contentDecoration = contentClass ? Decoration.mark({ class: contentClass }) : undefined;
+  const hideDecoration = hideTags ? Decoration.replace({}) : undefined;
+
+  const buildDecorations = (view: EditorView): DecorationSet => {
+    const text = view.state.sliceDoc(0, view.state.doc.length);
+    if (!text.includes(`<${tag}`)) {
+      return Decoration.none;
+    }
+
+    const tree = xmlLanguage.parser.parse(text);
+    const ranges: Range<Decoration>[] = [];
+    tree.iterate({
+      enter: (node) => {
+        if (node.type.name !== 'Element') {
+          return;
+        }
+        const openTag = node.node.getChild('OpenTag');
+        const closeTag = node.node.getChild('CloseTag') ?? node.node.getChild('MismatchedCloseTag');
+        const tagNameNode = openTag?.getChild('TagName');
+        if (!openTag || !tagNameNode) {
+          return;
+        }
+        if (text.slice(tagNameNode.from, tagNameNode.to) !== tag) {
+          return;
+        }
+
+        const contentFrom = openTag.to;
+        const contentTo = closeTag?.from ?? node.node.to;
+
+        if (hideDecoration) {
+          ranges.push(hideDecoration.range(openTag.from, openTag.to));
+          if (closeTag) {
+            ranges.push(hideDecoration.range(closeTag.from, closeTag.to));
+          }
+        }
+
+        if (contentDecoration && contentFrom < contentTo) {
+          ranges.push(contentDecoration.range(contentFrom, contentTo));
+        }
+
+        if (lineDecoration && contentFrom <= view.state.doc.length) {
+          // Apply line decoration to every line that intersects the content range.
+          let pos = contentFrom;
+          while (pos <= contentTo && pos <= view.state.doc.length) {
+            const line = view.state.doc.lineAt(pos);
+            ranges.push(lineDecoration.range(line.from));
+            if (line.to >= contentTo) {
+              break;
+            }
+            pos = line.to + 1;
+          }
+        }
+      },
+    });
+    return Decoration.set(ranges, true);
+  };
+
+  return ViewPlugin.fromClass(
+    class {
+      decorations: DecorationSet;
+
+      constructor(view: EditorView) {
+        this.decorations = buildDecorations(view);
+      }
+
+      update(update: ViewUpdate) {
+        if (update.docChanged) {
+          this.decorations = buildDecorations(update.view);
+        }
+      }
+    },
+    {
+      decorations: (instance) => instance.decorations,
+    },
+  );
+};

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

@@ -0,0 +1,125 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { xmlLanguage } from '@codemirror/lang-xml';
+import { type Extension, type Range } from '@codemirror/state';
+import { Decoration, type DecorationSet, EditorView, ViewPlugin, type ViewUpdate } from '@codemirror/view';
+
+/**
+ * Lezer XML node names that represent the angle-bracket delimited portions of an element.
+ */
+const XML_TAG_NODES = new Set(['OpenTag', 'CloseTag', 'SelfClosingTag', 'MismatchedCloseTag']);
+
+const xmlElementMark = Decoration.mark({ class: 'cm-xml-element' });
+const xmlTagMark = Decoration.mark({ class: 'cm-xml-tag' });
+const xmlContentMark = Decoration.mark({ class: 'cm-xml-content' });
+
+export type XmlFormattingOptions = {
+  /**
+   * Tag names whose elements should NOT receive xmlFormatting decorations. Use to
+   * opt-out tags rendered by another extension (e.g. `xmlBlockDecoration` for `<prompt>`)
+   * so the two don't double-wrap the same content with stacked styling.
+   *
+   * Skipping is recursive: descendants of a skipped element are also untouched, so a
+   * `<foo>` inside a skipped `<prompt>` still appears literally without xmlFormatting
+   * styling.
+   */
+  skip?: string[];
+};
+
+/**
+ * Mark decoration extension that highlights XML tag delimiters
+ * (e.g., `<tag>`, `</tag>`, `<tag attr="x"/>`) with the `cm-xml-tag` class.
+ *
+ * Uses `@codemirror/lang-xml`'s Lezer parser standalone — only to compute
+ * decoration ranges — without changing the editor's primary language. This
+ * keeps the document plain text while still handling nesting and attributes
+ * correctly.
+ */
+export const xmlFormatting = ({ skip }: XmlFormattingOptions = {}): Extension => {
+  const skipSet = skip && skip.length > 0 ? new Set(skip) : undefined;
+
+  const buildDecorations = (view: EditorView): DecorationSet => {
+    const text = view.state.sliceDoc(0, view.state.doc.length);
+    if (!text.includes('<')) {
+      return Decoration.none;
+    }
+
+    const tagNameAt = (node: { from: number; to: number }) => text.slice(node.from, node.to);
+
+    const tree = xmlLanguage.parser.parse(text);
+    const ranges: Range<Decoration>[] = [];
+    tree.iterate({
+      enter: (node) => {
+        const name = node.type.name;
+        if (name === 'SelfClosingTag' && node.from < node.to) {
+          if (skipSet) {
+            const tagNameNode = node.node.getChild('TagName');
+            if (tagNameNode && skipSet.has(tagNameAt(tagNameNode))) {
+              return false;
+            }
+          }
+          // Self-closing tag is its own outer block and tag delimiter.
+          ranges.push(xmlElementMark.range(node.from, node.to));
+          ranges.push(xmlTagMark.range(node.from, node.to));
+          return;
+        }
+        if (XML_TAG_NODES.has(name) && node.from < node.to) {
+          ranges.push(xmlTagMark.range(node.from, node.to));
+          return;
+        }
+        if (name === 'Element' && node.from < node.to) {
+          const openTag = node.node.getChild('OpenTag');
+          if (openTag && skipSet) {
+            const tagNameNode = openTag.getChild('TagName');
+            if (tagNameNode && skipSet.has(tagNameAt(tagNameNode))) {
+              // Skip this element AND its descendants — another extension owns rendering.
+              return false;
+            }
+          }
+          const closeTag = node.node.getChild('CloseTag') ?? node.node.getChild('MismatchedCloseTag');
+          ranges.push(xmlElementMark.range(node.from, node.to));
+          if (openTag && closeTag && openTag.to < closeTag.from) {
+            ranges.push(xmlContentMark.range(openTag.to, closeTag.from));
+          }
+        }
+      },
+    });
+    return Decoration.set(ranges, true);
+  };
+
+  return [
+    ViewPlugin.fromClass(
+      class {
+        decorations: DecorationSet;
+
+        constructor(view: EditorView) {
+          this.decorations = buildDecorations(view);
+        }
+
+        update(update: ViewUpdate) {
+          if (update.docChanged) {
+            this.decorations = buildDecorations(update.view);
+          }
+        }
+      },
+      {
+        decorations: (instance) => instance.decorations,
+      },
+    ),
+
+    EditorView.baseTheme({
+      '.cm-xml-element': {
+        backgroundColor: 'var(--color-active-surface)',
+        borderRadius: '0.25rem',
+        padding: '0.25rem',
+      },
+      '.cm-xml-tag': {
+        color: 'var(--color-blue-500)',
+        fontFamily: 'var(--font-mono)',
+      },
+      '.cm-xml-content': {},
+    }),
+  ];
+};

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

@@ -13,16 +13,15 @@ import {
   WidgetType,
   keymap,
 } from '@codemirror/view';
-// TODO(burdon): Factor out agnostic types (React/solid).
 import { type FunctionComponent } from 'react';
 
 import { invariant } from '@dxos/invariant';
 import { log } from '@dxos/log';
+import { Domino } from '@dxos/ui';
 
 import { type Range } from '../../types';
 import { decorationSetToArray } from '../../util';
-import { scrollToLineEffect } from '../scrolling';
-
+import { scrollerLineEffect } from '../scroller';
 import { nodeToJson } from './xml-util';
 
 /**
@@ -54,8 +53,9 @@ export type XmlEventHandler<TEvent = any> = (event: TEvent) => void;
  */
 export type XmlWidgetProps<TProps = any, TContext = any> = TProps & {
   _tag: string;
+  range: { from: number; to: number };
+  children?: any[];
   context?: TContext;
-  range?: { from: number; to: number };
   view?: EditorView;
   onEvent?: XmlEventHandler;
 };
@@ -63,19 +63,40 @@ export type XmlWidgetProps<TProps = any, TContext = any> = TProps & {
 /**
  * Factory for creating widgets.
  */
-export type XmlWidgetFactory = (props: XmlWidgetProps, onEvent?: XmlEventHandler) => WidgetType | null;
+export type XmlWidgetFactory = (props: XmlWidgetProps) => WidgetType | null;
 
 /**
  * Widget registry definition.
+ * NOTE: Widgets should NOT use top/bottom margins (it causes unstable measurements while scrolling which leads to jumps).
+ * If required, use encapsulated divs with padding instead.
  */
 export type XmlWidgetDef = {
-  /** Block widget. */
+  /**
+   * Block widget.
+   */
   block?: boolean;
 
-  /** Native widget (rendered inline). */
+  /**
+   * When true, the opening tag is flushed immediately and inner content streams character-by-character.
+   */
+  streaming?: boolean;
+
+  /**
+   * Debug only.
+   */
+  debug?: boolean;
+
+  /**
+   * Native widget (rendered inline).
+   */
   factory?: XmlWidgetFactory;
 
-  /** React/Solid widget (rendered in portals outside of the editor). */
+  /**
+   * React/Solid widget (rendered in portals outside of the editor).
+   * Prefer an `id="..."` attribute on the tag so `updateWidget` can target the instance; if omitted,
+   * an id is derived from the tag’s document range (non-streaming) or opening position (streaming).
+   * Streaming tags use `cm-xml-<from>` so the same portal id is kept when the closing tag arrives.
+   */
   Component?: FunctionComponent<XmlWidgetProps>;
 };
 
@@ -86,6 +107,13 @@ export const getXmlTextChild = (children: any[]): string | null => {
   return typeof child === 'string' ? child : null;
 };
 
+/** Stable id for portaled React/Solid widgets; explicit `id` on the tag wins for `updateWidget`. */
+const xmlWidgetId = (explicit: unknown, fallback: string): string =>
+  typeof explicit === 'string' && explicit.length > 0 ? explicit : fallback;
+
+/** Escapes a string for safe embedding in RegExp source (tag names from the registry). */
+const escapeRegExpSource = (value: string) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
 /**
  * Update context.
  */
@@ -103,6 +131,8 @@ export const xmlTagUpdateEffect = StateEffect.define<{ id: string; value: any }>
 
 type WidgetDecorationSet = {
   from: number;
+  /** Start position of an active unclosed streaming tag (for rebuild range). */
+  streamingFrom?: number;
   decorations: DecorationSet;
 };
 
@@ -164,11 +194,11 @@ export type XmlTagsOptions = {
   /** Tag registry. */
   registry?: XmlWidgetRegistry;
 
+  /** Tags to bookmark for navigation. */
+  bookmarks?: string[];
+
   /** Called when widgets are mounted or unmounted. */
   setWidgets?: (widgets: XmlWidgetState[]) => void;
-
-  /** Tags to bookmark. */
-  bookmarks?: string[];
 };
 
 /**
@@ -184,6 +214,7 @@ export type XmlTagsOptions = {
 export const xmlTags = ({ registry, setWidgets, bookmarks }: XmlTagsOptions = {}): Extension => {
   const notifier = createWidgetMap(setWidgets);
   const widgetDecorationsField = createWidgetDecorationsField(registry, notifier);
+
   return [
     widgetContextStateField,
     widgetStateMapStateField,
@@ -268,7 +299,7 @@ const createNavigationEffectPlugin = (
           const line = view.state.doc.lineAt(widget?.from ?? 0);
           view.dispatch({
             selection: { anchor: line.from, head: line.from },
-            effects: scrollToLineEffect.of({ line: line.number, options: { offset: -16 } }),
+            effects: scrollerLineEffect.of({ line: line.number - 1, offset: -16 }),
           });
 
           continue;
@@ -294,13 +325,13 @@ const createNavigationEffectPlugin = (
             const line = view.state.doc.lineAt(widget?.from);
             view.dispatch({
               selection: { anchor: line.to, head: line.to },
-              effects: scrollToLineEffect.of({ line: line.number, options: { offset: -16 } }),
+              effects: scrollerLineEffect.of({ line: line.number - 1, offset: -16 }),
             });
           } else {
             const line = view.state.doc.lineAt(view.state.doc.length);
             view.dispatch({
               selection: { anchor: line.to, head: line.to },
-              effects: scrollToLineEffect.of({ line: line.number, options: { position: 'end' } }),
+              effects: scrollerLineEffect.of({ line: line.number - 1, position: 'end' }),
             });
           }
 
@@ -355,10 +386,13 @@ const createWidgetDecorationsField = (registry: XmlWidgetRegistry = {}, notifier
     create: (state) => {
       return buildDecorations(state, { from: 0, to: state.doc.length }, registry, notifier);
     },
-    update: ({ from, decorations }, tr) => {
+    update: ({ from, streamingFrom, decorations }, tr) => {
       // Check for reset effect.
       for (const effect of tr.effects) {
         if (effect.is(xmlTagResetEffect)) {
+          if (tr.docChanged) {
+            return buildDecorations(tr.state, { from: 0, to: tr.state.doc.length }, registry, notifier);
+          }
           return { from: 0, decorations: Decoration.none };
         }
       }
@@ -372,16 +406,22 @@ const createWidgetDecorationsField = (registry: XmlWidgetRegistry = {}, notifier
           // Full rebuild from start.
           return buildDecorations(state, { from: 0, to: state.doc.length }, registry, notifier);
         } else {
-          // Append-only: rebuild decorations from after the last widget and merge with existing decorations.
-          const result = buildDecorations(state, { from, to: state.doc.length }, registry, notifier);
+          // Rebuild from the streaming tag start (if active) so the tree walk can detect completion.
+          const rebuildFrom = streamingFrom ?? from;
+          const result = buildDecorations(state, { from: rebuildFrom, to: state.doc.length }, registry, notifier);
           return {
             from: result.from,
-            decorations: decorations.update({ add: decorationSetToArray(result.decorations) }),
+            streamingFrom: result.streamingFrom,
+            decorations: decorations.update({
+              // Remove old streaming decorations — they are rebuilt each tick.
+              filter: (_f, _t, deco) => !deco.spec.streaming,
+              add: decorationSetToArray(result.decorations),
+            }),
           };
         }
       }
 
-      return { from, decorations };
+      return { from, streamingFrom, decorations };
     },
     provide: (field) => [
       EditorView.decorations.from(field, (v) => v.decorations),
@@ -391,6 +431,7 @@ const createWidgetDecorationsField = (registry: XmlWidgetRegistry = {}, notifier
 
 /**
  * Creates widget decorations for XML tags in the document using the syntax tree.
+ * After the tree walk, scans for unclosed streaming tags and creates provisional decorations.
  */
 const buildDecorations = (
   state: EditorState,
@@ -408,6 +449,8 @@ const buildDecorations = (
   }
 
   let last = range.from;
+  let streamingFrom: number | undefined;
+
   tree.iterate({
     from: range.from,
     to: range.to,
@@ -420,17 +463,32 @@ const buildDecorations = (
             if (args) {
               const def = registry[args._tag];
               if (def) {
+                // Skip unclosed streaming elements — the unclosed tag scan handles them.
+                if (def.streaming && !node.node.getChild('CloseTag')) {
+                  return false;
+                }
+
                 // NOTE: The widget state may already have been updated before the widget is mounted.
                 const { block, factory, Component } = def;
-                const widgetState = args.id ? widgetStateMap[args.id] : undefined;
                 const nodeRange = { from: node.node.from, to: node.node.to };
-                const props = { context, range: nodeRange, ...args, ...widgetState } satisfies XmlWidgetProps;
+                const widgetId = xmlWidgetId(
+                  args.id,
+                  def.streaming ? `cm-xml-${nodeRange.from}` : `cm-xml-${nodeRange.from}-${nodeRange.to}`,
+                );
+                const widgetState = widgetStateMap[widgetId];
+                const props = {
+                  id: widgetId,
+                  range: nodeRange,
+                  context,
+                  ...args,
+                  ...widgetState,
+                } satisfies XmlWidgetProps;
 
                 // Create widget.
                 const widget: WidgetType | undefined = factory
-                  ? factory(props)
+                  ? (factory(props) ?? undefined)
                   : Component
-                    ? args.id && new PlaceholderWidget(args.id, Component, props, notifier)
+                    ? new PlaceholderWidget(widgetId, Component, props, notifier)
                     : undefined;
 
                 // Add decoration.
@@ -463,30 +521,112 @@ const buildDecorations = (
     },
   });
 
-  return { from: last, decorations: builder.finish() };
+  // Scan for unclosed streaming tags at the document tail.
+  const streamingTagNames = Object.entries(registry)
+    .filter(([, def]) => def.streaming)
+    .map(([name]) => name)
+    // Longest names first so `react-widget` wins over `react` in alternation.
+    .sort((a, b) => b.length - a.length);
+
+  if (streamingTagNames.length > 0) {
+    const tailText = state.sliceDoc(range.from, range.to);
+    const streamingPattern = streamingTagNames.map(escapeRegExpSource).join('|');
+    const tagPattern = new RegExp(`<(${streamingPattern})(\\s[^>]*)?>`, 'g');
+    let match: RegExpExecArray | null;
+
+    while ((match = tagPattern.exec(tailText)) !== null) {
+      const tagName = match[1];
+      const closeTag = `</${tagName}>`;
+      const afterOpen = match.index + match[0].length;
+
+      // Only process if there's no closing tag after this opening tag.
+      if (tailText.indexOf(closeTag, afterOpen) === -1) {
+        const absoluteFrom = range.from + match.index;
+        const contentFrom = range.from + afterOpen;
+        const innerText = state.sliceDoc(contentFrom, range.to).trim();
+
+        const def = registry[tagName];
+        const props: XmlWidgetProps = {
+          _tag: tagName,
+          context,
+          range: { from: absoluteFrom, to: range.to },
+          children: innerText ? [innerText] : undefined,
+        };
+
+        // Parse attributes from the opening tag.
+        const attrPattern = /(\w+)="([^"]*)"/g;
+        let attrMatch: RegExpExecArray | null;
+        while ((attrMatch = attrPattern.exec(match[0])) !== null) {
+          props[attrMatch[1]] = attrMatch[2];
+        }
+
+        const widgetId = xmlWidgetId(props.id, `cm-xml-${absoluteFrom}`);
+        const widgetState = widgetStateMap[widgetId];
+        const mergedProps = { ...props, id: widgetId, ...widgetState };
+
+        const widget: WidgetType | undefined = def.factory
+          ? (def.factory(mergedProps) ?? undefined)
+          : def.Component
+            ? new PlaceholderWidget(widgetId, def.Component, mergedProps, notifier, true)
+            : undefined;
+
+        if (widget) {
+          builder.add(
+            absoluteFrom,
+            range.to,
+            Decoration.replace({
+              widget,
+              block: def.block,
+              atomic: true,
+              inclusive: true,
+              tag: tagName,
+              streaming: true,
+              contentFrom,
+            }),
+          );
+
+          // Set from to just before the streaming tag so next rebuild covers it.
+          streamingFrom = absoluteFrom;
+          last = absoluteFrom;
+        }
+
+        // Only one streaming tag at a time.
+        break;
+      }
+    }
+  }
+
+  return { from: last, streamingFrom, decorations: builder.finish() };
 };
 
 /**
  * Placeholder for widgets.
  */
 class PlaceholderWidget<TProps extends XmlWidgetProps> extends WidgetType {
-  private _root: HTMLElement | null = null;
+  #root: HTMLElement | null = null;
+  #view: EditorView | undefined;
 
   constructor(
-    public readonly id: string,
-    public readonly Component: FunctionComponent<TProps>,
-    public readonly props: TProps,
-    private readonly notifier: XmlWidgetNotifier,
+    readonly id: string,
+    readonly Component: FunctionComponent<TProps>,
+    readonly props: TProps,
+    readonly notifier: XmlWidgetNotifier,
+    readonly streaming?: boolean,
   ) {
     super();
     invariant(id);
   }
 
   get root(): HTMLElement | null {
-    return this._root;
+    return this.#root;
   }
 
   override eq(other: this) {
+    // Streaming widgets always need updating (content changes on each tick).
+    if (this.streaming) {
+      return false;
+    }
+
     return this.id === other.id;
   }
 
@@ -494,14 +634,25 @@ class PlaceholderWidget<TProps extends XmlWidgetProps> extends WidgetType {
     return true;
   }
 
-  override toDOM(_view: EditorView) {
-    this._root = document.createElement('span');
-    this.notifier.mounted({ id: this.id, root: this._root, props: this.props, Component: this.Component });
-    return this._root;
+  override toDOM(view: EditorView) {
+    this.#view = view;
+    // NOTE: Set min-height to avoid jumps while scrolling.
+    this.#root = Domino.of('div').classNames('min-h-[24px]').root;
+    const props = Object.assign({}, this.props, { view }) as TProps;
+    this.notifier.mounted({ id: this.id, root: this.#root, props, Component: this.Component });
+    return this.#root;
+  }
+
+  override updateDOM(dom: HTMLElement) {
+    this.#root = dom;
+    const props = Object.assign({}, this.props, { view: this.#view }) as TProps;
+    this.notifier.mounted({ id: this.id, root: this.#root, props, Component: this.Component });
+    return true;
   }
 
   override destroy(_dom: HTMLElement) {
     this.notifier.unmounted(this.id);
-    this._root = null;
+    this.#root = null;
+    this.#view = undefined;
   }
 }