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

package/src/hooks/useExtensions.tsx

@@ -0,0 +1,268 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { type ViewUpdate } from '@codemirror/view';
+import { useMemo } from 'react';
+
+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';
+import {
+  Cursor,
+  type EditorStateStore,
+  EditorView,
+  type Extension,
+  InputModeExtensions,
+  type PreviewOptions,
+  createDataExtensions,
+  decorateMarkdown,
+  documentId,
+  folding,
+  formattingKeymap,
+  linkTooltip,
+  listener,
+  preview,
+  replacer,
+  selectionState,
+  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 { setFallbackName } from '../util';
+
+export type DocumentType = Markdown.Document | Text.Text | { id: string; text: string };
+
+export type ExtensionsOptions = {
+  id: string;
+  object?: DocumentType;
+  settings?: Markdown.Settings;
+  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.
+export const useExtensions = ({
+  id,
+  object,
+  settings,
+  compact,
+  viewMode,
+  selectionManager,
+  editorStateStore,
+  previewOptions,
+  onSelectObject,
+}: ExtensionsOptions): Extension[] => {
+  const { platform } = useThemeContext();
+  const identity = useIdentity();
+  const space = getSpace(object);
+
+  // Get the content reference from Document objects.
+  const contentRef = Obj.instanceOf(Markdown.Document, object) ? (object as Markdown.Document).content : undefined;
+  // Use useObject to trigger re-render when the reference loads (returns snapshot for reactivity).
+  useObject(contentRef);
+  // Get the actual live object target via .target (needed for createDocAccessor).
+  const target = contentRef?.target ?? (Obj.instanceOf(Text.Text, object) ? object : undefined);
+
+  // TODO(wittjosiah): Autocomplete is not working and this query is causing performance issues.
+  // TODO(burdon): Unsubscribe.
+  // const query = space?.db.query(Filter.type(DocumentType));
+  // query?.subscribe();
+
+  const baseExtensions = useMemo(
+    () =>
+      createBaseExtensions({
+        id,
+        object,
+        settings,
+        compact,
+        viewMode,
+        selectionManager,
+        previewOptions,
+        platform,
+        onSelectObject,
+      }),
+    [
+      id,
+      object,
+      compact,
+      viewMode,
+      selectionManager,
+      previewOptions,
+      settings,
+      settings?.debug,
+      settings?.editorInputMode,
+      settings?.folding,
+      settings?.numberedHeadings,
+      platform,
+      onSelectObject,
+    ],
+  );
+
+  return useMemo<Extension[]>(
+    () =>
+      [
+        // TODO(burdon): Pass this in?
+        // NOTE: Data extensions must be first so that automerge is updated before other extensions compute their state.
+        target &&
+          createDataExtensions({
+            id,
+            text: createDocAccessor(target, ['content']),
+            messenger: space,
+            identity,
+          }),
+
+        // TODO(burdon): Reconcile with effect in parent.
+        Obj.instanceOf(Markdown.Document, object) &&
+          listener({
+            onChange: ({ text }) => {
+              setFallbackName(object as Markdown.Document, text);
+            },
+          }),
+
+        baseExtensions,
+        selectionState(editorStateStore),
+      ].filter(isTruthy),
+    [identity, space, id, object, target, baseExtensions],
+  );
+};
+
+/**
+ * Create extension instances for editor.
+ */
+const createBaseExtensions = ({
+  id,
+  object,
+  onSelectObject,
+  settings,
+  compact,
+  viewMode,
+  selectionManager,
+  previewOptions,
+  platform,
+}: ExtensionsOptions): Extension[] => {
+  const extensions: Extension[] = [
+    selectionManager && selectionChange(selectionManager),
+    settings?.editorInputMode && InputModeExtensions[settings.editorInputMode],
+    settings?.folding && !compact && platform !== 'mobile' && folding(),
+  ].filter(isTruthy);
+
+  //
+  // Markdown
+  //
+  if (viewMode !== 'source') {
+    extensions.push(
+      ...[
+        formattingKeymap(),
+        decorateMarkdown({
+          selectionChangeDelay: 100,
+          numberedHeadings: settings?.numberedHeadings ? { from: 2 } : undefined,
+          // TODO(wittjosiah): For internal links render the label of the object.
+          renderLinkButton: onSelectObject && createRenderLink(onSelectObject),
+        }),
+        linkTooltip(renderLinkTooltip),
+        preview(previewOptions),
+        replacer(),
+      ],
+    );
+  }
+
+  if (settings?.debug) {
+    const items = settings.snippets?.split(/[,\n]/) ?? '';
+    if (items) {
+      extensions.push(snippets({ items }));
+    }
+  }
+
+  return extensions;
+};
+
+const selectionChange = (selectionManager: SelectionManager) => {
+  const debouncedHandler = debounceAndThrottle((update: ViewUpdate) => {
+    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),
+      }));
+
+    selectionManager.updateMultiRange(id, ranges);
+  }, 100);
+
+  return EditorView.updateListener.of((update: ViewUpdate) => {
+    if (update.selectionSet) {
+      debouncedHandler(update);
+    }
+  });
+};
+
+const createRenderLink =
+  (onSelectObject: (id: string) => void): RenderCallback<{ url: string }> =>
+  (el, { url }) => {
+    // TODO(burdon): Formalize/document internal link format.
+    const isInternal = url.startsWith('/') || url.startsWith(window.location.origin);
+    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) {
+      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(icon.root);
+  };
+
+const renderLinkTooltip: RenderCallback<{ url: string }> = (el, { url }) => {
+  el.appendChild(
+    Domino.of('a')
+      .attributes({ href: url, target: '_blank', rel: 'noreferrer' })
+      .classNames('dx-link flex items-center gap-2')
+      .text(safeUrl(url)?.toString() ?? url)
+      .append(Domino.svg('ph--arrow-square-out--regular')).root,
+  );
+};

package/src/hooks/useLinkQuery.ts

@@ -0,0 +1,93 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as Option from 'effect/Option';
+import { useCallback, useMemo } from 'react';
+
+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 filter = useMemo(
+    () =>
+      Filter.or(
+        ...(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],
+  );
+
+  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();
+
+      const getLabel = (object: Obj.Unknown): Label => {
+        const type = Obj.getTypename(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))
+          .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,
+              onSelect: ({ view, head }) => {
+                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 {
+                  insertAtCursor(view, head, `${link} `);
+                }
+              },
+            };
+          }) ?? [];
+
+      // 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, t],
+  );
+
+  return handleLinkQuery;
+};

package/src/index.ts

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

package/src/meta.ts

@@ -2,18 +2,28 @@
 // Copyright 2023 DXOS.org
 //
 
-import { type PluginMeta } from '@dxos/app-framework';
+import { Plugin } from '@dxos/app-framework';
+import { DXN } from '@dxos/keys';
 import { trim } from '@dxos/util';
 
-export const meta: PluginMeta = {
-  id: 'dxos.org/plugin/markdown',
+export const meta = Plugin.makeMeta({
+  key: DXN.make('org.dxos.plugin.markdown'),
   name: 'Markdown',
+  author: 'DXOS',
   description: trim`
-    A collaborative and extensible Markdown editor.
-    In addition to markdown capabilities, the plugin supports collaborative in-line comments.
-    You can use documents to extend the memory of your personal agents and add context for automated workflows.
+    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;