@dxos/plugin-simple-layout 0.8.4-main.bc674ce → 0.8.4-main.d05673bc65

package/src/components/SimpleLayout/Main.tsx

@@ -4,17 +4,19 @@
 
 import React, { useMemo } 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 { Main as NaturalMain, useSidebars } from '@dxos/react-ui';
+import { ErrorFallback } from '@dxos/react-ui';
+import { useAttentionAttributes } from '@dxos/react-ui-attention';
 import { mx } from '@dxos/ui-theme';
 
-import { useSimpleLayoutState } from '../../hooks';
-import { ContentError } from '../ContentError';
+import { useAppBarProps, useNavbarActions, useSimpleLayoutState } from '../../hooks';
 import { ContentLoading } from '../ContentLoading';
-import { useLoadDescendents } from '../hooks';
+import { useExpandPath } from '../hooks';
+import { useMobileLayout } from '../MobileLayout';
 
-import { Banner } from './Banner';
+import { AppBar } from './AppBar';
 import { NavBar } from './NavBar';
 
 const MAIN_NAME = 'SimpleLayout.Main';
@@ -24,15 +26,16 @@ const MAIN_NAME = 'SimpleLayout.Main';
  */
 export const Main = () => {
   const { state } = useSimpleLayoutState();
-  const { graph } = useAppGraph();
   const id = state.active ?? state.workspace;
-  const node = useNode(graph, id);
-
-  // Ensures that children are loaded so that they are available to navigate to.
-  useLoadDescendents(id);
+  const attentionAttrs = useAttentionAttributes(id);
+  const { keyboardOpen } = useMobileLayout(MAIN_NAME);
+  const { actions, onAction } = useNavbarActions();
+  const appBarProps = useAppBarProps();
 
   const placeholder = useMemo(() => <ContentLoading />, []);
 
+  const { graph } = useAppGraph();
+  const node = useNode(graph, id);
   const data = useMemo(() => {
     return (
       node && {
@@ -44,28 +47,35 @@ export const Main = () => {
     );
   }, [id, node, node?.data, node?.properties, state.popoverAnchorId]);
 
-  const { drawerState } = useSidebars(MAIN_NAME);
-  const showNavBar = !state.isPopover && drawerState === 'closed';
+  useExpandPath(id);
+
+  // TODO(burdon): BUG: When showing ANY statusbar the size progressively shrinks when the keyboard opens/closes.
+  const showNavBar = !keyboardOpen && !state.isPopover && state.drawerState === 'closed';
 
   return (
-    <NaturalMain.Content
-      bounce
-      classNames={mx('bs-full', 'pbs-[env(safe-area-inset-top)] pbe-[env(safe-area-inset-bottom)]')}
+    <div
+      role='none'
+      className={mx(
+        'h-full grid overflow-hidden bg-toolbar-surface',
+        showNavBar
+          ? 'grid-rows-[var(--dx-rail-action)_1fr_var(--dx-toolbar-size)]'
+          : 'grid-rows-[var(--dx-rail-action)_1fr]',
+      )}
+      {...attentionAttrs}
     >
-      <div
-        role='none'
-        className={mx(
-          'grid bs-full overflow-hidden',
-          showNavBar ? 'grid-rows-[min-content_1fr_min-content]' : 'grid-rows-[min-content_1fr]',
-        )}
-      >
-        <Banner classNames='border-be border-separator' node={node} />
-        <article className='bs-full overflow-hidden'>
-          <Surface key={id} role='article' data={data} limit={1} fallback={ContentError} placeholder={placeholder} />
-        </article>
-        {showNavBar && <NavBar classNames='border-bs border-separator' activeId={id} />}
-      </div>
-    </NaturalMain.Content>
+      <AppBar {...appBarProps} />
+      <article className='h-full overflow-hidden bg-base-surface'>
+        <Surface.Surface
+          key={id}
+          role='article'
+          data={data}
+          limit={1}
+          fallback={ErrorFallback}
+          placeholder={placeholder}
+        />
+      </article>
+      {showNavBar && <NavBar classNames='border-y border-subdued-separator' actions={actions} onAction={onAction} />}
+    </div>
   );
 };
 

package/src/components/SimpleLayout/NavBar.stories.tsx

@@ -2,25 +2,97 @@
 // Copyright 2025 DXOS.org
 //
 
+import { Atom } from '@effect-atom/atom-react';
 import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React, { useMemo } from 'react';
+import { type Mock, expect, fn, screen, userEvent, within } from 'storybook/test';
 
-import { withPluginManager } from '@dxos/app-framework/testing';
-import { corePlugins } from '@dxos/plugin-testing';
-import { withTheme } from '@dxos/react-ui/testing';
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+import { type ActionGraphProps, createGapSeparator, createMenuAction, createMenuItemGroup } from '@dxos/react-ui-menu';
+import { withRegistry } from '@dxos/storybook-utils';
 
 import { translations } from '../../translations';
 
 import { NavBar } from './NavBar';
 
+const MAIN_MENU_GROUP_ID = 'navbar-main-menu';
+
+const buildEmptyActions = (): ActionGraphProps => ({ nodes: [], edges: [] });
+
+const buildCompanionOnlyActions = (): ActionGraphProps => {
+  const result: ActionGraphProps = { nodes: [], edges: [] };
+  const companions = [
+    createMenuAction('companion-browse', () => console.log('Browse'), {
+      icon: 'ph--house--regular',
+      label: 'Browse',
+      iconOnly: true,
+    }),
+    createMenuAction('companion-notifications', () => console.log('Notifications'), {
+      icon: 'ph--bell--regular',
+      label: 'Notifications',
+      iconOnly: true,
+    }),
+    createMenuAction('companion-profile', () => console.log('Profile'), {
+      icon: 'ph--user--regular',
+      label: 'Profile',
+      iconOnly: true,
+    }),
+  ];
+  result.nodes.push(...companions);
+  result.edges.push(...companions.map((c) => ({ source: 'root', target: c.id, relation: 'child' })));
+  return result;
+};
+
+const buildDefaultActions = (): ActionGraphProps => {
+  const result: ActionGraphProps = { nodes: [], edges: [] };
+  const gapSeparator = createGapSeparator('navbar-gap');
+  const mainMenuGroup = createMenuItemGroup(MAIN_MENU_GROUP_ID, {
+    variant: 'dropdownMenu',
+    icon: 'ph--plus--regular',
+    iconOnly: true,
+    label: 'Main menu',
+    testId: 'simpleLayoutPlugin.addSpace',
+  });
+  const companions = [
+    createMenuAction('companion-browse', () => console.log('Browse'), {
+      icon: 'ph--house--regular',
+      label: 'Browse',
+      iconOnly: true,
+    }),
+    createMenuAction('companion-notifications', () => console.log('Notifications'), {
+      icon: 'ph--bell--regular',
+      label: 'Notifications',
+      iconOnly: true,
+    }),
+  ];
+  const menuActions = [
+    createMenuAction('action-create-space', () => console.log('Create space'), {
+      icon: 'ph--planet--regular',
+      label: 'Create space',
+    }),
+    createMenuAction('action-join-space', () => console.log('Join space'), {
+      icon: 'ph--sign-in--regular',
+      label: 'Join space',
+    }),
+    createMenuAction('action-settings', () => console.log('Settings'), {
+      icon: 'ph--gear--regular',
+      label: 'Settings',
+    }),
+  ];
+  result.nodes.push(...companions, ...gapSeparator.nodes, mainMenuGroup, ...menuActions);
+  result.edges.push(
+    ...companions.map((c) => ({ source: 'root', target: c.id, relation: 'child' })),
+    ...gapSeparator.edges,
+    { source: 'root', target: mainMenuGroup.id, relation: 'child' },
+    ...menuActions.map((action) => ({ source: MAIN_MENU_GROUP_ID, target: action.id, relation: 'child' })),
+  );
+  return result;
+};
+
 const meta = {
-  title: 'plugins/plugin-simple-layout/NavBar',
+  title: 'plugins/plugin-simple-layout/components/NavBar',
   component: NavBar,
-  decorators: [
-    withTheme,
-    withPluginManager({
-      plugins: [...corePlugins()],
-    }),
-  ],
+  decorators: [withTheme(), withLayout({ layout: 'fullscreen' }), withRegistry],
   parameters: {
     layout: 'fullscreen',
     translations,
@@ -31,26 +103,62 @@ export default meta;
 
 type Story = StoryObj<typeof meta>;
 
+const DefaultStory = ({ onAction }: { onAction: (action: { id: string }) => void }) => {
+  const actions = useMemo(() => Atom.make(buildDefaultActions()).pipe(Atom.keepAlive), []);
+
+  return <NavBar classNames='border-y border-separator' actions={actions} onAction={onAction} />;
+};
+
 export const Default: Story = {
+  tags: ['test'],
   args: {
-    activeId: undefined,
+    onAction: fn(),
+  } as any,
+  render: (args: any) => <DefaultStory onAction={args.onAction} />,
+  play: async ({ args, canvasElement }) => {
+    const canvas = within(canvasElement);
+
+    // Verify the navbar renders with the toolbar.
+    await expect(canvas.getByRole('toolbar')).toBeInTheDocument();
+
+    // Test companion action click (Browse button).
+    const browseButton = canvas.getByRole('button', { name: /browse/i });
+    await expect(browseButton).toBeInTheDocument();
+    await userEvent.click(browseButton);
+    await expect(args.onAction).toHaveBeenCalledTimes(1);
+    await expect((args.onAction as Mock).mock.calls[0][0]).toHaveProperty('id', 'companion-browse');
+
+    // Test dropdown menu opens and action fires.
+    const menuTrigger = canvas.getByRole('button', { name: /main menu/i });
+    await expect(menuTrigger).toBeInTheDocument();
+    await userEvent.click(menuTrigger);
+
+    // Wait for menu to open and click an action (menu items render in a portal).
+    const createSpaceAction = await screen.findByRole('menuitem', { name: /create space/i });
+    await userEvent.click(createSpaceAction);
+    await expect(args.onAction).toHaveBeenCalledTimes(2);
+    await expect((args.onAction as Mock).mock.calls[1][0]).toHaveProperty('id', 'action-create-space');
   },
 };
 
-export const BrowseActive: Story = {
-  args: {
-    activeId: 'some-document',
-  },
+const CompanionsOnlyStory = () => {
+  const actions = useMemo(() => Atom.make(buildCompanionOnlyActions()).pipe(Atom.keepAlive), []);
+
+  return <NavBar actions={actions} onAction={(action) => console.log('Action:', action.id)} />;
 };
 
-export const NotificationsActive: Story = {
-  args: {
-    activeId: 'notifications',
-  },
+export const CompanionsOnly: Story = {
+  args: {} as any,
+  render: () => <CompanionsOnlyStory />,
 };
 
-export const ProfileActive: Story = {
-  args: {
-    activeId: 'profile',
-  },
+const EmptyStory = () => {
+  const actions = useMemo(() => Atom.make(buildEmptyActions()).pipe(Atom.keepAlive), []);
+
+  return <NavBar actions={actions} onAction={(action) => console.log('Action:', action.id)} />;
+};
+
+export const Empty: Story = {
+  args: {} as any,
+  render: () => <EmptyStory />,
 };

package/src/components/SimpleLayout/NavBar.tsx

@@ -2,64 +2,32 @@
 // Copyright 2025 DXOS.org
 //
 
+import { type Atom } from '@effect-atom/atom-react';
 import React from 'react';
 
-import { Common } from '@dxos/app-framework';
-import { useAppGraph, useOperationInvoker } from '@dxos/app-framework/react';
-import { Node, useActionRunner, useConnections } from '@dxos/plugin-graph';
-import { IconButton, type ThemedClassName, Toolbar, Tooltip, toLocalizedString, useTranslation } from '@dxos/react-ui';
-import { DropdownMenu, MenuProvider } from '@dxos/react-ui-menu';
+import { type ThemedClassName } from '@dxos/react-ui';
+import { type ActionExecutor, type ActionGraphProps, Menu, useMenuActions } from '@dxos/react-ui-menu';
 import { mx } from '@dxos/ui-theme';
 
-import { useCompanions } from '../../hooks';
-import { meta } from '../../meta';
-
 const NAVBAR_NAME = 'SimpleLayout.NavBar';
 
 export type NavBarProps = ThemedClassName<{
-  /** Active AppGraph node ID. */
-  activeId?: string;
+  /** Action graph atom for the toolbar. */
+  actions: Atom.Atom<ActionGraphProps>;
+  /** Action executor callback. */
+  onAction?: ActionExecutor;
 }>;
 
-export const NavBar = ({ classNames, activeId }: NavBarProps) => {
-  const { t } = useTranslation(meta.id);
-  const { graph } = useAppGraph();
-  const runAction = useActionRunner();
-  const { invokePromise } = useOperationInvoker();
-
-  const connections = useConnections(graph, Node.RootId);
-  const menuActions = connections.filter((node) => node.properties.disposition === 'menu');
-
-  const companions = useCompanions(activeId);
+/**
+ * Presentational navbar component that renders a toolbar from an action graph.
+ */
+export const NavBar = ({ classNames, actions, onAction }: NavBarProps) => {
+  const menu = useMenuActions(actions);
 
   return (
-    <Toolbar.Root classNames={mx('justify-center', classNames)}>
-      {companions.map((companion) => (
-        <Toolbar.IconButton
-          key={companion.id}
-          icon={companion.properties.icon ?? 'ph--placeholder--regular'}
-          iconOnly
-          label={toLocalizedString(companion.properties.label, t)}
-          onClick={() => {
-            void invokePromise(Common.LayoutOperation.Open, {
-              subject: [companion.id],
-            });
-          }}
-        />
-      ))}
-
-      <Toolbar.Separator variant='gap' />
-
-      <MenuProvider onAction={runAction}>
-        <DropdownMenu.Root items={menuActions}>
-          <Tooltip.Trigger asChild content={t('app menu label')}>
-            <DropdownMenu.Trigger asChild data-testid='simpleLayoutPlugin.addSpace'>
-              <IconButton icon='ph--plus--regular' iconOnly label={t('main menu label')} />
-            </DropdownMenu.Trigger>
-          </Tooltip.Trigger>
-        </DropdownMenu.Root>
-      </MenuProvider>
-    </Toolbar.Root>
+    <Menu.Root {...menu} alwaysActive onAction={onAction}>
+      <Menu.Toolbar density='coarse' classNames={mx(classNames)} />
+    </Menu.Root>
   );
 };
 

package/src/components/SimpleLayout/SimpleLayout.stories.tsx

@@ -5,16 +5,17 @@
 import { type Meta, type StoryObj } from '@storybook/react-vite';
 import * as Effect from 'effect/Effect';
 
-import { Capability, Common, Plugin } from '@dxos/app-framework';
+import { ActivationEvents, Capabilities, Capability, Plugin } from '@dxos/app-framework';
 import { withPluginManager } from '@dxos/app-framework/testing';
+import { AppActivationEvents, AppPlugin } from '@dxos/app-toolkit';
+import { Collection } from '@dxos/echo';
 import { ClientOperation, ClientPlugin } from '@dxos/plugin-client';
 import { SearchPlugin } from '@dxos/plugin-search';
 import { SpacePlugin } from '@dxos/plugin-space';
 import { SpaceOperation } from '@dxos/plugin-space/types';
 import { corePlugins } from '@dxos/plugin-testing';
-import { withTheme } from '@dxos/react-ui/testing';
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
 import { translations as searchTranslation } from '@dxos/react-ui-searchlist';
-import { Collection } from '@dxos/schema';
 
 import { OperationResolver, type SimpleLayoutStateOptions, State } from '../../capabilities';
 import { meta as pluginMeta } from '../../meta';
@@ -24,18 +25,18 @@ import { translations } from '../../translations';
 import { SimpleLayout } from './SimpleLayout';
 
 const TestPlugin = Plugin.define<SimpleLayoutPluginOptions>(pluginMeta).pipe(
+  AppPlugin.addOperationResolverModule({ activate: OperationResolver }),
   Plugin.addModule(({ isPopover = false }) => ({
     id: Capability.getModuleTag(State),
-    activatesOn: Common.ActivationEvent.Startup,
-    activatesAfter: [Common.ActivationEvent.LayoutReady],
+    activatesOn: ActivationEvents.Startup,
+    activatesAfter: [AppActivationEvents.LayoutReady],
     activate: () => State({ initialState: { isPopover } } satisfies SimpleLayoutStateOptions),
   })),
-  Common.Plugin.addOperationResolverModule({ activate: OperationResolver }),
   Plugin.addModule({
     id: 'setup',
-    activatesOn: Common.ActivationEvent.OperationInvokerReady,
+    activatesOn: ActivationEvents.OperationInvokerReady,
     activate: Effect.fnUntraced(function* () {
-      const { invoke } = yield* Capability.get(Common.Capability.OperationInvoker);
+      const { invoke } = yield* Capability.get(Capabilities.OperationInvoker);
       yield* invoke(ClientOperation.CreateIdentity, {});
       const { space: work } = yield* invoke(SpaceOperation.Create, { name: 'Work Space' });
       const { space: sharedProject } = yield* invoke(SpaceOperation.Create, { name: 'Shared Project' });
@@ -79,7 +80,7 @@ const createPluginManager = ({ isPopover }: { isPopover: boolean }) => {
 };
 
 const meta = {
-  title: 'plugins/plugin-simple-layout/SimpleLayout',
+  title: 'plugins/plugin-simple-layout/components/SimpleLayout',
   component: SimpleLayout,
   parameters: {
     layout: 'fullscreen',
@@ -96,9 +97,17 @@ type Story = StoryObj<typeof meta>;
  * `moon run storybook-react:serve dev -H 0.0.0.0`
  */
 export const Default: Story = {
-  decorators: [withTheme, createPluginManager({ isPopover: false })],
+  decorators: [
+    withTheme(),
+    withLayout({ layout: 'column', classNames: 'relative' }),
+    createPluginManager({ isPopover: false }),
+  ],
 };
 
 export const Popover: Story = {
-  decorators: [withTheme, createPluginManager({ isPopover: true })],
+  decorators: [
+    withTheme(),
+    withLayout({ layout: 'column', classNames: 'relative' }),
+    createPluginManager({ isPopover: true }),
+  ],
 };

package/src/components/SimpleLayout/SimpleLayout.tsx

@@ -2,39 +2,58 @@
 // Copyright 2025 DXOS.org
 //
 
-import React, { useCallback } from 'react';
+import React, { useEffect, useRef, useState } from 'react';
 
-import { type DrawerState, Main as NaturalMain } from '@dxos/react-ui';
+import { Splitter, type SplitterMode } from '@dxos/react-ui';
 import { Mosaic } from '@dxos/react-ui-mosaic';
 
 import { useSimpleLayoutState } from '../../hooks';
 import { Dialog } from '../Dialog';
+import { MobileLayout } from '../MobileLayout';
 import { PopoverContent, PopoverRoot } from '../Popover';
 
 import { Drawer } from './Drawer';
 import { Main } from './Main';
 
+// TODO(burdon): Mobile/Desktop variance?
 export const SimpleLayout = () => {
-  const { state, updateState } = useSimpleLayoutState();
+  const { state } = useSimpleLayoutState();
+  const [keyboardOpen, setKeyboardOpen] = useState(false);
+  const [splitterMode, setSplitterMode] = useState<SplitterMode>('upper');
 
-  const handleDrawerStateChange = useCallback(
-    (nextState: DrawerState) => {
-      // Sync all drawer state changes to state.
-      updateState((s) => ({ ...s, drawerState: nextState }));
-    },
-    [updateState],
-  );
+  const drawerRef = useRef<HTMLDivElement>(null);
+  useEffect(() => {
+    if (keyboardOpen) {
+      // Determine which panel has focus and expand that one.
+      const activeElement = document.activeElement;
+      const drawerHasFocus = drawerRef.current?.contains(activeElement);
+      setSplitterMode(drawerHasFocus ? 'lower' : 'upper');
+    } else {
+      setSplitterMode(state.drawerState === 'closed' ? 'upper' : state.drawerState === 'open' ? 'both' : 'lower');
+    }
+  }, [state.drawerState, keyboardOpen]);
 
   return (
-    <Mosaic.Root>
-      <NaturalMain.Root drawerState={state.drawerState ?? 'closed'} onDrawerStateChange={handleDrawerStateChange}>
-        <PopoverRoot>
-          <Main />
-          <Drawer />
-          <Dialog />
-          <PopoverContent />
-        </PopoverRoot>
-      </NaturalMain.Root>
+    <Mosaic.Root classNames='contents'>
+      <MobileLayout.Root
+        classNames='bg-toolbar-surface'
+        onKeyboardOpenChange={(keyboardOpen: boolean) => setKeyboardOpen(keyboardOpen)}
+      >
+        <MobileLayout.Panel safe={{ top: true, bottom: splitterMode === 'upper' }}>
+          <PopoverRoot>
+            <Splitter.Root mode={splitterMode} ratio={0.55}>
+              <Splitter.Panel position='upper'>
+                <Main />
+              </Splitter.Panel>
+              <Splitter.Panel position='lower' ref={drawerRef}>
+                <Drawer />
+              </Splitter.Panel>
+            </Splitter.Root>
+            <Dialog />
+            <PopoverContent />
+          </PopoverRoot>
+        </MobileLayout.Panel>
+      </MobileLayout.Root>
     </Mosaic.Root>
   );
 };

package/src/components/SimpleLayout/index.ts

@@ -2,4 +2,7 @@
 // Copyright 2026 DXOS.org
 //
 
+export * from './AppBar';
+export * from './Main';
+export * from './NavBar';
 export * from './SimpleLayout';

package/src/components/hooks.ts

@@ -4,23 +4,23 @@
 
 import { useEffect } from 'react';
 
-import { useAppGraph } from '@dxos/app-framework/react';
+import { expandAttendableId } from '@dxos/react-ui-attention';
+import { useAppGraph } from '@dxos/app-toolkit/ui';
 import { Graph } from '@dxos/plugin-graph';
 
 /**
- * Hook to expand graph nodes two levels deep when directly linked to.
+ * Expand graph nodes along the full path from root to the given node ID.
+ * Walks each progressive prefix, ensuring ancestor nodes are materialized
+ * before attempting to access their children.
  */
-export const useLoadDescendents = (nodeId?: string) => {
+export const useExpandPath = (nodeId?: string) => {
   const { graph } = useAppGraph();
 
   useEffect(() => {
     if (nodeId) {
-      // First level: expand the node itself.
-      Graph.expand(graph, nodeId, 'outbound');
-      // Second level: expand each child.
-      Graph.getConnections(graph, nodeId, 'outbound').forEach((child) => {
-        Graph.expand(graph, child.id, 'outbound');
-      });
+      for (const prefix of expandAttendableId(nodeId)) {
+        Graph.expand(graph, prefix, 'child');
+      }
     }
   }, [nodeId, graph]);
 };

package/src/components/index.ts

@@ -4,6 +4,7 @@
 
 export * from './ContentLoading';
 export * from './Home';
+export * from './MobileLayout';
 export * from './Popover';
 export * from './SimpleLayout';
-export * from './Workspace';
+export * from './NavBranch';

package/src/hooks/actions.ts

@@ -0,0 +1,83 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Atom } from '@effect-atom/atom-react';
+import * as Effect from 'effect/Effect';
+
+import { type AppCapabilities, getCompanionVariant } from '@dxos/app-toolkit';
+import { Node } from '@dxos/plugin-graph';
+import { type ActionGraphProps } from '@dxos/react-ui-menu';
+import { byPosition } from '@dxos/util';
+
+import { type SimpleLayoutState } from '../types';
+
+// TODO(wittjosiah): Factor out to shared location with plugin-deck.
+export const PLANK_COMPANION_TYPE = 'org.dxos.plugin.deck.plank-companion';
+
+export type CompanionActionsConfig = {
+  /** Prefix for companion action IDs (e.g. 'navbar' or 'drawer') */
+  idPrefix: string;
+  /** Optional: highlight companion with this variant */
+  selectedVariant?: string;
+  /** State updater for toggling the drawer. */
+  updateState: (fn: (state: SimpleLayoutState) => SimpleLayoutState) => void;
+};
+
+/**
+ * Creates action graph nodes and edges for companion actions.
+ * Shared logic between useNavbarActions and useDrawerActions.
+ */
+// TODO(burdon): Use builder pattern.
+export const createCompanionActions = (
+  graph: AppCapabilities.AppGraph['graph'],
+  stateAtom: Atom.Atom<SimpleLayoutState>,
+  get: (atom: Atom.Atom<any>) => any,
+  config: CompanionActionsConfig,
+): Pick<ActionGraphProps, 'nodes' | 'edges'> => {
+  const { idPrefix, selectedVariant, updateState } = config;
+
+  // Derive activeId from state atom.
+  const state = get(stateAtom);
+  const activeId = state.active ?? state.workspace;
+
+  // Get companions from graph connections for activeId.
+  const activeConnections = activeId ? get(graph.connections(activeId, 'child')) : [];
+  const companions = activeConnections
+    .filter((node: Node.Node) => node.type === PLANK_COMPANION_TYPE)
+    .toSorted((a: Node.Node, b: Node.Node) => byPosition(a.properties, b.properties));
+
+  const nodes: ActionGraphProps['nodes'] = [];
+  const edges: ActionGraphProps['edges'] = [];
+
+  companions.forEach((companion: Node.Node) => {
+    const companionVariant = getCompanionVariant(companion.id);
+    const companionAction = {
+      id: `${idPrefix}-companion-${companion.id}`,
+      type: Node.ActionType,
+      properties: {
+        icon: companion.properties.icon ?? 'ph--placeholder--regular',
+        label: companion.properties.label,
+        iconOnly: true,
+        ...(selectedVariant !== undefined && {
+          variant: selectedVariant === companionVariant ? 'primary' : 'ghost',
+        }),
+      },
+      data: () =>
+        Effect.sync(() =>
+          updateState((current) => {
+            const closing = current.companionVariant === companionVariant && current.drawerState !== 'closed';
+            return {
+              ...current,
+              companionVariant: closing ? undefined : companionVariant,
+              drawerState: closing ? 'closed' : 'open',
+            };
+          }),
+        ),
+    };
+    nodes.push(companionAction);
+    edges.push({ source: 'root', target: companionAction.id, relation: 'child' });
+  });
+
+  return { nodes, edges };
+};

package/src/hooks/index.ts

@@ -2,5 +2,9 @@
 // Copyright 2025 DXOS.org
 //
 
+export * from './useAppBarProps';
 export * from './useCompanions';
+export * from './actions';
+export * from './useDrawerActions';
+export * from './useNavbarActions';
 export * from './useSimpleLayoutState';