@dxos/plugin-stack 0.9.1-main.c7dcc2e112 → 0.10.0

package/dx.config.ts

@@ -8,12 +8,10 @@ import { trim } from '@dxos/util';
 export default Config2.make({
   plugin: {
     key: 'org.dxos.plugin.stack',
-    // TODO(wittjosiah): Prevents "stacks" language from being exposed to users in settings panel.
-    //   Conside renaming this to the collection plugin and trying to factor more collections logic from the space plugin.
-    name: 'Collections',
+    name: 'Stacks',
     author: 'DXOS',
     description: trim`
-      StackPlugin renders any Collection object as a vertically scrollable stack of collapsible sections in the
+      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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/plugin-stack",
-  "version": "0.9.1-main.c7dcc2e112",
+  "version": "0.10.0",
   "description": "DXOS Surface plugin for Stack entities",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -77,41 +77,46 @@
   "dependencies": {
     "@effect-atom/atom-react": "^0.5.0",
     "@radix-ui/react-collapsible": "1.1.3",
-    "effect": "3.21.3",
-    "@dxos/app-framework": "0.9.1-main.c7dcc2e112",
-    "@dxos/app-toolkit": "0.9.1-main.c7dcc2e112",
-    "@dxos/invariant": "0.9.1-main.c7dcc2e112",
-    "@dxos/operation": "0.9.1-main.c7dcc2e112",
-    "@dxos/keys": "0.9.1-main.c7dcc2e112",
-    "@dxos/plugin-graph": "0.9.1-main.c7dcc2e112",
-    "@dxos/plugin-deck": "0.9.1-main.c7dcc2e112",
-    "@dxos/echo": "0.9.1-main.c7dcc2e112",
-    "@dxos/react-ui-attention": "0.9.1-main.c7dcc2e112",
-    "@dxos/plugin-space": "0.9.1-main.c7dcc2e112",
-    "@dxos/react-ui-stack": "0.9.1-main.c7dcc2e112",
-    "@dxos/react-ui-form": "0.9.1-main.c7dcc2e112",
-    "@dxos/plugin-client": "0.9.1-main.c7dcc2e112",
-    "@dxos/util": "0.9.1-main.c7dcc2e112"
+    "effect": "3.21.4",
+    "@dxos/app-framework": "0.10.0",
+    "@dxos/app-toolkit": "0.10.0",
+    "@dxos/echo": "0.10.0",
+    "@dxos/invariant": "0.10.0",
+    "@dxos/keys": "0.10.0",
+    "@dxos/operation": "0.10.0",
+    "@dxos/plugin-client": "0.10.0",
+    "@dxos/plugin-graph": "0.10.0",
+    "@dxos/plugin-deck": "0.10.0",
+    "@dxos/plugin-space": "0.10.0",
+    "@dxos/react-ui-attention": "0.10.0",
+    "@dxos/react-ui-menu": "0.10.0",
+    "@dxos/react-ui-form": "0.10.0",
+    "@dxos/util": "0.10.0",
+    "@dxos/react-ui-mosaic": "0.10.0"
   },
   "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/storybook-utils": "0.9.1-main.c7dcc2e112",
-    "@dxos/react-ui": "0.9.1-main.c7dcc2e112",
-    "@dxos/ui-theme": "0.9.1-main.c7dcc2e112",
-    "@dxos/plugin-testing": "0.9.1-main.c7dcc2e112"
+    "@dxos/plugin-markdown": "0.10.0",
+    "@dxos/plugin-testing": "0.10.0",
+    "@dxos/plugin-sketch": "0.10.0",
+    "@dxos/react-client": "0.10.0",
+    "@dxos/random": "0.10.0",
+    "@dxos/storybook-utils": "0.10.0",
+    "@dxos/ui-theme": "0.10.0",
+    "@dxos/react-ui": "0.10.0"
   },
   "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.1-main.c7dcc2e112",
-    "@dxos/ui-theme": "0.9.1-main.c7dcc2e112"
+    "effect": "3.21.4",
+    "react": "~19.2.7",
+    "react-dom": "~19.2.7",
+    "@dxos/react-ui": "0.10.0",
+    "@dxos/ui-theme": "0.10.0"
   },
   "publishConfig": {
     "access": "public"

package/src/StackPlugin.ts

@@ -8,13 +8,13 @@ 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({

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,
+  },
+};