@dxos/plugin-help 0.7.4 → 0.7.5-labs.071a3e2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/plugin-help",
-  "version": "0.7.4",
+  "version": "0.7.5-labs.071a3e2",
   "description": "Help plugin.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -12,16 +12,16 @@
       "types": "./dist/types/src/index.d.ts",
       "browser": "./dist/lib/browser/index.mjs"
     },
-    "./meta": {
-      "types": "./dist/types/src/meta.d.ts",
-      "browser": "./dist/lib/browser/meta.mjs"
+    "./types": {
+      "types": "./dist/types/src/types.d.ts",
+      "browser": "./dist/lib/browser/types.mjs"
     }
   },
   "types": "dist/types/src/index.d.ts",
   "typesVersions": {
     "*": {
-      "meta": [
-        "dist/types/src/meta.d.ts"
+      "types": [
+        "dist/types/src/types.d.ts"
       ]
     }
   },
@@ -30,20 +30,20 @@
     "src"
   ],
   "dependencies": {
-    "@fluentui/react-tabster": "^9.19.0",
+    "@fluentui/react-tabster": "9.23.3",
     "lodash.get": "^4.4.2",
     "react-joyride": "^2.7.2",
-    "@dxos/app-framework": "0.7.4",
-    "@dxos/debug": "0.7.4",
-    "@dxos/app-graph": "0.7.4",
-    "@dxos/echo-schema": "0.7.4",
-    "@dxos/keyboard": "0.7.4",
-    "@dxos/live-object": "0.7.4",
-    "@dxos/local-storage": "0.7.4",
-    "@dxos/plugin-graph": "0.7.4",
-    "@dxos/plugin-client": "0.7.4",
-    "@dxos/plugin-space": "0.7.4",
-    "@dxos/react-client": "0.7.4"
+    "@dxos/app-framework": "0.7.5-labs.071a3e2",
+    "@dxos/debug": "0.7.5-labs.071a3e2",
+    "@dxos/app-graph": "0.7.5-labs.071a3e2",
+    "@dxos/keyboard": "0.7.5-labs.071a3e2",
+    "@dxos/echo-schema": "0.7.5-labs.071a3e2",
+    "@dxos/live-object": "0.7.5-labs.071a3e2",
+    "@dxos/local-storage": "0.7.5-labs.071a3e2",
+    "@dxos/plugin-client": "0.7.5-labs.071a3e2",
+    "@dxos/plugin-graph": "0.7.5-labs.071a3e2",
+    "@dxos/plugin-space": "0.7.5-labs.071a3e2",
+    "@dxos/react-client": "0.7.5-labs.071a3e2"
   },
   "devDependencies": {
     "@phosphor-icons/react": "^2.1.5",
@@ -55,17 +55,17 @@
     "react-floater": "0.7.9",
     "type-fest": "4.10.1",
     "vite": "5.4.7",
-    "@dxos/random": "0.7.4",
-    "@dxos/react-ui": "0.7.4",
-    "@dxos/react-ui-theme": "0.7.4",
-    "@dxos/storybook-utils": "0.7.4"
+    "@dxos/random": "0.7.5-labs.071a3e2",
+    "@dxos/react-ui": "0.7.5-labs.071a3e2",
+    "@dxos/react-ui-theme": "0.7.5-labs.071a3e2",
+    "@dxos/storybook-utils": "0.7.5-labs.071a3e2"
   },
   "peerDependencies": {
     "@phosphor-icons/react": "^2.1.5",
     "react": "~18.2.0",
     "react-dom": "~18.2.0",
-    "@dxos/react-ui": "0.7.4",
-    "@dxos/react-ui-theme": "0.7.4"
+    "@dxos/react-ui": "0.7.5-labs.071a3e2",
+    "@dxos/react-ui-theme": "0.7.5-labs.071a3e2"
   },
   "publishConfig": {
     "access": "public"

package/src/HelpPlugin.tsx

@@ -2,129 +2,56 @@
 // 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, ReactRoot, 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:
+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-root`,
+      activatesOn: Events.Startup,
+      activate: () => ReactRoot(steps),
+    }),
+    defineModule({
+      id: `${meta.id}/module/react-surface`,
+      activatesOn: Events.SetupSurfaces,
+      activate: ReactSurface,
+    }),
+    defineModule({
+      id: `${meta.id}/module/intent-resolver`,
+      activatesOn: Events.SetupIntents,
+      activate: (context) =>
+        contributes(
+          Capabilities.IntentResolver,
+          createResolver({
+            intent: HelpAction.Start,
+            resolve: () => {
+              const state = context.requestCapability(HelpCapabilities.MutableState);
               state.running = true;
-              break;
-          }
-        },
-      },
-    },
-  };
-};
+            },
+          }),
+        ),
+    }),
+    defineModule({
+      id: `${meta.id}/module/app-graph-builder`,
+      activatesOn: Events.SetupAppGraph,
+      activate: AppGraphBuilder,
+    }),
+  ]);

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

@@ -0,0 +1,66 @@
+//
+// 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.UpdateDialog, {
+                part: 'dialog',
+                subject: SHORTCUTS_DIALOG,
+                options: {
+                  blockAlign: 'center',
+                },
+              }),
+            );
+          },
+          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 ReactRoot = lazy(() => import('./react-root'));
+export const ReactSurface = lazy(() => import('./react-surface'));
+export const HelpState = lazy(() => import('./state'));
+
+export * from './capabilities';

package/src/capabilities/react-root.tsx

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

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/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/components/{HelpContextProvider/HelpContextProvider.stories.tsx → WelcomeTour/WelcomeTour.stories.tsx}

@@ -12,7 +12,7 @@ import { faker } from '@dxos/random';
 import { Button } from '@dxos/react-ui';
 import { withTheme } from '@dxos/storybook-utils';
 
-import { HelpContextProvider, type HelpContextProviderProps } from './HelpContextProvider';
+import { WelcomeTour, type WelcomeTourProps } from './WelcomeTour';
 import { useHelp } from '../../hooks';
 
 const App = () => {
@@ -57,18 +57,19 @@ const App = () => {
   );
 };
 
-const DefaultStory = ({ steps = [] }: HelpContextProviderProps) => (
-  <HelpContextProvider steps={steps}>
+const DefaultStory = ({ steps = [] }: WelcomeTourProps) => (
+  <>
+    <WelcomeTour steps={steps} />
     <div className='fixed inset-0 overflow-hidden'>
       <App />
     </div>
-  </HelpContextProvider>
+  </>
 );
 
 // TODO(burdon): Tour should prompt user to create a Stack -- and respond to it being created.
 //  Use beacon to simulate click.
 
-export const Default: StoryObj<typeof HelpContextProvider> = {
+export const Default: StoryObj<typeof WelcomeTour> = {
   args: {
     // https://docs.react-joyride.com/step#options
     steps: [
@@ -103,9 +104,9 @@ export const Default: StoryObj<typeof HelpContextProvider> = {
 /**
  * IMPORTANT: Run in separate tab.
  */
-const meta: Meta<typeof HelpContextProvider> = {
-  title: 'plugins/plugin-help/Joyride',
-  component: HelpContextProvider,
+const meta: Meta<typeof WelcomeTour> = {
+  title: 'plugins/plugin-help/WelcomeTour',
+  component: WelcomeTour,
   render: DefaultStory,
   decorators: [withTheme],
 };

package/src/components/{HelpContextProvider/HelpContextProvider.tsx → WelcomeTour/WelcomeTour.tsx}

@@ -2,10 +2,10 @@
 // Copyright 2023 DXOS.org
 //
 
-import React, { type PropsWithChildren, useState, useEffect } from 'react';
+import React, { useState, useEffect } from 'react';
 import Joyride, { ACTIONS, EVENTS } from 'react-joyride';
 
-import { usePlugins, resolvePlugin, parseLayoutPlugin } from '@dxos/app-framework';
+import { usePluginManager, useLayout } from '@dxos/app-framework';
 
 import { type Step, HelpContext } from '../../types';
 import { floaterProps, Tooltip } from '../Tooltip';
@@ -57,30 +57,25 @@ const waitForTarget = async (step: Step) => {
   }
 };
 
-export type HelpContextProviderProps = PropsWithChildren<{
+export type WelcomeTourProps = {
   steps: Step[];
   running?: boolean;
   onRunningChanged?: (state: boolean) => any;
-}>;
-
-export const HelpContextProvider = ({
-  children,
-  steps: initialSteps,
-  running: runningProp,
-  onRunningChanged,
-}: HelpContextProviderProps) => {
-  const { plugins } = usePlugins();
-  const layoutPlugin = resolvePlugin(plugins, parseLayoutPlugin);
+};
+
+export const WelcomeTour = ({ steps: initialSteps, running: runningProp, onRunningChanged }: WelcomeTourProps) => {
+  const manager = usePluginManager();
+  const layout = useLayout();
   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);
   };
@@ -170,7 +165,6 @@ export const HelpContextProvider = ({
         floaterProps={floaterProps}
         tooltipComponent={Tooltip}
       />
-      {children}
     </HelpContext.Provider>
   );
 };

package/src/components/WelcomeTour/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+export * from './WelcomeTour';

package/src/components/index.ts

@@ -2,6 +2,6 @@
 // Copyright 2023 DXOS.org
 //
 
-export * from './HelpContextProvider';
 export * from './Shortcuts';
 export * from './Tooltip';
+export * from './WelcomeTour';

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,
+  }) {}
+}