@dxos/react-ui-editor 0.9.1-main.c7dcc2e112 → 0.10.0

package/src/stories/Widgets.stories.tsx

@@ -0,0 +1,241 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+/**
+ * Stories demonstrating the xmlTags widget-portal mechanism in ui-editor.
+ *
+ * Both XmlTags and Preview stories use the same underlying pattern: a CodeMirror WidgetType
+ * creates a DOM placeholder, and React portals render content into it.
+ */
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React, { useEffect, useMemo, useState } from 'react';
+import { createPortal } from 'react-dom';
+
+import { random } from '@dxos/random';
+import { Card, Icon, Popover, useThemeContext } from '@dxos/react-ui';
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+import {
+  AnchorWidget,
+  type XmlWidgetProps,
+  type XmlWidgetRegistry,
+  type XmlWidgetState,
+  createBasicExtensions,
+  createThemeExtensions,
+  decorateMarkdown,
+  extendedMarkdown,
+  image,
+  xmlTags,
+} from '@dxos/ui-editor';
+import { type PreviewLinkRef, type PreviewLinkTarget } from '@dxos/ui-types';
+import { safeParseInt, trim } from '@dxos/util';
+
+import { EditorPreviewProvider, useEditorPreview } from '../components';
+import { useTextEditor } from '../hooks';
+import { EditorStory } from './components';
+
+// ----------------------------------------------------------------------------
+// XmlTags helpers
+// ----------------------------------------------------------------------------
+
+const xmlRegistry = {
+  test: {
+    block: true,
+    Component: ({ start = '0' }: { start?: string }) => {
+      const [count, setCount] = useState<number>(safeParseInt(start, 0));
+      useEffect(() => {
+        const interval = setInterval(() => {
+          setCount((prev) => {
+            if (prev >= 200) {
+              clearInterval(interval);
+              return prev;
+            }
+            return prev + 1;
+          });
+        }, 100);
+        return () => clearInterval(interval);
+      }, []);
+      return <div className='p-2 border border-separator rounded-sm'>Test {count}</div>;
+    },
+  },
+} satisfies XmlWidgetRegistry;
+
+const XmlTagsStory = ({ text }: { text?: string }) => {
+  const { themeMode } = useThemeContext();
+  const [widgets, setWidgets] = useState<XmlWidgetState[]>([]);
+  const { parentRef } = useTextEditor({
+    initialValue: text,
+    extensions: [
+      createThemeExtensions({ themeMode }),
+      createBasicExtensions({ lineWrapping: true }),
+      decorateMarkdown(),
+      extendedMarkdown({ registry: xmlRegistry }),
+      xmlTags({ registry: xmlRegistry, setWidgets }),
+    ],
+  });
+
+  return (
+    <>
+      <div ref={parentRef} className='w-full p-4' />
+      {widgets.map(({ id, root, Component, props }) => (
+        <div key={id}>{createPortal(<Component {...props} />, root)}</div>
+      ))}
+    </>
+  );
+};
+
+// ----------------------------------------------------------------------------
+// Preview helpers
+// ----------------------------------------------------------------------------
+
+const handlePreviewLookup = async ({ dxn, label }: PreviewLinkRef): Promise<PreviewLinkTarget> => {
+  random.seed(dxn.split('').reduce((acc: number, char: string) => acc + char.charCodeAt(0), 1));
+  return { label };
+};
+
+const PreviewCard = () => {
+  const { target } = useEditorPreview('PreviewCard');
+  if (!target) {
+    return null;
+  }
+  return (
+    <Popover.Portal>
+      <Popover.Content onOpenAutoFocus={(event) => event.preventDefault()}>
+        <Popover.Viewport classNames='dx-card-popover-width'>
+          <Card.Root border={false}>
+            <Card.Header>
+              <Card.Block>
+                <Icon icon='ph--file-text--regular' />
+              </Card.Block>
+              <Card.Title>{target.label}</Card.Title>
+              <Popover.Close asChild>
+                <Card.ActionIconButton action='close' />
+              </Popover.Close>
+            </Card.Header>
+            <Card.Row>
+              <Card.Text variant='description'>{target.label}</Card.Text>
+            </Card.Row>
+          </Card.Root>
+        </Popover.Viewport>
+        <Popover.Arrow />
+      </Popover.Content>
+    </Popover.Portal>
+  );
+};
+
+const PreviewBlockCard = ({ dxn, label }: XmlWidgetProps<{ dxn: string; label: string }>) => {
+  const [text, setText] = useState<string | undefined>();
+  useEffect(() => {
+    random.seed(dxn.split('').reduce((acc: number, char: string) => acc + char.charCodeAt(0), 1));
+    setText(Array.from({ length: 2 }, () => random.lorem.paragraphs()).join('\n\n'));
+  }, [dxn]);
+  return (
+    <Card.Root>
+      <Card.Header>
+        <Card.Block>
+          <Icon icon='ph--arrow-square-up--regular' />
+        </Card.Block>
+        <Card.Title>{label}</Card.Title>
+      </Card.Header>
+      {text && (
+        <Card.Row>
+          <Card.Text className='text-description'>{text}</Card.Text>
+        </Card.Row>
+      )}
+    </Card.Root>
+  );
+};
+
+// ----------------------------------------------------------------------------
+// Meta
+// ----------------------------------------------------------------------------
+
+const meta = {
+  title: 'ui/react-ui-editor/Widgets',
+  decorators: [withTheme(), withLayout({ layout: 'fullscreen' })],
+  parameters: { layout: 'fullscreen' },
+} satisfies Meta;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+// ----------------------------------------------------------------------------
+// Stories
+// ----------------------------------------------------------------------------
+
+const xmlTagsText = trim`
+  # XML Tags
+
+  React widget below.
+
+  <test id="t-1" />
+
+  <test id="t-2" start="100" />
+
+  React widget above.
+`;
+
+/**
+ * XML tag names in the document trigger React components via xmlTags.
+ */
+export const XmlTags: Story = {
+  render: () => <XmlTagsStory text={xmlTagsText} />,
+};
+
+const previewText = trim`
+  # Preview
+
+  This project is part of the [DXOS](echo:/123) SDK.
+
+  ![DXOS](echo:/123)
+
+  It consists of [ECHO](echo:/echo), [HALO](echo:/halo), and [MESH](echo:/mesh).
+
+  ## Deep dive
+
+  ![ECHO](echo:/echo)
+
+`;
+
+/**
+ * Markdown image/link URLs (echo:/…) trigger block widgets via xmlTags.
+ */
+export const Preview: Story = {
+  render: () => {
+    const [widgets, setWidgets] = useState<XmlWidgetState[]>([]);
+    const extensions = useMemo(
+      () => [
+        image(),
+        xmlTags({
+          registry: {
+            'dxn-preview': {
+              block: true,
+              urlSchemes: ['dxn:', 'echo:'],
+              Component: PreviewBlockCard,
+            },
+            'link-preview': {
+              block: false,
+              urlSchemes: ['dxn:', 'echo:'],
+              factory: ({ label, dxn }: XmlWidgetProps<{ label: string; dxn: string }>) =>
+                label && dxn ? new AnchorWidget(label, dxn) : null,
+            },
+          },
+          setWidgets,
+        }),
+      ],
+      [],
+    );
+
+    return (
+      <EditorPreviewProvider onLookup={handlePreviewLookup}>
+        <EditorStory text={previewText} extensions={extensions} />
+        <PreviewCard />
+        {widgets.map(({ id, root, Component, props }) => (
+          <div key={id}>{createPortal(<Component {...props} />, root)}</div>
+        ))}
+      </EditorPreviewProvider>
+    );
+  },
+};

package/src/stories/components/util.tsx

@@ -211,7 +211,7 @@ const hover =
 export const renderLinkTooltip: RenderCallback<{ url: string }> = (el, { url }) => {
   el.appendChild(
     Domino.of('a')
-      .attributes({ href: url, target: '_blank', rel: 'noreferrer', 'aria-label': 'Open link' })
+      .attributes({ 'href': url, 'target': '_blank', 'rel': 'noreferrer', 'aria-label': 'Open link' })
       .classNames(hover, 'flex items-center gap-2')
       .text(safeUrl(url)?.toString() ?? url)
       .append(Domino.svg('ph--arrow-square-out--regular')).root,

package/dist/types/src/stories/Preview.stories.d.ts

@@ -1,26 +0,0 @@
-import { type EditorView } from '@codemirror/view';
-import { type StoryObj } from '@storybook/react-vite';
-import React from 'react';
-import { type EditorController } from '../components';
-declare const meta: {
-    title: string;
-    component: React.ForwardRefExoticComponent<Pick<import("..").UseTextEditorProps, "extensions" | "id" | "scrollTo" | "selection"> & Pick<import("@dxos/ui-editor").ThemeExtensionsOptions, "slots"> & {
-        debug?: import("./components").DebugMode;
-        debugCustom?: (view: EditorView) => React.ReactNode;
-        text?: string;
-        object?: import("@dxos/echo/Obj").OfShape<import("@dxos/echo/testing").TestSchema.Expando>;
-        readOnly?: boolean;
-        placeholder?: string;
-        lineNumbers?: boolean;
-        monospace?: boolean;
-        onReady?: (view: EditorView) => void;
-    } & React.RefAttributes<EditorController>>;
-    decorators: import("@storybook/react").Decorator[];
-    parameters: {
-        layout: string;
-    };
-};
-export default meta;
-type Story = StoryObj<typeof meta>;
-export declare const Default: Story;
-//# sourceMappingURL=Preview.stories.d.ts.map

package/dist/types/src/stories/Preview.stories.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"Preview.stories.d.ts","sourceRoot":"","sources":["../../../../src/stories/Preview.stories.tsx"],"names":[],"mappings":"AAKA,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAa,KAAK,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACjE,OAAO,KAAoD,MAAM,OAAO,CAAC;AAmBzE,OAAO,EAAE,KAAK,gBAAgB,EAA2C,MAAM,eAAe,CAAC;AAwK/F,QAAA,MAAM,IAAI;;;;;;;;;;;;;;;QAKN,MAAM;;CAE0B,CAAC;eAEtB,IAAI;AAEnB,KAAK,KAAK,GAAG,QAAQ,CAAC,OAAO,IAAI,CAAC,CAAC;AAiBnC,eAAO,MAAM,OAAO,EAAE,KA8BrB,CAAC"}

package/dist/types/src/stories/Tags.stories.d.ts

@@ -1,16 +0,0 @@
-import { type StoryObj } from '@storybook/react-vite';
-import React from 'react';
-declare const meta: {
-    title: string;
-    render: ({ text }: {
-        text?: string;
-    }) => React.JSX.Element;
-    decorators: import("@storybook/react").Decorator[];
-    parameters: {
-        layout: string;
-    };
-};
-export default meta;
-type Story = StoryObj<typeof meta>;
-export declare const Default: Story;
-//# sourceMappingURL=Tags.stories.d.ts.map

package/dist/types/src/stories/Tags.stories.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"Tags.stories.d.ts","sourceRoot":"","sources":["../../../../src/stories/Tags.stories.tsx"],"names":[],"mappings":"AAIA,OAAO,EAAa,KAAK,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACjE,OAAO,KAA8B,MAAM,OAAO,CAAC;AAiFnD,QAAA,MAAM,IAAI;;uBApCsB;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE;;;QAyC7C,MAAM;;CAE2B,CAAC;eAEvB,IAAI;AAEnB,KAAK,KAAK,GAAG,QAAQ,CAAC,OAAO,IAAI,CAAC,CAAC;AAEnC,eAAO,MAAM,OAAO,EAAE,KAIrB,CAAC"}

package/src/stories/Preview.stories.tsx

@@ -1,253 +0,0 @@
-//
-// Copyright 2023 DXOS.org
-//
-
-import { syntaxTree } from '@codemirror/language';
-import { type EditorView } from '@codemirror/view';
-import { type Meta, type StoryObj } from '@storybook/react-vite';
-import React, { useCallback, useEffect, useMemo, useState } from 'react';
-import { createPortal } from 'react-dom';
-
-import { invariant } from '@dxos/invariant';
-import { random } from '@dxos/random';
-import { Card, Icon, IconButton, Popover } from '@dxos/react-ui';
-import { Menu, createMenuAction } from '@dxos/react-ui-menu';
-import { withLayout, withTheme } from '@dxos/react-ui/testing';
-import {
-  type PreviewBlock,
-  type PreviewLinkRef,
-  type PreviewLinkTarget,
-  getLinkRef,
-  image,
-  preview,
-} from '@dxos/ui-editor';
-import { hoverableControls } from '@dxos/ui-theme';
-import { trim } from '@dxos/util';
-
-import { type EditorController, EditorPreviewProvider, useEditorPreview } from '../components';
-import { EditorStory } from './components';
-
-const handlePreviewLookup = async ({ dxn, label }: PreviewLinkRef): Promise<PreviewLinkTarget> => {
-  // Random text.
-  random.seed(dxn.split('').reduce((acc: number, char: string) => acc + char.charCodeAt(0), 1));
-  const text = Array.from({ length: 2 }, () => random.lorem.paragraphs()).join('\n\n');
-  return {
-    label,
-    text,
-  };
-};
-
-// Async lookup.
-// TODO(burdon): Handle errors.
-const useRefTarget = (link: PreviewLinkRef): PreviewLinkTarget | undefined => {
-  const [target, setTarget] = useState<PreviewLinkTarget | undefined>();
-  useEffect(() => {
-    void handlePreviewLookup(link).then((target) => setTarget(target ?? undefined));
-  }, [link]);
-
-  return target;
-};
-
-const PreviewCard = () => {
-  const { target } = useEditorPreview('PreviewCard');
-  if (!target) {
-    return null;
-  }
-
-  return (
-    <Popover.Portal>
-      <Popover.Content onOpenAutoFocus={(event) => event.preventDefault()}>
-        <Popover.Viewport classNames='dx-card-popover-width'>
-          <Card.Root border={false}>
-            <Card.Header>
-              <Card.Block>
-                <Icon icon='ph--file-text--regular' />
-              </Card.Block>
-              <Card.Title>{target.label}</Card.Title>
-              <Popover.Close asChild>
-                <Card.ActionIconButton action='close' />
-              </Popover.Close>
-            </Card.Header>
-            <Card.Row>
-              <Card.Text variant='description'>{target.text}</Card.Text>
-            </Card.Row>
-          </Card.Root>
-        </Popover.Viewport>
-        <Popover.Arrow />
-      </Popover.Content>
-    </Popover.Portal>
-  );
-};
-
-type PreviewAction =
-  | {
-      type: 'insert';
-      link: PreviewLinkRef;
-      target: PreviewLinkTarget;
-    }
-  | {
-      type: 'delete';
-      link: PreviewLinkRef;
-    };
-
-const PreviewBlockComponent = ({ link, el, view }: { link: PreviewLinkRef; el: HTMLElement; view?: EditorView }) => {
-  const target = useRefTarget(link);
-
-  const handleAction = useCallback(
-    (action: PreviewAction) => {
-      invariant(view, 'View not found');
-      const pos = view.posAtDOM(el);
-      const node = syntaxTree(view.state).resolve(pos + 1).node.parent;
-      if (!node) {
-        return;
-      }
-
-      const link = getLinkRef(view.state, node);
-      if (link?.dxn !== action.link.dxn) {
-        return;
-      }
-
-      switch (action.type) {
-        // TODO(burdon): Should we dispatch to the view or mutate the document? (i.e., handle externally?)
-        // Insert ref text.
-        case 'insert': {
-          view.dispatch({
-            changes: {
-              from: node.from,
-              to: node.to,
-              insert: action.target.text,
-            },
-          });
-          break;
-        }
-        // Remove ref.
-        case 'delete': {
-          view.dispatch({
-            changes: {
-              from: node.from,
-              to: node.to,
-            },
-          });
-          break;
-        }
-      }
-    },
-    [view, el],
-  );
-
-  const handleDelete = useCallback(() => {
-    handleAction({ type: 'delete', link });
-  }, [handleAction, link]);
-
-  const handleInsert = useCallback(() => {
-    if (target) {
-      handleAction({ type: 'insert', link, target });
-    }
-  }, [handleAction, link, target]);
-
-  const menuItems = useMemo(
-    () => [
-      createMenuAction('delete', handleDelete, {
-        label: link.suggest ? 'Discard' : 'Delete',
-        icon: 'ph--x--regular',
-      }),
-      ...(target
-        ? [
-            createMenuAction('apply', handleInsert, {
-              label: 'Apply',
-              icon: 'ph--check--regular',
-            }),
-          ]
-        : []),
-    ],
-    [handleDelete, handleInsert, link.suggest, target],
-  );
-
-  return createPortal(
-    <Menu.Root>
-      <Card.Root classNames={hoverableControls}>
-        {!view?.state.readOnly && (
-          <Card.Header>
-            <Card.Block>
-              <Icon icon='ph--bookmark--regular' />
-            </Card.Block>
-            <Card.Title>{link.label}</Card.Title>
-            {/* TODO(wittjosiah): Reconcile with Card.Menu. */}
-            <Card.Block end>
-              <Menu.Trigger asChild disabled={!menuItems?.length}>
-                <IconButton iconOnly variant='ghost' icon='ph--dots-three-vertical--regular' label='Menu' />
-              </Menu.Trigger>
-            </Card.Block>
-            <Menu.Content items={menuItems} />
-          </Card.Header>
-        )}
-        {target && (
-          <Card.Row>
-            <Card.Text className='text-description'>{target.text}</Card.Text>
-          </Card.Row>
-        )}
-      </Card.Root>
-    </Menu.Root>,
-    el,
-  );
-};
-
-const meta = {
-  title: 'ui/react-ui-editor/Preview',
-  component: EditorStory,
-  decorators: [withTheme(), withLayout({ layout: 'fullscreen' })],
-  parameters: {
-    layout: 'fullscreen',
-  },
-} satisfies Meta<typeof EditorStory>;
-
-export default meta;
-
-type Story = StoryObj<typeof meta>;
-
-const text = trim`
-  # Preview
-
-  This project is part of the [DXOS](echo:/123) SDK.
-
-  ![DXOS](echo:/123)
-
-  It consists of [ECHO](echo:/echo), [HALO](echo:/halo), and [MESH](echo:/mesh).
-
-  ## Deep dive
-
-  ![ECHO](echo:/echo)
-
-`;
-
-export const Default: Story = {
-  render: () => {
-    const [controller, setController] = useState<EditorController | null>(null);
-    const [previewBlocks, setPreviewBlocks] = useState<PreviewBlock[]>([]);
-    const extensions = useMemo(() => {
-      return [
-        image(),
-        preview({
-          addBlockContainer: (block) => {
-            setPreviewBlocks((prev) => [...prev, block]);
-          },
-          removeBlockContainer: (block) => {
-            setPreviewBlocks((prev) => prev.filter(({ link: prevLink }) => prevLink.dxn !== block.link.dxn));
-          },
-        }),
-      ];
-    }, []);
-
-    // TODO(burdon): Migrate to Editor.Root.
-    return (
-      <EditorPreviewProvider onLookup={handlePreviewLookup}>
-        <EditorStory ref={setController} text={text} extensions={extensions} />
-        <PreviewCard />
-        {controller?.view &&
-          previewBlocks.map(({ link, el }) => (
-            <PreviewBlockComponent key={link.dxn} link={link} el={el} view={controller.view!} />
-          ))}
-      </EditorPreviewProvider>
-    );
-  },
-};

package/src/stories/Tags.stories.tsx

@@ -1,104 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import { type Meta, type StoryObj } from '@storybook/react-vite';
-import React, { useEffect, useState } from 'react';
-import { createPortal } from 'react-dom';
-
-import { useThemeContext } from '@dxos/react-ui';
-import { withLayout, withTheme } from '@dxos/react-ui/testing';
-import {
-  type XmlWidgetRegistry,
-  type XmlWidgetState,
-  createBasicExtensions,
-  createThemeExtensions,
-  decorateMarkdown,
-  extendedMarkdown,
-  xmlTags,
-} from '@dxos/ui-editor';
-import { safeParseInt, trim } from '@dxos/util';
-
-import { useTextEditor } from '../hooks';
-
-const registry = {
-  /**
-   * Custom tag: <test/>
-   */
-  test: {
-    block: true,
-    Component: ({ start = '0' }) => {
-      const [count, setCount] = useState<number>(safeParseInt(start, 0));
-      useEffect(() => {
-        const interval = setInterval(() => {
-          setCount((prev) => {
-            if (prev >= 200) {
-              clearInterval(interval);
-              return prev;
-            }
-
-            return prev + 1;
-          });
-        }, 100);
-        return () => clearInterval(interval);
-      }, []);
-
-      return <div className='p-2 border border-separator rounded-sm'>Test {count}</div>;
-    },
-  },
-} satisfies XmlWidgetRegistry;
-
-const DefaultStory = ({ text }: { text?: string }) => {
-  const { themeMode } = useThemeContext();
-  const [widgets, setWidgets] = useState<XmlWidgetState[]>([]);
-  const { parentRef } = useTextEditor({
-    initialValue: text,
-    extensions: [
-      createThemeExtensions({ themeMode }),
-      createBasicExtensions({ lineWrapping: true }),
-      decorateMarkdown(),
-      extendedMarkdown({ registry }),
-      xmlTags({ registry, setWidgets }),
-    ],
-  });
-
-  return (
-    <>
-      <div ref={parentRef} className='w-full p-4' />
-      {widgets.map(({ id, root, Component, props }) => (
-        <div key={id}>{createPortal(<Component {...props} />, root)}</div>
-      ))}
-    </>
-  );
-};
-
-const text = trim`
-  # Tags
-
-  React widget below.
-
-  <test id="t-1" />
-
-  <test id="t-2" start="100" />
-
-  React widget above.
-`;
-
-const meta = {
-  title: 'ui/react-ui-editor/Tags',
-  render: DefaultStory,
-  decorators: [withTheme(), withLayout({ layout: 'fullscreen' })],
-  parameters: {
-    layout: 'fullscreen',
-  },
-} satisfies Meta<typeof DefaultStory>;
-
-export default meta;
-
-type Story = StoryObj<typeof meta>;
-
-export const Default: Story = {
-  args: {
-    text,
-  },
-};