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

package/src/containers/Deck/DeckViewport.tsx

@@ -0,0 +1,397 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import React, {
+  Fragment,
+  memo,
+  type PropsWithChildren,
+  type UIEvent,
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+} from 'react';
+
+import { addEventListener } from '@dxos/async';
+import { Surface, useOperationInvoker } from '@dxos/app-framework/ui';
+import { LayoutOperation } from '@dxos/app-toolkit';
+import { useAppGraph } from '@dxos/app-toolkit/ui';
+import { invariant } from '@dxos/invariant';
+import { useNode } from '@dxos/plugin-graph';
+import { Main, type MainContentProps, useOnTransition } from '@dxos/react-ui';
+import { DEFAULT_HORIZONTAL_SIZE, Stack, StackContext } from '@dxos/react-ui-stack';
+import { mainPaddingTransitions, mx } from '@dxos/ui-theme';
+
+import { useBreakpoints, useCompanions, useDeckState, useHoistStatusbar, useSelectedCompanion } from '#hooks';
+import { DeckOperation } from '#operations';
+import { calculateOverscroll, layoutAppliesTopbar } from '../../util';
+import { Plank, PlankRootProps, type PlankComponentProps } from '../Plank';
+import {
+  ToggleComplementarySidebarButton as NativeToggleComplementarySidebarButton,
+  ToggleSidebarButton as NativeToggleSidebarButton,
+} from '../Sidebar';
+
+import { useDeckContext } from './DeckRoot';
+import { getMode } from '#types';
+
+const DECK_VIEWPORT_NAME = 'DeckViewport';
+
+//
+// DeckViewport
+//
+
+export type DeckViewportProps = PropsWithChildren;
+
+/**
+ * Deck viewport that renders the main content area and sets CSS variables for plank sizing.
+ */
+export const DeckViewport = ({ children }: DeckViewportProps) => {
+  const {
+    deck: { active, solo, plankSizing },
+    state: { sidebarState, complementarySidebarState },
+    settings,
+    layoutMode,
+  } = useDeckContext(DECK_VIEWPORT_NAME);
+
+  const breakpoint = useBreakpoints();
+  const topbar = layoutAppliesTopbar(breakpoint, layoutMode);
+  const hoistStatusbar = useHoistStatusbar(breakpoint, layoutMode);
+
+  return (
+    <Main.Content
+      bounce
+      handlesFocus
+      classNames={[
+        'grid top-[env(safe-area-inset-top)]!',
+        topbar && 'top-[calc(env(safe-area-inset-top)+var(--dx-rail-size))]!',
+        hoistStatusbar && 'lg:bottom-(--dx-statusbar-size)',
+      ]}
+      style={
+        {
+          '--main-spacing': settings?.encapsulatedPlanks ? '0.75rem' : '0',
+          '--main-sidebar-width':
+            sidebarState === 'expanded'
+              ? 'var(--dx-nav-sidebar-size)'
+              : sidebarState === 'collapsed'
+                ? 'var(--dx-l0-size)'
+                : '0',
+          '--main-complementary-width':
+            complementarySidebarState === 'expanded'
+              ? 'var(--dx-complementary-sidebar-size)'
+              : complementarySidebarState === 'collapsed'
+                ? 'var(--dx-rail-size)'
+                : '0',
+          '--main-content-first-width': `${plankSizing[active[0] ?? 'never'] ?? DEFAULT_HORIZONTAL_SIZE}rem`,
+          '--main-content-last-width': `${plankSizing[active[(active.length ?? 1) - 1] ?? 'never'] ?? DEFAULT_HORIZONTAL_SIZE}rem`,
+        } as MainContentProps['style']
+      }
+    >
+      {children}
+    </Main.Content>
+  );
+};
+
+DeckViewport.displayName = DECK_VIEWPORT_NAME;
+
+//
+// ContentEmpty
+//
+
+export const DeckContentEmpty = () => {
+  const breakpoint = useBreakpoints();
+  const { deck } = useDeckState();
+  const layoutMode = getMode(deck);
+  const topbar = layoutAppliesTopbar(breakpoint, layoutMode);
+  return (
+    <div
+      role='none'
+      className='grid place-items-center p-8 relative bg-deck-surface'
+      data-testid='layoutPlugin.firstRunMessage'
+    >
+      <Surface.Surface role='keyshortcuts' />
+      {!topbar && <ToggleSidebarButton />}
+    </div>
+  );
+};
+
+//
+// DeckSoloMode
+//
+
+/**
+ * Single-plank layout with optional companion.
+ */
+export const DeckSoloMode = () => {
+  const { deck, settings, layoutMode } = useDeckContext('DeckSoloMode');
+  const { companionOpen, companionVariant, fullscreen, solo } = deck;
+  const effectiveCompanionVariant = companionOpen ? companionVariant : undefined;
+  const breakpoint = useBreakpoints();
+  const topbar = layoutAppliesTopbar(breakpoint, layoutMode);
+  invariant(solo);
+
+  return (
+    <div role='none' className='relative overflow-hidden bg-deck-surface'>
+      <DeckSidebarToggles topbar={topbar} fullscreen={fullscreen} />
+      <StackContext.Provider
+        value={{
+          orientation: 'horizontal',
+          size: 'contain',
+          rail: true,
+        }}
+      >
+        <PlankContainer
+          id={solo}
+          part='solo'
+          layoutMode={layoutMode}
+          companionVariant={effectiveCompanionVariant}
+          settings={settings}
+        />
+      </StackContext.Provider>
+    </div>
+  );
+};
+
+//
+// DeckMultiMode
+//
+
+/**
+ * Multi-plank horizontal scrolling layout.
+ */
+export const DeckMultiMode = () => {
+  const {
+    deck: { active, companionOpen, companionVariant, fullscreen },
+    settings,
+    layoutMode,
+  } = useDeckContext('DeckMultiMode');
+  const effectiveCompanionVariant = companionOpen ? companionVariant : undefined;
+  const breakpoint = useBreakpoints();
+  const topbar = layoutAppliesTopbar(breakpoint, layoutMode);
+  const deckRef = useRef<HTMLDivElement>(null);
+
+  /** Clear scroll restoration state if the window is resized. */
+  const scrollLeftRef = useRef<number>(null);
+  useEffect(
+    () =>
+      addEventListener(window, 'resize', () => {
+        scrollLeftRef.current = null;
+      }),
+    [],
+  );
+
+  const restoreScroll = useCallback(() => {
+    if (deckRef.current && scrollLeftRef.current != null) {
+      deckRef.current.scrollLeft = scrollLeftRef.current;
+    }
+  }, []);
+
+  useOnTransition(layoutMode, (mode) => mode !== 'multi', 'multi', restoreScroll);
+
+  /** Save scroll position as the user scrolls. */
+  const handleScroll = useCallback((event: UIEvent) => {
+    if (event.currentTarget === event.target) {
+      scrollLeftRef.current = (event.target as HTMLDivElement).scrollLeft;
+    }
+  }, []);
+
+  // Create order map.
+  const { order, itemsCount } = useMemo(() => {
+    return active.reduce(
+      (acc: { order: Record<string, number>; itemsCount: number }, entryId) => {
+        acc.order[entryId] = acc.itemsCount + 1;
+        acc.itemsCount += companionOpen ? 3 : 2;
+        return acc;
+      },
+      { order: {}, itemsCount: 0 },
+    );
+  }, [active, companionOpen]);
+
+  const padding = useMemo(
+    () => (settings?.overscroll === 'centering' ? calculateOverscroll(active.length) : {}),
+    [settings?.overscroll, active.length],
+  );
+
+  return (
+    <div role='none' className='relative bg-deck-surface overflow-hidden'>
+      <DeckSidebarToggles topbar={topbar} fullscreen={fullscreen} />
+      <Stack
+        classNames={[
+          'absolute h-[calc(100%-2*var(--main-spacing))] w-full inset-y-(--main-spacing) -inset-w-px',
+          mainPaddingTransitions,
+        ]}
+        style={padding}
+        orientation='horizontal'
+        size='contain'
+        itemsCount={itemsCount - 1}
+        onScroll={handleScroll}
+        ref={deckRef}
+      >
+        {active.map((entryId) => (
+          <Fragment key={entryId}>
+            {/* TODO(burdon): Setting for separator. */}
+            <PlankSeparator hidden order={order[entryId] - 1} encapsulate={!!settings?.encapsulatedPlanks} />
+            <PlankContainer
+              id={entryId}
+              part='multi'
+              active={active}
+              order={order[entryId]}
+              layoutMode={layoutMode}
+              companionVariant={effectiveCompanionVariant}
+              settings={settings}
+            />
+          </Fragment>
+        ))}
+      </Stack>
+    </div>
+  );
+};
+
+//
+// SidebarToggles
+//
+
+const sidebarToggleStyles = 'h-(--dx-rail-item) w-(--dx-rail-item) absolute bottom-2 z-[1] bg-deck-surface! lg:hidden';
+
+const ToggleSidebarButton = () => <NativeToggleSidebarButton classNames={mx(sidebarToggleStyles, 'left-2')} />;
+const ToggleComplementarySidebarButton = () => (
+  <NativeToggleComplementarySidebarButton classNames={mx(sidebarToggleStyles, 'right-2')} />
+);
+
+const DeckSidebarToggles = ({ topbar, fullscreen }: { topbar: boolean; fullscreen: boolean }) => {
+  if (topbar || fullscreen) {
+    return null;
+  }
+
+  return (
+    <>
+      <ToggleSidebarButton />
+      <ToggleComplementarySidebarButton />
+    </>
+  );
+};
+
+//
+// PlankSeparator
+//
+
+const PlankSeparator = ({ order, hidden, encapsulate }: { order: number; hidden?: boolean; encapsulate?: boolean }) =>
+  order > 0 && (
+    <span
+      role='separator'
+      className={mx('row-span-2 bg-deck-surface', hidden && 'hidden', encapsulate ? 'w-0' : 'w-4')}
+      style={{ gridColumn: order }}
+    />
+  );
+
+//
+// PlankContainer
+//
+
+type PlankContainerProps = Pick<PlankRootProps, 'layoutMode' | 'part' | 'settings'> &
+  Pick<PlankComponentProps, 'id'> &
+  Partial<Pick<PlankComponentProps, 'path' | 'order' | 'active'>> & {
+    companionVariant?: string;
+  };
+
+/**
+ * Connected Plank that calls hooks and renders the radix-style Plank tree.
+ * This is the bridge between DeckViewport (which knows about framework hooks) and
+ * the pure Plank components (which receive everything via context).
+ */
+const PlankContainer = memo(
+  ({ id, layoutMode, part, order, settings, companionVariant, ...props }: PlankContainerProps) => {
+    const { graph } = useAppGraph();
+    const { invokePromise } = useOperationInvoker();
+    const { state, deck } = useDeckState();
+    const node = useNode(graph, id);
+    const companions = useCompanions(id);
+    const { companionId } = useSelectedCompanion(companions, companionVariant);
+    const resolvedCompanionId = companionVariant ? companionId : undefined;
+    const currentCompanion = companions.find(({ id }) => id === resolvedCompanionId);
+    const hasCompanion = !!(resolvedCompanionId && currentCompanion);
+
+    const handleAdjust = useCallback(
+      (plankId: string, type: DeckOperation.PartAdjustment) => {
+        if (type === 'close') {
+          if (part === 'complementary') {
+            return invokePromise(LayoutOperation.UpdateComplementary, { state: 'collapsed' });
+          } else {
+            return invokePromise(LayoutOperation.Close, { subject: [plankId] });
+          }
+        } else {
+          return invokePromise(DeckOperation.Adjust, { type, id: plankId });
+        }
+      },
+      [invokePromise, part],
+    );
+
+    const handleResize = useCallback(
+      (plankId: string, size: number) => invokePromise(DeckOperation.UpdatePlankSize, { id: plankId, size }),
+      [invokePromise],
+    );
+
+    const handleScrollIntoView = useCallback(
+      (subject?: string) => invokePromise(LayoutOperation.ScrollIntoView, { subject }),
+      [invokePromise],
+    );
+
+    const handleChangeCompanion = useCallback(
+      (companion: string | null) => invokePromise(DeckOperation.ChangeCompanion, { companion }),
+      [invokePromise],
+    );
+
+    return (
+      <Plank.Root
+        graph={graph}
+        layoutMode={layoutMode}
+        part={part}
+        settings={settings}
+        popoverAnchorId={state.popoverAnchorId}
+        scrollIntoView={state.scrollIntoView}
+        plankSizing={deck.plankSizing}
+        onAdjust={handleAdjust}
+        onResize={handleResize}
+        onScrollIntoView={handleScrollIntoView}
+        onChangeCompanion={handleChangeCompanion}
+      >
+        <Plank.Content solo={part === 'solo'} companion={hasCompanion} encapsulate={!!settings?.encapsulatedPlanks}>
+          <Plank.Component
+            {...props}
+            id={id}
+            node={node}
+            companioned={hasCompanion ? 'primary' : undefined}
+            companions={hasCompanion ? [] : companions}
+            order={order}
+            {...(part === 'solo'
+              ? {
+                  part: 'solo-primary',
+                }
+              : {
+                  part,
+                })}
+          />
+          {hasCompanion && (
+            <Plank.Component
+              {...props}
+              id={resolvedCompanionId}
+              node={currentCompanion}
+              companions={companions}
+              companioned='companion'
+              primary={node}
+              {...(part === 'solo'
+                ? {
+                    part: 'solo-companion',
+                    order,
+                  }
+                : {
+                    part,
+                    order: (order ?? 0) + 1,
+                  })}
+            />
+          )}
+        </Plank.Content>
+      </Plank.Root>
+    );
+  },
+);

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

@@ -4,7 +4,7 @@
 
 import React from 'react';
 
-import { Surface } from '@dxos/app-framework/react';
+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/react';
+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>
+  );
+};