App Graph

import * as AppGraph from '@dxos/app-graph/AppGraph';
import * as AppGraphBuilder from '@dxos/app-graph/AppGraphBuilder';
import * as AppGraphNode from '@dxos/app-graph/AppGraphNode';
import * as AppNode from '@dxos/app-toolkit/AppNode';

App Graph is a graph of everything a person can open or do in a PLEX app. In Composer, the navigation tree, toolbars, context menus and the command palette all read it, so a plugin that adds to App Graph shows up in all of them.

App Graph comes from the App Toolkit, not the framework: it is how a workspace app such as Composer organizes what plugins add. A PLEX app can run without it.

How App Graph is shaped

A node has an id, a type, data and properties. Its data is usually the thing it stands for, such as a space or an ECHO object; its properties carry the label, icon and display hints. The graph starts from a root node.

Nodes connect by relations. child makes the navigation tree: a space’s children are its sections and objects. action connects a node to the things a person can do to it; an action node’s data is a function that returns an Effect. Other relations, such as companion, attach panels to a node.

A node’s identity is its path: the ids from the root down to it, joined like a URL. GraphPath from @dxos/app-toolkit builds the paths of the common nodes, such as a space or an object in it, and navigation operations take paths. In Composer the address bar shows the open node’s path.

Plugins add nodes through builder extensions. An extension has a matcher and a connector: the matcher picks the nodes it applies to, and the connector returns the nodes to connect to them. For the usual section that lists an object type, TypeSection.createTypeSectionExtension builds the extensions for you, with an address for each object. Stash uses it:

src/capabilities/app-graph-builder.ts

import * as AppNodeMatcher from '@dxos/app-toolkit/AppNodeMatcher';
import * as GraphPath from '@dxos/app-toolkit/GraphPath';
import * as TypeSection from '@dxos/app-toolkit/TypeSection';
import * as Operation from '@dxos/compute/Operation';
import { Obj, Ref } from '@dxos/echo';

import { StashNamespace } from '../namespace.ts';
import { StashedLink } from '../types/StashedLink.ts';
import { MarkRead } from '../types/StashedLinkOperation.ts';

/** A "Stashed links" section in each space's Content group, once it has one. */
const section = TypeSection.createTypeSectionExtension(StashedLink, {
  match: AppNodeMatcher.whenNavTreeGroup(GraphPath.GroupTypes.content),
  groupSegment: GraphPath.GroupSegments.content,
  // The link's address in Composer's URL: `/w/<space>/stash/<id>`.
  urlKey: 'stash',
});

Stash’s App Graph module in the inspector shows the branches that lead to what it added:

How it behaves

• App Graph expands lazily. The framework runs a node’s extensions only when something asks for that node’s connections, such as the person opening a branch in the tree. A space with ten thousand objects costs nothing until it is opened.
• A connector reads reactive state through get. When that state changes, such as a query gaining a result, the connector reruns and the node’s connections update.
• Nodes nothing is showing can be dropped again. A plugin that must keep a node loaded while it is off screen, such as the one a panel is pinned to, contributes it through AppCapabilities.AppGraphRetention.
• Actions reach every menu from one place. An action node carries a disposition that says where it appears: toolbar for an object’s toolbar, list-item for its context menu in the tree. The command palette lists every action of the open node, so an action needs no command of its own.

src/capabilities/app-graph-builder.ts

import * as Effect from 'effect/Effect';

import * as Capability from '@dxos/app-framework/Capability';
import * as AppGraphBuilder from '@dxos/app-graph/AppGraphBuilder';
import * as AppCapabilities from '@dxos/app-toolkit/AppCapabilities';
import * as AppNodeMatcher from '@dxos/app-toolkit/AppNodeMatcher';
import * as GraphPath from '@dxos/app-toolkit/GraphPath';
import * as TypeSection from '@dxos/app-toolkit/TypeSection';
import * as Operation from '@dxos/compute/Operation';
import { Obj, Ref } from '@dxos/echo';

import { StashNamespace } from '../namespace.ts';
import { StashedLink } from '../types/StashedLink.ts';
import { MarkRead } from '../types/StashedLinkOperation.ts';

/** A "Stashed links" section in each space's Content group, once it has one. */
const section = TypeSection.createTypeSectionExtension(StashedLink, {
  match: AppNodeMatcher.whenNavTreeGroup(GraphPath.GroupTypes.content),
  groupSegment: GraphPath.GroupSegments.content,
  // The link's address in Composer's URL: `/w/<space>/stash/<id>`.
  urlKey: 'stash',
});

/** An action on every link, on its toolbar and its menu in the tree. */
const stashedLinkActions = AppGraphBuilder.createTypeExtension({
  id: 'stashedLinkActions',
  type: StashedLink,
  actions: (link) =>
    Effect.succeed([
      {
        id: 'markRead',
        data: () =>
          Operation.invoke(
            MarkRead,
            { link: Ref.make(link) },
            { spaceId: Obj.getDatabase(link)?.spaceId },
          ),
        properties: {
          label: ['mark-read.label', { ns: StashNamespace.key }],
          icon: 'ph--check-circle--regular',
          disposition: ['toolbar', 'list-item'],
        },
      },
    ]),
});

Write a graph builder extension

AppGraphBuilder.createExtension takes an id, a matcher and a connector. The matcher returns Option.some(value) for the nodes it applies to; AppNodeMatcher has ready-made ones such as whenSpace. The connector returns the nodes to connect. Read reactive state with get so the connector reruns when it changes.

import * as Effect from 'effect/Effect';
import * as AppGraphBuilder from '@dxos/app-graph/AppGraphBuilder';
import * as AppNode from '@dxos/app-toolkit/AppNode';
import * as AppNodeMatcher from '@dxos/app-toolkit/AppNodeMatcher';
import { Filter } from '@dxos/echo';

// One node per note, as a child of each space node.
const notes = AppGraphBuilder.createExtension({
  id: 'notes',
  match: AppNodeMatcher.whenSpace,
  connector: (space, get) => {
    const objects = get(space.db.query(Filter.type(Note)).atom);
    return Effect.succeed(
      objects
        .map((object) => AppNode.makeObject({ get, db: space.db, object }))
        .filter((node): node is NonNullable<typeof node> => node !== null),
    );
  },
});

Attach actions to nodes

AppGraphBuilder.createTypeExtension matches nodes whose data is an object of one type. Its actions callback returns action nodes. AppGraphNode.makeAction makes one; disposition decides where it shows. AppNode.makeToolbarAction is a shortcut for the object toolbar.

import * as Effect from 'effect/Effect';
import * as AppGraphBuilder from '@dxos/app-graph/AppGraphBuilder';
import * as AppGraphNode from '@dxos/app-graph/AppGraphNode';
import { Obj } from '@dxos/echo';

// An action on every node whose data is a Note.
const pin = AppGraphBuilder.createTypeExtension({
  id: 'pin',
  type: Note,
  actions: (note) =>
    Effect.succeed([
      AppGraphNode.makeAction({
        id: 'pin',
        data: () =>
          Effect.sync(() =>
            Obj.update(note, (note) => (note.pinned = !note.pinned)),
          ),
        properties: {
          label: 'Pin',
          icon: 'ph--push-pin--regular',
          disposition: 'list-item',
        },
      }),
    ]),
});

Both builders return Effects. Run them in the module body and contribute the result through AppCapabilities.AppGraphBuilder.

import * as Effect from 'effect/Effect';
import * as Capability from '@dxos/app-framework/Capability';
import * as AppCapabilities from '@dxos/app-toolkit/AppCapabilities';

export default Capability.makeModule(
  Effect.fnUntraced(function* () {
    const extensions = yield* Effect.all([notes, pin]);
    return Capability.contribute(
      AppCapabilities.AppGraphBuilder,
      extensions.flat(),
    );
  }),
);

Work with AppNode and GraphPath

AppNode builds the common kinds of node: makeObject for an ECHO object, makeSection for a heading in the tree, makeCompanion and makeDeckCompanion for panels. GraphPath builds and parses node paths, which navigation operations take.

import * as GraphPath from '@dxos/app-toolkit/GraphPath';

export const pathOfNote = (note: Note, spaceId: string) =>
  GraphPath.getSpacePath(spaceId, note.id);

Expand and read the graph from a component

useAppGraph returns the graph. Expand a node before reading its connections, because the graph builds them lazily. graph.connections(id, relation) is the same data as an atom, for a component that should update as the graph changes.

import { useEffect, useState } from 'react';
import * as AppGraph from '@dxos/app-graph/AppGraph';
import * as AppGraphNode from '@dxos/app-graph/AppGraphNode';
import * as Hooks from '@dxos/app-toolkit/Hooks';
import * as EffectEx from '@dxos/effect/EffectEx';

export const ChildCount = ({ id }: { id: string }) => {
  const { graph } = Hooks.useAppGraph();
  const [count, setCount] = useState(0);
  useEffect(() => {
    // Children are built lazily: expand the node, then read its connections.
    void EffectEx.runPromise(
      AppGraph.expand(graph, id, AppGraphNode.child),
    ).then(() =>
      setCount(AppGraph.getConnections(graph, id, AppGraphNode.child).length),
    );
  }, [graph, id]);
  return <span>{count}</span>;
};

Limits

• An extension’s id and a node’s id must be camelCase. A hyphenated id is dropped without an error.
• A connector must be cheap and must not write. It runs again on every change to the state it reads.
• Paths are stable only while the ids along them are. Moving an object to another space changes its path.

Related

Page	What it covers
Extend the App Graph	Sections, items and actions end to end.
Operation	The operations that actions invoke.