@dxos/plugin-simple-layout 0.0.0 → 0.8.4-main.03d5cd7b56

package/src/components/Popover/Popover.tsx

@@ -5,10 +5,13 @@
 import { createContext } from '@radix-ui/react-context';
 import React, { type PropsWithChildren, useCallback, useEffect, useMemo, useRef, useState } from 'react';
 
-import { Surface, useCapability } from '@dxos/app-framework/react';
-import { Popover, type PopoverContentInteractOutsideEvent } from '@dxos/react-ui';
+import { Surface } from '@dxos/app-framework/ui';
+import { AppSurface } from '@dxos/app-toolkit/ui';
+import { Popover, type PopoverContentInteractOutsideEvent, toLocalizedString, useTranslation } from '@dxos/react-ui';
+import { Card } from '@dxos/react-ui';
 
-import { SimpleLayoutState } from '../../types';
+import { useSimpleLayoutState } from '#hooks';
+import { meta } from '#meta';
 
 const DEBOUNCE_DELAY = 40;
 
@@ -19,7 +22,7 @@ type LayoutPopoverContextValue = {
 const [LayoutPopoverProvider, useLayoutPopoverContext] = createContext<LayoutPopoverContextValue>('LayoutPopover');
 
 export const PopoverRoot = ({ children }: PropsWithChildren) => {
-  const layout = useCapability(SimpleLayoutState);
+  const { state } = useSimpleLayoutState();
   const [open, setOpen] = useState(false);
   const virtualRef = useRef<HTMLButtonElement | null>(null);
   const [virtualIter, setVirtualIter] = useState(0);
@@ -29,22 +32,22 @@ export const PopoverRoot = ({ children }: PropsWithChildren) => {
   //  the anchor further down the tree or measuring the virtual trigger's client rect.
   useEffect(() => {
     setOpen(false);
-    if (layout.popoverOpen) {
+    if (state.popoverOpen) {
       if (debounceRef.current) {
         clearTimeout(debounceRef.current);
       }
-      if (layout.popoverAnchor && virtualRef.current !== layout.popoverAnchor) {
-        virtualRef.current = layout.popoverAnchor ?? null;
+      if (state.popoverAnchor && virtualRef.current !== state.popoverAnchor) {
+        virtualRef.current = state.popoverAnchor ?? null;
         setVirtualIter((iter) => iter + 1);
       }
       debounceRef.current = setTimeout(() => setOpen(true), DEBOUNCE_DELAY);
     }
-  }, [layout.popoverOpen, layout.popoverAnchorId, layout.popoverAnchor, layout.popoverContent]);
+  }, [state.popoverOpen, state.popoverAnchorId, state.popoverAnchor, state.popoverContent]);
 
   return (
     <LayoutPopoverProvider setOpen={setOpen}>
       <Popover.Root modal={false} open={open}>
-        {layout.popoverAnchor && <Popover.VirtualTrigger key={virtualIter} virtualRef={virtualRef} />}
+        {state.popoverAnchor && <Popover.VirtualTrigger key={virtualIter} virtualRef={virtualRef} />}
         {children}
       </Popover.Root>
     </LayoutPopoverProvider>
@@ -52,10 +55,21 @@ export const PopoverRoot = ({ children }: PropsWithChildren) => {
 };
 
 export const PopoverContent = () => {
-  const layout = useCapability(SimpleLayoutState);
+  const { t } = useTranslation(meta.id);
+  const { state, updateState } = useSimpleLayoutState();
   const { setOpen } = useLayoutPopoverContext('PopoverContent');
+  const handleClose = useCallback(() => {
+    setOpen(false);
+    updateState((s) => ({
+      ...s,
+      popoverOpen: false,
+      popoverAnchor: undefined,
+      popoverAnchorId: undefined,
+      popoverSide: undefined,
+    }));
+  }, [setOpen, updateState]);
 
-  const handleClose = useCallback(
+  const handleInteractOutside = useCallback(
     (event: KeyboardEvent | PopoverContentInteractOutsideEvent) => {
       if (
         // TODO(thure): CodeMirror should not focus itself when it updates.
@@ -64,36 +78,44 @@ export const PopoverContent = () => {
       ) {
         event.preventDefault();
       } else {
-        setOpen(false);
-        layout.popoverOpen = false;
-        layout.popoverAnchor = undefined;
-        layout.popoverAnchorId = undefined;
-        layout.popoverSide = undefined;
+        handleClose();
       }
     },
-    [setOpen],
+    [handleClose],
   );
 
   const collisionBoundaries: HTMLElement[] = useMemo(() => {
-    const closest = layout.popoverAnchor?.closest('[data-popover-collision-boundary]') as
-      | HTMLElement
-      | null
-      | undefined;
+    const closest = state.popoverAnchor?.closest('[data-popover-collision-boundary]') as HTMLElement | null | undefined;
     return closest ? [closest] : [];
-  }, [layout.popoverAnchor]);
+  }, [state.popoverAnchor]);
 
   return (
     <Popover.Portal>
       <Popover.Content
-        side={layout.popoverSide}
-        onInteractOutside={handleClose}
-        onEscapeKeyDown={handleClose}
-        collisionBoundary={collisionBoundaries}
+        side={state.popoverSide}
         sticky='always'
         hideWhenDetached
+        collisionBoundary={collisionBoundaries}
+        onInteractOutside={handleInteractOutside}
+        onEscapeKeyDown={handleInteractOutside}
       >
         <Popover.Viewport>
-          <Surface role='card--popover' data={layout.popoverContent} limit={1} />
+          {state.popoverKind === 'base' && state.popoverContent && 'component' in state.popoverContent && (
+            <Surface.Surface type={AppSurface.Popover} data={state.popoverContent} limit={1} />
+          )}
+          {state.popoverKind === 'card' && (
+            <Card.Root border={false} classNames='dx-card-popover'>
+              <Card.Toolbar>
+                {/* TODO(wittjosiah): Cleaner way to handle no drag handle in toolbar? */}
+                <span />
+                {state.popoverTitle ? <Card.Title>{toLocalizedString(state.popoverTitle, t)}</Card.Title> : <span />}
+                <Card.CloseIconButton onClick={handleClose} />
+              </Card.Toolbar>
+              {state.popoverContent && 'subject' in state.popoverContent && (
+                <Surface.Surface type={AppSurface.Card} data={state.popoverContent} limit={1} />
+              )}
+            </Card.Root>
+          )}
         </Popover.Viewport>
         <Popover.Arrow />
       </Popover.Content>

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

@@ -0,0 +1,144 @@
+//
+// 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 { type ActionGraphProps, createMenuAction } from '@dxos/react-ui-menu';
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+import { withRegistry } from '@dxos/storybook-utils';
+
+import { translations } from '#translations';
+
+import { MobileLayout } from '../MobileLayout';
+import { AppBar, type AppBarProps } from './AppBar';
+
+const buildEmptyActions = (): ActionGraphProps => ({ nodes: [], edges: [] });
+
+const buildDefaultActions = (): ActionGraphProps => {
+  const result: ActionGraphProps = { nodes: [], edges: [] };
+  const actions = [
+    createMenuAction('action-edit.menu', () => console.log('Edit'), {
+      icon: 'ph--pencil--regular',
+      label: 'Edit',
+    }),
+    createMenuAction('action-share.menu', () => console.log('Share'), {
+      icon: 'ph--share--regular',
+      label: 'Share',
+    }),
+    createMenuAction('action-delete.menu', () => console.log('Delete'), {
+      icon: 'ph--trash--regular',
+      label: 'Delete',
+    }),
+  ];
+  result.nodes.push(...actions);
+  result.edges.push(...actions.map((a) => ({ source: 'root', target: a.id, relation: 'child' })));
+  return result;
+};
+
+type DefaultStoryProps = Omit<AppBarProps, 'actions'> & {
+  actions: ActionGraphProps;
+};
+
+const DefaultStory = ({ actions: actionsProp, ...props }: DefaultStoryProps) => {
+  const actions = useMemo(() => Atom.make(actionsProp).pipe(Atom.keepAlive), [actionsProp]);
+  return (
+    <MobileLayout.Root>
+      <AppBar {...props} actions={actions} />
+    </MobileLayout.Root>
+  );
+};
+
+const meta = {
+  title: 'plugins/plugin-simple-layout/components/AppBar',
+  render: DefaultStory,
+  decorators: [
+    withTheme(),
+    withLayout({
+      layout: 'column',
+      classNames: 'relative',
+    }),
+    withRegistry,
+  ],
+  parameters: {
+    layout: 'fullscreen',
+    translations,
+  },
+} satisfies Meta<typeof DefaultStory>;
+
+export default meta;
+
+type Story = StoryObj<DefaultStoryProps>;
+
+export const Default: Story = {
+  tags: ['test'],
+  args: {
+    actions: buildDefaultActions(),
+    title: 'Document Title',
+    showBackButton: true,
+    onAction: fn(),
+    onBack: fn(),
+  },
+  play: async ({ args, canvasElement }) => {
+    const canvas = within(canvasElement);
+
+    // Verify the banner renders with the correct title.
+    await expect(canvas.getByRole('banner')).toBeInTheDocument();
+    await expect(canvas.getByText('Document Title')).toBeInTheDocument();
+
+    // Test back button click.
+    const backButton = canvas.getByRole('button', { name: /back/i });
+    await expect(backButton).toBeInTheDocument();
+    await userEvent.click(backButton);
+    await expect(args.onBack).toHaveBeenCalledTimes(1);
+
+    // Test actions menu opens and action fires.
+    const menuTrigger = canvas.getByRole('button', { name: /actions/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 editAction = await screen.findByRole('menuitem', { name: /edit/i });
+    await userEvent.click(editAction);
+    await expect(args.onAction).toHaveBeenCalledTimes(1);
+    await expect((args.onAction as Mock).mock.calls[0][0]).toHaveProperty('id', 'action-edit.menu');
+  },
+};
+
+export const NoBackButton: Story = {
+  args: {
+    actions: buildDefaultActions(),
+    title: 'Home',
+    showBackButton: false,
+    onAction: (action) => console.log('Action:', action.id),
+  },
+};
+
+export const LongTitle: Story = {
+  args: {
+    actions: buildDefaultActions(),
+    title: 'This is a very long document title that should be truncated when it exceeds the available space',
+    showBackButton: true,
+    onBack: () => console.log('Back clicked'),
+    onAction: (action) => console.log('Action:', action.id),
+  },
+};
+
+export const NoActions: Story = {
+  args: {
+    actions: buildEmptyActions(),
+    title: 'Empty Document',
+    showBackButton: true,
+    onBack: () => console.log('Back clicked'),
+    onAction: (action) => console.log('Action:', action.id),
+  },
+};
+
+export const Empty: Story = {
+  args: {
+    actions: buildEmptyActions(),
+  },
+};

package/src/components/SimpleLayout/AppBar.tsx

@@ -0,0 +1,94 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Atom, useAtomValue } from '@effect-atom/atom-react';
+import React, { Fragment } from 'react';
+
+import { IconButton, Popover, Toolbar, useTranslation } from '@dxos/react-ui';
+import { type ActionExecutor, type ActionGraphProps, Menu, useMenuActions } from '@dxos/react-ui-menu';
+import { composable, composableProps, osTranslations } from '@dxos/ui-theme';
+
+import { meta } from '#meta';
+
+import { useMobileLayout } from '../MobileLayout';
+
+const APP_BAR_NAME = 'SimpleLayout.AppBar';
+
+export type AppBarProps = {
+  /** Title/label to display in the banner. */
+  title?: string;
+  /** Action graph atom for the dropdown menu. */
+  actions: Atom.Atom<ActionGraphProps>;
+  /** Whether to show the back button. */
+  showBackButton?: boolean;
+  /** Popover anchor ID for the dropdown trigger. */
+  popoverAnchorId?: string;
+  /** Action executor callback. */
+  onAction?: ActionExecutor;
+  /** Callback when back button is clicked. */
+  onBack?: () => void;
+};
+
+/**
+ * AppBar component that renders a title, optional back button, and actions dropdown.
+ */
+export const AppBar = composable<HTMLDivElement, AppBarProps>(
+  ({ classNames, title, actions, showBackButton, popoverAnchorId, onAction, onBack, ...props }, forwardedRef) => {
+    const { t } = useTranslation(meta.id);
+    const menuActions = useMenuActions(actions);
+    const actionsValue = useAtomValue(actions);
+    const hasActions = actionsValue.nodes.length > 0;
+    const { keyboardOpen } = useMobileLayout(APP_BAR_NAME);
+
+    // Fall back to app name if no title provided.
+    const displayTitle = title ?? t('current-app.name', { ns: osTranslations });
+
+    // Wrap the menu trigger with Popover.Anchor when the popoverAnchorId is set.
+    const AnchorRoot = popoverAnchorId ? Popover.Anchor : Fragment;
+
+    return (
+      <Toolbar.Root
+        {...composableProps(props, {
+          role: 'banner',
+          classNames: 'grid grid-cols-[var(--dx-rail-size)_1fr_var(--dx-rail-size)] items-center dx-density-fine',
+        })}
+        ref={forwardedRef}
+      >
+        {keyboardOpen ? (
+          <IconButton variant='ghost' icon='ph--x--regular' iconOnly label={t('done.label')} />
+        ) : showBackButton ? (
+          <IconButton
+            variant='ghost'
+            icon='ph--caret-left--regular'
+            iconOnly
+            label={t('back.label')}
+            onClick={onBack}
+          />
+        ) : (
+          <div />
+        )}
+        <h1 className='text-center truncate font-thin uppercase'>{displayTitle}</h1>
+        {hasActions ? (
+          <AnchorRoot>
+            <Menu.Root {...menuActions} caller={meta.id} onAction={onAction}>
+              <Menu.Trigger asChild>
+                <IconButton
+                  variant='ghost'
+                  icon='ph--dots-three-vertical--regular'
+                  iconOnly
+                  label={t('actions-menu.label')}
+                />
+              </Menu.Trigger>
+              <Menu.Content />
+            </Menu.Root>
+          </AnchorRoot>
+        ) : (
+          <span />
+        )}
+      </Toolbar.Root>
+    );
+  },
+);
+
+AppBar.displayName = APP_BAR_NAME;

package/src/components/SimpleLayout/Drawer.tsx

@@ -0,0 +1,104 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React, { useMemo } from 'react';
+
+import { Surface } from '@dxos/app-framework/ui';
+import { AppSurface, useAppGraph } from '@dxos/app-toolkit/ui';
+import { type Node, useNode } from '@dxos/plugin-graph';
+import { ErrorFallback, Panel } from '@dxos/react-ui';
+import { getLinkedVariant } from '@dxos/react-ui-attention';
+import { Menu, useMenuActions } from '@dxos/react-ui-menu';
+
+import { useCompanions, useDrawerActions, useSimpleLayoutState } from '#hooks';
+
+import { Loading } from '../Loading';
+
+const DRAWER_NAME = 'SimpleLayout.Drawer';
+
+/**
+ * Companion drawer component.
+ */
+export const Drawer = () => {
+  const { graph } = useAppGraph();
+  const { state: layoutState } = useSimpleLayoutState();
+
+  const placeholder = useMemo(() => <Loading />, []);
+
+  // Get all companions for the current active (primary) item.
+  const activeId = layoutState.active ?? layoutState.workspace;
+  const companions = useCompanions(activeId);
+  const { companionId, variant } = useSelectedCompanion(companions, layoutState.companionVariant);
+
+  // Get node for the selected companion.
+  const node = useNode(graph, companionId);
+  const parentNode = useNode(graph, activeId);
+
+  // Build Surface data for the companion content.
+  const data = useMemo<AppSurface.ArticleData | undefined>(() => {
+    if (!node || !companionId) {
+      return undefined;
+    }
+    return {
+      attendableId: companionId,
+      subject: node.data,
+      companionTo: parentNode?.data,
+      properties: node.properties,
+      variant,
+    };
+  }, [companionId, node, parentNode, variant]);
+
+  // Get drawer actions (tabs + toolbar buttons).
+  const { actions, onAction } = useDrawerActions(DRAWER_NAME);
+  const menuActions = useMenuActions(actions);
+
+  return (
+    <Panel.Root>
+      <Panel.Toolbar>
+        <Menu.Root {...menuActions} alwaysActive onAction={onAction}>
+          <Menu.Toolbar />
+        </Menu.Root>
+      </Panel.Toolbar>
+      <Panel.Content>
+        <Surface.Surface
+          type={AppSurface.Article}
+          data={data}
+          limit={1}
+          fallback={ErrorFallback}
+          placeholder={placeholder}
+        />
+      </Panel.Content>
+    </Panel.Root>
+  );
+};
+
+Drawer.displayName = DRAWER_NAME;
+
+/**
+ * Resolves which companion to show based on variant preference.
+ * Falls back to first available if preferred variant not available.
+ */
+const useSelectedCompanion = (companions: Node.Node[], preferredVariant?: string) => {
+  const selectedCompanion = useMemo(() => {
+    if (companions.length === 0) {
+      return undefined;
+    }
+
+    // Try to find companion matching the preferred variant.
+    if (preferredVariant) {
+      const preferred = companions.find((c) => getLinkedVariant(c.id) === preferredVariant);
+      if (preferred) {
+        return preferred;
+      }
+    }
+
+    // Fallback to first companion.
+    return companions[0];
+  }, [companions, preferredVariant]);
+
+  const companionId = selectedCompanion?.id;
+  const variant = companionId ? getLinkedVariant(companionId) : undefined;
+
+  return { selectedCompanion, companionId, variant };
+};

package/src/components/SimpleLayout/Main.tsx

@@ -2,84 +2,77 @@
 // Copyright 2025 DXOS.org
 //
 
-import React, { Activity, useMemo } from 'react';
+import React, { useMemo } from 'react';
 
-import { Surface, useAppGraph, useCapability } from '@dxos/app-framework/react';
+import { Surface } from '@dxos/app-framework/ui';
+import { AppSurface, useAppGraph } from '@dxos/app-toolkit/ui';
 import { useNode } from '@dxos/plugin-graph';
-import { Main as NaturalMain } from '@dxos/react-ui';
-import { ATTENDABLE_PATH_SEPARATOR } from '@dxos/react-ui-attention';
-import { mx } from '@dxos/ui-theme';
+import { ErrorFallback, Panel } from '@dxos/react-ui';
+import { useAttentionAttributes } from '@dxos/react-ui-attention';
 
-import { SimpleLayoutState } from '../../types';
-import { ContentError } from '../ContentError';
-import { ContentLoading } from '../ContentLoading';
-import { Home } from '../Home';
+import { useAppBarProps, useNavbarActions, useSimpleLayoutState } from '#hooks';
 
-import { Banner } from './Banner';
+import { useExpandPath } from '../hooks';
+import { Loading } from '../Loading';
+import { useMobileLayout } from '../MobileLayout';
+import { AppBar } from './AppBar';
 import { NavBar } from './NavBar';
 
+const MAIN_NAME = 'SimpleLayout.Main';
+
+/**
+ * Main content component.
+ */
 export const Main = () => {
-  const layout = useCapability(SimpleLayoutState);
-  const id = layout.active ?? layout.workspace;
-  const { graph } = useAppGraph();
-  const node = useNode(graph, id);
+  const { state } = useSimpleLayoutState();
+  const id = state.active ?? state.workspace;
+  const attentionAttrs = useAttentionAttributes(id);
+  const { keyboardOpen } = useMobileLayout(MAIN_NAME);
+  const { actions, onAction } = useNavbarActions();
+  const appBarProps = useAppBarProps();
 
-  const placeholder = useMemo(() => <ContentLoading />, []);
+  const placeholder = useMemo(() => <Loading />, []);
 
-  const { variant } = parseEntryId(id);
-  const data = useMemo(
-    () =>
+  const { graph } = useAppGraph();
+  const node = useNode(graph, id);
+  const data = useMemo(() => {
+    return (
       node && {
         attendableId: id,
         subject: node.data,
         properties: node.properties,
-        variant,
-        popoverAnchorId: layout.popoverAnchorId,
-      },
-    [node, node?.data, node?.properties, layout.popoverAnchorId, variant, id],
-  );
+        popoverAnchorId: state.popoverAnchorId,
+      }
+    );
+  }, [id, node, node?.data, node?.properties, state.popoverAnchorId]);
 
-  const handleActiveIdChange = (nextActiveId: string | null) => {
-    // eslint-disable-next-line no-console
-    console.log('[navigate]', nextActiveId);
-  };
+  useExpandPath(id);
 
-  const showNavBar = !layout.isPopover;
+  // 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.Root complementarySidebarState='closed' navigationSidebarState='closed'>
-      <NaturalMain.Content bounce classNames='dx-mobile-main dx-mobile-main-scroll-area--flush !overflow-y-auto'>
-        <div
-          className={mx(
-            'bs-full overflow-hidden grid',
-            showNavBar ? 'grid-rows-[min-content_1fr_min-content]' : 'grid-rows-[min-content_1fr]',
-          )}
-        >
-          <Banner node={node} />
-          <Activity mode={id === 'default' ? 'visible' : 'hidden'}>
-            <Home />
-          </Activity>
-          <Activity mode={id !== 'default' ? 'visible' : 'hidden'}>
-            <section>
-              <Surface
-                key={id}
-                role='article'
-                data={data}
-                limit={1}
-                fallback={ContentError}
-                placeholder={placeholder}
-              />
-            </section>
-          </Activity>
-          {showNavBar && <NavBar activeId={id} onActiveIdChange={handleActiveIdChange} />}
-        </div>
-      </NaturalMain.Content>
-    </NaturalMain.Root>
+    <Panel.Root {...attentionAttrs} className='dx-document'>
+      <Panel.Toolbar asChild>
+        <AppBar {...appBarProps} />
+      </Panel.Toolbar>
+      <Panel.Content role='article' className='bg-base-surface'>
+        <Surface.Surface
+          key={id}
+          type={AppSurface.Article}
+          data={data}
+          limit={1}
+          fallback={ErrorFallback}
+          placeholder={placeholder}
+        />
+      </Panel.Content>
+      {showNavBar && (
+        <Panel.Statusbar asChild>
+          <NavBar actions={actions} onAction={onAction} />
+        </Panel.Statusbar>
+      )}
+    </Panel.Root>
   );
 };
 
-// TODO(wittjosiah): Factor out. Copied from deck plugin.
-const parseEntryId = (entryId: string) => {
-  const [id, variant] = entryId.split(ATTENDABLE_PATH_SEPARATOR);
-  return { id, variant };
-};
+Main.displayName = MAIN_NAME;