@dxos/app-graph 0.4.6 → 0.4.7-main.06facb4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/app-graph",
-  "version": "0.4.6",
+  "version": "0.4.7-main.06facb4",
   "description": "Constructs knowledge graphs for the purpose of building applications on top of",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -12,22 +12,9 @@
       "import": "./dist/lib/browser/index.mjs",
       "require": "./dist/lib/node/index.cjs",
       "node": "./dist/lib/node/index.cjs"
-    },
-    "./testing": {
-      "browser": "./dist/lib/browser/testing.mjs",
-      "import": "./dist/lib/browser/testing.mjs",
-      "require": "./dist/lib/node/testing.cjs",
-      "node": "./dist/lib/node/testing.cjs"
     }
   },
   "types": "dist/types/src/index.d.ts",
-  "typesVersions": {
-    "*": {
-      "testing": [
-        "dist/types/src/testing.d.ts"
-      ]
-    }
-  },
   "files": [
     "dist",
     "src"
@@ -35,31 +22,25 @@
   "dependencies": {
     "@preact/signals-core": "^1.5.1",
     "deepsignal": "^1.5.0",
-    "lodash.get": "^4.4.2",
-    "lodash.set": "^4.3.2",
-    "@dxos/debug": "0.4.6",
-    "@dxos/invariant": "0.4.6",
-    "@dxos/keyboard": "0.4.6",
-    "@dxos/util": "0.4.6",
-    "@dxos/async": "0.4.6"
+    "@dxos/async": "0.4.7-main.06facb4",
+    "@dxos/invariant": "0.4.7-main.06facb4",
+    "@dxos/util": "0.4.7-main.06facb4",
+    "@dxos/debug": "0.4.7-main.06facb4"
   },
   "devDependencies": {
     "@phosphor-icons/react": "^2.0.5",
-    "@types/lodash.get": "^4.4.7",
-    "@types/lodash.set": "^4.3.7",
     "@types/react": "^18.0.21",
     "@types/react-dom": "^18.0.6",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
     "vite": "^5.1.3",
-    "@dxos/random": "0.4.6",
-    "@dxos/react-client": "0.4.6",
-    "@dxos/react-ui": "0.4.6",
-    "@dxos/storybook-utils": "0.4.6",
-    "@dxos/react-ui-theme": "0.4.6"
+    "@dxos/random": "0.4.7-main.06facb4",
+    "@dxos/react-client": "0.4.7-main.06facb4",
+    "@dxos/react-ui": "0.4.7-main.06facb4",
+    "@dxos/react-ui-theme": "0.4.7-main.06facb4",
+    "@dxos/storybook-utils": "0.4.7-main.06facb4"
   },
   "peerDependencies": {
-    "@phosphor-icons/react": "^2.0.5",
     "react": "^18.2.0",
     "react-dom": "^18.2.0"
   },

package/src/graph-builder.ts

@@ -2,238 +2,50 @@
 // Copyright 2023 DXOS.org
 //
 
-import { untracked } from '@preact/signals-core';
-import { type RevertDeepSignal, deepSignal } from 'deepsignal/react';
+import { EventSubscriptions, type UnsubscribeCallback } from '@dxos/async';
 
-import { EventSubscriptions } from '@dxos/async';
-import { Keyboard } from '@dxos/keyboard';
-import { getHostPlatform } from '@dxos/util';
-
-import type { ActionArg, Action } from './action';
 import { Graph } from './graph';
-import type { NodeArg, Node, NodeBuilder } from './node';
 
-export const KEY_BINDING = 'KeyBinding';
+export type BuilderExtension = (graph: Graph) => UnsubscribeCallback | void;
 
 /**
- * The builder...
+ * The builder provides an extensible way to compose the construction of the graph.
  */
 export class GraphBuilder {
-  private readonly _nodeBuilders = new Map<string, NodeBuilder>();
-  private readonly _unsubscribe = new Map<string, EventSubscriptions>();
+  private readonly _extensions = new Map<string, BuilderExtension>();
+  private readonly _unsubscribe = new EventSubscriptions();
 
   /**
    * Register a node builder which will be called in order to construct the graph.
    */
-  addNodeBuilder(id: string, builder: NodeBuilder): GraphBuilder {
-    this._nodeBuilders.set(id, builder);
+  addExtension(id: string, extension: BuilderExtension): GraphBuilder {
+    this._extensions.set(id, extension);
     return this;
   }
 
   /**
    * Remove a node builder from the graph builder.
    */
-  removeNodeBuilder(id: string): GraphBuilder {
-    this._nodeBuilders.delete(id);
+  removeExtension(id: string): GraphBuilder {
+    this._extensions.delete(id);
     return this;
   }
 
   /**
-   * Construct the graph, starting by calling all registered node builders on the root node.
-   * Node builders will be filtered out as they are used such that they are only used once on any given path.
+   * Construct the graph, starting by calling all registered extensions.
    * @param previousGraph If provided, the graph will be updated in place.
-   * @param startingPath If provided, the graph will be updated starting at the given path.
-   */
-  build(previousGraph?: Graph, startingPath: string[] = []): Graph {
-    const graph: Graph = previousGraph ?? new Graph(this._createNode(() => graph, { id: 'root', label: 'Root' }));
-    return this._build(graph, graph.root, startingPath);
-  }
-
-  /**
-   * Called recursively.
    */
-  private _build(graph: Graph, node: Node, path: string[] = [], ignoreBuilders: string[] = []): Graph {
-    // TODO(wittjosiah): Should this support multiple paths to the same node?
-    graph._setPath(node.id, path);
-
-    // TODO(burdon): Document.
-    const subscriptions = this._unsubscribe.get(node.id) ?? new EventSubscriptions();
-    subscriptions.clear();
+  build(previousGraph?: Graph): Graph {
+    // Clear previous extension subscriptions.
+    this._unsubscribe.clear();
 
-    Array.from(this._nodeBuilders.entries())
-      .filter(([id]) => ignoreBuilders.findIndex((ignore) => ignore === id) === -1)
-      .forEach(([_, builder]) => {
-        const unsubscribe = builder(node);
-        unsubscribe && subscriptions.add(unsubscribe);
-      });
+    const graph: Graph = previousGraph ?? new Graph();
 
-    this._unsubscribe.set(node.id, subscriptions);
+    Array.from(this._extensions.values()).forEach((builder) => {
+      const unsubscribe = builder(graph);
+      unsubscribe && this._unsubscribe.add(unsubscribe);
+    });
 
     return graph;
   }
-
-  private _createNode<TData = null, TProperties extends Record<string, any> = Record<string, any>>(
-    getGraph: () => Graph,
-    partial: NodeArg<TData, TProperties>,
-    path: string[] = [],
-    ignoreBuilders: string[] = [],
-  ): Node<TData, TProperties> {
-    // TODO(burdon): Document implications and rationale of deepSignal.
-    const node: Node<TData, TProperties> = deepSignal({
-      parent: null,
-      data: null as TData, // TODO(burdon): Allow null property?
-      properties: {} as TProperties,
-      childrenMap: {},
-      actionsMap: {},
-      // TODO(burdon): Document.
-      ...partial,
-
-      get children() {
-        return Object.values(node.childrenMap);
-      },
-      get actions() {
-        return Object.values(node.actionsMap);
-      },
-
-      //
-      // Properties
-      //
-
-      addProperty: (key, value) => {
-        untracked(() => {
-          (node.properties as Record<string, any>)[key] = value;
-        });
-      },
-      removeProperty: (key) => {
-        untracked(() => {
-          delete (node.properties as Record<string, any>)[key];
-        });
-      },
-
-      //
-      // Nodes
-      //
-
-      addNode: (builder, ...partials) => {
-        return untracked(() => {
-          return partials.map((partial) => {
-            const builders = [...ignoreBuilders, builder];
-            const childPath = [...path, 'childrenMap', partial.id];
-            const child = this._createNode(getGraph, { ...partial, parent: node }, childPath, builders);
-            node.childrenMap[child.id] = child;
-            // TODO(burdon): Defer triggering recursive updates until task has completed.
-            this._build(getGraph(), child, childPath, builders);
-            return child;
-          });
-        });
-      },
-      removeNode: (id) => {
-        return untracked(() => {
-          const child = node.childrenMap[id];
-          delete node.childrenMap[id];
-          return child;
-        });
-      },
-
-      //
-      // Actions
-      //
-
-      addAction: (...partials) => {
-        return untracked(() => {
-          return partials.map((partial) => {
-            const action = this._createAction(partial);
-            let shortcut: string | undefined;
-            if (typeof action.keyBinding === 'object') {
-              const availablePlatforms = Object.keys(action.keyBinding);
-              const platform = getHostPlatform();
-              shortcut = availablePlatforms.includes(platform)
-                ? action.keyBinding[platform]
-                : platform === 'ios'
-                  ? action.keyBinding.macos // Fallback to macos if ios-specific bindings not provided.
-                  : platform === 'linux' || platform === 'unknown'
-                    ? action.keyBinding.windows // Fallback to windows if platform-specific bindings not provided.
-                    : undefined;
-            } else {
-              shortcut = action.keyBinding;
-            }
-            if (shortcut) {
-              Keyboard.singleton.getContext(path.join('/')).bind({
-                shortcut,
-                handler: () => {
-                  action.invoke({ caller: KEY_BINDING });
-                },
-                data: action.label,
-              });
-            }
-
-            node.actionsMap[action.id] = action;
-            return action;
-          });
-        });
-      },
-      removeAction: (id) => {
-        return untracked(() => {
-          const action = node.actionsMap[id];
-          if (action.keyBinding) {
-            // keyboardjs.unbind(action.keyBinding);
-          }
-
-          delete node.actionsMap[id];
-          return action;
-        });
-      },
-    }) as RevertDeepSignal<Node<TData, TProperties>>;
-
-    // Only actions added at this stage are available to subsequent builders.
-    // `addNode` immediately passes the new node to other builders.
-    // As such, actions added later with `addAction` are not available to those builders.
-    // Having actions available to subsequent builders is useful for building groups.
-    partial.actions && partial.actions.forEach((action) => node.addAction(action));
-
-    return node;
-  }
-
-  private _createAction<TProperties extends Record<string, any> = Record<string, any>>(
-    partial: ActionArg<TProperties>,
-  ): Action<TProperties> {
-    const action: Action<TProperties> = deepSignal({
-      properties: {} as TProperties,
-      ...partial,
-      actionsMap: {},
-      get actions() {
-        return Object.values(action.actionsMap);
-      },
-      addAction: (...partials) => {
-        return untracked(() => {
-          return partials.map((partial) => {
-            const subAction = this._createAction(partial);
-            action.actionsMap[subAction.id] = subAction;
-            return subAction;
-          });
-        });
-      },
-      removeAction: (id) => {
-        return untracked(() => {
-          const subAction = action.actionsMap[id];
-          delete action.actionsMap[id];
-          return subAction;
-        });
-      },
-      addProperty: (key, value) => {
-        return untracked(() => {
-          (action.properties as Record<string, any>)[key] = value;
-        });
-      },
-      removeProperty: (key) => {
-        return untracked(() => {
-          delete (action.properties as Record<string, any>)[key];
-        });
-      },
-    }) as RevertDeepSignal<Action<TProperties>>;
-
-    partial.actions && partial.actions.forEach((subAction) => action.addAction(subAction));
-
-    return action;
-  }
 }