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

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

@@ -0,0 +1,134 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { EditorState } from '@codemirror/state';
+import { EditorView } from '@codemirror/view';
+import { describe, test } from 'vitest';
+
+import { isBusy } from '../busy';
+import {
+  appendPendingText,
+  cancelPending,
+  commitPending,
+  pendingText,
+  pendingTextState,
+  setPendingAnchor,
+  setPendingInterim,
+} from './pending-text';
+
+const createView = (doc: string): EditorView =>
+  new EditorView({ state: EditorState.create({ doc, extensions: [pendingText()] }) });
+
+// Busy is toggled via a queued microtask, so flush before asserting.
+const flush = () => new Promise<void>((resolve) => queueMicrotask(resolve));
+
+describe('pendingText extension', () => {
+  test('append and interim accumulate without changing the document', ({ expect }) => {
+    const view = createView('hello ');
+    view.dispatch({ effects: setPendingAnchor.of({ anchor: 6 }) });
+    view.dispatch({ effects: appendPendingText.of('world') });
+    view.dispatch({ effects: setPendingInterim.of(' and') });
+    expect(view.state.field(pendingTextState)).toEqual({
+      anchor: 6,
+      final: 'world',
+      interim: ' and',
+      placeholder: undefined,
+    });
+    expect(view.state.doc.toString()).toBe('hello ');
+    view.destroy();
+  });
+
+  test('appending finalized text clears the interim tail', ({ expect }) => {
+    const view = createView('hello ');
+    view.dispatch({ effects: setPendingAnchor.of({ anchor: 6 }) });
+    view.dispatch({ effects: setPendingInterim.of('wor') });
+    view.dispatch({ effects: appendPendingText.of('world') });
+    expect(view.state.field(pendingTextState)).toMatchObject({ anchor: 6, final: 'world', interim: '' });
+    view.destroy();
+  });
+
+  test('commit at the end of the document inserts the text and leaves a trailing blank line', ({ expect }) => {
+    const view = createView('hello ');
+    view.dispatch({ effects: setPendingAnchor.of({ anchor: 6 }) });
+    view.dispatch({ effects: appendPendingText.of('world') });
+    view.dispatch({ effects: setPendingInterim.of(' dropped') });
+    expect(commitPending(view)).toBe(true);
+    expect(view.state.doc.toString()).toBe('hello world\n\n');
+    expect(view.state.field(pendingTextState)).toBeNull();
+    view.destroy();
+  });
+
+  test('commit before the end of the document does not add a trailing blank line', ({ expect }) => {
+    const view = createView('one\ntwo');
+    view.dispatch({ effects: setPendingAnchor.of({ anchor: 3 }) });
+    view.dispatch({ effects: appendPendingText.of(' and a half') });
+    expect(commitPending(view)).toBe(true);
+    // Single newline terminates the inserted line; the document still ends at 'two' (no trailing blank line).
+    expect(view.state.doc.toString()).toBe('one and a half\n\ntwo');
+    view.destroy();
+  });
+
+  test('cancel discards pending text and leaves the document unchanged', ({ expect }) => {
+    const view = createView('hello ');
+    view.dispatch({ effects: setPendingAnchor.of({ anchor: 6 }) });
+    view.dispatch({ effects: appendPendingText.of('world') });
+    expect(cancelPending(view)).toBe(true);
+    expect(view.state.doc.toString()).toBe('hello ');
+    expect(view.state.field(pendingTextState)).toBeNull();
+    view.destroy();
+  });
+
+  test('commit and cancel are no-ops when there is no pending text', ({ expect }) => {
+    const view = createView('hello ');
+    expect(commitPending(view)).toBe(false);
+    expect(cancelPending(view)).toBe(false);
+    view.destroy();
+  });
+
+  test('a placeholder-only session is held without committable text', ({ expect }) => {
+    const view = createView('hello ');
+    view.dispatch({ effects: setPendingAnchor.of({ anchor: 6, placeholder: 'Recording…' }) });
+    expect(view.state.field(pendingTextState)).toEqual({
+      anchor: 6,
+      final: '',
+      interim: '',
+      placeholder: 'Recording…',
+    });
+    // Nothing finalized yet, so commit is a no-op.
+    expect(commitPending(view)).toBe(false);
+    view.destroy();
+  });
+
+  test('anchor survives an edit before the anchor', ({ expect }) => {
+    const view = createView('hello ');
+    view.dispatch({ effects: setPendingAnchor.of({ anchor: 6 }) });
+    view.dispatch({ effects: appendPendingText.of('world') });
+    view.dispatch({ changes: { from: 0, insert: 'X' } });
+    expect(view.state.field(pendingTextState)?.anchor).toBe(7);
+    expect(commitPending(view)).toBe(true);
+    expect(view.state.doc.toString()).toBe('Xhello world\n\n');
+    view.destroy();
+  });
+
+  test('the first text effect without an explicit anchor uses the selection head', ({ expect }) => {
+    const view = createView('hello ');
+    view.dispatch({ selection: { anchor: 6 } });
+    view.dispatch({ effects: appendPendingText.of('world') });
+    expect(view.state.field(pendingTextState)?.anchor).toBe(6);
+    view.destroy();
+  });
+
+  test('flags the editor busy while a session is active and clears it on commit', async ({ expect }) => {
+    const view = createView('hello ');
+    view.dispatch({ effects: setPendingAnchor.of({ anchor: 6, placeholder: 'Recording…' }) });
+    await flush();
+    expect(isBusy(view.state)).toBe(true);
+
+    view.dispatch({ effects: appendPendingText.of('world') });
+    commitPending(view);
+    await flush();
+    expect(isBusy(view.state)).toBe(false);
+    view.destroy();
+  });
+});

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

@@ -0,0 +1,264 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Extension, StateEffect, StateField } from '@codemirror/state';
+import { type Command, Decoration, EditorView, WidgetType, keymap } from '@codemirror/view';
+
+import { Domino } from '@dxos/ui';
+
+import { busy, setBusy } from '../busy';
+import { type MarkerHue, markerButtons, markerText, markerTheme } from '../marker';
+
+//
+// State.
+//
+
+/**
+ * Pending (not-yet-committed) text injected from an external source.
+ * `final` is the accumulated finalized text; `interim` is the volatile in-flight tail; `placeholder`
+ * is shown while both are empty (e.g. "Recording…"). `anchor` is the document position the text will
+ * be inserted at; it is mapped through document changes so it survives concurrent edits.
+ */
+export type PendingTextState = {
+  anchor: number;
+  final: string;
+  interim: string;
+  placeholder?: string;
+};
+
+/** Start a pending-text session at the given position, optionally showing a placeholder until text arrives. */
+export const setPendingAnchor = StateEffect.define<{ anchor: number; placeholder?: string }>();
+
+/** Append finalized text to the pending buffer; clears the interim tail and placeholder. */
+export const appendPendingText = StateEffect.define<string>();
+
+/** Replace the volatile in-flight tail. */
+export const setPendingInterim = StateEffect.define<string>();
+
+/** Replace the finalized buffer wholesale (e.g. with post-processed text). */
+export const setPendingFinal = StateEffect.define<string>();
+
+/** Discard the pending buffer without modifying the document. */
+export const cancelPendingText = StateEffect.define<void>();
+
+const emptyAt = (anchor: number, placeholder?: string): PendingTextState => ({
+  anchor,
+  final: '',
+  interim: '',
+  placeholder,
+});
+
+export const pendingTextState = StateField.define<PendingTextState | null>({
+  create: () => null,
+  update: (value, tr) => {
+    // Map the anchor through document changes so injected text lands at the right place.
+    let next = value && tr.docChanged ? { ...value, anchor: tr.changes.mapPos(value.anchor) } : value;
+    for (const effect of tr.effects) {
+      if (effect.is(setPendingAnchor)) {
+        next = emptyAt(effect.value.anchor, effect.value.placeholder);
+      } else if (effect.is(appendPendingText)) {
+        const base = next ?? emptyAt(tr.state.selection.main.head);
+        next = { ...base, final: base.final + effect.value, interim: '', placeholder: undefined };
+      } else if (effect.is(setPendingInterim)) {
+        const base = next ?? emptyAt(tr.state.selection.main.head);
+        next = { ...base, interim: effect.value };
+      } else if (effect.is(setPendingFinal)) {
+        // Replace the EXISTING buffer only; never resurrect a cancelled/empty session. This lets a
+        // late post-process result (e.g. entity linking) be dropped if the user cancelled meanwhile.
+        if (next) {
+          next = { ...next, final: effect.value, placeholder: undefined };
+        }
+      } else if (effect.is(cancelPendingText)) {
+        next = null;
+      }
+    }
+
+    return next;
+  },
+});
+
+const hasContent = (value: PendingTextState): boolean =>
+  value.final.length > 0 || value.interim.length > 0 || (value.placeholder?.length ?? 0) > 0;
+
+//
+// Commands.
+//
+
+/**
+ * Insert the finalized pending text into the document and clear the buffer. The text is terminated
+ * with a newline; when committed at the end of the document an extra newline is added so the document
+ * always ends with a blank line.
+ */
+export const commitPending: Command = (view) => {
+  const value = view.state.field(pendingTextState, false);
+  if (!value || value.final.length === 0) {
+    return false;
+  }
+
+  const atEnd = value.anchor >= view.state.doc.length;
+  const insert = value.final + (atEnd ? '\n\n' : '\n');
+  view.dispatch({
+    // Place the cursor on the line after the inserted text (before the trailing blank line).
+    changes: { from: value.anchor, insert },
+    selection: { anchor: value.anchor + value.final.length + 1 },
+    effects: cancelPendingText.of(),
+  });
+  return true;
+};
+
+/** Discard the pending text without modifying the document. */
+export const cancelPending: Command = (view) => {
+  if (!view.state.field(pendingTextState, false)) {
+    return false;
+  }
+
+  view.dispatch({ effects: cancelPendingText.of() });
+  return true;
+};
+
+// Commit when there is finalized text, otherwise just consume the key so the editor's default
+// newline insertion cannot mutate the document mid-session (e.g. placeholder/interim-only state).
+const commitOrConsumePending: Command = (view) => {
+  const value = view.state.field(pendingTextState, false);
+  if (!value) {
+    return false;
+  }
+
+  return value.final.length > 0 ? commitPending(view) : true;
+};
+
+//
+// Decorations.
+//
+
+// Finalized + interim text share one teal marker (a single transcription); the placeholder uses a
+// rose marker with a pulsing icon to signal active recording.
+const TEXT_HUE: MarkerHue = 'teal';
+const PLACEHOLDER_HUE: MarkerHue = 'rose';
+
+class PendingTextWidget extends WidgetType {
+  constructor(private readonly _state: PendingTextState) {
+    super();
+  }
+
+  override eq(other: PendingTextWidget): boolean {
+    return (
+      other._state.final === this._state.final &&
+      other._state.interim === this._state.interim &&
+      other._state.placeholder === this._state.placeholder
+    );
+  }
+
+  override toDOM(view: EditorView): HTMLElement {
+    const root = Domino.of('span').classNames('cm-pending-text');
+    if (this._state.final.length > 0 || this._state.interim.length > 0) {
+      const marker = Domino.of('span').classNames('cm-marker-text').attributes({ 'data-hue': TEXT_HUE });
+      if (this._state.final.length > 0) {
+        marker.append(Domino.of('span').text(this._state.final));
+      }
+      if (this._state.interim.length > 0) {
+        marker.append(Domino.of('span').classNames('cm-pending-text-interim').text(this._state.interim));
+      }
+      root.append(marker);
+    } else if (this._state.placeholder) {
+      root.append(
+        markerText(this._state.placeholder, {
+          hue: PLACEHOLDER_HUE,
+          className: 'cm-pending-text-indicator',
+          icon: 'ph--circle-notch--regular',
+          iconClassNames: 'animate-spin',
+        }),
+      );
+    }
+
+    root.append(
+      markerButtons([
+        {
+          icon: 'ph--check--regular',
+          label: 'Confirm',
+          className: 'cm-marker-button-success',
+          testId: 'pending-text.confirm',
+          onClick: () => commitPending(view),
+        },
+        {
+          icon: 'ph--x--regular',
+          label: 'Cancel',
+          className: 'cm-marker-button-error',
+          testId: 'pending-text.cancel',
+          onClick: () => cancelPending(view),
+        },
+      ]),
+    );
+    return root.root;
+  }
+
+  override ignoreEvent(): boolean {
+    return true;
+  }
+}
+
+const pendingDecorations = EditorView.decorations.compute([pendingTextState], (state) => {
+  const value = state.field(pendingTextState);
+  if (!value || !hasContent(value)) {
+    return Decoration.none;
+  }
+
+  return Decoration.set([Decoration.widget({ widget: new PendingTextWidget(value), side: 1 }).range(value.anchor)]);
+});
+
+// Flag the editor busy while a pending session is active so other extensions (e.g. the command-hint
+// placeholder) suppress themselves. Deferred to a microtask to avoid dispatching mid-update.
+const busyListener = EditorView.updateListener.of((update) => {
+  const active = update.state.field(pendingTextState) != null;
+  if (active === (update.startState.field(pendingTextState) != null)) {
+    return;
+  }
+  queueMicrotask(() => {
+    if ((update.view.state.field(pendingTextState) != null) === active) {
+      update.view.dispatch({ effects: setBusy.of(active) });
+    }
+  });
+});
+
+const styles = EditorView.theme({
+  // Keep the marker and affordances on a single line (it already sits on its own line at the anchor).
+  '.cm-pending-text': {
+    display: 'inline-flex',
+    alignItems: 'center',
+    gap: '0.5rem',
+  },
+  // The interim tail is distinguished from the finalized text only by reduced opacity.
+  '.cm-pending-text-interim': {
+    opacity: 0.6,
+  },
+  // Keep the "Recording…" indicator (text + spinner) on a single line.
+  '.cm-pending-text-indicator': {
+    whiteSpace: 'nowrap',
+  },
+});
+
+//
+// Extension.
+//
+
+/**
+ * Renders externally-supplied "pending" text as an inline preview at a tracked anchor, with inline
+ * confirm/cancel affordances. An external controller drives the buffer via the `setPendingAnchor` /
+ * `appendPendingText` / `setPendingInterim` / `cancelPendingText` effects; the user commits or
+ * discards it via the affordances or the Enter/Escape keys. While a session is active the editor is
+ * flagged {@link busy} so hint placeholders suppress themselves. The extension is agnostic to the
+ * source of the text (e.g. speech transcription), so any CodeMirror component can opt in.
+ */
+export const pendingText = (): Extension => [
+  pendingTextState,
+  busy(),
+  pendingDecorations,
+  busyListener,
+  markerTheme(),
+  styles,
+  keymap.of([
+    { key: 'Enter', run: commitOrConsumePending },
+    { key: 'Escape', run: cancelPending },
+  ]),
+];

package/src/extensions/pos.test.ts

@@ -0,0 +1,97 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { EditorState } from '@codemirror/state';
+import { EditorView } from '@codemirror/view';
+import { describe, test } from 'vitest';
+
+import { type Document, sourceHash } from '@dxos/nlp';
+
+import { clearAnalysis, pos, posAnalysisField, posDecorations, posSpans, setAnalysis, spanDiverged } from './pos';
+
+describe('posAnalysisField', () => {
+  const make = (doc = 'hello world') => EditorState.create({ doc, extensions: [posAnalysisField] });
+
+  test('setAnalysis adds a span', ({ expect }) => {
+    const state = make().update({ effects: setAnalysis.of({ from: 0, to: 5, document: docFor('hello') }) }).state;
+    expect(posSpans(state)).toHaveLength(1);
+    expect(posSpans(state)[0]).toMatchObject({ from: 0, to: 5, stale: false });
+  });
+
+  test('span offsets are mapped through an insertion before them', ({ expect }) => {
+    const withSpan = make().update({ effects: setAnalysis.of({ from: 6, to: 11, document: docFor('world') }) }).state;
+    const afterEdit = withSpan.update({ changes: { from: 0, insert: 'XXX' } }).state;
+    expect(posSpans(afterEdit)[0]).toMatchObject({ from: 9, to: 14 });
+  });
+
+  test('clearAnalysis removes all spans', ({ expect }) => {
+    const withSpan = make().update({ effects: setAnalysis.of({ from: 0, to: 5, document: docFor('hello') }) }).state;
+    const cleared = withSpan.update({ effects: clearAnalysis.of(null) }).state;
+    expect(posSpans(cleared)).toHaveLength(0);
+  });
+});
+
+describe('posDecorations', () => {
+  test('emits decorations for the analyzed tokens', ({ expect }) => {
+    const text = 'hello world';
+    let state = EditorState.create({ doc: text, extensions: [posAnalysisField, posDecorations] });
+    const document: Document = {
+      sourceHash: 'deadbeef',
+      sentences: [
+        {
+          index: 0,
+          start: 0,
+          end: 11,
+          tokens: [
+            { index: 0, text: 'hello', upos: 'INTJ', start: 0, end: 5 },
+            { index: 1, text: 'world', upos: 'NOUN', start: 6, end: 11 },
+          ],
+        },
+      ],
+    };
+    state = state.update({ effects: setAnalysis.of({ from: 0, to: 11, document }) }).state;
+    const sources = state.facet(EditorView.decorations);
+    expect(sources.length).toBeGreaterThan(0);
+  });
+});
+
+describe('pos reactive initial parse', () => {
+  test('parses existing content on mount (decorates without an edit)', async ({ expect }) => {
+    const text = 'hello world';
+    const fakeParse = async (input: string): Promise<Document> => docFor(input);
+    const view = new EditorView({ doc: text, extensions: [pos({ parse: fakeParse })] });
+    try {
+      // The mount parse and its dispatch run as microtasks (no timer); drain the queue rather than
+      // sleeping so the assertion is deterministic.
+      await flushMicrotasks();
+      expect(posSpans(view.state).length).toBe(1);
+      expect(posSpans(view.state)[0]).toMatchObject({ from: 0, to: text.length });
+    } finally {
+      view.destroy();
+    }
+  });
+});
+
+describe('spanDiverged', () => {
+  test('detects when live span text no longer matches the stored hash', ({ expect }) => {
+    const span = { from: 0, to: 5, sourceHash: sourceHash('hello'), document: docFor('hello'), stale: false };
+    expect(spanDiverged('hello world', span)).toBe(false);
+    expect(spanDiverged('hELLo world', span)).toBe(true);
+  });
+});
+
+/** A minimal single-token `Document` whose hash matches `text`. */
+const docFor = (text: string): Document => ({
+  sourceHash: sourceHash(text),
+  sentences: [
+    { index: 0, start: 0, end: text.length, tokens: [{ index: 0, text, upos: 'NOUN', start: 0, end: text.length }] },
+  ],
+});
+
+/** Drain the microtask queue so chained `.then` callbacks settle without a real timer. */
+const flushMicrotasks = async (ticks = 4): Promise<void> => {
+  for (let index = 0; index < ticks; index++) {
+    await Promise.resolve();
+  }
+};