@dxos/app-framework 0.8.3 → 0.8.4-main.1068cf700f

package/src/plugin-settings/app-graph-builder.ts

@@ -1,157 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import { Rx } from '@effect-rx/rx-react';
-import { Option, pipe } from 'effect';
-
-import { createExtension, ROOT_ID } from '@dxos/app-graph';
-import { type SettingsStore, type SettingsValue } from '@dxos/local-storage';
-import { isNonNullable } from '@dxos/util';
-
-import { SETTINGS_ID, SETTINGS_KEY, SETTINGS_PLUGIN, SettingsAction } from './actions';
-import { Capabilities } from '../common';
-import { contributes, type PluginMeta, type PluginContext } from '../core';
-import { createIntent } from '../plugin-intent';
-
-export default (context: PluginContext) =>
-  contributes(Capabilities.AppGraphBuilder, [
-    createExtension({
-      id: `${SETTINGS_PLUGIN}/action`,
-      actions: (node) =>
-        Rx.make((get) =>
-          pipe(
-            get(node),
-            Option.flatMap((node) => (node.id === ROOT_ID ? Option.some(node) : Option.none())),
-            Option.map(() => [
-              {
-                id: SETTINGS_PLUGIN,
-                data: async () => {
-                  const { dispatchPromise: dispatch } = context.getCapability(Capabilities.IntentDispatcher);
-                  await dispatch(createIntent(SettingsAction.Open));
-                },
-                properties: {
-                  label: ['open settings label', { ns: SETTINGS_PLUGIN }],
-                  icon: 'ph--gear--regular',
-                  disposition: 'menu',
-                  keyBinding: {
-                    macos: 'meta+,',
-                    windows: 'alt+,',
-                  },
-                },
-              },
-            ]),
-            Option.getOrElse(() => []),
-          ),
-        ),
-    }),
-    createExtension({
-      id: `${SETTINGS_PLUGIN}/core`,
-      connector: (node) =>
-        Rx.make((get) =>
-          pipe(
-            get(node),
-            Option.flatMap((node) => (node.id === ROOT_ID ? Option.some(node) : Option.none())),
-            Option.map(() => [
-              {
-                id: SETTINGS_ID,
-                type: SETTINGS_PLUGIN,
-                properties: {
-                  label: ['app settings label', { ns: SETTINGS_PLUGIN }],
-                  icon: 'ph--gear--regular',
-                  disposition: 'pin-end',
-                  position: 'hoist',
-                  testId: 'treeView.appSettings',
-                },
-              },
-            ]),
-            Option.getOrElse(() => []),
-          ),
-        ),
-    }),
-    createExtension({
-      id: `${SETTINGS_PLUGIN}/core-plugins`,
-      connector: (node) =>
-        Rx.make((get) =>
-          pipe(
-            get(node),
-            Option.flatMap((node) => (node.id !== SETTINGS_ID ? Option.none() : Option.some(node))),
-            Option.map(() => {
-              const manager = get(context.capability(Capabilities.PluginManager));
-              const [settingsStore] = get(context.capabilities(Capabilities.SettingsStore));
-              return [
-                ...manager.plugins
-                  .filter((plugin) => manager.core.includes(plugin.meta.id))
-                  .map((plugin): [PluginMeta, SettingsStore<SettingsValue>] | null => {
-                    const settings = settingsStore?.getStore(plugin.meta.id);
-                    if (!settings) {
-                      return null;
-                    }
-
-                    return [plugin.meta, settings];
-                  })
-                  .filter(isNonNullable)
-                  .map(([meta, settings]) => ({
-                    id: `${SETTINGS_KEY}:${meta.id.replaceAll('/', ':')}`,
-                    type: 'category',
-                    data: settings,
-                    properties: {
-                      label: meta.name ?? meta.id,
-                      icon: meta.icon ?? 'ph--circle--regular',
-                    },
-                  })),
-
-                {
-                  id: `${SETTINGS_KEY}:custom-plugins`,
-                  type: 'category',
-                  properties: {
-                    label: ['custom plugins label', { ns: SETTINGS_PLUGIN }],
-                    icon: 'ph--squares-four--regular',
-                    role: 'branch',
-                    disposition: 'collection',
-                  },
-                },
-              ];
-            }),
-            Option.getOrElse(() => []),
-          ),
-        ),
-    }),
-    createExtension({
-      id: `${SETTINGS_PLUGIN}/custom-plugins`,
-      connector: (node) =>
-        Rx.make((get) =>
-          pipe(
-            get(node),
-            Option.flatMap((node) =>
-              node.id !== `${SETTINGS_KEY}:custom-plugins` ? Option.none() : Option.some(node),
-            ),
-            Option.map(() => {
-              const manager = get(context.capability(Capabilities.PluginManager));
-              const [settingsStore] = get(context.capabilities(Capabilities.SettingsStore));
-              return manager.plugins
-                .filter((plugin) => !manager.core.includes(plugin.meta.id))
-                .map((plugin): [PluginMeta, SettingsStore<SettingsValue>] | null => {
-                  const settings = settingsStore?.getStore(plugin.meta.id);
-                  if (!settings) {
-                    return null;
-                  }
-
-                  return [plugin.meta, settings];
-                })
-                .filter(isNonNullable)
-                .map(([meta, settings]) => ({
-                  id: `${SETTINGS_KEY}:${meta.id.replaceAll('/', ':')}`,
-                  type: 'category',
-                  data: settings,
-                  properties: {
-                    label: meta.name ?? meta.id,
-                    icon: meta.icon ?? 'ph--circle--regular',
-                  },
-                }));
-            }),
-            Option.getOrElse(() => []),
-          ),
-        ),
-    }),
-  ]);

package/src/plugin-settings/index.ts

@@ -1,6 +0,0 @@
-//
-// Copyright 2024 DXOS.org
-//
-
-export * from './actions';
-export * from './SettingsPlugin';

package/src/plugin-settings/intent-resolver.ts

@@ -1,34 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import { pipe } from 'effect';
-
-import { SETTINGS_ID, SETTINGS_KEY, SettingsAction } from './actions';
-import { Capabilities, LayoutAction } from '../common';
-import { contributes } from '../core';
-import { createResolver, createIntent, chain } from '../plugin-intent';
-
-export default () =>
-  contributes(
-    Capabilities.IntentResolver,
-    createResolver({
-      intent: SettingsAction.Open,
-      resolve: ({ plugin }) => {
-        const openSettings = createIntent(LayoutAction.SwitchWorkspace, { part: 'workspace', subject: SETTINGS_ID });
-        return {
-          intents: [
-            plugin
-              ? pipe(
-                  openSettings,
-                  chain(LayoutAction.Open, {
-                    part: 'main',
-                    subject: [`${SETTINGS_KEY}:${plugin.replaceAll('/', ':')}`],
-                  }),
-                )
-              : openSettings,
-          ],
-        };
-      },
-    }),
-  );

package/src/plugin-settings/store.ts

@@ -1,33 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import { RootSettingsStore } from '@dxos/local-storage';
-
-import { Capabilities } from '../common';
-import { contributes, type PluginContext } from '../core';
-
-export default (context: PluginContext) => {
-  // TODO(wittjosiah): Replace with rx?
-  const settingsStore = new RootSettingsStore();
-
-  let previous: Capabilities.Settings[] = [];
-  const registry = context.getCapability(Capabilities.RxRegistry);
-  const cancel = registry.subscribe(
-    context.capabilities(Capabilities.Settings),
-    (allSettings) => {
-      const added = allSettings.filter((setting) => !previous.includes(setting));
-      const removed = previous.filter((setting) => !allSettings.includes(setting));
-      previous = allSettings;
-      added.forEach((setting) => {
-        settingsStore.createStore(setting as any);
-      });
-      removed.forEach((setting) => {
-        settingsStore.removeStore(setting.prefix);
-      });
-    },
-    { immediate: true },
-  );
-
-  return contributes(Capabilities.SettingsStore, settingsStore, () => cancel());
-};

package/src/plugin-settings/translations.ts

@@ -1,17 +0,0 @@
-//
-// Copyright 2023 DXOS.org
-//
-
-import { SETTINGS_PLUGIN } from './actions';
-
-export default [
-  {
-    'en-US': {
-      [SETTINGS_PLUGIN]: {
-        'open settings label': 'Open settings',
-        'app settings label': 'Settings',
-        'custom plugins label': 'Plugins',
-      },
-    },
-  },
-];

package/src/react/ErrorBoundary.tsx

@@ -1,45 +0,0 @@
-//
-// Copyright 2023 DXOS.org
-//
-
-import React, { Component, type FC, type PropsWithChildren } from 'react';
-
-type Props = PropsWithChildren<{ data?: any; fallback: FC<{ data?: any; error: Error; reset: () => void }> }>;
-type State = { error: Error | undefined };
-
-/**
- * Surface error boundary.
- *
- * For basic usage prefer providing a fallback component to `Surface`.
- *
- * For more information on error boundaries, see:
- * https://react.dev/reference/react/Component#catching-rendering-errors-with-an-error-boundary
- */
-export class ErrorBoundary extends Component<Props, State> {
-  constructor(props: Props) {
-    super(props);
-    this.state = { error: undefined };
-  }
-
-  static getDerivedStateFromError(error: Error): { error: Error } {
-    return { error };
-  }
-
-  override componentDidUpdate(prevProps: Props): void {
-    if (prevProps.data !== this.props.data) {
-      this.resetError();
-    }
-  }
-
-  override render(): string | number | boolean | React.JSX.Element | Iterable<React.ReactNode> | null | undefined {
-    if (this.state.error) {
-      return <this.props.fallback data={this.props.data} error={this.state.error} reset={this.resetError} />;
-    }
-
-    return this.props.children;
-  }
-
-  private resetError(): void {
-    this.setState({ error: undefined });
-  }
-}

package/src/react/IntentContext.tsx

@@ -1,34 +0,0 @@
-//
-// 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 { usePluginManager } from './PluginManagerProvider';
-import { Capabilities } from '../common';
-import { type AnyIntentResolver, type IntentContext } from '../plugin-intent';
-
-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,96 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import '@dxos-theme';
-
-import React, { useCallback, useState } from 'react';
-
-import { faker } from '@dxos/random';
-import { Button, List, ListItem } from '@dxos/react-ui';
-import { withLayout, withTheme } from '@dxos/storybook-utils';
-
-import { PluginManagerProvider, usePluginManager } from './PluginManagerProvider';
-import { Surface, useSurfaces } from './Surface';
-import { Capabilities, createSurface } from '../common';
-import { type PluginManager } from '../core';
-import { setupPluginManager } from '../testing';
-
-const randomColor = (): string => {
-  const hue = faker.number.int({ min: 0, max: 360 });
-  const saturation = faker.number.int({ min: 50, max: 90 });
-  const lightness = faker.number.int({ min: 40, max: 70 });
-  return `hsl(${hue}, ${saturation}%, ${lightness}%)`;
-};
-
-const Story = () => {
-  const manager = usePluginManager();
-  const surfaces = useSurfaces();
-  const [picked, setPicked] = useState('test');
-
-  const handleAdd = useCallback(() => {
-    const id = `test-${faker.number.int({ min: 0, max: 1_000_000 })}`;
-    const backgroundColor = randomColor();
-
-    manager.context.contributeCapability({
-      module: 'test',
-      interface: Capabilities.ReactSurface,
-      implementation: createSurface({
-        id,
-        role: id,
-        component: () => (
-          <div className='flex-1' style={{ backgroundColor }}>
-            {id}
-          </div>
-        ),
-      }),
-    });
-
-    setPicked(id);
-  }, [manager]);
-
-  const handlePick = useCallback(() => {
-    setPicked(faker.helpers.arrayElement(surfaces).id);
-  }, [surfaces]);
-
-  return (
-    <div className='flex flex-col gap-2'>
-      <div className='flex gap-2'>
-        <Button onClick={handleAdd}>Add</Button>
-        <Button onClick={handlePick}>Pick</Button>
-      </div>
-      <div className='flex gap-2'>
-        <div className='flex-1'>
-          <List itemSizes='one'>
-            {surfaces.map((surface) => (
-              <ListItem.Root key={surface.id} id={surface.id}>
-                <ListItem.Heading classNames='grow pbs-2'>{surface.id}</ListItem.Heading>
-              </ListItem.Root>
-            ))}
-          </List>
-        </div>
-        <div className='flex-1'>
-          <Surface role={picked} limit={1} />
-        </div>
-      </div>
-    </div>
-  );
-};
-
-export default {
-  title: 'sdk/app-framework/Surface',
-  render: ({ manager }: { manager: PluginManager }) => {
-    return (
-      <PluginManagerProvider value={manager}>
-        <Story />
-      </PluginManagerProvider>
-    );
-  },
-  // NOTE: Intentionally not using withPluginManager to try to reduce surface area of the story.
-  decorators: [withTheme, withLayout()],
-  args: {
-    manager: setupPluginManager(),
-  },
-};
-
-export const Default = {};

package/src/react/Surface.tsx

@@ -1,77 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import React, { memo, forwardRef, Suspense, useMemo, Fragment } from 'react';
-
-import { useDefaultValue } from '@dxos/react-hooks';
-import { byPosition } from '@dxos/util';
-
-import { ErrorBoundary } from './ErrorBoundary';
-import { useCapabilities } from './useCapabilities';
-import { Capabilities, type SurfaceDefinition, type SurfaceProps } from '../common';
-import { type PluginContext } from '../core';
-
-const DEFAULT_PLACEHOLDER = <Fragment />;
-
-/**
- * @internal
- */
-export const useSurfaces = () => {
-  const surfaces = useCapabilities(Capabilities.ReactSurface);
-  return useMemo(() => surfaces.flat(), [surfaces]);
-};
-
-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);
-};
-
-/**
- * @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;
-};
-
-/**
- * A surface is a named region of the screen that can be populated by plugins.
- */
-export const Surface = memo(
-  forwardRef<HTMLElement, SurfaceProps>(
-    ({ id: _id, role, data: _data, limit, fallback, 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 anyways.
-      //   In the future, it would be nice to be able to bucket the surface contributions by role.
-      const surfaces = useSurfaces();
-      const data = useDefaultValue(_data, () => ({}));
-
-      // 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(({ component: Component, id }) => (
-        <Component ref={forwardedRef} key={id} id={id} role={role} data={data} limit={limit} {...rest} />
-      ));
-
-      const suspense = <Suspense fallback={placeholder}>{nodes}</Suspense>;
-
-      return fallback ? (
-        <ErrorBoundary data={data} fallback={fallback}>
-          {suspense}
-        </ErrorBoundary>
-      ) : (
-        suspense
-      );
-    },
-  ),
-);
-
-Surface.displayName = 'Surface';

package/src/react/common.ts

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

package/src/react/index.ts

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

package/src/react/useCapabilities.ts

@@ -1,30 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import { useRxValue } from '@effect-rx/rx-react';
-
-import { invariant } from '@dxos/invariant';
-
-import { usePluginManager } from './PluginManagerProvider';
-import { type InterfaceDef } from '../core';
-
-/**
- * Hook to request capabilities from the plugin context.
- * @returns An array of capabilities.
- */
-export const useCapabilities = <T>(interfaceDef: InterfaceDef<T>) => {
-  const manager = usePluginManager();
-  return useRxValue(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]);
-};

package/src/worker.ts

@@ -1,11 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-// Entrypoint for using plugins in workers runtimes (e.g. Cloudflare Workers, etc.)
-// Excludes all frontend code & dependencies (e.g. localStorage, React, etc.)
-
-export * from './core';
-// NOTE: Common includes browser capabilities but they are types only.
-export * from './common';
-export * from './plugin-intent';

package/typedoc/.nojekyll

@@ -1 +0,0 @@
-TypeDoc added this file to prevent GitHub Pages from using Jekyll. You can turn off this behavior by setting the `githubPages` option to false.

package/typedoc/assets/hierarchy.js

@@ -1 +0,0 @@
-window.hierarchyData = "eJyrVirKzy8pVrKKjtVRKkpNy0lNLsnMzytWsqqurQUAmx4Kpg=="