@dxos/plugin-navtree 0.8.3-staging.0fa589b → 0.8.4-main.1068cf700f

package/src/components/Sidebar/L1Panel.tsx

@@ -2,71 +2,52 @@
 // Copyright 2025 DXOS.org
 //
 
+import * as Effect from 'effect/Effect';
 import React, { useCallback, useMemo } from 'react';
 
-import { type Node } from '@dxos/app-graph';
-import { Button, type ButtonProps, Icon, IconButton, toLocalizedString, useTranslation } from '@dxos/react-ui';
+import { Node } from '@dxos/app-graph';
+import { useActionRunner } from '@dxos/plugin-graph';
+import { DensityProvider, IconButton, ScrollArea, toLocalizedString, useTranslation } from '@dxos/react-ui';
 import { Tree } from '@dxos/react-ui-list';
+import { DropdownMenu, type MenuItem, MenuProvider } from '@dxos/react-ui-menu';
 import { Tabs } from '@dxos/react-ui-tabs';
-import { hoverableControlItem, hoverableOpenControlItem, mx } from '@dxos/react-ui-theme';
+import { hoverableControlItem, hoverableOpenControlItem } from '@dxos/ui-theme';
 
-import { useLoadDescendents } from '../../hooks';
-import { NAVTREE_PLUGIN } from '../../meta';
-import { l0ItemType } from '../../util';
+import { useIsAlternateTree, useLoadDescendents } from '../../hooks';
+import { meta } from '../../meta';
+import { NAV_TREE_ITEM } from '../NavTree';
 import { useNavTreeContext } from '../NavTreeContext';
-import { NavTreeItemColumns } from '../NavTreeItem';
-
-const headingBackButtonLabel = 'inset-0 min-is-0 truncate flex items-center pis-2';
-
-const TitleButton = ({ title, onClick }: { title: string } & Pick<ButtonProps, 'onClick'>) => {
-  return (
-    <Button
-      variant='ghost'
-      classNames='pli-1 flex-1 group text-start justify-start bs-[--rail-action] font-normal'
-      onClick={onClick}
-    >
-      <Icon icon='ph--caret-left--bold' size={3} />
-      <span className={mx(headingBackButtonLabel)}>{title}</span>
-    </Button>
-  );
-};
+import { NavTreeItemAction, NavTreeItemColumns } from '../NavTreeItem';
 
 export type L1PanelProps = {
   open?: boolean;
-  item: Node<any>;
   path: string[];
+  item: Node.Node;
   currentItemId: string;
   onBack?: () => void;
 };
 
-const L1Panel = ({ open, item, path, currentItemId, onBack }: L1PanelProps) => {
-  const { isAlternateTree, setAlternateTree, ...navTreeContext } = useNavTreeContext();
-  const { t } = useTranslation(NAVTREE_PLUGIN);
+/**
+ * Space or settings panel.
+ */
+export const L1Panel = ({ open, path, item, currentItemId, onBack }: L1PanelProps) => {
+  const { t } = useTranslation(meta.id);
+  const navTreeContext = useNavTreeContext();
+  const title = toLocalizedString(item.properties.label, t);
 
   // TODO(wittjosiah): Support multiple alternate trees.
-  const alternateTree = navTreeContext.useItems(item, { disposition: 'alternate-tree' })[0];
+  const { useItems } = navTreeContext;
+  const alternateTree = useItems(item, { disposition: 'alternate-tree' })[0];
   const alternatePath = useMemo(() => [...path, item.id], [item.id, path]);
-  const handleOpen = useCallback(() => setAlternateTree?.(alternatePath, true), [alternatePath, setAlternateTree]);
-  const isAlternate = isAlternateTree?.(alternatePath, item) ?? false;
+  const isAlternate = useIsAlternateTree(alternatePath, item);
   const useAlternateItems = useCallback(
-    (node?: Node, { disposition }: { disposition?: string } = {}) => {
+    (node?: Node.Node, { disposition }: { disposition?: string } = {}) => {
       // TODO(wittjosiah): Sorting is expensive, limit to necessary items for now.
-      return navTreeContext.useItems(node, { disposition, sort: node?.id === alternateTree.id });
+      return useItems(node, { disposition, sort: node?.id === alternateTree.id });
     },
-    [navTreeContext, alternateTree],
+    [alternateTree, useItems],
   );
 
-  const handleBack = useCallback(() => {
-    if (isAlternate) {
-      setAlternateTree?.(alternatePath, false);
-    } else {
-      onBack?.();
-    }
-  }, [isAlternate, onBack, alternatePath, setAlternateTree]);
-
-  const title = toLocalizedString(item.properties.label, t);
-  const backCapable = item.id.startsWith('!') || isAlternate;
-
   return (
     <Tabs.Tabpanel
       key={item.id}
@@ -79,97 +60,171 @@ const L1Panel = ({ open, item, path, currentItemId, onBack }: L1PanelProps) => {
       ]}
       tabIndex={-1}
       aria-label={title}
-      {...(!open && { inert: 'true' })}
+      {...(!open && { inert: true })}
     >
       {item.id === currentItemId && (
-        <>
-          <h2 className='flex items-center border-be border-subduedSeparator app-drag pli-1'>
-            {backCapable ? (
-              <TitleButton title={title} onClick={handleBack} />
-            ) : (
-              <span className='flex-1 truncate min-is-0 pis-6'>{title}</span>
-            )}
-            {alternateTree && !isAlternate && (
-              <IconButton
-                variant='ghost'
-                classNames={mx('shrink-0', hoverableControlItem, hoverableOpenControlItem, 'pli-2 pointer-fine:pli-1')}
-                iconOnly
-                size={5}
-                density='coarse'
-                icon={alternateTree.properties.icon ?? 'ph--placeholder--regular'}
-                label={toLocalizedString(alternateTree.properties.label ?? alternateTree.id, t)}
-                data-testid='treeView.alternateTreeButton'
-                onClick={handleOpen}
-              />
-            )}
-            <NavTreeItemColumns path={path} item={item} open density='coarse' />
-          </h2>
-          <div role='none' className='overflow-y-auto'>
-            {isAlternate ? (
-              <Tree
-                {...navTreeContext}
-                useItems={useAlternateItems}
-                id={alternateTree.id}
-                root={alternateTree}
-                path={alternatePath}
-                levelOffset={5}
-                gridTemplateColumns='[tree-row-start] 1fr min-content min-content min-content [tree-row-end]'
-                renderColumns={NavTreeItemColumns}
-              />
-            ) : (
-              <Tree
-                {...navTreeContext}
-                id={item.id}
-                root={item}
-                path={path}
-                levelOffset={5}
-                draggable
-                gridTemplateColumns='[tree-row-start] 1fr min-content min-content min-content [tree-row-end]'
-                renderColumns={NavTreeItemColumns}
-              />
-            )}
-          </div>
-        </>
+        <DensityProvider density='fine'>
+          <L1PanelHeader path={path} item={item} currentItemId={currentItemId} onBack={onBack} />
+          <ScrollArea.Root thin orientation='vertical'>
+            <ScrollArea.Viewport>
+              {isAlternate ? (
+                <Tree
+                  {...navTreeContext}
+                  id={alternateTree.id}
+                  root={alternateTree}
+                  path={alternatePath}
+                  levelOffset={5}
+                  gridTemplateColumns='[tree-row-start] 1fr min-content min-content min-content [tree-row-end]'
+                  renderColumns={NavTreeItemColumns}
+                  useItems={useAlternateItems}
+                />
+              ) : (
+                <Tree
+                  {...navTreeContext}
+                  id={item.id}
+                  root={item}
+                  path={path}
+                  levelOffset={5}
+                  gridTemplateColumns='[tree-row-start] 1fr min-content min-content min-content [tree-row-end]'
+                  renderColumns={NavTreeItemColumns}
+                  draggable
+                />
+              )}
+            </ScrollArea.Viewport>
+          </ScrollArea.Root>
+        </DensityProvider>
       )}
     </Tabs.Tabpanel>
   );
 };
 
-const L1PanelCollection = ({ item, path, ...props }: L1PanelProps) => {
-  const { useItems } = useNavTreeContext();
+/**
+ * Header row.
+ */
+const L1PanelHeader = ({ item, path, onBack }: L1PanelProps) => {
+  const { t } = useTranslation(meta.id);
+  const { renderItemEnd: ItemEnd } = useNavTreeContext();
+  const title = toLocalizedString(item.properties.label, t);
+
+  const { primaryAction, groupedActions, menuActions, onAction } = useL1MenuActions({ item, path });
   useLoadDescendents(item);
-  const collectionItems = useItems(item);
-  const groupPath = useMemo(() => [...path, item.id], [item.id, path]);
+
   return (
-    <>
-      {collectionItems
-        .filter((item) => l0ItemType(item) === 'tab')
-        .map((item) => (
-          <L1Panel key={item.id} item={item} path={groupPath} {...props} />
-        ))}
-    </>
+    <div className='flex is-full items-center border-be border-subduedSeparator app-drag density-coarse'>
+      <div className='is-6' />
+      <h2 className='flex-1 truncate min-is-0'>{title}</h2>
+      {/* TODO(wittjosiah): Reconcile with NavTreeItemColumns. */}
+      <div role='none' className='contents app-no-drag'>
+        {primaryAction?.properties?.disposition === 'list-item-primary' && !primaryAction?.properties?.disabled && (
+          <NavTreeItemAction
+            testId={primaryAction.properties?.testId}
+            label={toLocalizedString(primaryAction.properties?.label, t)}
+            icon={primaryAction.properties?.icon ?? 'ph--placeholder--regular'}
+            parent={item}
+            monolithic={Node.isAction(primaryAction)}
+            menuActions={Node.isAction(primaryAction) ? [primaryAction] : groupedActions[primaryAction?.id ?? '']}
+            menuType={primaryAction.properties?.menuType}
+            caller={NAV_TREE_ITEM}
+          />
+        )}
+        {menuActions.length === 1 && (
+          <IconButton
+            size={5}
+            density='coarse'
+            classNames={['shrink-0 pli-2 pointer-fine:pli-1', hoverableControlItem, hoverableOpenControlItem]}
+            variant='ghost'
+            icon={menuActions[0].properties?.icon ?? 'ph--placeholder--regular'}
+            iconOnly
+            label={toLocalizedString(menuActions[0].properties?.label, t)}
+            data-testid={menuActions[0].properties?.testId}
+            onClick={() => onAction(menuActions[0] as Node.Action)}
+          />
+        )}
+        {menuActions.length > 1 && (
+          <MenuProvider onAction={onAction}>
+            <DropdownMenu.Root group={item} items={menuActions as MenuItem[]} caller={NAV_TREE_ITEM}>
+              <DropdownMenu.Trigger asChild>
+                <IconButton
+                  size={5}
+                  density='coarse'
+                  classNames={['shrink-0 pli-2 pointer-fine:pli-1', hoverableControlItem, hoverableOpenControlItem]}
+                  variant='ghost'
+                  icon='ph--dots-three-vertical--regular'
+                  iconOnly
+                  label={t('tree item actions label')}
+                  data-testid='navtree.treeItem.actionsLevel0'
+                />
+              </DropdownMenu.Trigger>
+            </DropdownMenu.Root>
+          </MenuProvider>
+        )}
+        {ItemEnd && <ItemEnd node={item} open />}
+      </div>
+    </div>
   );
 };
 
-export type L1PanelsProps = Pick<L1PanelProps, 'open' | 'currentItemId' | 'onBack'> & {
-  topLevelItems: Node<any>[];
-  path: string[];
-};
+/**
+ * Builds the menu actions for the L1 panel header, combining graph actions with a synthetic settings/back action.
+ */
+const useL1MenuActions = ({ item, path }: Pick<L1PanelProps, 'item' | 'path'>) => {
+  const { t } = useTranslation(meta.id);
+  const { setAlternateTree, useActions, ...navTreeContext } = useNavTreeContext();
+  const runAction = useActionRunner();
 
-export const L1Panels = ({ topLevelItems, onBack, ...props }: L1PanelsProps) => {
-  return (
-    <>
-      {topLevelItems.map((item) => {
-        const type = l0ItemType(item);
-        switch (type) {
-          case 'collection':
-            return <L1PanelCollection key={item.id} item={item} {...props} />;
-          case 'tab':
-            return <L1Panel key={item.id} item={item} {...props} onBack={onBack} />;
-          default:
-            return null;
-        }
-      })}
-    </>
+  // TODO(wittjosiah): Support multiple alternate trees.
+  const alternateTree = navTreeContext.useItems(item, { disposition: 'alternate-tree' })[0];
+  const alternatePath = useMemo(() => [...path, item.id], [item.id, path]);
+  const isAlternate = useIsAlternateTree(alternatePath, item);
+
+  // Graph actions.
+  const { actions: _actions, groupedActions } = useActions(item);
+  const [primaryAction, ...secondaryActions] = _actions.toSorted((a, _b) =>
+    a.properties?.disposition === 'list-item-primary' ? -1 : 1,
   );
+
+  const graphMenuActions = (
+    primaryAction?.properties?.disposition === 'list-item-primary' ? secondaryActions : _actions
+  )
+    .flatMap((action) => (Node.isAction(action) ? [action] : []))
+    .filter((a) => ['list-item', 'list-item-primary'].includes(a.properties?.disposition));
+
+  // Synthetic settings/back action.
+  const settingsActionId = `${item.id}~settings`;
+  const settingsAction = useMemo((): Node.Action | undefined => {
+    if (!alternateTree) {
+      return undefined;
+    }
+    return {
+      id: settingsActionId,
+      type: Node.ActionType,
+      data: () => Effect.void,
+      properties: {
+        label: isAlternate ? ['button back', { ns: meta.id }] : (alternateTree.properties.label ?? alternateTree.id),
+        icon: isAlternate
+          ? 'ph--arrow-u-down-left--regular'
+          : (alternateTree.properties.icon ?? 'ph--placeholder--regular'),
+        disposition: 'list-item',
+        testId: isAlternate ? 'navtree.backToSpace' : 'navtree.spaceSettings',
+      },
+    } as Node.Action;
+  }, [alternateTree, isAlternate, settingsActionId, t]);
+
+  const menuActions = useMemo(
+    () => [...graphMenuActions, ...(settingsAction ? [settingsAction] : [])],
+    [graphMenuActions, settingsAction],
+  );
+
+  const onAction = useCallback(
+    (action: Node.Action, params?: Node.InvokeProps) => {
+      if (action.id === settingsActionId) {
+        setAlternateTree?.(alternatePath, !isAlternate);
+      } else {
+        void runAction(action, params);
+      }
+    },
+    [settingsActionId, setAlternateTree, alternatePath, isAlternate, runAction],
+  );
+
+  return { primaryAction, groupedActions, menuActions, onAction };
 };

package/src/components/Sidebar/L1Tabs.tsx

@@ -0,0 +1,33 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React from 'react';
+
+import { type Node } from '@dxos/app-graph';
+
+import { l0ItemType } from '../../util';
+
+import { L1Panel, type L1PanelProps } from './L1Panel';
+
+export type L1TabsProps = Pick<L1PanelProps, 'open' | 'currentItemId' | 'onBack'> & {
+  path: string[];
+  topLevelItems: Node.Node[];
+};
+
+/**
+ * Each workspace is an L1 tab.
+ */
+export const L1Tabs = ({ topLevelItems, onBack, ...props }: L1TabsProps) => {
+  return (
+    <>
+      {topLevelItems.map((item) => {
+        const type = l0ItemType(item);
+        if (type === 'tab') {
+          return <L1Panel key={item.id} item={item} {...props} onBack={onBack} />;
+        }
+        return null;
+      })}
+    </>
+  );
+};

package/src/components/Sidebar/index.ts

@@ -4,3 +4,4 @@
 
 export * from './L0Menu';
 export * from './L1Panel';
+export * from './L1Tabs';

package/src/components/UserAccountAvatar/UserAccountAvatar.stories.tsx

@@ -2,20 +2,21 @@
 // Copyright 2023 DXOS.org
 //
 
-import '@dxos-theme';
+import { type Meta, type StoryObj } from '@storybook/react-vite';
 
-import { type Meta } from '@storybook/react';
-
-import { withTheme } from '@dxos/storybook-utils';
+import { withTheme } from '@dxos/react-ui/testing';
 
 import { UserAccountAvatar } from './UserAccountAvatar';
 
-const meta: Meta<typeof UserAccountAvatar> = {
+const meta = {
   title: 'plugins/plugin-navtree/UserAccountAvatar',
+
+  decorators: [withTheme()],
   component: UserAccountAvatar,
-  decorators: [withTheme],
-};
+} satisfies Meta<typeof UserAccountAvatar>;
 
 export default meta;
 
-export const Default = {};
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};

package/src/components/UserAccountAvatar/UserAccountAvatar.tsx

@@ -7,6 +7,8 @@ import React from 'react';
 import { Avatar, type AvatarStatus, type Size } from '@dxos/react-ui';
 import { hexToFallback } from '@dxos/util';
 
+import { L0ItemActiveTabIndicator } from '../Sidebar';
+
 export type UserAccountAvatarProps = {
   size?: Size;
   userId?: string;
@@ -19,17 +21,23 @@ export const UserAccountAvatar = ({ size, userId, hue, emoji, status }: UserAcco
   const fallbackValue = hexToFallback(userId ?? '0');
 
   return (
-    <div className='grid place-items-center' data-joyride='welcome/account'>
-      <Avatar.Root>
-        <Avatar.Content
-          variant='circle'
-          size={size ?? 12}
-          status={status ?? 'active'}
-          hue={hue || fallbackValue.hue}
-          fallback={emoji || fallbackValue.emoji}
-          data-testid='treeView.userAccount'
-        />
-      </Avatar.Root>
-    </div>
+    <>
+      <L0ItemActiveTabIndicator classNames='inset-block-6' />
+      <div
+        className='grid place-items-center dx-focus-ring-group-indicator rounded-full'
+        data-joyride='welcome/account'
+      >
+        <Avatar.Root>
+          <Avatar.Content
+            variant='circle'
+            size={size ?? 12}
+            status={status ?? 'active'}
+            hue={hue || fallbackValue.hue}
+            fallback={emoji || fallbackValue.emoji}
+            data-testid='treeView.userAccount'
+          />
+        </Avatar.Root>
+      </div>
+    </>
   );
 };

package/src/components/index.ts

@@ -7,4 +7,5 @@ export * from './NavTree';
 export * from './NavTreeContainer';
 export * from './NavTreeContext';
 export * from './NavTreeDocumentTitle';
-export * from './types';
+
+export type * from './types';

package/src/components/types.ts

@@ -4,33 +4,34 @@
 
 import type { FC } from 'react';
 
-import type { Node } from '@dxos/app-graph';
+import { type Node } from '@dxos/app-graph';
 import type { Density } from '@dxos/react-ui';
 import type { TreeProps } from '@dxos/react-ui-list';
 import type { MaybePromise } from '@dxos/util';
 
-import type { L1PanelProps } from './Sidebar';
 import type { FlattenedActions, NavTreeItemGraphNode } from '../types';
 
+import type { L1PanelProps } from './Sidebar';
+
 export type NavTreeContextValue = Pick<
   TreeProps<NavTreeItemGraphNode, { disposition?: string; sort?: boolean }>,
-  'useItems' | 'getProps' | 'isCurrent' | 'isOpen' | 'canDrop' | 'onOpenChange' | 'onSelect'
+  'useItems' | 'getProps' | 'useIsCurrent' | 'useIsOpen' | 'blockInstruction' | 'canDrop' | 'onOpenChange' | 'onSelect'
 > &
   Pick<L1PanelProps, 'onBack'> & {
     tab: string;
     topbar?: boolean;
     popoverAnchorId?: string;
-    renderItemEnd?: FC<{ node: Node; open: boolean }>;
-    getActions: (node: Node) => FlattenedActions;
-    loadDescendents?: (node: Node) => MaybePromise<void>;
-    isAlternateTree?: (path: string[], item: NavTreeItemGraphNode) => boolean;
+    renderItemEnd?: FC<{ node: Node.Node; open: boolean }>;
+    useActions: (node: Node.Node) => FlattenedActions;
+    loadDescendents?: (node: Node.Node) => MaybePromise<void>;
+    useIsAlternateTree?: (path: string[], item: NavTreeItemGraphNode) => boolean;
     setAlternateTree?: (path: string[], open: boolean) => void;
     onTabChange?: (node: NavTreeItemGraphNode) => void;
   };
 
 export type NavTreeItemColumnsProps = {
   path: string[];
-  item: Node;
+  item: Node.Node;
   open: boolean;
   density?: Density;
 };