@dxos/app-framework 0.7.4 → 0.7.5-labs.5f04cf6

package/src/helpers.test.ts

@@ -0,0 +1,97 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { describe, it, expect } from 'vitest';
+
+import { topologicalSort } from './helpers';
+
+describe('topologicalSort', () => {
+  it('should handle empty array', () => {
+    const result = topologicalSort([]);
+    expect(result).toEqual([]);
+  });
+
+  it('should handle single node with no dependencies', () => {
+    const nodes = [{ id: 'A', dependsOn: [], data: 1 }];
+    const result = topologicalSort(nodes);
+    expect(result).toEqual(nodes);
+  });
+
+  it('should sort simple linear dependencies', () => {
+    const nodes = [
+      { id: 'A', dependsOn: ['B'], data: 1 },
+      { id: 'B', dependsOn: ['C'], data: 2 },
+      { id: 'C', data: 3 },
+    ];
+    const result = topologicalSort(nodes);
+
+    expect(result.map((n) => n.id)).toEqual(['C', 'B', 'A']);
+  });
+
+  it('should handle multiple dependencies', () => {
+    const nodes = [
+      { id: 'A', dependsOn: ['B', 'C'], data: 1 },
+      { id: 'B', dependsOn: ['D'], data: 2 },
+      { id: 'C', dependsOn: ['D'], data: 3 },
+      { id: 'D', data: 4 },
+    ];
+    const result = topologicalSort(nodes);
+
+    const resultIds = result.map((n) => n.id);
+    expect(resultIds[0]).toBe('D'); // D must be first.
+    expect(resultIds[3]).toBe('A'); // A must be last.
+    // B and C can be in either order.
+    expect(resultIds.slice(1, 3)).toContain('B');
+    expect(resultIds.slice(1, 3)).toContain('C');
+  });
+
+  it('should throw on circular dependencies', () => {
+    const nodes = [
+      { id: 'A', dependsOn: ['B'], data: 1 },
+      { id: 'B', dependsOn: ['A'], data: 2 },
+    ];
+
+    expect(() => topologicalSort(nodes)).toThrow(/Circular dependency detected/);
+  });
+
+  it('should throw on missing dependencies', () => {
+    const nodes = [
+      { id: 'A', dependsOn: ['B'], data: 1 },
+      { id: 'B', dependsOn: ['C'], data: 2 },
+      // C is missing.
+    ];
+
+    expect(() => topologicalSort(nodes)).toThrow(/Node C not found/);
+  });
+
+  it('should maintain data integrity', () => {
+    const nodes = [
+      { id: 'A', dependsOn: ['B'], data: { value: 1 } },
+      { id: 'B', data: { value: 2 } },
+    ];
+    const result = topologicalSort(nodes);
+
+    expect(result[0].data).toEqual({ value: 2 });
+    expect(result[1].data).toEqual({ value: 1 });
+  });
+
+  it('should handle complex dependency graph', () => {
+    const nodes = [
+      { id: 'A', dependsOn: ['B', 'C'], data: 1 },
+      { id: 'B', dependsOn: ['D'], data: 2 },
+      { id: 'C', dependsOn: ['D', 'E'], data: 3 },
+      { id: 'D', dependsOn: ['F'], data: 4 },
+      { id: 'E', dependsOn: ['F'], data: 5 },
+      { id: 'F', data: 6 },
+    ];
+    const result = topologicalSort(nodes);
+    const resultIds = result.map((n) => n.id);
+
+    // Verify order constraints.
+    expect(resultIds[0]).toBe('F'); // F must be first.
+    expect(resultIds[resultIds.length - 1]).toBe('A'); // A must be last.
+    expect(resultIds.indexOf('D')).toBeLessThan(resultIds.indexOf('B'));
+    expect(resultIds.indexOf('E')).toBeLessThan(resultIds.indexOf('C'));
+  });
+});

package/src/helpers.ts

@@ -0,0 +1,45 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+type DependencyNode = {
+  id: string;
+  dependsOn?: string[];
+};
+
+/**
+ * Topologically sorts a list of nodes based on their dependencies.
+ */
+// TODO(wittjosiah): Factor out?
+export const topologicalSort = <T extends DependencyNode>(nodes: T[]): T[] => {
+  const getDependencies = (nodeId: string, seen = new Set<string>(), path = new Set<string>()): string[] => {
+    if (path.has(nodeId)) {
+      throw new Error(`Circular dependency detected involving ${nodeId}`);
+    }
+    if (seen.has(nodeId)) {
+      return [];
+    }
+
+    const node = nodes.find((n) => n.id === nodeId);
+    if (!node) {
+      throw new Error(`Node ${nodeId} not found but is listed as a dependency`);
+    }
+
+    const newPath = new Set([...path, nodeId]);
+    const newSeen = new Set([...seen, nodeId]);
+
+    const dependsOn = node.dependsOn ?? [];
+    return [...dependsOn.flatMap((depId) => getDependencies(depId, newSeen, newPath)), nodeId];
+  };
+
+  // Get all unique dependencies.
+  const allDependencies = nodes
+    .map((node) => node.id)
+    .flatMap((id) => getDependencies(id))
+    .filter((id, index, self) => self.indexOf(id) === index);
+
+  // Map back to original nodes
+  return allDependencies
+    .map((id) => nodes.find((node) => node.id === id))
+    .filter((node): node is T => node !== undefined);
+};

package/src/index.ts

@@ -1,7 +1,10 @@
 //
-// Copyright 2023 DXOS.org
+// Copyright 2025 DXOS.org
 //
 
-export * from './plugins';
-
 export * from './App';
+export * from './common';
+export * from './core';
+export * from './plugin-intent';
+export * from './plugin-settings';
+export * from './react';

package/src/playground/debug/Debug.tsx

@@ -0,0 +1,39 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React from 'react';
+
+import { SyntaxHighlighter } from '@dxos/react-ui-syntax-highlighter';
+
+import { Capabilities, createSurface } from '../../common';
+import { contributes } from '../../core';
+import { usePluginManager } from '../../react';
+
+export const Debug = () => {
+  const manager = usePluginManager();
+
+  const object = {
+    core: manager.core,
+    enabled: manager.enabled,
+    active: manager.active,
+    pendingReset: manager.pendingReset,
+    eventsFired: manager.eventsFired,
+  };
+
+  return (
+    <SyntaxHighlighter language='json' classNames='flex w-full text-xs opacity-75 rounded'>
+      {JSON.stringify(object, undefined, 2)}
+    </SyntaxHighlighter>
+  );
+};
+
+export default () =>
+  contributes(
+    Capabilities.ReactSurface,
+    createSurface({
+      id: 'dxos.org/test/debug/main',
+      role: 'secondary',
+      component: Debug,
+    }),
+  );

package/src/playground/debug/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './plugin';

package/src/playground/debug/plugin.ts

@@ -0,0 +1,17 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Events } from '../../common';
+import { defineModule, definePlugin, lazy } from '../../core';
+
+const Debug = lazy(() => import('./Debug'));
+
+export const DebugPlugin = () =>
+  definePlugin({ id: 'dxos.org/test/debug' }, [
+    defineModule({
+      id: 'dxos.org/test/debug/main',
+      activatesOn: Events.Startup,
+      activate: () => Debug(),
+    }),
+  ]);

package/src/playground/generator/Main.tsx

@@ -0,0 +1,71 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React, { useCallback } from 'react';
+
+import { IconButton, List, ListItem } from '@dxos/react-ui';
+
+import { Capabilities } from '../../common';
+import { contributes } from '../../core';
+import { usePluginManager } from '../../react';
+
+const Item = ({
+  id,
+  disabled,
+  onRemove,
+}: {
+  id: string;
+  disabled: boolean;
+  onRemove: (id: string) => Promise<void>;
+}) => {
+  const handleRemove = useCallback(() => onRemove(id), [onRemove]);
+
+  return (
+    <ListItem.Root key={id} id={id}>
+      <ListItem.Heading classNames='grow pbs-2'>{id}</ListItem.Heading>
+      <ListItem.Endcap>
+        <IconButton
+          iconOnly
+          variant='ghost'
+          icon='ph--x--regular'
+          label='Remove'
+          size={5}
+          disabled={disabled}
+          onClick={handleRemove}
+        />
+      </ListItem.Endcap>
+    </ListItem.Root>
+  );
+};
+
+export const Main = () => {
+  const manager = usePluginManager();
+
+  const handleRemove = useCallback(
+    async (id: string) => {
+      await manager.remove(id);
+    },
+    [manager],
+  );
+
+  return (
+    <List itemSizes='one'>
+      {manager.plugins.map((plugin) => (
+        <Item
+          key={plugin.meta.id}
+          id={plugin.meta.id}
+          disabled={manager.core.includes(plugin.meta.id)}
+          onRemove={handleRemove}
+        />
+      ))}
+    </List>
+  );
+};
+
+export default () =>
+  contributes(Capabilities.ReactSurface, {
+    id: 'dxos.org/test/generator/main',
+    role: 'primary',
+    component: Main,
+  });

package/src/playground/generator/Toolbar.tsx

@@ -0,0 +1,46 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React, { useCallback } from 'react';
+
+import { Button } from '@dxos/react-ui';
+
+import { CountEvent, createPluginId, Number } from './generator';
+import { Capabilities } from '../../common';
+import { contributes } from '../../core';
+import { usePluginManager } from '../../react';
+
+export const Toolbar = () => {
+  const manager = usePluginManager();
+
+  const handleAdd = useCallback(async () => {
+    const id = createPluginId(Math.random().toString(16).substring(2, 8));
+    await manager.add(id);
+  }, [manager]);
+
+  const handleCount = useCallback(async () => {
+    if (manager.pendingReset.includes(CountEvent.id)) {
+      await manager.reset(CountEvent);
+    } else {
+      await manager.activate(CountEvent);
+    }
+  }, [manager]);
+
+  const count = manager.context.requestCapabilities(Number).reduce((acc, curr) => acc + curr, 0);
+
+  return (
+    <>
+      <Button onClick={handleAdd}>Add</Button>
+      <Button onClick={handleCount}>Count</Button>
+      <div className='flex items-center'>Count: {count}</div>
+    </>
+  );
+};
+
+export default () =>
+  contributes(Capabilities.ReactSurface, {
+    id: 'dxos.org/test/generator/toolbar',
+    role: 'toolbar',
+    component: Toolbar,
+  });

package/src/playground/generator/generator.ts

@@ -0,0 +1,23 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { contributes, defineEvent, defineCapability, defineModule, definePlugin } from '../../core';
+
+export const Number = defineCapability<number>('dxos.org/test/generator/number');
+
+export const CountEvent = defineEvent('dxos.org/test/generator/count');
+
+export const createPluginId = (id: string) => `dxos.org/test/generator/${id}`;
+
+export const createNumberPlugin = (id: string) => {
+  const number = Math.floor(Math.random() * 100);
+
+  return definePlugin({ id }, [
+    defineModule({
+      id: `${id}/main`,
+      activatesOn: CountEvent,
+      activate: () => contributes(Number, number),
+    }),
+  ]);
+};

package/src/playground/generator/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './plugin';
+export * from './generator';

package/src/playground/generator/plugin.ts

@@ -0,0 +1,18 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Events } from '../../common';
+import { defineModule, definePlugin, lazy } from '../../core';
+
+const Main = lazy(() => import('./Main'));
+const Toolbar = lazy(() => import('./Toolbar'));
+
+export const GeneratorPlugin = () =>
+  definePlugin({ id: 'dxos.org/test/generator' }, [
+    defineModule({
+      id: 'dxos.org/test/generator/main',
+      activatesOn: Events.Startup,
+      activate: async () => [await Main(), await Toolbar()],
+    }),
+  ]);

package/src/playground/layout/Layout.tsx

@@ -0,0 +1,33 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React from 'react';
+
+import { Capabilities } from '../../common';
+import { contributes } from '../../core';
+import { Surface } from '../../react';
+
+export const Layout = () => {
+  return (
+    <div className='flex flex-col gap-2'>
+      <div className='flex gap-2'>
+        <Surface role='toolbar' />
+      </div>
+      <div className='flex gap-2'>
+        <div className='flex-1'>
+          <Surface role='primary' limit={1} />
+        </div>
+        <div className='flex-1'>
+          <Surface role='secondary' limit={1} />
+        </div>
+      </div>
+    </div>
+  );
+};
+
+export default () =>
+  contributes(Capabilities.ReactRoot, {
+    id: 'dxos.org/test/layout/root',
+    root: Layout,
+  });

package/src/playground/layout/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './plugin';

package/src/playground/layout/plugin.ts

@@ -0,0 +1,17 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Events } from '../../common';
+import { definePlugin, lazy, defineModule } from '../../core';
+
+const Layout = lazy(() => import('./Layout'));
+
+export const LayoutPlugin = () =>
+  definePlugin({ id: 'dxos.org/test/layout' }, [
+    defineModule({
+      id: 'dxos.org/test/layout/root',
+      activatesOn: Events.Startup,
+      activate: () => Layout(),
+    }),
+  ]);

package/src/playground/logger/Toolbar.tsx

@@ -0,0 +1,28 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React, { useCallback } from 'react';
+
+import { Button } from '@dxos/react-ui';
+
+import { Log } from './schema';
+import { Capabilities, createSurface } from '../../common';
+import { contributes } from '../../core';
+import { createIntent, useIntentDispatcher } from '../../plugin-intent';
+
+export const Logger = () => {
+  const { dispatchPromise } = useIntentDispatcher();
+  const handleClick = useCallback(() => dispatchPromise(createIntent(Log, { message: 'Hello, world!' })), []);
+  return <Button onClick={handleClick}>Log</Button>;
+};
+
+export default () =>
+  contributes(
+    Capabilities.ReactSurface,
+    createSurface({
+      id: 'dxos.org/test/logger/action',
+      role: 'toolbar',
+      component: Logger,
+    }),
+  );

package/src/playground/logger/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './plugin';

package/src/playground/logger/plugin.ts

@@ -0,0 +1,33 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { log } from '@dxos/log';
+
+import { Log } from './schema';
+import { Capabilities, Events } from '../../common';
+import { contributes, defineModule, lazy, definePlugin } from '../../core';
+import { createResolver } from '../../plugin-intent';
+
+const Toolbar = lazy(() => import('./Toolbar'));
+
+export const LoggerPlugin = () =>
+  definePlugin({ id: 'dxos.org/test/logger' }, [
+    defineModule({
+      id: 'dxos.org/test/logger/intents',
+      activatesOn: Events.SetupIntents,
+      activate: () => [
+        contributes(
+          Capabilities.IntentResolver,
+          createResolver(Log, ({ message }) => {
+            log.info(message);
+          }),
+        ),
+      ],
+    }),
+    defineModule({
+      id: 'dxos.org/test/logger/surfaces',
+      activatesOn: Events.Startup,
+      activate: () => Toolbar(),
+    }),
+  ]);

package/src/playground/logger/schema.ts

@@ -0,0 +1,12 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { S } from '@dxos/echo-schema';
+
+export class Log extends S.TaggedClass<Log>()('dxos.org/test/logger/log', {
+  input: S.Struct({
+    message: S.String,
+  }),
+  output: S.Void,
+}) {}

package/src/playground/playground.stories.tsx

@@ -0,0 +1,34 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import '@dxos-theme';
+
+import React from 'react';
+
+import { withLayout, withTheme } from '@dxos/storybook-utils';
+
+import { DebugPlugin } from './debug';
+import { createNumberPlugin, GeneratorPlugin } from './generator';
+import { LayoutPlugin } from './layout';
+import { LoggerPlugin } from './logger';
+import { createApp } from '../App';
+import { IntentPlugin } from '../plugin-intent';
+
+const plugins = [IntentPlugin(), LayoutPlugin(), DebugPlugin(), LoggerPlugin(), GeneratorPlugin()];
+
+const Story = createApp({
+  pluginLoader: (id) => createNumberPlugin(id),
+  plugins,
+  core: plugins.map((plugin) => plugin.meta.id),
+  // Having a non-empty placeholder makes it clear if it's taking a while to load.
+  placeholder: <div>Loading...</div>,
+});
+
+export const Playground = {};
+
+export default {
+  title: 'sdk/app-framework/playground',
+  render: Story,
+  decorators: [withTheme, withLayout({ tooltips: true })],
+};

package/src/plugin-intent/IntentContext.tsx

@@ -0,0 +1,34 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { type Context, createContext, useContext, type Provider, useEffect } from 'react';
+
+import { raise } from '@dxos/debug';
+import { pick } from '@dxos/util';
+
+import { type AnyIntentResolver, type IntentContext } from './intent-dispatcher';
+import { Capabilities } from '../common';
+import { usePluginManager } from '../react';
+
+const IntentContext: Context<IntentContext | undefined> = createContext<IntentContext | undefined>(undefined);
+
+export const useIntentDispatcher = (): Pick<IntentContext, 'dispatch' | 'dispatchPromise'> => {
+  const context = useContext(IntentContext) ?? raise(new Error('IntentContext not found'));
+  return pick(context, ['dispatch', 'dispatchPromise']);
+};
+
+export const useIntentResolver = (module: string, resolver: AnyIntentResolver) => {
+  const manager = usePluginManager();
+  useEffect(() => {
+    manager.context.contributeCapability({
+      module,
+      interface: Capabilities.IntentResolver,
+      implementation: resolver,
+    });
+
+    return () => manager.context.removeCapability(Capabilities.IntentResolver, resolver);
+  }, [module, resolver]);
+};
+
+export const IntentProvider: Provider<IntentContext | undefined> = IntentContext.Provider;

package/src/plugin-intent/IntentPlugin.tsx

@@ -0,0 +1,60 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Effect } from 'effect';
+import React from 'react';
+
+import { create } from '@dxos/live-object';
+
+import { IntentProvider } from './IntentContext';
+import { INTENT_PLUGIN } from './actions';
+import { type AnyIntentResolver, createDispatcher, type IntentContext } from './intent-dispatcher';
+import { Capabilities, Events } from '../common';
+import { contributes, defineModule, definePlugin } from '../core';
+
+const defaultEffect = () => Effect.fail(new Error('Intent runtime not ready'));
+const defaultPromise = () => Effect.runPromise(defaultEffect());
+
+export const IntentPlugin = () =>
+  definePlugin({ id: INTENT_PLUGIN }, [
+    defineModule({
+      id: `${INTENT_PLUGIN}/module/dispatcher`,
+      // TODO(wittjosiah): This will mean that startup needs to be reset when intents are added or removed.
+      //   This is fine for now because it's how it worked prior to capabilities api anyways.
+      //   In the future, the intent dispatcher should be able to be reset without resetting the entire app.
+      activatesOn: Events.Startup,
+      activatesBefore: [Events.SetupIntents],
+      activatesAfter: [Events.DispatcherReady],
+      activate: (context) => {
+        const state = create<IntentContext>({
+          dispatch: defaultEffect,
+          dispatchPromise: defaultPromise,
+          undo: defaultEffect,
+          undoPromise: defaultPromise,
+        });
+
+        // TODO(wittjosiah): Make getResolver callback async and allow resolvers to be requested on demand.
+        const { dispatch, dispatchPromise, undo, undoPromise } = createDispatcher((module) =>
+          context
+            .requestCapabilities(Capabilities.IntentResolver, (c, moduleId): c is AnyIntentResolver => {
+              return module ? moduleId === module : true;
+            })
+            .flat(),
+        );
+
+        state.dispatch = dispatch;
+        state.dispatchPromise = dispatchPromise;
+        state.undo = undo;
+        state.undoPromise = undoPromise;
+
+        return [
+          contributes(Capabilities.IntentDispatcher, state),
+          contributes(Capabilities.ReactContext, {
+            id: INTENT_PLUGIN,
+            context: ({ children }) => <IntentProvider value={state}>{children}</IntentProvider>,
+          }),
+        ];
+      },
+    }),
+  ]);