@dxos/ui-editor 0.9.1-main.c7dcc2e112 → 0.10.0

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

@@ -156,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]');
+  });
+});

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

@@ -0,0 +1,269 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type EditorView } from '@codemirror/view';
+
+import {
+  appendPendingText,
+  cancelPendingText,
+  setPendingAnchor,
+  setPendingFinal,
+  setPendingInterim,
+} from './pending-text';
+
+//
+// Sinks — decouple the streamer from its target (a live editor, or memory for tests/stories).
+//
+
+/**
+ * Target for streamed pending text. The {@link PendingTextStreamer} writes to this interface; the
+ * editor implementation dispatches CodeMirror effects, while the memory implementation accumulates
+ * state so the mechanism can be exercised without a CodeMirror component.
+ */
+export type PendingTextSink = {
+  begin(options?: { anchor?: number; placeholder?: string }): void;
+  /** Set the volatile in-flight tail. */
+  interim(text: string): void;
+  /** Append finalized text to the buffer. */
+  appendFinal(text: string): void;
+  /** Replace the finalized buffer wholesale (e.g. post-processed text). */
+  replaceFinal(text: string): void;
+  cancel(): void;
+};
+
+/** Sink that drives the `pendingText` extension in a live editor via its state effects. */
+export const editorPendingTextSink = (view: EditorView): PendingTextSink => ({
+  begin: ({ anchor = view.state.selection.main.head, placeholder } = {}) =>
+    view.dispatch({ effects: setPendingAnchor.of({ anchor, placeholder }) }),
+  interim: (text) => view.dispatch({ effects: setPendingInterim.of(text) }),
+  appendFinal: (text) => view.dispatch({ effects: appendPendingText.of(text) }),
+  replaceFinal: (text) => view.dispatch({ effects: setPendingFinal.of(text) }),
+  cancel: () => view.dispatch({ effects: cancelPendingText.of() }),
+});
+
+export type PendingTextSnapshot = {
+  active: boolean;
+  final: string;
+  interim: string;
+  placeholder?: string;
+};
+
+/** In-memory sink for tests and CodeMirror-free stories. */
+export const memoryPendingTextSink = (
+  onChange?: (snapshot: PendingTextSnapshot) => void,
+): PendingTextSink & { snapshot: () => PendingTextSnapshot } => {
+  let state: PendingTextSnapshot = { active: false, final: '', interim: '', placeholder: undefined };
+  const set = (next: PendingTextSnapshot) => {
+    state = next;
+    onChange?.(state);
+  };
+
+  return {
+    begin: ({ placeholder } = {}) => set({ active: true, final: '', interim: '', placeholder }),
+    interim: (text) => set({ ...state, interim: text }),
+    appendFinal: (text) => set({ ...state, final: state.final + text, interim: '', placeholder: undefined }),
+    replaceFinal: (text) => set({ ...state, final: text, placeholder: undefined }),
+    cancel: () => set({ active: false, final: '', interim: '', placeholder: undefined }),
+    snapshot: () => state,
+  };
+};
+
+//
+// Streamer — buffering, pacing, and post-processing between a text source and a sink.
+//
+
+/** Minimal timer interface so tests can drive the streamer deterministically. */
+export type Scheduler = {
+  setTimeout: (callback: () => void, ms: number) => unknown;
+  clearTimeout: (handle: unknown) => void;
+};
+
+const defaultScheduler: Scheduler = {
+  setTimeout: (callback, ms) => setTimeout(callback, ms),
+  clearTimeout: (handle) => clearTimeout(handle as ReturnType<typeof setTimeout>),
+};
+
+export type PendingTextStreamerOptions = {
+  /** Delay (ms) before the first text is revealed — absorbs the source's initial latency. */
+  initialBufferMs?: number;
+  /** `batch` reveals each pushed chunk whole; `word` reveals one word per {@link wordIntervalMs}. */
+  mode?: 'batch' | 'word';
+  /** Pacing (ms) for `word` mode. */
+  wordIntervalMs?: number;
+  /** Idle delay (ms) before {@link postProcess} runs after the buffer settles. */
+  postProcessDebounceMs?: number;
+  /** Rewrites the finalized buffer once it settles (e.g. entity extraction / dx-anchor links). */
+  postProcess?: (final: string) => string | Promise<string>;
+  /** Injectable timers (defaults to the global timers). */
+  scheduler?: Scheduler;
+};
+
+const DEFAULTS = {
+  initialBufferMs: 0,
+  mode: 'batch' as const,
+  wordIntervalMs: 120,
+  postProcessDebounceMs: 800,
+};
+
+/**
+ * Streams text from an arbitrary source (e.g. a transcriber, or a scripted mock) into a
+ * {@link PendingTextSink}, decoupling the source from the editor and centralizing the cross-cutting
+ * concerns: an initial buffering delay, optional word-by-word reveal, and a post-processing pass.
+ */
+export class PendingTextStreamer {
+  readonly #sink: PendingTextSink;
+  readonly #options: Required<Omit<PendingTextStreamerOptions, 'postProcess' | 'scheduler'>> &
+    Pick<PendingTextStreamerOptions, 'postProcess'>;
+  readonly #scheduler: Scheduler;
+
+  #started = false;
+  #buffering = false;
+  #final = '';
+  #queue: string[] = [];
+  #bufferHandle: unknown = null;
+  #wordHandle: unknown = null;
+  #postHandle: unknown = null;
+  /** The in-flight post-process pass, tracked so `flush()` can await it (drain contract). */
+  #postPromise: Promise<void> | null = null;
+
+  constructor(sink: PendingTextSink, options: PendingTextStreamerOptions = {}) {
+    this.#sink = sink;
+    this.#options = { ...DEFAULTS, ...options };
+    this.#scheduler = options.scheduler ?? defaultScheduler;
+  }
+
+  /** Begin a session; nothing is revealed until the initial buffer elapses (or the first push, if 0). */
+  start(options: { placeholder?: string; anchor?: number } = {}): void {
+    this.#started = true;
+    this.#final = '';
+    this.#queue = [];
+    this.#sink.begin(options);
+    if (this.#options.initialBufferMs > 0) {
+      this.#buffering = true;
+      this.#bufferHandle = this.#scheduler.setTimeout(() => {
+        this.#buffering = false;
+        this.#bufferHandle = null;
+        this.#drain();
+      }, this.#options.initialBufferMs);
+    }
+  }
+
+  /** Feed a finalized text chunk from the source. */
+  push(text: string): void {
+    if (!this.#started) {
+      this.start();
+    }
+    const trimmed = text.trim();
+    if (trimmed.length === 0) {
+      return;
+    }
+    this.#queue.push(...(this.#options.mode === 'word' ? trimmed.split(/\s+/) : [trimmed]));
+    this.#drain();
+  }
+
+  /** Feed a volatile interim chunk (when the source yields partials). */
+  pushInterim(text: string): void {
+    if (!this.#started) {
+      this.start();
+    }
+    if (!this.#buffering) {
+      this.#sink.interim(text);
+    }
+  }
+
+  /**
+   * Reveal everything immediately and run any pending post-process (e.g. on stop). Resolves once the
+   * post-process pass (entity linking, …) has settled, so callers can drain before disposing.
+   */
+  async flush(): Promise<void> {
+    this.#clear(this.#bufferHandle);
+    this.#bufferHandle = null;
+    this.#buffering = false;
+    this.#clear(this.#wordHandle);
+    this.#wordHandle = null;
+    while (this.#queue.length > 0) {
+      this.#appendFinal(this.#queue.shift()!);
+    }
+    this.#sink.interim('');
+    this.#clear(this.#postHandle);
+    this.#postHandle = null;
+    if (this.#options.postProcess && this.#final.length > 0) {
+      // Await any post-process already in flight (its scheduled timer may have fired), then run a
+      // final pass over the settled buffer — so draining truly waits for post-processing to finish.
+      if (this.#postPromise) {
+        await this.#postPromise;
+      }
+      this.#postPromise = this.#runPostProcess();
+      await this.#postPromise;
+    }
+  }
+
+  dispose(): void {
+    [this.#bufferHandle, this.#wordHandle, this.#postHandle].forEach((handle) => this.#clear(handle));
+    this.#bufferHandle = this.#wordHandle = this.#postHandle = null;
+  }
+
+  #drain(): void {
+    if (this.#buffering) {
+      return;
+    }
+    if (this.#options.mode === 'word') {
+      if (this.#wordHandle == null) {
+        this.#tickWord();
+      }
+    } else {
+      while (this.#queue.length > 0) {
+        this.#appendFinal(this.#queue.shift()!);
+      }
+    }
+  }
+
+  #tickWord(): void {
+    const word = this.#queue.shift();
+    if (word == null) {
+      this.#wordHandle = null;
+      return;
+    }
+    this.#appendFinal(word);
+    this.#wordHandle = this.#scheduler.setTimeout(() => this.#tickWord(), this.#options.wordIntervalMs);
+  }
+
+  #appendFinal(text: string): void {
+    const chunk = (this.#final.length > 0 ? ' ' : '') + text;
+    this.#final += chunk;
+    this.#sink.appendFinal(chunk);
+    this.#schedulePostProcess();
+  }
+
+  #schedulePostProcess(): void {
+    if (!this.#options.postProcess) {
+      return;
+    }
+    this.#clear(this.#postHandle);
+    this.#postHandle = this.#scheduler.setTimeout(() => {
+      this.#postHandle = null;
+      this.#postPromise = this.#runPostProcess();
+    }, this.#options.postProcessDebounceMs);
+  }
+
+  async #runPostProcess(): Promise<void> {
+    const input = this.#final;
+    try {
+      const result = await this.#options.postProcess!(input);
+      // Skip if the buffer grew while processing — a later pass will cover the newer text.
+      if (result !== input && this.#final === input) {
+        this.#final = result;
+        this.#sink.replaceFinal(result);
+      }
+    } catch {
+      // Post-process is best-effort (e.g. entity linking); a failure leaves the un-rewritten text.
+    }
+  }
+
+  #clear(handle: unknown): void {
+    if (handle != null) {
+      this.#scheduler.clearTimeout(handle);
+    }
+  }
+}