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

package/src/experimental/Tree.stories.tsx

@@ -2,42 +2,18 @@
 // Copyright 2023 DXOS.org
 //
 
-import '@dxos-theme';
-
-import { House, List, Planet, PlusCircle, Sailboat } from '@phosphor-icons/react';
-import { type Meta } from '@storybook/react';
-import React, { type JSX, type PropsWithChildren, useEffect, useState } from 'react';
+import { type Meta } from '@storybook/react-vite';
+import React, { useEffect, useState } from 'react';
 
 import { faker } from '@dxos/random';
-import { modalSurface, mx } from '@dxos/react-ui-theme';
-import { withLayout, withTheme } from '@dxos/storybook-utils';
+import { Icon, IconButton, Layout, ScrollArea } from '@dxos/react-ui';
+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';
 
 faker.seed(1234);
 
-/**
- * Space:
- * - Space panels are separated from each other to give them more weight than folders.
- * - Private space isn't different (just first, different icon).
- * - Edit titles in place.
- *
- * Navigation:
- *  - up/down across spaces/folder peers
- *  - right to enter space/folder children
- *  - left to parent
- */
-const Container = ({ children, sidebar }: PropsWithChildren<{ sidebar: JSX.Element }>) => {
-  return (
-    <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 grow overflow-hidden'>{children}</div>
-    </div>
-  );
-};
-
 // TODO(burdon): Generate.
 const data: TreeNodeData[] = [
   {
@@ -48,7 +24,7 @@ const data: TreeNodeData[] = [
         id: faker.string.uuid(),
         title: 'plugins/Personal Space',
         color: 'text-green-400',
-        Icon: House,
+        iconName: 'ph--house--regular',
         children: [
           {
             id: faker.string.uuid(),
@@ -83,7 +59,7 @@ const data: TreeNodeData[] = [
       {
         id: faker.string.uuid(),
         title: faker.commerce.productName(),
-        Icon: Planet,
+        iconName: 'ph--planet--regular',
         children: [
           {
             id: faker.string.uuid(),
@@ -94,38 +70,17 @@ const data: TreeNodeData[] = [
       {
         id: faker.string.uuid(),
         title: faker.commerce.productName(),
-        Icon: Sailboat,
+        iconName: 'ph--sailboat--regular',
       },
       {
         id: faker.string.uuid(),
         title: faker.commerce.productName(),
-        Icon: Planet,
+        iconName: 'ph--planet--regular',
       },
     ],
   },
 ];
 
-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];
@@ -157,7 +112,7 @@ const Sidebar = ({ mutate }: { mutate?: boolean }) => {
     }
   }, []);
 
-  const handleCreateItem: TreeProps['onMenuAction'] = (id, action) => {
+  const handleCreateItem: TreeProps['onMenuAction'] = (id) => {
     setItems((items) => {
       let parent: TreeNodeData | undefined;
       visitNodes(root, (node) => {
@@ -181,7 +136,7 @@ const Sidebar = ({ mutate }: { mutate?: boolean }) => {
     setItems((items) => {
       items[0].children?.push({
         id: faker.string.uuid(),
-        Icon: Planet,
+        iconName: 'ph--planet--regular',
         title: faker.commerce.productName(),
       });
 
@@ -190,43 +145,80 @@ const Sidebar = ({ mutate }: { mutate?: boolean }) => {
   };
 
   return (
-    <div className='flex flex-col overflow-hidden'>
-      <div className='flex flex-col overflow-y-auto'>
-        <Tree
-          className='p-0.5 gap-1'
-          node={root}
-          open={openItems}
-          selected={selectedItems}
-          active={activeItems}
-          onChangeOpen={(id, open) => setOpenItems((items) => ({ ...items, [id]: open }))}
-          onChangeSelected={(id, open) => setSelectedItems((items) => ({ ...items, [id]: open }))}
-          onMenuAction={handleCreateItem}
-          getSlots={(node, open, depth, ancestors) => {
-            if (depth === 1) {
-              return {
-                root: 'rounded bg-white dark:bg-neutral-850',
-                header: mx('rounded-t bg-neutral-50 dark:bg-neutral-900', !open && 'rounded-b'),
-              };
-            }
-          }}
-        />
-      </div>
-
-      <div className='flex items-center my-2 px-2 gap-2'>
-        <PlusCircle onClick={handleCreateSpace} />
+    <Layout.Main>
+      <ScrollArea.Root orientation='vertical' thin>
+        <ScrollArea.Viewport>
+          <Tree
+            className='p-0.5 gap-1'
+            node={root}
+            open={openItems}
+            selected={selectedItems}
+            active={activeItems}
+            onChangeOpen={(id, open) => setOpenItems((items) => ({ ...items, [id]: open }))}
+            onChangeSelected={(id, open) => setSelectedItems((items) => ({ ...items, [id]: open }))}
+            onMenuAction={handleCreateItem}
+            getSlots={(node, open, depth) => {
+              if (depth === 1) {
+                return {
+                  root: 'rounded bg-white dark:bg-neutral-850',
+                  header: mx('rounded-t bg-neutral-50 dark:bg-neutral-900', !open && 'rounded-b'),
+                };
+              }
+            }}
+          />
+        </ScrollArea.Viewport>
+      </ScrollArea.Root>
+
+      <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
         </span>
-        <List />
+        <Icon icon='ph--list--regular' />
       </div>
-    </div>
+    </Layout.Main>
   );
 };
 
-const meta: Meta = {
+const meta = {
   title: 'plugins/plugin-navtree/experimental/Tree',
   component: Tree,
-  decorators: [withTheme, withLayout({ fullscreen: true, classNames: modalSurface })],
-};
+  decorators: [withTheme(), withLayout({ layout: 'column', classNames: 'is-[20rem]' })],
+  parameters: {
+    layout: 'fullscreen',
+  },
+} satisfies Meta<typeof Tree>;
 
 export default meta;
+
+/**
+ * Space:
+ * - Space panels are separated from each other to give them more weight than folders.
+ * - Private space isn't different (just first, different icon).
+ * - Edit titles in place.
+ *
+ * Navigation:
+ *  - up/down across spaces/folder peers
+ *  - right to enter space/folder children
+ *  - left to parent
+ */
+export const Default = () => {
+  return <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

@@ -2,34 +2,25 @@
 // Copyright 2024 DXOS.org
 //
 
-import { CaretRight, Circle, File, Folder, type Icon, type IconProps, Plus, UserCircle } from '@phosphor-icons/react';
 import React, { type HTMLAttributes, type PropsWithChildren } from 'react';
 
-import { type ClassNameValue, type Size } from '@dxos/react-ui';
-import { getSize, 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 { type ClassNameValue, Icon, type Size } from '@dxos/react-ui';
+import { mx } from '@dxos/ui-theme';
 
 export const IconButton = ({
-  Icon,
+  iconName,
   classNames,
   size = 4,
   onClick,
-  ...props
 }: {
-  Icon: Icon;
+  iconName: string;
   classNames?: ClassNameValue;
   size?: Size;
-} & Pick<IconProps, 'weight'> &
-  Pick<HTMLAttributes<HTMLDivElement>, 'onClick'>) => {
+} & 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}>
-      <Icon className={mx('cursor-pointer', getSize(size))} {...props} />
+    <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>
   );
 };
@@ -37,7 +28,7 @@ export const IconButton = ({
 export type TreeNodeData = {
   id: string;
   title: string;
-  Icon?: Icon;
+  iconName?: string;
   color?: string;
   children?: TreeNodeData[];
 };
@@ -123,9 +114,8 @@ const StateIcon = ({ node, open, selected, active }: TreeNodeProps) => {
   // TODO(burdon): No animation if opening/closing folder.
   return (
     <IconButton
-      Icon={isActive ? UserCircle : Circle}
+      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',
@@ -143,7 +133,7 @@ const OpenIcon = ({
   return (
     (children?.length && open && (
       <IconButton
-        Icon={CaretRight}
+        iconName='ph--caret-right--regular'
         size={3}
         classNames={mx('transition duration-200', open?.[id] ? 'rotate-90' : 'transform-none')}
         onClick={(ev) => {
@@ -157,23 +147,15 @@ const OpenIcon = ({
 
 // TODO(burdon): Drag handle,
 const ItemIcon = ({
-  node: { children, Icon = children?.length ? Folder : File, color },
+  node: { children, iconName = children?.length ? 'ph--folder--regular' : 'ph--file--regular', color },
 }: Pick<TreeNodeProps, 'node'>) => {
-  return (
-    (Icon && (
-      <IconButton
-        Icon={Icon}
-        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'>) => {
   return (
     <IconButton
-      Icon={Plus}
+      iconName='ph--plus--regular'
       classNames='invisible group-hover:visible'
       onClick={(ev) => {
         ev.stopPropagation();
@@ -211,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])}
@@ -256,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/ui';
 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`;