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

package/src/hooks/useNavTreeModel.ts

@@ -7,14 +7,14 @@ 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 { 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 { 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.
@@ -40,16 +40,25 @@ const createItemPropsFamily = (graph: ReturnType<typeof useAppGraph>['graph']) =
           : 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,
+        count: node.properties.count,
+        modifiedCount: node.properties.modifiedCount,
       };
     }).pipe(Atom.keepAlive);
   });
@@ -65,8 +74,7 @@ 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;
+      return node && filterItems(node) ? node : undefined;
     }).pipe(Atom.keepAlive),
   );
 

package/src/hooks/useNavTreeState.ts

@@ -7,12 +7,12 @@ import { useMemo } from 'react';
 
 import { useCapability } from '@dxos/app-framework/ui';
 
-import { NavTreeCapabilities } from '../types';
+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;
+  setItem: (path: string[], key: 'open' | 'current', next: boolean) => void;
 };
 
 /**
@@ -33,10 +33,3 @@ export const useNavTreeItemState = (path: string[]): NavTreeCapabilities.NavTree
   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,7 +2,6 @@
 // Copyright 2023 DXOS.org
 //
 
-export { NavTreeCapabilities, NavTreeEvents } from './types';
-export * from './NavTreePlugin';
 export * from './meta';
+export * from './types';
 export * from './util';

package/src/meta.ts

@@ -2,19 +2,34 @@
 // Copyright 2023 DXOS.org
 //
 
-import { type Plugin } from '@dxos/app-framework';
+import { Plugin } from '@dxos/app-framework';
+import { DXN } from '@dxos/keys';
 import { trim } from '@dxos/util';
 
-export const meta: Plugin.Meta = {
-  id: 'dxos.org/plugin/navtree',
+export const meta = Plugin.makeMeta({
+  key: DXN.make('org.dxos.plugin.navtree'),
   name: 'Navtree',
+  author: 'DXOS',
+  spec: 'PLUGIN.mdl',
   description: trim`
-    Hierarchical navigation tree for browsing spaces, folders, and objects.
-    Provides sidebar navigation with collapsible sections and quick access to workspace content.
+    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 = DXN.make(`${meta.id}.commandsDialog`);

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';

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

@@ -7,8 +7,8 @@ import * as Effect from 'effect/Effect';
 
 import { type BuilderExtensions } from '@dxos/app-graph';
 import { log } from '@dxos/log';
-import { GraphBuilder, NodeMatcher } from '@dxos/plugin-graph';
-import { faker } from '@dxos/random';
+import { GraphBuilder, Node, NodeMatcher } from '@dxos/plugin-graph';
+import { random } from '@dxos/random';
 
 export const storybookGraphBuilders = (): BuilderExtensions => {
   const propertiesCache = new Map<string, Record<string, unknown>>();
@@ -26,18 +26,18 @@ export const storybookGraphBuilders = (): BuilderExtensions => {
     Effect.all([
       // Create app menu actions.
       GraphBuilder.createExtension({
-        id: 'app-menu',
+        id: 'appMenu',
         match: NodeMatcher.whenRoot,
         actions: () =>
           Effect.succeed(
             Array.from({ length: 5 }, (_, i) => ({
-              id: `app-menu/action-${i}`,
+              id: `action-${i}`,
               data: Effect.fnUntraced(function* () {
                 log.info('action', { id: 'app-menu', index: i });
               }),
               properties: {
                 label: `Action ${i}`,
-                icon: faker.properties.icon(),
+                icon: random.properties.icon(),
                 disposition: 'menu',
               },
             })),
@@ -45,11 +45,11 @@ export const storybookGraphBuilders = (): BuilderExtensions => {
       }),
       // Create user account node.
       GraphBuilder.createExtension({
-        id: 'user-account',
+        id: 'userAccount',
         match: NodeMatcher.whenRoot,
         connector: () =>
           Effect.succeed([
-            {
+            Node.make({
               id: 'user-account',
               type: 'user-account',
               properties: {
@@ -57,37 +57,37 @@ export const storybookGraphBuilders = (): BuilderExtensions => {
                 icon: 'ph--user--regular',
                 disposition: 'user-account',
                 userId: '1234567890ABCDEF',
-                hue: faker.properties.hue(),
-                emoji: faker.properties.emoji(),
+                hue: random.properties.hue(),
+                emoji: random.properties.emoji(),
                 status: 'active',
               },
               nodes: [
-                {
+                Node.make({
                   id: 'profile',
                   type: 'profile',
                   properties: {
                     label: 'Profile',
                     icon: 'ph--user--regular',
                   },
-                },
-                {
+                }),
+                Node.make({
                   id: 'devices',
                   type: 'devices',
                   properties: {
                     label: 'Devices',
                     icon: 'ph--devices--regular',
                   },
-                },
-                {
+                }),
+                Node.make({
                   id: 'security',
                   type: 'security',
                   properties: {
                     label: 'Security',
                     icon: 'ph--key--regular',
                   },
-                },
+                }),
               ],
-            },
+            }),
           ]),
       }),
       // Create space (workspace) nodes directly under root.
@@ -111,32 +111,34 @@ export const storybookGraphBuilders = (): BuilderExtensions => {
               return value;
             });
 
-            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',
+            return Array.from({ length: get(count) }, (_, i) =>
+              Node.make({
+                id: `space-${i}`,
+                type: 'space',
+                properties: getProperties(`space-${i}`, {
+                  label: `Space ${i}`,
+                  icon: random.properties.icon(),
+                  hue: random.properties.hue(),
+                  disposition: 'workspace',
+                }),
               }),
-            }));
+            );
           }),
       }),
       // Create space actions.
       GraphBuilder.createExtension({
-        id: 'space-actions',
+        id: 'spaceActions',
         match: NodeMatcher.whenNodeType('space'),
         actions: () =>
           Effect.succeed(
             Array.from({ length: 5 }, (_, i) => ({
-              id: `space-actions/action-${i}`,
+              id: `action-${i}`,
               data: Effect.fnUntraced(function* () {
                 log.info('action', { id: 'space-actions', index: i });
               }),
-              properties: getProperties(`space-actions/action-${i}`, {
+              properties: getProperties(`action-${i}`, {
                 label: `Action ${i}`,
-                icon: faker.properties.icon(),
+                icon: random.properties.icon(),
               }),
             })),
           ),
@@ -162,30 +164,34 @@ export const storybookGraphBuilders = (): BuilderExtensions => {
               return value;
             });
 
-            return Array.from({ length: get(count) }, (_, i) => ({
-              id: `object-${i}`,
-              type: 'object',
-              properties: getProperties(`object-${i}`, {
-                label: `Object ${i}`,
-                icon: faker.properties.icon(),
+            return Array.from({ length: get(count) }, (_, i) =>
+              Node.make({
+                id: `object-${i}`,
+                type: 'object',
+                properties: getProperties(`object-${i}`, {
+                  label: `Object ${i}`,
+                  icon: random.properties.icon(),
+                  ...(i % 3 === 0 && { count: (i + 1) * 2 }),
+                  ...(i % 3 === 1 && { modifiedCount: i + 1 }),
+                }),
               }),
-            }));
+            );
           }),
       }),
       // Create object actions.
       GraphBuilder.createExtension({
-        id: 'object-actions',
+        id: 'objectActions',
         match: NodeMatcher.whenNodeType('object'),
         actions: () =>
           Effect.succeed(
             Array.from({ length: 5 }, (_, i) => ({
-              id: `object-actions/action-${i}`,
+              id: `action-${i}`,
               data: Effect.fnUntraced(function* () {
-                log.info('action', { id: 'object-actions', index: i });
+                log.info('action', { id: 'objectActions', index: i });
               }),
-              properties: getProperties(`object-actions/action-${i}`, {
+              properties: getProperties(`action-${i}`, {
                 label: `Action ${i}`,
-                icon: faker.properties.icon(),
+                icon: random.properties.icon(),
               }),
             })),
           ),

package/src/testing/generator.ts

@@ -5,9 +5,9 @@
 import * as Schema from 'effect/Schema';
 
 import { type Node } from '@dxos/app-graph';
-import { Obj, Type } from '@dxos/echo';
+import { DXN, Obj, Type } from '@dxos/echo';
 import { TestSchema } from '@dxos/echo/testing';
-import { faker } from '@dxos/random';
+import { random } from '@dxos/random';
 import { range } from '@dxos/util';
 
 // TODO(burdon): Reconcile with @dxos/plugin-debug, @dxos/react-ui/testing.
@@ -43,16 +43,16 @@ export const Priority = [1, 2, 3, 4, 5];
 export const defaultGenerators: { [type: string]: ObjectDataGenerator } = {
   document: {
     createData: () => ({
-      title: faker.lorem.sentence(3),
-      body: faker.lorem.sentences({ min: 1, max: faker.number.int({ min: 1, max: 3 }) }),
+      title: random.lorem.sentence(3),
+      body: random.lorem.sentences({ min: 1, max: random.number.int({ min: 1, max: 3 }) }),
     }),
   },
 
   image: {
     createData: () => ({
-      title: faker.lorem.sentence(3),
-      image: faker.helpers.arrayElement(data.images),
-      body: faker.datatype.boolean() ? faker.lorem.sentences() : undefined,
+      title: random.lorem.sentence(3),
+      image: random.helpers.arrayElement(data.images),
+      body: random.datatype.boolean() ? random.lorem.sentences() : undefined,
     }),
   },
 
@@ -63,18 +63,13 @@ export const defaultGenerators: { [type: string]: ObjectDataGenerator } = {
         repo: Schema.String,
         status: Schema.String,
         priority: Schema.Number,
-      }).pipe(
-        Type.object({
-          typename: 'example.com/type/Project',
-          version: '0.1.0',
-        }),
-      ),
+      }).pipe(Type.makeObject(DXN.make('com.example.type.project', '0.1.0'))),
 
     createData: () => ({
-      title: faker.commerce.productName(),
-      repo: faker.datatype.boolean({ probability: 0.3 }) ? faker.internet.url() : undefined,
-      status: faker.helpers.arrayElement(Status),
-      priority: faker.helpers.arrayElement(Priority),
+      title: random.commerce.productName(),
+      repo: random.datatype.boolean({ probability: 0.3 }) ? random.internet.url() : undefined,
+      status: random.helpers.arrayElement(Status),
+      priority: random.helpers.arrayElement(Priority),
     }),
   },
 };
@@ -99,7 +94,7 @@ export class TestObjectGenerator {
   }
 
   createObject({ types }: { types?: string[] } = {}) {
-    const type = faker.helpers.arrayElement(types ?? Object.keys(this.factories));
+    const type = random.helpers.arrayElement(types ?? Object.keys(this.factories));
     const factory = this.factories[type];
     return factory?.createObject();
   }
@@ -136,7 +131,7 @@ export const createTree = () => {
     nodes: [...Array(4)].map(() => {
       const l0 = generator.createObject();
       return {
-        id: faker.string.uuid(),
+        id: random.string.uuid(),
         data: null,
         type: 'category',
         properties: {
@@ -148,7 +143,7 @@ export const createTree = () => {
           ...[...Array(4)].map(() => {
             const l1 = generator.createObject();
             return {
-              id: faker.string.uuid(),
+              id: random.string.uuid(),
               data: null,
               type: 'document',
               properties: {
@@ -157,20 +152,20 @@ export const createTree = () => {
               },
               nodes: [
                 {
-                  id: `${faker.string.uuid()}__a1`,
+                  id: `${random.string.uuid()}__a1`,
                   data: () => {},
                   type: 'action',
                   properties: {
-                    label: faker.lorem.words(2),
+                    label: random.lorem.words(2),
                     icon: 'ph--boat--regular',
                   },
                 },
                 {
-                  id: `${faker.string.uuid()}__a2`,
+                  id: `${random.string.uuid()}__a2`,
                   data: () => {},
                   type: 'action',
                   properties: {
-                    label: faker.lorem.words(2),
+                    label: random.lorem.words(2),
                     icon: 'ph--train-simple--regular',
                   },
                 },
@@ -178,20 +173,20 @@ export const createTree = () => {
             } satisfies Node.NodeArg<any>;
           }),
           {
-            id: `${faker.string.uuid()}__a1`,
+            id: `${random.string.uuid()}__a1`,
             data: () => {},
             type: 'action',
             properties: {
-              label: faker.lorem.words(2),
+              label: random.lorem.words(2),
               icon: 'ph--boat--regular',
             },
           },
           {
-            id: `${faker.string.uuid()}__a2`,
+            id: `${random.string.uuid()}__a2`,
             data: () => {},
             type: 'action',
             properties: {
-              label: faker.lorem.words(2),
+              label: random.lorem.words(2),
               icon: 'ph--train-simple--regular',
             },
           },

package/src/translations.ts

@@ -4,21 +4,19 @@
 
 import { type Resource } from '@dxos/react-ui';
 
-import { meta } from './meta';
+import { meta } from '#meta';
 
 export const translations = [
   {
     'en-US': {
       [meta.id]: {
-        'app menu label': 'App menu',
-        'open settings label': 'Settings',
-        'open commands label': 'Search commands',
-        'commands dialog title': 'Commands',
-        'command list input placeholder': 'Search for commands…',
-        'node actions menu invoker label': 'More options',
-        'tree item actions label': 'More actions',
-        'empty branch message': ' ',
-        'button back': 'Back to Space',
+        'app-menu.label': 'App menu',
+        'open-commands.label': 'Search commands',
+        'commands-dialog.title': 'Commands',
+        'command-list-input.placeholder': 'Search for commands…',
+        'node-actions-menu-invoker.label': 'More options',
+        'tree-item-actions.label': 'More actions',
+        'button-back.button': 'Back to Space',
       },
     },
   },

package/src/types/NavTreeCapabilities.ts

@@ -0,0 +1,21 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// @import-as-namespace
+
+import { type Atom } from '@effect-atom/atom-react';
+
+import { Capability } from '@dxos/app-framework';
+
+import { meta } from '#meta';
+
+export type NavTreeItemState = { open: boolean; current: boolean };
+
+export type NavTreeStateStore = {
+  getItem: (path: string[]) => NavTreeItemState;
+  getItemAtom: (path: string[]) => Atom.Atom<NavTreeItemState>;
+  setItem: (path: string[], key: 'open' | 'current', next: boolean) => void;
+};
+
+export const State = Capability.make<NavTreeStateStore>(`${meta.id}.capability.state`);

package/src/types/NavTreeEvents.ts

@@ -0,0 +1,12 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// @import-as-namespace
+
+import { type ActivationEvent } from '@dxos/app-framework';
+import { AppActivationEvents } from '@dxos/app-toolkit';
+
+import { meta } from '#meta';
+
+export const StateReady: ActivationEvent.ActivationEvent = AppActivationEvents.createStateEvent(meta.id);

package/src/types/index.ts

@@ -2,6 +2,7 @@
 // Copyright 2025 DXOS.org
 //
 
-export * from './capabilities';
-export * from './events';
 export * from './schema';
+
+export * as NavTreeCapabilities from './NavTreeCapabilities';
+export * as NavTreeEvents from './NavTreeEvents';

package/src/types/schema.ts

@@ -43,6 +43,10 @@ export type NodeProperties = SharedProperties & {
   error?: string;
   modified?: boolean;
   palette?: string;
+  /** Optional item count rendered as a neutral badge after the label. */
+  count?: number;
+  /** Optional count of new/modified items; when greater than zero it shows as a rose badge in place of `count`. */
+  modifiedCount?: number;
 };
 
 export type ActionProperties = SharedProperties & {

package/src/util.ts

@@ -5,7 +5,7 @@
 import { Graph, Node } from '@dxos/plugin-graph';
 import { isNonNullable } from '@dxos/util';
 
-import { type NavTreeItemGraphNode } from './types';
+import { type NavTreeItemGraphNode } from '#types';
 
 export const getParent = (
   graph: Graph.ReadableGraph,
@@ -93,7 +93,7 @@ export const getChildren = (
  * Determines whether a node should be visible based on its disposition.
  */
 export const filterItems = (node: Node.Node, disposition?: string) => {
-  if (!disposition && (node.properties.disposition === 'hidden' || node.properties.disposition === 'alternate-tree')) {
+  if (!disposition && node.properties.disposition === 'hidden') {
     return false;
   } else if (!disposition) {
     const action = Node.isAction(node);

package/src/vite-env.d.ts

@@ -0,0 +1,10 @@
+/// <reference types="vite/client" />
+
+//
+// Copyright 2026 DXOS.org
+//
+
+declare module '*.mdl?raw' {
+  const content: string;
+  export default content;
+}