@dxos/app-graph 0.3.3-main.052ad73

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

@@ -0,0 +1,71 @@
+import type { IconProps } from '@phosphor-icons/react';
+import { type FC } from 'react';
+import type { UnsubscribeCallback } from '@dxos/async';
+import { 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 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.
+     *
+     * @example { index: 'a1' }
+     */
+    properties: TProperties;
+    /**
+     * Data the node represents.
+     */
+    data: TData;
+    /**
+     * Children of the node stored by their id.
+     */
+    childrenMap: Record<string, Node>;
+    /**
+     * Actions of the node stored by their id.
+     */
+    actionsMap: Record<string, Action>;
+    /**
+     * Children of the node in default order.
+     */
+    get children(): Node[];
+    /**
+     * Actions of the node in default order.
+     */
+    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: (Pick<Node, 'id' | 'label'> & Partial<Node<TChildData, TChildProperties>>)[]): Node<TChildData, TChildProperties>[];
+    removeNode(id: string): Node;
+    addAction<TActionProperties extends Record<string, any> = Record<string, any>>(...action: (Pick<Action, 'id' | 'label' | 'invoke'> & Partial<Action<TActionProperties>>)[]): Action<TActionProperties>[];
+    removeAction(id: string): Action;
+};
+//# sourceMappingURL=node.d.ts.map

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

@@ -0,0 +1 @@
+{"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,MAAM,EAAE,KAAK,KAAK,EAAE,MAAM,UAAU,CAAC;AAEnD;;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;;;;OAIG;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,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,UAAU,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAAE,GACpF,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,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,GAAG,OAAO,GAAG,QAAQ,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC,CAAC,EAAE,GAC1F,MAAM,CAAC,iBAAiB,CAAC,EAAE,CAAC;IAC/B,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC;CAClC,CAAC"}

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

@@ -0,0 +1,10 @@
+import '@dxosTheme';
+declare const _default: {
+    title: string;
+};
+export default _default;
+export declare const EchoGraph: {
+    render: () => JSX.Element;
+    decorators: import("@storybook/csf").DecoratorFunction<import("@storybook/react/dist/types-0a347bb9").R, any>[];
+};
+//# sourceMappingURL=EchoGraph.stories.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"EchoGraph.stories.d.ts","sourceRoot":"","sources":["../../../../src/stories/EchoGraph.stories.tsx"],"names":[],"mappings":"AAIA,OAAO,YAAY,CAAC;;;;AAkBpB,wBAEE;AA6MF,eAAO,MAAM,SAAS;;;CAGrB,CAAC"}

package/dist/types/src/stories/Tree.d.ts

@@ -0,0 +1,14 @@
+import { type FC } from 'react';
+export declare const Tree: FC<{
+    data?: object;
+}>;
+export declare const Node: FC<{
+    data?: any;
+    root?: boolean;
+}>;
+export declare const KeyValue: FC<{
+    label: string;
+    data?: any;
+    className?: string;
+}>;
+//# sourceMappingURL=Tree.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Tree.d.ts","sourceRoot":"","sources":["../../../../src/stories/Tree.tsx"],"names":[],"mappings":"AAIA,OAAc,EAAE,KAAK,EAAE,EAAiC,MAAM,OAAO,CAAC;AAMtE,eAAO,MAAM,IAAI,EAAE,EAAE,CAAC;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAMtC,CAAC;AAEF,eAAO,MAAM,IAAI,EAAE,EAAE,CAAC;IAAE,IAAI,CAAC,EAAE,GAAG,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,CAsBnD,CAAC;AAEF,eAAO,MAAM,QAAQ,EAAE,EAAE,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,GAAG,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,CAiB1E,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

@@ -0,0 +1,74 @@
+{
+  "name": "@dxos/app-graph",
+  "version": "0.3.3-main.052ad73",
+  "description": "Constructs knowledge graphs for the purpose of building applications on top of",
+  "homepage": "https://dxos.org",
+  "bugs": "https://github.com/dxos/dxos/issues",
+  "license": "MIT",
+  "author": "DXOS.org",
+  "exports": {
+    ".": {
+      "browser": "./dist/lib/browser/index.mjs",
+      "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"
+  ],
+  "dependencies": {
+    "@preact/signals-react": "^1.3.6",
+    "deepsignal": "^1.3.6",
+    "lodash.get": "^4.4.2",
+    "lodash.set": "^4.3.2",
+    "mousetrap": "^1.6.5",
+    "@dxos/async": "0.3.3-main.052ad73",
+    "@dxos/debug": "0.3.3-main.052ad73",
+    "@dxos/invariant": "0.3.3-main.052ad73",
+    "@dxos/util": "0.3.3-main.052ad73"
+  },
+  "devDependencies": {
+    "@faker-js/faker": "^8.0.2",
+    "@phosphor-icons/react": "^2.0.5",
+    "@tldraw/indices": "2.0.0-alpha.14",
+    "@types/lodash.get": "^4.4.7",
+    "@types/lodash.set": "^4.3.7",
+    "@types/mousetrap": "^1.6.11",
+    "@types/react": "^18.0.21",
+    "@types/react-dom": "^18.0.6",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "vite": "^4.3.9",
+    "@dxos/react-client": "0.3.3-main.052ad73",
+    "@dxos/react-surface": "0.3.3-main.052ad73",
+    "@dxos/react-ui": "0.3.3-main.052ad73",
+    "@dxos/react-ui-theme": "0.3.3-main.052ad73"
+  },
+  "peerDependencies": {
+    "@phosphor-icons/react": "^2.0.5",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "@dxos/react-surface": "0.3.3-main.052ad73",
+    "@dxos/react-ui": "0.3.3-main.052ad73",
+    "@dxos/react-ui-theme": "0.3.3-main.052ad73"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/action.ts

@@ -0,0 +1,69 @@
+//
+// 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 }];
+
+/**
+ * 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.
+   * NOTE: Alphanumeric characters should be declared in lowercase.
+   */
+  keyBinding?: string;
+
+  /**
+   * 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: () => MaybePromise<any>;
+
+  addProperty(key: string, value: any): void;
+  removeProperty(key: string): void;
+
+  addAction<TActionProperties extends Record<string, any> = Record<string, any>>(
+    ...action: (Pick<Action, 'id' | 'label' | 'invoke'> & Partial<Action<TActionProperties>>)[]
+  ): Action<TActionProperties>[];
+  removeAction(id: string): Action;
+};

package/src/graph-builder.ts

@@ -0,0 +1,200 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { untracked } from '@preact/signals-react';
+import { type RevertDeepSignal, deepSignal } from 'deepsignal/react';
+import Mousetrap from 'mousetrap';
+
+import { EventSubscriptions } from '@dxos/async';
+
+import { type Action } from './action';
+import { Graph } from './graph';
+import { type Node, type NodeBuilder } from './node';
+
+/**
+ * The builder...
+ */
+export class GraphBuilder {
+  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.
+   */
+  addNodeBuilder(id: string, builder: NodeBuilder): GraphBuilder {
+    this._nodeBuilders.set(id, builder);
+    return this;
+  }
+
+  /**
+   * Remove a node builder from the graph builder.
+   */
+  removeNodeBuilder(id: string): GraphBuilder {
+    this._nodeBuilders.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.
+   * @param root
+   * @param path
+   */
+  build(root?: Node, path: string[] = []): Graph {
+    const graph: Graph = new Graph(root ?? this._createNode(() => graph, { id: 'root', label: 'Root' }));
+    return this._build(graph, graph.root, path);
+  }
+
+  /**
+   * 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();
+
+    Array.from(this._nodeBuilders.entries())
+      .filter(([id]) => ignoreBuilders.findIndex((ignore) => ignore === id) === -1)
+      .forEach(([_, builder]) => {
+        const unsubscribe = builder(node);
+        unsubscribe && subscriptions.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: Pick<Node, 'id' | 'label'> & Partial<Node<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,
+
+      // TODO(wittjosiah): Default sort.
+      get children() {
+        return Object.values(node.childrenMap);
+      },
+      get actions() {
+        return Object.values(node.actionsMap);
+      },
+
+      addProperty: (key, value) => {
+        untracked(() => {
+          (node.properties as Record<string, any>)[key] = value;
+        });
+      },
+      removeProperty: (key) => {
+        untracked(() => {
+          delete (node.properties as Record<string, any>)[key];
+        });
+      },
+
+      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;
+            // TOOD(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;
+        });
+      },
+
+      addAction: (...partials) => {
+        return untracked(() => {
+          return partials.map((partial) => {
+            const action = this._createAction(partial);
+            if (action.keyBinding) {
+              Mousetrap.bind(action.keyBinding, () => {
+                action.invoke();
+              });
+            }
+
+            node.actionsMap[action.id] = action;
+            return action;
+          });
+        });
+      },
+      removeAction: (id) => {
+        return untracked(() => {
+          const action = node.actionsMap[id];
+          if (action.keyBinding) {
+            Mousetrap.unbind(action.keyBinding);
+          }
+
+          delete node.actionsMap[id];
+          return action;
+        });
+      },
+    }) as RevertDeepSignal<Node<TData, TProperties>>;
+
+    return node;
+  }
+
+  private _createAction<TProperties extends Record<string, any> = Record<string, any>>(
+    partial: Pick<Action, 'id' | 'label' | 'invoke'> & Partial<Action<TProperties>>,
+  ): Action<TProperties> {
+    const action: Action<TProperties> = deepSignal({
+      properties: {} as TProperties,
+      actionsMap: {},
+      ...partial,
+      // TODO(wittjosiah): Default sort.
+      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>>;
+
+    return action;
+  }
+}