@dxos/plugin-help 0.7.5-main.9cb18ac → 0.7.5-main.9d2a38b

package/src/HelpPlugin.tsx

@@ -2,136 +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,
-  createSurface,
-  createResolver,
-  createIntent,
-} 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,
-  SHORTCUTS_DIALOG,
-  ShortcutsDialogContent,
-  ShortcutsHints,
-  ShortcutsList,
-} from './components';
-import meta, { 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, HelpAction } 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 dispatch = resolvePlugin(plugins, parseIntentPlugin)?.provides.intent.dispatchPromise;
-
-          return createExtension({
-            id: HELP_PLUGIN,
-            filter: (node): node is Node<null> => node.id === 'root',
-            actions: () => [
-              {
-                id: HelpAction.Start._tag,
-                data: async () => {
-                  settings.values.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 () => {
-                  settings.values.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+/',
-                  },
-                },
-              },
-            ],
-          });
-        },
-      },
-      surface: {
-        definitions: () => [
-          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 />,
-          }),
-        ],
-      },
-      intent: {
-        resolvers: () =>
+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/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,7 +7,7 @@ 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',

package/src/types.ts

@@ -5,19 +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 = {
@@ -38,8 +32,6 @@ 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`, {

package/dist/lib/browser/chunk-RHSC3EWO.mjs.map

@@ -1,7 +0,0 @@
-{
-  "version": 3,
-  "sources": ["../../../src/types.ts"],
-  "sourcesContent": ["//\n// Copyright 2023 DXOS.org\n//\n\nimport { type Context, createContext } from 'react';\nimport { type Step as BaseStep } from 'react-joyride';\n\nimport {\n  type Plugin,\n  type GraphBuilderProvides,\n  type IntentResolverProvides,\n  type SurfaceProvides,\n  type TranslationsProvides,\n} from '@dxos/app-framework';\nimport { S } from '@dxos/echo-schema';\n\nimport { HELP_PLUGIN } from './meta';\n\nexport type Step = BaseStep & {\n  before?: (context: { plugins: Plugin[]; step: Step }) => void;\n};\n\nexport type HelpContextType = {\n  running: boolean;\n  steps: Step[];\n  setSteps: (steps: Step[]) => void;\n  setIndex: (index: number) => void;\n  start: () => void;\n  stop: () => void;\n};\n\nexport const HelpContext: Context<HelpContextType> = createContext<HelpContextType>({\n  running: false,\n  steps: [],\n  setSteps: () => {},\n  setIndex: () => {},\n  start: () => {},\n  stop: () => {},\n});\n\nexport type HelpPluginProvides = GraphBuilderProvides & IntentResolverProvides & SurfaceProvides & TranslationsProvides;\n\nexport const HELP_ACTION = `${HELP_PLUGIN}/action`;\nexport namespace HelpAction {\n  export class Start extends S.TaggedClass<Start>()(`${HELP_ACTION}/start`, {\n    input: S.Void,\n    output: S.Void,\n  }) {}\n}\n"],
-  "mappings": ";;;;;AAIA,SAAuBA,qBAAqB;AAU5C,SAASC,SAAS;AAiBX,IAAMC,cAAwCC,cAA+B;EAClFC,SAAS;EACTC,OAAO,CAAA;EACPC,UAAU,MAAA;EAAO;EACjBC,UAAU,MAAA;EAAO;EACjBC,OAAO,MAAA;EAAO;EACdC,MAAM,MAAA;EAAO;AACf,CAAA;AAIO,IAAMC,cAAc,GAAGC,WAAAA;;UACbC,aAAAA;EACR,MAAMC,cAAcC,EAAEC,YAAW,EAAU,GAAGL,WAAAA,UAAqB;IACxEM,OAAOF,EAAEG;IACTC,QAAQJ,EAAEG;EACZ,CAAA,EAAA;EAAI;cAHSJ,QAAAA;AAIf,GALiBD,eAAAA,aAAAA,CAAAA,EAAAA;",
-  "names": ["createContext", "S", "HelpContext", "createContext", "running", "steps", "setSteps", "setIndex", "start", "stop", "HELP_ACTION", "HELP_PLUGIN", "HelpAction", "Start", "S", "TaggedClass", "input", "Void", "output"]
-}

package/dist/lib/browser/chunk-STC3ORFI.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"],
-  "mappings": ";AAOO,IAAMA,cAAc;AAE3B,IAAA,eAAe;EACbC,IAAID;EACJE,MAAM;EACNC,MAAM;AACR;",
-  "names": ["HELP_PLUGIN", "id", "name", "icon"]
-}