@dxos/app-graph 0.8.4-main.fffef41 → 0.8.4-staging.60fe92afc8

package/src/node.ts

@@ -2,9 +2,30 @@
 // Copyright 2023 DXOS.org
 //
 
-import { type MakeOptional, type MaybePromise } from '@dxos/util';
+import type * as Context from 'effect/Context';
+import type * as Effect from 'effect/Effect';
 
-import { ACTION_GROUP_TYPE, ACTION_TYPE } from './graph';
+import { type MakeOptional } from '@dxos/util';
+
+/**
+ * Root node ID.
+ */
+export const RootId = 'root';
+
+/**
+ * Root node type.
+ */
+export const RootType = 'org.dxos.type.graphRoot';
+
+/**
+ * Action node type.
+ */
+export const ActionType = 'org.dxos.type.graphAction';
+
+/**
+ * Action group node type.
+ */
+export const ActionGroupType = 'org.dxos.type.graphActionGroup';
 
 /**
  * Represents a node in the graph.
@@ -48,7 +69,19 @@ export type NodeFilter<TData = any, TProperties extends Record<string, any> = Re
   connectedNode: Node,
 ) => node is Node<TData, TProperties>;
 
-export type Relation = 'outbound' | 'inbound';
+export type RelationDirection = 'outbound' | 'inbound';
+
+export type Relation = Readonly<{
+  kind: string;
+  direction: RelationDirection;
+}>;
+
+export type RelationInput = Relation | string;
+
+export const relation = (kind: string, direction: RelationDirection = 'outbound'): Relation => ({ kind, direction });
+// TODO(wittjosiah): Consider moving these helpers out of the core API.
+export const childRelation = (direction: RelationDirection = 'outbound'): Relation => relation('child', direction);
+export const actionRelation = (direction: RelationDirection = 'outbound'): Relation => relation('action', direction);
 
 export const isGraphNode = (data: unknown): data is Node =>
   data && typeof data === 'object' && 'id' in data && 'properties' in data && data.properties
@@ -63,30 +96,45 @@ export type NodeArg<TData, TProperties extends Record<string, any> = Record<stri
   nodes?: NodeArg<unknown>[];
 
   /** Will automatically add specified edges. */
-  edges?: [string, Relation][];
+  edges?: [string, RelationInput][];
 };
 
 //
 // Actions
 //
 
-export type InvokeParams = {
+export type InvokeProps = {
   /** Node the invoked action is connected to. */
   parent?: Node;
 
+  /** Path from root to the node in the current tree context. */
+  path?: string[];
+
   caller?: string;
 };
 
-export type ActionData = (params?: InvokeParams) => MaybePromise<void>;
+/**
+ * Action data is an Effect-returning function.
+ * The Effect is provided with captured context at execution time.
+ */
+export type ActionData<R = never> = (params?: InvokeProps) => Effect.Effect<any, Error, R>;
+
+/**
+ * Context captured at extension creation time.
+ * Automatically provided to action Effects at execution.
+ */
+export type ActionContext = Context.Context<any>;
 
 export type Action<TProperties extends Record<string, any> = Record<string, any>> = Readonly<
   Omit<Node<ActionData, TProperties>, 'properties'> & {
     properties: Readonly<TProperties>;
+    /** Captured context from extension creation. Provided automatically at action execution. */
+    _actionContext?: ActionContext;
   }
 >;
 
 export const isAction = (data: unknown): data is Action =>
-  isGraphNode(data) ? typeof data.data === 'function' && data.type === ACTION_TYPE : false;
+  isGraphNode(data) ? typeof data.data === 'function' && data.type === ActionType : false;
 
 export const actionGroupSymbol = Symbol('ActionGroup');
 
@@ -97,8 +145,34 @@ export type ActionGroup<TProperties extends Record<string, any> = Record<string,
 >;
 
 export const isActionGroup = (data: unknown): data is ActionGroup =>
-  isGraphNode(data) ? data.data === actionGroupSymbol && data.type === ACTION_GROUP_TYPE : false;
+  isGraphNode(data) ? data.data === actionGroupSymbol && data.type === ActionGroupType : false;
 
 export type ActionLike = Action | ActionGroup;
 
 export const isActionLike = (data: unknown): data is Action | ActionGroup => isAction(data) || isActionGroup(data);
+
+//
+// Node Factories
+//
+
+/** Typed factory for constructing a NodeArg. Provides auto-complete and type validation. */
+export const make = <TData = any, TProperties extends Record<string, any> = Record<string, any>>(
+  arg: NodeArg<TData, TProperties>,
+): NodeArg<TData, TProperties> => arg;
+
+/** Create an action node. Automatically sets `type: ActionType`. */
+export const makeAction = <R = never>(
+  arg: Omit<NodeArg<ActionData<R>>, 'type' | 'nodes' | 'edges'>,
+): NodeArg<ActionData<R>> => ({
+  ...arg,
+  type: ActionType,
+});
+
+/** Create an action group node. Automatically sets `type` and `data`. */
+export const makeActionGroup = (
+  arg: Omit<NodeArg<typeof actionGroupSymbol>, 'type' | 'data' | 'nodes' | 'edges'>,
+): NodeArg<typeof actionGroupSymbol> => ({
+  ...arg,
+  type: ActionGroupType,
+  data: actionGroupSymbol,
+});

package/src/scheduler.browser.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export { scheduleTask, yieldOrContinue } from 'main-thread-scheduling';

package/src/scheduler.ts

@@ -0,0 +1,17 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// CF Workers / Node fallback: there is no main thread to yield to.
+// scheduleTask runs the callback on the next microtask; yieldOrContinue is a microtask hop.
+
+type ScheduleOptions = { strategy?: 'smooth' | 'interactive' | 'idle'; signal?: AbortSignal };
+
+export const scheduleTask = async <T>(callback: () => T | Promise<T>, _options?: ScheduleOptions): Promise<T> => {
+  await Promise.resolve();
+  return callback();
+};
+
+export const yieldOrContinue = async (_priority: 'smooth' | 'interactive' | 'idle'): Promise<void> => {
+  await Promise.resolve();
+};

package/src/stories/EchoGraph.stories.tsx

@@ -6,34 +6,24 @@ import { Atom, type Registry, RegistryContext, useAtomValue } from '@effect-atom
 import { type Meta, type StoryObj } from '@storybook/react-vite';
 import * as Function from 'effect/Function';
 import * as Option from 'effect/Option';
-import React, { type PropsWithChildren, useCallback, useContext, useEffect, useMemo, useState } from 'react';
-
-import {
-  Expando,
-  Filter,
-  type Live,
-  Query,
-  type QueryResult,
-  type Space,
-  SpaceState,
-  isSpace,
-  live,
-} from '@dxos/client/echo';
-import { Obj, Type } from '@dxos/echo';
-import { faker } from '@dxos/random';
+import React, { type PropsWithChildren, useCallback, useContext, useEffect, useMemo, useRef, useState } from 'react';
+
+import { type Space, SpaceState, isSpace } from '@dxos/client/echo';
+import { Filter, Obj, Query } from '@dxos/echo';
+import { TestSchema } from '@dxos/echo/testing';
+import { random } from '@dxos/random';
 import { type Client, useClient } from '@dxos/react-client';
 import { withClientProvider } from '@dxos/react-client/testing';
 import { Icon, IconButton, Input, Select } from '@dxos/react-ui';
+import { Path, Tree, type TreeModel } from '@dxos/react-ui-list';
 import { withTheme } from '@dxos/react-ui/testing';
-import { Path, Tree } from '@dxos/react-ui-list';
-import { getSize, mx } from '@dxos/react-ui-theme';
-import { byPosition, isNonNullable, safeParseInt } from '@dxos/util';
-
-import { type ExpandableGraph, ROOT_ID } from '../graph';
-import { GraphBuilder, atomFromObservable, createExtension } from '../graph-builder';
-import { type Node } from '../node';
-import { atomFromQuery } from '../testing';
+import { getSize, mx } from '@dxos/ui-theme';
+import { safeParseInt } from '@dxos/util';
 
+import * as CreateAtom from '../atoms';
+import * as Graph from '../graph';
+import * as GraphBuilder from '../graph-builder';
+import * as Node from '../node';
 import { JsonTree } from './Tree';
 
 const DEFAULT_PERIOD = 500;
@@ -56,48 +46,47 @@ const actionWeights = {
   [Action.RENAME_OBJECT]: 4,
 };
 
-const createGraph = (client: Client, registry: Registry.Registry): ExpandableGraph => {
-  const spaceBuilderExtension = createExtension({
+const createGraph = (client: Client, registry: Registry.Registry): Graph.ExpandableGraph => {
+  const spaceBuilderExtension = GraphBuilder.createExtensionRaw({
     id: 'space',
     connector: (node) =>
       Atom.make((get) =>
         Function.pipe(
           get(node),
-          Option.flatMap((node) => (node.id === ROOT_ID ? Option.some(node) : Option.none())),
+          Option.flatMap((node) => (node.id === Node.RootId ? Option.some(node) : Option.none())),
           Option.map(() => {
-            const spaces = get(atomFromObservable(client.spaces)) ?? [];
+            const spaces = get(CreateAtom.fromObservable(client.spaces)) ?? [];
             return spaces
-              .filter((space) => get(atomFromObservable(space.state)) === SpaceState.SPACE_READY)
-              .map((space) => ({
-                id: space.id,
-                type: 'dxos.org/type/Space',
-                properties: {
-                  label: get(atomFromObservable(space.properties.name)),
-                },
-                data: space,
-              }));
+              .filter((space: any) => get(CreateAtom.fromObservable(space.state)) === SpaceState.SPACE_READY)
+              .map((space) => {
+                const propertiesSnapshot = get(Obj.atom(space.properties));
+                return {
+                  id: space.id,
+                  type: 'org.dxos.type.space',
+                  properties: {
+                    label: propertiesSnapshot.name,
+                  },
+                  data: space,
+                };
+              });
           }),
           Option.getOrElse(() => []),
         ),
       ),
   });
 
-  const objectBuilderExtension = createExtension({
+  const objectBuilderExtension = GraphBuilder.createExtensionRaw({
     id: 'object',
     connector: (node) => {
-      let query: QueryResult<Live<Expando>> | undefined;
       return Atom.make((get) =>
         Function.pipe(
           get(node),
           Option.flatMap((node) => (isSpace(node.data) ? Option.some(node.data) : Option.none())),
           Option.map((space) => {
-            if (!query) {
-              query = space.db.query(Query.type(Expando, { type: 'test' }));
-            }
-            const objects = get(atomFromQuery(query));
+            const objects = get(space.db.query(Query.type(TestSchema.Expando, { type: 'test' })).atom);
             return objects.map((object) => ({
               id: object.id,
-              type: 'dxos.org/type/test',
+              type: 'org.dxos.type.test',
               properties: { label: object.name },
               data: object,
             }));
@@ -108,15 +97,15 @@ const createGraph = (client: Client, registry: Registry.Registry): ExpandableGra
     },
   });
 
-  const graph = new GraphBuilder({ registry })
-    .addExtension(spaceBuilderExtension)
-    .addExtension(objectBuilderExtension).graph;
+  const builder = GraphBuilder.make({ registry });
+  GraphBuilder.addExtension(builder, spaceBuilderExtension);
+  GraphBuilder.addExtension(builder, objectBuilderExtension);
+  const graph = builder.graph;
   graph.onNodeChanged.on(({ id }) => {
-    graph.expand(id);
+    Graph.expand(graph, id, 'child');
   });
-  graph.expand(ROOT_ID);
+  Graph.expand(graph, Node.RootId, 'child');
   (window as any).graph = graph;
-
   return graph;
 };
 
@@ -136,9 +125,9 @@ const getRandomSpace = (client: Client): Space | undefined => {
 const getSpaceWithObjects = async (client: Client): Promise<Space | undefined> => {
   const readySpaces = client.spaces.get().filter((space) => space.state.get() === SpaceState.SPACE_READY);
   const spaceQueries = await Promise.all(
-    readySpaces.map((space) => space.db.query(Filter.type(Expando, { type: 'test' })).run()),
+    readySpaces.map((space) => space.db.query(Filter.type(TestSchema.Expando, { type: 'test' })).run()),
   );
-  const spaces = readySpaces.filter((space, index) => spaceQueries[index].objects.length > 0);
+  const spaces = readySpaces.filter((space, index) => spaceQueries[index].length > 0);
   return spaces[Math.floor(Math.random() * spaces.length)];
 };
 
@@ -155,16 +144,18 @@ const runAction = async (client: Client, action: Action) => {
     case Action.RENAME_SPACE: {
       const space = getRandomSpace(client);
       if (space) {
-        space.properties.name = faker.commerce.productName();
+        Obj.update(space.properties, (obj) => {
+          obj.name = random.commerce.productName();
+        });
       }
       break;
     }
 
     case Action.ADD_OBJECT:
       getRandomSpace(client)?.db.add(
-        Obj.make(Type.Expando, {
+        Obj.make(TestSchema.Expando, {
           type: 'test',
-          name: faker.commerce.productName(),
+          name: random.commerce.productName(),
         }),
       );
       break;
@@ -172,7 +163,7 @@ const runAction = async (client: Client, action: Action) => {
     case Action.REMOVE_OBJECT: {
       const space = await getSpaceWithObjects(client);
       if (space) {
-        const { objects } = await space.db.query(Filter.type(Expando, { type: 'test' })).run();
+        const objects = await space.db.query(Filter.type(TestSchema.Expando, { type: 'test' })).run();
         space.db.remove(objects[Math.floor(Math.random() * objects.length)]);
       }
       break;
@@ -181,8 +172,11 @@ const runAction = async (client: Client, action: Action) => {
     case Action.RENAME_OBJECT: {
       const space = await getSpaceWithObjects(client);
       if (space) {
-        const { objects } = await space.db.query(Filter.type(Expando, { type: 'test' })).run();
-        objects[Math.floor(Math.random() * objects.length)].name = faker.commerce.productName();
+        const objects = await space.db.query(Filter.type(TestSchema.Expando, { type: 'test' })).run();
+        const object = objects[Math.floor(Math.random() * objects.length)];
+        Obj.update(object, (object) => {
+          object.name = random.commerce.productName();
+        });
       }
       break;
     }
@@ -220,14 +214,13 @@ const Controls = ({ children }: PropsWithChildren) => {
           <Input.Root>
             <Input.TextInput
               autoComplete='off'
-              size={5}
-              classNames='is-[100px] text-right pie-[22px]'
+              classNames='w-[100px] text-right pe-[22px]'
               placeholder='Interval'
               value={actionInterval}
               onChange={({ target: { value } }) => setActionInterval(value)}
             />
           </Input.Root>
-          <Icon icon='ph--timer--regular' classNames={mx('absolute inline-end-1 block-start-1 mt-[6px]', getSize(3))} />
+          <Icon icon='ph--timer--regular' classNames={mx('absolute right-1 top-1 mt-[6px]', getSize(3))} />
         </div>
         <IconButton icon='ph--plus--regular' label='Add' onClick={() => action && runAction(client, action)} />
         <Select.Root value={action?.toString()} onValueChange={(action) => setAction(action as unknown as Action)}>
@@ -256,9 +249,10 @@ const Controls = ({ children }: PropsWithChildren) => {
 const meta = {
   title: 'sdk/app-graph/EchoGraph',
   decorators: [
-    withTheme,
+    withTheme(),
     withClientProvider({
       createIdentity: true,
+      types: [TestSchema.Expando],
       onCreateIdentity: async ({ client }) => {
         await client.spaces.create();
         await client.spaces.create();
@@ -292,94 +286,129 @@ export const TreeView: Story = {
     const client = useClient();
     const registry = useContext(RegistryContext);
     const graph = useMemo(() => createGraph(client, registry), [client, registry]);
-    const state = useMemo(() => new Map<string, Live<{ open: boolean; current: boolean }>>(), []);
-
-    const useItems = useCallback(
-      (node?: Node, options?: { disposition?: string; sort?: boolean }) => {
-        const connections = useAtomValue(graph.connections(node?.id ?? ROOT_ID));
-        return options?.sort ? connections.toSorted((a, b) => byPosition(a.properties, b.properties)) : connections;
+    const stateRef = useRef(new Map<string, Atom.Writable<{ open: boolean; current: boolean }>>());
+
+    const getOrCreateState = useMemo(
+      () => (pathKey: string) => {
+        let atom = stateRef.current.get(pathKey);
+        if (!atom) {
+          atom = Atom.make({ open: true, current: false }).pipe(Atom.keepAlive);
+          stateRef.current.set(pathKey, atom);
+        }
+        return atom;
       },
+      [],
+    );
+
+    const childIdsFamily = useMemo(
+      () =>
+        Atom.family((id: string) =>
+          Atom.make((get) => {
+            const connections = get(graph.connections(id, 'child'));
+            return connections.map((connection) => connection.id);
+          }),
+        ),
       [graph],
     );
 
-    const getProps = useCallback(
-      (node: Node, path: string[]) => {
-        const children = graph
-          .getConnections(node.id, 'outbound')
-          .map((n) => {
-            // Break cycles.
-            const nextPath = [...path, node.id];
-            return nextPath.includes(n.id) ? undefined : (n as Node);
-          })
-          .filter(isNonNullable) as Node[];
-        const parentOf =
-          children.length > 0 ? children.map(({ id }) => id) : node.properties.role === 'branch' ? [] : undefined;
-        return {
-          id: node.id,
-          label: node.id,
-          icon: node.type === 'dxos.org/type/Space' ? 'ph--planet--regular' : 'ph--placeholder--regular',
-          parentOf,
-        };
-      },
+    const itemFamily = useMemo(
+      () =>
+        Atom.family((id: string) =>
+          Atom.make((get) => {
+            const node = get(graph.node(id));
+            return Option.isSome(node) ? node.value : undefined;
+          }),
+        ),
       [graph],
     );
 
-    const isOpen = useCallback(
-      (_path: string[]) => {
-        const path = Path.create(..._path);
-        const object = state.get(path) ?? live({ open: true, current: false });
-        if (!state.has(path)) {
-          state.set(path, object);
-        }
+    const itemPropsFamily = useMemo(
+      () =>
+        Atom.family((pathKey: string) => {
+          const path = pathKey.split('~');
+          const id = path[path.length - 1];
+          return Atom.make((get) => {
+            const nodeOpt = get(graph.node(id));
+            const node = Option.isSome(nodeOpt) ? nodeOpt.value : undefined;
+            if (!node) {
+              return { id, label: id };
+            }
+            const connections = get(graph.connections(node.id, 'child'));
+            const safeChildren = connections.filter((n) => !path.includes(n.id));
+            const parentOf =
+              safeChildren.length > 0
+                ? safeChildren.map(({ id }) => id)
+                : node.properties.role === 'branch'
+                  ? []
+                  : undefined;
+            return {
+              id: node.id,
+              label: node.id,
+              icon: node.type === 'org.dxos.type.space' ? 'ph--planet--regular' : 'ph--circle-dashed--regular',
+              parentOf,
+            };
+          });
+        }),
+      [graph],
+    );
 
-        return object.open;
-      },
-      [state],
+    const itemOpenFamily = useMemo(
+      () =>
+        Atom.family((pathKey: string) => {
+          const stateAtom = getOrCreateState(pathKey);
+          return Atom.make((get) => get(stateAtom).open);
+        }),
+      [getOrCreateState],
     );
 
-    const isCurrent = useCallback(
-      (_path: string[]) => {
-        const path = Path.create(..._path);
-        const object = state.get(path) ?? live({ open: false, current: false });
-        if (!state.has(path)) {
-          state.set(path, object);
-        }
+    const itemCurrentFamily = useMemo(
+      () =>
+        Atom.family((pathKey: string) => {
+          const stateAtom = getOrCreateState(pathKey);
+          return Atom.make((get) => get(stateAtom).current);
+        }),
+      [getOrCreateState],
+    );
 
-        return object.current;
-      },
-      [state],
+    const model: TreeModel<Node.Node> = useMemo(
+      () => ({
+        childIds: (parentId?: string) => childIdsFamily(parentId ?? Node.RootId),
+        item: (id: string) => itemFamily(id),
+        itemProps: (path: string[]) => itemPropsFamily(path.join('~')),
+        itemOpen: (path: string[]) => itemOpenFamily(Path.create(...path)),
+        itemCurrent: (path: string[]) => itemCurrentFamily(Path.create(...path)),
+      }),
+      [childIdsFamily, itemFamily, itemPropsFamily, itemOpenFamily, itemCurrentFamily],
     );
 
     const onOpenChange = useCallback(
       ({ path: _path, open }: { path: string[]; open: boolean }) => {
         const path = Path.create(..._path);
-        const object = state.get(path);
-        object!.open = open;
+        const atom = stateRef.current.get(path);
+        if (atom) {
+          const prev = registry.get(atom);
+          registry.set(atom, { ...prev, open });
+        }
       },
-      [state],
+      [registry],
     );
 
     const onSelect = useCallback(
       ({ path: _path, current }: { path: string[]; current: boolean }) => {
         const path = Path.create(..._path);
-        const object = state.get(path);
-        object!.current = current;
+        const atom = stateRef.current.get(path);
+        if (atom) {
+          const prev = registry.get(atom);
+          registry.set(atom, { ...prev, current });
+        }
       },
-      [state],
+      [registry],
     );
 
     return (
       <>
         <Controls />
-        <Tree
-          id={ROOT_ID}
-          useItems={useItems}
-          getProps={getProps}
-          isOpen={isOpen}
-          isCurrent={isCurrent}
-          onOpenChange={onOpenChange}
-          onSelect={onSelect}
-        />
+        <Tree model={model} id={Node.RootId} onOpenChange={onOpenChange} onSelect={onSelect} />
       </>
     );
   },

package/src/stories/Tree.tsx

@@ -4,7 +4,7 @@
 
 import React, { type FC, type HTMLAttributes, useState } from 'react';
 
-import { mx } from '@dxos/react-ui-theme';
+import { mx } from '@dxos/ui-theme';
 
 // TODO(burdon): Copied form devtools.
 
@@ -72,7 +72,7 @@ const Scalar: FC<{ value: any }> = ({ value }) => {
 
 const Box: FC<HTMLAttributes<HTMLDivElement>> = ({ children, className, ...props }) => {
   return (
-    <div className={mx('flex pli-2 border border-l-0 font-mono truncate', className)} {...props}>
+    <div className={mx('flex px-2 border border-l-0 font-mono truncate', className)} {...props}>
       {children}
     </div>
   );

package/src/testing/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './setup-graph-builder';

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

@@ -0,0 +1,41 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Registry } from '@effect-atom/atom-react';
+import * as Option from 'effect/Option';
+
+import * as Graph from '../graph';
+import * as GraphBuilder from '../graph-builder';
+import * as Node from '../node';
+
+export type SetupGraphBuilderOptions = {
+  registry?: Registry.Registry;
+  extensions?: GraphBuilder.BuilderExtensions;
+};
+
+export const setupGraphBuilder = ({ registry = Registry.make(), extensions }: SetupGraphBuilderOptions = {}) => {
+  const builder = GraphBuilder.make({ registry });
+  const graph = builder.graph;
+
+  if (extensions) {
+    GraphBuilder.addExtension(builder, extensions);
+  }
+
+  return {
+    registry,
+    builder,
+    graph,
+    addExtensions: (nextExtensions: GraphBuilder.BuilderExtensions) => {
+      GraphBuilder.addExtension(builder, nextExtensions);
+    },
+    expand: async (id: string, relation: Node.RelationInput = 'child') => {
+      Graph.expand(graph, id, relation);
+      await GraphBuilder.flush(builder);
+    },
+    flush: () => GraphBuilder.flush(builder),
+    getConnections: (id: string, relation: Node.RelationInput = 'child') =>
+      registry.get(graph.connections(id, relation)),
+    getNode: (id: string) => Graph.getNode(graph, id).pipe(Option.getOrNull),
+  };
+};