@dxos/plugin-help 0.7.4 → 0.7.5-labs.5f04cf6

package/src/HelpPlugin.tsx

@@ -2,129 +2,53 @@
 // Copyright 2023 DXOS.org
 //
 
-import React from 'react';
+import { createResolver, defineModule, definePlugin, Events, contributes, Capabilities } from '@dxos/app-framework';
 
-import { resolvePlugin, type PluginDefinition, parseIntentPlugin, LayoutAction } from '@dxos/app-framework';
-import { createExtension, type Node } from '@dxos/app-graph';
-import { create } from '@dxos/live-object';
-import { LocalStorageStore } from '@dxos/local-storage';
-
-import { HelpContextProvider, ShortcutsDialogContent, ShortcutsHints, ShortcutsList } from './components';
-import meta, { HelpAction, HELP_PLUGIN } from './meta';
+import { AppGraphBuilder, HelpState, ReactContext, ReactSurface } from './capabilities';
+import { HelpCapabilities } from './capabilities/capabilities';
+import { meta } from './meta';
 import translations from './translations';
-import { type Step, type HelpPluginProvides } from './types';
-
-export type HelpSettingsProps = { showHints?: boolean; showWelcome?: boolean };
+import { type Step, HelpAction } from './types';
 
 export type HelpPluginOptions = { steps?: Step[] };
 
-export const HelpPlugin = ({ steps = [] }: HelpPluginOptions): PluginDefinition<HelpPluginProvides> => {
-  const settings = new LocalStorageStore<HelpSettingsProps>(HELP_PLUGIN, { showHints: true, showWelcome: true });
-  const state = create<{ running: boolean }>({ running: false });
-  return {
-    meta,
-    ready: async () => {
-      settings
-        .prop({ key: 'showHints', type: LocalStorageStore.bool({ allowUndefined: true }) })
-        .prop({ key: 'showWelcome', type: LocalStorageStore.bool({ allowUndefined: true }) });
-    },
-    provides: {
-      context: ({ children }) => {
-        return (
-          <HelpContextProvider
-            steps={steps}
-            running={state.running}
-            onRunningChanged={(newState) => {
-              state.running = newState;
-              if (!newState) {
-                settings.values.showHints = false;
-              }
-            }}
-          >
-            {children}
-          </HelpContextProvider>
-        );
-      },
-      translations,
-      graph: {
-        builder: (plugins) => {
-          const intentPlugin = resolvePlugin(plugins, parseIntentPlugin)!;
-
-          return createExtension({
-            id: HELP_PLUGIN,
-            filter: (node): node is Node<null> => node.id === 'root',
-            actions: () => [
-              {
-                id: HelpAction.START,
-                data: async () => {
-                  settings.values.showHints = true;
-                  await intentPlugin?.provides.intent.dispatch({
-                    plugin: HELP_PLUGIN,
-                    action: HelpAction.START,
-                  });
-                },
-                properties: {
-                  label: ['open help tour', { ns: HELP_PLUGIN }],
-                  icon: 'ph--info--regular',
-                  keyBinding: {
-                    macos: 'shift+meta+/',
-                    // TODO(wittjosiah): Test on windows to see if it behaves the same as linux.
-                    windows: 'shift+ctrl+/',
-                    linux: 'shift+ctrl+?',
-                  },
-                  testId: 'helpPlugin.openHelp',
-                },
-              },
-              {
-                id: 'dxos.org/plugin/help/open-shortcuts',
-                data: async () => {
-                  settings.values.showHints = true;
-                  await intentPlugin?.provides.intent.dispatch({
-                    action: LayoutAction.SET_LAYOUT,
-                    data: {
-                      element: 'dialog',
-                      component: `${HELP_PLUGIN}/Shortcuts`,
-                    },
-                  });
-                },
-                properties: {
-                  label: ['open shortcuts label', { ns: HELP_PLUGIN }],
-                  icon: 'ph--keyboard--regular',
-                  keyBinding: {
-                    macos: 'meta+ctrl+/',
-                  },
-                },
-              },
-            ],
-          });
-        },
-      },
-      surface: {
-        component: ({ data, role }) => {
-          switch (role) {
-            case 'hints':
-              return <ShortcutsHints />;
-            case 'keyshortcuts':
-              return <ShortcutsList />;
-          }
-
-          switch (data.component) {
-            case `${HELP_PLUGIN}/Shortcuts`:
-              return <ShortcutsDialogContent />;
-          }
-
-          return null;
-        },
-      },
-      intent: {
-        resolver: async (intent) => {
-          switch (intent.action) {
-            case HelpAction.START:
-              state.running = true;
-              break;
-          }
-        },
-      },
-    },
-  };
-};
+export const HelpPlugin = ({ steps = [] }: HelpPluginOptions) =>
+  definePlugin(meta, [
+    defineModule({
+      id: `${meta.id}/module/state`,
+      activatesOn: Events.Startup,
+      activate: HelpState,
+    }),
+    defineModule({
+      id: `${meta.id}/module/translations`,
+      activatesOn: Events.SetupTranslations,
+      activate: () => contributes(Capabilities.Translations, translations),
+    }),
+    defineModule({
+      id: `${meta.id}/module/react-context`,
+      activatesOn: Events.Startup,
+      activate: () => ReactContext(steps),
+    }),
+    defineModule({
+      id: `${meta.id}/module/react-surface`,
+      activatesOn: Events.Startup,
+      activate: ReactSurface,
+    }),
+    defineModule({
+      id: `${meta.id}/module/intent-resolver`,
+      activatesOn: Events.SetupIntents,
+      activate: (context) =>
+        contributes(
+          Capabilities.IntentResolver,
+          createResolver(HelpAction.Start, () => {
+            const state = context.requestCapability(HelpCapabilities.MutableState);
+            state.running = true;
+          }),
+        ),
+    }),
+    defineModule({
+      id: `${meta.id}/module/app-graph-builder`,
+      activatesOn: Events.SetupAppGraph,
+      activate: AppGraphBuilder,
+    }),
+  ]);

package/src/capabilities/app-graph-builder.ts

@@ -0,0 +1,58 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { Capabilities, contributes, createIntent, LayoutAction, type PluginsContext } from '@dxos/app-framework';
+import { createExtension, type Node } from '@dxos/app-graph';
+
+import { HelpCapabilities } from './capabilities';
+import { SHORTCUTS_DIALOG } from '../components';
+import { HELP_PLUGIN } from '../meta';
+import { HelpAction } from '../types';
+
+export default (context: PluginsContext) =>
+  contributes(
+    Capabilities.AppGraphBuilder,
+    createExtension({
+      id: HELP_PLUGIN,
+      filter: (node): node is Node<null> => node.id === 'root',
+      actions: () => [
+        {
+          id: HelpAction.Start._tag,
+          data: async () => {
+            const { dispatchPromise: dispatch } = context.requestCapability(Capabilities.IntentDispatcher);
+            const state = context.requestCapability(HelpCapabilities.MutableState);
+            state.showHints = true;
+            await dispatch(createIntent(HelpAction.Start));
+          },
+          properties: {
+            label: ['open help tour', { ns: HELP_PLUGIN }],
+            icon: 'ph--info--regular',
+            keyBinding: {
+              macos: 'shift+meta+/',
+              // TODO(wittjosiah): Test on windows to see if it behaves the same as linux.
+              windows: 'shift+ctrl+/',
+              linux: 'shift+ctrl+?',
+            },
+            testId: 'helpPlugin.openHelp',
+          },
+        },
+        {
+          id: 'dxos.org/plugin/help/open-shortcuts',
+          data: async () => {
+            const { dispatchPromise: dispatch } = context.requestCapability(Capabilities.IntentDispatcher);
+            const state = context.requestCapability(HelpCapabilities.MutableState);
+            state.showHints = true;
+            await dispatch?.(createIntent(LayoutAction.SetLayout, { element: 'dialog', component: SHORTCUTS_DIALOG }));
+          },
+          properties: {
+            label: ['open shortcuts label', { ns: HELP_PLUGIN }],
+            icon: 'ph--keyboard--regular',
+            keyBinding: {
+              macos: 'meta+ctrl+/',
+            },
+          },
+        },
+      ],
+    }),
+  );

package/src/capabilities/capabilities.ts

@@ -0,0 +1,13 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { defineCapability } from '@dxos/app-framework';
+
+import { HELP_PLUGIN } from '../meta';
+
+export namespace HelpCapabilities {
+  export type State = { running: boolean; showHints: boolean; showWelcome: boolean };
+  export const State = defineCapability<Readonly<State>>(`${HELP_PLUGIN}/capability/state`);
+  export const MutableState = defineCapability<State>(`${HELP_PLUGIN}/capability/state`);
+}

package/src/capabilities/index.ts

@@ -0,0 +1,12 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { lazy } from '@dxos/app-framework';
+
+export const AppGraphBuilder = lazy(() => import('./app-graph-builder'));
+export const ReactContext = lazy(() => import('./react-context'));
+export const ReactSurface = lazy(() => import('./react-surface'));
+export const HelpState = lazy(() => import('./state'));
+
+export * from './capabilities';

package/src/capabilities/react-context.tsx

@@ -0,0 +1,34 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React from 'react';
+
+import { Capabilities, contributes, useCapability } from '@dxos/app-framework';
+
+import { HelpCapabilities } from './capabilities';
+import { HelpContextProvider } from '../components';
+import { HELP_PLUGIN } from '../meta';
+import { type Step } from '../types';
+
+export default (steps: Step[]) =>
+  contributes(Capabilities.ReactContext, {
+    id: HELP_PLUGIN,
+    context: ({ children }) => {
+      const state = useCapability(HelpCapabilities.MutableState);
+      return (
+        <HelpContextProvider
+          steps={steps}
+          running={state.running}
+          onRunningChanged={(newState) => {
+            state.running = newState;
+            if (!newState) {
+              state.showHints = false;
+            }
+          }}
+        >
+          {children}
+        </HelpContextProvider>
+      );
+    },
+  });

package/src/capabilities/react-surface.tsx

@@ -0,0 +1,30 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import React from 'react';
+
+import { Capabilities, contributes, createSurface } from '@dxos/app-framework';
+
+import { SHORTCUTS_DIALOG, ShortcutsDialogContent, ShortcutsHints, ShortcutsList } from '../components';
+import { HELP_PLUGIN } from '../meta';
+
+export default () =>
+  contributes(Capabilities.ReactSurface, [
+    createSurface({
+      id: `${HELP_PLUGIN}/hints`,
+      role: 'hints',
+      component: () => <ShortcutsHints />,
+    }),
+    createSurface({
+      id: `${HELP_PLUGIN}/keyshortcuts`,
+      role: 'keyshortcuts',
+      component: () => <ShortcutsList />,
+    }),
+    createSurface({
+      id: SHORTCUTS_DIALOG,
+      role: 'dialog',
+      filter: (data): data is any => data.component === SHORTCUTS_DIALOG,
+      component: () => <ShortcutsDialogContent />,
+    }),
+  ]);

package/src/capabilities/state.ts

@@ -0,0 +1,23 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { contributes } from '@dxos/app-framework';
+import { LocalStorageStore } from '@dxos/local-storage';
+
+import { HelpCapabilities } from './capabilities';
+import { HELP_PLUGIN } from '../meta';
+
+export default () => {
+  const state = new LocalStorageStore<HelpCapabilities.State>(HELP_PLUGIN, {
+    running: false,
+    showHints: true,
+    showWelcome: true,
+  });
+
+  state
+    .prop({ key: 'showHints', type: LocalStorageStore.bool() })
+    .prop({ key: 'showWelcome', type: LocalStorageStore.bool() });
+
+  return contributes(HelpCapabilities.State, state.values);
+};

package/src/components/HelpContextProvider/HelpContextProvider.tsx

@@ -5,7 +5,7 @@
 import React, { type PropsWithChildren, useState, useEffect } from 'react';
 import Joyride, { ACTIONS, EVENTS } from 'react-joyride';
 
-import { usePlugins, resolvePlugin, parseLayoutPlugin } from '@dxos/app-framework';
+import { usePluginManager, useCapability, Capabilities } from '@dxos/app-framework';
 
 import { type Step, HelpContext } from '../../types';
 import { floaterProps, Tooltip } from '../Tooltip';
@@ -69,18 +69,18 @@ export const HelpContextProvider = ({
   running: runningProp,
   onRunningChanged,
 }: HelpContextProviderProps) => {
-  const { plugins } = usePlugins();
-  const layoutPlugin = resolvePlugin(plugins, parseLayoutPlugin);
+  const manager = usePluginManager();
+  const layout = useCapability(Capabilities.Layout);
   const [running, setRunning] = useState(!!runningProp && !!getTarget(initialSteps[0]));
   const [stepIndex, _setStepIndex] = useState(0);
   const [steps, setSteps] = useState(initialSteps);
 
-  const paused = layoutPlugin?.provides.layout.dialogOpen;
+  const paused = layout.dialogOpen;
 
   const setStepIndex = (index: number) => {
     if (runningProp) {
       const step = steps[index];
-      step?.before?.({ plugins, step });
+      step?.before?.(manager.context);
     }
     _setStepIndex(index);
   };

package/src/components/Shortcuts/ShortcutsDialog.tsx

@@ -9,6 +9,8 @@ import { Button, Dialog, Icon, useTranslation } from '@dxos/react-ui';
 import { ShortcutsList } from './ShortcutsList';
 import { HELP_PLUGIN } from '../../meta';
 
+export const SHORTCUTS_DIALOG = `${HELP_PLUGIN}/ShortcutsDialog`;
+
 export const ShortcutsDialogContent = () => {
   const { t } = useTranslation(HELP_PLUGIN);
 

package/src/index.ts

@@ -2,14 +2,9 @@
 // Copyright 2023 DXOS.org
 //
 
-import { HelpPlugin } from './HelpPlugin';
-import { type Step } from './types';
-
-export type { Step };
-
+export { HelpCapabilities } from './capabilities';
 export * from './components';
-export * from './hooks';
-
+export * from './meta';
 export * from './HelpPlugin';
-
-export default HelpPlugin;
+export * from './hooks';
+export * from './types';

package/src/meta.ts

@@ -7,13 +7,8 @@ import { type PluginMeta } from '@dxos/app-framework';
 // TODO(burdon): Rename Guide? Help?
 export const HELP_PLUGIN = 'dxos.org/plugin/help';
 
-export default {
+export const meta = {
   id: HELP_PLUGIN,
   name: 'Help',
   icon: 'ph--info--regular',
 } satisfies PluginMeta;
-
-const HELP_ACTION = `${HELP_PLUGIN}/action`;
-export enum HelpAction {
-  START = `${HELP_ACTION}/start`,
-}

package/src/types.ts

@@ -5,16 +5,13 @@
 import { type Context, createContext } from 'react';
 import { type Step as BaseStep } from 'react-joyride';
 
-import {
-  type Plugin,
-  type GraphBuilderProvides,
-  type IntentResolverProvides,
-  type SurfaceProvides,
-  type TranslationsProvides,
-} from '@dxos/app-framework';
+import { type PluginsContext } from '@dxos/app-framework';
+import { S } from '@dxos/echo-schema';
+
+import { HELP_PLUGIN } from './meta';
 
 export type Step = BaseStep & {
-  before?: (context: { plugins: Plugin[]; step: Step }) => void;
+  before?: (context: PluginsContext) => void;
 };
 
 export type HelpContextType = {
@@ -35,4 +32,10 @@ export const HelpContext: Context<HelpContextType> = createContext<HelpContextTy
   stop: () => {},
 });
 
-export type HelpPluginProvides = GraphBuilderProvides & IntentResolverProvides & SurfaceProvides & TranslationsProvides;
+export const HELP_ACTION = `${HELP_PLUGIN}/action`;
+export namespace HelpAction {
+  export class Start extends S.TaggedClass<Start>()(`${HELP_ACTION}/start`, {
+    input: S.Void,
+    output: S.Void,
+  }) {}
+}

package/dist/lib/browser/chunk-2EMBCGD5.mjs

@@ -1,19 +0,0 @@
-// packages/plugins/plugin-help/src/meta.ts
-var HELP_PLUGIN = "dxos.org/plugin/help";
-var meta_default = {
-  id: HELP_PLUGIN,
-  name: "Help",
-  icon: "ph--info--regular"
-};
-var HELP_ACTION = `${HELP_PLUGIN}/action`;
-var HelpAction;
-(function(HelpAction2) {
-  HelpAction2[HelpAction2["START"] = `${HELP_ACTION}/start`] = "START";
-})(HelpAction || (HelpAction = {}));
-
-export {
-  HELP_PLUGIN,
-  meta_default,
-  HelpAction
-};
-//# sourceMappingURL=chunk-2EMBCGD5.mjs.map

package/dist/lib/browser/chunk-2EMBCGD5.mjs.map

@@ -1,7 +0,0 @@
-{
-  "version": 3,
-  "sources": ["../../../src/meta.ts"],
-  "sourcesContent": ["//\n// Copyright 2023 DXOS.org\n//\n\nimport { type PluginMeta } from '@dxos/app-framework';\n\n// TODO(burdon): Rename Guide? Help?\nexport const HELP_PLUGIN = 'dxos.org/plugin/help';\n\nexport default {\n  id: HELP_PLUGIN,\n  name: 'Help',\n  icon: 'ph--info--regular',\n} satisfies PluginMeta;\n\nconst HELP_ACTION = `${HELP_PLUGIN}/action`;\nexport enum HelpAction {\n  START = `${HELP_ACTION}/start`,\n}\n"],
-  "mappings": ";AAOO,IAAMA,cAAc;AAE3B,IAAA,eAAe;EACbC,IAAID;EACJE,MAAM;EACNC,MAAM;AACR;AAEA,IAAMC,cAAc,GAAGJ,WAAAA;;UACXK,aAAAA;qCACF,GAAGD,WAAAA,QAAmB,IAAA;GADpBC,eAAAA,aAAAA,CAAAA,EAAAA;",
-  "names": ["HELP_PLUGIN", "id", "name", "icon", "HELP_ACTION", "HelpAction"]
-}