@dxos/app-framework 0.8.4-main.a4bbb77 → 0.8.4-main.abd8ff62ef

package/src/common/layout.ts

@@ -1,277 +0,0 @@
-//
-// Copyright 2023 DXOS.org
-//
-
-import { Schema } from 'effect';
-
-import { Label } from '../plugin-intent';
-
-const LAYOUT_PLUGIN = 'dxos.org/plugin/layout';
-
-/**
- * Expected payload for layout actions.
- */
-export namespace LayoutAction {
-  export const UPDATE_LAYOUT = `${LAYOUT_PLUGIN}/action/update-layout`;
-
-  /**
-   * Generic layout action.
-   */
-  export class UpdateLayout extends Schema.TaggedClass<UpdateLayout>()(UPDATE_LAYOUT, {
-    input: Schema.Struct({
-      part: Schema.String.annotations({ description: 'The part of the layout to mutate.' }),
-      subject: Schema.optional(Schema.Any.annotations({ description: 'The subject of the layout update.' })),
-      options: Schema.optional(
-        Schema.Record({ key: Schema.String, value: Schema.Any }).annotations({
-          description: 'Additional options for the layout action.',
-        }),
-      ),
-    }),
-    output: Schema.Void,
-  }) {}
-
-  //
-  // Common layout actions.
-  //
-
-  // NOTE: These are layout actions which are currently in common use.
-  //  They constrain the generic layout action types to provide additional type safety.
-  //  However, they all follow the same generic structure and intent id.
-  //  This allows for plugins to update the layout without depending on a specific layout plugin.
-  //  The expectation is that other norms other than these will emerge over time.
-
-  export class SetLayoutMode extends Schema.TaggedClass<SetLayoutMode>()(UPDATE_LAYOUT, {
-    input: Schema.Struct({
-      part: Schema.Literal('mode').annotations({ description: 'Setting the layout mode.' }),
-      subject: Schema.optional(
-        Schema.String.annotations({ description: 'Item which is the subject of the new layout mode.' }),
-      ),
-      options: Schema.Union(
-        Schema.Struct({ mode: Schema.String.annotations({ description: 'The new layout mode.' }) }),
-        Schema.Struct({ revert: Schema.Boolean.annotations({ description: 'Revert to the previous layout mode.' }) }),
-      ),
-    }),
-    output: Schema.Void,
-  }) {}
-
-  export class UpdateSidebar extends Schema.TaggedClass<UpdateSidebar>()(UPDATE_LAYOUT, {
-    input: Schema.Struct({
-      part: Schema.Literal('sidebar').annotations({ description: 'Updating the sidebar.' }),
-      subject: Schema.optional(
-        Schema.String.annotations({ description: 'URI of the component to display in the sidebar.' }),
-      ),
-      options: Schema.optional(
-        Schema.Struct({
-          state: Schema.Literal('closed', 'collapsed', 'expanded').annotations({
-            description: 'Whether the sidebar is closed, collapsed, or expanded.',
-          }),
-        }),
-      ),
-    }),
-    output: Schema.Void,
-  }) {}
-
-  export class UpdateComplementary extends Schema.TaggedClass<UpdateComplementary>()(UPDATE_LAYOUT, {
-    input: Schema.Struct({
-      part: Schema.Literal('complementary').annotations({ description: 'Updating the complementary sidebar.' }),
-      subject: Schema.optional(
-        Schema.String.annotations({ description: 'URI of the component to display in the complementary area.' }),
-      ),
-      options: Schema.optional(
-        Schema.Struct({
-          state: Schema.Literal('closed', 'collapsed', 'expanded').annotations({
-            description: 'Whether the complementary sidebar is closed, collapsed, or expanded.',
-          }),
-        }),
-      ),
-    }),
-    output: Schema.Void,
-  }) {}
-
-  export class UpdateDialog extends Schema.TaggedClass<UpdateDialog>()(UPDATE_LAYOUT, {
-    input: Schema.Struct({
-      part: Schema.Literal('dialog').annotations({ description: 'Updating the dialog.' }),
-      subject: Schema.optional(
-        Schema.String.annotations({ description: 'URI of the component to display in the dialog.' }),
-      ),
-      options: Schema.Struct({
-        state: Schema.optional(Schema.Boolean.annotations({ description: 'Whether the dialog is open or closed.' })),
-        type: Schema.optional(Schema.Literal('default', 'alert').annotations({ description: 'The type of dialog.' })),
-        blockAlign: Schema.optional(
-          Schema.Literal('start', 'center', 'end').annotations({ description: 'The alignment of the dialog.' }),
-        ),
-        overlayClasses: Schema.optional(
-          Schema.String.annotations({ description: 'Additional classes for the dialog overlay.' }),
-        ),
-        overlayStyle: Schema.optional(
-          Schema.Record({ key: Schema.String, value: Schema.Any }).annotations({
-            description: 'Additional styles for the dialog overlay.',
-          }),
-        ),
-        props: Schema.optional(
-          Schema.Record({ key: Schema.String, value: Schema.Any }).annotations({
-            description: 'Additional props for the dialog.',
-          }),
-        ),
-      }),
-    }),
-    output: Schema.Void,
-  }) {}
-
-  export class UpdatePopover extends Schema.TaggedClass<UpdatePopover>()(UPDATE_LAYOUT, {
-    input: Schema.Struct({
-      part: Schema.Literal('popover').annotations({ description: 'Updating the popover.' }),
-      subject: Schema.optional(
-        Schema.Any.annotations({
-          description: 'URI of the component to display in the popover or data to pass to the popover.',
-        }),
-      ),
-      options: Schema.Struct({
-        side: Schema.optional(
-          Schema.Literal('top', 'right', 'bottom', 'left').annotations({ description: 'The side of the anchor.' }),
-        ),
-        state: Schema.optional(Schema.Boolean.annotations({ description: 'Whether the popover is open or closed.' })),
-        props: Schema.optional(
-          Schema.Record({ key: Schema.String, value: Schema.Any }).annotations({
-            description: 'Additional props for the popover.',
-          }),
-        ),
-      }).pipe(
-        Schema.extend(
-          Schema.Union(
-            Schema.Struct({
-              variant: Schema.Literal('virtual'),
-              anchor: Schema.Any.annotations({ description: 'The DOM element to anchor the popover to.' }),
-            }),
-            Schema.Struct({
-              variant: Schema.optional(Schema.Literal('react')),
-              anchorId: Schema.String.annotations({
-                description: 'An id that can be used to determine whether to render the anchor subcomponent.',
-              }),
-            }),
-          ),
-        ),
-      ),
-    }),
-    output: Schema.Void,
-  }) {}
-
-  export const Toast = Schema.Struct({
-    id: Schema.String.annotations({ description: 'The id of the toast.' }),
-    title: Schema.optional(Label.annotations({ description: 'The title of the toast.' })),
-    description: Schema.optional(Label.annotations({ description: 'The description of the toast.' })),
-    icon: Schema.optional(Schema.String.annotations({ description: 'The icon of the toast.' })),
-    duration: Schema.optional(Schema.Number.annotations({ description: 'The duration of the toast.' })),
-    closeLabel: Schema.optional(Label.annotations({ description: 'The label of the close button.' })),
-    actionLabel: Schema.optional(Label.annotations({ description: 'The label of the action button.' })),
-    actionAlt: Schema.optional(Label.annotations({ description: 'The alt text of the action button.' })),
-    onAction: Schema.optional(
-      Schema.Any.annotations({ description: 'The action to perform when the action button is clicked.' }),
-    ),
-  });
-
-  export interface Toast extends Omit<Schema.Schema.Type<typeof Toast>, 'onAction'> {
-    onAction?: () => void;
-  }
-
-  export class AddToast extends Schema.TaggedClass<AddToast>()(UPDATE_LAYOUT, {
-    input: Schema.Struct({
-      part: Schema.Literal('toast').annotations({ description: 'Adding a toast.' }),
-      subject: Toast.annotations({ description: 'The toast to add.' }),
-    }),
-    output: Schema.Void,
-  }) {}
-
-  export class SwitchWorkspace extends Schema.TaggedClass<SwitchWorkspace>()(UPDATE_LAYOUT, {
-    input: Schema.Struct({
-      part: Schema.Literal('workspace').annotations({ description: 'Switching the workspace.' }),
-      subject: Schema.String.annotations({ description: 'The id of the workspace to switch to.' }),
-    }),
-    output: Schema.Void,
-  }) {}
-
-  export class RevertWorkspace extends Schema.TaggedClass<RevertWorkspace>()(UPDATE_LAYOUT, {
-    input: Schema.Struct({
-      part: Schema.Literal('workspace').annotations({ description: 'Switching the workspace.' }),
-      options: Schema.Struct({
-        revert: Schema.Literal(true).annotations({ description: 'Revert to the previous workspace.' }),
-      }),
-    }),
-    output: Schema.Void,
-  }) {}
-
-  export class Open extends Schema.TaggedClass<Open>()(UPDATE_LAYOUT, {
-    input: Schema.Struct({
-      part: Schema.Literal('main').annotations({ description: 'Opening an item in the main content area.' }),
-      subject: Schema.Array(Schema.String.annotations({ description: 'Ids of the items to open.' })),
-      options: Schema.optional(
-        Schema.Struct({
-          state: Schema.optional(Schema.Literal(true).annotations({ description: 'The items are being added.' })),
-          variant: Schema.optional(Schema.String.annotations({ description: 'The variant of the item to open.' })),
-          key: Schema.optional(
-            Schema.String.annotations({
-              description: 'If provided, will replace item with a matching key (id prefix).',
-            }),
-          ),
-          workspace: Schema.optional(Schema.String.annotations({ description: 'The workspace to open the items in.' })),
-          scrollIntoView: Schema.optional(Schema.Boolean.annotations({ description: 'Scroll the items into view.' })),
-          pivotId: Schema.optional(
-            Schema.String.annotations({ description: 'The id of the item to place new items next to.' }),
-          ),
-          positioning: Schema.optional(
-            Schema.Union(
-              Schema.Literal('start').annotations({ description: 'The items are being added before the pivot item.' }),
-              Schema.Literal('end').annotations({ description: 'The items are being added after the pivot item.' }),
-            ),
-          ),
-        }),
-      ),
-    }),
-    output: Schema.Void,
-  }) {}
-
-  export class Set extends Schema.TaggedClass<Set>()(UPDATE_LAYOUT, {
-    input: Schema.Struct({
-      part: Schema.Literal('main').annotations({ description: 'Setting items in the main content area.' }),
-      subject: Schema.Array(Schema.String.annotations({ description: 'Ids of the items to set.' })),
-      options: Schema.Struct({
-        override: Schema.Literal(true).annotations({
-          description: 'Override the current items in the main content area.',
-        }),
-      }),
-    }),
-    output: Schema.Void,
-  }) {}
-
-  export class Close extends Schema.TaggedClass<Close>()(UPDATE_LAYOUT, {
-    input: Schema.Struct({
-      part: Schema.Literal('main').annotations({ description: 'Closing items in the main content area.' }),
-      subject: Schema.Array(Schema.String.annotations({ description: 'Ids of the items to close.' })),
-      options: Schema.Struct({
-        state: Schema.Literal(false).annotations({ description: 'The items are being removed.' }),
-      }),
-    }),
-    output: Schema.Void,
-  }) {}
-
-  export class ScrollIntoView extends Schema.TaggedClass<ScrollIntoView>()(UPDATE_LAYOUT, {
-    input: Schema.Struct({
-      part: Schema.Literal('current').annotations({ description: 'Setting the current item' }),
-      subject: Schema.optional(Schema.String.annotations({ description: 'The id of the item to set as current.' })),
-      options: Schema.optional(
-        Schema.Record({ key: Schema.String, value: Schema.Any }).annotations({
-          description: 'Additional options for the scroll into view.',
-        }),
-      ),
-    }),
-    output: Schema.Void,
-  }) {}
-
-  export class Expose extends Schema.TaggedClass<Expose>()(UPDATE_LAYOUT, {
-    input: Schema.Struct({
-      part: Schema.Literal('navigation').annotations({ description: 'Exposing an item in the navigation area.' }),
-      subject: Schema.String.annotations({ description: 'The id of the item to expose.' }),
-    }),
-    output: Schema.Void,
-  }) {}
-}

package/src/common/surface.ts

@@ -1,83 +0,0 @@
-//
-// Copyright 2023 DXOS.org
-//
-
-import type { ComponentType, PropsWithChildren, ReactNode } from 'react';
-
-import { type GuardedType, type MakeOptional, type Position } from '@dxos/util';
-
-import { type ErrorBoundary } from '../react';
-
-/**
- * SurfaceProps are the props that are passed to the Surface component.
- */
-export type SurfaceProps<T extends Record<string, any> = Record<string, unknown>> = {
-  /**
-   * If specified, the Surface will be wrapped in an error boundary.
-   * The fallback component will be rendered if an error occurs.
-   */
-  fallback?: ErrorBoundary['props']['fallback'];
-
-  /**
-   * If specified, the Surface will be wrapped in a suspense boundary.
-   * The placeholder component will be rendered while the surface component is loading.
-   */
-  placeholder?: ReactNode;
-} & MakeOptional<CoreSurfaceProps<T>, 'id' | 'data'> &
-  // Additional props to pass to the component.
-  // These props are not used by Surface itself but may be used by components which resolve the surface.
-  // Exclude known prop names to prevent overriding well-defined props.
-  {
-    [K in keyof Record<string, any>]: K extends keyof CoreSurfaceProps<T> | 'fallback' | 'placeholder' ? never : any;
-  };
-
-// NOTE: If `[key: string]: unknown` is included in shared types, when re-used other fields become unknown as well.
-type CoreSurfaceProps<T extends Record<string, any> = Record<string, unknown>> = PropsWithChildren<{
-  /**
-   * ID for debugging.
-   */
-  id: string;
-
-  /**
-   * Role defines how the data should be rendered.
-   */
-  role: string;
-
-  /**
-   * The data to be rendered by the surface.
-   */
-  data: T;
-
-  /**
-   * If more than one component is resolved, the limit determines how many are rendered.
-   */
-  limit?: number | undefined;
-}>;
-
-type SurfaceComponentProps<T extends Record<string, any> = Record<string, unknown>> = CoreSurfaceProps<T> &
-  Record<string, any>;
-
-/**
- * React component used to render a surface once is has matched.
- */
-export type SurfaceComponent<T extends Record<string, any> = Record<string, unknown>> = ComponentType<
-  SurfaceComponentProps<T>
->;
-
-/**
- * Definition of when a SurfaceComponent should be rendered.
- */
-export type SurfaceDefinition<T extends Record<string, any> = any> = Readonly<{
-  id: string;
-  role: string | string[];
-  position?: Position;
-  filter?: (data: Record<string, unknown>) => data is T;
-  component: SurfaceComponent<GuardedType<SurfaceDefinition<T>['filter']>>;
-}>;
-
-/**
- * Creates a surface definition.
- */
-export const createSurface = <T extends Record<string, any> = any>(
-  definition: SurfaceDefinition<T>,
-): SurfaceDefinition<T> => definition;

package/src/components/App.stories.tsx

@@ -1,33 +0,0 @@
-//
-// Copyright 2022 DXOS.org
-//
-
-import { type Meta, type StoryObj } from '@storybook/react-vite';
-import React from 'react';
-
-import { withTheme } from '@dxos/react-ui/testing';
-
-import { useApp } from './useApp';
-
-const DefaultStory = () => {
-  const App = useApp({
-    placeholder: () => <div className='fixed inset-0 flex items-center justify-center'>Loading...</div>,
-  });
-
-  return <App />;
-};
-
-const meta = {
-  title: 'sdk/app-framework/App',
-  render: DefaultStory,
-  decorators: [withTheme],
-  parameters: {
-    layout: 'fullscreen',
-  },
-} satisfies Meta;
-
-export default meta;
-
-type Story = StoryObj<typeof meta>;
-
-export const Default: Story = {};

package/src/components/App.tsx

@@ -1,59 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import React, { type PropsWithChildren } from 'react';
-
-import { Capabilities } from '../common';
-import { topologicalSort } from '../helpers';
-import { useCapabilities } from '../react';
-
-import { type UseAppOptions } from './useApp';
-import { LoadingState, useLoading } from './useLoading';
-
-export type AppProps = Pick<UseAppOptions, 'placeholder' | 'debounce'> & {
-  state: { ready: boolean; error: unknown };
-};
-
-export const App = ({ placeholder: Placeholder, state, debounce }: AppProps) => {
-  const reactContexts = useCapabilities(Capabilities.ReactContext);
-  const reactRoots = useCapabilities(Capabilities.ReactRoot);
-  const stage = useLoading(state, debounce);
-
-  if (state.error) {
-    // This triggers the error boundary to provide UI feedback for the startup error.
-    throw state.error;
-  }
-
-  // TODO(wittjosiah): Consider using Suspense instead.
-  if (stage < LoadingState.Done) {
-    if (!Placeholder) {
-      return null;
-    }
-
-    return <Placeholder stage={stage} />;
-  }
-
-  const ComposedContext = composeContexts(reactContexts);
-  return (
-    <ComposedContext>
-      {reactRoots.map(({ id, root: Component }) => (
-        <Component key={id} />
-      ))}
-    </ComposedContext>
-  );
-};
-
-const composeContexts = (contexts: Capabilities.ReactContext[]) => {
-  if (contexts.length === 0) {
-    return ({ children }: PropsWithChildren) => <>{children}</>;
-  }
-
-  return topologicalSort(contexts)
-    .map(({ context }) => context)
-    .reduce((Acc, Next) => ({ children }) => (
-      <Acc>
-        <Next>{children}</Next>
-      </Acc>
-    ));
-};

package/src/components/DefaultFallback.tsx

@@ -1,26 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import React from 'react';
-
-/**
- * NOTE: Default fallback should not use tailwind or theme.
- */
-export const DefaultFallback = ({ error }: { error: Error }) => {
-  return (
-    <div
-      style={{
-        margin: '1rem',
-        padding: '1rem',
-        overflow: 'hidden',
-        border: '4px solid teal',
-        borderRadius: '1rem',
-      }}
-    >
-      {/* TODO(wittjosiah): Link to docs for replacing default. */}
-      <h1 style={{ margin: '0.5rem 0', fontSize: '1.2rem' }}>[ERROR]: {error.message}</h1>
-      <pre style={{ overflow: 'auto', fontSize: '1rem', whiteSpace: 'pre-wrap', color: '#888888' }}>{error.stack}</pre>
-    </div>
-  );
-};

package/src/components/useApp.tsx

@@ -1,164 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import { RegistryContext } from '@effect-rx/rx-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 { ErrorBoundary, PluginManagerProvider } from '../react';
-
-import { App } from './App';
-import { DefaultFallback } from './DefaultFallback';
-
-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: _pluginLoader,
-  plugins: _plugins,
-  core: _core,
-  defaults: _defaults,
-  placeholder,
-  fallback = DefaultFallback,
-  cacheEnabled = false,
-  safeMode = false,
-  debounce = 0,
-}: UseAppOptions) => {
-  const plugins = useDefaultValue(_plugins, () => []);
-  const core = useDefaultValue(_core, () => plugins.map(({ meta }) => meta.id));
-  const defaults = useDefaultValue(_defaults, () => []);
-
-  // TODO(wittjosiah): Provide a custom plugin loader which supports loading via url.
-  const pluginLoader = useMemo(
-    () =>
-      _pluginLoader ??
-      ((id: string) => {
-        const plugin = plugins.find((plugin) => plugin.meta.id === id);
-        invariant(plugin, `Plugin not found: ${id}`);
-        return plugin;
-      }),
-    [_pluginLoader, 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.RxRegistry,
-      implementation: manager.registry,
-      module: 'dxos.org/app-framework/rx-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.RxRegistry, 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;
-};