@dxos/plugin-navtree 0.8.4-main.c4373fc → 0.8.4-main.c85a9c8dae

package/src/hooks/useNavTreeModel.ts

@@ -0,0 +1,112 @@
+//
+// 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/types';
+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;
+      return {
+        id: node.id,
+        parentOf,
+        disabled: node.properties.disabled,
+        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);
+      const passed = node ? filterItems(node) : false;
+      return node && passed ? 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,42 @@
+//
+// 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' | '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);
+  const pathKey = useMemo(() => path.join('~'), [path]);
+  const atom = useMemo(() => getItemAtom(path), [getItemAtom, pathKey]);
+  return useAtomValue(atom);
+};
+
+/**
+ * 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,11 +2,16 @@
 // 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 = {
+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.

package/src/testing/app-graph-builder.ts

@@ -2,16 +2,15 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Rx } from '@effect-rx/rx-react';
-import * as Function from 'effect/Function';
-import * as Option from 'effect/Option';
+import { Atom } from '@effect-atom/atom-react';
+import * as Effect from 'effect/Effect';
 
-import { type PluginContext } from '@dxos/app-framework';
+import { type BuilderExtensions } from '@dxos/app-graph';
 import { log } from '@dxos/log';
-import { type BuilderExtensions, ROOT_ID, createExtension } from '@dxos/plugin-graph';
+import { GraphBuilder, NodeMatcher } from '@dxos/plugin-graph';
 import { faker } from '@dxos/random';
 
-export const storybookGraphBuilders = (context: PluginContext): BuilderExtensions => {
+export const storybookGraphBuilders = (): BuilderExtensions => {
   const propertiesCache = new Map<string, Record<string, unknown>>();
   const getProperties = (id: string, defaults: Record<string, unknown>) => {
     const cached = propertiesCache.get(id);
@@ -23,249 +22,174 @@ export const storybookGraphBuilders = (context: PluginContext): BuilderExtension
     return defaults;
   };
 
-  return [
-    // Create app menu actions.
-    createExtension({
-      id: 'app-menu',
-      actions: (node) =>
-        Rx.make((get) =>
-          Function.pipe(
-            get(node),
-            Option.flatMap((node) => (node.id === ROOT_ID ? Option.some(node) : Option.none())),
-            Option.map((node) => {
-              return [
-                ...Array.from({ length: 5 }, (_, i) => ({
-                  id: `${node.id}/action-${i}`,
-                  data: () => {
-                    log.info('action', { id: node.id, index: i });
-                  },
-                  properties: {
-                    label: `Action ${i}`,
-                    icon: faker.properties.icon(),
-                    disposition: 'menu',
-                  },
-                })),
-              ];
-            }),
-            Option.getOrElse(() => []),
+  return Effect.runSync(
+    Effect.all([
+      // Create app menu actions.
+      GraphBuilder.createExtension({
+        id: 'app-menu',
+        match: NodeMatcher.whenRoot,
+        actions: () =>
+          Effect.succeed(
+            Array.from({ length: 5 }, (_, i) => ({
+              id: `app-menu/action-${i}`,
+              data: Effect.fnUntraced(function* () {
+                log.info('action', { id: 'app-menu', index: i });
+              }),
+              properties: {
+                label: `Action ${i}`,
+                icon: faker.properties.icon(),
+                disposition: 'menu',
+              },
+            })),
           ),
-        ),
-    }),
-    // Create user account node.
-    createExtension({
-      id: 'user-account',
-      connector: (node) =>
-        Rx.make((get) =>
-          Function.pipe(
-            get(node),
-            Option.flatMap((node) => (node.id === ROOT_ID ? Option.some(node) : Option.none())),
-            Option.map(() => {
-              return [
+      }),
+      // Create user account node.
+      GraphBuilder.createExtension({
+        id: 'user-account',
+        match: NodeMatcher.whenRoot,
+        connector: () =>
+          Effect.succeed([
+            {
+              id: 'user-account',
+              type: 'user-account',
+              properties: {
+                label: 'User profile',
+                icon: 'ph--user--regular',
+                disposition: 'user-account',
+                userId: '1234567890ABCDEF',
+                hue: faker.properties.hue(),
+                emoji: faker.properties.emoji(),
+                status: 'active',
+              },
+              nodes: [
                 {
-                  id: 'user-account',
-                  type: 'user-account',
+                  id: 'profile',
+                  type: 'profile',
                   properties: {
-                    label: 'User Account',
+                    label: 'Profile',
                     icon: 'ph--user--regular',
-                    disposition: 'user-account',
-                    userId: '1234567890ABCDEF',
-                    hue: faker.properties.hue(),
-                    emoji: faker.properties.emoji(),
-                    status: 'active',
                   },
-                  nodes: [
-                    {
-                      id: 'profile',
-                      type: 'profile',
-                      properties: {
-                        label: 'Profile',
-                        icon: 'ph--user--regular',
-                      },
-                    },
-                    {
-                      id: 'devices',
-                      type: 'devices',
-                      properties: {
-                        label: 'Devices',
-                        icon: 'ph--devices--regular',
-                      },
-                    },
-                    {
-                      id: 'security',
-                      type: 'security',
-                      properties: {
-                        label: 'Security',
-                        icon: 'ph--key--regular',
-                      },
-                    },
-                  ],
                 },
-              ];
-            }),
-            Option.getOrElse(() => []),
-          ),
-        ),
-    }),
-    // TODO(wittjosiah): This group node probably is unnecessary now with the flat L0 structure.
-    // Create spaces group node.
-    createExtension({
-      id: 'spaces-root',
-      position: 'hoist',
-      connector: (node) =>
-        Rx.make((get) =>
-          Function.pipe(
-            get(node),
-            Option.flatMap((node) => (node.id === ROOT_ID ? Option.some(node) : Option.none())),
-            Option.map(() => {
-              return [
                 {
-                  id: 'spaces-root',
-                  type: 'spaces-root',
+                  id: 'devices',
+                  type: 'devices',
                   properties: {
-                    label: 'Spaces',
-                    icon: 'ph--planet--regular',
-                    role: 'branch',
-                    disposition: 'collection',
+                    label: 'Devices',
+                    icon: 'ph--devices--regular',
                   },
                 },
-              ];
-            }),
-            Option.getOrElse(() => []),
-          ),
-        ),
-    }),
-    // Create space nodes.
-    createExtension({
-      id: 'spaces',
-      connector: (node) => {
-        const count = Rx.make((get) => {
-          let value = 3;
-          const interval = setInterval(() => {
-            if (value >= 10) {
-              clearInterval(interval);
-              return;
-            }
+                {
+                  id: 'security',
+                  type: 'security',
+                  properties: {
+                    label: 'Security',
+                    icon: 'ph--key--regular',
+                  },
+                },
+              ],
+            },
+          ]),
+      }),
+      // Create space (workspace) nodes directly under root.
+      GraphBuilder.createExtension({
+        id: 'spaces',
+        match: NodeMatcher.whenRoot,
+        connector: (_, get) =>
+          Effect.sync(() => {
+            const count = Atom.make((get) => {
+              let value = 3;
+              const interval = setInterval(() => {
+                if (value >= 10) {
+                  clearInterval(interval);
+                  return;
+                }
 
-            value++;
-            get.setSelf(value);
-          }, 5000);
-          get.addFinalizer(() => clearInterval(interval));
-          return value;
-        });
+                value++;
+                get.setSelf(value);
+              }, 5000);
+              get.addFinalizer(() => clearInterval(interval));
+              return value;
+            });
 
-        return Rx.make((get) =>
-          Function.pipe(
-            get(node),
-            Option.flatMap((node) => (node.id === 'spaces-root' ? Option.some(node) : Option.none())),
-            Option.map(() => {
-              return [
-                ...Array.from({ length: get(count) }, (_, i) => ({
-                  id: `space-${i}`,
-                  type: 'space',
-                  properties: getProperties(`space-${i}`, {
-                    label: `Space ${i}`,
-                    icon: faker.properties.icon(),
-                    hue: faker.properties.hue(),
-                  }),
-                })),
-              ];
-            }),
-            Option.getOrElse(() => []),
-          ),
-        );
-      },
-    }),
-    // Create space actions.
-    createExtension({
-      id: 'space-actions',
-      actions: (node) =>
-        Rx.make((get) =>
-          Function.pipe(
-            get(node),
-            Option.flatMap((node) => (node.type === 'space' ? Option.some(node) : Option.none())),
-            Option.map((node) => {
-              return [
-                ...Array.from({ length: 5 }, (_, i) => ({
-                  id: `${node.id}/action-${i}`,
-                  data: () => {
-                    log.info('action', { id: node.id, index: i });
-                  },
-                  properties: getProperties(`${node.id}/action-${i}`, {
-                    label: `Action ${i}`,
-                    icon: faker.properties.icon(),
-                  }),
-                })),
-              ];
-            }),
-            Option.getOrElse(() => []),
+            return Array.from({ length: get(count) }, (_, i) => ({
+              id: `space-${i}`,
+              type: 'space',
+              properties: getProperties(`space-${i}`, {
+                label: `Space ${i}`,
+                icon: faker.properties.icon(),
+                hue: faker.properties.hue(),
+                disposition: 'workspace',
+              }),
+            }));
+          }),
+      }),
+      // Create space actions.
+      GraphBuilder.createExtension({
+        id: 'space-actions',
+        match: NodeMatcher.whenNodeType('space'),
+        actions: () =>
+          Effect.succeed(
+            Array.from({ length: 5 }, (_, i) => ({
+              id: `space-actions/action-${i}`,
+              data: Effect.fnUntraced(function* () {
+                log.info('action', { id: 'space-actions', index: i });
+              }),
+              properties: getProperties(`space-actions/action-${i}`, {
+                label: `Action ${i}`,
+                icon: faker.properties.icon(),
+              }),
+            })),
           ),
-        ),
-    }),
-    // Create object nodes.
-    createExtension({
-      id: 'objects',
-      connector: (node) => {
-        const count = Rx.make((get) => {
-          let value = 3;
-          const interval = setInterval(() => {
-            if (value >= 20) {
-              clearInterval(interval);
-              return;
-            }
+      }),
+      // Create object nodes.
+      GraphBuilder.createExtension({
+        id: 'objects',
+        match: NodeMatcher.whenNodeType('space'),
+        connector: (_, get) =>
+          Effect.sync(() => {
+            const count = Atom.make((get) => {
+              let value = 3;
+              const interval = setInterval(() => {
+                if (value >= 20) {
+                  clearInterval(interval);
+                  return;
+                }
 
-            value++;
-            get.setSelf(value);
-          }, 5000);
-          get.addFinalizer(() => clearInterval(interval));
-          return value;
-        });
+                value++;
+                get.setSelf(value);
+              }, 5000);
+              get.addFinalizer(() => clearInterval(interval));
+              return value;
+            });
 
-        return Rx.make((get) =>
-          Function.pipe(
-            get(node),
-            Option.flatMap((node) => (node.type === 'space' ? Option.some(node) : Option.none())),
-            Option.map((node) => {
-              return [
-                ...Array.from({ length: get(count) }, (_, i) => ({
-                  id: `${node.id}/object-${i}`,
-                  type: 'object',
-                  properties: getProperties(`${node.id}/object-${i}`, {
-                    label: `Object ${i}`,
-                    icon: faker.properties.icon(),
-                  }),
-                })),
-              ];
-            }),
-            Option.getOrElse(() => []),
-          ),
-        );
-      },
-    }),
-    // Create object actions.
-    createExtension({
-      id: 'object-actions',
-      actions: (node) =>
-        Rx.make((get) =>
-          Function.pipe(
-            get(node),
-            Option.flatMap((node) => (node.type === 'object' ? Option.some(node) : Option.none())),
-            Option.map((node) => {
-              return [
-                ...Array.from({ length: 5 }, (_, i) => ({
-                  id: `${node.id}/action-${i}`,
-                  data: () => {
-                    log.info('action', { id: node.id, index: i });
-                  },
-                  properties: getProperties(`${node.id}/action-${i}`, {
-                    label: `Action ${i}`,
-                    icon: faker.properties.icon(),
-                  }),
-                })),
-              ];
-            }),
-            Option.getOrElse(() => []),
+            return Array.from({ length: get(count) }, (_, i) => ({
+              id: `object-${i}`,
+              type: 'object',
+              properties: getProperties(`object-${i}`, {
+                label: `Object ${i}`,
+                icon: faker.properties.icon(),
+              }),
+            }));
+          }),
+      }),
+      // Create object actions.
+      GraphBuilder.createExtension({
+        id: 'object-actions',
+        match: NodeMatcher.whenNodeType('object'),
+        actions: () =>
+          Effect.succeed(
+            Array.from({ length: 5 }, (_, i) => ({
+              id: `object-actions/action-${i}`,
+              data: Effect.fnUntraced(function* () {
+                log.info('action', { id: 'object-actions', index: i });
+              }),
+              properties: getProperties(`object-actions/action-${i}`, {
+                label: `Action ${i}`,
+                icon: faker.properties.icon(),
+              }),
+            })),
           ),
-        ),
-    }),
-  ];
+      }),
+    ]),
+  );
 };