@dxos/plugin-navtree 0.8.4-main.ead640a → 0.8.4-main.effb148878

package/src/experimental/Tree.stories.tsx

@@ -3,38 +3,16 @@
 //
 
 import { type Meta } from '@storybook/react-vite';
-import React, { type JSX, type PropsWithChildren, useEffect, useState } from 'react';
+import React, { useEffect, useState } from 'react';
 
-import { faker } from '@dxos/random';
-import { Icon, IconButton } from '@dxos/react-ui';
+import { random } from '@dxos/random';
+import { Icon, IconButton, Panel, ScrollArea } from '@dxos/react-ui';
 import { withLayout, withTheme } from '@dxos/react-ui/testing';
-import { mx } from '@dxos/react-ui-theme';
+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>
-  );
-};
+random.seed(1234);
 
 // TODO(burdon): Generate.
 const data: TreeNodeData[] = [
@@ -43,34 +21,34 @@ const data: TreeNodeData[] = [
     title: 'plugins/Root',
     children: [
       {
-        id: faker.string.uuid(),
+        id: random.string.uuid(),
         title: 'plugins/Personal Space',
         color: 'text-green-400',
         iconName: 'ph--house--regular',
         children: [
           {
-            id: faker.string.uuid(),
-            title: faker.commerce.productName(),
+            id: random.string.uuid(),
+            title: random.commerce.productName(),
           },
           {
-            id: faker.string.uuid(),
-            title: faker.commerce.productName(),
+            id: random.string.uuid(),
+            title: random.commerce.productName(),
           },
           {
-            id: faker.string.uuid(),
-            title: faker.commerce.productName(),
+            id: random.string.uuid(),
+            title: random.commerce.productName(),
             children: [
               {
-                id: faker.string.uuid(),
-                title: faker.commerce.productName(),
+                id: random.string.uuid(),
+                title: random.commerce.productName(),
                 children: [
                   {
-                    id: faker.string.uuid(),
-                    title: faker.commerce.productName(),
+                    id: random.string.uuid(),
+                    title: random.commerce.productName(),
                   },
                   {
-                    id: faker.string.uuid(),
-                    title: faker.commerce.productName(),
+                    id: random.string.uuid(),
+                    title: random.commerce.productName(),
                   },
                 ],
               },
@@ -79,24 +57,24 @@ const data: TreeNodeData[] = [
         ],
       },
       {
-        id: faker.string.uuid(),
-        title: faker.commerce.productName(),
+        id: random.string.uuid(),
+        title: random.commerce.productName(),
         iconName: 'ph--planet--regular',
         children: [
           {
-            id: faker.string.uuid(),
-            title: faker.commerce.productName(),
+            id: random.string.uuid(),
+            title: random.commerce.productName(),
           },
         ],
       },
       {
-        id: faker.string.uuid(),
-        title: faker.commerce.productName(),
+        id: random.string.uuid(),
+        title: random.commerce.productName(),
         iconName: 'ph--sailboat--regular',
       },
       {
-        id: faker.string.uuid(),
-        title: faker.commerce.productName(),
+        id: random.string.uuid(),
+        title: random.commerce.productName(),
         iconName: 'ph--planet--regular',
       },
     ],
@@ -134,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) => {
@@ -144,8 +122,8 @@ const Sidebar = ({ mutate }: { mutate?: boolean }) => {
       });
 
       (parent!.children ??= []).push({
-        id: faker.string.uuid(),
-        title: faker.commerce.productName(),
+        id: random.string.uuid(),
+        title: random.commerce.productName(),
       });
 
       setOpenItems((open) => ({ ...open, [parent!.id]: true }));
@@ -157,9 +135,9 @@ const Sidebar = ({ mutate }: { mutate?: boolean }) => {
   const handleCreateSpace = () => {
     setItems((items) => {
       items[0].children?.push({
-        id: faker.string.uuid(),
+        id: random.string.uuid(),
         iconName: 'ph--planet--regular',
-        title: faker.commerce.productName(),
+        title: random.commerce.productName(),
       });
 
       return { ...items };
@@ -167,49 +145,68 @@ 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'>
-        <IconButton icon='ph--plus-circle--regular' iconOnly label='Create space' onClick={handleCreateSpace} />
-        <span className='grow text-sm' onClick={handleCreateSpace}>
-          New space
-        </span>
-        <Icon icon='ph--list--regular' />
-      </div>
-    </div>
+    <Panel.Root>
+      <Panel.Content asChild>
+        <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-sm bg-white dark:bg-neutral-850',
+                    header: mx('rounded-t bg-neutral-50 dark:bg-neutral-900', !open && 'rounded-b'),
+                  };
+                }
+              }}
+            />
+          </ScrollArea.Viewport>
+        </ScrollArea.Root>
+      </Panel.Content>
+      <Panel.Statusbar>
+        <div className='flex items-center my-2 px-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>
+          <Icon icon='ph--list--regular' />
+        </div>
+      </Panel.Statusbar>
+    </Panel.Root>
   );
 };
 
 const meta = {
   title: 'plugins/plugin-navtree/experimental/Tree',
   component: Tree,
-  decorators: [withTheme, withLayout({ container: 'column' })],
+  decorators: [withTheme(), withLayout({ layout: 'column', classNames: 'w-[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 <Container sidebar={<Sidebar mutate />} />;
+  return <Sidebar mutate />;
 };
 
 export const Visitor = () => {

package/src/experimental/Tree.tsx

@@ -5,7 +5,7 @@
 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';
+import { mx } from '@dxos/ui-theme';
 
 export const IconButton = ({
   iconName,
@@ -193,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 bg-hoverSurface',
+        'group w-full items-center cursor-pointer bg-hover-surface',
         // TODO(burdon): Use data-active.
-        selected?.[id] && 'bg-activeSurface',
+        selected?.[id] && 'bg-current-surface',
         className,
       )}
       onClick={() => selected && onChangeSelected?.(id, !selected[id])}
@@ -220,7 +220,7 @@ export const TreeNode = (props: TreeNodeProps & { ancestors?: TreeNodeData[] })
   const { root, header } = getSlots?.(props.node, open?.[id] ?? false, depth, ancestors) ?? {};
 
   return (
-    <div role='none' className={mx('flex flex-col', root)}>
+    <div className={mx('flex flex-col', root)}>
       <TreeNodeRow {...props} className={header} />
       {(children?.length ?? 0) > 0 && open?.[id] && <TreeChildNodes {...props} ancestors={ancestors} />}
     </div>

package/src/hooks/index.ts

@@ -0,0 +1,8 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './useActions';
+export * from './useLoadDescendents';
+export * from './useNavTreeModel';
+export * from './useNavTreeState';

package/src/hooks/useActions.ts

@@ -0,0 +1,34 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { useMemo } from 'react';
+
+import { useAppGraph } from '@dxos/app-toolkit/ui';
+import { Graph, Node, useActions as useGraphActions } from '@dxos/plugin-graph';
+
+import { type FlattenedActions } from '#types';
+
+/** Returns flattened actions and grouped sub-actions for a given graph node. */
+export const useActions = (node: Node.Node): FlattenedActions => {
+  const { graph } = useAppGraph();
+  const actions = useGraphActions(graph, node.id);
+
+  return useMemo(() => {
+    return actions.reduce(
+      (acc: FlattenedActions, arg) => {
+        if (arg.properties.disposition === 'item') {
+          return acc;
+        }
+
+        acc.actions.push(arg);
+        if (!Node.isAction(arg)) {
+          const actionGroup = Graph.getActions(graph, arg.id);
+          acc.groupedActions[arg.id] = actionGroup;
+        }
+        return acc;
+      },
+      { actions: [], groupedActions: {} },
+    );
+  }, [actions]);
+};

package/src/hooks/useLoadDescendents.ts

@@ -0,0 +1,23 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { useEffect } from 'react';
+
+import { type Node } from '@dxos/app-graph';
+import { useAppGraph } from '@dxos/app-toolkit/ui';
+import { Graph } from '@dxos/plugin-graph';
+
+/**
+ * Expands a root node in the app graph.
+ */
+export const useLoadDescendents = (root?: Node.Node) => {
+  const { graph } = useAppGraph();
+  useEffect(() => {
+    if (!root) {
+      return;
+    }
+
+    Graph.expand(graph, root.id, 'child');
+  }, [graph, root]);
+};

package/src/hooks/useNavTreeModel.ts

@@ -0,0 +1,118 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Atom } from '@effect-atom/atom-react';
+import * as Option from 'effect/Option';
+import { useMemo } from 'react';
+
+import { useAppGraph } from '@dxos/app-toolkit/ui';
+import { PLANK_COMPANION_TYPE } from '@dxos/plugin-deck';
+import { type Node } from '@dxos/plugin-graph';
+import { Path, type TreeModel } from '@dxos/react-ui-list';
+import { mx } from '@dxos/ui-theme';
+
+import { type NavTreeItemGraphNode } from '#types';
+
+import { filterItems } from '../util';
+import { useNavTreeState } from './useNavTreeState';
+
+// TODO(wittjosiah): Move companion/hidden nodes to their own edge categories so this filter is unnecessary.
+const isVisibleChild = (node: Node.Node): boolean =>
+  node.type !== PLANK_COMPANION_TYPE && node.properties.disposition !== 'hidden';
+
+/** Create an atom family for item display props keyed by path. */
+const createItemPropsFamily = (graph: ReturnType<typeof useAppGraph>['graph']) =>
+  Atom.family((pathKey: string) => {
+    const path = Path.parts(pathKey);
+    const id = Path.last(pathKey);
+    return Atom.make((get) => {
+      const nodeOpt = get(graph.node(id));
+      const node = Option.getOrElse(nodeOpt, () => undefined);
+      if (!node) {
+        return { id, label: id };
+      }
+      const safeChildren = get(graph.connections(node.id, 'child')).filter((child) => !path.includes(child.id));
+      const visibleChildren = safeChildren.filter(isVisibleChild);
+      const parentOf =
+        visibleChildren.length > 0
+          ? visibleChildren.map((child) => child.id)
+          : node.properties.role === 'branch'
+            ? []
+            : undefined;
+      const parentId = path.length >= 2 ? path[path.length - 2] : undefined;
+      const parentNode = parentId ? Option.getOrElse(get(graph.node(parentId)), () => undefined) : undefined;
+      const droppable =
+        node.properties.droppable === false || parentNode?.properties.childrenDroppable === false ? false : undefined;
+
+      return {
+        id: node.id,
+        parentOf,
+        disabled: node.properties.disabled,
+        draggable: node.properties.draggable,
+        droppable,
+        label: node.properties.label ?? node.id,
+        className: mx(node.properties.className, node.properties.modified && 'italic'),
+        headingClassName: node.properties.headingClassName,
+        icon: node.properties.icon,
+        iconHue: node.properties.iconHue,
+        testId: node.properties.testId,
+      };
+    }).pipe(Atom.keepAlive);
+  });
+
+/** Create an atom family for outbound child IDs keyed by parent ID (pre-sorted by position on write). */
+const createChildIdsFamily = (graph: ReturnType<typeof useAppGraph>['graph']) =>
+  Atom.family((id: string) =>
+    Atom.make((get) => get(graph.connections(id, 'child')).map((child) => child.id)).pipe(Atom.keepAlive),
+  );
+
+/** Create an atom family for item resolution keyed by ID. */
+const createItemFamily = (graph: ReturnType<typeof useAppGraph>['graph']) =>
+  Atom.family((id: string) =>
+    Atom.make((get) => {
+      const node = Option.getOrElse(get(graph.node(id)), () => undefined);
+      return node && filterItems(node) ? node : undefined;
+    }).pipe(Atom.keepAlive),
+  );
+
+/** Create an atom family for open state keyed by path. */
+const createItemOpenFamily = (getItemAtom: ReturnType<typeof useNavTreeState>['getItemAtom']) =>
+  Atom.family((pathKey: string) => {
+    const path = Path.parts(pathKey);
+    const stateAtom = getItemAtom(path);
+    return Atom.make((get) => get(stateAtom).open).pipe(Atom.keepAlive);
+  });
+
+/** Create an atom family for current (selected) state keyed by path. */
+const createItemCurrentFamily = (getItemAtom: ReturnType<typeof useNavTreeState>['getItemAtom']) =>
+  Atom.family((pathKey: string) => {
+    const path = Path.parts(pathKey);
+    const stateAtom = getItemAtom(path);
+    return Atom.make((get) => get(stateAtom).current).pipe(Atom.keepAlive);
+  });
+
+/**
+ * Creates a TreeModel backed by the app graph and navtree state.
+ */
+export const useNavTreeModel = (rootId: string): TreeModel<NavTreeItemGraphNode> => {
+  const { graph } = useAppGraph();
+  const { getItemAtom } = useNavTreeState();
+
+  const itemPropsFamily = useMemo(() => createItemPropsFamily(graph), [graph]);
+  const childIdsFamily = useMemo(() => createChildIdsFamily(graph), [graph]);
+  const itemFamily = useMemo(() => createItemFamily(graph), [graph]);
+  const itemOpenFamily = useMemo(() => createItemOpenFamily(getItemAtom), [getItemAtom]);
+  const itemCurrentFamily = useMemo(() => createItemCurrentFamily(getItemAtom), [getItemAtom]);
+
+  return useMemo(
+    () => ({
+      item: (id: string) => itemFamily(id),
+      itemProps: (path: string[]) => itemPropsFamily(Path.create(...path)),
+      itemOpen: (path: string[]) => itemOpenFamily(Path.create(...path)),
+      itemCurrent: (path: string[]) => itemCurrentFamily(Path.create(...path)),
+      childIds: (parentId?: string) => childIdsFamily(parentId ?? rootId),
+    }),
+    [itemFamily, itemPropsFamily, itemOpenFamily, itemCurrentFamily, childIdsFamily, rootId],
+  );
+};

package/src/hooks/useNavTreeState.ts

@@ -0,0 +1,35 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Atom, useAtomValue } from '@effect-atom/atom-react';
+import { useMemo } from 'react';
+
+import { useCapability } from '@dxos/app-framework/ui';
+
+import { NavTreeCapabilities } from '#types';
+
+export type UseNavTreeStateResult = {
+  getItem: (path: string[]) => NavTreeCapabilities.NavTreeItemState;
+  getItemAtom: (path: string[]) => Atom.Atom<NavTreeCapabilities.NavTreeItemState>;
+  setItem: (path: string[], key: 'open' | 'current', 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);
+  const pathKey = useMemo(() => path.join('~'), [path]);
+  const atom = useMemo(() => getItemAtom(path), [getItemAtom, pathKey]);
+  return useAtomValue(atom);
+};

package/src/index.ts

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

package/src/meta.ts

@@ -2,14 +2,33 @@
 // 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 meta: PluginMeta = {
-  id: 'dxos.org/plugin/navtree',
+export const meta: Plugin.Meta = {
+  id: 'org.dxos.plugin.navtree',
   name: 'Navtree',
+  author: 'DXOS',
+  spec: 'PLUGIN.mdl',
+  description: trim`
+    NavTreePlugin renders the application graph as a collapsible hierarchical tree in the Composer sidebar.
+    It manages workspace tabs at the root level and provides expand/collapse navigation for spaces, folders,
+    and objects, with open/current state persisted to localStorage across sessions.
+
+    The plugin wires drag-and-drop rearrangement and cross-parent transfer of tree items via Pragmatic DnD,
+    and registers graph-action keyboard shortcuts (including the ⌘K / Ctrl+K command palette) through a
+    global Keyboard singleton that tracks context as the user navigates.
+
+    An operation handler for LayoutOperation.Expose expands ancestor paths on demand so that any
+    programmatically activated item is scrolled into view in the tree.
+
+    A commands dialog surfaces all discoverable graph actions as a searchable palette, making it the primary
+    keyboard-first entry point for power users.
+  `,
+  tags: ['system'],
 };
 
 // TODO(wittjosiah): Factor out.
 export const KEY_BINDING = 'KeyBinding';
 // TODO(wittjosiah): Factor out.
-export const COMMANDS_DIALOG = `${meta.id}/CommandsDialog`;
+export const COMMANDS_DIALOG = `${meta.id}.commands-dialog`;

package/src/operations/expose.ts

@@ -0,0 +1,42 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Option from 'effect/Option';
+
+import { Capability } from '@dxos/app-framework';
+import { AppCapabilities, LayoutOperation } from '@dxos/app-toolkit';
+import { Operation } from '@dxos/compute';
+import { log } from '@dxos/log';
+import { Graph } from '@dxos/plugin-graph';
+import { expandAttendableId } from '@dxos/react-ui-attention';
+
+import { NavTreeCapabilities } from '../types';
+
+const handler: Operation.WithHandler<typeof LayoutOperation.Expose> = LayoutOperation.Expose.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* ({ subject }) {
+      const { graph } = yield* Capability.get(AppCapabilities.AppGraph);
+      const { getItem, setItem } = yield* Capability.get(NavTreeCapabilities.State);
+
+      const prefixes = expandAttendableId(subject);
+
+      for (const qualifiedId of prefixes) {
+        Graph.expand(graph, qualifiedId, 'child');
+
+        const treePath = prefixes.slice(0, prefixes.indexOf(qualifiedId) + 1);
+        const state = getItem(treePath);
+        if (!state.open) {
+          setItem(treePath, 'open', true);
+        }
+      }
+
+      if (Option.isNone(Graph.getNode(graph, subject))) {
+        log('Node not found after expansion', { subject });
+      }
+    }),
+  ),
+);
+
+export default handler;

package/src/operations/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { OperationHandlerSet } from '@dxos/compute';
+
+export const NavTreeOperationHandlerSet = OperationHandlerSet.lazy(() => import('./expose'));

package/src/plugin.ts

@@ -0,0 +1,11 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { Plugin } from '@dxos/app-framework';
+
+import { meta } from './meta';
+
+export const NavTreePlugin = Plugin.lazy(meta, () => import('#plugin'));
+
+export { NavTreeOperationHandlerSet } from './operations';