@dxos/app-framework 0.7.5-main.9d26e3a → 0.7.5-main.e9bb01b

package/src/plugins/common/navigation.ts

@@ -1,214 +0,0 @@
-//
-// Copyright 2024 DXOS.org
-//
-
-import { Schema as S } from '@effect/schema';
-
-import { pick } from '@dxos/util';
-
-import { type Plugin } from '../plugin-host';
-
-// NOTE(thure): These are chosen from RFC 1738’s `safe` characters: http://www.faqs.org/rfcs/rfc1738.html
-export const SLUG_LIST_SEPARATOR = '+';
-export const SLUG_ENTRY_SEPARATOR = '_';
-export const SLUG_KEY_VALUE_SEPARATOR = '-';
-export const SLUG_PATH_SEPARATOR = '~';
-export const SLUG_COLLECTION_INDICATOR = '';
-
-const LayoutEntrySchema = S.mutable(S.Struct({ id: S.String, path: S.optional(S.String) }));
-export type LayoutEntry = S.Schema.Type<typeof LayoutEntrySchema>;
-
-// TODO(Zan): Consider renaming the 'main' part to 'deck' part now that we are throwing out the old layout plugin.
-// TODO(Zan): Extend to all strings?
-const LayoutPartSchema = S.Union(
-  S.Literal('sidebar'),
-  S.Literal('main'),
-  S.Literal('solo'),
-  S.Literal('complementary'),
-  S.Literal('fullScreen'),
-);
-export type LayoutPart = S.Schema.Type<typeof LayoutPartSchema>;
-
-const LayoutPartsSchema = S.partial(
-  S.mutable(S.Record({ key: LayoutPartSchema, value: S.mutable(S.Array(LayoutEntrySchema)) })),
-);
-export type LayoutParts = S.Schema.Type<typeof LayoutPartsSchema>;
-
-const LayoutCoordinateSchema = S.mutable(S.Struct({ part: LayoutPartSchema, entryId: S.String }));
-export type LayoutCoordinate = S.Schema.Type<typeof LayoutCoordinateSchema>;
-
-const PartAdjustmentSchema = S.Union(
-  S.Literal('increment-start'),
-  S.Literal('increment-end'),
-  S.Literal('pin-start'),
-  S.Literal('pin-end'),
-  S.Literal('close'),
-  S.Literal('solo'),
-);
-export type PartAdjustment = S.Schema.Type<typeof PartAdjustmentSchema>;
-
-const LayoutAdjustmentSchema = S.mutable(
-  S.Struct({ layoutCoordinate: LayoutCoordinateSchema, type: PartAdjustmentSchema }),
-);
-export type LayoutAdjustment = S.Schema.Type<typeof LayoutAdjustmentSchema>;
-
-/** @deprecated */
-export const ActiveParts = S.Record({ key: S.String, value: S.Union(S.String, S.mutable(S.Array(S.String))) });
-export type ActiveParts = S.Schema.Type<typeof ActiveParts>;
-
-// TODO(burdon): Where should this go?
-export type LayoutContainerProps<T> = T & { role?: string; coordinate?: LayoutCoordinate };
-
-/**
- * Provides for a plugin that can manage the app navigation.
- */
-const LocationProvidesSchema = S.mutable(
-  S.Struct({
-    location: S.Struct({
-      active: LayoutPartsSchema,
-      closed: S.Array(S.String),
-    }),
-  }),
-);
-export type LocationProvides = S.Schema.Type<typeof LocationProvidesSchema>;
-
-/**
- * Type guard for layout plugins.
- */
-export const isLayoutParts = (value: unknown): value is LayoutParts => {
-  return S.is(LayoutPartsSchema)(value);
-};
-
-// Type guard for PartAdjustment.
-export const isLayoutAdjustment = (value: unknown): value is LayoutAdjustment => {
-  return S.is(LayoutAdjustmentSchema)(value);
-};
-
-export const parseNavigationPlugin = (plugin: Plugin): Plugin<LocationProvides> | undefined => {
-  const location = (plugin.provides as any)?.location;
-  if (!location) {
-    return undefined;
-  }
-
-  if (S.is(LocationProvidesSchema)({ location })) {
-    return plugin as Plugin<LocationProvides>;
-  }
-
-  return undefined;
-};
-
-/**
- * Utilities.
- */
-
-/** Extracts all unique IDs from the layout parts. */
-export const openIds = (layout: LayoutParts, parts?: LayoutPart[]): string[] => {
-  return Object.values(parts ? pick(layout, parts) : layout)
-    .flatMap((part) => part?.map((entry) => entry.id) ?? [])
-    .filter((id): id is string => id !== undefined);
-};
-
-export const firstIdInPart = (layout: LayoutParts | undefined, part: LayoutPart): string | undefined => {
-  if (!layout) {
-    return undefined;
-  }
-
-  return layout[part]?.at(0)?.id;
-};
-
-export const indexInPart = (
-  layout: LayoutParts | undefined,
-  layoutCoordinate: LayoutCoordinate | undefined,
-): number | undefined => {
-  if (!layout || !layoutCoordinate) {
-    return undefined;
-  }
-
-  const { part, entryId } = layoutCoordinate;
-  return layout[part]?.findIndex((entry) => entry.id === entryId);
-};
-
-export const partLength = (layout: LayoutParts | undefined, part: LayoutPart | undefined): number => {
-  if (!layout || !part) {
-    return 0;
-  }
-
-  return layout[part]?.length ?? 0;
-};
-
-//
-// Intents
-//
-
-export const NAVIGATION_PLUGIN = 'dxos.org/plugin/navigation';
-export const NAVIGATION_ACTION = `${NAVIGATION_PLUGIN}/action`;
-
-/**
- * Expected payload for navigation actions.
- */
-// TODO(wittjosiah): These seem to be too deck-specific.
-export namespace NavigationAction {
-  /**
-   * An additive overlay to apply to `location.active` (i.e. the result is a union of previous active and the argument)
-   */
-  export class Open extends S.TaggedClass<Open>()(`${NAVIGATION_ACTION}/open`, {
-    input: S.Struct({
-      activeParts: ActiveParts,
-      noToggle: S.optional(S.Boolean),
-    }),
-    output: S.Struct({
-      open: S.Array(S.String),
-    }),
-  }) {}
-
-  /**
-   * Payload for adding an item to the active items.
-   */
-  export class AddToActive extends S.TaggedClass<AddToActive>()(`${NAVIGATION_ACTION}/add-to-active`, {
-    input: S.Struct({
-      id: S.String,
-      part: LayoutPartSchema,
-      scrollIntoView: S.optional(S.Boolean),
-      pivotId: S.optional(S.String),
-      positioning: S.optional(S.Literal('start', 'end')),
-    }),
-    output: S.Void,
-  }) {}
-
-  /**
-   * The active parts to directly set, to be used when working with URLs or restoring a specific state.
-   */
-  export class Set extends S.TaggedClass<Set>()(`${NAVIGATION_ACTION}/set`, {
-    input: S.Struct({
-      activeParts: ActiveParts,
-    }),
-    output: S.Void,
-  }) {}
-
-  /**
-   * A subtractive overlay to apply to `location.active` (i.e. the result is a subtraction from the previous active of the argument)
-   */
-  export class Close extends S.TaggedClass<Close>()(`${NAVIGATION_ACTION}/close`, {
-    input: S.Struct({
-      activeParts: ActiveParts,
-      noToggle: S.optional(S.Boolean),
-    }),
-    output: S.Void,
-  }) {}
-
-  /**
-   * An atomic transaction to apply to `location.active`, describing which element to (attempt to) move to which location.
-   */
-  export class Adjust extends S.TaggedClass<Adjust>()(`${NAVIGATION_ACTION}/adjust`, {
-    input: LayoutAdjustmentSchema,
-    output: S.Void,
-  }) {}
-
-  // TODO(wittjosiah): This action seems unrelated to the others.
-  export class Expose extends S.TaggedClass<Expose>()(`${NAVIGATION_ACTION}/expose`, {
-    input: S.Struct({
-      id: S.String,
-    }),
-    output: S.Void,
-  }) {}
-}

package/src/plugins/common/translations.ts

@@ -1,36 +0,0 @@
-//
-// Copyright 2023 DXOS.org
-//
-
-import { z } from 'zod';
-
-import { type Plugin } from '../plugin-host';
-
-// TODO(burdon): Replace zed with effect.
-export const ResourceKey = z.union([z.string(), z.record(z.any())]);
-export type ResourceKey = z.infer<typeof ResourceKey>;
-
-export const ResourceLanguage = z.record(ResourceKey);
-export type ResourceLanguage = z.infer<typeof ResourceLanguage>;
-
-/**
- * A resource is a collection of translations for a language.
- */
-export const Resource = z.record(ResourceLanguage);
-export type Resource = z.infer<typeof Resource>;
-
-/**
- * Provides for a plugin that exposes translations.
- */
-// TODO(wittjosiah): Rename to TranslationResourcesProvides.
-export type TranslationsProvides = {
-  translations: Readonly<Resource[]>;
-};
-
-/**
- * Type guard for translation plugins.
- */
-export const parseTranslationsPlugin = (plugin: Plugin) => {
-  const { success } = z.array(Resource).safeParse((plugin.provides as any).translations);
-  return success ? (plugin as Plugin<TranslationsProvides>) : undefined;
-};

package/src/plugins/helpers.ts

@@ -1,92 +0,0 @@
-//
-// Copyright 2023 DXOS.org
-//
-
-import { Context, type DisposeCallback } from '@dxos/context';
-import { raise } from '@dxos/debug';
-import { invariant } from '@dxos/invariant';
-
-import { type Plugin, type PluginDefinition } from './plugin-host';
-
-/**
- * Resolvers allow different instances of plugins to provide a particular capability.
- */
-export type PluginResolver<T> = (plugin: Plugin) => Plugin<T> | undefined;
-
-/**
- * Find a plugin by ID.
- */
-export const findPlugin = <T>(plugins: Plugin[], id: string): Plugin<T> | undefined => {
-  return plugins.find(
-    (plugin) => plugin.meta.id === id || (typeof plugin.meta.shortId === 'string' && plugin.meta.shortId === id),
-  ) as Plugin<T>;
-};
-
-/**
- * Find a plugin by ID, or raise an error if not found.
- */
-export const getPlugin = <T>(plugins: Plugin[], id: string): Plugin<T> => {
-  return findPlugin(plugins, id) ?? raise(new Error(`Plugin not found: ${id}`));
-};
-
-/**
- * Filter a list of plugins to only those that match a predicate.
- */
-export const filterPlugins = <T>(plugins: Plugin[], predicate: PluginResolver<T>): Plugin<T>[] =>
-  plugins.map((plugin) => predicate(plugin)).filter((plugin): plugin is Plugin<T> => !!plugin);
-
-/**
- * Resolves a plugin by predicate.
- *
- * @example
- * import { parseIntentPlugin, resolvePlugin } from '@dxos/app-framework';
- * const intentPlugin = resolvePlugin(plugins, parseIntentPlugin);
- */
-export const resolvePlugin = <T>(plugins: Plugin[], predicate: PluginResolver<T>): Plugin<T> | undefined =>
-  filterPlugins(plugins, predicate)[0];
-
-class PluginContext {
-  // TODO(burdon): Use Resource (@dima)?
-  public readonly ctx = new Context();
-
-  private _plugins?: Plugin[];
-
-  init(plugins: Plugin[]) {
-    this._plugins = plugins;
-  }
-
-  getPlugin<T>(id: string): Plugin<T> {
-    invariant(this._plugins);
-    return getPlugin(this._plugins, id);
-  }
-
-  resolvePlugin<T>(resolver: PluginResolver<T>): Plugin<T>;
-  resolvePlugin<T>(resolver: PluginResolver<T>, required = false): Plugin<T> | undefined {
-    invariant(this._plugins, 'context not initialized');
-    const plugin = resolvePlugin(this._plugins, resolver);
-    if (required && !plugin) {
-      // TODO(burdon): Resolver should have a name.
-      throw new Error('Plugin not found.');
-    }
-
-    return plugin;
-  }
-
-  onDispose(cb: DisposeCallback) {
-    this.ctx.onDispose(cb);
-  }
-
-  dispose() {
-    void this.ctx.dispose();
-  }
-}
-
-/**
- * Plugin helper with dependency injection and life-cycle support.
- */
-export const definePlugin = <Provides>(
-  cb: (context: PluginContext) => PluginDefinition<Provides>,
-): (() => PluginDefinition<Provides>) => {
-  const context = new PluginContext();
-  return () => cb(context);
-};

package/src/plugins/index.ts

@@ -1,11 +0,0 @@
-//
-// Copyright 2023 DXOS.org
-//
-
-export * from './common';
-export * from './helpers';
-
-export * from './plugin-intent';
-export * from './plugin-host';
-export * from './plugin-settings';
-export * from './plugin-surface';

package/src/plugins/plugin-host/HostPlugin.tsx

@@ -1,88 +0,0 @@
-//
-// Copyright 2023 DXOS.org
-//
-
-import React, { type ReactNode } from 'react';
-
-import { LocalStorageStore } from '@dxos/local-storage';
-
-import { PluginContainer } from './PluginContainer';
-import { type PluginContext, PluginProvider } from './PluginContext';
-import { type PluginDefinition, type PluginMeta } from './plugin';
-import { ErrorBoundary } from '../plugin-surface';
-
-export type HostPluginParams = {
-  plugins: Record<string, () => Promise<PluginDefinition>>;
-  // Ordered list of plugins.
-  meta: PluginMeta[];
-  core: string[];
-  defaults?: string[];
-  fallback?: ErrorBoundary['props']['fallback'];
-  placeholder?: ReactNode;
-};
-
-const HOST_PLUGIN = 'dxos.org/plugin/host';
-
-/**
- * Bootstraps an application by initializing plugins and rendering root components.
- */
-export const HostPlugin = ({
-  plugins,
-  meta,
-  core,
-  defaults = [],
-  fallback = DefaultFallback,
-  placeholder = null,
-}: HostPluginParams): PluginDefinition => {
-  const state = new LocalStorageStore<PluginContext>(HOST_PLUGIN, {
-    ready: false,
-    core,
-    enabled: [...defaults],
-    plugins: [],
-    available: meta.filter(({ id }) => !core.includes(id)),
-    // TODO(burdon): Functions should not be part of the settings type.
-    setPlugin: (id: string, enabled: boolean) => {
-      if (enabled) {
-        state.values.enabled.push(id);
-      } else {
-        const index = state.values.enabled.findIndex((enabled) => enabled === id);
-        index !== -1 && state.values.enabled.splice(index, 1);
-      }
-    },
-  });
-
-  // Register and load values.
-  state.prop({ key: 'enabled', type: LocalStorageStore.json<string[]>() });
-
-  return {
-    meta: {
-      id: HOST_PLUGIN,
-      name: 'Plugin host',
-    },
-    provides: {
-      context: ({ children }) => {
-        return <PluginProvider value={state.values}>{children}</PluginProvider>;
-      },
-      root: () => {
-        return (
-          <ErrorBoundary fallback={fallback}>
-            <PluginContainer plugins={plugins} core={core} state={state.values} placeholder={placeholder} />
-          </ErrorBoundary>
-        );
-      },
-    },
-  };
-};
-
-/**
- * Fallback does not use tailwind or theme.
- */
-const DefaultFallback = ({ error }: { error: Error }) => {
-  return (
-    <div style={{ padding: '1rem' }}>
-      {/* TODO(wittjosiah): Link to docs for replacing default. */}
-      <h1 style={{ fontSize: '1.2rem', fontWeight: 700, margin: '0.5rem 0' }}>{error.message}</h1>
-      <pre>{error.stack}</pre>
-    </div>
-  );
-};

package/src/plugins/plugin-host/PluginContainer.tsx

@@ -1,120 +0,0 @@
-//
-// Copyright 2023 DXOS.org
-//
-
-import React, { type JSX, type FC, type PropsWithChildren, type ReactNode, useEffect, useState } from 'react';
-
-import { log } from '@dxos/log';
-
-import { type HostPluginParams } from './HostPlugin';
-import { type PluginContext } from './PluginContext';
-import { type Plugin, type PluginDefinition, type PluginProvides } from './plugin';
-
-export type PluginContainerProps = Pick<HostPluginParams, 'core'> & {
-  plugins: Record<string, () => Promise<PluginDefinition>>;
-  state: PluginContext;
-  placeholder: ReactNode;
-};
-
-/**
- * Root component initializes plugins.
- */
-export const PluginContainer = ({ plugins: definitions, core, state, placeholder }: PluginContainerProps) => {
-  const [error, setError] = useState<unknown>();
-
-  useEffect(() => {
-    log('initializing plugins', { enabled: state.enabled });
-    const t = setTimeout(async () => {
-      try {
-        const enabledIds = [...core, ...state.enabled];
-        const enabled = await Promise.all(
-          enabledIds
-            .map((id) => definitions[id])
-            // If local storage indicates a plugin is enabled, but it is not available, ignore it.
-            .filter((definition): definition is () => Promise<PluginDefinition> => Boolean(definition))
-            .map((definition) => definition()),
-        );
-
-        const plugins = await Promise.all(
-          enabled.map(async (definition) => {
-            const plugin = await initializePlugin(definition).catch((err) => {
-              log.error('Failed to initialize plugin:', { id: definition.meta.id, err });
-            });
-
-            log('initialized', { plugin: definition.meta.id });
-            return plugin;
-          }),
-        );
-
-        const initialized = plugins.filter((plugin): plugin is Plugin => Boolean(plugin));
-        log('plugins initialized', { plugins: initialized });
-
-        await Promise.all(enabled.map((plugin) => plugin.ready?.({ plugins: initialized })));
-        log('plugins ready', { plugins: initialized });
-
-        state.plugins = initialized;
-        state.ready = true;
-      } catch (err) {
-        setError(err);
-      }
-    });
-
-    return () => {
-      clearTimeout(t);
-      state.ready = false;
-      // TODO(wittjosiah): Does this ever need to be called prior to having dynamic plugins?
-      // void Promise.all(enabled.map((definition) => definition.unload?.()));
-    };
-  }, []);
-
-  if (error) {
-    throw error;
-  }
-
-  if (!state.ready) {
-    return <>{placeholder}</>;
-  }
-
-  const ComposedContext = composeContext(state.plugins);
-
-  return <ComposedContext>{rootComponents(state.plugins)}</ComposedContext>;
-};
-
-/**
- * Resolve a `PluginDefinition` into a fully initialized `Plugin`.
- */
-const initializePlugin = async <T, U>(pluginDefinition: PluginDefinition<T, U>): Promise<Plugin<T & U>> => {
-  const provides = await pluginDefinition.initialize?.();
-  return {
-    ...pluginDefinition,
-    provides: {
-      ...pluginDefinition.provides,
-      ...provides,
-    } as PluginProvides<T & U>,
-  };
-};
-
-const rootComponents = (plugins: Plugin[]) => {
-  return plugins
-    .map((plugin) => {
-      const Component = plugin.provides.root;
-      if (Component) {
-        return <Component key={plugin.meta.id} />;
-      } else {
-        return null;
-      }
-    })
-    .filter((node): node is JSX.Element => Boolean(node));
-};
-
-const composeContext = (plugins: Plugin[]) => {
-  return compose(plugins.map((p) => p.provides.context!).filter(Boolean));
-};
-
-const compose = (contexts: FC<PropsWithChildren>[]) => {
-  return [...contexts].reduce((Acc, Next) => ({ children }) => (
-    <Acc>
-      <Next>{children}</Next>
-    </Acc>
-  ));
-};

package/src/plugins/plugin-host/PluginContext.tsx

@@ -1,79 +0,0 @@
-//
-// Copyright 2024 DXOS.org
-//
-
-import { createContext, useContext, useMemo } from 'react';
-
-import { raise } from '@dxos/debug';
-import { nonNullable } from '@dxos/util';
-
-import { type Plugin, type PluginMeta } from './plugin';
-import { findPlugin, resolvePlugin } from '../helpers';
-
-export type PluginContext = {
-  /**
-   * All plugins are ready.
-   */
-  ready: boolean;
-
-  /**
-   * Core plugins.
-   */
-  core: string[];
-
-  /**
-   * Ids of plugins which are enabled on this device.
-   */
-  enabled: string[];
-
-  /**
-   * Initialized and ready plugins.
-   */
-  plugins: Plugin[];
-
-  /**
-   * All available plugins.
-   * NOTE: This is metadata rather than just ids because it includes plugins which have not been fully loaded yet.
-   */
-  available: PluginMeta[];
-
-  /**
-   * Mark plugin as enabled.
-   * Requires reload to take effect.
-   */
-  // TODO(burdon): Functions should not be part of the settings type.
-  setPlugin: (id: string, enabled: boolean) => void;
-};
-
-const PluginContext = createContext<PluginContext | undefined>(undefined);
-
-/**
- * Get all plugins.
- */
-export const usePlugins = (): PluginContext => useContext(PluginContext) ?? raise(new Error('Missing PluginContext'));
-
-/**
- * Get a plugin by ID.
- */
-export const usePlugin = <T,>(id: string): Plugin<T> | undefined => {
-  const { plugins } = usePlugins();
-  return findPlugin<T>(plugins, id);
-};
-
-/**
- * Resolve a plugin by predicate.
- */
-export const useResolvePlugin = <T,>(predicate: (plugin: Plugin) => Plugin<T> | undefined): Plugin<T> | undefined => {
-  const { plugins } = usePlugins();
-  return resolvePlugin(plugins, predicate);
-};
-
-/**
- * Resolve a collection of plugins by predicate.
- */
-export const useResolvePlugins = <T,>(predicate: (plugin: Plugin) => Plugin<T> | undefined): Plugin<T>[] => {
-  const { plugins } = usePlugins();
-  return useMemo(() => plugins.map(predicate).filter(nonNullable), [plugins, predicate]);
-};
-
-export const PluginProvider = PluginContext.Provider;

package/src/plugins/plugin-host/index.ts

@@ -1,12 +0,0 @@
-//
-// Copyright 2023 DXOS.org
-//
-
-import { HostPlugin } from './HostPlugin';
-
-export * from './plugin';
-
-export * from './HostPlugin';
-export * from './PluginContext';
-
-export default HostPlugin;