@dxos/plugin-deck 0.8.2-main.f11618f → 0.8.2-staging.42af850

package/src/components/Plank/Plank.stories.tsx

@@ -5,39 +5,51 @@
 import '@dxos-theme';
 
 import { type StoryObj, type Meta } from '@storybook/react';
+import React from 'react';
 
-import { IntentPlugin } from '@dxos/app-framework';
+import { IntentPlugin, SettingsPlugin } from '@dxos/app-framework';
 import { withPluginManager } from '@dxos/app-framework/testing';
+import { AttentionPlugin } from '@dxos/plugin-attention';
 import { GraphPlugin } from '@dxos/plugin-graph';
+import { Stack } from '@dxos/react-ui-stack';
 import { withTheme, withLayout } from '@dxos/storybook-utils';
 
-import { Plank } from './Plank';
+import { Plank, type PlankProps } from './Plank';
+import DeckStateFactory from '../../capabilities/state';
 import translations from '../../translations';
 
-// TODO(burdon): invariant violation: No capability found for dxos.org/plugin/deck/capability/state
-const meta: Meta<typeof Plank> = {
+const meta: Meta<PlankProps> = {
   title: 'plugins/plugin-deck/Plank',
   component: Plank,
+  render: (args) => {
+    return (
+      <Stack orientation='horizontal'>
+        <Plank {...args} />
+      </Stack>
+    );
+  },
   decorators: [
     withPluginManager({
-      plugins: [IntentPlugin(), GraphPlugin()],
+      plugins: [AttentionPlugin(), SettingsPlugin(), IntentPlugin(), GraphPlugin()],
+      capabilities: () => DeckStateFactory(),
     }),
     withTheme,
-    withLayout({ fullscreen: true, tooltips: true }),
+    withLayout({ fullscreen: true }),
   ],
   parameters: {
-    layout: 'centered',
     translations,
   },
 };
 
 export default meta;
 
-type Story = StoryObj<typeof meta>;
+type Story = StoryObj<PlankProps>;
 
+// TODO(burdon): Need to define surface provider?
 export const Default: Story = {
   args: {
     id: 'plank-1',
     part: 'solo',
+    layoutMode: 'deck',
   },
 };

package/src/components/Plank/Plank.tsx

@@ -3,7 +3,6 @@
 //
 
 import React, {
-  Fragment,
   type KeyboardEvent,
   type PropsWithChildren,
   memo,
@@ -31,40 +30,117 @@ import { PlankContentError, PlankError } from './PlankError';
 import { PlankHeading } from './PlankHeading';
 import { PlankLoading } from './PlankLoading';
 import { DeckCapabilities } from '../../capabilities';
-import { useMainSize } from '../../hooks';
+import { useMainSize, useCompanions } from '../../hooks';
 import { parseEntryId } from '../../layout';
-import { DeckAction, type LayoutMode, type Part, type ResolvedPart, type DeckSettingsProps } from '../../types';
-import { useCompanions } from '../../util';
+import { DeckAction, type LayoutMode, type ResolvedPart, type DeckSettingsProps } from '../../types';
 
 const UNKNOWN_ID = 'unknown_id';
 
-export type PlankProps = {
+export type PlankProps = Pick<PlankComponentProps, 'layoutMode' | 'part' | 'path' | 'order' | 'active' | 'settings'> & {
   id?: string;
   companionId?: string;
-  part: Part;
-  path?: string[];
-  order?: number;
-  active?: string[];
-  layoutMode: LayoutMode;
-  settings?: DeckSettingsProps;
 };
 
-type PlankImplProps = Omit<PlankProps, 'id' | 'companionId' | 'part'> & {
+// TODO(burdon): Factor out conditional rendering.
+//   Remove this wrapper component and render the entire set of planks in the deck with conditional visibility
+//   to obviate mounting and unmounting when switching between solo and companion mode?
+// NOTE(thure, in reply): Whether any surface should be rendered and hidden is a performance matter — remember that
+//  article surfaces contain full experiences, so being able to unmount them will yield relatively large performance
+//  benefits. I think where we anticipate users will definitely want to quickly switch between showing and hiding entire
+//  articles, over the (again probably large) performance benefit that unmounting them would confer, we can mount and
+//  hide them, but I think that scenario in its most unambiguous form is probably rare. You could extrapolate
+//  the scenario to include all “potential” planks such as companions, which we could keep mounted and hidden, but I
+//  don’t think the resulting performance would be acceptable. I think the real issue is “perceived performance” which
+//  has mitigations that are in between mounting and un-mounting since both of those have tradeoffs; we may need one or more
+//  “partially-mounted” experiences, like loading skeletons at the simple end, or screenshots of “sleeping” planks at
+//  the advanced end.
+
+/**
+ * A Plank is the main container for surfaces within a Deck.
+ * It may be paired with a companion plank that enables the user to select one of multiple companion surfaces.
+ */
+export const Plank = memo(({ id = UNKNOWN_ID, companionId, ...props }: PlankProps) => {
+  const { graph } = useAppGraph();
+  const node = useNode(graph, id);
+  const companions = useCompanions(id);
+  const currentCompanion = companions.find(({ id }) => id === companionId);
+  const hasCompanion = !!(companionId && currentCompanion);
+
+  return (
+    <PlankContainer solo={props.part === 'solo'} companion={hasCompanion}>
+      <PlankComponent
+        id={id}
+        node={node}
+        companioned={hasCompanion ? 'primary' : undefined}
+        companions={hasCompanion ? [] : companions}
+        {...props}
+        {...(props.part === 'solo' ? { part: 'solo-primary' } : {})}
+      />
+      {hasCompanion && (
+        <PlankComponent
+          id={companionId}
+          node={currentCompanion}
+          primary={node}
+          companions={companions}
+          companioned='companion'
+          {...props}
+          {...(props.part === 'solo' ? { part: 'solo-companion' } : { order: (props.order ?? 0) + 1 })}
+        />
+      )}
+    </PlankContainer>
+  );
+});
+
+const PlankContainer = ({ children, solo, companion }: PropsWithChildren<{ solo: boolean; companion: boolean }>) => {
+  const sizeAttrs = useMainSize();
+  if (!solo) {
+    return children;
+  }
+
+  // TODO(burdon): Make resizable.
+  return (
+    <div
+      role='none'
+      className={mx('absolute inset-0 grid', companion && 'grid-cols-[1fr_1fr]', railGridHorizontal, mainIntrinsicSize)}
+      {...sizeAttrs}
+    >
+      {children}
+    </div>
+  );
+};
+
+type PlankComponentProps = {
+  layoutMode: LayoutMode;
   id: string;
   part: ResolvedPart;
-  node?: Node;
+  path?: string[];
+  order?: number;
+  active?: string[];
+  // TODO(burdon): Change to role?
   companioned?: 'primary' | 'companion';
+  node?: Node;
   primary?: Node;
   companions?: Node[];
+  settings?: DeckSettingsProps;
 };
 
-const PlankImpl = memo(
-  ({ id, node, part, path, order, active, layoutMode, companioned, primary, companions, settings }: PlankImplProps) => {
+const PlankComponent = memo(
+  ({
+    layoutMode,
+    id,
+    part,
+    path,
+    order,
+    active,
+    companioned,
+    node,
+    primary,
+    companions,
+    settings,
+  }: PlankComponentProps) => {
     const { dispatchPromise: dispatch } = useIntentDispatcher();
     const { deck, popoverAnchorId, scrollIntoView } = useCapability(DeckCapabilities.DeckState);
-    const rootElement = useRef<HTMLDivElement | null>(null);
     const canResize = layoutMode === 'deck';
-    const Root = part.startsWith('solo') ? 'article' : StackItem.Root;
 
     const attendableAttrs = useAttendableAttributes(primary?.id ?? id);
     const index = active ? active.findIndex((entryId) => entryId === id) : 0;
@@ -72,10 +148,13 @@ const PlankImpl = memo(
     const canIncrementStart = active && index !== undefined && index > 0 && length !== undefined && length > 1;
     const canIncrementEnd = active && index !== undefined && index < length - 1 && length !== undefined;
 
+    const rootElement = useRef<HTMLDivElement | null>(null);
+
     const { variant } = parseEntryId(id);
     const sizeKey = `${id.split('+')[0]}${variant ? `${ATTENDABLE_PATH_SEPARATOR}${variant}` : ''}`;
     const size = deck.plankSizing[sizeKey] as number | undefined;
-    const setSize = useCallback(
+
+    const handleSizeChange = useCallback(
       debounce((nextSize: number) => {
         return dispatch(createIntent(DeckAction.UpdatePlankSize, { id: sizeKey, size: nextSize }));
       }, 200),
@@ -122,8 +201,9 @@ const PlankImpl = memo(
     // TODO(wittjosiah): Change prop to accept a component.
     const placeholder = useMemo(() => <PlankLoading />, []);
 
+    const Root = part.startsWith('solo') ? 'article' : StackItem.Root;
     const className = mx(
-      'attention-surface relative',
+      'attention-surface relative dx-focus-ring-inset-over-all',
       isSolo && mainIntrinsicSize,
       isSolo && railGridHorizontal,
       isSolo && 'absolute inset-0',
@@ -131,8 +211,6 @@ const PlankImpl = memo(
       part === 'deck' && (companioned === 'companion' ? '!border-separator border-ie' : '!border-separator border-li'),
       part.startsWith('solo-') && 'row-span-2 grid-rows-subgrid min-is-0',
       part === 'solo-companion' && '!border-separator border-is',
-      layoutMode === 'solo--fullscreen' &&
-        '!transition-[margin-block-start,inline-size] -mbs-[--rail-action] has-[[data-plank-heading]:hover]:mbs-0',
     );
 
     return (
@@ -145,7 +223,7 @@ const PlankImpl = memo(
           : {
               item: { id },
               size,
-              onSizeChange: setSize,
+              onSizeChange: handleSizeChange,
               classNames: className,
               order,
               role: 'article',
@@ -180,54 +258,9 @@ const PlankImpl = memo(
         ) : (
           <PlankError id={id} part={part} />
         )}
+
         {canResize && <StackItem.ResizeHandle />}
       </Root>
     );
   },
 );
-
-const SplitFrame = ({ children }: PropsWithChildren<{}>) => {
-  const sizeAttrs = useMainSize();
-  return (
-    <div
-      role='none'
-      className={mx('grid grid-cols-[1fr_1fr] absolute inset-0', railGridHorizontal, mainIntrinsicSize)}
-      {...sizeAttrs}
-    >
-      {children}
-    </div>
-  );
-};
-
-export const Plank = ({ id = UNKNOWN_ID, ...props }: PlankProps) => {
-  const { graph } = useAppGraph();
-  const node = useNode(graph, id);
-  const companions = useCompanions(id);
-  const currentCompanion = companions.find(({ id }) => id === props.companionId);
-
-  if (props.companionId) {
-    const Root = props.part === 'solo' ? SplitFrame : Fragment;
-    return (
-      <Root>
-        <PlankImpl
-          id={id}
-          node={node}
-          companioned='primary'
-          {...props}
-          {...(props.part === 'solo' ? { part: 'solo-primary' } : {})}
-        />
-        <PlankImpl
-          id={props.companionId}
-          node={currentCompanion}
-          companioned='companion'
-          primary={node}
-          companions={companions}
-          {...props}
-          {...(props.part === 'solo' ? { part: 'solo-companion' } : { order: props.order! + 1 })}
-        />
-      </Root>
-    );
-  } else {
-    return <PlankImpl id={id} node={node} companions={companions} {...props} />;
-  }
-};

package/src/components/Plank/PlankControls.tsx

@@ -6,15 +6,7 @@ import React, { forwardRef, useCallback } from 'react';
 
 import { createIntent, useIntentDispatcher } from '@dxos/app-framework';
 import { invariant } from '@dxos/invariant';
-import {
-  Button,
-  ButtonGroup,
-  type ButtonGroupProps,
-  type ButtonProps,
-  Icon,
-  Tooltip,
-  useTranslation,
-} from '@dxos/react-ui';
+import { ButtonGroup, type ButtonGroupProps, type ButtonProps, IconButton, useTranslation } from '@dxos/react-ui';
 
 import { DECK_PLUGIN } from '../../meta';
 import { DeckAction, type LayoutMode } from '../../types';
@@ -26,6 +18,7 @@ export type PlankCapabilities = {
   incrementEnd?: boolean;
   deck?: boolean;
   solo?: boolean;
+  fullscreen?: boolean;
   companion?: boolean;
 };
 
@@ -39,22 +32,10 @@ export type PlankControlsProps = Omit<ButtonGroupProps, 'onClick'> & {
 };
 
 const PlankControl = ({ icon, label, ...props }: Omit<ButtonProps, 'children'> & { label: string; icon: string }) => {
-  return (
-    <Tooltip.Root>
-      <Tooltip.Trigger asChild>
-        <Button variant='ghost' {...props}>
-          <span className='sr-only'>{label}</span>
-          <Icon icon={icon} size={5} />
-        </Button>
-      </Tooltip.Trigger>
-      <Tooltip.Portal>
-        <Tooltip.Content side='bottom'>{label}</Tooltip.Content>
-      </Tooltip.Portal>
-    </Tooltip.Root>
-  );
+  return <IconButton iconOnly label={label} icon={icon} size={5} variant='ghost' tooltipSide='bottom' {...props} />;
 };
 
-const plankControlSpacing = 'pli-2 plb-3';
+const plankControlSpacing = 'pli-2';
 
 type PlankComplimentControlsProps = {
   primary?: string;
@@ -97,8 +78,8 @@ export const PlankControls = forwardRef<HTMLDivElement, PlankControlsProps>(
     const layoutIsAnySolo = !!layoutMode?.startsWith('solo');
 
     return (
-      <ButtonGroup {...props} classNames={['app-no-drag', classNames]} ref={forwardedRef}>
-        {capabilities.deck && (
+      <ButtonGroup {...props} classNames={['app-no-drag !opacity-100', classNames]} ref={forwardedRef}>
+        {capabilities.deck ? (
           <>
             {capabilities.solo && (
               <>
@@ -150,6 +131,15 @@ export const PlankControls = forwardRef<HTMLDivElement, PlankControlsProps>(
               </>
             )}
           </>
+        ) : (
+          capabilities.fullscreen && (
+            <PlankControl
+              label={t(layoutMode === 'solo--fullscreen' ? 'exit fullscreen label' : 'show fullscreen plank label')}
+              classNames={buttonClassNames}
+              icon={layoutMode === 'solo--fullscreen' ? 'ph--corners-in--regular' : 'ph--corners-out--regular'}
+              onClick={() => onClick?.('solo--fullscreen')}
+            />
+          )
         )}
 
         {close && !layoutIsAnySolo && (

package/src/components/Plank/PlankHeading.tsx

@@ -9,12 +9,13 @@ import { type Node } from '@dxos/plugin-graph';
 import { Icon, IconButton, Popover, toLocalizedString, useTranslation } from '@dxos/react-ui';
 import { StackItem, type StackItemSigilAction } from '@dxos/react-ui-stack';
 import { TextTooltip } from '@dxos/react-ui-text-tooltip';
+import { hoverableControls, hoverableFocusedWithinControls } from '@dxos/react-ui-theme';
 
 import { PlankCompanionControls, PlankControls } from './PlankControls';
+import { useBreakpoints } from '../../hooks';
 import { parseEntryId } from '../../layout';
 import { DECK_PLUGIN } from '../../meta';
 import { PLANK_COMPANION_TYPE, DeckAction, type ResolvedPart, type LayoutMode } from '../../types';
-import { useBreakpoints } from '../../util';
 import { soloInlinePadding } from '../fragments';
 
 const MAX_COMPANIONS = 5;
@@ -65,7 +66,9 @@ export const PlankHeading = memo(
     useEffect(() => {
       const frame = requestAnimationFrame(() => {
         // Load actions for the node.
-        node && graph.actions(node);
+        if (node) {
+          void graph.expand(node.id);
+        }
       });
 
       return () => cancelAnimationFrame(frame);
@@ -78,6 +81,7 @@ export const PlankHeading = memo(
         solo: breakpoint !== 'mobile' && (part === 'solo' || part === 'deck'),
         incrementStart: canIncrementStart,
         incrementEnd: canIncrementEnd,
+        fullscreen: !isCompanionNode,
         companion: !isCompanionNode && companions && companions.length > 0,
       }),
       [breakpoint, part, companions, canIncrementStart, canIncrementEnd, isCompanionNode, deckEnabled],
@@ -90,13 +94,16 @@ export const PlankHeading = memo(
       } else if (variant) {
         return [];
       } else {
-        return [actions, graph.actions(node)].filter((a) => a.length > 0);
+        return [actions, graph.getActions(node.id)].filter((a) => a.length > 0);
       }
     }, [actions, node, variant, graph]);
 
-    const handleAction = useCallback((action: StackItemSigilAction) => {
-      typeof action.data === 'function' && action.data?.({ node: action as Node, caller: DECK_PLUGIN });
-    }, []);
+    const handleAction = useCallback(
+      (action: StackItemSigilAction) => {
+        typeof action.data === 'function' && action.data?.({ parent: node, caller: DECK_PLUGIN });
+      },
+      [node],
+    );
 
     const handlePlankAction = useCallback(
       (eventType: DeckAction.PartAdjustment) => {
@@ -143,14 +150,19 @@ export const PlankHeading = memo(
     return (
       <StackItem.Heading
         classNames={[
-          'plb-1 border-be border-separator items-stretch gap-1 sticky inline-start-12 app-drag min-is-0 contain-layout',
+          'plb-1 border-be border-subduedSeparator items-stretch gap-1 sticky inline-start-12 app-drag min-is-0 contain-layout',
           part === 'solo' ? soloInlinePadding : 'pli-1',
-          layoutMode === 'solo--fullscreen' &&
-            'opacity-0 border-transparent hover:border-separator hover:opacity-100 transition-[border-color,opacity]',
+          ...(layoutMode === 'solo--fullscreen'
+            ? [
+                hoverableControls,
+                hoverableFocusedWithinControls,
+                '[&>*]:transition-opacity [&>*]:opacity-[--controls-opacity] bg-transparent border-transparent transition-[background-color,border-color] hover-hover:hover:bg-headerSurface focus-within:bg-headerSurface hover-hover:hover:border-subduedSeparator focus-within:border-subduedSeparator',
+              ]
+            : []),
         ]}
         data-plank-heading
       >
-        {companions && isCompanionNode ? (
+        {companions && isCompanionNode /* TODO(thure): This is a tablist, it should be implemented as such. */ ? (
           <div role='none' className='flex-1 min-is-0 overflow-x-auto scrollbar-thin flex gap-1'>
             {companions.map(({ id, properties: { icon, label } }) => (
               <IconButton

package/src/components/Sidebar/ComplementarySidebar.tsx

@@ -12,51 +12,20 @@ import React, {
   useState,
 } from 'react';
 
-import {
-  LayoutAction,
-  Surface,
-  createIntent,
-  useAppGraph,
-  useCapability,
-  useIntentDispatcher,
-} from '@dxos/app-framework';
-import { type Node } from '@dxos/plugin-graph';
+import { LayoutAction, Surface, createIntent, useCapability, useIntentDispatcher } from '@dxos/app-framework';
 import { Main, useTranslation, toLocalizedString, IconButton, type Label } from '@dxos/react-ui';
 import { Tabs } from '@dxos/react-ui-tabs';
-import { byPosition, type Position } from '@dxos/util';
 
 import { ToggleComplementarySidebarButton } from './SidebarButton';
 import { DeckCapabilities } from '../../capabilities';
+import { type DeckCompanion, getCompanionId, useDeckCompanions, useBreakpoints, useHoistStatusbar } from '../../hooks';
 import { DECK_PLUGIN } from '../../meta';
-import { ATTENDABLE_PATH_SEPARATOR, DECK_COMPANION_TYPE, getMode } from '../../types';
-import { layoutAppliesTopbar, useBreakpoints, useHoistStatusbar } from '../../util';
+import { getMode } from '../../types';
+import { layoutAppliesTopbar } from '../../util';
 import { PlankContentError, PlankLoading } from '../Plank';
 
 const label = ['complementary sidebar title', { ns: DECK_PLUGIN }] satisfies Label;
 
-const getCompanionId = (id: string) => {
-  const [_, companionId] = id.split(ATTENDABLE_PATH_SEPARATOR);
-  return companionId ?? 'never';
-};
-
-type DeckCompanion = Node<
-  any,
-  {
-    label: Label;
-    icon: string;
-    // TODO(burdon): Scroll area should be controlled by surface.
-    /** If true, the panel will not be wrapped in a scroll area. */
-    fixed?: boolean;
-    position?: Position;
-  }
->;
-
-const useDeckCompanions = (): DeckCompanion[] => {
-  const { graph } = useAppGraph();
-  const companions = graph.nodes(graph.root, { type: DECK_COMPANION_TYPE }) as DeckCompanion[];
-  return companions.toSorted((a, b) => byPosition(a.properties, b.properties));
-};
-
 export type ComplementarySidebarProps = {
   current?: string;
 };
@@ -121,7 +90,7 @@ export const ComplementarySidebar = ({ current }: ComplementarySidebarProps) =>
       <Tabs.Root orientation='vertical' verticalVariant='stateless' value={internalValue} classNames='contents'>
         <div
           role='none'
-          className='absolute z-[1] inset-block-0 inline-end-0 !is-[--r0-size] pbs-[env(safe-area-inset-top)] pbe-[env(safe-area-inset-bottom)] border-is border-separator grid grid-cols-1 grid-rows-[1fr_min-content] bg-baseSurface contain-layout app-drag'
+          className='absolute z-[1] inset-block-0 inline-end-0 !is-[--r0-size] pbs-[env(safe-area-inset-top)] pbe-[env(safe-area-inset-bottom)] border-is border-subduedSeparator grid grid-cols-1 grid-rows-[1fr_min-content] bg-baseSurface contain-layout app-drag'
         >
           <Tabs.Tablist classNames='grid grid-cols-1 auto-rows-[--rail-action] p-1 gap-1 !overflow-y-auto'>
             {companions.map((companion) => (
@@ -200,7 +169,7 @@ const ComplementarySidebarPanel = ({ companion, activeId, data, hoistStatusbar }
 
   return (
     <>
-      <h2 className='flex items-center pli-2 border-separator border-be font-medium'>
+      <h2 className='flex items-center pli-2 border-subduedSeparator border-be font-medium'>
         {toLocalizedString(companion.properties.label, t)}
       </h2>
       <Wrapper>
@@ -214,7 +183,7 @@ const ComplementarySidebarPanel = ({ companion, activeId, data, hoistStatusbar }
       {!hoistStatusbar && (
         <div
           role='contentinfo'
-          className='flex flex-wrap justify-center items-center border-bs border-separator pbs-1 pbe-[max(env(safe-area-inset-bottom),0.25rem)]'
+          className='flex flex-wrap justify-center items-center border-bs border-subduedSeparator pbs-1 pbe-[max(env(safe-area-inset-bottom),0.25rem)]'
         >
           <Surface role='status-bar--r1-footer' limit={1} />
         </div>

package/src/components/Sidebar/Sidebar.tsx

@@ -8,9 +8,10 @@ import { Surface, useCapability } from '@dxos/app-framework';
 import { type Label, Main } from '@dxos/react-ui';
 
 import { DeckCapabilities } from '../../capabilities';
+import { useBreakpoints, useHoistStatusbar } from '../../hooks';
 import { DECK_PLUGIN } from '../../meta';
 import { getMode } from '../../types';
-import { layoutAppliesTopbar, useBreakpoints, useHoistStatusbar } from '../../util';
+import { layoutAppliesTopbar } from '../../util';
 
 const label = ['sidebar title', { ns: DECK_PLUGIN }] satisfies Label;
 

package/src/components/Sidebar/SidebarButton.tsx

@@ -2,12 +2,13 @@
 // Copyright 2025 DXOS.org
 //
 
-import React from 'react';
+import React, { useCallback } from 'react';
 
-import { useCapability } from '@dxos/app-framework';
+import { createIntent, LayoutAction, useCapability, useIntentDispatcher } from '@dxos/app-framework';
 import { IconButton, type IconButtonProps, type ThemedClassName, useTranslation } from '@dxos/react-ui';
 
 import { DeckCapabilities } from '../../capabilities';
+import { useDeckCompanions, getCompanionId } from '../../hooks';
 import { DECK_PLUGIN } from '../../meta';
 
 export const ToggleSidebarButton = ({
@@ -47,16 +48,34 @@ export const CloseSidebarButton = () => {
   );
 };
 
-export const ToggleComplementarySidebarButton = ({ inR0, classNames }: ThemedClassName<{ inR0?: boolean }>) => {
+export const ToggleComplementarySidebarButton = ({
+  inR0,
+  classNames,
+  current,
+}: ThemedClassName<{ inR0?: boolean; current?: string }>) => {
+  const { dispatchPromise: dispatch } = useIntentDispatcher();
   const layoutContext = useCapability(DeckCapabilities.MutableDeckState);
   const { t } = useTranslation(DECK_PLUGIN);
+
+  const companions = useDeckCompanions();
+  const handleClick = useCallback(async () => {
+    layoutContext.complementarySidebarState =
+      layoutContext.complementarySidebarState === 'expanded' ? 'collapsed' : 'expanded';
+    const firstCompanion = companions[0];
+    if (layoutContext.complementarySidebarState === 'expanded' && !current && firstCompanion) {
+      await dispatch(
+        createIntent(LayoutAction.UpdateComplementary, {
+          part: 'complementary',
+          subject: getCompanionId(firstCompanion.id),
+        }),
+      );
+    }
+  }, [layoutContext, current, companions, dispatch]);
+
   return (
     <IconButton
       iconOnly
-      onClick={() =>
-        (layoutContext.complementarySidebarState =
-          layoutContext.complementarySidebarState === 'expanded' ? 'collapsed' : 'expanded')
-      }
+      onClick={handleClick}
       variant='ghost'
       label={t('open complementary sidebar label')}
       classNames={['[&>svg]:-scale-x-100', classNames]}

package/src/components/fragments.ts

@@ -7,7 +7,7 @@ import { mx } from '@dxos/react-ui-theme';
 export const soloInlinePadding =
   'pis-[calc(env(safe-area-inset-left)+.25rem)] pie-[calc(env(safe-area-inset-left)+.25rem)]';
 
-const sidebarToggleStyles = 'bs-[--rail-item] is-[--rail-item] absolute block-end-2 z-[1] !bg-deck lg:hidden';
+const sidebarToggleStyles = 'bs-[--rail-item] is-[--rail-item] absolute block-end-2 z-[1] !bg-deckSurface lg:hidden';
 
 export const fixedSidebarToggleStyles = mx(sidebarToggleStyles, 'inline-start-2');
 

package/src/hooks/index.ts

@@ -2,5 +2,9 @@
 // Copyright 2024 DXOS.org
 //
 
-export * from './useNodeActionExpander';
+export * from './useBreakpoints';
+export * from './useCompanions';
+export * from './useDeckCompanions';
+export * from './useHoistStatusbar';
 export * from './useMainSize';
+export * from './useNodeActionExpander';

package/src/{util → hooks}/useCompanions.ts

@@ -5,14 +5,14 @@
 import { useMemo } from 'react';
 
 import { useAppGraph } from '@dxos/app-framework';
-import { useNode } from '@dxos/plugin-graph';
+import { useConnections } from '@dxos/plugin-graph';
 import { byPosition } from '@dxos/util';
 
 import { PLANK_COMPANION_TYPE } from '../types';
 
 export const useCompanions = (id?: string) => {
   const { graph } = useAppGraph();
-  const node = useNode(graph, id);
-  const companions = node ? graph.nodes(node, { type: PLANK_COMPANION_TYPE }) : [];
+  const nodes = useConnections(graph, id);
+  const companions = nodes.filter((node) => node.type === PLANK_COMPANION_TYPE);
   return useMemo(() => companions.toSorted((a, b) => byPosition(a.properties, b.properties)), [companions]);
 };