@dxos/ui-editor 0.10.0 → 0.11.1

package/src/extensions/{marker.ts → decoration/marker.ts}

@@ -6,7 +6,7 @@ import { type Extension } from '@codemirror/state';
 import { Decoration, EditorView } from '@codemirror/view';
 
 import { Domino } from '@dxos/ui';
-import { hues } from '@dxos/ui-theme';
+import { hues } from '@dxos/ui-types';
 import { type ChromaticPalette } from '@dxos/ui-types';
 
 /**
@@ -16,21 +16,6 @@ import { type ChromaticPalette } from '@dxos/ui-types';
  */
 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.
@@ -39,12 +24,14 @@ 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]: {
+    // No `border-radius`: with `box-decoration-break: clone` every wrapped fragment would round its
+    // own corners, pinching the left/right edges of a multi-line span into jagged notches. Square
+    // corners let the per-line boxes stack into one continuous block with straight vertical edges.
+    '.cm-marker > span, .cm-marker-text': {
       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': {
@@ -141,3 +128,16 @@ export const markerButtons = (buttons: MarkerButton[]): Domino<HTMLElement> =>
           }),
       ),
     );
+
+// 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)`,
+      },
+    ]),
+  ),
+);

package/src/extensions/{pos.test.ts → decoration/pos.test.ts}

@@ -8,7 +8,16 @@ import { describe, test } from 'vitest';
 
 import { type Document, sourceHash } from '@dxos/nlp';
 
-import { clearAnalysis, pos, posAnalysisField, posDecorations, posSpans, setAnalysis, spanDiverged } from './pos';
+import {
+  clearAnalysis,
+  pos,
+  posAnalysisField,
+  posDecorations,
+  posSpans,
+  posTokenAt,
+  setAnalysis,
+  spanDiverged,
+} from './pos';
 
 describe('posAnalysisField', () => {
   const make = (doc = 'hello world') => EditorState.create({ doc, extensions: [posAnalysisField] });
@@ -73,6 +82,53 @@ describe('pos reactive initial parse', () => {
   });
 });
 
+describe('posTokenAt', () => {
+  const analyzed = () => {
+    const text = 'XX hello world';
+    // Span starts at 3 so absolute token offsets exercise the span-relative mapping.
+    const document: Document = {
+      sourceHash: sourceHash('hello world'),
+      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 },
+          ],
+        },
+      ],
+    };
+    return EditorState.create({ doc: text, extensions: [posAnalysisField] }).update({
+      effects: setAnalysis.of({ from: 3, to: 14, document }),
+    }).state;
+  };
+
+  test('resolves the token covering an absolute position', ({ expect }) => {
+    const state = analyzed();
+    expect(posTokenAt(state, 4)).toMatchObject({ from: 3, to: 8, upos: 'INTJ', stale: false });
+    expect(posTokenAt(state, 9)).toMatchObject({ from: 9, to: 14, upos: 'NOUN' });
+  });
+
+  test('returns undefined outside analyzed tokens', ({ expect }) => {
+    const state = analyzed();
+    expect(posTokenAt(state, 0)).toBeUndefined(); // Before the span.
+    expect(posTokenAt(state, 8)).toBeUndefined(); // Inter-token whitespace.
+  });
+});
+
+describe('pos options', () => {
+  test('popover option mounts alongside the underline default', ({ expect }) => {
+    // Both presentations are independent extensions; constructing a state with each combination
+    // must not throw and must retain the analysis field.
+    for (const options of [{ popover: true }, { underline: false, popover: true }, { underline: false }]) {
+      const state = EditorState.create({ doc: 'hello', extensions: [pos(options)] });
+      expect(posSpans(state)).toEqual([]);
+    }
+  });
+});
+
 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 };

package/src/extensions/{pos.ts → decoration/pos.ts}

@@ -3,11 +3,45 @@
 //
 
 import { type EditorState, type Extension, RangeSetBuilder, StateEffect, StateField } from '@codemirror/state';
-import { Decoration, EditorView, ViewPlugin, type ViewUpdate } from '@codemirror/view';
+import { Decoration, EditorView, ViewPlugin, type ViewUpdate, hoverTooltip } from '@codemirror/view';
 
 import { debounce } from '@dxos/async';
 import { type Document, type Upos, sourceHash } from '@dxos/nlp';
 
+export type PosOptions = {
+  /** When set, the extension self-parses on idle and dispatches `setAnalysis`. */
+  parse?: (text: string) => Promise<Document>;
+  /** Idle debounce before reactive parsing (ms). */
+  debounceMs?: number;
+  /** Colored underline per UPOS tag (default true). */
+  underline?: boolean;
+  /** Hover popover naming the part of speech (default false). */
+  popover?: boolean;
+};
+
+/**
+ * Part-of-speech decoration extension.
+ * Renders per-word UPOS marks from analysis state held in a span-oriented state field, with
+ * independently switchable presentations: a colored underline per tag ({@link posTheme}) and a
+ * hover popover naming the part of speech ({@link posPopover}). State can be set externally via
+ * `setAnalysis`/`clearAnalysis`, or — when `options.parse` is supplied — self-driven on idle
+ * (reactive mode).
+ */
+export const pos = ({ parse, debounceMs = 500, underline = true, popover = false }: PosOptions = {}): Extension => {
+  const extensions: Extension[] = [posAnalysisField, posDecorations, staleTheme];
+  if (underline) {
+    extensions.push(posTheme());
+  }
+  if (popover) {
+    extensions.push(posPopover());
+  }
+  if (parse) {
+    extensions.push(reactiveDriver(parse, debounceMs));
+  }
+
+  return extensions;
+};
+
 /** One analyzed region of the document. `document` offsets are relative to the span's own text. */
 export type PosSpan = {
   from: number;
@@ -28,6 +62,10 @@ export const clearAnalysis = StateEffect.define<null>();
 /** Internal: mark a span stale (dispatched by the reactive driver on divergence). */
 export const markStale = StateEffect.define<{ from: number; to: number }>();
 
+/**
+ * StateField holding the span-oriented part-of-speech analysis.
+ * Included by {@link pos}; exported for reads via {@link posSpans}.
+ */
 export const posAnalysisField = StateField.define<PosSpan[]>({
   create: () => [],
   update: (spans, tr) => {
@@ -67,6 +105,10 @@ export const posSpans = (state: EditorState): PosSpan[] => state.field(posAnalys
 const posMark = (upos: Upos, stale: boolean) =>
   Decoration.mark({ class: ['cm-pos', `cm-pos-${upos}`, stale && 'cm-pos-stale'].filter(Boolean).join(' ') });
 
+/**
+ * Computes UPOS decoration marks from the analysis field.
+ * Included by {@link pos}.
+ */
 export const posDecorations = EditorView.decorations.compute([posAnalysisField], (state) => {
   const builder = new RangeSetBuilder<Decoration>();
   const spans = state.field(posAnalysisField);
@@ -109,29 +151,89 @@ const POS_HUE: Partial<Record<Upos, string>> = {
   PART: 'neutral',
 };
 
-export const posTheme = (): Extension =>
-  EditorView.theme({
-    '.cm-pos': { borderRadius: '0.125rem' },
-    ...Object.fromEntries(
-      Object.entries(POS_HUE).map(([upos, hue]) => [
-        `.cm-pos-${upos}`,
-        { borderBottom: `2px solid var(--color-${hue}-500)` },
-      ]),
-    ),
-    '.cm-pos-stale': { opacity: '0.4' },
-  });
+/** Human-readable UPOS names (https://universaldependencies.org/u/pos/), shown in the hover popover. */
+const UPOS_LABEL: Record<Upos, string> = {
+  ADJ: 'adjective',
+  ADP: 'adposition',
+  ADV: 'adverb',
+  AUX: 'auxiliary',
+  CCONJ: 'coordinating conjunction',
+  DET: 'determiner',
+  INTJ: 'interjection',
+  NOUN: 'noun',
+  NUM: 'numeral',
+  PART: 'particle',
+  PRON: 'pronoun',
+  PROPN: 'proper noun',
+  PUNCT: 'punctuation',
+  SCONJ: 'subordinating conjunction',
+  SYM: 'symbol',
+  VERB: 'verb',
+  X: 'other',
+};
+
+export type PosToken = {
+  from: number;
+  to: number;
+  upos: Upos;
+  stale: boolean;
+};
+
+/** Resolve the analyzed token covering an absolute document position, if any. */
+export const posTokenAt = (state: EditorState, position: number): PosToken | undefined => {
+  const spans = state.field(posAnalysisField, false) ?? [];
+  for (const span of spans) {
+    if (position < span.from || position > span.to) {
+      continue;
+    }
+    for (const sentence of span.document.sentences) {
+      for (const token of sentence.tokens) {
+        const from = span.from + token.start;
+        const to = span.from + token.end;
+        if (position >= from && position < to && to <= state.doc.length) {
+          return { from, to, upos: token.upos, stale: span.stale };
+        }
+      }
+    }
+  }
+  return undefined;
+};
+
+/** Hover popover naming the part of speech of the token under the pointer. */
+export const posPopover = (): Extension => [
+  hoverTooltip((view, position) => {
+    const token = posTokenAt(view.state, position);
+    if (!token) {
+      return null;
+    }
+    return {
+      pos: token.from,
+      end: token.to,
+      above: true,
+      create: () => {
+        const dom = document.createElement('div');
+        dom.className = 'cm-pos-popover';
+        const swatch = document.createElement('span');
+        swatch.className = 'cm-pos-swatch';
+        swatch.style.background = `var(--color-${POS_HUE[token.upos] ?? 'neutral'}-500)`;
+        const tag = document.createElement('span');
+        tag.className = 'cm-pos-popover-tag';
+        tag.textContent = token.upos;
+        const label = document.createElement('span');
+        label.className = 'cm-pos-popover-label';
+        label.textContent = UPOS_LABEL[token.upos];
+        dom.append(swatch, tag, label);
+        return { dom };
+      },
+    };
+  }),
+  popoverTheme,
+];
 
 /** A span has diverged when the current text under its (mapped) range no longer matches its hash. */
 export const spanDiverged = (docText: string, span: { from: number; to: number; sourceHash: string }): boolean =>
   sourceHash(docText.slice(span.from, span.to)) !== span.sourceHash;
 
-export type PosOptions = {
-  /** When set, the extension self-parses on idle and dispatches `setAnalysis`. */
-  parse?: (text: string) => Promise<Document>;
-  /** Idle debounce before reactive parsing (ms). */
-  debounceMs?: number;
-};
-
 /**
  * Reactive driver: on doc change, mark edit-touched spans stale (immediate visual feedback), then
  * after idle re-parse and dispatch fresh analysis. Re-hashing is bounded to spans overlapping the
@@ -192,15 +294,47 @@ const reactiveDriver = (parse: NonNullable<PosOptions['parse']>, debounceMs: num
   return [initial, onEdit];
 };
 
-/**
- * Part-of-speech decoration extension. Renders per-word UPOS marks from analysis state held in a
- * span-oriented state field. State can be set externally via `setAnalysis`/`clearAnalysis`, or — when
- * `options.parse` is supplied — self-driven on idle (reactive mode).
- */
-export const pos = (options: PosOptions = {}): Extension => {
-  const extensions: Extension[] = [posAnalysisField, posDecorations, posTheme()];
-  if (options.parse) {
-    extensions.push(reactiveDriver(options.parse, options.debounceMs ?? 500));
-  }
-  return extensions;
-};
+/** Colored underline per UPOS tag (stale dimming lives in the always-on base theme). */
+export const posTheme = (): Extension =>
+  EditorView.theme({
+    '.cm-pos': {
+      borderRadius: '0.125rem',
+    },
+    ...Object.fromEntries(
+      Object.entries(POS_HUE).map(([upos, hue]) => [
+        `.cm-pos-${upos}`,
+        {
+          borderBottom: `2px solid var(--color-${hue}-500)`,
+        },
+      ]),
+    ),
+  });
+
+// Stale dimming must apply even when the underline theme is disabled (e.g. popover-only mode), so a
+// diverged span never presents confident decorations.
+const staleTheme = EditorView.theme({
+  '.cm-pos-stale': {
+    opacity: '0.4',
+  },
+});
+
+const popoverTheme = EditorView.theme({
+  '.cm-pos-popover': {
+    display: 'flex',
+    alignItems: 'center',
+    gap: '6px',
+    padding: '2px 6px',
+  },
+  '.cm-pos-swatch': {
+    width: '8px',
+    height: '8px',
+    borderRadius: '2px',
+    flexShrink: '0',
+  },
+  '.cm-pos-popover-tag': {
+    fontWeight: '600',
+  },
+  '.cm-pos-popover-label': {
+    opacity: '0.7',
+  },
+});

package/src/extensions/{blast.ts → demo/blast.ts}

@@ -37,6 +37,9 @@ export const defaultOptions: BlastOptions = {
   shakeIntensity: 5,
 };
 
+/**
+ * Particle 'code blast' cursor effect (demo/novelty).
+ */
 export const blast = (options: Partial<BlastOptions> = defaultOptions): Extension => {
   let blaster: Blaster | undefined;
   let last = 0;

package/src/extensions/demo/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './blast';
+export * from './snippets';

package/src/extensions/{snippets.ts → demo/snippets.ts}

@@ -38,8 +38,12 @@ export const snippets = ({ delay = 75, items = defaultItems }: SnippetsOptions =
         run: (view) => {
           clearTimeout(timer);
           // TODO(burdon): Add space if needed.
+          if (items.length === 0) {
+            return false;
+          }
+
           const text = items[index++];
-          if (index === items?.length) {
+          if (index >= items.length) {
             index = 0;
           }
 

package/src/extensions/index.ts

@@ -2,38 +2,15 @@
 // Copyright 2023 DXOS.org
 //
 
-export * from './annotations';
-export * from './autocomplete';
-export * from './automerge';
-export * from './awareness';
-export * from './blast';
-export * from './blocks';
-export * from './bookmarks';
-export * from './busy';
-export * from './comments';
+export * from './behavior';
+export * from './collab';
+export * from './completion';
+export * from './core';
 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 './pending';
-export * from './pos';
-export * from './replacer';
-export * from './scrolling';
-export * from './selection';
-export * from './spacing';
-export * from './snippets';
+export * from './decoration';
+export * from './demo';
+export * from './language';
+export * from './review';
 export * from './state';
-export * from './submit';
-export * from './tags';
-export * from './typewriter';
+export * from './streaming';
+export * from './structure';

package/src/extensions/language/index.ts

@@ -0,0 +1,8 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './json';
+export * from './markdown';
+export * from './mermaid';
+export * from './xml';

package/src/extensions/language/json/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './json';

package/src/extensions/{json.ts → language/json/json.ts}

@@ -2,18 +2,23 @@
 // Copyright 2025 DXOS.org
 //
 
-import { json, jsonParseLinter } from '@codemirror/lang-json';
+import { json as jsonLanguage, jsonParseLinter } from '@codemirror/lang-json';
 import { type LintSource, linter } from '@codemirror/lint';
 import { type Extension } from '@codemirror/state';
 import Ajv, { type ValidateFunction } from 'ajv';
 
 import { type JsonSchema as JsonSchemaType } from '@dxos/echo/JsonSchema';
 
-export type JsonExtensionsOptions = {
+export type JsonOptions = {
   schema?: JsonSchemaType;
 };
 
-export const createJsonExtensions = ({ schema }: JsonExtensionsOptions = {}): Extension => {
+/**
+ * JSON editing extension: the JSON language (syntax highlighting, folding, bracket matching) plus a
+ * linter. When `schema` (a JSON Schema) is given the linter validates against it; otherwise it reports
+ * only parse errors.
+ */
+export const json = ({ schema }: JsonOptions = {}): Extension => {
   let lintSource: LintSource = jsonParseLinter();
   if (schema) {
     // NOTE: Relaxing strict mode to allow additional custom schema properties.
@@ -22,7 +27,7 @@ export const createJsonExtensions = ({ schema }: JsonExtensionsOptions = {}): Ex
     lintSource = schemaLinter(validate);
   }
 
-  return [json(), linter(lintSource)];
+  return [jsonLanguage(), linter(lintSource)];
 };
 
 const schemaLinter =
@@ -37,7 +42,7 @@ const schemaLinter =
       }
 
       return (
-        validate.errors?.map((err: any) => ({
+        validate.errors?.map((err) => ({
           from: 0,
           to: jsonText.length,
           severity: 'error',
@@ -50,7 +55,7 @@ const schemaLinter =
           from: 0,
           to: view.state.doc.length,
           severity: 'error',
-          message: 'Invalid JSON: ' + (err as Error).message,
+          message: 'Invalid JSON: ' + (err instanceof Error ? err.message : String(err)),
         },
       ];
     }

package/src/extensions/{markdown → language/markdown}/action.ts

@@ -7,7 +7,7 @@ import { type EditorView } from '@codemirror/view';
 import { type Node } from '@dxos/app-graph';
 import { type MenuActionProperties } from '@dxos/ui-types';
 
-import { createComment } from '../comments';
+import { createComment } from '../../review/comments';
 import {
   Inline,
   List,

package/src/extensions/{markdown → language/markdown}/bundle.ts

@@ -11,9 +11,11 @@ import { languages } from '@codemirror/language-data';
 import { type Extension } from '@codemirror/state';
 import { keymap } from '@codemirror/view';
 import { type MarkdownConfig } from '@lezer/markdown';
+import { mermaidLanguageDescription } from 'codemirror-lang-mermaid';
 
 import { isTruthy } from '@dxos/util';
 
+import { mermaidHighlightStyle } from '../mermaid';
 import { markdownHighlightStyle, markdownTagsExtensions } from './highlight';
 
 export type MarkdownBundleOptions = {
@@ -47,8 +49,10 @@ export const createMarkdownExtensions = (options: MarkdownBundleOptions = {}): E
 
       // Languages for syntax highlighting fenced code blocks.
       // Caller-supplied languages are checked first so they can override defaults.
+      // Mermaid is registered here rather than by plugin-mermaid: `codeLanguages` is read once when
+      // the parser is built, so an extension contributed later cannot add a fenced-code language.
       defaultCodeLanguage: jsonLanguage,
-      codeLanguages: [...(options.codeLanguages ?? []), ...languages],
+      codeLanguages: [...(options.codeLanguages ?? []), mermaidLanguageDescription, ...languages],
 
       // Don't complete HTML tags.
       completeHTMLTags: false,
@@ -66,6 +70,8 @@ export const createMarkdownExtensions = (options: MarkdownBundleOptions = {}): E
     }),
 
     // Custom styles.
+    // Fenced mermaid uses custom tags, so it needs its own style alongside markdown's.
+    syntaxHighlighting(mermaidHighlightStyle()),
     syntaxHighlighting(markdownHighlightStyle()),
 
     keymap.of(

package/src/extensions/{markdown → language/markdown}/changes.test.ts

@@ -2,7 +2,7 @@
 // Copyright 2024 DXOS.org
 //
 
-import { describe, expect, test } from 'vitest';
+import { describe, test } from 'vitest';
 
 import { createLinkLabel } from './changes';
 
@@ -18,7 +18,7 @@ const testCases = [
 ];
 
 describe('changes', () => {
-  test('createLinkLabel', () => {
+  test('createLinkLabel', ({ expect }) => {
     testCases.forEach(({ input, expected }) => {
       expect(createLinkLabel(new URL(input))).to.eq(expected);
     });

package/src/extensions/{markdown → language/markdown}/changes.ts

@@ -6,10 +6,10 @@ import { syntaxTree } from '@codemirror/language';
 import { type ChangeSpec, Transaction } from '@codemirror/state';
 import { type PluginValue, ViewPlugin, type ViewUpdate } from '@codemirror/view';
 
+// TODO(burdon): Tests.
 /**
- * Monitors and augments changes.
+ * ViewPlugin that augments input and paste: auto-links pasted URLs and fixes task markers.
  */
-// TODO(burdon): Tests.
 export const adjustChanges = () => {
   return ViewPlugin.fromClass(
     class implements PluginValue {

package/src/extensions/{markdown → language/markdown}/debug.ts

@@ -6,6 +6,9 @@ import { syntaxTree } from '@codemirror/language';
 import { type EditorState, type Extension, StateField } from '@codemirror/state';
 import { type TreeCursor } from '@lezer/common';
 
+/**
+ * StateField that serialises the syntax tree to JSON and invokes the callback on every state change (debug only).
+ */
 export const debugTree = (cb: (tree: DebugNode) => void): Extension =>
   StateField.define({
     create: (state) => cb(convertTreeToJson(state)),