@dxos/plugin-deck 0.8.4-main.b97322e → 0.8.4-main.bcb3aa67d6

package/src/{components/DeckLayout → containers/Deck}/StatusBar.tsx

@@ -4,7 +4,7 @@
 
 import React from 'react';
 
-import { Surface } from '@dxos/app-framework';
+import { Surface } from '@dxos/app-framework/ui';
 import { useLandmarkMover } from '@dxos/react-ui';
 
 export const StatusBar = ({ showHints }: { showHints?: boolean }) => {
@@ -12,11 +12,11 @@ export const StatusBar = ({ showHints }: { showHints?: boolean }) => {
   return (
     <div
       role='contentinfo'
-      className='fixed block-end-0 inset-inline-0 bs-[--statusbar-size] border-bs border-separator z-[2] flex text-description'
+      className='fixed bottom-0 inset-x-0 h-(--dx-statusbar-size) border-y border-separator z-[2] flex text-description'
       {...mover}
     >
-      {showHints && <Surface role='hints' limit={1} />}
-      <Surface role='status-bar' limit={1} />
+      {showHints && <Surface.Surface role='hints' limit={1} />}
+      <Surface.Surface role='status-bar' limit={1} />
     </div>
   );
 };

package/src/containers/Deck/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './Deck';

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

@@ -4,11 +4,12 @@
 
 import React from 'react';
 
-import { Surface, useAppGraph } from '@dxos/app-framework';
+import { Surface } from '@dxos/app-framework/ui';
+import { useAppGraph } from '@dxos/app-toolkit/ui';
 import { useNode } from '@dxos/plugin-graph';
 import { useAttended } from '@dxos/react-ui-attention';
 
-import { useNodeActionExpander } from '../../hooks';
+import { useNodeActionExpander } from '#hooks';
 
 // TODO(burdon): Factor out to effect in plugin set document title.
 export const ActiveNode = () => {
@@ -21,7 +22,7 @@ export const ActiveNode = () => {
     <div role='none' className='sr-only'>
       {/* TODO(wittjosiah): Weird that this is a surface, feel like it's not really render logic.
             Probably this lives in React-land currently in order to access translations? */}
-      <Surface role='document-title' data={{ subject: activeNode }} limit={1} />
+      <Surface.Surface role='document-title' data={{ subject: activeNode }} limit={1} />
     </div>
   );
 };

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

@@ -0,0 +1,174 @@
+//
+// 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 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, AppPlugin, LayoutOperation } from '@dxos/app-toolkit';
+import { Node, GraphBuilder, NodeMatcher } from '@dxos/plugin-graph';
+import { corePlugins } from '@dxos/plugin-testing';
+import { useAsyncEffect } from '@dxos/react-hooks';
+import { Json } from '@dxos/react-ui-syntax-highlighter';
+import { Loading, withLayout } from '@dxos/react-ui/testing';
+
+import { meta as pluginMeta } from '#meta';
+import { DeckLayoutStoryNavigation } from '#testing';
+
+import { translations } from '../../translations';
+
+import { DeckLayout } from './DeckLayout';
+
+import { DeckState, OperationHandler } from '#capabilities';
+import { DeckCapabilities, type Settings } from '#types';
+
+/**
+ * Same as {@link DeckSettings} but `enableDeck: true` so `DeckContent` does not force solo
+ * whenever layout is multi (see `DeckContent` when `!settings.enableDeck`).
+ */
+const storyDeckSettings = Capability.makeModule(() =>
+  Effect.sync(() => {
+    const settingsAtom = Atom.make<Settings.Settings>({
+      showHints: false,
+      enableDeck: true,
+      enableStatusbar: false,
+      enableNativeRedirect: false,
+      newPlankPositioning: 'start',
+      overscroll: 'none',
+      encapsulatedPlanks: false,
+    }).pipe(Atom.keepAlive);
+
+    return [Capability.contributes(DeckCapabilities.Settings, settingsAtom)];
+  }),
+);
+
+const STORY_ITEM_SEGMENTS = ['story-a', 'story-b', 'story-c', 'story-d', 'story-e'];
+const STORY_ITEMS = STORY_ITEM_SEGMENTS.map((id) => `${Node.RootId}/${id}`);
+
+const TestPlugin = Plugin.define(pluginMeta).pipe(
+  Plugin.addModule({
+    id: 'story-deck-settings',
+    activatesOn: AppActivationEvents.SetupSettings,
+    activate: storyDeckSettings,
+  }),
+  Plugin.addModule({
+    id: Capability.getModuleTag(DeckState),
+    activatesOn: AppActivationEvents.AppGraphReady,
+    activate: () => DeckState(),
+  }),
+  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 }) => <DeckLayoutStoryNavigation current={data.current} ref={ref} />,
+          }),
+          Surface.create({
+            id: 'story-article',
+            role: 'article',
+            component: ({ data }) => {
+              const subject = (data as any)?.subject;
+              if (!subject) {
+                return <Loading />;
+              }
+              return (
+                <Json.Root data={subject}>
+                  <Json.Content />
+                </Json.Root>
+              );
+            },
+          }),
+        ]),
+      ),
+  }),
+  AppPlugin.addAppGraphModule({
+    id: 'story-graph',
+    activate: Effect.fnUntraced(function* () {
+      const extensions = yield* GraphBuilder.createExtension({
+        id: 'story-items',
+        match: NodeMatcher.whenRoot,
+        connector: () =>
+          Effect.succeed(
+            STORY_ITEM_SEGMENTS.map((id, index) => ({
+              id,
+              type: 'story-item',
+              data: { id, title: `Story Item ${index + 1}` },
+              properties: {
+                label: `Item ${index + 1}`,
+                icon: 'ph--file--regular',
+              },
+            })),
+          ),
+      });
+      return Capability.contributes(AppCapabilities.AppGraphBuilder, extensions);
+    }),
+  }),
+  Plugin.make,
+);
+
+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 = {};
+
+const SoloStory = () => {
+  const { invokePromise } = useOperationInvoker();
+
+  useAsyncEffect(async () => {
+    await invokePromise(LayoutOperation.Open, { subject: [STORY_ITEMS[0]], navigation: 'immediate' });
+    await invokePromise(LayoutOperation.SetLayoutMode, { mode: 'solo', subject: STORY_ITEMS[0] });
+  });
+
+  return <DeckLayout />;
+};
+
+export const Solo: Story = {
+  render: () => <SoloStory />,
+};
+
+const MultiStory = () => {
+  const { invokePromise } = useOperationInvoker();
+
+  useAsyncEffect(async () => {
+    await invokePromise(LayoutOperation.Open, { subject: [STORY_ITEMS[0]], navigation: 'immediate' });
+    await invokePromise(LayoutOperation.SetLayoutMode, { mode: 'multi' });
+    await invokePromise(LayoutOperation.Set, {
+      subject: [STORY_ITEMS[0], STORY_ITEMS[1], STORY_ITEMS[2]],
+    });
+  });
+
+  return <DeckLayout />;
+};
+
+export const Multi: Story = {
+  render: () => <MultiStory />,
+};

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

@@ -2,33 +2,42 @@
 // Copyright 2025 DXOS.org
 //
 
-import React from 'react';
+import React, { useCallback } from 'react';
 
-import { Surface, useCapability } from '@dxos/app-framework';
+import { Surface } from '@dxos/app-framework/ui';
 import { AlertDialog, Dialog as NaturalDialog } from '@dxos/react-ui';
 
-import { DeckCapabilities } from '../../capabilities';
-import { PlankContentError } from '../Plank';
+import { useDeckState } from '#hooks';
+import { PlankErrorFallback } from '../Plank';
 
 export const Dialog = () => {
-  const context = useCapability(DeckCapabilities.MutableDeckState);
-  const { dialogOpen, dialogType, dialogBlockAlign, dialogOverlayClasses, dialogOverlayStyle, dialogContent } = context;
+  const { state, updateEphemeral } = useDeckState();
+  const { dialogOpen, dialogType, dialogBlockAlign, dialogOverlayClasses, dialogOverlayStyle, dialogContent } = state;
   const Root = dialogType === 'alert' ? AlertDialog.Root : NaturalDialog.Root;
   const Overlay = dialogType === 'alert' ? AlertDialog.Overlay : NaturalDialog.Overlay;
 
+  const handleOpenChange = useCallback(
+    (nextOpen: boolean) => {
+      updateEphemeral((s) => ({ ...s, dialogOpen: nextOpen }));
+    },
+    [updateEphemeral],
+  );
+
   // TODO(thure): End block alignment affecting `modal` and whether the surface renders in an overlay is tailored to the needs of the ambient chat dialog. As the feature matures, consider separating concerns.
   return (
-    <Root
-      modal={dialogBlockAlign !== 'end'}
-      open={dialogOpen}
-      onOpenChange={(nextOpen) => (context.dialogOpen = nextOpen)}
-    >
+    <Root modal={dialogBlockAlign !== 'end'} open={dialogOpen} onOpenChange={handleOpenChange}>
       {dialogBlockAlign === 'end' ? (
         // TODO(burdon): Placeholder creates a suspense boundary; replace with defaults.
-        <Surface role='dialog' data={dialogContent} limit={1} fallback={PlankContentError} placeholder={<div />} />
+        <Surface.Surface
+          role='dialog'
+          data={dialogContent}
+          limit={1}
+          fallback={PlankErrorFallback}
+          placeholder={<div />}
+        />
       ) : (
         <Overlay blockAlign={dialogBlockAlign} classNames={dialogOverlayClasses} style={dialogOverlayStyle}>
-          <Surface role='dialog' data={dialogContent} limit={1} fallback={PlankContentError} />
+          <Surface.Surface role='dialog' data={dialogContent} limit={1} fallback={PlankErrorFallback} />
         </Overlay>
       )}
     </Root>

package/src/containers/DeckLayout/Fallback.tsx

@@ -0,0 +1,24 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import React from 'react';
+
+import { useTranslation } from '@dxos/react-ui';
+
+import { meta } from '#meta';
+
+const Fallback = () => {
+  const { t } = useTranslation(meta.id);
+
+  return (
+    <div role='none' 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')}
+      </p>
+    </div>
+  );
+};

package/src/containers/DeckLayout/Popover.tsx

@@ -0,0 +1,156 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { createContext } from '@radix-ui/react-context';
+import * as Function from 'effect/Function';
+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 { Annotation, Obj } from '@dxos/echo';
+import {
+  Card,
+  Popover,
+  type PopoverContentInteractOutsideEvent,
+  toLocalizedString,
+  Toolbar,
+  useTranslation,
+} from '@dxos/react-ui';
+import { Menu } from '@dxos/react-ui-menu';
+
+import { useDeckState } from '#hooks';
+import { meta } from '#meta';
+
+const DEBOUNCE_DELAY = 40;
+
+type DeckPopoverContextValue = {
+  setOpen: (open: boolean) => void;
+};
+
+const [DeckPopoverProvider, useDeckPopoverContext] = createContext<DeckPopoverContextValue>('DeckPopover');
+
+export type PopoverRootProps = PropsWithChildren;
+
+export const PopoverRoot = ({ children }: PopoverRootProps) => {
+  const { state } = useDeckState();
+  const virtualRef = useRef<HTMLButtonElement | null>(null);
+  const [virtualIter, setVirtualIter] = useState(0);
+  const [open, setOpen] = useState(false);
+  const debounceRef = useRef<NodeJS.Timeout | null>(null);
+
+  // TODO(thure): This is a workaround for the race condition between displaying a Popover and either rendering
+  //  the anchor further down the tree or measuring the virtual trigger's client rect.
+  useEffect(() => {
+    setOpen(false);
+    if (state.popoverOpen) {
+      if (debounceRef.current) {
+        clearTimeout(debounceRef.current);
+      }
+      if (state.popoverAnchor && virtualRef.current !== state.popoverAnchor) {
+        virtualRef.current = state.popoverAnchor ?? null;
+        setVirtualIter((iter) => iter + 1);
+      }
+      debounceRef.current = setTimeout(() => setOpen(true), DEBOUNCE_DELAY);
+    }
+  }, [state.popoverOpen, state.popoverAnchorId, state.popoverAnchor, state.popoverContent]);
+
+  return (
+    <DeckPopoverProvider setOpen={setOpen}>
+      <Popover.Root modal={false} open={open}>
+        {state.popoverAnchor && <Popover.VirtualTrigger key={virtualIter} virtualRef={virtualRef} />}
+        {children}
+      </Popover.Root>
+    </DeckPopoverProvider>
+  );
+};
+
+export const PopoverContent = () => {
+  const { t } = useTranslation(meta.id);
+  const { state, updateEphemeral } = useDeckState();
+  const { setOpen } = useDeckPopoverContext('PopoverContent');
+  const popoverSubject = state.popoverContent?.subject;
+  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),
+        Option.fromNullable,
+        Option.flatMap(Annotation.IconAnnotation.get),
+        Option.map(({ icon }) => icon),
+        Option.getOrElse(() => 'ph--placeholder--regular'),
+      )
+    : undefined;
+
+  const handleClose = useCallback(() => {
+    setOpen(false);
+    updateEphemeral((state) => ({
+      ...state,
+      popoverOpen: false,
+      popoverAnchor: undefined,
+      popoverAnchorId: undefined,
+      popoverSide: undefined,
+    }));
+  }, [updateEphemeral]);
+
+  const handleInteractOutside = useCallback(
+    (event: KeyboardEvent | PopoverContentInteractOutsideEvent) => {
+      if (
+        // TODO(thure): CodeMirror should not focus itself when it updates.
+        event.type === 'dismissableLayer.focusOutside' &&
+        (event.currentTarget as HTMLElement | undefined)?.classList.contains('cm-content')
+      ) {
+        event.preventDefault();
+      } else {
+        handleClose();
+      }
+    },
+    [handleClose],
+  );
+
+  return (
+    <Popover.Portal>
+      <Popover.Content
+        side={state.popoverSide}
+        sticky='always'
+        hideWhenDetached
+        onInteractOutside={handleInteractOutside}
+        onEscapeKeyDown={handleInteractOutside}
+      >
+        <Popover.Viewport>
+          {/* Base popover */}
+          {state.popoverKind === 'base' && <Surface.Surface role='popover' data={state.popoverContent} limit={1} />}
+
+          {/* Card popover */}
+          {state.popoverKind === 'card' && (
+            <Menu.Root>
+              <Card.Root border={false} classNames='dx-card-popover'>
+                <Card.Toolbar>
+                  <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} />
+              </Card.Root>
+            </Menu.Root>
+          )}
+        </Popover.Viewport>
+        <Popover.Arrow />
+      </Popover.Content>
+    </Popover.Portal>
+  );
+};

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

@@ -4,7 +4,7 @@
 
 import React from 'react';
 
-import { type LayoutAction } from '@dxos/app-framework';
+import { type LayoutOperation } from '@dxos/app-toolkit';
 import {
   Button,
   Icon,
@@ -14,7 +14,7 @@ import {
   useTranslation,
 } from '@dxos/react-ui';
 
-import { DECK_PLUGIN } from '../../meta';
+import { meta } from '#meta';
 
 // TODO(wittjosiah): Render remaining duration as a progress bar within the toast.
 export const Toast = ({
@@ -28,14 +28,14 @@ export const Toast = ({
   closeLabel,
   onAction,
   onOpenChange,
-}: LayoutAction.Toast & Pick<ToastRootProps, 'onOpenChange'>) => {
-  const { t } = useTranslation(DECK_PLUGIN);
+}: LayoutOperation.Toast & Pick<ToastRootProps, 'onOpenChange'>) => {
+  const { t } = useTranslation(meta.id);
 
   return (
     <NaturalToast.Root data-testid={id} defaultOpen duration={duration} onOpenChange={onOpenChange}>
       <NaturalToast.Body>
         <NaturalToast.Title classNames='items-center'>
-          {icon && <Icon icon={icon} size={5} classNames='inline mr-1' />}
+          {icon && <Icon icon={icon} classNames='inline mr-1' />}
           {title && <span>{toLocalizedString(title, t)}</span>}
         </NaturalToast.Title>
         {description && (
@@ -59,3 +59,28 @@ export const Toast = ({
     </NaturalToast.Root>
   );
 };
+
+export type ToasterProps = {
+  toasts?: LayoutOperation.Toast[];
+  onDismissToast?: (id: string) => void;
+};
+
+export const Toaster = ({ toasts, onDismissToast }: ToasterProps) => {
+  return (
+    <>
+      {toasts?.map((toast) => (
+        <Toast
+          {...toast}
+          key={toast.id}
+          onOpenChange={(open: boolean) => {
+            if (!open) {
+              onDismissToast?.(toast.id);
+            }
+
+            return open;
+          }}
+        />
+      ))}
+    </>
+  );
+};

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;