@dxos/app-framework 0.8.4-main.fffef41 → 0.9.0

package/src/react/IntentContext.tsx

@@ -1,35 +0,0 @@
-//
-// Copyright 2023 DXOS.org
-//
-
-import { type Context, type Provider, createContext, useContext, useEffect } from 'react';
-
-import { raise } from '@dxos/debug';
-import { pick } from '@dxos/util';
-
-import { Capabilities } from '../common';
-import { type AnyIntentResolver, type IntentContext } from '../plugin-intent';
-
-import { usePluginManager } from './PluginManagerProvider';
-
-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/react/Surface.stories.tsx

@@ -1,125 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import { type Meta, type StoryObj } from '@storybook/react-vite';
-import React, { useCallback, useEffect, useState } from 'react';
-
-import { faker } from '@dxos/random';
-import { List, ListItem, Toolbar } from '@dxos/react-ui';
-import { withTheme } from '@dxos/react-ui/testing';
-import { getHashStyles, mx } from '@dxos/react-ui-theme';
-
-import { Capabilities, createSurface } from '../common';
-import { withPluginManager } from '../testing';
-
-import { usePluginManager } from './PluginManagerProvider';
-import { Surface, useSurfaces } from './Surface';
-
-const DefaultStory = () => {
-  const [selected, setSelected] = useState<string | undefined>();
-  const manager = usePluginManager();
-  const surfaces = useSurfaces();
-
-  const handleAdd = useCallback(() => {
-    const id = `test-${faker.number.int({ min: 0, max: 1_000 })}`;
-    const styles = getHashStyles(id);
-
-    manager.context.contributeCapability({
-      module: 'test',
-      interface: Capabilities.ReactSurface,
-      implementation: createSurface({
-        id,
-        role: 'item',
-        filter: (data): data is any => (data as any)?.id === id,
-        component: () => (
-          <div className={mx('flex justify-center items-center border rounded', styles.surface, styles.border)}>
-            <span className={mx('dx-tag font-mono text-lg', styles.text)}>{id}</span>
-          </div>
-        ),
-      }),
-    });
-
-    setSelected(id);
-  }, [manager]);
-
-  const handleSelect = useCallback(() => {
-    setSelected(faker.helpers.arrayElement(surfaces)?.id);
-  }, [surfaces]);
-
-  const handleError = useCallback(() => {
-    manager.context.contributeCapability({
-      module: 'error',
-      interface: Capabilities.ReactSurface,
-      implementation: createSurface({
-        id: 'error',
-        role: 'item',
-        filter: (data): data is any => (data as any)?.id === 'error',
-        component: () => {
-          const [count, setCount] = useState(3);
-          useEffect(() => {
-            const interval = setInterval(() => {
-              setCount((count) => {
-                if (count <= 1) {
-                  clearInterval(interval);
-                }
-
-                return count - 1;
-              });
-            }, 1_000);
-            return () => clearInterval(interval);
-          }, []);
-
-          if (count <= 0) {
-            throw new Error('BANG!');
-          }
-
-          return (
-            <div className='flex justify-center items-center border border-roseFill rounded'>
-              <span className='font-mono'>Ticking... {count}</span>
-            </div>
-          );
-        },
-      }),
-    });
-
-    setSelected('error');
-  }, [manager]);
-
-  return (
-    <div className='flex flex-col bs-full overflow-hidden'>
-      <Toolbar.Root>
-        <Toolbar.Button onClick={handleAdd}>Add</Toolbar.Button>
-        <Toolbar.Button onClick={handleSelect}>Pick</Toolbar.Button>
-        <Toolbar.Button onClick={handleError}>Error</Toolbar.Button>
-      </Toolbar.Root>
-      <div className='grid grid-cols-2 bs-full gap-4 overflow-hidden'>
-        <Surface role='item' data={selected ? { id: selected } : undefined} limit={1} />
-        <div className='overflow-y-auto bs-full'>
-          <List>
-            {surfaces.map((surface) => (
-              <ListItem.Root key={surface.id} id={surface.id}>
-                <ListItem.Heading classNames='flex items-center'>{surface.id}</ListItem.Heading>
-              </ListItem.Root>
-            ))}
-          </List>
-        </div>
-      </div>
-    </div>
-  );
-};
-
-const meta = {
-  title: 'sdk/app-framework/Surface',
-  render: DefaultStory,
-  decorators: [withTheme, withPluginManager({ capabilities: [] })],
-  parameters: {
-    layout: 'fullscreen',
-  },
-} satisfies Meta<typeof DefaultStory>;
-
-export default meta;
-
-type Story = StoryObj<typeof meta>;
-
-export const Default: Story = {};

package/src/react/Surface.tsx

@@ -1,109 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import React, {
-  Fragment,
-  type NamedExoticComponent,
-  type RefAttributes,
-  Suspense,
-  forwardRef,
-  memo,
-  useMemo,
-} from 'react';
-
-import { useDefaultValue } from '@dxos/react-hooks';
-import { byPosition } from '@dxos/util';
-
-import { Capabilities, type SurfaceDefinition, type SurfaceProps } from '../common';
-import { type PluginContext } from '../core';
-
-import { ErrorBoundary } from './ErrorBoundary';
-import { useCapabilities } from './useCapabilities';
-
-const DEFAULT_PLACEHOLDER = <Fragment />;
-
-/**
- * A surface is a named region of the screen that can be populated by plugins.
- */
-export const Surface: NamedExoticComponent<SurfaceProps & RefAttributes<HTMLElement>> = memo(
-  forwardRef(
-    (
-      { id: _id, role, data: dataParam, limit, fallback = DefaultFallback, placeholder = DEFAULT_PLACEHOLDER, ...rest },
-      forwardedRef,
-    ) => {
-      // TODO(wittjosiah): This will make all surfaces depend on a single signal.
-      //   This isn't ideal because it means that any change to the data will cause all surfaces to re-render.
-      //   This effectively means that plugin modules which contribute surfaces need to all be activated at startup.
-      //   This should be fine for now because it's how it worked prior to capabilities api anyway.
-      //   In the future, it would be nice to be able to bucket the surface contributions by role.
-      const surfaces = useSurfaces();
-      const data = useDefaultValue(dataParam, () => ({}));
-
-      // NOTE: Memoizing the candidates makes the surface not re-render based on reactivity within data.
-      const definitions = findCandidates(surfaces, { role, data });
-      const candidates = limit ? definitions.slice(0, limit) : definitions;
-      const nodes = candidates.map(({ id, component: Component }) => (
-        <Component ref={forwardedRef} key={id} id={id} role={role} data={data} limit={limit} {...rest} />
-      ));
-
-      // TODO(burdon): Able to inject DOM properties into root (e.g., object.id).
-      const suspense = <Suspense fallback={placeholder}>{nodes}</Suspense>;
-
-      return (
-        <ErrorBoundary data={data} fallback={fallback}>
-          {suspense}
-        </ErrorBoundary>
-      );
-    },
-  ),
-);
-
-// TODO(burdon): Make user facing, with telemetry.
-// TODO(burdon): Change based on dev/prod mode; infer subject type, id.
-const DefaultFallback = ({ data, error, dev }: { data: any; error: Error; dev?: boolean }) => {
-  if (dev) {
-    return (
-      <div className='flex flex-col gap-4 p-4 is-full overflow-y-auto'>
-        <h1 className='flex gap-2 text-sm mbs-2'>{error.message}</h1>
-        <pre className='overflow-auto text-xs text-description'>{JSON.stringify(data, null, 2)}</pre>
-      </div>
-    );
-  }
-
-  return (
-    <div className='flex flex-col gap-4 p-4 is-full overflow-y-auto border border-roseFill'>
-      <h1 className='flex gap-2 text-sm mbs-2 text-rose-500'>{error.message}</h1>
-      <pre className='overflow-auto text-xs text-description'>{error.stack}</pre>
-      <pre className='overflow-auto text-xs text-description'>{JSON.stringify(data, null, 2)}</pre>
-    </div>
-  );
-};
-
-/**
- * @internal
- */
-export const useSurfaces = () => {
-  const surfaces = useCapabilities(Capabilities.ReactSurface);
-  return useMemo(() => surfaces.flat(), [surfaces]);
-};
-
-/**
- * @returns `true` if there is a contributed surface which matches the specified role & data, `false` otherwise.
- */
-export const isSurfaceAvailable = (context: PluginContext, { role, data }: Pick<SurfaceProps, 'role' | 'data'>) => {
-  const surfaces = context.getCapabilities(Capabilities.ReactSurface);
-  const candidates = findCandidates(surfaces.flat(), { role, data });
-  return candidates.length > 0;
-};
-
-const findCandidates = (surfaces: SurfaceDefinition[], { role, data }: Pick<SurfaceProps, 'role' | 'data'>) => {
-  return Object.values(surfaces)
-    .filter((definition) =>
-      Array.isArray(definition.role) ? definition.role.includes(role) : definition.role === role,
-    )
-    .filter(({ filter }) => (filter ? filter(data ?? {}) : true))
-    .toSorted(byPosition);
-};
-
-Surface.displayName = 'Surface';

package/src/react/common.ts

@@ -1,13 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import { Capabilities } from '../common';
-
-import { useCapability } from './useCapabilities';
-
-export const useIntentDispatcher = () => useCapability(Capabilities.IntentDispatcher);
-
-export const useAppGraph = () => useCapability(Capabilities.AppGraph);
-
-export const useLayout = () => useCapability(Capabilities.Layout);

package/src/react/index.ts

@@ -1,14 +0,0 @@
-//
-// Copyright 2023 DXOS.org
-//
-
-export * from './common';
-export * from './types';
-
-export * from './ErrorBoundary';
-export * from './PluginManagerProvider';
-export * from './Surface';
-
-export * from './useApp';
-export * from './useCapabilities';
-export * from './useIntentResolver';

package/src/react/types.ts

@@ -1,38 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import * as Schema from 'effect/Schema';
-
-import { type Obj } from '@dxos/echo';
-
-export const SurfaceCardRole = Schema.Literal(
-  'card',
-  'card--popover',
-  'card--intrinsic',
-  'card--extrinsic',
-  'card--transclusion',
-);
-
-export type SurfaceCardRole = Schema.Schema.Type<typeof SurfaceCardRole>;
-
-// TODO(burdon): Define all roles.
-export type SurfaceRole =
-  | 'item'
-  | 'article'
-  | 'complementary' // (for companion?)
-  | 'section'
-  | SurfaceCardRole;
-
-/**
- * Base type for surface components.
- */
-// TODO(burdon): Standardize PluginSettings and ObjectProperties.
-// TODO(burdon): Include attendableId?
-// TODO(burdon): companionTo?
-export type SurfaceComponentProps<Subject extends Obj.Any = Obj.Any, Role extends string = string> = {
-  role?: Role;
-
-  /** The primary object being displayed. */
-  subject: Subject;
-};

package/src/react/useApp.tsx

@@ -1,165 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import { RegistryContext } from '@effect-atom/atom-react';
-import { effect } from '@preact/signals-core';
-import React, { type FC, useCallback, useEffect, useMemo } from 'react';
-
-import { invariant } from '@dxos/invariant';
-import { live } from '@dxos/live-object';
-import { useAsyncEffect, useDefaultValue } from '@dxos/react-hooks';
-
-import { Capabilities, Events } from '../common';
-import { type Plugin, PluginManager, type PluginManagerOptions } from '../core';
-
-import { App } from './App';
-import { DefaultFallback } from './DefaultFallback';
-import { ErrorBoundary } from './ErrorBoundary';
-import { PluginManagerProvider } from './PluginManagerProvider';
-
-const ENABLED_KEY = 'dxos.org/app-framework/enabled';
-
-export type UseAppOptions = {
-  pluginManager?: PluginManager;
-  pluginLoader?: PluginManagerOptions['pluginLoader'];
-  plugins?: Plugin[];
-  core?: string[];
-  defaults?: string[];
-  placeholder?: FC<{ stage: number }>;
-  fallback?: ErrorBoundary['props']['fallback'];
-  cacheEnabled?: boolean;
-  safeMode?: boolean;
-  debounce?: number;
-};
-
-/**
- * Expected usage is for this to be the entrypoint of the application.
- * Initializes plugins and renders the root components.
- *
- * @example
- * const plugins = [LayoutPlugin(), MyPlugin()];
- * const core = [LayoutPluginId];
- * const default = [MyPluginId];
- * const fallback = <div>Initializing Plugins...</div>;
- * const App = useApp({ plugins, core, default, fallback });
- * createRoot(document.getElementById('root')!).render(
- *   <StrictMode>
- *     <App />
- *   </StrictMode>,
- * );
- *
- * @param params.pluginLoader A function which loads new plugins.
- * @param params.plugins All plugins available to the application.
- * @param params.core Core plugins which will always be enabled.
- * @param params.defaults Default plugins are enabled by default but can be disabled by the user.
- * @param params.placeholder Placeholder component to render during startup.
- * @param params.fallback Fallback component to render if an error occurs during startup.
- * @param params.cacheEnabled Whether to cache enabled plugins in localStorage.
- * @param params.safeMode Whether to enable safe mode, which disables optional plugins.
- */
-export const useApp = ({
-  pluginManager,
-  pluginLoader: pluginLoaderParam,
-  plugins: pluginsParam,
-  core: coreParam,
-  defaults: defaultsParam,
-  placeholder,
-  fallback = DefaultFallback,
-  cacheEnabled = false,
-  safeMode = false,
-  debounce = 0,
-}: UseAppOptions) => {
-  const plugins = useDefaultValue(pluginsParam, () => []);
-  const core = useDefaultValue(coreParam, () => plugins.map(({ meta }) => meta.id));
-  const defaults = useDefaultValue(defaultsParam, () => []);
-
-  // TODO(wittjosiah): Provide a custom plugin loader which supports loading via url.
-  const pluginLoader = useMemo(
-    () =>
-      pluginLoaderParam ??
-      ((id: string) => {
-        const plugin = plugins.find((plugin) => plugin.meta.id === id);
-        invariant(plugin, `Plugin not found: ${id}`);
-        return plugin;
-      }),
-    [pluginLoaderParam, plugins],
-  );
-
-  const state = useMemo(() => live({ ready: false, error: null }), []);
-  const cached: string[] = useMemo(() => JSON.parse(localStorage.getItem(ENABLED_KEY) ?? '[]'), []);
-  const enabled = useMemo(
-    () => (safeMode ? [] : cacheEnabled && cached.length > 0 ? cached : defaults),
-    [safeMode, cacheEnabled, cached, defaults],
-  );
-  const manager = useMemo(
-    () => pluginManager ?? new PluginManager({ pluginLoader, plugins, core, enabled }),
-    [pluginManager, pluginLoader, plugins, core, enabled],
-  );
-
-  useEffect(() => {
-    return manager.activation.on(({ event, state: _state, error }) => {
-      // Once the app is ready the first time, don't show the fallback again.
-      if (!state.ready && event === Events.Startup.id) {
-        state.ready = _state === 'activated';
-      }
-
-      if (error && !state.ready && !state.error) {
-        state.error = error;
-      }
-    });
-  }, [manager, state]);
-
-  useEffect(() => {
-    effect(() => {
-      cacheEnabled && localStorage.setItem(ENABLED_KEY, JSON.stringify(manager.enabled));
-    });
-  }, [cacheEnabled, manager]);
-
-  useEffect(() => {
-    setupDevtools(manager);
-  }, [manager]);
-
-  useAsyncEffect(async () => {
-    manager.context.contributeCapability({
-      interface: Capabilities.PluginManager,
-      implementation: manager,
-      module: 'dxos.org/app-framework/plugin-manager',
-    });
-
-    manager.context.contributeCapability({
-      interface: Capabilities.AtomRegistry,
-      implementation: manager.registry,
-      module: 'dxos.org/app-framework/atom-registry',
-    });
-
-    await Promise.all([
-      // TODO(wittjosiah): Factor out such that this could be called per surface role when attempting to render.
-      manager.activate(Events.SetupReactSurface),
-      manager.activate(Events.Startup),
-    ]);
-
-    return () => {
-      manager.context.removeCapability(Capabilities.PluginManager, manager);
-      manager.context.removeCapability(Capabilities.AtomRegistry, manager.registry);
-    };
-  }, [manager]);
-
-  return useCallback(
-    () => (
-      <ErrorBoundary fallback={fallback}>
-        <PluginManagerProvider value={manager}>
-          <RegistryContext.Provider value={manager.registry}>
-            <App placeholder={placeholder} state={state} debounce={debounce} />
-          </RegistryContext.Provider>
-        </PluginManagerProvider>
-      </ErrorBoundary>
-    ),
-    [fallback, manager, placeholder, state],
-  );
-};
-
-const setupDevtools = (manager: PluginManager) => {
-  (globalThis as any).composer ??= {};
-  (globalThis as any).composer.manager = manager;
-};

package/src/react/useCapabilities.ts

@@ -1,31 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import { useAtomValue } from '@effect-atom/atom-react';
-
-import { invariant } from '@dxos/invariant';
-
-import { type InterfaceDef } from '../core';
-
-import { usePluginManager } from './PluginManagerProvider';
-
-/**
- * Hook to request capabilities from the plugin context.
- * @returns An array of capabilities.
- */
-export const useCapabilities = <T>(interfaceDef: InterfaceDef<T>) => {
-  const manager = usePluginManager();
-  return useAtomValue(manager.context.capabilities(interfaceDef));
-};
-
-/**
- * Hook to request a capability from the plugin context.
- * @returns The capability.
- * @throws If no capability is found.
- */
-export const useCapability = <T>(interfaceDef: InterfaceDef<T>) => {
-  const capabilities = useCapabilities(interfaceDef);
-  invariant(capabilities.length > 0, `No capability found for ${interfaceDef.identifier}`);
-  return capabilities[0];
-};

package/src/react/useIntentResolver.ts

@@ -1,22 +0,0 @@
-//
-// Copyright 2023 DXOS.org
-//
-
-import { useEffect } from 'react';
-
-import { Capabilities } from '../common';
-import { type AnyIntentResolver } from '../plugin-intent';
-import { usePluginManager } from '../react';
-
-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]);
-};