@dxos/app-graph 0.4.7-main.d28a540 → 0.4.7-main.e015b9e

package/dist/types/src/node.d.ts

@@ -1,12 +1,40 @@
-import { type MaybePromise, type MakeOptional } from '@dxos/util';
+import type { IconProps } from '@phosphor-icons/react';
+import { type FC } from 'react';
+import type { UnsubscribeCallback } from '@dxos/async';
+import { type ActionArg, type Action, type Label } from './action';
+/**
+ * Called when a node is added to the graph, allowing other node builders to add children, actions or properties.
+ */
+export type NodeBuilder = (parent: Node) => UnsubscribeCallback | void;
 /**
  * Represents a node in the graph.
  */
-export type NodeBase<TData = any, TProperties extends Record<string, any> = Record<string, any>> = {
+export type Node<TData = any, TProperties extends Record<string, any> = Record<string, any>> = {
     /**
      * Globally unique ID.
      */
     id: string;
+    /**
+     * Parent node in the graph.
+     */
+    parent: Node | null;
+    /**
+     * Label to be used when displaying the node.
+     * For default labels, use a translated string.
+     *
+     * @example 'My Node'
+     * @example ['unknown node label, { ns: 'example-plugin' }]
+     */
+    label: Label;
+    /**
+     * Description to be used when displaying a detailed view of the node.
+     * For default descriptions, use a translated string.
+     */
+    description?: Label;
+    /**
+     * Icon to be used when displaying the node.
+     */
+    icon?: FC<IconProps>;
     /**
      * Properties of the node relevant to displaying the node.
      */
@@ -15,69 +43,31 @@ export type NodeBase<TData = any, TProperties extends Record<string, any> = Reco
      * Data the node represents.
      */
     data: TData;
-};
-export type NodeFilter<T = any, U extends Record<string, any> = Record<string, any>> = (node: Node<unknown, Record<string, any>>, connectedNode: Node) => node is Node<T, U>;
-export type EdgeDirection = 'outbound' | 'inbound';
-export type ConnectedNodes = {
     /**
-     * Edges that this node is connected to in default order.
+     * Children of the node stored by their id.
      */
-    edges(params?: {
-        direction?: EdgeDirection;
-    }): Readonly<string[]>;
+    childrenMap: Record<string, Node>;
     /**
-     * Nodes that this node is connected to in default order.
+     * Actions of the node stored by their id.
      */
-    nodes<T = any, U extends Record<string, any> = Record<string, any>>(params?: {
-        direction?: EdgeDirection;
-        filter?: NodeFilter<T, U>;
-    }): Node<T>[];
+    actionsMap: Record<string, Action>;
     /**
-     * Get a specific connected node by id.
+     * Children of the node in default order.
      */
-    node(id: string): Node | undefined;
-};
-export type ConnectedActions = {
+    get children(): Node[];
     /**
-     * Actions or action groups that this node is connected to in default order.
+     * Actions of the node in default order.
      */
-    actions(): ActionLike[];
-};
-export type Node<TData = any, TProperties extends Record<string, any> = Record<string, any>> = Readonly<Omit<NodeBase<TData, TProperties>, 'properties'> & {
-    properties: Readonly<TProperties>;
-} & ConnectedNodes & ConnectedActions>;
-export declare const isGraphNode: (data: unknown) => data is Readonly<Omit<NodeBase<any, Record<string, any>>, "properties"> & {
-    properties: Readonly<Record<string, any>>;
-} & ConnectedNodes & ConnectedActions>;
-export type NodeArg<TData, TProperties extends Record<string, any> = Record<string, any>> = MakeOptional<NodeBase<TData, TProperties>, 'data' | 'properties'> & {
-    /** Will automatically add nodes with an edge from this node to each. */
-    nodes?: NodeArg<unknown>[];
-    /** Will automatically add specified edges. */
-    edges?: [string, EdgeDirection][];
+    get actions(): Action[];
+    addProperty(key: string, value: any): void;
+    removeProperty(key: string): void;
+    addNode<TChildData = null, TChildProperties extends Record<string, any> = Record<string, any>>(id: string, ...node: NodeArg<TChildData, TChildProperties>[]): Node<TChildData, TChildProperties>[];
+    removeNode(id: string): Node;
+    addAction<TActionProperties extends Record<string, any> = Record<string, any>>(...action: ActionArg<TActionProperties>[]): Action<TActionProperties>[];
+    removeAction(id: string): Action;
 };
-export type InvokeParams = {
-    /** Node the invoked action is connected to. */
-    node: Node;
-    caller?: string;
+export type NodeArg<TData = null, TProperties extends Record<string, any> = Record<string, any>> = Pick<Node, 'id' | 'label'> & Partial<Omit<Node<TData, TProperties>, 'id' | 'label' | 'actions'>> & {
+    actions?: ActionArg[];
 };
-export type ActionData = (params: InvokeParams) => MaybePromise<void>;
-export type Action<TProperties extends Record<string, any> = Record<string, any>> = Readonly<Omit<NodeBase<ActionData, TProperties>, 'properties'> & {
-    properties: Readonly<TProperties>;
-} & ConnectedNodes>;
-export declare const isAction: (data: unknown) => data is Readonly<Omit<NodeBase<ActionData, Record<string, any>>, "properties"> & {
-    properties: Readonly<Record<string, any>>;
-} & ConnectedNodes>;
-export declare const actionGroupSymbol: unique symbol;
-export type ActionGroup = Readonly<Omit<NodeBase<typeof actionGroupSymbol, Record<string, any>>, 'properties'> & {
-    properties: Readonly<Record<string, any>>;
-} & ConnectedActions>;
-export declare const isActionGroup: (data: unknown) => data is Readonly<Omit<NodeBase<typeof actionGroupSymbol, Record<string, any>>, "properties"> & {
-    properties: Readonly<Record<string, any>>;
-} & ConnectedActions>;
-export type ActionLike = Action | ActionGroup;
-export declare const isActionLike: (data: unknown) => data is Readonly<Omit<NodeBase<ActionData, Record<string, any>>, "properties"> & {
-    properties: Readonly<Record<string, any>>;
-} & ConnectedNodes> | Readonly<Omit<NodeBase<typeof actionGroupSymbol, Record<string, any>>, "properties"> & {
-    properties: Readonly<Record<string, any>>;
-} & ConnectedActions>;
+export declare const isGraphNode: (data: unknown) => data is Node<any, Record<string, any>>;
 //# sourceMappingURL=node.d.ts.map

package/dist/types/src/node.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../../../src/node.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../../../src/node.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,KAAK,EAAE,EAAE,MAAM,OAAO,CAAC;AAEhC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAEvD,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,MAAM,EAAE,KAAK,KAAK,EAAE,MAAM,UAAU,CAAC;AAEnE;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,MAAM,EAAE,IAAI,KAAK,mBAAmB,GAAG,IAAI,CAAC;AAEvE;;GAEG;AACH,MAAM,MAAM,IAAI,CAAC,KAAK,GAAG,GAAG,EAAE,WAAW,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,IAAI;IAC7F;;OAEG;IACH,EAAE,EAAE,MAAM,CAAC;IAEX;;OAEG;IACH,MAAM,EAAE,IAAI,GAAG,IAAI,CAAC;IAEpB;;;;;;OAMG;IACH,KAAK,EAAE,KAAK,CAAC;IAEb;;;OAGG;IACH,WAAW,CAAC,EAAE,KAAK,CAAC;IAEpB;;OAEG;IACH,IAAI,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,CAAC;IAErB;;OAEG;IAEH,UAAU,EAAE,WAAW,CAAC;IAExB;;OAEG;IAIH,IAAI,EAAE,KAAK,CAAC;IAEZ;;OAEG;IAEH,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAElC;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEnC;;OAEG;IACH,IAAI,QAAQ,IAAI,IAAI,EAAE,CAAC;IAEvB;;OAEG;IACH,IAAI,OAAO,IAAI,MAAM,EAAE,CAAC;IAExB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,GAAG,IAAI,CAAC;IAC3C,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAElC,OAAO,CAAC,UAAU,GAAG,IAAI,EAAE,gBAAgB,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3F,EAAE,EAAE,MAAM,EACV,GAAG,IAAI,EAAE,OAAO,CAAC,UAAU,EAAE,gBAAgB,CAAC,EAAE,GAC/C,IAAI,CAAC,UAAU,EAAE,gBAAgB,CAAC,EAAE,CAAC;IACxC,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAE7B,SAAS,CAAC,iBAAiB,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC3E,GAAG,MAAM,EAAE,SAAS,CAAC,iBAAiB,CAAC,EAAE,GACxC,MAAM,CAAC,iBAAiB,CAAC,EAAE,CAAC;IAC/B,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC;CAClC,CAAC;AAEF,MAAM,MAAM,OAAO,CAAC,KAAK,GAAG,IAAI,EAAE,WAAW,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,IAAI,IAAI,CACrG,IAAI,EACJ,IAAI,GAAG,OAAO,CACf,GACC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,WAAW,CAAC,EAAE,IAAI,GAAG,OAAO,GAAG,SAAS,CAAC,CAAC,GAAG;IAAE,OAAO,CAAC,EAAE,SAAS,EAAE,CAAA;CAAE,CAAC;AAElG,eAAO,MAAM,WAAW,SAAU,OAAO,2CACmC,CAAC"}

package/dist/types/src/stories/EchoGraph.stories.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"EchoGraph.stories.d.ts","sourceRoot":"","sources":["../../../../src/stories/EchoGraph.stories.tsx"],"names":[],"mappings":"AAIA,OAAO,YAAY,CAAC;;;;;AAoBpB,wBAGE;AA6OF,eAAO,MAAM,OAAO;;CAEnB,CAAC"}
+{"version":3,"file":"EchoGraph.stories.d.ts","sourceRoot":"","sources":["../../../../src/stories/EchoGraph.stories.tsx"],"names":[],"mappings":"AAIA,OAAO,YAAY,CAAC;;;;;AAoBpB,wBAGE;AA6MF,eAAO,MAAM,OAAO;;CAEnB,CAAC"}

package/dist/types/src/testing.d.ts

@@ -0,0 +1,52 @@
+import { type Action } from './action';
+import { type Graph } from './graph';
+import { type NodeBuilder, type Node } from './node';
+/**
+ * Create a test node builder that always adds nodes and actions to the specified depth.
+ *
+ * @param id The id of the node builder, used to identify nodes created by this builder.
+ * @param depth The depth at which to add nodes and actions.
+ * @default 1
+ *
+ * @returns A test node builder
+ */
+export declare const createTestNodeBuilder: (id: string, depth?: number) => {
+    nodeBuilder: NodeBuilder;
+    addNode: (parentId: string, node: Pick<Node, 'id' | 'label'> & Partial<Node>) => Node<any, Record<string, any>> | undefined;
+    removeNode: (parentId: string, id: string) => Node<any, Record<string, any>> | undefined;
+    addAction: (parentId: string, action: Pick<Action, 'id' | 'label' | 'invoke'> & Partial<Action>) => Action<Record<string, any>>[] | undefined;
+    removeAction: (parentId: string, id: string) => Action | undefined;
+    addProperty: (parentId: string, key: string, value: any) => void;
+    removeProperty: (parentId: string, key: string) => void;
+};
+/**
+ * Build a graph from a nested list of nodes.
+ *
+ * @param graph Graph to add nodes to.
+ * @param nodes Nodes to add to the
+ *
+ * @example
+ * const graph = new GraphStore();
+ * buildGraph(graph, [
+ *   {
+ *     id: 'test1',
+ *     label: 'test1',
+ *     children: [
+ *       {
+ *         id: 'test1.1',
+ *         label: 'test1.1',
+ *       },
+ *       {
+ *         id: 'test1.2',
+ *         label: 'test1.2',
+ *       },
+ *     ],
+ *   },
+ *   {
+ *     id: 'test2',
+ *     label: 'test2',
+ *   },
+ * ]);
+ */
+export declare const buildGraph: (graph: Graph, id: string, nodes: any[]) => Graph;
+//# sourceMappingURL=testing.d.ts.map

package/dist/types/src/testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../../../src/testing.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,KAAK,WAAW,EAAE,KAAK,IAAI,EAAE,MAAM,QAAQ,CAAC;AAErD;;;;;;;;GAQG;AAEH,eAAO,MAAM,qBAAqB,OAAQ,MAAM;;wBAwBnB,MAAM,QAAQ,KAAK,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,GAAG,QAAQ,IAAI,CAAC;2BAWrD,MAAM,MAAM,MAAM;0BASnB,MAAM,UAAU,KAAK,MAAM,EAAE,IAAI,GAAG,OAAO,GAAG,QAAQ,CAAC,GAAG,QAAQ,MAAM,CAAC;6BAStE,MAAM,MAAM,MAAM;4BASnB,MAAM,OAAO,MAAM,SAAS,GAAG;+BAS5B,MAAM,OAAO,MAAM;CAUtD,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAGH,eAAO,MAAM,UAAU,UAAW,KAAK,MAAM,MAAM,SAAS,GAAG,EAAE,UAGhE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/app-graph",
-  "version": "0.4.7-main.d28a540",
+  "version": "0.4.7-main.e015b9e",
   "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,9 +12,22 @@
       "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"
@@ -22,25 +35,31 @@
   "dependencies": {
     "@preact/signals-core": "^1.5.1",
     "deepsignal": "^1.5.0",
-    "@dxos/async": "0.4.7-main.d28a540",
-    "@dxos/debug": "0.4.7-main.d28a540",
-    "@dxos/invariant": "0.4.7-main.d28a540",
-    "@dxos/util": "0.4.7-main.d28a540"
+    "lodash.get": "^4.4.2",
+    "lodash.set": "^4.3.2",
+    "@dxos/async": "0.4.7-main.e015b9e",
+    "@dxos/debug": "0.4.7-main.e015b9e",
+    "@dxos/invariant": "0.4.7-main.e015b9e",
+    "@dxos/keyboard": "0.4.7-main.e015b9e",
+    "@dxos/util": "0.4.7-main.e015b9e"
   },
   "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.7-main.d28a540",
-    "@dxos/react-client": "0.4.7-main.d28a540",
-    "@dxos/react-ui": "0.4.7-main.d28a540",
-    "@dxos/storybook-utils": "0.4.7-main.d28a540",
-    "@dxos/react-ui-theme": "0.4.7-main.d28a540"
+    "@dxos/react-client": "0.4.7-main.e015b9e",
+    "@dxos/random": "0.4.7-main.e015b9e",
+    "@dxos/react-ui-theme": "0.4.7-main.e015b9e",
+    "@dxos/react-ui": "0.4.7-main.e015b9e",
+    "@dxos/storybook-utils": "0.4.7-main.e015b9e"
   },
   "peerDependencies": {
+    "@phosphor-icons/react": "^2.0.5",
     "react": "^18.2.0",
     "react-dom": "^18.2.0"
   },

package/src/action.ts

@@ -0,0 +1,92 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import type { IconProps } from '@phosphor-icons/react';
+import type { FC } from 'react';
+
+import type { MaybePromise } from '@dxos/util';
+
+// TODO(thure): `Parameters<TFunction>` causes typechecking issues because `TFunction` has so many signatures.
+export type Label = string | [string, { ns: string; count?: number }];
+
+export type InvokeParams = Partial<{
+  caller: string;
+}>;
+
+/**
+ * Platform-specific key binding.
+ */
+// NOTE: Keys come from `getHostPlatform` in `@dxos/util`.
+export type KeyBinding = {
+  windows?: string;
+  macos?: string;
+  ios?: string;
+  linux?: string;
+  unknown?: string;
+};
+
+/**
+ * An action on a node in the graph which may be invoked by sending the associated intent.
+ */
+export type Action<TProperties extends Record<string, any> = Record<string, any>> = {
+  /**
+   * Locally unique ID.
+   */
+  id: string;
+
+  /**
+   * Label to be used when displaying the node.
+   * For default labels, use a translated string.
+   *
+   * @example 'Test Action'
+   * @example ['test action label, { ns: 'example-plugin' }]
+   */
+  label: Label;
+
+  /**
+   * Icon to be used when displaying the node.
+   */
+  icon?: FC<IconProps>;
+
+  /**
+   * Key binding.
+   */
+  // TODO(wittjosiah): Factor out.
+  // TODO(burdon): Rename shortcut.
+  keyBinding?: string | KeyBinding;
+
+  /**
+   * Properties of the node relevant to displaying the action.
+   *
+   * @example { index: 'a1' }
+   */
+  properties: TProperties;
+
+  /**
+   * Sub-actions of the node stored by their id.
+   */
+  actionsMap: Record<string, Action>;
+
+  /**
+   * Actions of the node in default order.
+   */
+  // TODO(burdon): Why get vs. prop?
+  get actions(): Action[];
+
+  invoke: (params?: InvokeParams) => MaybePromise<any>;
+
+  addProperty(key: string, value: any): void;
+  removeProperty(key: string): void;
+
+  addAction<TActionProperties extends Record<string, any> = Record<string, any>>(
+    ...action: ActionArg<TActionProperties>[]
+  ): Action<TActionProperties>[];
+  removeAction(id: string): Action;
+};
+
+export type ActionArg<TProperties extends Record<string, any> = Record<string, any>> = Pick<
+  Action,
+  'id' | 'label' | 'invoke'
+> &
+  Partial<Omit<Action<TProperties>, 'id' | 'label' | 'invoke' | 'actions'>> & { actions?: ActionArg[] };

package/src/graph-builder.ts

@@ -2,50 +2,238 @@
 // Copyright 2023 DXOS.org
 //
 
-import { EventSubscriptions, type UnsubscribeCallback } from '@dxos/async';
+import { untracked } from '@preact/signals-core';
+import { type RevertDeepSignal, deepSignal } from 'deepsignal/react';
 
+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 type BuilderExtension = (graph: Graph) => UnsubscribeCallback | void;
+export const KEY_BINDING = 'KeyBinding';
 
 /**
- * The builder provides an extensible way to compose the construction of the graph.
+ * The builder...
  */
 export class GraphBuilder {
-  private readonly _extensions = new Map<string, BuilderExtension>();
-  private readonly _unsubscribe = new EventSubscriptions();
+  private readonly _nodeBuilders = new Map<string, NodeBuilder>();
+  private readonly _unsubscribe = new Map<string, EventSubscriptions>();
 
   /**
    * Register a node builder which will be called in order to construct the graph.
    */
-  addExtension(id: string, extension: BuilderExtension): GraphBuilder {
-    this._extensions.set(id, extension);
+  addNodeBuilder(id: string, builder: NodeBuilder): GraphBuilder {
+    this._nodeBuilders.set(id, builder);
     return this;
   }
 
   /**
    * Remove a node builder from the graph builder.
    */
-  removeExtension(id: string): GraphBuilder {
-    this._extensions.delete(id);
+  removeNodeBuilder(id: string): GraphBuilder {
+    this._nodeBuilders.delete(id);
     return this;
   }
 
   /**
-   * Construct the graph, starting by calling all registered extensions.
+   * 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.
    * @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.
    */
-  build(previousGraph?: Graph): Graph {
-    // Clear previous extension subscriptions.
-    this._unsubscribe.clear();
+  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();
 
-    const graph: Graph = previousGraph ?? new Graph();
+    Array.from(this._nodeBuilders.entries())
+      .filter(([id]) => ignoreBuilders.findIndex((ignore) => ignore === id) === -1)
+      .forEach(([_, builder]) => {
+        const unsubscribe = builder(node);
+        unsubscribe && subscriptions.add(unsubscribe);
+      });
 
-    Array.from(this._extensions.values()).forEach((builder) => {
-      const unsubscribe = builder(graph);
-      unsubscribe && this._unsubscribe.add(unsubscribe);
-    });
+    this._unsubscribe.set(node.id, subscriptions);
 
     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;
+  }
 }