@dxos/plugin-stack 0.9.0 → 0.9.1-staging.ee54ba693a

package/dx.config.ts

@@ -0,0 +1,32 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Config2 } from '@dxos/app-framework/config';
+import { trim } from '@dxos/util';
+
+export default Config2.make({
+  plugin: {
+    key: 'org.dxos.plugin.stack',
+    name: 'Stacks',
+    author: 'DXOS',
+    description: trim`
+      The Stack plugin renders any Collection as a vertically scrollable stack of collapsible sections in the
+      Composer article surface. Each section wraps an arbitrary ECHO object and delegates its content rendering
+      to the section surface role, enabling any other plugin to contribute its own section renderer.
+
+      Sections can be individually collapsed to show only their title, expanded to reveal full content, navigated
+      to directly, or removed from the collection. New sections can be inserted before or after any existing
+      section via a per-section dropdown menu, or appended via the toolbar Add button.
+
+      The plugin registers StackViewType with the ECHO schema module so that per-section view metadata
+      (height overrides, custom display data) can be stored and replicated alongside the collection.
+
+      A settings panel exposes a separation toggle that controls whether visual dividers are rendered between
+      sections.
+    `,
+    source: 'https://github.com/dxos/dxos/tree/main/packages/plugins/plugin-stack',
+    icon: { key: 'ph--stack-simple--regular' },
+    spec: 'PLUGIN.mdl',
+  },
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/plugin-stack",
-  "version": "0.9.0",
+  "version": "0.9.1-staging.ee54ba693a",
   "description": "DXOS Surface plugin for Stack entities",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -70,47 +70,53 @@
   "types": "dist/types/src/index.d.ts",
   "files": [
     "dist",
+    "dx.config.ts",
     "src",
     "PLUGIN.mdl"
   ],
   "dependencies": {
     "@effect-atom/atom-react": "^0.5.0",
     "@radix-ui/react-collapsible": "1.1.3",
-    "effect": "3.21.3",
-    "@dxos/app-framework": "0.9.0",
-    "@dxos/invariant": "0.9.0",
-    "@dxos/app-toolkit": "0.9.0",
-    "@dxos/echo": "0.9.0",
-    "@dxos/keys": "0.9.0",
-    "@dxos/operation": "0.9.0",
-    "@dxos/plugin-client": "0.9.0",
-    "@dxos/plugin-deck": "0.9.0",
-    "@dxos/react-ui-attention": "0.9.0",
-    "@dxos/react-ui-form": "0.9.0",
-    "@dxos/plugin-graph": "0.9.0",
-    "@dxos/react-ui-stack": "0.9.0",
-    "@dxos/util": "0.9.0",
-    "@dxos/plugin-space": "0.9.0"
+    "effect": "3.21.4",
+    "@dxos/app-framework": "0.9.1-staging.ee54ba693a",
+    "@dxos/echo": "0.9.1-staging.ee54ba693a",
+    "@dxos/app-toolkit": "0.9.1-staging.ee54ba693a",
+    "@dxos/keys": "0.9.1-staging.ee54ba693a",
+    "@dxos/invariant": "0.9.1-staging.ee54ba693a",
+    "@dxos/operation": "0.9.1-staging.ee54ba693a",
+    "@dxos/plugin-client": "0.9.1-staging.ee54ba693a",
+    "@dxos/plugin-deck": "0.9.1-staging.ee54ba693a",
+    "@dxos/plugin-graph": "0.9.1-staging.ee54ba693a",
+    "@dxos/plugin-space": "0.9.1-staging.ee54ba693a",
+    "@dxos/react-ui-attention": "0.9.1-staging.ee54ba693a",
+    "@dxos/react-ui-form": "0.9.1-staging.ee54ba693a",
+    "@dxos/util": "0.9.1-staging.ee54ba693a",
+    "@dxos/react-ui-mosaic": "0.9.1-staging.ee54ba693a",
+    "@dxos/react-ui-menu": "0.9.1-staging.ee54ba693a"
   },
   "devDependencies": {
     "@babel/core": "^7.18.13",
-    "@types/react": "~19.2.7",
+    "@types/react": "~19.2.17",
     "@types/react-dom": "~19.2.3",
-    "react": "~19.2.3",
-    "react-dom": "~19.2.3",
+    "react": "~19.2.7",
+    "react-dom": "~19.2.7",
     "vite": "^8.0.16",
-    "@dxos/plugin-testing": "0.9.0",
-    "@dxos/react-ui": "0.9.0",
-    "@dxos/storybook-utils": "0.9.0",
-    "@dxos/ui-theme": "0.9.0"
+    "@dxos/plugin-sketch": "0.9.1-staging.ee54ba693a",
+    "@dxos/plugin-markdown": "0.9.1-staging.ee54ba693a",
+    "@dxos/react-client": "0.9.1-staging.ee54ba693a",
+    "@dxos/plugin-testing": "0.9.1-staging.ee54ba693a",
+    "@dxos/ui-theme": "0.9.1-staging.ee54ba693a",
+    "@dxos/storybook-utils": "0.9.1-staging.ee54ba693a",
+    "@dxos/random": "0.9.1-staging.ee54ba693a",
+    "@dxos/react-ui": "0.9.1-staging.ee54ba693a"
   },
   "peerDependencies": {
     "@effect-atom/atom-react": "^0.5.0",
-    "effect": "3.21.3",
-    "react": "~19.2.3",
-    "react-dom": "~19.2.3",
-    "@dxos/react-ui": "0.9.0",
-    "@dxos/ui-theme": "0.9.0"
+    "effect": "3.21.4",
+    "react": "~19.2.7",
+    "react-dom": "~19.2.7",
+    "@dxos/react-ui": "0.9.1-staging.ee54ba693a",
+    "@dxos/ui-theme": "0.9.1-staging.ee54ba693a"
   },
   "publishConfig": {
     "access": "public"

package/src/StackPlugin.ts

@@ -8,17 +8,17 @@ import { AppPlugin } from '@dxos/app-toolkit';
 import { ReactSurface } from '#capabilities';
 import { meta } from '#meta';
 import { translations } from '#translations';
-import { StackViewType } from '#types';
+import { Stack } from '#types';
 
 // eslint-disable-next-line import/no-relative-packages
 import pluginSpec from '../PLUGIN.mdl?raw';
 
 export const StackPlugin = Plugin.define(meta).pipe(
-  AppPlugin.addSchemaModule({ schema: [StackViewType] }),
+  AppPlugin.addSchemaModule({ schema: [Stack.Stack] }),
   AppPlugin.addSurfaceModule({ activate: ReactSurface }),
   AppPlugin.addTranslationsModule({ translations }),
   AppPlugin.addPluginAssetModule({
-    asset: { pluginId: meta.id, path: 'PLUGIN.mdl', content: pluginSpec, mimeType: 'application/x-mdl' },
+    asset: { pluginId: meta.profile.key, path: 'PLUGIN.mdl', content: pluginSpec, mimeType: 'application/x-mdl' },
   }),
   Plugin.make,
 );

package/src/components/Stack/Stack.tsx

@@ -0,0 +1,319 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import React, {
+  type ComponentPropsWithoutRef,
+  type ForwardedRef,
+  type PropsWithChildren,
+  createContext,
+  forwardRef,
+  useCallback,
+  useContext,
+  useMemo,
+  useState,
+} from 'react';
+
+import { Surface } from '@dxos/app-framework/ui';
+import { Paths } from '@dxos/app-toolkit';
+import { AppSurface, AttentionSigilButton } from '@dxos/app-toolkit/ui';
+import { Obj } from '@dxos/echo';
+import {
+  DropdownMenu,
+  Icon,
+  ScrollArea,
+  ScrollAreaRootProps,
+  type ThemedClassName,
+  useTranslation,
+} from '@dxos/react-ui';
+import { useAttentionAttributes } from '@dxos/react-ui-attention';
+import { Mosaic, type MosaicEventHandler, type MosaicTileProps } from '@dxos/react-ui-mosaic';
+
+import { meta } from '#meta';
+
+//
+// Types
+//
+
+export type StackSectionItem = {
+  id: string;
+  object: Obj.Unknown;
+};
+
+//
+// Context
+//
+
+/** Section-level callbacks consumed by stack sections. */
+export type StackContextValue = {
+  attendableId: string;
+  /** Ids of sections that are currently collapsed. */
+  collapsed: ReadonlySet<string>;
+  onCollapse: (id: string, collapsed: boolean) => void;
+  /** Add a new section immediately after the given section. */
+  onAdd: (id: string) => void;
+  onMoveUp: (id: string) => void;
+  onMoveDown: (id: string) => void;
+  onDelete: (id: string) => void;
+};
+
+type StackContextType = StackContextValue & {
+  /** Container id used to scope Mosaic drag/drop. */
+  id: string;
+  eventHandler: MosaicEventHandler;
+  /** Scroll viewport element; threaded to the Mosaic container for autoscroll. */
+  viewport: HTMLElement | null;
+  setViewport: (element: HTMLElement | null) => void;
+};
+
+const StackContext = createContext<StackContextType | undefined>(undefined);
+
+const useStackContext = (consumer: string): StackContextType => {
+  const context = useContext(StackContext);
+  if (!context) {
+    throw new Error(`\`${consumer}\` must be used within \`Stack.Root\`.`);
+  }
+  return context;
+};
+
+/** Section-level callbacks consumed by stack sections. */
+export const useStack = (): StackContextValue => useStackContext('useStack');
+
+//
+// Root
+//
+
+type StackRootProps = PropsWithChildren<
+  StackContextValue & {
+    /** Container id used to scope Mosaic drag/drop. */
+    id: string;
+    /** Drag/drop event handler; defaults to a read-only (no-drop) handler. */
+    eventHandler?: MosaicEventHandler;
+  }
+>;
+
+const StackRoot = ({
+  id,
+  eventHandler,
+  children,
+  attendableId,
+  collapsed,
+  onCollapse,
+  onAdd,
+  onMoveUp,
+  onMoveDown,
+  onDelete,
+}: StackRootProps) => {
+  const [viewport, setViewport] = useState<HTMLElement | null>(null);
+  const value = useMemo<StackContextType>(
+    () => ({
+      id,
+      eventHandler: eventHandler ?? { id, canDrop: () => false },
+      viewport,
+      setViewport,
+      attendableId,
+      collapsed,
+      onCollapse,
+      onAdd,
+      onMoveUp,
+      onMoveDown,
+      onDelete,
+    }),
+    [id, eventHandler, viewport, attendableId, collapsed, onCollapse, onAdd, onMoveUp, onMoveDown, onDelete],
+  );
+
+  return (
+    <StackContext.Provider value={value}>
+      <Mosaic.Root>{children}</Mosaic.Root>
+    </StackContext.Provider>
+  );
+};
+
+StackRoot.displayName = 'Stack.Root';
+
+//
+// Content
+//
+
+type StackContentProps = ThemedClassName<
+  ComponentPropsWithoutRef<'div'> & Pick<ScrollAreaRootProps, 'centered' | 'thin' | 'padding'>
+>;
+
+const StackContent = forwardRef<HTMLDivElement, StackContentProps>(({ children, ...props }, forwardedRef) => {
+  const { eventHandler, viewport } = useStackContext('Stack.Content');
+  return (
+    <Mosaic.Container asChild orientation='vertical' autoScroll={viewport} eventHandler={eventHandler}>
+      <ScrollArea.Root {...props} orientation='vertical' ref={forwardedRef}>
+        {children}
+      </ScrollArea.Root>
+    </Mosaic.Container>
+  );
+});
+
+StackContent.displayName = 'Stack.Content';
+
+//
+// Viewport
+//
+
+type StackViewportProps = ThemedClassName<PropsWithChildren>;
+
+const StackViewport = forwardRef<HTMLDivElement, StackViewportProps>(
+  ({ classNames, children }, forwardedRef: ForwardedRef<HTMLDivElement>) => {
+    const { setViewport } = useStackContext('Stack.Viewport');
+    // Capture the viewport element for autoscroll while still honouring a forwarded ref.
+    const setRefs = useCallback(
+      (element: HTMLDivElement | null) => {
+        setViewport(element);
+        if (typeof forwardedRef === 'function') {
+          forwardedRef(element);
+        } else if (forwardedRef) {
+          forwardedRef.current = element;
+        }
+      },
+      [setViewport, forwardedRef],
+    );
+
+    return (
+      <ScrollArea.Viewport classNames={classNames} ref={setRefs}>
+        {children}
+      </ScrollArea.Viewport>
+    );
+  },
+);
+
+StackViewport.displayName = 'Stack.Viewport';
+
+//
+// Section
+//
+
+type StackSectionProps = MosaicTileProps<StackSectionItem>;
+
+/**
+ * A stack section rendered as a Mosaic tile: a 40px left rail (drag handle + section menu) beside the
+ * main content area, which renders the object's content surface (or its title when collapsed). The
+ * rail sticks to the top of the scroll viewport while the section is in view.
+ */
+// TODO(burdon): All sections are intrinsic (content-sized) for now. Extrinsic content (e.g. a sketch
+//   with no intrinsic height) should later get a Mosaic-native resizable height affordance.
+
+// Inline grip glyph for the drag preview. The native drag image does not rasterize external SVG sprite
+// `<use>` icons (e.g. `@dxos/react-ui` `Icon`), so the preview uses plain inline SVG circles instead.
+const DragHandleGlyph = () => (
+  <svg width={10} height={16} viewBox='0 0 10 16' aria-hidden className='shrink-0 text-description'>
+    {[3, 8, 13].flatMap((cy) =>
+      [2.5, 7.5].map((cx) => <circle key={`${cx}-${cy}`} cx={cx} cy={cy} r={1.1} fill='currentColor' />),
+    )}
+  </svg>
+);
+
+const StackSection = ({ data, ...tileProps }: StackSectionProps) => {
+  const { id, object } = data;
+  const { t } = useTranslation(meta.profile.key);
+  const { attendableId: parentAttendableId, collapsed, onAdd, onMoveUp, onMoveDown, onCollapse, onDelete } = useStack();
+  const [optionsMenuOpen, setOptionsMenuOpen] = useState(false);
+  const attendableId = Paths.getCollectionObjectPath(parentAttendableId, object.id);
+  const attentionAttrs = useAttentionAttributes(attendableId);
+  const surfaceData = useMemo(() => ({ attendableId, subject: object }), [object, attendableId]);
+  const isCollapsed = collapsed.has(id);
+  const icon = Obj.getIcon(object)?.icon ?? 'ph--circle-dashed--regular';
+  const title = Obj.getLabel(object, { fallback: 'typename' }) ?? t('untitled-section.title');
+
+  const rail = (
+    <div className='grid grid-rows-[min-content_1fr]'>
+      <div className='p-1 bg-toolbar-surface'>
+        <DropdownMenu.Root open={optionsMenuOpen} onOpenChange={setOptionsMenuOpen}>
+          <DropdownMenu.Trigger asChild>
+            <AttentionSigilButton size='md' attendableId={attendableId}>
+              <Icon icon={icon} classNames='transition-opacity' />
+            </AttentionSigilButton>
+          </DropdownMenu.Trigger>
+          <DropdownMenu.Portal>
+            <DropdownMenu.Content>
+              <DropdownMenu.Viewport>
+                {isCollapsed ? (
+                  <DropdownMenu.Item onClick={() => onCollapse(id, false)} data-testid='section.expand'>
+                    <Icon icon='ph--arrows-out-line-vertical--regular' />
+                    <span className='ms-2 grow'>{t('expand.label')}</span>
+                  </DropdownMenu.Item>
+                ) : (
+                  <DropdownMenu.Item onClick={() => onCollapse(id, true)} data-testid='section.collapse'>
+                    <Icon icon='ph--arrows-in-line-vertical--regular' />
+                    <span className='ms-2 grow'>{t('collapse.label')}</span>
+                  </DropdownMenu.Item>
+                )}
+                <DropdownMenu.Separator />
+                <DropdownMenu.Item onClick={() => onAdd(id)} data-testid='section.add'>
+                  <Icon icon='ph--plus--regular' />
+                  <span className='ms-2 grow'>{t('add-section.label')}</span>
+                </DropdownMenu.Item>
+                <DropdownMenu.Item onClick={() => onMoveUp(id)} data-testid='section.move-up'>
+                  <Icon icon='ph--arrow-line-up--regular' />
+                  <span className='ms-2 grow'>{t('move-up.label')}</span>
+                </DropdownMenu.Item>
+                <DropdownMenu.Item onClick={() => onMoveDown(id)} data-testid='section.move-down'>
+                  <Icon icon='ph--arrow-line-down--regular' />
+                  <span className='ms-2 grow'>{t('move-down.label')}</span>
+                </DropdownMenu.Item>
+                <DropdownMenu.Separator />
+                <DropdownMenu.Item onClick={() => onDelete(id)} data-testid='section.remove'>
+                  <Icon icon='ph--trash--regular' />
+                  <span className='ms-2 grow'>{t('remove-section.label')}</span>
+                </DropdownMenu.Item>
+              </DropdownMenu.Viewport>
+              <DropdownMenu.Arrow />
+            </DropdownMenu.Content>
+          </DropdownMenu.Portal>
+        </DropdownMenu.Root>
+      </div>
+      <div className='p-1'>
+        {/* Inline glyph (not a sprite `Icon`) so the handle stays visible in the tile's native drag image. */}
+        <Mosaic.DragHandle
+          label={t('drag-handle.label')}
+          classNames='p-1 min-h-0 w-(--dx-rail-item) h-(--dx-rail-item)'
+          testId='section.drag-handle'
+        >
+          <DragHandleGlyph />
+        </Mosaic.DragHandle>
+      </div>
+    </div>
+  );
+
+  return (
+    <Mosaic.Tile
+      {...tileProps}
+      data={data}
+      classNames='grid grid-cols-[var(--dx-rail-action)_1fr] dx-attention-surface border border-subdued-separator'
+    >
+      <div className='border-e border-subdued-separator'>
+        <div className='sticky top-0 flex flex-col items-center'>{rail}</div>
+      </div>
+      <div {...attentionAttrs} className='min-w-0'>
+        <span className='sr-only'>{title}</span>
+        {isCollapsed ? (
+          <div className='h-(--dx-toolbar-size) flex p-1'>
+            <h2 className='flex items-center font-medium'>{title}</h2>
+          </div>
+        ) : (
+          <Surface.Surface type={AppSurface.Section} data={surfaceData} limit={1} />
+        )}
+      </div>
+    </Mosaic.Tile>
+  );
+};
+
+StackSection.displayName = 'Stack.Section';
+
+//
+// Stack
+//
+
+export const Stack = {
+  Root: StackRoot,
+  Content: StackContent,
+  Viewport: StackViewport,
+  Section: StackSection,
+};
+
+export type { StackContentProps, StackRootProps, StackSectionProps, StackViewportProps };

package/src/components/{StackContext → Stack}/index.ts

@@ -2,4 +2,4 @@
 // Copyright 2024 DXOS.org
 //
 
-export * from './StackContext';
+export * from './Stack';

package/src/components/index.ts

@@ -2,6 +2,4 @@
 // Copyright 2023 DXOS.org
 //
 
-export * from './StackContext';
-export * from './StackSection';
-export * from './StackSettings';
+export * from './Stack';

package/src/containers/StackArticle/StackArticle.stories.tsx

@@ -0,0 +1,122 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import * as Effect from 'effect/Effect';
+import React from 'react';
+
+import { Capability } from '@dxos/app-framework';
+import { withPluginManager } from '@dxos/app-framework/testing';
+import { AppActivationEvents, AppCapabilities } from '@dxos/app-toolkit';
+import { AppSurface } from '@dxos/app-toolkit/ui';
+import { Collection, Filter, Ref } from '@dxos/echo';
+import { ClientPlugin, initializeIdentity } from '@dxos/plugin-client/testing';
+import { Markdown, MarkdownEvents } from '@dxos/plugin-markdown';
+import { MarkdownPlugin } from '@dxos/plugin-markdown/testing';
+import { Sketch } from '@dxos/plugin-sketch';
+import { SketchPlugin } from '@dxos/plugin-sketch/plugin';
+import { SketchBuilder } from '@dxos/plugin-sketch/testing';
+import { SpacePlugin } from '@dxos/plugin-space/testing';
+import { StorybookPlugin, corePlugins } from '@dxos/plugin-testing';
+import { random } from '@dxos/random';
+import { useClient } from '@dxos/react-client';
+import { useQuery } from '@dxos/react-client/echo';
+import { Loading, withLayout } from '@dxos/react-ui/testing';
+
+import { translations } from '#translations';
+
+import { StackArticle, type StackArticleProps } from './StackArticle';
+
+// A minimal sketch (tldraw `tldraw.com/2`) snapshot, used as a test image.
+const SKETCH_CONTENT = new SketchBuilder()
+  .rectangle({ id: 'rect', x: 0, y: 0, text: 'DXOS', color: 'blue', fill: 'solid', size: 'l' })
+  .ellipse({ id: 'echo', x: 320, y: 0, text: 'ECHO', color: 'green' })
+  .arrow({ from: 'rect', to: 'echo' })
+  .build();
+
+const DefaultStory = (args: StackArticleProps) => {
+  const client = useClient();
+  const [space] = client.spaces.get();
+  const [collection] = useQuery(space?.db, Filter.type(Collection.Collection));
+  if (!collection) {
+    return <Loading />;
+  }
+
+  return <StackArticle {...args} subject={collection} attendableId='test' />;
+};
+
+const meta: Meta<typeof StackArticle> = {
+  title: 'plugins/plugin-stack/containers/StackArticle',
+  component: StackArticle,
+  render: DefaultStory,
+  decorators: [
+    withLayout({ layout: 'fullscreen' }),
+    withPluginManager({
+      setupEvents: [AppActivationEvents.SetupSettings, MarkdownEvents.SetupExtensions],
+      capabilities: [Capability.contributes(AppCapabilities.Translations, translations)],
+      plugins: [
+        ...corePlugins(),
+        ClientPlugin({
+          types: [Collection.Collection, Markdown.Document, Sketch.Sketch, Sketch.Canvas],
+          onClientInitialized: ({ client }) =>
+            Effect.gen(function* () {
+              const { personalSpace: space } = yield* initializeIdentity(client);
+
+              const documents = Array.from({ length: 5 }).map(() =>
+                Ref.make(
+                  space.db.add(
+                    Markdown.make({
+                      name: random.lorem.sentence(5),
+                      content:
+                        [
+                          `# ${random.lorem.sentence(5)}`,
+                          random.lorem.paragraph(),
+                          random.lorem.paragraph(),
+                          random.lorem.paragraph(),
+                        ].join('\n\n') + '\n',
+                    }),
+                  ),
+                ),
+              );
+
+              const sketches = [
+                Ref.make(
+                  space.db.add(
+                    Sketch.make({
+                      name: random.lorem.sentence(2),
+                      canvas: {
+                        content: SKETCH_CONTENT,
+                      },
+                    }),
+                  ),
+                ),
+              ];
+
+              const insertAt = 1;
+              space.db.add(
+                Collection.make({
+                  name: random.lorem.sentence(5),
+                  objects: [...documents.slice(0, insertAt), ...sketches, ...documents.slice(insertAt + 1)],
+                }),
+              );
+            }),
+        }),
+        MarkdownPlugin(),
+        SketchPlugin(),
+        SpacePlugin({}),
+        StorybookPlugin({}),
+      ],
+    }),
+  ],
+};
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    role: AppSurface.Article.role,
+  },
+};