@dxos/react-ui-canvas 0.13.0 → 0.14.0

package/src/components/SceneView/Constrained.stories.tsx

@@ -87,7 +87,7 @@ const DefaultStory = () => {
 };
 
 const meta: Meta = {
-  title: 'ui/react-ui-canvas/scene/Constrained',
+  title: 'ui/react-ui-canvas/Constrained',
   render: DefaultStory,
   decorators: [withRegistry, withTheme(), withLayout({ layout: 'fullscreen' })],
 };

package/src/components/SceneView/Dock.stories.tsx

@@ -0,0 +1,95 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React, { useLayoutEffect, useMemo } from 'react';
+import { expect, userEvent, waitFor, within } from 'storybook/test';
+
+import { translations as formTranslations } from '@dxos/react-ui-form/translations';
+import { withLayout, withRegistry, withTheme } from '@dxos/react-ui/testing';
+import { translations as uiTranslations } from '@dxos/react-ui/translations';
+
+import { useRegistry } from '../../hooks/index.ts';
+import { createSceneViewAtoms } from '../../model/atoms.ts';
+import { createMemoryStore } from '../../model/store.ts';
+import { type Layer } from '../../model/types.ts';
+import { SceneBuilder } from '../../utils/builder.ts';
+import { between } from '../../utils/order.ts';
+import { SceneView } from './SceneView.tsx';
+
+const box = (x: number, y = 0) => ({ x, y, width: 256, height: 128 });
+
+/** A scene with two layers and a shape on each. */
+const createTree = () => {
+  const background: Layer = { id: 'background', name: 'Background', z: between() };
+  const diagram: Layer = { id: 'diagram', name: 'Diagram', z: between(background.z) };
+  const tree = SceneBuilder.scene('root', [
+    SceneBuilder.rect('a', box(0)).properties({ label: 'Rect', layer: 'diagram' }),
+    SceneBuilder.rect('b', box(400)).properties({ label: 'Other', layer: 'background' }),
+  ]).build();
+  const [scene, ...rest] = tree.scenes;
+  return { root: tree.root, scenes: [{ ...scene, layers: { background, diagram } }, ...rest] };
+};
+
+type StoryArgs = {
+  /** The element selected, whose properties fill the dock's first section. */
+  select?: string;
+};
+
+/** The docked panels alone: the properties, layers and about sections, without the canvas they sit beside. */
+const DefaultStory = ({ select }: StoryArgs) => {
+  const registry = useRegistry();
+  const { store, root } = useMemo(() => {
+    const tree = createTree();
+    return { store: createMemoryStore(tree.scenes), root: tree.root };
+  }, []);
+  const atoms = useMemo(() => createSceneViewAtoms(root), [root]);
+  useLayoutEffect(() => {
+    registry.set(atoms.selection, new Set(select ? [select] : []));
+  }, [registry, atoms, select]);
+  return (
+    <SceneView.Root store={store} root={root} atoms={atoms}>
+      <SceneView.Properties />
+      <SceneView.Layers />
+      <SceneView.About />
+    </SceneView.Root>
+  );
+};
+
+const meta: Meta<StoryArgs> = {
+  title: 'ui/react-ui-canvas/Dock',
+  render: DefaultStory,
+  decorators: [withRegistry, withTheme(), withLayout({ layout: 'fullscreen' })],
+  args: { select: 'a' },
+  parameters: { translations: [...uiTranslations, ...formTranslations] },
+};
+
+export default meta;
+
+type Story = StoryObj<StoryArgs>;
+
+/** A shape selected: its properties above the scene's layers. */
+export const Default: Story = {};
+
+/** Nothing selected: the properties section says so rather than going away. */
+export const Empty: Story = { args: { select: undefined } };
+
+/** Each section's header collapses it. */
+export const Test: Story = {
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    // 1. Both sections are open, the properties showing the selected shape's layer.
+    const dock = await canvas.findByTestId('scene-view-dock');
+    await waitFor(() => expect(within(dock).getByTestId('dock-section-layers')).toHaveAttribute('data-state', 'open'));
+    await expect(await within(dock).findByRole('combobox', { name: 'Layer' })).toHaveTextContent('Diagram');
+    // 2. The properties header collapses its section.
+    await userEvent.click(within(dock).getByRole('button', { name: 'Properties' }));
+    await waitFor(() =>
+      expect(within(dock).getByTestId('dock-section-properties')).toHaveAttribute('data-state', 'closed'),
+    );
+    // 3. The about section follows the layers, its figures those of the scene.
+    await expect(within(dock).getByTestId('about-nodes')).toHaveTextContent('2');
+    await expect(within(dock).getByTestId('about-layers')).toHaveTextContent('2');
+  },
+};

package/src/components/SceneView/Dock.tsx

@@ -0,0 +1,146 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+//
+// The dock: a column beside the canvas that panels move into when the view's panels are docked, one accordion
+// section per panel. A panel registers its section and portals itself into the section's slot.
+//
+
+import React, {
+  type PropsWithChildren,
+  type ReactNode,
+  type SyntheticEvent,
+  createContext,
+  useCallback,
+  useContext,
+  useLayoutEffect,
+  useMemo,
+  useState,
+} from 'react';
+import { createPortal } from 'react-dom';
+
+import * as Accordion from '@dxos/react-ui/Accordion';
+import * as ScrollArea from '@dxos/react-ui/ScrollArea';
+
+/** A panel's section in the dock. */
+export type DockSection = {
+  id: string;
+  title: string;
+  icon: string;
+  /** Sections stack by it, lowest first. */
+  order: number;
+};
+
+type DockContextValue = {
+  sections: readonly DockSection[];
+  slots: Readonly<Record<string, HTMLDivElement | null>>;
+  closed: ReadonlySet<string>;
+  register: (section: DockSection) => () => void;
+  setSlot: (id: string, element: HTMLDivElement | null) => void;
+  setClosed: (closed: ReadonlySet<string>) => void;
+};
+
+const DockContext = createContext<DockContextValue | undefined>(undefined);
+
+/** Holds the docked sections and their slots for a view's `Dock` and its panels. */
+export const DockProvider = ({ children }: PropsWithChildren) => {
+  const [sections, setSections] = useState<DockSection[]>([]);
+  const [slots, setSlots] = useState<Record<string, HTMLDivElement | null>>({});
+  // Closed rather than open, so a section that docks later starts open.
+  const [closed, setClosed] = useState<ReadonlySet<string>>(new Set());
+  const register = useCallback((section: DockSection) => {
+    setSections((current) =>
+      [...current.filter((entry) => entry.id !== section.id), section].sort((left, right) => left.order - right.order),
+    );
+    return () => setSections((current) => current.filter((entry) => entry.id !== section.id));
+  }, []);
+  const setSlot = useCallback(
+    (id: string, element: HTMLDivElement | null) =>
+      setSlots((current) => (current[id] === element ? current : { ...current, [id]: element })),
+    [],
+  );
+  const value = useMemo(
+    () => ({ sections, slots, closed, register, setSlot, setClosed }),
+    [sections, slots, closed, register, setSlot],
+  );
+  return <DockContext.Provider value={value}>{children}</DockContext.Provider>;
+};
+
+/** A section's slot; its ref callback is stable, since a new one each render would detach and reattach (a loop). */
+const DockSlot = ({ id, setSlot }: { id: string; setSlot: DockContextValue['setSlot'] }) => {
+  const ref = useCallback((element: HTMLDivElement | null) => setSlot(id, element), [id, setSlot]);
+  return <div ref={ref} />;
+};
+
+/** Stops a docked panel's events at the dock: through the portal they would reach the canvas root (hover, menus). */
+const stop = (event: SyntheticEvent) => event.stopPropagation();
+
+/**
+ * The dock column: an accordion of the registered sections, any number open, each as tall as its panel, the column
+ * scrolling them together. Nothing (and no space) while no panel is docked.
+ */
+export const Dock = () => {
+  const dock = useContext(DockContext);
+  if (!dock || dock.sections.length === 0) {
+    return null;
+  }
+  const { sections, closed, setSlot, setClosed } = dock;
+  return (
+    // The column is the scroll area itself: each section is as tall as its panel, and it scrolls them together.
+    <ScrollArea.Root
+      classNames='w-80 shrink-0 border-l border-separator-subtle bg-base-surface'
+      data-testid='scene-view-dock'
+    >
+      <ScrollArea.Viewport>
+        <Accordion.Root
+          border={false}
+          onPointerDown={stop}
+          onPointerMove={stop}
+          onPointerUp={stop}
+          onDoubleClick={stop}
+          onContextMenu={stop}
+          onKeyDown={stop}
+          value={sections.filter((section) => !closed.has(section.id)).map((section) => section.id)}
+          onValueChange={(open) =>
+            setClosed(new Set(sections.filter((section) => !open.includes(section.id)).map((section) => section.id)))
+          }
+        >
+          {sections.map((section) => (
+            <Accordion.Item key={section.id} value={section.id} data-testid={`dock-section-${section.id}`}>
+              {/* A distinct surface, so a section's header reads apart from its panel's own toolbar. */}
+              <Accordion.ItemTrigger icon={section.icon} classNames='bg-group-surface'>
+                {section.title}
+              </Accordion.ItemTrigger>
+              <Accordion.ItemContent>
+                <DockSlot id={section.id} setSlot={setSlot} />
+              </Accordion.ItemContent>
+            </Accordion.Item>
+          ))}
+        </Accordion.Root>
+      </ScrollArea.Viewport>
+    </ScrollArea.Root>
+  );
+};
+
+/**
+ * Registers a section while `docked`, and renders `panel` into it: docked, the panel's portal into the dock (once its
+ * slot mounts); floating, `null`, so the caller renders the panel where it floats.
+ */
+export const useDockSection = (section: DockSection, docked: boolean, panel: ReactNode): ReactNode | null => {
+  const dock = useContext(DockContext);
+  const { id, title, icon, order } = section;
+  useLayoutEffect(() => {
+    if (!dock || !docked) {
+      return;
+    }
+    return dock.register({ id, title, icon, order });
+    // `register` is stable; the section re-registers only when it changes.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [dock?.register, docked, id, title, icon, order]);
+  if (!docked) {
+    return null;
+  }
+  const slot = dock?.slots[id];
+  return slot ? createPortal(panel, slot) : null;
+};

package/src/components/SceneView/Dynamic.stories.tsx

@@ -126,7 +126,7 @@ const DefaultStory = () => {
 };
 
 const meta: Meta = {
-  title: 'ui/react-ui-canvas/scene/Dynamic',
+  title: 'ui/react-ui-canvas/Dynamic',
   render: DefaultStory,
   decorators: [withRegistry, withTheme(), withLayout({ layout: 'fullscreen' })],
 };

package/src/components/SceneView/SceneView.stories.tsx

@@ -4,18 +4,20 @@
 
 import { type Meta, type StoryObj } from '@storybook/react-vite';
 import React, { useMemo } from 'react';
+import { expect, userEvent, waitFor, within } from 'storybook/test';
 
 import { translations as formTranslations } from '@dxos/react-ui-form/translations';
 import { withLayout, withRegistry, withTheme } from '@dxos/react-ui/testing';
 import { translations as uiTranslations } from '@dxos/react-ui/translations';
 
+import { type PanelMode } from '../../model/atoms.ts';
 import { createLatticeProjection } from '../../model/projections/lattice.ts';
 import { createMemoryStore } from '../../model/store.ts';
 import { type Box, SceneBuilder } from '../../utils/builder.ts';
 import { DEFAULT_LATTICE, cellBounds } from '../../utils/lattice.ts';
 import { DEFAULT_SHAPE_SIZE } from '../../utils/shapes.ts';
 import { TONES } from '../../utils/style.ts';
-import { createClassSceneTree, createSceneTree } from '../../utils/testing.ts';
+import { createModelSceneTree, createSceneTree } from '../../utils/testing.ts';
 import { SceneView } from './SceneView.tsx';
 
 /**
@@ -26,9 +28,9 @@ import { SceneView } from './SceneView.tsx';
  * 3. L / K / P pick the line, curve or spline link tool: every port shows; dropping onto empty canvas creates a
  *    rectangle and links to it. A selected spline shows a diamond per control point and a dot per span midpoint:
  *    drag a diamond to move a point, drag a dot to add one there, alt-click a diamond to remove one.
- * 4. R / E / C / T / S then drag draws a rectangle, ellipse, UML class, text or nested scene; Delete removes the
- *    selection (nodes or links).
- * 5. Double-click a portal (or zoom until it fills the view) drills in; Escape, Up or the breadcrumb drills out.
+ * 4. R / E / T / F then drag draws a rectangle, ellipse, text or frame (the UML class is plugin-uml's);
+ *    Delete removes the selection (nodes or links).
+ * 5. Double-click a frame (or zoom until it fills the view) drills in; Escape, Up or the breadcrumb drills out.
  * 6. G (or the Grid button) toggles the grid; with it off nothing snaps. The floating panel (top right) edits the
  *    selected element.
  */
@@ -36,7 +38,8 @@ type StoryArgs = {
   depth: number;
   liveDepth: number;
   readonly?: boolean;
-  fixture?: 'elements' | 'classes' | 'square' | 'lattice';
+  fixture?: 'elements' | 'model' | 'square' | 'lattice' | 'scenes' | 'frame';
+  panels?: PanelMode;
 };
 
 type EditorProps = {
@@ -45,13 +48,15 @@ type EditorProps = {
   liveDepth: number;
   readonly?: boolean;
   lattice?: boolean;
+  panels?: PanelMode;
 };
 
-const Editor = ({ store, root, liveDepth, readonly, lattice }: EditorProps) => (
+const Editor = ({ store, root, liveDepth, readonly, lattice, panels }: EditorProps) => (
   <SceneView.Root
     store={store}
     root={root}
     readonly={readonly}
+    panels={panels}
     createProjection={lattice ? createLatticeProjection : undefined}
   >
     <SceneView.Canvas liveDepth={liveDepth} />
@@ -60,6 +65,8 @@ const Editor = ({ store, root, liveDepth, readonly, lattice }: EditorProps) => (
     <SceneView.Debug />
     <SceneView.Palette />
     <SceneView.Properties />
+    <SceneView.Layers />
+    <SceneView.About />
   </SceneView.Root>
 );
 
@@ -92,11 +99,11 @@ const createLatticeTree = () => {
     ...[box('a', at(-1, -1), 'A'), box('b', at(-1, 0), 'B'), box('c', at(-1, 1), 'C')].map((element) =>
       element.properties({ style: { hue: 'neutral' } }),
     ),
-    box('d', at(0, 0), 'D').properties({ style: { hue: 'green', tone: 1 } }),
-    box('e', at(0, 1), 'E').properties({ style: { hue: 'green', tone: 3 } }),
+    box('d', at(0, 0), 'D').properties({ style: { hue: 'green', tone: 3 } }),
+    box('e', at(0, 1), 'E').properties({ style: { hue: 'green', tone: 1 } }),
     // Unlabelled, so the scene shows its contents.
     SceneBuilder.scene('f', [
-      // One hue at each of its tones, lightest to strongest.
+      // One hue at each of its tones: outline, then strongest to lightest.
       ...TONES.map((tone, index) =>
         box(`f${index + 1}`, at(0, index - 1), `F${index + 1}`).properties({ style: { hue: 'blue', tone } }),
       ),
@@ -123,17 +130,105 @@ const createLatticeTree = () => {
     .build();
 };
 
-const DefaultStory = ({ depth, liveDepth, readonly, fixture }: StoryArgs) => {
+/**
+ * Three levels, every shape 256×128: A, scene B, C; inside B, D, scene E, F, with two rectangles either side
+ * of E; inside E, X, Y, Z with a box above X, below Z and beside each; each level's shapes linked. Open the
+ * scenes to check that a shape is the same size at the same zoom on every level.
+ */
+const createScenesTree = () => {
+  const root = 'scene:root';
+  const size = { width: 256, height: 128 };
+  const at = (y: number, x = 0) => ({ x: x - size.width / 2, y: y - size.height / 2, ...size });
+  const rect = (id: string, y: number, x = 0) =>
+    SceneBuilder.rect(id, at(y, x)).properties({ label: id.toUpperCase() });
+  // An unlabelled box beside the column.
+  const box = (id: string, y: number, x: number) => SceneBuilder.rect(id, at(y, x));
+  const link = (from: string, to: string) => SceneBuilder.link('smart', from, to);
+  return SceneBuilder.scene(root, [
+    rect('a', -256),
+    SceneBuilder.scene('b', [
+      rect('d', -256),
+      // X, Y, Z down the middle, with a box above X, below Z and either side of each.
+      SceneBuilder.scene('e', [
+        box('n', -512, 0),
+        box('xw', -256, -384),
+        rect('x', -256),
+        box('xe', -256, 384),
+        rect('y', 0),
+        box('zw', 256, -384),
+        rect('z', 256),
+        box('ze', 256, 384),
+        box('s', 512, 0),
+        link('n', 'x'),
+        link('xw', 'x'),
+        link('x', 'xe'),
+        link('x', 'y'),
+        link('y', 'z'),
+        link('zw', 'z'),
+        link('z', 'ze'),
+        link('z', 's'),
+      ])
+        .at(at(0))
+        .name('E'),
+      rect('f', 256),
+      // Two rectangles either side of E.
+      rect('g', 0, -768),
+      rect('h', 0, -384),
+      rect('i', 0, 384),
+      rect('j', 0, 768),
+      link('d', 'e'),
+      link('e', 'f'),
+      link('g', 'h'),
+      link('h', 'e'),
+      link('e', 'i'),
+      link('i', 'j'),
+    ])
+      .at(at(0))
+      .name('B'),
+    rect('c', 256),
+    link('a', 'b'),
+    link('b', 'c'),
+  ])
+    .name('root')
+    .build();
+};
+
+/** A labelled frame onto a nested scene of two linked shapes, beside a rectangle. */
+const createFrameTree = () => {
+  const root = 'scene:root';
+  const size = { width: 256, height: 128 };
+  const at = (x: number, y = 0) => ({ x: x - size.width / 2, y: y - size.height / 2, ...size });
+  return SceneBuilder.scene(root, [
+    SceneBuilder.rect('a', at(-384)).properties({ label: 'A' }),
+    SceneBuilder.scene('frame', [
+      SceneBuilder.rect('b', at(-192)).properties({ label: 'B' }),
+      SceneBuilder.rect('c', at(192)).properties({ label: 'C' }),
+      SceneBuilder.link('smart', 'b', 'c'),
+    ])
+      .name('Inner')
+      .at({ x: 0, y: -128, width: 512, height: 256 })
+      .properties({ label: 'Frame' }),
+    SceneBuilder.link('smart', 'a', 'frame'),
+  ])
+    .name('root')
+    .build();
+};
+
+const DefaultStory = ({ depth, liveDepth, readonly, fixture, panels }: StoryArgs) => {
   const { store, root } = useMemo(() => {
-    // The class fixture is a fixed three levels, so `depth` does not apply to it.
+    // The model fixture is a fixed three levels, so `depth` does not apply to it.
     const tree =
-      fixture === 'classes'
-        ? createClassSceneTree()
+      fixture === 'model'
+        ? createModelSceneTree()
         : fixture === 'square'
           ? createSquareTree()
           : fixture === 'lattice'
             ? createLatticeTree()
-            : createSceneTree(depth);
+            : fixture === 'scenes'
+              ? createScenesTree()
+              : fixture === 'frame'
+                ? createFrameTree()
+                : createSceneTree(depth);
     return { store: createMemoryStore(tree.scenes), root: tree.root };
   }, [depth, fixture]);
 
@@ -146,17 +241,23 @@ const DefaultStory = ({ depth, liveDepth, readonly, fixture }: StoryArgs) => {
       liveDepth={liveDepth}
       readonly={readonly}
       lattice={fixture === 'lattice'}
+      panels={panels}
     />
   );
 };
 
 const meta: Meta<StoryArgs> = {
-  title: 'ui/react-ui-canvas/scene/SceneView',
+  title: 'ui/react-ui-canvas/SceneView',
   render: DefaultStory,
   decorators: [withRegistry, withTheme(), withLayout({ layout: 'fullscreen' })],
   // The properties panel is a react-ui-form form; its strings (e.g. "Mixed") and its controls' come from their bundles.
   parameters: { translations: [...uiTranslations, ...formTranslations] },
   argTypes: {
+    panels: {
+      control: { type: 'inline-radio' },
+      options: ['docked', 'floating'],
+      description: 'Where the properties and layers panels sit',
+    },
     depth: {
       control: { type: 'range', min: 0, max: 5, step: 1 },
       description: 'Levels of nested scenes in the fixture; 0 is an empty scene',
@@ -192,15 +293,66 @@ export const Readonly: Story = {
   args: { depth: 1, liveDepth: 1, readonly: true },
 };
 
-/** A three-level class model: drill into a subsystem's portal to open its own classes. */
-export const Classes: Story = {
-  args: { depth: 0, liveDepth: 1, fixture: 'classes' },
+/** A three-level model, a box per class: drill into a subsystem's portal to open its own. */
+export const Model: Story = {
+  args: { depth: 0, liveDepth: 1, fixture: 'model' },
 };
 
 /**
  * Lattice mode (DESIGN §8b): shapes snap to whole cells of a 256x128 lattice with 128x64 gutters, span any number
  * of cells, and may not overlap; a drag onto occupied cells previews in red and is refused.
  */
+/** A, an empty scene B and C in a column: open B, draw in it, and compare sizes at 100% on both levels. */
+export const Scenes: Story = {
+  args: { depth: 0, liveDepth: 1, fixture: 'scenes' },
+};
+
 export const Lattice: Story = {
   args: { depth: 0, liveDepth: 1, fixture: 'lattice' },
 };
+
+/** The panels dock by default: one accordion section each beside the canvas; a section collapses to its header. */
+export const Docked: Story = {
+  args: { depth: 0, liveDepth: 1, fixture: 'square' },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    // 1. The dock holds the properties and layers sections, both open.
+    const dock = await canvas.findByTestId('scene-view-dock');
+    await waitFor(() => expect(within(dock).getByTestId('dock-section-layers')).toHaveAttribute('data-state', 'open'));
+    await expect(within(dock).getByTestId('dock-section-properties')).toHaveAttribute('data-state', 'open');
+    // 2. A section's header collapses it.
+    await userEvent.click(
+      within(within(dock).getByTestId('dock-section-properties')).getByRole('button', { name: 'Properties' }),
+    );
+    await waitFor(() =>
+      expect(within(dock).getByTestId('dock-section-properties')).toHaveAttribute('data-state', 'closed'),
+    );
+  },
+};
+
+/** Floating panels: no dock, the layers over the canvas until something is selected. */
+export const Floating: Story = {
+  args: { depth: 0, liveDepth: 1, fixture: 'square', panels: 'floating' },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(await canvas.findByTestId('layers')).toBeInTheDocument();
+    await expect(canvas.queryByTestId('scene-view-dock')).not.toBeInTheDocument();
+    // About lives only in the dock.
+    await expect(canvas.queryByTestId('about')).not.toBeInTheDocument();
+  },
+};
+
+/** A frame onto a nested scene: its open control drills into the child scene, and Up returns. */
+export const Frame: Story = {
+  args: { depth: 0, liveDepth: 1, fixture: 'frame' },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    // 1. The frame shows its label and an open control; the root has nowhere up to go.
+    await waitFor(() => expect(canvasElement.querySelector('[data-node-id="frame"]')).toHaveTextContent('Frame'));
+    await waitFor(() => expect(canvas.getByTestId('toolbar-up')).toBeDisabled());
+    // 2. Opening the frame drills into its scene.
+    await userEvent.click(await canvas.findByTestId('portal-open'));
+    await waitFor(() => expect(canvas.getByTestId('toolbar-up')).toBeEnabled());
+    await waitFor(() => expect(canvasElement.querySelector('[data-node-id="b"]')).not.toBeNull());
+  },
+};