@dxos/ui-editor 0.0.0 → 0.8.4-main.1c7ec43d41

package/src/typings.d.ts

@@ -0,0 +1,8 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+declare module '*.md?raw' {
+  const content: string;
+  export default content;
+}

package/src/util/cursor.ts

@@ -5,7 +5,6 @@
 import { type EditorState } from '@codemirror/state';
 
 import { type Range } from '../types';
-
 import { singleValueFacet } from './facet';
 
 /**
@@ -26,7 +25,7 @@ export const overlap = (a: Range, b: Range): boolean => a.from <= b.to && a.to >
  *  while positive - with the next one.
  */
 export interface CursorConverter {
-  toCursor(position: number, assoc?: -1 | 1 | undefined): string;
+  toCursor(position: number, assoc?: -1 | 1): string;
   fromCursor(cursor: string): number;
 }
 

package/src/extensions/autoscroll.ts

@@ -1,165 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import { StateEffect } from '@codemirror/state';
-import { EditorView, ViewPlugin } from '@codemirror/view';
-
-import { debounce } from '@dxos/async';
-import { Domino } from '@dxos/ui';
-
-import { scrollToLineEffect } from './scrolling';
-
-// TODO(burdon): Reconcile with scrollToLineEffect (scrolling).
-export const scrollToBottomEffect = StateEffect.define<ScrollBehavior | undefined>();
-
-export type AutoScrollOptions = {
-  /** Auto-scroll when reaches the bottom. */
-  autoScroll?: boolean;
-  /** Threshold in px to trigger scroll from bottom. */
-  threshold?: number;
-  /** Throttle time in ms. */
-  throttleDelay?: number;
-  /** Callback when auto-scrolling. */
-  onAutoScroll?: (props: { view: EditorView; distanceFromBottom: number }) => boolean | void;
-};
-
-/**
- * Extension that supports pinning the scroll position and automatically scrolls to the bottom when content is added.
- */
-// TODO(burdon): Reconcile with transcript-extension.
-export const autoScroll = ({
-  autoScroll = true,
-  threshold = 100,
-  throttleDelay = 1_000,
-  onAutoScroll,
-}: Partial<AutoScrollOptions> = {}) => {
-  let buttonContainer: HTMLDivElement | undefined;
-  let hideTimeout: NodeJS.Timeout | undefined;
-  let lastScrollTop = 0;
-  let isPinned = true;
-
-  const setPinned = (pin: boolean) => {
-    isPinned = pin;
-    buttonContainer?.classList.toggle('opacity-0', pin);
-  };
-
-  // Temporarily hide the scrollbar while auto-scrolling.
-  const hideScrollbar = (view: EditorView) => {
-    view.scrollDOM.classList.add('cm-hide-scrollbar');
-    clearTimeout(hideTimeout);
-    hideTimeout = setTimeout(() => {
-      view.scrollDOM.classList.remove('cm-hide-scrollbar');
-    }, 1_000);
-  };
-
-  // Throttled scroll to bottom.
-  const scrollToBottom = (view: EditorView, behavior?: ScrollBehavior) => {
-    setPinned(true);
-    hideScrollbar(view);
-    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', offset: threshold, behavior },
-      }),
-    });
-  };
-
-  // Throttled check for distance from bottom (for downward scrolls only).
-  const checkDistance = debounce((view: EditorView) => {
-    const scrollerRect = view.scrollDOM.getBoundingClientRect();
-    const coords = view.coordsAtPos(view.state.doc.length);
-    const distanceFromBottom = coords ? coords.bottom - scrollerRect.bottom : 0;
-    setPinned(distanceFromBottom < 0);
-  }, 1_000);
-
-  // Debounce scroll updates so rapid edits don't cause clunky scrolling.
-  const triggerUpdate = debounce((view: EditorView) => scrollToBottom(view), throttleDelay);
-
-  return [
-    // Update listener for logging when scrolling is needed.
-    EditorView.updateListener.of(({ view, transactions, heightChanged }) => {
-      // TODO(burdon): Remove and use scrollToLineEffect instead.
-      transactions.forEach((transaction) => {
-        for (const effect of transaction.effects) {
-          if (effect.is(scrollToBottomEffect)) {
-            scrollToBottom(view, effect.value);
-          }
-        }
-      });
-
-      // Maybe scroll if doc changed and pinned.
-      // NOTE: Geometry changed is triggered when widgets change height (e.g., toggle tool block).
-      if (heightChanged && isPinned) {
-        const coords = view.coordsAtPos(view.state.doc.length);
-        const scrollerRect = view.scrollDOM.getBoundingClientRect();
-        const distanceFromBottom = coords ? scrollerRect.bottom - coords.bottom : 0;
-        if (autoScroll && distanceFromBottom < threshold) {
-          const shouldScroll = onAutoScroll?.({ view, distanceFromBottom }) ?? true;
-          if (shouldScroll) {
-            triggerUpdate(view);
-          }
-        } else if (distanceFromBottom < 0) {
-          setPinned(false);
-        }
-      }
-    }),
-
-    // Detect user scroll.
-    EditorView.domEventHandlers({
-      scroll: (event, view) => {
-        const currentScrollTop = view.scrollDOM.scrollTop;
-        const scrollingUp = currentScrollTop < lastScrollTop;
-        lastScrollTop = currentScrollTop;
-
-        // If user scrolls up, immediately unpin auto-scroll.
-        if (scrollingUp) {
-          setPinned(false);
-        } else {
-          checkDistance(view);
-        }
-      },
-    }),
-
-    // Scroll button.
-    ViewPlugin.fromClass(
-      class {
-        constructor(view: EditorView) {
-          const icon = Domino.of('dx-icon' as any).attributes({ icon: 'ph--arrow-down--regular' });
-          const button = Domino.of('button')
-            .classNames('dx-button bg-accentSurface')
-            .attributes({ 'data-density': 'fine' })
-            .children(icon)
-            .on('click', () => {
-              scrollToBottom(view);
-            });
-          buttonContainer = Domino.of('div')
-            .classNames('cm-scroll-button transition-opacity duration-300 opacity-0')
-            .children(button).root as HTMLDivElement;
-
-          view.scrollDOM.parentElement!.appendChild(buttonContainer);
-        }
-      },
-    ),
-
-    // Styles.
-    EditorView.theme({
-      '.cm-scroller': {
-        scrollbarWidth: 'thin',
-      },
-      '.cm-scroller.cm-hide-scrollbar': {
-        scrollbarWidth: 'none',
-      },
-      '.cm-scroller.cm-hide-scrollbar::-webkit-scrollbar': {
-        display: 'none',
-      },
-      '.cm-scroll-button': {
-        position: 'absolute',
-        bottom: '0.5rem',
-        right: '1rem',
-      },
-    }),
-  ];
-};

package/src/extensions/scrolling.ts

@@ -1,189 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import { StateEffect } from '@codemirror/state';
-import { EditorView, ViewPlugin } from '@codemirror/view';
-
-/**
- * Configuration options for smooth scrolling behavior.
- */
-export type SmoothScrollOptions = {
-  /**
-   * Additional offset from the target line in pixels.
-   * Positive values scroll past the line, negative values stop before it.
-   * @default 0
-   */
-  offset?: number;
-  /**
-   * Position of the target line in the viewport.
-   * - 'start': Line appears at the start (top) of the screen
-   * - 'end': Line appears at the end (bottom) of the screen
-   * @default 'start'
-   */
-  position?: 'start' | 'end';
-  /**
-   * Whether to use smooth scrolling.
-   * @default 'smooth'
-   */
-  behavior?: ScrollBehavior;
-};
-
-/**
- * Parameters for the scroll to line effect.
- */
-export type ScrollToLineProps = {
-  /**
-   * The line number to scroll to (1-based).
-   */
-  line: number;
-  /**
-   * Optional configuration to override default scroll behavior.
-   */
-  options?: SmoothScrollOptions;
-};
-
-/**
- * StateEffect for triggering smooth scroll to a specific line.
- */
-export const scrollToLineEffect = StateEffect.define<ScrollToLineProps>();
-
-/**
- * Extension that provides smooth scrolling to specific lines in the editor.
- *
- * @example
- * ```typescript
- * // Add to editor extensions.
- * const extensions = [
- *   smoothScroll()
- * ];
- *
- * // Trigger scroll to line 42.
- * view.dispatch({
- *   effects: scrollToLineEffect.of({ line: 42 })
- * });
- *
- * // Scroll with custom options.
- * view.dispatch({
- *   effects: scrollToLineEffect.of({ line: 100, options: { offset: -50 } })
- * });
- *
- * // Scroll so line appears at end (bottom) of screen.
- * view.dispatch({
- *   effects: scrollToLineEffect.of({ line: 50, options: { position: 'end' } })
- * });
- * ```
- */
-export const smoothScroll = ({ offset = 0, position = 'start' }: Partial<SmoothScrollOptions> = {}) => {
-  // ViewPlugin to manage scroll animations.
-  const scrollPlugin = ViewPlugin.fromClass(
-    class SmoothScrollPlugin {
-      constructor(private readonly view: EditorView) {}
-
-      // No-op.
-      destroy() {}
-
-      /**
-       * Perform smooth scroll to the specified line.
-       */
-      scrollToLine(lineNumber: number, options: SmoothScrollOptions) {
-        const { offset: animOffset = 0, position: animPosition, behavior } = options;
-        const doc = this.view.state.doc;
-        const scroller = this.view.scrollDOM;
-
-        // Convert 1-based line number to 0-based.
-        const targetLine = Math.max(0, lineNumber - 1);
-        if (behavior === 'instant') {
-          requestAnimationFrame(() => {
-            this.view.dispatch({
-              selection: { anchor: doc.line(targetLine + 1).from },
-              scrollIntoView: true,
-            });
-          });
-          return;
-        }
-
-        // Get the position of the target line.
-        if (targetLine >= doc.lines) {
-          // Line doesn't exist, scroll to end.
-          const targetScrollTop = scroller.scrollHeight - scroller.clientHeight + (animOffset || 0);
-          this.animateScroll(scroller, targetScrollTop);
-          return;
-        }
-
-        const lineStart = doc.line(targetLine + 1).from;
-        const coords = this.view.coordsAtPos(lineStart);
-        if (!coords) {
-          return;
-        }
-
-        // Calculate target scroll position based on position option.
-        const currentScrollTop = scroller.scrollTop;
-        const scrollerRect = scroller.getBoundingClientRect();
-        const maxScrollTop = scroller.scrollHeight - scroller.clientHeight;
-
-        let targetScrollTop: number;
-        if (animPosition === 'end') {
-          // Position line at end (bottom) of viewport.
-          // Calculate how far down we need to scroll so the line's bottom aligns with viewport bottom.
-          targetScrollTop = currentScrollTop + coords.bottom - scrollerRect.bottom + animOffset;
-        } else {
-          // Default: position line at start (top) of viewport.
-          targetScrollTop = currentScrollTop + coords.top - scrollerRect.top + animOffset;
-        }
-
-        // Clamp to valid scroll range.
-        const clampedScrollTop = Math.max(0, Math.min(targetScrollTop, maxScrollTop));
-        this.animateScroll(scroller, clampedScrollTop);
-      }
-
-      /**
-       * Animate scroll using browser's built-in smooth scrolling.
-       */
-      private animateScroll(element: HTMLElement, targetScrollTop: number) {
-        if (Math.abs(targetScrollTop - element.scrollTop) < 1) {
-          return;
-        }
-
-        // Use browser's built-in smooth scrolling.
-        element.scrollTo({
-          top: targetScrollTop,
-          behavior: 'smooth',
-        });
-      }
-    },
-  );
-
-  return [
-    scrollPlugin,
-
-    // Update listener to handle scroll effects.
-    EditorView.updateListener.of((update) => {
-      update.transactions.forEach((transaction) => {
-        for (const effect of transaction.effects) {
-          if (effect.is(scrollToLineEffect)) {
-            const { line, options = {} } = effect.value;
-            const plugin = update.view.plugin(scrollPlugin);
-            if (plugin) {
-              plugin.scrollToLine(line, { offset, position, ...options });
-            }
-          }
-        }
-      });
-    }),
-  ];
-};
-
-/**
- * Helper function to scroll to a specific line.
- * This is a convenience function that can be used directly with an EditorView.
- *
- * @param view - The CodeMirror EditorView instance
- * @param line - The line number to scroll to (1-based)
- * @param options - Optional scroll configuration
- */
-export const scrollToLine = (view: EditorView, line: number, options?: SmoothScrollOptions) => {
-  view.dispatch({
-    effects: scrollToLineEffect.of({ line, options }),
-  });
-};

package/src/extensions/tags/streamer.ts

@@ -1,243 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import { type Extension, StateEffect, StateField } from '@codemirror/state';
-import { Decoration, type DecorationSet, EditorView, ViewPlugin, type ViewUpdate, WidgetType } from '@codemirror/view';
-
-import { Domino } from '@dxos/ui';
-import { isTruthy } from '@dxos/util';
-
-const BLINK_RATE = 2_000;
-
-export type StreamerOptions = {
-  cursor?: boolean;
-  // When true, uses defaults. When object, allows configuring removal delay.
-  fadeIn?: boolean | { removalDelay?: number };
-};
-
-/**
- * Extension that adds a blinking cursor widget at the end of the document.
- */
-export const streamer = (options: StreamerOptions = {}): Extension => {
-  return [
-    options.cursor && cursor(),
-    options.fadeIn && fadeIn(typeof options.fadeIn === 'object' ? options.fadeIn : {}),
-  ].filter(isTruthy);
-};
-
-/**
- * State field to manage the cursor widget decoration.
- */
-const cursor = (): Extension => {
-  const hideCursor = StateEffect.define();
-
-  // State field to track if cursor should be shown.
-  const showCursor = StateField.define<boolean>({
-    create: () => true,
-    update: (value, tr) => {
-      for (const effect of tr.effects) {
-        if (effect.is(hideCursor)) {
-          return false;
-        }
-      }
-      if (tr.docChanged) {
-        return true;
-      }
-
-      return value;
-    },
-  });
-
-  // View plugin to manage timer and dispatch effects.
-  const timerPlugin = ViewPlugin.fromClass(
-    class {
-      timer: any;
-
-      constructor(private view: EditorView) {}
-
-      update(update: ViewUpdate) {
-        if (update.docChanged) {
-          clearTimeout(this.timer);
-          this.timer = setTimeout(() => {
-            this.view.dispatch({
-              effects: hideCursor.of(null),
-            });
-          }, BLINK_RATE);
-        }
-      }
-
-      destroy() {
-        clearTimeout(this.timer);
-      }
-    },
-  );
-
-  // Decoration field that uses the showCursor state.
-  const cursorDecoration = StateField.define<DecorationSet>({
-    create: () => Decoration.none,
-    update: (_decorations, tr) => {
-      const show = tr.state.field(showCursor);
-      if (!show) {
-        return Decoration.none;
-      }
-
-      // Always place cursor at the end of the document.
-      const endPos = tr.state.doc.length;
-      return Decoration.set([
-        Decoration.widget({
-          widget: new CursorWidget(),
-          side: 1, // Place after the position.
-        }).range(endPos),
-      ]);
-    },
-    provide: (f) => EditorView.decorations.from(f),
-  });
-
-  return [showCursor, timerPlugin, cursorDecoration];
-};
-
-/**
- * Widget class for the cursor at the end of the document.
- * Half
- */
-class CursorWidget extends WidgetType {
-  toDOM() {
-    const inner = Domino.of('span').text('\u258F').style({ animation: 'blink 2s infinite' });
-    return Domino.of('span').style({ opacity: '0.8' }).children(inner).root;
-  }
-}
-
-/**
- * State field to detect and decorate appended text with a fade-in effect.
- * Also schedules removal of the last appended decoration after a delay.
- */
-const fadeIn = (options: { removalDelay?: number } = {}): Extension => {
-  const FADE_IN_DURATION = 1_000; // ms.
-  const DEFAULT_REMOVAL_DELAY = 5_000; // ms.
-  const removalDelay = options.removalDelay ?? DEFAULT_REMOVAL_DELAY;
-
-  // Effect to remove a specific decoration by range.
-  const removeDecoration = StateEffect.define<{ from: number; to: number }>();
-
-  // Decoration field that adds fade-in marks for appended content and responds to removal effects.
-  const fadeField = StateField.define<DecorationSet>({
-    create: () => Decoration.none,
-    update: (decorations, tr) => {
-      let next = decorations;
-
-      // Apply removals first, if any.
-      for (const effect of tr.effects) {
-        if (effect.is(removeDecoration)) {
-          const target = effect.value;
-          next = next.update({
-            filter: (from, to) => !(from === target.from && to === target.to),
-          });
-        }
-      }
-
-      if (!tr.docChanged) {
-        return next;
-      }
-
-      // Reset decorations if the entire content was replaced.
-      let isReset = tr.state.doc.length === 0;
-      if (!isReset) {
-        tr.changes.iterChanges((fromA, toA) => {
-          if (fromA === 0 && toA === tr.startState.doc.length) {
-            isReset = true;
-          }
-        });
-      }
-      if (isReset) {
-        return Decoration.none;
-      }
-
-      // Add fade-in decorations for appended content at the end only.
-      const add: any[] = [];
-      tr.changes.iterChanges((fromA, toA, fromB, toB, inserted) => {
-        // Don't fade in initial content.
-        if (fromB === 0 && toB === inserted.length) {
-          return;
-        }
-        // At-the-end append.
-        if (toA === tr.startState.doc.length && inserted.length > 0) {
-          add.push(Decoration.mark({ class: 'cm-fade-in' }).range(fromB, toB));
-        }
-      });
-
-      return next.update({ add });
-    },
-    provide: (f) => EditorView.decorations.from(f),
-  });
-
-  // View plugin that tracks appended ranges and schedules their removal.
-  const timerPlugin = ViewPlugin.fromClass(
-    class {
-      // Map a simple key "from-to" to timer id.
-      _timers = new Map<string, any>();
-
-      constructor(private view: EditorView) {}
-
-      update(update: ViewUpdate) {
-        if (!update.docChanged) {
-          return;
-        }
-
-        update.changes.iterChanges((fromA, toA, fromB, toB, inserted) => {
-          // Only consider appends at the end.
-          if (toA !== update.startState.doc.length || inserted.length === 0) {
-            return;
-          }
-
-          const key = `${fromB}-${toB}`;
-          // Clear any prior timer for this exact range.
-          if (this._timers.has(key)) {
-            clearTimeout(this._timers.get(key));
-          }
-
-          const totalDelay = FADE_IN_DURATION + removalDelay;
-          const id = setTimeout(() => {
-            this.view.dispatch({
-              effects: removeDecoration.of({ from: fromB, to: toB }),
-            });
-            this._timers.delete(key);
-          }, totalDelay);
-
-          this._timers.set(key, id);
-        });
-      }
-
-      destroy() {
-        for (const id of this._timers.values()) {
-          clearTimeout(id);
-        }
-        this._timers.clear();
-      }
-    },
-  );
-
-  return [
-    fadeField,
-    timerPlugin,
-    EditorView.theme({
-      '.cm-line > span': {
-        opacity: '0.8',
-      },
-      '.cm-fade-in': {
-        animation: 'fade-in 3s ease-out forwards',
-      },
-      '@keyframes fade-in': {
-        '0%': {
-          opacity: '0',
-        },
-        '80%': {
-          opacity: '1',
-        },
-        '100%': {
-          opacity: '0.8',
-        },
-      },
-    }),
-  ];
-};

package/src/extensions/typewriter.ts

@@ -1,68 +0,0 @@
-//
-// Copyright 2023 DXOS.org
-//
-
-import { type Extension } from '@codemirror/state';
-import { keymap } from '@codemirror/view';
-
-// TODO(burdon): Review https://github.com/sergeche/codemirror-movie?tab=readme-ov-file
-
-export type DemoOptions = {
-  delay?: number;
-  items?: string[];
-};
-
-const defaultItems = ['hello world!', 'this is a test.', 'this is [DXOS](https://dxos.org)'];
-
-/**
- * Configurable plugin that let's user cycle through pre-configured input script.
- */
-export const typewriter = ({ delay = 75, items = defaultItems }: DemoOptions = {}): Extension => {
-  let t: any;
-  let idx = 0; // TODO(burdon): Make global.
-
-  return [
-    keymap.of([
-      {
-        // Reset.
-        key: "alt-meta-'",
-        run: () => {
-          clearTimeout(t);
-          idx = 0;
-          return true;
-        },
-      },
-      {
-        // Next prompt.
-        // TODO(burdon): Press 1-9 to select prompt?
-        key: "Shift-Meta-'",
-        run: (view) => {
-          clearTimeout(t);
-          // TODO(burdon): Add space if needed.
-          const text = items[idx++];
-          if (idx === items?.length) {
-            idx = 0;
-          }
-
-          let i = 0;
-          const insert = (d = 0) => {
-            t = setTimeout(() => {
-              const pos = view.state.selection.main.head;
-              view.dispatch({
-                changes: { from: pos, insert: text[i++] },
-                selection: { anchor: pos + 1 },
-              });
-
-              if (i < text.length) {
-                insert(Math.random() * delay * (text[i] === ' ' ? 2 : 1));
-              }
-            }, d);
-          };
-
-          insert();
-          return true;
-        },
-      },
-    ]),
-  ];
-};