@dxos/react-ui-editor 0.4.7 → 0.4.8-main.0602afb

package/src/extensions/cursor-line-margin.ts

@@ -5,26 +5,26 @@
 // Based upon @acheronfail’s implementation, fetched 16 Feb 2024
 // https://discuss.codemirror.net/t/cursorscrollmargin-for-v6/7448/5
 
-import { type EditorState, type Extension, Facet, Transaction } from '@codemirror/state';
+import { type EditorState, type Extension, Transaction } from '@codemirror/state';
 import { EditorView } from '@codemirror/view';
 
 import { log } from '@dxos/log';
 
-/**
- * Number of lines above/below the cursor to keep visible in the viewport.
- * Defaults to 3.
- */
-export const cursorLineMarginFacet = Facet.define<number, number>({
-  combine: (input) => input[0] ?? 3,
-});
-
 const annotation = 'cursorLineMargin';
 const lineAtPos = (s: EditorState, pos: number) => s.doc.lineAt(pos).number;
 
-// Seems to the best approximation of CM5's `cursorScrollMargin`
-// https://discuss.codemirror.net/t/cursorscrollmargin-for-v6/7448
-export const cursorLineMargin: Extension = EditorView.updateListener.of(
-  ({ transactions, state, selectionSet, startState, view }) => {
+type Options = {
+  lines?: number;
+};
+
+// TODO(burdon): Remove. Buggy and creates scrolling problems. Find better (more general) way to deal with HALO notch.
+export const cursorLineMargin = (options: Options = { lines: 3 }): Extension => {
+  const { lines } = options;
+  if (!lines || lines <= 0) {
+    return [];
+  }
+
+  return EditorView.updateListener.of(({ transactions, state, selectionSet, startState, view }) => {
     // make sure we don't trigger an infinite loop and ignore our own changes
     if (transactions.length < 1 || transactions.some((tr) => tr.isUserEvent(annotation))) {
       return;
@@ -32,7 +32,6 @@ export const cursorLineMargin: Extension = EditorView.updateListener.of(
 
     const s = state;
     const { main } = s.selection;
-    const cursorLineMargin = s.facet(cursorLineMarginFacet);
 
     // editor rect
     const rect = view.dom.getBoundingClientRect();
@@ -59,7 +58,7 @@ export const cursorLineMargin: Extension = EditorView.updateListener.of(
 
     // const needsScrollTop = mainLine <= visTopLine + cursorLineMargin;
     const needsScrollTop = false;
-    const needsScrollBot = mainLine >= visBotLine - cursorLineMargin;
+    const needsScrollBot = mainLine >= visBotLine - lines;
 
     // the scroll margins are overlapping
     if (needsScrollTop && needsScrollBot) {
@@ -88,8 +87,8 @@ export const cursorLineMargin: Extension = EditorView.updateListener.of(
       annotations: Transaction.userEvent.of(annotation),
       effects: EditorView.scrollIntoView(s.selection.main.head, {
         y: needsScrollTop ? 'start' : 'end',
-        yMargin: view.defaultLineHeight * cursorLineMargin,
+        yMargin: view.defaultLineHeight * lines,
       }),
     });
-  },
-);
+  });
+};

package/src/extensions/cursor.ts

@@ -4,7 +4,7 @@
 
 import { type EditorState, Facet } from '@codemirror/state';
 
-import type { Range } from '../hooks';
+import type { Range } from './types';
 
 /**
  * Converts indexes into the text document into stable peer-independent cursors.

package/src/extensions/doc.ts

@@ -0,0 +1,14 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { Facet } from '@codemirror/state';
+
+import { invariant } from '@dxos/invariant';
+
+export const documentId = Facet.define<string, string>({
+  combine: (providers) => {
+    invariant(providers.length <= 1);
+    return providers[0];
+  },
+});

package/src/extensions/factories.ts

@@ -0,0 +1,170 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { closeBrackets } from '@codemirror/autocomplete';
+import { history } from '@codemirror/commands';
+import { bracketMatching } from '@codemirror/language';
+import { EditorState, type Extension } from '@codemirror/state';
+import {
+  EditorView,
+  crosshairCursor,
+  drawSelection,
+  dropCursor,
+  highlightActiveLine,
+  lineNumbers,
+  placeholder,
+  scrollPastEnd,
+} from '@codemirror/view';
+import defaultsDeep from 'lodash.defaultsdeep';
+
+import { generateName } from '@dxos/display-name';
+import { type DocAccessor } from '@dxos/echo-schema';
+import { log } from '@dxos/log';
+import { type Space } from '@dxos/react-client/echo';
+import { type Identity } from '@dxos/react-client/halo';
+import { type ThemeMode } from '@dxos/react-ui';
+import { type HuePalette, hueTokens } from '@dxos/react-ui-theme';
+import { hexToHue, isNotFalsy } from '@dxos/util';
+
+import { automerge } from './automerge';
+import { awareness, SpaceAwarenessProvider } from './awareness';
+import { type ThemeStyles } from '../styles';
+import { defaultTheme } from '../themes';
+
+// TODO(burdon): Move into extensions folder.
+
+//
+// Basic
+//
+
+/**
+ * https://codemirror.net/docs/extensions
+ * https://github.com/codemirror/basic-setup
+ */
+// TODO(burdon): Reconcile with createMarkdownExtensions.
+export type BasicExtensionsOptions = {
+  allowMultipleSelections?: boolean;
+  bracketMatching?: boolean;
+  closeBrackets?: boolean;
+  crosshairCursor?: boolean;
+  dropCursor?: boolean;
+  drawSelection?: boolean;
+  editable?: boolean;
+  highlightActiveLine?: boolean;
+  history?: boolean;
+  lineNumbers?: boolean;
+  lineWrapping?: boolean;
+  placeholder?: string;
+  readonly?: boolean;
+  scrollPastEnd?: boolean;
+  tabSize?: number;
+};
+
+const defaults: BasicExtensionsOptions = {
+  bracketMatching: true,
+  closeBrackets: true,
+  drawSelection: true,
+  editable: true,
+  history: true,
+  lineWrapping: true,
+};
+
+export const createBasicExtensions = (_props?: BasicExtensionsOptions): Extension => {
+  const props: BasicExtensionsOptions = defaultsDeep({}, _props, defaults);
+  return [
+    // TODO(burdon): Doesn't catch errors in keymap functions.
+    EditorView.exceptionSink.of((err) => {
+      log.catch(err);
+    }),
+
+    props.allowMultipleSelections && EditorState.allowMultipleSelections.of(true),
+    props.bracketMatching && bracketMatching(),
+    props.closeBrackets && closeBrackets(),
+    props.crosshairCursor && crosshairCursor(),
+    props.dropCursor && dropCursor(),
+    props.drawSelection && drawSelection(),
+    props.highlightActiveLine && highlightActiveLine(),
+    props.history && history(),
+    props.lineNumbers && lineNumbers(),
+    props.lineWrapping && EditorView.lineWrapping,
+    props.placeholder && placeholder(props.placeholder),
+    props.readonly && [EditorState.readOnly.of(true), EditorView.editable.of(false)],
+    props.scrollPastEnd && scrollPastEnd(),
+    props.tabSize && EditorState.tabSize.of(props.tabSize),
+  ].filter(isNotFalsy);
+};
+
+//
+// Theme
+//
+
+export type ThemeExtensionsOptions = {
+  theme?: ThemeStyles;
+  themeMode?: ThemeMode;
+  slots?: {
+    editor?: {
+      className?: string;
+    };
+    content?: {
+      className?: string;
+    };
+  };
+};
+
+const defaultSlots = {
+  editor: {
+    className: 'w-full bs-full',
+  },
+  content: {
+    className: '!p-2',
+  },
+};
+
+export const createThemeExtensions = ({ theme, themeMode, slots: _slots }: ThemeExtensionsOptions = {}): Extension => {
+  const slots = defaultsDeep({}, _slots, defaultSlots);
+  return [
+    EditorView.baseTheme(defaultTheme),
+    EditorView.darkTheme.of(themeMode === 'dark'),
+    theme && EditorView.theme(theme),
+    slots.editor?.className && EditorView.editorAttributes.of({ class: slots.editor.className }),
+    slots.content?.className && EditorView.contentAttributes.of({ class: slots.content.className }),
+  ].filter(isNotFalsy);
+};
+
+//
+// Data
+//
+
+export type DataExtensionsProps = {
+  id: string;
+  text: DocAccessor; // TODO(burdon): Rename content.
+  space?: Space;
+  identity?: Identity | null;
+};
+
+// TODO(burdon): Factor out automerge defs and extension (not hook).
+// TODO(burdon): Move out of react-ui-editor (remove echo deps).
+export const createDataExtensions = ({ id, text, space, identity }: DataExtensionsProps): Extension[] => {
+  const extensions: Extension[] = [automerge(text)];
+
+  if (space && identity) {
+    const peerId = identity?.identityKey.toHex();
+    const { cursorLightValue, cursorDarkValue } =
+      hueTokens[(identity?.profile?.data?.hue as HuePalette | undefined) ?? hexToHue(peerId ?? '0')];
+    const awarenessProvider = new SpaceAwarenessProvider({
+      space,
+      channel: `awareness.${id}`,
+      peerId: identity.identityKey.toHex(),
+      info: {
+        displayName: identity.profile?.displayName ?? generateName(identity.identityKey.toHex()),
+        color: cursorDarkValue,
+        lightColor: cursorLightValue,
+      },
+    });
+
+    extensions.push(awareness(awarenessProvider));
+  }
+
+  return extensions;
+};

package/src/extensions/index.ts

@@ -11,10 +11,12 @@ export * from './command';
 export * from './comments';
 export * from './cursor';
 export * from './cursor-line-margin';
+export * from './doc';
 export * from './dnd';
+export * from './factories';
 export * from './listener';
 export * from './markdown';
 export * from './mention';
 export * from './modes';
-export * from './outliner';
+export * from './types';
 export * from './typewriter';

package/src/extensions/markdown/bundle.ts

@@ -2,51 +2,34 @@
 // Copyright 2023 DXOS.org
 //
 
-import { closeBrackets, closeBracketsKeymap } from '@codemirror/autocomplete';
-import { history, historyKeymap, indentWithTab, standardKeymap } from '@codemirror/commands';
+import { closeBracketsKeymap } from '@codemirror/autocomplete';
+import { historyKeymap, indentWithTab, standardKeymap } from '@codemirror/commands';
 import { markdownLanguage, markdown } from '@codemirror/lang-markdown';
-import { bracketMatching, defaultHighlightStyle, indentOnInput, syntaxHighlighting } from '@codemirror/language';
+import { defaultHighlightStyle, syntaxHighlighting } from '@codemirror/language';
 import { languages } from '@codemirror/language-data';
 import { searchKeymap } from '@codemirror/search';
-import { EditorState, type Extension } from '@codemirror/state';
+import { type Extension } from '@codemirror/state';
 import { oneDarkHighlightStyle } from '@codemirror/theme-one-dark';
-import { EditorView, drawSelection, dropCursor, keymap, placeholder } from '@codemirror/view';
+import { keymap } from '@codemirror/view';
 
 import { type ThemeMode } from '@dxos/react-ui';
-import { isNotFalsy } from '@dxos/util';
 
 import { markdownHighlightStyle, markdownTagsExtensions } from './highlight';
-import { type TextEditorProps } from '../../components';
 
 export type MarkdownBundleOptions = {
   themeMode?: ThemeMode;
-} & Pick<TextEditorProps, 'lineWrapping' | 'placeholder'>;
+};
 
 /**
- * Markdown bundle.
+ * Creates markdown extensions.
+ * To be used in conjunction with createBasicExtensions.
+ *
  * Refs:
  * https://codemirror.net/docs/community
  * https://codemirror.net/docs/ref/#codemirror.basicSetup
  */
-export const createMarkdownExtensions = ({
-  themeMode,
-  placeholder: _placeholder,
-  lineWrapping = true,
-}: MarkdownBundleOptions = {}): Extension[] => {
+export const createMarkdownExtensions = ({ themeMode }: MarkdownBundleOptions = {}): Extension[] => {
   return [
-    // TODO(burdon): Reconcile with createBasicExtensions.
-    lineWrapping && EditorView.lineWrapping,
-    EditorState.allowMultipleSelections.of(true),
-    EditorState.tabSize.of(2),
-
-    bracketMatching(),
-    closeBrackets(),
-    dropCursor(),
-    drawSelection(),
-    history(),
-    indentOnInput(),
-    _placeholder && placeholder(_placeholder),
-
     // Main extension.
     // https://github.com/codemirror/lang-markdown
     // https://codemirror.net/5/mode/markdown/index.html (demo).
@@ -86,5 +69,5 @@ export const createMarkdownExtensions = ({
       // https://codemirror.net/docs/ref/#commands.standardKeymap
       ...standardKeymap,
     ]),
-  ].filter(isNotFalsy);
+  ];
 };

package/src/extensions/markdown/decorate.ts

@@ -148,9 +148,7 @@ const buildDecorations = (view: EditorView, options: DecorateOptions, focus: boo
                 marks[1].from,
                 node.to,
                 options.renderLinkButton
-                  ? Decoration.replace({
-                      widget: new LinkButton(url, options.renderLinkButton),
-                    })
+                  ? Decoration.replace({ widget: new LinkButton(url, options.renderLinkButton) })
                   : hide,
               );
             }

package/src/extensions/markdown/formatting.ts

@@ -161,7 +161,7 @@ export const setStyle =
   ({ state, dispatch }) => {
     const marker = inlineMarkerText(type);
     const changes = state.changeByRange((range) => {
-      // Special case for markers directly around the cursor, which will often not be parsed as valid styling
+      // Special case for markers directly around the cursor, which will often not be parsed as valid styling.
       if (!enable && range.empty) {
         const after = state.doc.sliceString(range.head, range.head + 6);
         const found = after.indexOf(marker);
@@ -190,16 +190,16 @@ export const setStyle =
       let startCovered: boolean | { from: number; to: number } = false;
       let endCovered: boolean | { from: number; to: number } = false;
       let { from, to } = range;
-      // Iterate the selected range. For each textblock, determine a
-      // start and end position, the overlap of the selected range and
-      // the block's extent, that should be styled/unstyled.
+
+      // Iterate the selected range. For each textblock, determine a start and end position,
+      // the overlap of the selected range and the block's extent, that should be styled/unstyled.
       syntaxTree(state).iterate({
         from,
         to,
         enter: (node) => {
           const { name } = node;
           if (Object.hasOwn(Textblocks, name) && Textblocks[name] !== 'codeblock') {
-            // Set up for this textblock
+            // Set up for this textblock.
             blockStart = blockContentStart(node);
             blockEnd = blockContentEnd(node, state.doc);
             startCovered = endCovered = false;
@@ -243,8 +243,7 @@ export const setStyle =
                     : true;
               }
             }
-            // Marks of the same type in range, or any mark if we're
-            // adding code style, need to be removed.
+            // Marks of the same type in range, or any mark if we're adding code style, need to be removed.
             if (markType === type || (type === Inline.Code && enable)) {
               if (node.from >= from && openEnd <= to) {
                 changes.push({ from: node.from, to: openEnd });
@@ -271,7 +270,7 @@ export const setStyle =
         },
         leave: (node) => {
           if (Object.hasOwn(Textblocks, node.name) && Textblocks[node.name] !== 'codeblock') {
-            // Finish opening/closing the marks for this textblock
+            // Finish opening/closing the marks for this textblock.
             const rangeStart = Math.max(from, blockStart);
             const rangeEnd = Math.min(to, blockEnd);
             if (enable) {
@@ -296,12 +295,14 @@ export const setStyle =
           }
         },
       });
+
       if (blockStart < 0 && range.empty && enable && !/\S/.test(state.doc.lineAt(range.from).text)) {
         return {
           changes: { from: range.head, insert: marker + marker },
           range: EditorSelection.cursor(range.head + marker.length),
         };
       }
+
       const changeSet = state.changes(changes.concat(changesAtEnd));
       return {
         changes: changeSet,
@@ -313,8 +314,12 @@ export const setStyle =
     });
 
     dispatch(
-      state.update(changes, { userEvent: enable ? 'format.style.add' : 'format.style.remove', scrollIntoView: true }),
+      state.update(changes, {
+        userEvent: enable ? 'format.style.add' : 'format.style.remove',
+        scrollIntoView: true,
+      }),
     );
+
     return true;
   };
 
@@ -987,7 +992,7 @@ export const toggleCodeblock: StateCommand = (target) => {
 
 export type FormattingOptions = {};
 
-export const formatting = (options: FormattingOptions = {}): Extension => {
+export const formattingKeymap = (options: FormattingOptions = {}): Extension => {
   return [
     keymap.of([
       {

package/src/extensions/markdown/image.ts

@@ -61,6 +61,7 @@ const buildDecorations = (from: number, to: number, state: EditorState) => {
         if (urlNode) {
           const hide = state.readOnly || cursor < node.from || cursor > node.to;
           const url = state.sliceDoc(urlNode.from, urlNode.to);
+          // TODO(burdon): Doesn't load if scrolling with mouse.
           preloadImage(url);
           decorations.push(
             Decoration.replace({

package/src/extensions/markdown/table.ts

@@ -3,7 +3,14 @@
 //
 
 import { syntaxTree } from '@codemirror/language';
-import { type EditorState, type RangeSet, RangeSetBuilder, StateField, type Transaction } from '@codemirror/state';
+import {
+  type EditorState,
+  type Extension,
+  type RangeSet,
+  RangeSetBuilder,
+  StateField,
+  type Transaction,
+} from '@codemirror/state';
 import { Decoration, EditorView, WidgetType } from '@codemirror/view';
 
 // TODO(burdon): Snippet to create basic table.
@@ -18,7 +25,7 @@ export type TableOptions = {};
  * GFM tables.
  * https://github.github.com/gfm/#tables-extension
  */
-export const table = (options: TableOptions = {}) => {
+export const table = (options: TableOptions = {}): Extension => {
   return StateField.define<RangeSet<any>>({
     create: (state) => update(state, options),
     update: (_: RangeSet<any>, tr: Transaction) => update(tr.state, options),
@@ -76,7 +83,7 @@ const update = (state: EditorState, options: TableOptions) => {
 
   tables.forEach((table) => {
     const hide = state.readOnly || cursor < table.from || cursor > table.to;
-    hide &&
+    if (hide) {
       builder.add(
         table.from,
         table.to,
@@ -84,6 +91,7 @@ const update = (state: EditorState, options: TableOptions) => {
           widget: new TableWidget(table),
         }),
       );
+    }
 
     // Add class for styling.
     builder.add(table.from, table.to, Decoration.mark({ class: 'cm-table' }));

package/src/extensions/types.ts

@@ -0,0 +1,16 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+// Runtime data structure.
+export type Range = {
+  from: number;
+  to: number;
+};
+
+// Persistent data structure.
+// TODO(burdon): Rename annotation?
+export type Comment = {
+  id: string;
+  cursor?: string;
+};

package/src/hooks/index.ts

@@ -2,10 +2,6 @@
 // Copyright 2023 DXOS.org
 //
 
-export * from './awareness-provider';
-export * from './defs';
-
 export * from './useActionHandler';
-export * from './useEditorView';
+export * from './useDocAccessor';
 export * from './useTextEditor';
-export * from './useTextModel';

package/src/hooks/useDocAccessor.ts

@@ -0,0 +1,21 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { useMemo } from 'react';
+
+import { createDocAccessor, type DocAccessor, getTextContent, type TextObject } from '@dxos/echo-schema';
+
+// TODO(burdon): Factor out.
+export const useDocAccessor = <T = any>(
+  text: TextObject,
+): { id: string; doc: string | undefined; accessor: DocAccessor<T> } => {
+  return useMemo(
+    () => ({
+      id: text.id,
+      doc: getTextContent(text),
+      accessor: createDocAccessor<T>(text),
+    }),
+    [text],
+  );
+};

package/src/hooks/useTextEditor.stories.tsx

@@ -4,34 +4,28 @@
 
 import '@dxosTheme';
 
-import React, { useMemo, useState } from 'react';
+import React, { useState } from 'react';
 
 import { Toolbar as NaturalToolbar, Select, useThemeContext, Tooltip } from '@dxos/react-ui';
 import { attentionSurface, mx, textBlockWidth } from '@dxos/react-ui-theme';
 import { withTheme } from '@dxos/storybook-utils';
 
 import { useActionHandler } from './useActionHandler';
-import { createBasicExtensions, createThemeExtensions, useTextEditor } from './useTextEditor';
+import { useTextEditor } from './useTextEditor';
 import { Toolbar } from '../components';
+import { createBasicExtensions, createThemeExtensions } from '../extensions';
 import {
   type EditorMode,
   EditorModes,
   decorateMarkdown,
   createMarkdownExtensions,
-  formatting,
-  image,
+  formattingKeymap,
   table,
   useFormattingState,
+  image,
 } from '../extensions';
-import { markdownTheme } from '../themes';
 import translations from '../translations';
 
-// TODO(burdon): Demo toolbar with hooks.
-// TODO(burdon): Build components from hooks and adapters for model/extensions, etc.
-// TODO(burdon): Remove BaseTextEditor.
-// TODO(burdon): Move scrolling container layout/logic into TextEditor/MarkdownEditor components.
-// TODO(burdon): Define keymap in composer framework format.
-
 type StoryProps = {
   autoFocus?: boolean;
   placeholder?: string;
@@ -43,29 +37,24 @@ const Story = ({ autoFocus, placeholder, doc, readonly }: StoryProps) => {
   const { themeMode } = useThemeContext();
   const [formattingState, trackFormatting] = useFormattingState();
   const [editorMode, setEditorMode] = useState<EditorMode>('default');
-  const extensions = useMemo(
-    () => [
-      editorMode ? EditorModes[editorMode] : [],
-      createBasicExtensions({ readonly }),
-      createThemeExtensions({
-        themeMode,
-        theme: markdownTheme,
-        slots: {
-          editor: { className: 'p-2' },
-        },
-      }),
-      // TODO(burdon): Move lineWrapping.
-      createMarkdownExtensions({ placeholder, lineWrapping: true }),
-      // TODO(burdon): Move into markdown bundle (with React callbacks).
-      decorateMarkdown(),
-      formatting(),
-      image(),
-      table(),
-      trackFormatting,
-    ],
-    [editorMode, themeMode, placeholder, trackFormatting, readonly],
+  const { parentRef, view } = useTextEditor(
+    () => ({
+      autoFocus,
+      doc,
+      extensions: [
+        editorMode ? EditorModes[editorMode] : [],
+        createBasicExtensions({ placeholder, lineWrapping: true, readonly }),
+        createMarkdownExtensions({ themeMode }),
+        createThemeExtensions({ themeMode }),
+        decorateMarkdown(),
+        formattingKeymap(),
+        image(),
+        table(),
+        trackFormatting,
+      ],
+    }),
+    [editorMode, themeMode, placeholder, readonly],
   );
-  const { parentRef, view } = useTextEditor({ autoFocus, doc, extensions });
 
   const handleAction = useActionHandler(view);
 
@@ -116,7 +105,6 @@ const EditorModeToolbar = ({
 
 export default {
   title: 'react-ui-editor/useTextEditor',
-  // component: TextEditor,
   decorators: [withTheme],
   render: (args: StoryProps) => (
     <Tooltip.Provider>
@@ -127,6 +115,23 @@ export default {
 };
 
 export const Default = {
+  render: () => {
+    const { parentRef } = useTextEditor();
+    return <div role='textbox' className={mx(textBlockWidth, attentionSurface)} ref={parentRef} />;
+  },
+};
+
+export const Basic = {
+  render: () => {
+    const { themeMode } = useThemeContext();
+    const { parentRef } = useTextEditor(() => ({
+      extensions: [createBasicExtensions({ placeholder: 'Enter text...' }), createThemeExtensions({ themeMode })],
+    }));
+    return <div role='textbox' className={mx(textBlockWidth, attentionSurface)} ref={parentRef} />;
+  },
+};
+
+export const Markdown = {
   args: {
     autoFocus: true,
     placeholder: 'Text...',