@dxos/react-ui-editor 0.10.0 → 0.11.0

package/src/stories/Widgets.stories.tsx

@@ -10,7 +10,7 @@
  */
 
 import { type Meta, type StoryObj } from '@storybook/react-vite';
-import React, { useEffect, useMemo, useState } from 'react';
+import React, { useEffect, useMemo, useRef, useState } from 'react';
 import { createPortal } from 'react-dom';
 
 import { random } from '@dxos/random';
@@ -35,9 +35,11 @@ import { EditorPreviewProvider, useEditorPreview } from '../components';
 import { useTextEditor } from '../hooks';
 import { EditorStory } from './components';
 
-// ----------------------------------------------------------------------------
+random.seed(123);
+
+//
 // XmlTags helpers
-// ----------------------------------------------------------------------------
+//
 
 const xmlRegistry = {
   test: {
@@ -85,9 +87,9 @@ const XmlTagsStory = ({ text }: { text?: string }) => {
   );
 };
 
-// ----------------------------------------------------------------------------
+//
 // Preview helpers
-// ----------------------------------------------------------------------------
+//
 
 const handlePreviewLookup = async ({ dxn, label }: PreviewLinkRef): Promise<PreviewLinkTarget> => {
   random.seed(dxn.split('').reduce((acc: number, char: string) => acc + char.charCodeAt(0), 1));
@@ -140,16 +142,82 @@ const PreviewBlockCard = ({ dxn, label }: XmlWidgetProps<{ dxn: string; label: s
       </Card.Header>
       {text && (
         <Card.Row>
-          <Card.Text className='text-description'>{text}</Card.Text>
+          <Card.Text classNames='text-description'>{text}</Card.Text>
         </Card.Row>
       )}
     </Card.Root>
   );
 };
 
-// ----------------------------------------------------------------------------
+/** Obsidian-style height suffix in the image label: `![Sketch|400](echo:/…)`. */
+const parseBlockHeight = (label = ''): number | undefined => {
+  const match = /\|(\d+)$/.exec(label);
+  return match ? Number.parseInt(match[1], 10) : undefined;
+};
+
+/**
+ * Fixed-height block that mirrors the plugin-markdown sketch embed: it renders at exactly the height
+ * encoded in the label, so CM's reserved `estimatedHeight` and the measured height match — the setup
+ * that exercises the scroll/cull path (jitter, blank, flash, jump) without needing ECHO.
+ */
+const FixedHeightPreview = ({ label, dxn }: XmlWidgetProps<{ label: string; dxn: string }>) => {
+  const height = parseBlockHeight(label) ?? 200;
+  return (
+    <div
+      style={{ height }}
+      className='grid place-items-center border border-separator rounded-md bg-base-surface text-description'
+    >
+      {label} · {height}px · {dxn}
+    </div>
+  );
+};
+
+/**
+ * Faithfully mimics a Surface-backed embed (the real plugin-markdown block): the content mounts
+ * asynchronously (like a Surface resolving) and runs an inner ResizeObserver (like the sketch's
+ * auto-fit) that re-lays-out whenever the container size changes — including the 0↔height blips that
+ * CM's scroll-culling produces as the node is detached and re-parented.
+ *
+ * NOTE: The scroll-*jump* on large scroll deltas is NOT specific to this async variant — verified via
+ * Playwright, `FixedHeightPreview` (plain inert div) jumps identically. It is CM's height-estimate
+ * re-anchor, not the widget. See `StubWidget` and CM #1727.
+ */
+const SurfaceLikePreview = ({ label, dxn }: XmlWidgetProps<{ label: string; dxn: string }>) => {
+  const height = parseBlockHeight(label) ?? 200;
+  const ref = useRef<HTMLDivElement>(null);
+  const [resolved, setResolved] = useState(false);
+  // Async resolution, like a Surface looking up + mounting its component.
+  useEffect(() => {
+    const timer = setTimeout(() => setResolved(true), 30);
+    return () => clearTimeout(timer);
+  }, []);
+  // Inner ResizeObserver that does layout work on every size change, like the sketch's auto-fit.
+  useEffect(() => {
+    const element = ref.current;
+    if (!element) {
+      return;
+    }
+    const observer = new ResizeObserver(() => {
+      // Touch layout the way an auto-fit would (read forces reflow).
+      void element.clientHeight;
+    });
+    observer.observe(element);
+    return () => observer.disconnect();
+  }, []);
+  return (
+    <div
+      ref={ref}
+      style={{ height }}
+      className='grid place-items-center border border-separator rounded-md bg-base-surface text-description'
+    >
+      {resolved ? `Surface ${label} · ${height}px · ${dxn}` : 'resolving…'}
+    </div>
+  );
+};
+
+//
 // Meta
-// ----------------------------------------------------------------------------
+//
 
 const meta = {
   title: 'ui/react-ui-editor/Widgets',
@@ -161,9 +229,9 @@ export default meta;
 
 type Story = StoryObj<typeof meta>;
 
-// ----------------------------------------------------------------------------
+//
 // Stories
-// ----------------------------------------------------------------------------
+//
 
 const xmlTagsText = trim`
   # XML Tags
@@ -197,6 +265,8 @@ const previewText = trim`
 
   ![ECHO](echo:/echo)
 
+  Text
+
 `;
 
 /**
@@ -239,3 +309,85 @@ export const Preview: Story = {
     );
   },
 };
+
+const filler = (marker: string) =>
+  Array.from({ length: 20 }, (_, index) => `${marker} ${index + 1} - ${random.lorem.paragraphs()}`).join('\n\n');
+
+const previewScrollText = [
+  '# Preview blocks (scroll test)',
+  filler('Above'),
+  '![Sketch|400](echo:/sketch)',
+  filler('Below'),
+].join('\n\n');
+
+/**
+ * A fixed-height (400px) `echo:` block embed in a long scrollable document. Sets `estimatedHeight`
+ * from the label so CM reserves the right space, matching the plugin-markdown sketch embed. Use this
+ * to reproduce scroll behavior: scroll the block off-screen and back, and past the viewport edges.
+ */
+export const PreviewScroll: Story = {
+  render: () => {
+    const [widgets, setWidgets] = useState<XmlWidgetState[]>([]);
+    const extensions = useMemo(
+      () => [
+        xmlTags({
+          registry: {
+            'dxn-preview': {
+              block: true,
+              urlSchemes: ['dxn:', 'echo:'],
+              estimatedHeight: ({ label }: XmlWidgetProps<{ label?: string }>) => parseBlockHeight(label),
+              Component: FixedHeightPreview,
+            },
+          },
+          setWidgets,
+        }),
+      ],
+      [],
+    );
+
+    return (
+      <>
+        <EditorStory text={previewScrollText} extensions={extensions} />
+        {widgets.map(({ id, root, Component, props }) => (
+          <div key={id}>{createPortal(<Component {...props} />, root)}</div>
+        ))}
+      </>
+    );
+  },
+};
+
+/**
+ * Same long scrollable document as `PreviewScroll`, but the block renders a Surface-like component
+ * (async mount + inner ResizeObserver). Use this to reproduce the scroll jump that only appears with
+ * Surface-backed embeds, and to verify fixes against it.
+ */
+export const PreviewScrollSurface: Story = {
+  render: () => {
+    const [widgets, setWidgets] = useState<XmlWidgetState[]>([]);
+    const extensions = useMemo(
+      () => [
+        xmlTags({
+          registry: {
+            'dxn-preview': {
+              block: true,
+              urlSchemes: ['dxn:', 'echo:'],
+              estimatedHeight: ({ label }: XmlWidgetProps<{ label?: string }>) => parseBlockHeight(label),
+              Component: SurfaceLikePreview,
+            },
+          },
+          setWidgets,
+        }),
+      ],
+      [],
+    );
+
+    return (
+      <>
+        <EditorStory text={previewScrollText} extensions={extensions} />
+        {widgets.map(({ id, root, Component, props }) => (
+          <div key={id}>{createPortal(<Component {...props} />, root)}</div>
+        ))}
+      </>
+    );
+  },
+};

package/src/stories/components/EditorStory.tsx

@@ -9,7 +9,6 @@ import { Obj } from '@dxos/echo';
 import { TestSchema } from '@dxos/echo/testing';
 import { invariant } from '@dxos/invariant';
 import { PublicKey } from '@dxos/keys';
-import { log } from '@dxos/log';
 import { useMergeRefs, useThemeContext } from '@dxos/react-ui';
 import { useAttentionAttributes } from '@dxos/react-ui-attention';
 import { Syntax } from '@dxos/react-ui-syntax-highlighter';
@@ -50,6 +49,7 @@ export const EditorStory = forwardRef<EditorController, EditorStoryProps>(
   ({ debug, debugCustom, text, extensions: extensionsProp, ...props }, forwardedRef) => {
     const controllerRef = useRef<EditorController>(null);
     const mergedRef = useMergeRefs([controllerRef, forwardedRef]);
+    const view = controllerRef.current?.view;
 
     const attentionAttrs = useAttentionAttributes('test-panel');
     const [tree, setTree] = useState<DebugNode>();
@@ -60,14 +60,13 @@ export const EditorStory = forwardRef<EditorController, EditorStoryProps>(
       [debug, extensionsProp],
     );
 
-    const view = controllerRef.current?.view;
     return (
       <div className={mx('dx-container grid', debug && 'grid-cols-2 lg:grid-cols-[1fr_600px]')}>
         <EditorComponent ref={mergedRef} object={object} text={text} extensions={extensions} {...props} />
 
         {debug && (
           <div
-            className='grid h-full auto-rows-fr border-l border-separator divide-y divide-separator overflow-hidden'
+            className='grid h-full auto-rows-fr border-l border-separator divide-y divide-subdued-separator overflow-hidden'
             {...attentionAttrs}
           >
             {view && debugCustom?.(view)}
@@ -124,8 +123,19 @@ const EditorComponent = forwardRef<EditorController, EditorStoryProps>(
         selection,
         initialValue: text,
         extensions: [
-          createBasicExtensions({ readOnly, placeholder, lineNumbers, scrollPastEnd: true, search: true }),
-          createThemeExtensions({ monospace, themeMode, syntaxHighlighting: true, slots }),
+          createBasicExtensions({
+            lineNumbers,
+            placeholder,
+            readOnly,
+            scrollPastEnd: true,
+            search: true,
+          }),
+          createThemeExtensions({
+            monospace,
+            slots,
+            syntaxHighlighting: true,
+            themeMode,
+          }),
           createMarkdownExtensions(),
           extensions || [],
         ],
@@ -135,7 +145,6 @@ const EditorComponent = forwardRef<EditorController, EditorStoryProps>(
 
     // External controller.
     useImperativeHandle(forwardedRef, () => {
-      log.info('view updated', { id });
       return createEditorController(view);
     }, [id, view]);
 

package/src/stories/components/util.tsx

@@ -13,18 +13,56 @@ import {
   folding,
   formattingKeymap,
   image,
+  join,
   linkTooltip,
   table,
 } from '@dxos/ui-editor';
 import { type RenderCallback } from '@dxos/ui-editor/types';
 import { safeUrl } from '@dxos/util';
 
+random.seed(1);
+
 import { str } from '../../util';
 
 export const num = () => random.number.int({ min: 0, max: 9999 }).toLocaleString();
 
 export const img = '![dxos](https://dxos.network/dxos-logotype-blue.png)';
 
+export type GenerateListOptions = {
+  /** Maximum nesting depth. */
+  depth?: number;
+  /** Children per node — a fixed count or an inclusive `[min, max]` range. */
+  children?: number | [number, number];
+  /** Emit task markers (`- [ ]`) rather than plain bullets (`- `). */
+  task?: boolean;
+  /** Spaces of indentation per level. */
+  indent?: number;
+  /** Content generator for each item (default: a lorem sentence). */
+  content?: () => string;
+};
+
+/**
+ * Generates a hierarchical markdown list for the outliner stories. Deterministic under `random.seed`.
+ */
+export const generateList = ({
+  depth = 3,
+  children = [1, 3],
+  task = true,
+  indent = 2,
+  content = () => random.lorem.sentence(),
+}: GenerateListOptions = {}): string => {
+  const count = (value: number | [number, number]): number =>
+    Array.isArray(value) ? random.number.int({ min: value[0], max: value[1] }) : value;
+
+  const build = (level: number): string[] =>
+    Array.from({ length: count(children) }).flatMap(() => {
+      const line = ' '.repeat(indent * level) + (task ? '- [ ] ' : '- ') + content();
+      return level + 1 < depth ? [line, ...build(level + 1)] : [line];
+    });
+
+  return join(...build(0));
+};
+
 export const code = str(
   // prettier-ignore
   '// Code',
@@ -231,13 +269,13 @@ export const renderLinkButton: RenderCallback<{ url: string }> = (el, { url }) =
 export const defaultExtensions: Extension[] = [
   decorateMarkdown({ renderLinkButton, selectionChangeDelay: 100 }),
   formattingKeymap(),
-  linkTooltip(renderLinkTooltip),
+  linkTooltip({ render: renderLinkTooltip }),
 ];
 
 export const allExtensions: Extension[] = [
   decorateMarkdown({ renderLinkButton, selectionChangeDelay: 100, numberedHeadings: { from: 2, to: 4 } }),
   formattingKeymap(),
-  linkTooltip(renderLinkTooltip),
+  linkTooltip({ render: renderLinkTooltip }),
   image(),
   table(),
   folding(),