@dxos/ui-editor 0.9.0 → 0.9.1-staging.ee54ba693a

package/src/extensions/dnd.ts

@@ -2,19 +2,142 @@
 // Copyright 2024 DXOS.org
 //
 
-import type { Extension } from '@codemirror/state';
-import { EditorView, dropCursor } from '@codemirror/view';
+import { type Extension, StateEffect, StateField } from '@codemirror/state';
+import { EditorView, ViewPlugin, type ViewUpdate } from '@codemirror/view';
 
 export type DropOptions = {
   onDrop?: (view: EditorView, event: { files: FileList }) => void;
 };
 
+/**
+ * Whether a drag carries external files. Internal element drags (e.g. an embed's resize handle using
+ * native HTML5 DnD) carry custom data-transfer types, not `Files`, so this gates the file-drop UI to
+ * real file drags and leaves other drags untouched (otherwise the drop cursor and drop handler would
+ * fire for — and interfere with — an in-document resize drag).
+ */
+const isFileDrag = (event: DragEvent): boolean =>
+  !!event.dataTransfer && Array.from(event.dataTransfer.types).includes('Files');
+
+const setDropCursorPos = StateEffect.define<number | null>();
+
+const dropCursorPos = StateField.define<number | null>({
+  create: () => null,
+  update(pos, tr) {
+    if (pos != null && tr.docChanged) {
+      pos = tr.changes.mapPos(pos);
+    }
+    return tr.effects.reduce((value, effect) => (effect.is(setDropCursorPos) ? effect.value : value), pos);
+  },
+});
+
+type CursorMeasure = { left: number; top: number; height: number };
+
+// Mirrors `@codemirror/view`'s built-in drop cursor, but the `dragover` observer only tracks file
+// drags (see `isFileDrag`) so non-file drags never render the cursor.
+const drawDropCursor = ViewPlugin.fromClass(
+  class {
+    cursor: HTMLElement | null = null;
+    readonly measureReq: { read: () => CursorMeasure | null; write: (measure: CursorMeasure | null) => void };
+
+    constructor(readonly view: EditorView) {
+      this.measureReq = { read: this.readPos.bind(this), write: this.drawCursor.bind(this) };
+    }
+
+    update(update: ViewUpdate) {
+      const pos = update.state.field(dropCursorPos);
+      if (pos == null) {
+        this.cursor?.remove();
+        this.cursor = null;
+      } else {
+        if (!this.cursor) {
+          this.cursor = this.view.scrollDOM.appendChild(document.createElement('div'));
+          this.cursor.className = 'cm-dropCursor';
+        }
+        if (update.startState.field(dropCursorPos) !== pos || update.docChanged || update.geometryChanged) {
+          this.view.requestMeasure(this.measureReq);
+        }
+      }
+    }
+
+    readPos(): CursorMeasure | null {
+      const pos = this.view.state.field(dropCursorPos);
+      const rect = pos != null && this.view.coordsAtPos(pos);
+      if (!rect) {
+        return null;
+      }
+      const outer = this.view.scrollDOM.getBoundingClientRect();
+      return {
+        left: rect.left - outer.left + this.view.scrollDOM.scrollLeft * this.view.scaleX,
+        top: rect.top - outer.top + this.view.scrollDOM.scrollTop * this.view.scaleY,
+        height: rect.bottom - rect.top,
+      };
+    }
+
+    drawCursor(measure: CursorMeasure | null) {
+      if (!this.cursor) {
+        return;
+      }
+      const { scaleX, scaleY } = this.view;
+      if (measure) {
+        this.cursor.style.left = measure.left / scaleX + 'px';
+        this.cursor.style.top = measure.top / scaleY + 'px';
+        this.cursor.style.height = measure.height / scaleY + 'px';
+      } else {
+        this.cursor.style.left = '-100000px';
+      }
+    }
+
+    destroy() {
+      this.cursor?.remove();
+    }
+
+    setDropPos(pos: number | null) {
+      if (this.view.state.field(dropCursorPos) !== pos) {
+        this.view.dispatch({ effects: setDropCursorPos.of(pos) });
+      }
+    }
+  },
+  {
+    eventObservers: {
+      dragover(event) {
+        if (isFileDrag(event)) {
+          // Mark the editor a valid drop target so the `drop` event fires for external files.
+          event.preventDefault();
+          this.setDropPos(this.view.posAtCoords({ x: event.clientX, y: event.clientY }));
+        }
+      },
+      dragleave(event) {
+        const related = event.relatedTarget instanceof Node ? event.relatedTarget : null;
+        if (event.target === this.view.contentDOM || !this.view.contentDOM.contains(related)) {
+          this.setDropPos(null);
+        }
+      },
+      dragend() {
+        this.setDropPos(null);
+      },
+      drop() {
+        this.setDropPos(null);
+      },
+    },
+  },
+);
+
+/**
+ * Editor extension that accepts external file drops (drawing a drop cursor and invoking
+ * `options.onDrop`) while leaving internal drags — e.g. an embed's resize handle — untouched.
+ */
 export const dropFile = (options: DropOptions = {}): Extension => {
   return [
     styles,
-    dropCursor(),
+    dropCursorPos,
+    drawDropCursor,
     EditorView.domEventHandlers({
       drop: (event, view) => {
+        // Leave non-file drops (e.g. an embed resize drag) to their own handlers.
+        if (!isFileDrag(event)) {
+          return false;
+        }
+
         event.preventDefault();
         const files = event.dataTransfer?.files;
         const pos = view.posAtCoords(event);
@@ -22,6 +145,7 @@ export const dropFile = (options: DropOptions = {}): Extension => {
           view.dispatch({ selection: { anchor: pos } });
           options.onDrop?.(view, { files });
         }
+        return true;
       },
     }),
   ];

package/src/extensions/factories.test.ts

@@ -2,7 +2,7 @@
 // Copyright 2026 DXOS.org
 //
 
-import { markdown, markdownLanguage, insertNewlineContinueMarkup } from '@codemirror/lang-markdown';
+import { insertNewlineContinueMarkup, markdown, markdownLanguage } from '@codemirror/lang-markdown';
 import { EditorSelection, EditorState } from '@codemirror/state';
 import { describe, test } from 'vitest';
 

package/src/extensions/factories.ts

@@ -22,7 +22,7 @@ import { vscodeDarkStyle, vscodeLightStyle } from '@uiw/codemirror-theme-vscode'
 import defaultsDeep from 'lodash.defaultsdeep';
 
 import { generateName } from '@dxos/display-name';
-import { type DocAccessor } from '@dxos/echo-client';
+import { Doc } from '@dxos/echo-doc';
 import { log } from '@dxos/log';
 import { type Messenger } from '@dxos/protocols';
 import { type Identity } from '@dxos/protocols/proto/dxos/client/services';
@@ -267,7 +267,7 @@ export const createThemeExtensions = ({
 
 export type DataExtensionsProps<T> = {
   id: string;
-  text?: DocAccessor<T>;
+  text?: Doc.Accessor<T>;
   messenger?: Messenger;
   identity?: Identity | null;
 };

package/src/extensions/index.ts

@@ -9,21 +9,25 @@ export * from './awareness';
 export * from './blast';
 export * from './blocks';
 export * from './bookmarks';
+export * from './busy';
 export * from './comments';
 export * from './debug';
 export * from './dnd';
 export * from './factories';
+export * from './fader';
 export * from './focus';
 export * from './folding';
 export * from './hashtag';
 export * from './json';
 export * from './listener';
+export * from './marker';
 export * from './markdown';
 export * from './mention';
 export * from './modal';
 export * from './modes';
 export * from './outliner';
-export * from './preview';
+export * from './pending';
+export * from './pos';
 export * from './replacer';
 export * from './scrolling';
 export * from './selection';
@@ -32,3 +36,4 @@ export * from './snippets';
 export * from './state';
 export * from './submit';
 export * from './tags';
+export * from './typewriter';

package/src/extensions/markdown/styles.ts

@@ -82,7 +82,8 @@ export const formattingStyles = EditorView.theme({
   },
   '& .cm-codeblock-line': {
     background: 'var(--color-cm-codeblock)',
-    paddingInline: '1rem !important',
+    paddingLeft: '1rem !important',
+    paddingRight: '1.5rem !important',
   },
   '& .cm-codeblock-start': {
     borderTopLeftRadius: '.25rem',
@@ -155,11 +156,11 @@ export const formattingStyles = EditorView.theme({
   },
   '.cm-image-wrapper': {
     'grid-template-columns': '1fr',
-    display: 'grid',
-    margin: '0.5rem 0',
-    overflow: 'hidden',
-    transitionDuration: '350ms',
-    transitionProperty: 'height',
+    'display': 'grid',
+    'margin': '0.5rem 0',
+    'overflow': 'hidden',
+    'transitionDuration': '350ms',
+    'transitionProperty': 'height',
     '& > *': {
       'grid-row-start': 1,
       'grid-column-start': 1,

package/src/extensions/marker.ts

@@ -0,0 +1,143 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Extension } from '@codemirror/state';
+import { Decoration, EditorView } from '@codemirror/view';
+
+import { Domino } from '@dxos/ui';
+import { hues } from '@dxos/ui-theme';
+import { type ChromaticPalette } from '@dxos/ui-types';
+
+/**
+ * Reusable, hue-tinted text markers for CodeMirror decorations (shared by comments and pending-text).
+ * The tint is driven by a `data-hue` attribute holding a standard ui-theme hue, mapped to the
+ * `--color-<hue>-*` tokens — rather than hardcoded per-feature CSS variables.
+ */
+export type MarkerHue = ChromaticPalette;
+
+const MARKED = ['.cm-marker > span', '.cm-marker-text'].join(', ');
+
+// Map `data-hue` to the standard ui-theme surface/foreground tokens (one rule per hue).
+const hueVars = Object.fromEntries(
+  hues.flatMap((hue) =>
+    ['.cm-marker', '.cm-marker-text'].map((selector) => [
+      `${selector}[data-hue="${hue}"]`,
+      {
+        '--cm-marker-surface': `var(--color-${hue}-bg)`,
+        '--cm-marker-text': `var(--color-${hue}-fg)`,
+      },
+    ]),
+  ),
+);
+
+/**
+ * Shared theme for hue-tinted markers and their inline button affordances. Include once per editor;
+ * both `markerMark` (range marks) and `markerText` (widget spans) read from it.
+ */
+export const markerTheme = (): Extension =>
+  EditorView.theme({
+    ...hueVars,
+    // The comment-style surface "padding" is a box-shadow of the same colour so adjacent lines join.
+    [MARKED]: {
+      boxDecorationBreak: 'clone',
+      backgroundColor: 'var(--cm-marker-surface)',
+      boxShadow: '0 0 0 3px var(--cm-marker-surface)',
+      color: 'var(--cm-marker-text) !important',
+      borderRadius: '0.25rem',
+    },
+    // `inline-block` (not flex) so the finalized + interim spans flow as one continuous block.
+    '.cm-marker-text': {
+      display: 'inline-block',
+    },
+    // Align a trailing icon (e.g. the recording spinner) inline with the text — the global reset
+    // sets `svg { display: block }`, which would otherwise push it onto its own line.
+    '.cm-marker-text svg': {
+      display: 'inline-block',
+      verticalAlign: '-0.15em',
+      marginInlineStart: '0.25rem',
+    },
+    '.cm-marker-buttons': {
+      display: 'inline-flex',
+      alignItems: 'center',
+      gap: '0.25rem',
+    },
+    '.cm-marker-button': {
+      display: 'inline-flex',
+      padding: '4px',
+      borderRadius: '4px',
+      cursor: 'pointer',
+    },
+    '.cm-marker-button:hover': {
+      backgroundColor: 'var(--color-hover-bg)',
+    },
+    '.cm-marker-button-success:hover': {
+      backgroundColor: 'var(--color-success-bg)',
+    },
+    '.cm-marker-button-error:hover': {
+      backgroundColor: 'var(--color-error-bg)',
+    },
+  });
+
+/** Range mark tinted by hue (used by comments to highlight a selection). */
+export const markerMark = (hue: MarkerHue, options: { class?: string; attributes?: Record<string, string> } = {}) =>
+  Decoration.mark({
+    class: ['cm-marker', options.class].filter(Boolean).join(' '),
+    attributes: { 'data-hue': hue, ...options.attributes },
+  });
+
+export type MarkerTextOptions = {
+  hue: MarkerHue;
+  className?: string;
+  /** Optional trailing icon (e.g. a recording indicator). */
+  icon?: string;
+  /** Extra classes for the trailing icon (e.g. `animate-spin`). */
+  iconClassNames?: string;
+};
+
+/** A hue-tinted text span for use inside widgets; optionally trailed by an icon. */
+export const markerText = (
+  text: string,
+  { hue, className, icon, iconClassNames }: MarkerTextOptions,
+): Domino<HTMLElement> => {
+  const span = Domino.of('span')
+    .classNames('cm-marker-text', className)
+    .attributes({ 'data-hue': hue })
+    .append(Domino.of('span').text(text));
+  if (icon) {
+    // Preserve the sprite sizing (`Domino.svg` sets `h-[1em] w-[1em]`) since `classNames` replaces.
+    span.append(Domino.svg(icon).classNames('shrink-0 h-[1em] w-[1em]', iconClassNames));
+  }
+
+  return span;
+};
+
+export type MarkerButton = {
+  icon: string;
+  label: string;
+  className?: string;
+  testId?: string;
+  onClick: () => void;
+};
+
+/** Inline group of icon buttons (e.g. confirm/cancel affordances). */
+export const markerButtons = (buttons: MarkerButton[]): Domino<HTMLElement> =>
+  Domino.of('span')
+    .classNames('cm-marker-buttons')
+    .append(
+      ...buttons.map((button) =>
+        Domino.of('button')
+          .classNames('cm-marker-button', button.className)
+          .attributes({
+            'type': 'button',
+            'aria-label': button.label,
+            ...(button.testId ? { 'data-testid': button.testId } : {}),
+          })
+          .append(Domino.svg(button.icon))
+          // `mousedown` + preventDefault so clicking the affordance does not steal the editor selection.
+          .on('mousedown', (event) => {
+            event.preventDefault();
+            button.onClick();
+          }),
+      ),
+    );

package/src/extensions/pending/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './pending-text';
+export * from './pending-text-stream';

package/src/extensions/pending/pending-text-stream.test.ts

@@ -0,0 +1,133 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { PendingTextStreamer, type Scheduler, memoryPendingTextSink } from './pending-text-stream';
+
+// Deterministic fake clock: `advance` runs due timers in time order (including timers they schedule).
+const createFakeScheduler = (): Scheduler & { advance: (ms: number) => void } => {
+  let now = 0;
+  let seq = 0;
+  const timers = new Map<number, { time: number; fn: () => void }>();
+  return {
+    setTimeout: (fn, ms) => {
+      const id = ++seq;
+      timers.set(id, { time: now + ms, fn });
+      return id;
+    },
+    clearTimeout: (handle) => {
+      timers.delete(handle as number);
+    },
+    advance: (ms) => {
+      now += ms;
+      let ran = true;
+      while (ran) {
+        ran = false;
+        const due = [...timers].filter(([, t]) => t.time <= now).sort((a, b) => a[1].time - b[1].time);
+        if (due.length > 0) {
+          const [id, timer] = due[0];
+          timers.delete(id);
+          timer.fn();
+          ran = true;
+        }
+      }
+    },
+  };
+};
+
+// Flush pending microtasks (postProcess awaits its callback).
+const flushMicrotasks = () => new Promise<void>((resolve) => setTimeout(resolve, 0));
+
+describe('PendingTextStreamer', () => {
+  test('holds text until the initial buffer elapses', ({ expect }) => {
+    const scheduler = createFakeScheduler();
+    const sink = memoryPendingTextSink();
+    const streamer = new PendingTextStreamer(sink, { initialBufferMs: 1000, scheduler });
+
+    streamer.start({ placeholder: 'Recording…' });
+    streamer.push('hello world');
+    expect(sink.snapshot()).toMatchObject({ final: '', placeholder: 'Recording…' });
+
+    scheduler.advance(1000);
+    expect(sink.snapshot().final).toBe('hello world');
+  });
+
+  test('batch mode reveals each chunk immediately when unbuffered', ({ expect }) => {
+    const scheduler = createFakeScheduler();
+    const sink = memoryPendingTextSink();
+    const streamer = new PendingTextStreamer(sink, { scheduler });
+
+    streamer.start();
+    streamer.push('hello');
+    streamer.push('world');
+    expect(sink.snapshot().final).toBe('hello world');
+  });
+
+  test('word mode reveals one word per interval', ({ expect }) => {
+    const scheduler = createFakeScheduler();
+    const sink = memoryPendingTextSink();
+    const streamer = new PendingTextStreamer(sink, { mode: 'word', wordIntervalMs: 100, scheduler });
+
+    streamer.start();
+    streamer.push('one two three');
+    expect(sink.snapshot().final).toBe('one');
+    scheduler.advance(100);
+    expect(sink.snapshot().final).toBe('one two');
+    scheduler.advance(100);
+    expect(sink.snapshot().final).toBe('one two three');
+  });
+
+  test('post-processes the finalized buffer once it settles', async ({ expect }) => {
+    const scheduler = createFakeScheduler();
+    const sink = memoryPendingTextSink();
+    const streamer = new PendingTextStreamer(sink, {
+      postProcessDebounceMs: 500,
+      postProcess: (text) => text.toUpperCase(),
+      scheduler,
+    });
+
+    streamer.start();
+    streamer.push('hello world');
+    expect(sink.snapshot().final).toBe('hello world');
+
+    scheduler.advance(500);
+    await flushMicrotasks();
+    expect(sink.snapshot().final).toBe('HELLO WORLD');
+  });
+
+  test('flush reveals queued words and runs post-process immediately', async ({ expect }) => {
+    const scheduler = createFakeScheduler();
+    const sink = memoryPendingTextSink();
+    const streamer = new PendingTextStreamer(sink, {
+      mode: 'word',
+      wordIntervalMs: 100,
+      postProcess: (text) => `[${text}]`,
+      scheduler,
+    });
+
+    streamer.start();
+    streamer.push('alpha beta gamma');
+    expect(sink.snapshot().final).toBe('alpha');
+
+    void streamer.flush();
+    expect(sink.snapshot().final).toBe('alpha beta gamma');
+    await flushMicrotasks();
+    expect(sink.snapshot().final).toBe('[alpha beta gamma]');
+  });
+
+  test('awaiting flush() resolves only after async post-process settles (drain contract)', async ({ expect }) => {
+    const sink = memoryPendingTextSink();
+    const streamer = new PendingTextStreamer(sink, {
+      mode: 'batch',
+      postProcess: async (text) => `[${text}]`,
+    });
+
+    streamer.start();
+    streamer.push('alpha beta');
+    // Drain: a single await must guarantee the post-process pass has applied.
+    await streamer.flush();
+    expect(sink.snapshot().final).toBe('[alpha beta]');
+  });
+});