@dxos/plugin-markdown 0.8.4-main.c85a9c8dae → 0.8.4-main.d9fc60f731

package/src/hooks/useEditorMenuOptions.ts

@@ -15,7 +15,7 @@ import {
 } from '@dxos/react-ui-editor';
 import { Domino } from '@dxos/ui';
 
-import { meta } from '../meta';
+import { meta } from '#meta';
 
 export type UseEditorMenuOptionsProps = {
   editorView?: EditorView;
@@ -59,7 +59,7 @@ export const useEditorMenuOptions = ({
           Domino.of('span').classNames('mx-1 px-1.5 pt-[1px] pb-[2px] border border-separator rounded-xs').text(text),
         );
         const forCommandsEl = Domino.of('span').text('for commands.');
-        return Domino.of('div').children(pressEl, ...triggerEls, forCommandsEl).root;
+        return Domino.of('div').append(pressEl, ...triggerEls, forCommandsEl).root;
       },
     };
 

package/src/hooks/useExtensions.tsx

@@ -5,15 +5,14 @@
 import { type ViewUpdate } from '@codemirror/view';
 import { useMemo } from 'react';
 
-import { type Capabilities } from '@dxos/app-framework';
-import { useOperationInvoker } from '@dxos/app-framework/ui';
-import { LayoutOperation } from '@dxos/app-toolkit';
+import { fromUrlPath } from '@dxos/app-toolkit';
 import { debounceAndThrottle } from '@dxos/async';
 import { Obj } from '@dxos/echo';
 import { createDocAccessor } from '@dxos/echo-db';
 import { invariant } from '@dxos/invariant';
 import { getSpace, useObject } from '@dxos/react-client/echo';
 import { useIdentity } from '@dxos/react-client/halo';
+import { useThemeContext } from '@dxos/react-ui';
 import { type SelectionManager } from '@dxos/react-ui-attention';
 import { Text } from '@dxos/schema';
 import { Domino } from '@dxos/ui';
@@ -21,11 +20,9 @@ import {
   Cursor,
   type EditorStateStore,
   EditorView,
-  type EditorViewMode,
   type Extension,
   InputModeExtensions,
   type PreviewOptions,
-  type RenderCallback,
   createDataExtensions,
   decorateMarkdown,
   documentId,
@@ -36,11 +33,13 @@ import {
   preview,
   replacer,
   selectionState,
-  typewriter,
+  snippets,
 } from '@dxos/ui-editor';
+import { type EditorViewMode, type RenderCallback } from '@dxos/ui-editor/types';
 import { isTruthy, safeUrl } from '@dxos/util';
 
-import { Markdown } from '../types';
+import { Markdown } from '#types';
+
 import { setFallbackName } from '../util';
 
 export type DocumentType = Markdown.Document | Text.Text | { id: string; text: string };
@@ -48,12 +47,16 @@ export type DocumentType = Markdown.Document | Text.Text | { id: string; text: s
 export type ExtensionsOptions = {
   id: string;
   object?: DocumentType;
-  invokePromise?: Capabilities.OperationInvoker['invokePromise'];
   settings?: Markdown.Settings;
-  selectionManager?: SelectionManager;
+  compact?: boolean;
   viewMode?: EditorViewMode;
+  editable?: boolean;
+  selectionManager?: SelectionManager;
   editorStateStore?: EditorStateStore;
   previewOptions?: PreviewOptions;
+  platform?: 'mobile' | 'desktop';
+  /** Callback when an internal link is clicked. */
+  onSelectObject?: (objectId: string) => void;
 };
 
 // TODO(burdon): Merge with createBaseExtensions below.
@@ -61,12 +64,14 @@ export const useExtensions = ({
   id,
   object,
   settings,
-  selectionManager,
+  compact,
   viewMode,
+  selectionManager,
   editorStateStore,
   previewOptions,
+  onSelectObject,
 }: ExtensionsOptions): Extension[] => {
-  const { invokePromise } = useOperationInvoker();
+  const { platform } = useThemeContext();
   const identity = useIdentity();
   const space = getSpace(object);
 
@@ -88,24 +93,27 @@ export const useExtensions = ({
         id,
         object,
         settings,
-        selectionManager,
+        compact,
         viewMode,
+        selectionManager,
         previewOptions,
-        invokePromise,
+        platform,
+        onSelectObject,
       }),
     [
       id,
       object,
+      compact,
       viewMode,
-      invokePromise,
+      selectionManager,
       previewOptions,
       settings,
       settings?.debug,
       settings?.editorInputMode,
       settings?.folding,
       settings?.numberedHeadings,
-      settings?.typewriter,
-      selectionManager,
+      platform,
+      onSelectObject,
     ],
   );
 
@@ -143,16 +151,18 @@ export const useExtensions = ({
 const createBaseExtensions = ({
   id,
   object,
-  invokePromise,
+  onSelectObject,
   settings,
-  selectionManager,
+  compact,
   viewMode,
+  selectionManager,
   previewOptions,
+  platform,
 }: ExtensionsOptions): Extension[] => {
   const extensions: Extension[] = [
     selectionManager && selectionChange(selectionManager),
     settings?.editorInputMode && InputModeExtensions[settings.editorInputMode],
-    settings?.folding && folding(),
+    settings?.folding && !compact && platform !== 'mobile' && folding(),
   ].filter(isTruthy);
 
   //
@@ -166,12 +176,7 @@ const createBaseExtensions = ({
           selectionChangeDelay: 100,
           numberedHeadings: settings?.numberedHeadings ? { from: 2 } : undefined,
           // TODO(wittjosiah): For internal links render the label of the object.
-          renderLinkButton: createRenderLink((targetId: string) => {
-            void invokePromise?.(LayoutOperation.Open, {
-              subject: [targetId],
-              pivotId: object && Obj.isObject(object) ? Obj.getDXN(object).toString() : id,
-            });
-          }),
+          renderLinkButton: onSelectObject && createRenderLink(onSelectObject),
         }),
         linkTooltip(renderLinkTooltip),
         preview(previewOptions),
@@ -181,9 +186,9 @@ const createBaseExtensions = ({
   }
 
   if (settings?.debug) {
-    const items = settings.typewriter?.split(/[,\n]/) ?? '';
+    const items = settings.snippets?.split(/[,\n]/) ?? '';
     if (items) {
-      extensions.push(typewriter({ items }));
+      extensions.push(snippets({ items }));
     }
   }
 
@@ -195,12 +200,18 @@ const selectionChange = (selectionManager: SelectionManager) => {
     const id = update.state.facet(documentId);
     const cursorConverter = update.state.facet(Cursor.converter);
     const selection = update.state.selection;
+    // NOTE: Filter on numeric offsets BEFORE converting to cursor strings.
+    // Cursors are opaque (Automerge-encoded), so a lexicographic `to > from`
+    // comparison is nondeterministic — it would let some cursor-placements
+    // (where from === to numerically) through and reject genuine selections
+    // depending on encoding, which made the comment button's enabled state
+    // appear random across different lines.
     const ranges = selection.ranges
+      .filter((range) => range.to > range.from)
       .map((range) => ({
         from: cursorConverter.toCursor(range.from),
         to: cursorConverter.toCursor(range.to),
-      }))
-      .filter(({ from, to }) => to > from);
+      }));
 
     selectionManager.updateMultiRange(id, ranges);
   }, 100);
@@ -217,21 +228,33 @@ const createRenderLink =
   (el, { url }) => {
     // TODO(burdon): Formalize/document internal link format.
     const isInternal = url.startsWith('/') || url.startsWith(window.location.origin);
-    const anchor = Domino.of('a')
-      .classNames('dx-link dx-icon-inline ms-1')
-      .children(Domino.svg(isInternal ? 'ph--arrow-square-down--regular' : 'ph--arrow-square-out--regular'));
+    const qualifiedId = isInternal ? fromUrlPath(new URL(url, window.location.origin).pathname) : undefined;
+    const icon = Domino.of('span')
+      .classNames('dx-link ms-1 inline-block align-[-0.125em]')
+      .append(Domino.svg(isInternal ? 'ph--arrow-square-down--regular' : 'ph--arrow-square-out--regular'));
 
     if (isInternal) {
-      anchor.on('click', () => {
-        const qualifiedId = url.split('/').at(-1);
-        invariant(qualifiedId, 'Invalid link format.');
-        onSelectObject(qualifiedId);
-      });
-    } else {
-      anchor.attributes({ href: url, rel: 'noreferrer', target: '_blank' });
+      invariant(qualifiedId, 'Invalid link format.');
+      icon
+        .attributes({ role: 'button', tabindex: '0' })
+        .on('click', (event) => {
+          event.preventDefault();
+          event.stopPropagation();
+          onSelectObject(qualifiedId);
+        })
+        .on('keydown', (event) => {
+          const keyboardEvent = event as KeyboardEvent;
+          if (keyboardEvent.key !== 'Enter' && keyboardEvent.key !== ' ') {
+            return;
+          }
+
+          keyboardEvent.preventDefault();
+          keyboardEvent.stopPropagation();
+          onSelectObject(qualifiedId);
+        });
     }
 
-    el.appendChild(anchor.root);
+    el.appendChild(icon.root);
   };
 
 const renderLinkTooltip: RenderCallback<{ url: string }> = (el, { url }) => {
@@ -239,7 +262,7 @@ const renderLinkTooltip: RenderCallback<{ url: string }> = (el, { url }) => {
     Domino.of('a')
       .attributes({ href: url, target: '_blank', rel: 'noreferrer' })
       .classNames('dx-link flex items-center gap-2')
-      .text(safeUrl(url)?.origin ?? url)
-      .children(Domino.svg('ph--arrow-square-out--regular')).root,
+      .text(safeUrl(url)?.toString() ?? url)
+      .append(Domino.svg('ph--arrow-square-out--regular')).root,
   );
 };

package/src/hooks/useLinkQuery.ts

@@ -5,30 +5,23 @@
 import * as Option from 'effect/Option';
 import { useCallback, useMemo } from 'react';
 
-import { usePluginManager } from '@dxos/app-framework/ui';
-import { AppCapabilities } from '@dxos/app-toolkit';
-import { type Database, Filter, Obj, Query, Type } from '@dxos/echo';
-import { EntityKind, SystemTypeAnnotation, getTypeAnnotation } from '@dxos/echo/internal';
-import { toLocalizedString, useTranslation } from '@dxos/react-ui';
+import { Annotation, type Database, Filter, Obj, Query, Type } from '@dxos/echo';
+import { EntityKind, HiddenAnnotation, getTypeAnnotation } from '@dxos/echo/internal';
+import { type Label, toLocalizedString, useTranslation } from '@dxos/react-ui';
 import { type EditorMenuGroup, type EditorMenuItem } from '@dxos/react-ui-editor';
 import { insertAtCursor, insertAtLineStart } from '@dxos/ui-editor';
 
+import { Markdown } from '../types';
+
 export const useLinkQuery = (db: Database.Database | undefined) => {
   const { t } = useTranslation();
 
-  const manager = usePluginManager();
-  const resolve = useCallback(
-    (typename: string) =>
-      manager.capabilities.getAll(AppCapabilities.Metadata).find(({ id }) => id === typename)?.metadata ?? {},
-    [manager],
-  );
-
   const filter = useMemo(
     () =>
       Filter.or(
-        ...(db?.schemaRegistry.query({ location: ['database', 'runtime'] }).runSync() ?? [])
-          .filter((schema) => getTypeAnnotation(schema)?.kind !== EntityKind.Relation)
-          .filter((schema) => !SystemTypeAnnotation.get(schema).pipe(Option.getOrElse(() => false)))
+        ...(db ? db.graph.registry.list().filter(Type.isType) : [])
+          .filter((schema) => getTypeAnnotation(Type.getSchema(schema))?.kind !== EntityKind.Relation)
+          .filter((schema) => !HiddenAnnotation.get(Type.getSchema(schema)).pipe(Option.getOrElse(() => false)))
           .map((schema) => Filter.typename(Type.getTypename(schema))),
       ),
     [db],
@@ -36,35 +29,31 @@ export const useLinkQuery = (db: Database.Database | undefined) => {
 
   const handleLinkQuery = useCallback(
     async (query?: string): Promise<EditorMenuGroup[]> => {
+      // A second "@" switches the link query into block-embed mode, so "@@foo" searches for "foo".
       const name = query?.startsWith('@') ? query.slice(1).toLowerCase() : (query?.toLowerCase() ?? '');
       const results = await db?.query(Query.select(filter)).run();
 
-      // TODO(wittjosiah): Use `Obj.Unknown` type.
-      const getLabel = (object: any) => {
-        const label = Obj.getLabel(object);
-        if (label) {
-          return label;
-        }
-
-        // TODO(wittjosiah): Remove metadata labels.
+      const getLabel = (object: Obj.Unknown): Label => {
         const type = Obj.getTypename(object)!;
-        const metadata = resolve(type);
-        return metadata.label?.(object) || ['object name placeholder', { ns: type, default: 'New object' }];
+        return Obj.getLabel(object) ?? ['object-name.placeholder', { ns: type, defaultValue: 'New object' }];
       };
 
       const items =
         results
           ?.filter((object) => toLocalizedString(getLabel(object), t).toLowerCase().includes(name))
-          // TODO(wittjosiah): Remove `any` type.
-          .map((object: any): EditorMenuItem => {
-            const metadata = resolve(Obj.getTypename(object)!);
+          .map((object: Obj.Unknown): EditorMenuItem => {
+            const type = Obj.getType(object);
+            const icon = type
+              ? Option.getOrUndefined(Annotation.IconAnnotation.get(Type.getSchema(type)))?.icon
+              : undefined;
             const label = toLocalizedString(getLabel(object), t);
             return {
               id: object.id,
               label,
-              icon: metadata.icon,
+              icon,
               onSelect: ({ view, head }) => {
-                const link = `[${label}](${Obj.getDXN(object)})`;
+                const link = `[${label}](${Obj.getURI(object)})`;
+                // "@@" inserts a block embed on its own line instead of an inline link.
                 if (query?.startsWith('@')) {
                   insertAtLineStart(view, head, `!${link}\n`);
                 } else {
@@ -74,9 +63,30 @@ export const useLinkQuery = (db: Database.Database | undefined) => {
             };
           }) ?? [];
 
-      return [{ id: 'echo', items }];
+      // Add "Create new document" option at the end.
+      const createItem: EditorMenuItem = {
+        id: 'create-document',
+        label: ['add-object.label', { ns: Type.getTypename(Markdown.Document) }],
+        icon: 'ph--plus--regular',
+        onSelect: ({ view, head }) => {
+          const doc = Markdown.make({ name: name || undefined });
+          db?.add(doc);
+          const label = name || t('object-name.placeholder', { ns: Type.getTypename(Markdown.Document) });
+          const link = `[${label}](${Obj.getURI(doc)})`;
+          if (query?.startsWith('@')) {
+            insertAtLineStart(view, head, `!${link}\n`);
+          } else {
+            insertAtCursor(view, head, `${link} `);
+          }
+        },
+      };
+
+      return [
+        { id: 'echo', items },
+        { id: 'create', items: [createItem] },
+      ];
     },
-    [db, filter, resolve],
+    [db, filter, t],
   );
 
   return handleLinkQuery;

package/src/index.ts

@@ -2,12 +2,8 @@
 // Copyright 2023 DXOS.org
 //
 
-export { MarkdownCapabilities, MarkdownEvents } from './types';
-
+export * from './blueprints';
 export * from './meta';
+export * from './operations';
 export * from './types';
 export * from './util';
-
-export * from './MarkdownPlugin';
-
-export { MarkdownEditor } from './components';

package/src/meta.ts

@@ -2,18 +2,28 @@
 // Copyright 2023 DXOS.org
 //
 
-import { type Plugin } from '@dxos/app-framework';
+import { Plugin } from '@dxos/app-framework';
+import { DXN } from '@dxos/keys';
 import { trim } from '@dxos/util';
 
-export const meta: Plugin.Meta = {
-  id: 'dxos.org/plugin/markdown',
+export const meta = Plugin.makeMeta({
+  key: DXN.make('org.dxos.plugin.markdown'),
   name: 'Markdown',
+  author: 'DXOS',
   description: trim`
-    Full-featured collaborative markdown editor with real-time editing, inline comments, and rich formatting.
-    Supports AI-powered editing assistance and seamlessly integrates with other workspace objects.
+    A full-featured markdown editor for authoring documents in your space. Edits flow through a collaborative CodeMirror surface backed by ECHO Text, so every keystroke replicates to other peers in real time without merge conflicts or lost work.
+
+    Documents can be opened in source, preview, or read-only mode and rendered as a full-surface article or as embeddable cards. An optional formatting toolbar exposes headings, lists, links, and other common markdown actions, and dispositional toolbar actions contributed by other plugins are surfaced inline alongside it.
+
+    The editor integrates with the rest of the workspace through @ references that link to any ECHO object, image and file uploads stored in the active space, and anchored comment threads on text ranges. Comments can optionally be routed to an AI agent on every message or only on @mention.
+
+    A built-in blueprint exposes create, open, and update operations as tools for AI agents. Updates are applied as compact find-and-replace diffs against the document, making it safe for agents to edit large documents incrementally while you continue collaborating.
   `,
   icon: 'ph--text-aa--regular',
   iconHue: 'indigo',
   source: 'https://github.com/dxos/dxos/tree/main/packages/plugins/plugin-markdown',
-  screenshots: ['https://dxos.network/plugin-details-markdown-dark.png'],
-};
+  screenshots: [
+    'https://customer-5rxcjpyab08avpmn.cloudflarestream.com/cdf2656365bb1fd327c1fc2105d75e5a/iframe?poster=https%3A%2F%2Fcustomer-5rxcjpyab08avpmn.cloudflarestream.com%2Fcdf2656365bb1fd327c1fc2105d75e5a%2Fthumbnails%2Fthumbnail.jpg%3Ftime%3D%26height%3D600',
+    'https://dxos.network/plugin-details-markdown-dark.png',
+  ],
+});

package/src/operations/create-markdown.ts

@@ -0,0 +1,19 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Operation } from '@dxos/compute';
+
+import { Markdown, MarkdownOperation } from '../types';
+
+const handler: Operation.WithHandler<typeof MarkdownOperation.CreateMarkdown> = MarkdownOperation.CreateMarkdown.pipe(
+  Operation.withHandler(({ name, content }) =>
+    Effect.succeed({
+      object: Markdown.make({ name, content }),
+    }),
+  ),
+);
+
+export default handler;