@dxos/plugin-navtree 0.8.4-main.1da679c → 0.8.4-main.21d9917

package/src/components/Sidebar/L1Panel.tsx

@@ -5,11 +5,12 @@
 import React, { useCallback, useMemo } from 'react';
 
 import { type Node } from '@dxos/app-graph';
-import { IconButton, toLocalizedString, useTranslation } from '@dxos/react-ui';
+import { DensityProvider, IconButton, toLocalizedString, useTranslation } from '@dxos/react-ui';
 import { Tree } from '@dxos/react-ui-list';
 import { Tabs } from '@dxos/react-ui-tabs';
-import { hoverableControlItem, hoverableOpenControlItem } from '@dxos/react-ui-theme';
+import { hoverableControlItem, hoverableOpenControlItem } from '@dxos/ui-theme';
 
+import { useIsAlternateTree } from '../../hooks';
 import { meta } from '../../meta';
 import { useNavTreeContext } from '../NavTreeContext';
 import { NavTreeItemColumns } from '../NavTreeItem';
@@ -17,7 +18,7 @@ import { NavTreeItemColumns } from '../NavTreeItem';
 export type L1PanelProps = {
   open?: boolean;
   path: string[];
-  item: Node<any>;
+  item: Node.Node;
   currentItemId: string;
   onBack?: () => void;
 };
@@ -27,17 +28,16 @@ export type L1PanelProps = {
  */
 export const L1Panel = ({ open, path, item, currentItemId, onBack }: L1PanelProps) => {
   const { t } = useTranslation(meta.id);
-  const { isAlternateTree, ...navTreeContext } = useNavTreeContext();
-  // NOTE(burdon): I'm very uneasy about this pattern of declaring hooks as context props.
-  const { useItems } = navTreeContext;
+  const navTreeContext = useNavTreeContext();
   const title = toLocalizedString(item.properties.label, t);
 
   // TODO(wittjosiah): Support multiple alternate trees.
+  const { useItems } = navTreeContext;
   const alternateTree = useItems(item, { disposition: 'alternate-tree' })[0];
   const alternatePath = useMemo(() => [...path, item.id], [item.id, path]);
-  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 useItems(node, { disposition, sort: node?.id === alternateTree.id });
     },
@@ -56,22 +56,22 @@ export const L1Panel = ({ open, path, item, currentItemId, onBack }: L1PanelProp
       ]}
       tabIndex={-1}
       aria-label={title}
-      {...(!open && { inert: 'true' })}
+      {...(!open && { inert: true })}
     >
       {item.id === currentItemId && (
-        <>
+        <DensityProvider density='fine'>
           <L1PanelHeader path={path} item={item} currentItemId={currentItemId} onBack={onBack} />
           <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}
+                useItems={useAlternateItems}
               />
             ) : (
               <Tree
@@ -80,13 +80,13 @@ export const L1Panel = ({ open, path, item, currentItemId, onBack }: L1PanelProp
                 root={item}
                 path={path}
                 levelOffset={5}
-                draggable
                 gridTemplateColumns='[tree-row-start] 1fr min-content min-content min-content [tree-row-end]'
                 renderColumns={NavTreeItemColumns}
+                draggable
               />
             )}
           </div>
-        </>
+        </DensityProvider>
       )}
     </Tabs.Tabpanel>
   );
@@ -97,13 +97,13 @@ export const L1Panel = ({ open, path, item, currentItemId, onBack }: L1PanelProp
  */
 const L1PanelHeader = ({ item, path, onBack }: L1PanelProps) => {
   const { t } = useTranslation(meta.id);
-  const { isAlternateTree, setAlternateTree, ...navTreeContext } = useNavTreeContext();
+  const { setAlternateTree, ...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 alternatePath = useMemo(() => [...path, item.id], [item.id, path]);
-  const isAlternate = isAlternateTree?.(alternatePath, item) ?? false;
+  const isAlternate = useIsAlternateTree(alternatePath, item);
   const backCapable = item.id.startsWith('!') || isAlternate;
 
   const handleOpen = useCallback(() => {
@@ -125,10 +125,10 @@ const L1PanelHeader = ({ item, path, onBack }: L1PanelProps) => {
       <h2 className='flex-1 truncate min-is-0'>{title}</h2>
       {(backCapable && (
         <IconButton
+          data-testid='treeView.primaryTreeButton'
           variant='ghost'
           icon='ph--arrow-u-down-left--regular'
           iconOnly
-          size={5}
           label={t('button back')}
           classNames={[hoverableControlItem, hoverableOpenControlItem, 'pointer-fine:pli-1']}
           onClick={handleBack}
@@ -140,7 +140,6 @@ const L1PanelHeader = ({ item, path, onBack }: L1PanelProps) => {
             variant='ghost'
             icon={alternateTree.properties.icon ?? 'ph--placeholder--regular'}
             iconOnly
-            size={5}
             label={toLocalizedString(alternateTree.properties.label ?? alternateTree.id, t)}
             classNames={[hoverableControlItem, hoverableOpenControlItem, 'pointer-fine:pli-1']}
             onClick={handleOpen}

package/src/components/Sidebar/L1Tabs.tsx

@@ -2,57 +2,32 @@
 // Copyright 2025 DXOS.org
 //
 
-import React, { useMemo } from 'react';
+import React from 'react';
 
 import { type Node } from '@dxos/app-graph';
 
-import { useLoadDescendents } from '../../hooks';
 import { l0ItemType } from '../../util';
-import { useNavTreeContext } from '../NavTreeContext';
 
 import { L1Panel, type L1PanelProps } from './L1Panel';
 
 export type L1TabsProps = Pick<L1PanelProps, 'open' | 'currentItemId' | 'onBack'> & {
   path: string[];
-  topLevelItems: Node<any>[];
+  topLevelItems: Node.Node[];
 };
 
 /**
- * Each space is an L1 tab.
+ * Each workspace is an L1 tab.
  */
 export const L1Tabs = ({ topLevelItems, onBack, ...props }: L1TabsProps) => {
   return (
     <>
       {topLevelItems.map((item) => {
         const type = l0ItemType(item);
-        switch (type) {
-          case 'tab':
-            return <L1Panel key={item.id} item={item} {...props} onBack={onBack} />;
-          case 'collection':
-            return <L1PanelCollection key={item.id} item={item} {...props} />;
-          default:
-            return null;
+        if (type === 'tab') {
+          return <L1Panel key={item.id} item={item} {...props} onBack={onBack} />;
         }
+        return null;
       })}
     </>
   );
 };
-
-/**
- *
- */
-const L1PanelCollection = ({ item, path, ...props }: L1PanelProps) => {
-  const { useItems } = useNavTreeContext();
-  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} />
-        ))}
-    </>
-  );
-};

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

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

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 type * from './types';

package/src/components/types.ts

@@ -4,7 +4,7 @@
 
 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';
@@ -15,23 +15,23 @@ 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 }>;
-    useActions: (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;
 };

package/src/experimental/Tree.stories.tsx

@@ -2,15 +2,13 @@
 // Copyright 2023 DXOS.org
 //
 
-import '@dxos-theme';
-
-import { type Meta, type StoryObj } from '@storybook/react-vite';
+import { type Meta } from '@storybook/react-vite';
 import React, { type JSX, type PropsWithChildren, useEffect, useState } from 'react';
 
 import { faker } from '@dxos/random';
 import { Icon, IconButton } from '@dxos/react-ui';
-import { modalSurface, mx } from '@dxos/react-ui-theme';
-import { withLayout, withTheme } from '@dxos/storybook-utils';
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+import { mx } from '@dxos/ui-theme';
 
 import { type ItemMap, Tree, type TreeNodeData, type TreeProps, visitNodes, visitor } from './Tree';
 
@@ -32,7 +30,7 @@ const Container = ({ children, sidebar }: PropsWithChildren<{ sidebar: JSX.Eleme
     <div className='flex'>
       {/* TODO(burdon): Custom thin scrollbar. */}
       {/* TODO(burdon): Horizontal scrolling within navtree? */}
-      <div className='flex flex-col overflow-y-auto w-[300px] bg-neutral-100 dark:bg-neutral-950'>{sidebar}</div>
+      <div className='flex flex-col overflow-y-auto is-[300px] bg-neutral-100 dark:bg-neutral-950'>{sidebar}</div>
       <div className='flex flex-col grow overflow-hidden'>{children}</div>
     </div>
   );
@@ -105,27 +103,6 @@ const data: TreeNodeData[] = [
   },
 ];
 
-export const Default = () => {
-  return <Container sidebar={<Sidebar mutate />} />;
-};
-
-export const Visitor = () => {
-  const [items] = useState(data);
-  const root = items[0];
-  const [openItems] = useState<ItemMap>({ [root.children![0].id]: true });
-  return (
-    <div className='flex flex-col'>
-      {Array.from(visitor(root, openItems)).map(({ node: { id, title }, depth }) => (
-        <div key={id} className='grid grid-cols-[40px_400px_400px] font-mono'>
-          <div>{depth}</div>
-          <div>{id}</div>
-          <div>{title}</div>
-        </div>
-      ))}
-    </div>
-  );
-};
-
 const Sidebar = ({ mutate }: { mutate?: boolean }) => {
   const [items, setItems] = useState(data);
   const root = items[0];
@@ -212,7 +189,7 @@ const Sidebar = ({ mutate }: { mutate?: boolean }) => {
         />
       </div>
 
-      <div className='flex items-center my-2 px-2 gap-2'>
+      <div className='flex items-center my-2 pli-2 gap-2'>
         <IconButton icon='ph--plus-circle--regular' iconOnly label='Create space' onClick={handleCreateSpace} />
         <span className='grow text-sm' onClick={handleCreateSpace}>
           New space
@@ -226,9 +203,28 @@ const Sidebar = ({ mutate }: { mutate?: boolean }) => {
 const meta = {
   title: 'plugins/plugin-navtree/experimental/Tree',
   component: Tree,
-  decorators: [withTheme, withLayout({ fullscreen: true, classNames: modalSurface })],
+  decorators: [withTheme, withLayout({ layout: 'column' })],
 } satisfies Meta<typeof Tree>;
 
 export default meta;
 
-type Story = StoryObj<typeof meta>;
+export const Default = () => {
+  return <Container sidebar={<Sidebar mutate />} />;
+};
+
+export const Visitor = () => {
+  const [items] = useState(data);
+  const root = items[0];
+  const [openItems] = useState<ItemMap>({ [root.children![0].id]: true });
+  return (
+    <div className='flex flex-col'>
+      {Array.from(visitor(root, openItems)).map(({ node: { id, title }, depth }) => (
+        <div key={id} className='grid grid-cols-[40px_400px_400px] font-mono'>
+          <div>{depth}</div>
+          <div>{id}</div>
+          <div>{title}</div>
+        </div>
+      ))}
+    </div>
+  );
+};

package/src/experimental/Tree.tsx

@@ -5,29 +5,21 @@
 import React, { type HTMLAttributes, type PropsWithChildren } from 'react';
 
 import { type ClassNameValue, Icon, type Size } from '@dxos/react-ui';
-import { mx } from '@dxos/react-ui-theme';
-
-// TODO(burdon): Rounded border if first/last.
-const styles = {
-  hover: 'hover:bg-slate-400 dark:hover:bg-slate-800',
-  selected: '!bg-slate-300 dark:!bg-slate-700',
-};
+import { mx } from '@dxos/ui-theme';
 
 export const IconButton = ({
   iconName,
   classNames,
   size = 4,
   onClick,
-  weight = 'regular',
 }: {
   iconName: string;
   classNames?: ClassNameValue;
   size?: Size;
-  weight?: 'regular' | 'duotone' | 'fill';
 } & Pick<HTMLAttributes<HTMLDivElement>, 'onClick'>) => {
   // TODO(burdon): Density aware.
   return (
-    <div className={mx('flex w-6 h-6 items-center justify-center select-none', classNames)} onClick={onClick}>
+    <div className={mx('flex is-6 bs-6 items-center justify-center select-none', classNames)} onClick={onClick}>
       <Icon icon={iconName} classNames='cursor-pointer' size={size} />
     </div>
   );
@@ -124,7 +116,6 @@ const StateIcon = ({ node, open, selected, active }: TreeNodeProps) => {
     <IconButton
       iconName={isActive ? 'ph--user-circle--regular' : 'ph--circle--regular'}
       size={4}
-      weight={selected?.[id] ? 'fill' : 'duotone'}
       classNames={mx(
         'text-slate-500',
         !isChildActive && 'opacity-0 transition duration-500',
@@ -158,15 +149,7 @@ const OpenIcon = ({
 const ItemIcon = ({
   node: { children, iconName = children?.length ? 'ph--folder--regular' : 'ph--file--regular', color },
 }: Pick<TreeNodeProps, 'node'>) => {
-  return (
-    (iconName && (
-      <IconButton
-        iconName={iconName}
-        classNames={color ?? 'text-neutral-700 dark:text-neutral-300'}
-        weight={color ? 'duotone' : 'regular'}
-      />
-    )) || <div />
-  );
+  return (iconName && <IconButton iconName={iconName} classNames={color ?? 'text-subdued'} />) || <div />;
 };
 
 const MenuItem = ({ node: { id }, onMenuAction }: Pick<TreeNodeProps, 'node' | 'onMenuAction'>) => {
@@ -210,9 +193,9 @@ export const TreeNodeRow = (props: TreeNodeProps & { className?: string }) => {
     <Grid
       style={{ paddingLeft: `${(depth - 1) * 24}px` }}
       className={mx(
-        'group w-full items-center cursor-pointer',
-        styles.hover,
-        selected?.[id] && styles.selected,
+        'group is-full items-center cursor-pointer bg-hoverSurface',
+        // TODO(burdon): Use data-active.
+        selected?.[id] && 'bg-activeSurface',
         className,
       )}
       onClick={() => selected && onChangeSelected?.(id, !selected[id])}
@@ -255,7 +238,7 @@ export const TreeChildNodes = ({
   } = props;
   return (
     <div className={mx('flex flex-col mt-0.5 gap-0.5', className)}>
-      {children?.map((child, i) => (
+      {children?.map((child) => (
         <TreeNode key={child.id} {...props} depth={depth + 1} node={child} ancestors={[...ancestors, props.node]} />
       ))}
     </div>

package/src/hooks.ts

@@ -2,13 +2,16 @@
 // Copyright 2025 DXOS.org
 //
 
-import { useEffect } from 'react';
+import { type Atom, useAtomValue } from '@effect-atom/atom-react';
+import { useEffect, useMemo } from 'react';
 
+import { useCapability } from '@dxos/app-framework/react';
 import { type Node } from '@dxos/app-graph';
 
 import { useNavTreeContext } from './components';
+import { NavTreeCapabilities } from './types';
 
-export const useLoadDescendents = (root?: Node) => {
+export const useLoadDescendents = (root?: Node.Node) => {
   const { loadDescendents } = useNavTreeContext();
   useEffect(() => {
     const frame = requestAnimationFrame(() => {
@@ -19,3 +22,52 @@ export const useLoadDescendents = (root?: Node) => {
     return () => cancelAnimationFrame(frame);
   }, [root]);
 };
+
+export type UseNavTreeStateResult = {
+  getItem: (path: string[]) => NavTreeCapabilities.NavTreeItemState;
+  getItemAtom: (path: string[]) => Atom.Atom<NavTreeCapabilities.NavTreeItemState>;
+  setItem: (path: string[], key: 'open' | 'current' | 'alternateTree', next: boolean) => void;
+};
+
+/**
+ * Hook that provides access to navtree state functions.
+ * For reactive subscriptions, use `useNavTreeItemState` or `useAtomValue(getItemAtom(path))`.
+ */
+export const useNavTreeState = (): UseNavTreeStateResult => {
+  return useCapability(NavTreeCapabilities.State);
+};
+
+/**
+ * Hook that subscribes to a single navtree item's state.
+ * Use this for fine-grained reactivity.
+ */
+export const useNavTreeItemState = (path: string[]): NavTreeCapabilities.NavTreeItemState => {
+  const { getItemAtom } = useCapability(NavTreeCapabilities.State);
+  // Memoize the path to avoid creating new atoms on every render.
+  const pathKey = useMemo(() => path.join('~'), [path]);
+  const atom = useMemo(() => getItemAtom(path), [getItemAtom, pathKey]);
+  return useAtomValue(atom);
+};
+
+/**
+ * Hook that subscribes to the open state for a tree item.
+ * Designed to be passed to Tree component as useIsOpen prop.
+ */
+export const useIsOpen = (path: string[], _item?: any): boolean => {
+  return useNavTreeItemState(path).open;
+};
+
+/**
+ * Hook that subscribes to the current state for a tree item.
+ * Designed to be passed to Tree component as useIsCurrent prop.
+ */
+export const useIsCurrent = (path: string[], _item?: any): boolean => {
+  return useNavTreeItemState(path).current;
+};
+
+/**
+ * Hook that subscribes to the alternateTree state for a tree item.
+ */
+export const useIsAlternateTree = (path: string[], _item?: any): boolean => {
+  return useNavTreeItemState(path).alternateTree ?? false;
+};

package/src/index.ts

@@ -2,8 +2,7 @@
 // Copyright 2023 DXOS.org
 //
 
-export { NavTreeCapabilities } from './capabilities';
-export { NavTreeEvents } from './events';
+export { NavTreeCapabilities, NavTreeEvents } from './types';
 export * from './NavTreePlugin';
 export * from './meta';
 export * from './util';

package/src/meta.ts

@@ -2,16 +2,19 @@
 // Copyright 2023 DXOS.org
 //
 
-import { type PluginMeta } from '@dxos/app-framework';
+import { type Plugin } from '@dxos/app-framework';
+import { trim } from '@dxos/util';
 
-export const NAVTREE_PLUGIN = 'dxos.org/plugin/navtree';
+export const meta: Plugin.Meta = {
+  id: 'dxos.org/plugin/navtree',
+  name: 'Navtree',
+  description: trim`
+    Hierarchical navigation tree for browsing spaces, folders, and objects.
+    Provides sidebar navigation with collapsible sections and quick access to workspace content.
+  `,
+};
 
 // TODO(wittjosiah): Factor out.
 export const KEY_BINDING = 'KeyBinding';
 // TODO(wittjosiah): Factor out.
-export const COMMANDS_DIALOG = `${NAVTREE_PLUGIN}/CommandsDialog`;
-
-export const meta: PluginMeta = {
-  id: NAVTREE_PLUGIN,
-  name: 'Navtree',
-};
+export const COMMANDS_DIALOG = `${meta.id}/CommandsDialog`;