@dxos/plugin-navtree 0.7.5-main.9cb18ac → 0.7.5-main.9d2a38b

package/src/NavTreePlugin.tsx

@@ -1,206 +1,46 @@
 //
-// Copyright 2023 DXOS.org
+// Copyright 2025 DXOS.org
 //
 
-import { effect } from '@preact/signals-core';
-import React from 'react';
-
 import {
-  createIntent,
-  createResolver,
-  createSurface,
-  type GraphBuilderProvides,
-  type GraphProvides,
-  type IntentResolverProvides,
-  LayoutAction,
-  type MetadataRecordsProvides,
+  definePlugin,
+  defineModule,
+  Events,
+  contributes,
+  Capabilities,
+  allOf,
+  oneOf,
   NavigationAction,
-  parseGraphPlugin,
-  parseIntentPlugin,
-  parseLayoutPlugin,
-  parseNavigationPlugin,
-  type Plugin,
-  type PluginDefinition,
-  resolvePlugin,
-  type SurfaceProvides,
-  type TranslationsProvides,
+  createIntent,
 } from '@dxos/app-framework';
-import { createExtension, type Graph, isAction, isGraphNode, type Node } from '@dxos/app-graph';
-import { type UnsubscribeCallback } from '@dxos/async';
-import { Keyboard } from '@dxos/keyboard';
-import { create, type ReactiveObject } from '@dxos/live-object';
 import { type TreeData } from '@dxos/react-ui-list';
-import { Path } from '@dxos/react-ui-mosaic';
-import { getHostPlatform } from '@dxos/util';
 
-import { CommandsDialogContent, NavTreeContainer, NavTreeDocumentTitle, NODE_TYPE, NotchStart } from './components';
-import { CommandsTrigger } from './components/CommandsTrigger';
-import meta, { COMMANDS_DIALOG, KEY_BINDING, NAVTREE_PLUGIN } from './meta';
+import { AppGraphBuilder, IntentResolver, Keyboard, ReactSurface, State } from './capabilities';
+import { NODE_TYPE } from './components';
+import { NavTreeEvents } from './events';
+import { meta } from './meta';
 import translations from './translations';
-import { type NavTreeItemGraphNode } from './types';
-import { expandChildrenAndActions } from './util';
-
-export type NavTreePluginProvides = SurfaceProvides &
-  MetadataRecordsProvides &
-  GraphBuilderProvides &
-  TranslationsProvides &
-  IntentResolverProvides;
-
-const KEY = `${NAVTREE_PLUGIN}/state`;
-const getInitialState = () => {
-  const stringified = localStorage.getItem(KEY);
-  if (!stringified) {
-    return;
-  }
-
-  try {
-    const cached: [string, { open: boolean; current: boolean }][] = JSON.parse(stringified);
-    return cached.map(
-      ([key, value]): [
-        string,
-        ReactiveObject<{
-          open: boolean;
-          current: boolean;
-        }>,
-      ] => [key, create({ open: value.open, current: false })],
-    );
-  } catch {}
-};
-
-export const NavTreePlugin = (): PluginDefinition<NavTreePluginProvides> => {
-  let graphPlugin: Plugin<GraphProvides> | undefined;
-  let graph: Graph | undefined;
-  let unsubscribe: UnsubscribeCallback | undefined;
-
-  // TODO(wittjosiah): This currently needs to be not a ReactiveObject at the root.
-  //   If it is a ReactiveObject then React errors when initializing new paths because of state change during render.
-  //   Ideally this could be a ReactiveObject but be able to access and update the root level without breaking render.
-  //   Wrapping accesses and updates in `untracked` didn't seem to work in all cases.
-  const state = new Map<string, ReactiveObject<{ open: boolean; current: boolean }>>(
-    getInitialState() ?? [
-      // TODO(thure): Initialize these dynamically.
-      ['root', create({ open: true, current: false })],
-      ['root~dxos.org/plugin/space-spaces', create({ open: true, current: false })],
-      ['root~dxos.org/plugin/files', create({ open: true, current: false })],
-    ],
-  );
-
-  const getItem = (_path: string[]) => {
-    const path = Path.create(..._path);
-    const value = state.get(path) ?? create({ open: false, current: false });
-    if (!state.has(path)) {
-      state.set(path, value);
-    }
-
-    return value;
-  };
-
-  const setItem = (path: string[], key: 'open' | 'current', next: boolean) => {
-    const value = getItem(path);
-    value[key] = next;
-
-    localStorage.setItem(KEY, JSON.stringify(Array.from(state.entries())));
-  };
-
-  const isOpen = (path: string[]) => getItem(path).open;
-  const isCurrent = (path: string[]) => getItem(path).current;
-
-  const handleOpenChange = ({ item: { id }, path, open }: { item: Node; path: string[]; open: boolean }) => {
-    // TODO(thure): This might become a localstorage leak; openItemIds that no longer exist should be removed from this map.
-    setItem(path, 'open', open);
 
-    if (graph) {
-      const node = graph.findNode(id);
-      return node && expandChildrenAndActions(graph, node as NavTreeItemGraphNode);
-    }
-  };
-
-  return {
-    meta,
-    ready: async ({ plugins }) => {
-      const layout = resolvePlugin(plugins, parseLayoutPlugin)?.provides.layout;
-      const location = resolvePlugin(plugins, parseNavigationPlugin)?.provides.location;
-      graphPlugin = resolvePlugin(plugins, parseGraphPlugin);
-      graph = graphPlugin?.provides.graph;
-      if (!graph || !location || !layout) {
-        return;
-      }
-
-      const soloPart = location?.active.solo?.[0];
-      const dispatch = resolvePlugin(plugins, parseIntentPlugin)?.provides.intent.dispatchPromise;
-      if (dispatch && soloPart) {
-        void dispatch(createIntent(NavigationAction.Expose, { id: soloPart.id }));
-      }
-
-      let previous: string[] = [];
-      unsubscribe = effect(() => {
-        const part = layout.layoutMode === 'solo' ? 'solo' : 'main';
-        const current = location.active[part]?.map(({ id }) => id) ?? [];
-        const removed = previous.filter((id) => !current.includes(id));
-        previous = current;
-
-        // TODO(wittjosiah): This is setTimeout because there's a race between the keys be initialized.
-        //   This could be avoided if the location was a path as well and not just an id.
-        setTimeout(() => {
-          removed.forEach((id) => {
-            const keys = Array.from(state.keys()).filter((key) => Path.last(key) === id);
-            keys.forEach((key) => {
-              setItem(Path.parts(key), 'current', false);
-            });
-          });
-
-          current.forEach((id) => {
-            const keys = Array.from(new Set([...state.keys(), id])).filter((key) => Path.last(key) === id);
-            keys.forEach((key) => {
-              setItem(Path.parts(key), 'current', true);
-            });
-          });
-        });
-      });
-
-      // TODO(wittjosiah): Factor out.
-      // TODO(wittjosiah): Handle removal of actions.
-      graph.subscribeTraverse({
-        visitor: (node, path) => {
-          let shortcut: string | undefined;
-          if (typeof node.properties.keyBinding === 'object') {
-            const availablePlatforms = Object.keys(node.properties.keyBinding);
-            const platform = getHostPlatform();
-            shortcut = availablePlatforms.includes(platform)
-              ? node.properties.keyBinding[platform]
-              : platform === 'ios'
-                ? node.properties.keyBinding.macos // Fallback to macos if ios-specific bindings not provided.
-                : platform === 'linux' || platform === 'unknown'
-                  ? node.properties.keyBinding.windows // Fallback to windows if platform-specific bindings not provided.
-                  : undefined;
-          } else {
-            shortcut = node.properties.keyBinding;
-          }
-
-          if (shortcut && isAction(node)) {
-            Keyboard.singleton.getContext(path.slice(0, -1).join('/')).bind({
-              shortcut,
-              handler: () => {
-                void node.data({ node, caller: KEY_BINDING });
-              },
-              data: node.properties.label,
-            });
-          }
-        },
-      });
-
-      // TODO(burdon): Create context and plugin.
-      Keyboard.singleton.initialize();
-      Keyboard.singleton.setCurrentContext(graphPlugin?.provides.graph.root.id);
-    },
-    unload: async () => {
-      unsubscribe?.();
-      Keyboard.singleton.destroy();
-    },
-    provides: {
-      metadata: {
-        records: {
-          [NODE_TYPE]: {
+export const NavTreePlugin = () =>
+  definePlugin(meta, [
+    defineModule({
+      id: `${meta.id}/module/state`,
+      activatesOn: allOf(Events.LayoutReady, Events.LocationReady),
+      activatesAfter: [NavTreeEvents.StateReady],
+      activate: State,
+    }),
+    defineModule({
+      id: `${meta.id}/module/translations`,
+      activatesOn: Events.SetupTranslations,
+      activate: () => contributes(Capabilities.Translations, translations),
+    }),
+    defineModule({
+      id: `${meta.id}/module/metadata`,
+      activatesOn: oneOf(Events.Startup, Events.SetupAppGraph),
+      activate: () =>
+        contributes(Capabilities.Metadata, {
+          id: NODE_TYPE,
+          metadata: {
             parse: ({ item }: TreeData, type: string) => {
               switch (type) {
                 case 'node':
@@ -212,103 +52,41 @@ export const NavTreePlugin = (): PluginDefinition<NavTreePluginProvides> => {
               }
             },
           },
-        },
-      },
-      surface: {
-        definitions: () => [
-          createSurface({
-            id: COMMANDS_DIALOG,
-            role: 'dialog',
-            filter: (data): data is { subject?: string } => data.component === COMMANDS_DIALOG,
-            component: ({ data }) => <CommandsDialogContent selected={data.subject} />,
-          }),
-          createSurface({
-            id: `${NAVTREE_PLUGIN}/navigation`,
-            role: 'navigation',
-            component: ({ data }) => (
-              <NavTreeContainer
-                isOpen={isOpen}
-                isCurrent={isCurrent}
-                onOpenChange={handleOpenChange}
-                popoverAnchorId={data.popoverAnchorId as string | undefined}
-              />
-            ),
-          }),
-          createSurface({
-            id: `${NAVTREE_PLUGIN}/document-title`,
-            role: 'document-title',
-            component: ({ data }) => (
-              <NavTreeDocumentTitle node={isGraphNode(data.subject) ? data.subject : undefined} />
-            ),
-          }),
-          createSurface({
-            id: `${NAVTREE_PLUGIN}/notch-start`,
-            role: 'notch-start',
-            component: () => <NotchStart />,
-          }),
-          createSurface({
-            id: `${NAVTREE_PLUGIN}/search-input`,
-            role: 'search-input',
-            disposition: 'fallback',
-            component: () => <CommandsTrigger />,
-          }),
-        ],
-      },
-      intent: {
-        resolvers: ({ plugins }) => {
-          const graph = resolvePlugin(plugins, parseGraphPlugin)?.provides.graph;
-          if (!graph) {
-            return [];
-          }
-
-          return createResolver(NavigationAction.Expose, async ({ id }) => {
-            const path = await graph.waitForPath({ target: id });
-            [...Array(path.length)].forEach((_, index) => {
-              const subpath = path.slice(0, index);
-              const value = getItem(subpath);
-              if (!value.open) {
-                setItem(subpath, 'open', true);
-              }
-            });
-          });
-        },
-      },
-      graph: {
-        builder: (plugins) => {
-          // TODO(burdon): Move to separate plugin (for keys and command k). Move bindings from LayoutPlugin.
-          const dispatch = resolvePlugin(plugins, parseIntentPlugin)?.provides.intent.dispatchPromise;
-
-          return [
-            createExtension({
-              id: NAVTREE_PLUGIN,
-              filter: (node): node is Node<null> => node.id === 'root',
-              actions: () => [
-                {
-                  id: COMMANDS_DIALOG,
-                  data: async () => {
-                    await dispatch?.(
-                      createIntent(LayoutAction.SetLayout, {
-                        element: 'dialog',
-                        component: COMMANDS_DIALOG,
-                        dialogBlockAlign: 'start',
-                      }),
-                    );
-                  },
-                  properties: {
-                    label: ['open commands label', { ns: NAVTREE_PLUGIN }],
-                    icon: 'ph--magnifying-glass--regular',
-                    keyBinding: {
-                      macos: 'meta+k',
-                      windows: 'ctrl+k',
-                    },
-                  },
-                },
-              ],
-            }),
-          ];
-        },
+        }),
+    }),
+    defineModule({
+      id: `${meta.id}/module/expose`,
+      activatesOn: allOf(Events.DispatcherReady, Events.LayoutReady, Events.LocationReady, NavTreeEvents.StateReady),
+      activate: async (context) => {
+        const location = context.requestCapability(Capabilities.Location);
+        const { dispatchPromise: dispatch } = context.requestCapability(Capabilities.IntentDispatcher);
+
+        const soloPart = location.active.solo?.[0];
+        if (dispatch && soloPart) {
+          await dispatch(createIntent(NavigationAction.Expose, { id: soloPart.id }));
+        }
+
+        return [];
       },
-      translations,
-    },
-  };
-};
+    }),
+    defineModule({
+      id: `${meta.id}/module/keyboard`,
+      activatesOn: Events.AppGraphReady,
+      activate: Keyboard,
+    }),
+    defineModule({
+      id: `${meta.id}/module/react-surface`,
+      activatesOn: Events.Startup,
+      activate: ReactSurface,
+    }),
+    defineModule({
+      id: `${meta.id}/module/intent-resolver`,
+      activatesOn: Events.SetupIntents,
+      activate: IntentResolver,
+    }),
+    defineModule({
+      id: `${meta.id}/module/app-graph-builder`,
+      activatesOn: Events.SetupAppGraph,
+      activate: AppGraphBuilder,
+    }),
+  ]);

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

@@ -0,0 +1,40 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Capabilities, contributes, type PluginsContext, createIntent, LayoutAction } from '@dxos/app-framework';
+import { createExtension, type Node } from '@dxos/plugin-graph';
+
+import { COMMANDS_DIALOG, NAVTREE_PLUGIN } from '../meta';
+
+export default (context: PluginsContext) =>
+  contributes(
+    Capabilities.AppGraphBuilder,
+    createExtension({
+      id: NAVTREE_PLUGIN,
+      filter: (node): node is Node<null> => node.id === 'root',
+      actions: () => [
+        {
+          id: COMMANDS_DIALOG,
+          data: async () => {
+            const { dispatchPromise: dispatch } = context.requestCapability(Capabilities.IntentDispatcher);
+            await dispatch(
+              createIntent(LayoutAction.SetLayout, {
+                element: 'dialog',
+                component: COMMANDS_DIALOG,
+                dialogBlockAlign: 'start',
+              }),
+            );
+          },
+          properties: {
+            label: ['open commands label', { ns: NAVTREE_PLUGIN }],
+            icon: 'ph--magnifying-glass--regular',
+            keyBinding: {
+              macos: 'meta+k',
+              windows: 'ctrl+k',
+            },
+          },
+        },
+      ],
+    }),
+  );

package/src/capabilities/capabilities.ts

@@ -0,0 +1,18 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { defineCapability } from '@dxos/app-framework';
+import { type ReactiveObject } from '@dxos/live-object';
+
+import { NAVTREE_PLUGIN } from '../meta';
+
+export namespace NavTreeCapabilities {
+  export const State = defineCapability<{
+    state: Map<string, ReactiveObject<{ open: boolean; current: boolean }>>;
+    getItem: (path: string[]) => ReactiveObject<{ open: boolean; current: boolean }>;
+    setItem: (path: string[], key: 'open' | 'current', next: boolean) => void;
+    isOpen: (path: string[]) => boolean;
+    isCurrent: (path: string[]) => boolean;
+  }>(`${NAVTREE_PLUGIN}/capability/state`);
+}

package/src/capabilities/index.ts

@@ -0,0 +1,13 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { lazy } from '@dxos/app-framework';
+
+export const AppGraphBuilder = lazy(() => import('./app-graph-builder'));
+export const IntentResolver = lazy(() => import('./intent-resolver'));
+export const Keyboard = lazy(() => import('./keyboard'));
+export const ReactSurface = lazy(() => import('./react-surface'));
+export const State = lazy(() => import('./state'));
+
+export * from './capabilities';

package/src/capabilities/intent-resolver.ts

@@ -0,0 +1,30 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { contributes, type PluginsContext, Capabilities, NavigationAction, createResolver } from '@dxos/app-framework';
+import { log } from '@dxos/log';
+
+import { NavTreeCapabilities } from './capabilities';
+
+export default (context: PluginsContext) =>
+  contributes(
+    Capabilities.IntentResolver,
+    createResolver(NavigationAction.Expose, async ({ id }) => {
+      const { graph } = context.requestCapability(Capabilities.AppGraph);
+      const { getItem, setItem } = context.requestCapability(NavTreeCapabilities.State);
+
+      try {
+        const path = await graph.waitForPath({ target: id }, { timeout: 1_000 });
+        [...Array(path.length)].forEach((_, index) => {
+          const subpath = path.slice(0, index);
+          const value = getItem(subpath);
+          if (!value.open) {
+            setItem(subpath, 'open', true);
+          }
+        });
+      } catch {
+        log.warn('Path to node not found', { id });
+      }
+    }),
+  );

package/src/capabilities/keyboard.ts

@@ -0,0 +1,54 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Capabilities as AppCapabilities, contributes, type PluginsContext } from '@dxos/app-framework';
+import { Keyboard } from '@dxos/keyboard';
+import { isAction } from '@dxos/plugin-graph';
+import { getHostPlatform } from '@dxos/util';
+
+import { KEY_BINDING } from '../meta';
+
+export default (context: PluginsContext) => {
+  const { graph } = context.requestCapability(AppCapabilities.AppGraph);
+
+  // TODO(wittjosiah): Factor out.
+  // TODO(wittjosiah): Handle removal of actions.
+  const unsubscribe = graph.subscribeTraverse({
+    visitor: (node, path) => {
+      let shortcut: string | undefined;
+      if (typeof node.properties.keyBinding === 'object') {
+        const availablePlatforms = Object.keys(node.properties.keyBinding);
+        const platform = getHostPlatform();
+        shortcut = availablePlatforms.includes(platform)
+          ? node.properties.keyBinding[platform]
+          : platform === 'ios'
+            ? node.properties.keyBinding.macos // Fallback to macos if ios-specific bindings not provided.
+            : platform === 'linux' || platform === 'unknown'
+              ? node.properties.keyBinding.windows // Fallback to windows if platform-specific bindings not provided.
+              : undefined;
+      } else {
+        shortcut = node.properties.keyBinding;
+      }
+
+      if (shortcut && isAction(node)) {
+        Keyboard.singleton.getContext(path.slice(0, -1).join('/')).bind({
+          shortcut,
+          handler: () => {
+            void node.data({ node, caller: KEY_BINDING });
+          },
+          data: node.properties.label,
+        });
+      }
+    },
+  });
+
+  // TODO(burdon): Create context and plugin.
+  Keyboard.singleton.initialize();
+  Keyboard.singleton.setCurrentContext(graph.root.id);
+
+  return contributes(AppCapabilities.Null, null, () => {
+    unsubscribe();
+    Keyboard.singleton.destroy();
+  });
+};

package/src/capabilities/react-surface.tsx

@@ -0,0 +1,82 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React, { useCallback } from 'react';
+
+import { createSurface, Capabilities, contributes, useCapability } from '@dxos/app-framework';
+import { isGraphNode, type Node } from '@dxos/plugin-graph';
+
+import { NavTreeCapabilities } from './capabilities';
+import {
+  CommandsDialogContent,
+  CommandsTrigger,
+  NavTreeDocumentTitle,
+  NotchStart,
+  NavTreeContainer,
+} from '../components';
+import { NavTreeFooter } from '../components/NavTreeFooter';
+import { COMMANDS_DIALOG, NAVTREE_PLUGIN } from '../meta';
+import { type NavTreeItemGraphNode } from '../types';
+import { expandChildrenAndActions } from '../util';
+
+export default () =>
+  contributes(Capabilities.ReactSurface, [
+    createSurface({
+      id: COMMANDS_DIALOG,
+      role: 'dialog',
+      filter: (data): data is { subject?: string } => data.component === COMMANDS_DIALOG,
+      component: ({ data }) => <CommandsDialogContent selected={data.subject} />,
+    }),
+    createSurface({
+      id: `${NAVTREE_PLUGIN}/navigation`,
+      role: 'navigation',
+      component: ({ data }) => {
+        const { graph } = useCapability(Capabilities.AppGraph);
+        const { isOpen, isCurrent, setItem } = useCapability(NavTreeCapabilities.State);
+
+        const handleOpenChange = useCallback(
+          ({ item: { id }, path, open }: { item: Node; path: string[]; open: boolean }) => {
+            // TODO(thure): This might become a localstorage leak; openItemIds that no longer exist should be removed from this map.
+            setItem(path, 'open', open);
+
+            if (graph) {
+              const node = graph.findNode(id);
+              return node && expandChildrenAndActions(graph, node as NavTreeItemGraphNode);
+            }
+          },
+          [graph],
+        );
+
+        return (
+          <NavTreeContainer
+            isOpen={isOpen}
+            isCurrent={isCurrent}
+            onOpenChange={handleOpenChange}
+            popoverAnchorId={data.popoverAnchorId as string | undefined}
+          />
+        );
+      },
+    }),
+    createSurface({
+      id: `${NAVTREE_PLUGIN}/document-title`,
+      role: 'document-title',
+      component: ({ data }) => <NavTreeDocumentTitle node={isGraphNode(data.subject) ? data.subject : undefined} />,
+    }),
+    createSurface({
+      id: `${NAVTREE_PLUGIN}/notch-start`,
+      role: 'notch-start',
+      component: () => <NotchStart />,
+    }),
+    createSurface({
+      id: `${NAVTREE_PLUGIN}/header-end`,
+      role: 'header-end',
+      component: () => <NavTreeFooter />,
+    }),
+    createSurface({
+      id: `${NAVTREE_PLUGIN}/search-input`,
+      role: 'search-input',
+      disposition: 'fallback',
+      component: () => <CommandsTrigger />,
+    }),
+  ]);