@dxos/plugin-deck 0.8.4-main.8360d9e660 → 0.8.4-main.8baae0fced

package/src/containers/DeckLayout/DeckLayout.stories.tsx

@@ -0,0 +1,395 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Atom } from '@effect-atom/atom-react';
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import * as Effect from 'effect/Effect';
+import React, { forwardRef, useMemo } from 'react';
+
+import { Capabilities, Capability, Plugin } from '@dxos/app-framework';
+import { withPluginManager } from '@dxos/app-framework/testing';
+import { Surface, useOperationInvoker } from '@dxos/app-framework/ui';
+import { AppActivationEvents, AppCapabilities, AppNode, AppPlugin, LayoutOperation } from '@dxos/app-toolkit';
+import { AppSurface, useAppGraph, useLayout } from '@dxos/app-toolkit/ui';
+import { invariant } from '@dxos/invariant';
+import { GraphBuilder, Node, NodeMatcher, useConnections } from '@dxos/plugin-graph';
+import { corePlugins } from '@dxos/plugin-testing';
+import { random } from '@dxos/random';
+import { useAsyncEffect } from '@dxos/react-hooks';
+import { Icon, List, ListItem, Panel } from '@dxos/react-ui';
+import { linkedSegment } from '@dxos/react-ui-attention';
+import { Syntax } from '@dxos/react-ui-syntax-highlighter';
+import { Loading, withLayout } from '@dxos/react-ui/testing';
+
+import { OperationHandler } from '#capabilities';
+import { meta as pluginMeta } from '#meta';
+import { translations } from '#translations';
+import {
+  DeckCapabilities,
+  type EphemeralDeckState,
+  type Settings,
+  type StoredDeckState,
+  defaultDeck,
+  getMode,
+  PLANK_COMPANION_TYPE,
+} from '#types';
+
+import { DeckLayout } from './DeckLayout';
+
+random.seed(1234);
+
+// TODO(burdon): Show/hide companions.
+// TODO(burdon): Companion width.
+
+// TODO(burdon): Factor out.
+const storyDeckSettings = Capability.makeModule(() =>
+  Effect.sync(() => {
+    const settingsAtom = Atom.make<Settings.Settings>({
+      showHints: false,
+      enableDeck: true,
+      enableNativeRedirect: false,
+      encapsulatedPlanks: false,
+    }).pipe(Atom.keepAlive);
+
+    return [Capability.contributes(DeckCapabilities.Settings, settingsAtom)];
+  }),
+);
+
+// TODO(burdon): Factor out.
+const storyDeckState = Capability.makeModule(() =>
+  Effect.sync(() => {
+    const defaultStoredDeckState: StoredDeckState = {
+      sidebarState: 'expanded',
+      complementarySidebarState: 'collapsed',
+      complementarySidebarPanel: undefined,
+      activeDeck: 'default',
+      previousDeck: 'default',
+      previousMode: {},
+      decks: {
+        default: { ...defaultDeck },
+      },
+    };
+
+    const stateAtom = Atom.make<StoredDeckState>({ ...defaultStoredDeckState }).pipe(Atom.keepAlive);
+
+    const defaultEphemeralDeckState: EphemeralDeckState = {
+      dialogContent: null,
+      dialogOpen: false,
+      dialogBlockAlign: undefined,
+      dialogType: undefined,
+      popoverContent: null,
+      popoverAnchor: undefined,
+      popoverAnchorId: undefined,
+      popoverOpen: false,
+      toasts: [],
+      currentUndoId: undefined,
+      scrollIntoView: undefined,
+    };
+
+    const ephemeralAtom = Atom.make<EphemeralDeckState>({ ...defaultEphemeralDeckState }).pipe(Atom.keepAlive);
+
+    const layoutAtom = Atom.make((get) => {
+      const state = get(stateAtom);
+      const ephemeral = get(ephemeralAtom);
+      const deck = state.decks[state.activeDeck];
+      invariant(deck, `Deck not found: ${state.activeDeck}`);
+      return {
+        mode: getMode(deck),
+        dialogOpen: ephemeral.dialogOpen,
+        sidebarOpen: state.sidebarState === 'expanded',
+        complementarySidebarOpen: state.complementarySidebarState === 'expanded',
+        workspace: state.activeDeck,
+        active: deck.solo ? [deck.solo] : deck.active,
+        inactive: deck.inactive,
+        scrollIntoView: ephemeral.scrollIntoView,
+      } satisfies AppCapabilities.Layout;
+    }).pipe(Atom.keepAlive);
+
+    return [
+      Capability.contributes(DeckCapabilities.State, stateAtom),
+      Capability.contributes(DeckCapabilities.EphemeralState, ephemeralAtom),
+      Capability.contributes(AppCapabilities.Layout, layoutAtom),
+    ];
+  }),
+);
+
+type Item = { id: string; title: string; children?: Item[] };
+
+/**
+ * @param depth - Current depth; children are only added when `depth < maxDepth`.
+ * @param maxDepth - Defaults to {@link STORY_ITEM_MAX_DEPTH}.
+ */
+const createItem = (depth = 0, maxDepth = 3): Item => ({
+  id: random.string.uuid(),
+  title: random.lorem.words({ min: 2, max: 4 }),
+  children:
+    depth < maxDepth
+      ? Array.from({ length: random.number.int({ min: 1, max: 8 }) }, () => createItem(depth + 1, maxDepth))
+      : undefined,
+});
+
+const STORY_ITEMS = Array.from({ length: 5 }, () => createItem());
+
+/**
+ * Maps a nested {@link Item} tree to graph nodes so `Graph.getConnections` / `useConnections` see children.
+ */
+const toStoryItemNode = (item: Item, index: number, depth: number): Node.NodeArg<Item> =>
+  Node.make({
+    id: item.id,
+    type: 'story-item',
+    data: item,
+    properties: {
+      label: depth === 0 ? `Item ${index + 1}` : item.title,
+      icon: depth === 0 ? 'ph--file--regular' : 'ph--file-text--regular',
+    },
+    nodes: (item.children ?? []).map((child, childIndex) => toStoryItemNode(child, childIndex, depth + 1)),
+  });
+
+const TestPlugin = Plugin.define(pluginMeta).pipe(
+  Plugin.addModule({
+    id: 'story-deck-settings',
+    activatesOn: AppActivationEvents.SetupSettings,
+    activate: storyDeckSettings,
+  }),
+  Plugin.addModule({
+    id: 'story-deck-state',
+    activatesOn: AppActivationEvents.AppGraphReady,
+    activate: storyDeckState,
+  }),
+  AppPlugin.addOperationHandlerModule({
+    activate: OperationHandler,
+  }),
+  AppPlugin.addSurfaceModule({
+    id: 'story-surfaces',
+    activate: () =>
+      Effect.succeed(
+        Capability.contributes(Capabilities.ReactSurface, [
+          Surface.create({
+            id: 'story-navigation',
+            role: 'navigation',
+            filter: (data): data is { current: string } => typeof (data as any).current === 'string',
+            component: ({ data, ref }) => <NavContainer current={data.current} ref={ref} />,
+          }),
+          Surface.create({
+            id: 'story-article',
+            role: 'article',
+            filter: (data): data is Record<string, unknown> =>
+              typeof data === 'object' && data !== null && (data as { companionTo?: unknown }).companionTo == null,
+            component: ({ data }) => {
+              const subject = (data as any)?.subject;
+              const attendableId = (data as any)?.attendableId as string | undefined;
+              if (subject == null) {
+                return <Loading />;
+              }
+
+              return (
+                <Panel.Root>
+                  <Panel.Content className='grid grid-rows-[min-content_1fr]'>
+                    {attendableId && <ItemComponent id={attendableId} />}
+                    <Syntax.Root data={subject}>
+                      <Syntax.Content>
+                        <Syntax.Filter />
+                        <Syntax.Viewport>
+                          <Syntax.Code />
+                        </Syntax.Viewport>
+                      </Syntax.Content>
+                    </Syntax.Root>
+                  </Panel.Content>
+                </Panel.Root>
+              );
+            },
+          }),
+          Surface.create({
+            id: 'story-article-companion',
+            role: 'article',
+            filter: (data): data is AppSurface.ArticleData<unknown, {}, unknown> =>
+              typeof data === 'object' && data !== null && (data as { companionTo?: unknown }).companionTo != null,
+            component: ({ data: { subject, companionTo, properties, variant } }) => {
+              if (companionTo == null) {
+                return <Loading />;
+              }
+
+              return (
+                <Syntax.Root
+                  data={{
+                    primaryItem: companionTo,
+                    companion: { data: subject, properties, variant },
+                  }}
+                >
+                  <Syntax.Content>
+                    <Syntax.Viewport>
+                      <Syntax.Code />
+                    </Syntax.Viewport>
+                  </Syntax.Content>
+                </Syntax.Root>
+              );
+            },
+          }),
+        ]),
+      ),
+  }),
+  AppPlugin.addAppGraphModule({
+    id: 'story-graph',
+    activate: Effect.fnUntraced(function* () {
+      const extensions = yield* Effect.all([
+        GraphBuilder.createExtension({
+          id: 'story-items',
+          match: NodeMatcher.whenRoot,
+          connector: () => Effect.succeed(STORY_ITEMS.map((item, index) => toStoryItemNode(item, index, 0))),
+        }),
+        GraphBuilder.createExtension({
+          id: 'story-item-companions',
+          match: NodeMatcher.whenNodeType('story-item'),
+          connector: (node) =>
+            Effect.succeed([
+              AppNode.makeCompanion({
+                id: linkedSegment('alpha'),
+                label: 'Companion Alpha',
+                icon: 'ph--sidebar--regular',
+                data: { variant: 'alpha', parentId: node.id },
+                position: 'first',
+              }),
+              AppNode.makeCompanion({
+                id: linkedSegment('beta'),
+                label: 'Companion Beta',
+                icon: 'ph--chat-circle--regular',
+                data: { variant: 'beta', parentId: node.id },
+              }),
+            ]),
+        }),
+      ]);
+      return Capability.contributes(AppCapabilities.AppGraphBuilder, extensions.flat());
+    }),
+  }),
+  Plugin.make,
+);
+
+type NavContainerProps = {
+  current?: string;
+};
+
+const NavContainer = forwardRef<HTMLDivElement, NavContainerProps>((_props, forwardedRef) => {
+  const { graph } = useAppGraph();
+  const layout = useLayout();
+  const { invokePromise } = useOperationInvoker();
+
+  const items = useConnections(graph, Node.RootId, 'child');
+  const activeSet = useMemo(() => new Set(layout.active), [layout.active]);
+
+  return (
+    <div className='dx-container overflow-y-auto p-2' ref={forwardedRef}>
+      <List>
+        {items.map((node) => (
+          <ListItem.Root
+            key={node.id}
+            classNames={activeSet.has(node.id) ? 'bg-current-surface' : undefined}
+            onClick={() => void invokePromise(LayoutOperation.Set, { subject: [node.id] })}
+          >
+            {node.properties.icon && (
+              <ListItem.Endcap>
+                <Icon icon={node.properties.icon} />
+              </ListItem.Endcap>
+            )}
+            <ListItem.Heading classNames='cursor-pointer'>
+              {typeof node.properties.label === 'string' ? node.properties.label : node.id}
+            </ListItem.Heading>
+          </ListItem.Root>
+        ))}
+      </List>
+    </div>
+  );
+});
+
+type ItemComponentProps = {
+  id: string;
+};
+
+const ItemComponent = ({ id }: ItemComponentProps) => {
+  const { graph } = useAppGraph();
+  const { invokePromise } = useOperationInvoker();
+  const connections = useConnections(graph, id, 'child');
+  const items = useMemo(
+    () => connections.filter((node) => !Node.isActionLike(node) && node.type !== PLANK_COMPANION_TYPE),
+    [connections],
+  );
+
+  return (
+    <List>
+      {items.map((node) => {
+        const open = () =>
+          void invokePromise(LayoutOperation.Open, { subject: [node.id], pivotId: id, navigation: 'immediate' });
+        return (
+          <ListItem.Root
+            key={node.id}
+            classNames='dx-hover cursor-pointer'
+            role='button'
+            tabIndex={0}
+            onClick={open}
+            onKeyDown={(event) => {
+              if (event.key === 'Enter' || event.key === ' ') {
+                event.preventDefault();
+                open();
+              }
+            }}
+          >
+            {node.properties.icon && (
+              <ListItem.Endcap>
+                <Icon icon={node.properties.icon} size={4} />
+              </ListItem.Endcap>
+            )}
+            <ListItem.Heading classNames='truncate'>
+              {typeof node.properties.label === 'string' ? node.properties.label : node.id}
+            </ListItem.Heading>
+          </ListItem.Root>
+        );
+      })}
+    </List>
+  );
+};
+
+const meta = {
+  title: 'plugins/plugin-deck/containers/DeckLayout',
+  component: DeckLayout,
+  decorators: [
+    withLayout({ layout: 'fullscreen' }),
+    withPluginManager({
+      plugins: [...corePlugins(), TestPlugin()],
+      setupEvents: [AppActivationEvents.SetupSettings],
+    }),
+  ],
+  parameters: {
+    layout: 'fullscreen',
+    translations,
+  },
+} satisfies Meta<typeof DeckLayout>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};
+
+export const Solo: Story = {
+  render: () => {
+    const { invokePromise } = useOperationInvoker();
+    useAsyncEffect(async () => {
+      await invokePromise(LayoutOperation.Open, { subject: [STORY_ITEMS[0].id], navigation: 'immediate' });
+      await invokePromise(LayoutOperation.SetLayoutMode, { mode: 'solo', subject: STORY_ITEMS[0].id });
+    });
+
+    return <DeckLayout />;
+  },
+};
+
+export const Multi: Story = {
+  render: () => {
+    const { invokePromise } = useOperationInvoker();
+    useAsyncEffect(async () => {
+      await invokePromise(LayoutOperation.Open, { subject: [STORY_ITEMS[0].id], navigation: 'immediate' });
+      await invokePromise(LayoutOperation.SetLayoutMode, { mode: 'multi' });
+    });
+
+    return <DeckLayout />;
+  },
+};

package/src/containers/DeckLayout/DeckLayout.tsx

@@ -0,0 +1,62 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import React, { useCallback } from 'react';
+
+import { useAtomCapability, useOperationInvoker, usePluginManager } from '@dxos/app-framework/ui';
+import { LayoutOperation } from '@dxos/app-toolkit';
+import { Mosaic } from '@dxos/react-ui-mosaic';
+
+import { useDeckState } from '#hooks';
+import { DeckCapabilities, getMode } from '#types';
+
+import { Deck, type DeckLayoutChangeRequest } from '../Deck';
+import { ActiveNode } from './ActiveNode';
+import { Dialog } from './Dialog';
+import { PopoverContent, PopoverRoot } from './Popover';
+import { Toaster, type ToasterProps } from './Toast';
+
+export type DeckLayoutProps = Pick<ToasterProps, 'onDismissToast'>;
+
+export const DeckLayout = ({ onDismissToast }: DeckLayoutProps) => {
+  const settings = useAtomCapability(DeckCapabilities.Settings);
+  const pluginManager = usePluginManager();
+  const { invokePromise } = useOperationInvoker();
+  const { deck, state, updateState } = useDeckState();
+  const layoutMode = getMode(deck);
+  const { toasts } = state;
+
+  const handleLayoutChange = useCallback(
+    (request: DeckLayoutChangeRequest) => {
+      void invokePromise(LayoutOperation.SetLayoutMode, request);
+    },
+    [invokePromise],
+  );
+
+  return (
+    <Mosaic.Root>
+      <PopoverRoot>
+        <ActiveNode />
+        <Deck.Root
+          settings={settings}
+          pluginManager={pluginManager}
+          layoutMode={layoutMode}
+          deck={deck}
+          state={state}
+          updateState={updateState}
+          onLayoutChange={handleLayoutChange}
+        >
+          <Deck.Content>
+            <Deck.Viewport>
+              {deck.solo ? <Deck.SoloMode /> : deck.active.length === 0 ? <Deck.ContentEmpty /> : <Deck.MultiMode />}
+            </Deck.Viewport>
+          </Deck.Content>
+        </Deck.Root>
+        <PopoverContent />
+        <Dialog />
+        <Toaster toasts={toasts} onDismissToast={onDismissToast} />
+      </PopoverRoot>
+    </Mosaic.Root>
+  );
+};

package/src/{components → containers}/DeckLayout/Dialog.tsx

@@ -5,9 +5,11 @@
 import React, { useCallback } from 'react';
 
 import { Surface } from '@dxos/app-framework/ui';
+import { AppSurface } from '@dxos/app-toolkit/ui';
 import { AlertDialog, Dialog as NaturalDialog } from '@dxos/react-ui';
 
-import { useDeckState } from '../../hooks';
+import { useDeckState } from '#hooks';
+
 import { PlankErrorFallback } from '../Plank';
 
 export const Dialog = () => {
@@ -29,15 +31,20 @@ export const Dialog = () => {
       {dialogBlockAlign === 'end' ? (
         // TODO(burdon): Placeholder creates a suspense boundary; replace with defaults.
         <Surface.Surface
-          role='dialog'
-          data={dialogContent}
+          type={AppSurface.Dialog}
+          data={dialogContent ?? undefined}
           limit={1}
           fallback={PlankErrorFallback}
           placeholder={<div />}
         />
       ) : (
         <Overlay blockAlign={dialogBlockAlign} classNames={dialogOverlayClasses} style={dialogOverlayStyle}>
-          <Surface.Surface role='dialog' data={dialogContent} limit={1} fallback={PlankErrorFallback} />
+          <Surface.Surface
+            type={AppSurface.Dialog}
+            data={dialogContent ?? undefined}
+            limit={1}
+            fallback={PlankErrorFallback}
+          />
         </Overlay>
       )}
     </Root>

package/src/{components → containers}/DeckLayout/Fallback.tsx

@@ -6,18 +6,18 @@ import React from 'react';
 
 import { useTranslation } from '@dxos/react-ui';
 
-import { meta } from '../../meta';
+import { meta } from '#meta';
 
-export const Fallback = () => {
+const Fallback = () => {
   const { t } = useTranslation(meta.id);
 
   return (
-    <div role='none' className='min-h-screen w-full flex items-center justify-center p-8'>
+    <div className='min-h-screen w-full flex items-center justify-center p-8'>
       <p
         role='alert'
         className='flex items-center justify-center p-8 font-normal text-lg text-error-text border border-rose-fill rounded-md'
       >
-        {t('plugin error message')}
+        {t('plugin-error.message')}
       </p>
     </div>
   );

package/src/{components → containers}/DeckLayout/Popover.tsx

@@ -8,7 +8,7 @@ import * as Option from 'effect/Option';
 import React, { type PropsWithChildren, useCallback, useEffect, useRef, useState } from 'react';
 
 import { Surface } from '@dxos/app-framework/ui';
-import { useObjectMenuItems } from '@dxos/app-toolkit/ui';
+import { AppSurface, useObjectMenuItems } from '@dxos/app-toolkit/ui';
 import { Annotation, Obj } from '@dxos/echo';
 import {
   Card,
@@ -20,10 +20,8 @@ import {
 } from '@dxos/react-ui';
 import { Menu } from '@dxos/react-ui-menu';
 
-import { useDeckState } from '../../hooks';
-import { meta } from '../../meta';
-
-export type DeckPopoverRootProps = PropsWithChildren<{}>;
+import { useDeckState } from '#hooks';
+import { meta } from '#meta';
 
 const DEBOUNCE_DELAY = 40;
 
@@ -33,7 +31,9 @@ type DeckPopoverContextValue = {
 
 const [DeckPopoverProvider, useDeckPopoverContext] = createContext<DeckPopoverContextValue>('DeckPopover');
 
-export const PopoverRoot = ({ children }: DeckPopoverRootProps) => {
+export type PopoverRootProps = PropsWithChildren;
+
+export const PopoverRoot = ({ children }: PopoverRootProps) => {
   const { state } = useDeckState();
   const virtualRef = useRef<HTMLButtonElement | null>(null);
   const [virtualIter, setVirtualIter] = useState(0);
@@ -70,9 +70,11 @@ export const PopoverContent = () => {
   const { t } = useTranslation(meta.id);
   const { state, updateEphemeral } = useDeckState();
   const { setOpen } = useDeckPopoverContext('PopoverContent');
-  const popoverSubject = state.popoverContent?.subject;
+  const popoverSubject =
+    state.popoverContent && 'subject' in state.popoverContent ? state.popoverContent.subject : undefined;
   const isObjectPopover = Obj.isObject(popoverSubject);
   const objectMenuItems = useObjectMenuItems(popoverSubject);
+  const title = state.popoverTitle ? toLocalizedString(state.popoverTitle, t) : 'Unknown';
   const icon = isObjectPopover
     ? Function.pipe(
         Obj.getSchema(popoverSubject),
@@ -82,6 +84,7 @@ export const PopoverContent = () => {
         Option.getOrElse(() => 'ph--placeholder--regular'),
       )
     : undefined;
+
   const handleClose = useCallback(() => {
     setOpen(false);
     updateEphemeral((state) => ({
@@ -118,25 +121,35 @@ export const PopoverContent = () => {
         onEscapeKeyDown={handleInteractOutside}
       >
         <Popover.Viewport>
-          {/* TODO(burdon): Set/disable column context. */}
-          {state.popoverKind === 'base' && <Surface.Surface role='popover' data={state.popoverContent} limit={1} />}
+          {/* Base popover */}
+          {state.popoverKind === 'base' && state.popoverContent && 'component' in state.popoverContent && (
+            <Surface.Surface type={AppSurface.Popover} data={state.popoverContent} limit={1} />
+          )}
+
+          {/* Card popover */}
           {state.popoverKind === 'card' && (
             <Menu.Root>
               <Card.Root border={false} classNames='dx-card-popover'>
                 <Card.Toolbar>
-                  {icon ? <Card.Icon icon={icon} /> : <Card.IconBlock />}
-                  {state.popoverTitle ? <Card.Title>{toLocalizedString(state.popoverTitle, t)}</Card.Title> : <span />}
-                  <Menu.Trigger asChild disabled={!objectMenuItems.length}>
-                    <Toolbar.IconButton
-                      iconOnly
-                      variant='ghost'
-                      icon='ph--dots-three-vertical--regular'
-                      label='Actions'
-                    />
-                  </Menu.Trigger>
-                  <Menu.Content items={objectMenuItems} />
+                  <Card.IconBlock padding>{icon && <Card.Icon icon={icon} />}</Card.IconBlock>
+                  <Card.Title>{title}</Card.Title>
+                  {/* TODO(wittjosiah): Reconcile with Card.Menu. */}
+                  <Card.IconBlock padding>
+                    <Menu.Trigger asChild disabled={!objectMenuItems.length}>
+                      <Toolbar.IconButton
+                        variant='ghost'
+                        icon='ph--dots-three-vertical--regular'
+                        iconOnly
+                        label='Actions'
+                      />
+                    </Menu.Trigger>
+                    <Menu.Content items={objectMenuItems} />
+                  </Card.IconBlock>
                 </Card.Toolbar>
-                <Surface.Surface role='card--content' data={state.popoverContent} limit={1} />
+
+                {state.popoverContent && 'subject' in state.popoverContent && (
+                  <Surface.Surface type={AppSurface.Card} data={state.popoverContent} limit={1} />
+                )}
               </Card.Root>
             </Menu.Root>
           )}

package/src/{components → containers}/DeckLayout/Toast.tsx

@@ -14,7 +14,7 @@ import {
   useTranslation,
 } from '@dxos/react-ui';
 
-import { meta } from '../../meta';
+import { meta } from '#meta';
 
 // TODO(wittjosiah): Render remaining duration as a progress bar within the toast.
 export const Toast = ({

package/src/{components → containers}/DeckLayout/constants.ts

@@ -3,4 +3,5 @@
 //
 
 export const NAV_ID = 'NavTree';
+
 export const SURFACE_PREFIX = 'surface:';

package/src/{components → containers}/DeckLayout/index.ts

@@ -2,7 +2,8 @@
 // Copyright 2024 DXOS.org
 //
 
+import { DeckLayout } from './DeckLayout';
+
 export { NAV_ID } from './constants';
 
-export * from './Banner';
-export * from './DeckLayout';
+export default DeckLayout;