@dxos/plugin-help 0.8.4-main.a4bbb77 → 0.8.4-main.abd8ff62ef

package/package.json

@@ -1,13 +1,28 @@
 {
   "name": "@dxos/plugin-help",
-  "version": "0.8.4-main.a4bbb77",
+  "version": "0.8.4-main.abd8ff62ef",
   "description": "Help plugin.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dxos/dxos"
+  },
   "license": "MIT",
   "author": "DXOS.org",
   "sideEffects": true,
   "type": "module",
+  "imports": {
+    "#plugin": "./src/HelpPlugin.tsx",
+    "#capabilities": "./src/capabilities/index.ts",
+    "#components": "./src/components/index.ts",
+    "#containers": "./src/containers/index.ts",
+    "#hooks": "./src/hooks/index.ts",
+    "#meta": "./src/meta.ts",
+    "#operations": "./src/operations/index.ts",
+    "#translations": "./src/translations.ts",
+    "#types": "./src/types/index.ts"
+  },
   "exports": {
     ".": {
       "source": "./src/index.ts",
@@ -19,6 +34,17 @@
       "types": "./dist/types/src/meta.d.ts",
       "browser": "./dist/lib/browser/meta.mjs"
     },
+    "./operations": {
+      "source": "./src/operations/index.ts",
+      "types": "./dist/types/src/operations/index.d.ts",
+      "browser": "./dist/lib/browser/operations/index.mjs"
+    },
+    "./translations": {
+      "source": "./src/translations.ts",
+      "types": "./dist/types/src/translations.d.ts",
+      "browser": "./dist/lib/browser/translations.mjs",
+      "node": "./dist/lib/node-esm/translations.mjs"
+    },
     "./types": {
       "source": "./src/types/index.ts",
       "types": "./dist/types/src/types/index.d.ts",
@@ -26,62 +52,53 @@
     }
   },
   "types": "dist/types/src/index.d.ts",
-  "typesVersions": {
-    "*": {
-      "meta": [
-        "dist/types/src/meta.d.ts"
-      ],
-      "types": [
-        "dist/types/src/types/index.d.ts"
-      ]
-    }
-  },
   "files": [
     "dist",
     "src"
   ],
   "dependencies": {
-    "@fluentui/react-tabster": "^9.24.2",
-    "@preact-signals/safe-react": "^0.9.0",
+    "@effect-atom/atom": "^0.5.1",
+    "@fluentui/react-tabster": "9.26.11",
     "react-joyride": "^2.7.2",
-    "@dxos/app-framework": "0.8.4-main.a4bbb77",
-    "@dxos/debug": "0.8.4-main.a4bbb77",
-    "@dxos/echo-schema": "0.8.4-main.a4bbb77",
-    "@dxos/app-graph": "0.8.4-main.a4bbb77",
-    "@dxos/keyboard": "0.8.4-main.a4bbb77",
-    "@dxos/live-object": "0.8.4-main.a4bbb77",
-    "@dxos/echo": "0.8.4-main.a4bbb77",
-    "@dxos/plugin-client": "0.8.4-main.a4bbb77",
-    "@dxos/local-storage": "0.8.4-main.a4bbb77",
-    "@dxos/plugin-graph": "0.8.4-main.a4bbb77",
-    "@dxos/react-client": "0.8.4-main.a4bbb77",
-    "@dxos/plugin-space": "0.8.4-main.a4bbb77"
+    "@dxos/app-framework": "0.8.4-main.abd8ff62ef",
+    "@dxos/app-toolkit": "0.8.4-main.abd8ff62ef",
+    "@dxos/app-graph": "0.8.4-main.abd8ff62ef",
+    "@dxos/compute": "0.8.4-main.abd8ff62ef",
+    "@dxos/echo": "0.8.4-main.abd8ff62ef",
+    "@dxos/debug": "0.8.4-main.abd8ff62ef",
+    "@dxos/effect": "0.8.4-main.abd8ff62ef",
+    "@dxos/keyboard": "0.8.4-main.abd8ff62ef",
+    "@dxos/plugin-client": "0.8.4-main.abd8ff62ef",
+    "@dxos/util": "0.8.4-main.abd8ff62ef",
+    "@dxos/plugin-space": "0.8.4-main.abd8ff62ef",
+    "@dxos/plugin-graph": "0.8.4-main.abd8ff62ef",
+    "@dxos/react-client": "0.8.4-main.abd8ff62ef"
   },
   "devDependencies": {
-    "@effect-rx/rx-react": "0.42.4",
-    "@effect/platform": "0.92.1",
-    "@types/react": "~19.2.0",
-    "@types/react-dom": "~19.2.0",
-    "effect": "3.18.3",
-    "react": "~19.2.0",
-    "react-dom": "~19.2.0",
+    "@effect-atom/atom-react": "^0.5.0",
+    "@effect/platform": "0.94.4",
+    "@types/react": "~19.2.7",
+    "@types/react-dom": "~19.2.3",
+    "effect": "3.20.0",
+    "react": "~19.2.3",
+    "react-dom": "~19.2.3",
     "react-floater": "0.7.9",
     "type-fest": "4.10.1",
-    "vite": "7.1.9",
-    "@dxos/plugin-storybook-layout": "0.8.4-main.a4bbb77",
-    "@dxos/random": "0.8.4-main.a4bbb77",
-    "@dxos/react-ui": "0.8.4-main.a4bbb77",
-    "@dxos/react-ui-theme": "0.8.4-main.a4bbb77",
-    "@dxos/storybook-utils": "0.8.4-main.a4bbb77"
+    "vite": "^8.0.10",
+    "@dxos/plugin-testing": "0.8.4-main.abd8ff62ef",
+    "@dxos/random": "0.8.4-main.abd8ff62ef",
+    "@dxos/react-ui": "0.8.4-main.abd8ff62ef",
+    "@dxos/storybook-utils": "0.8.4-main.abd8ff62ef",
+    "@dxos/ui-theme": "0.8.4-main.abd8ff62ef"
   },
   "peerDependencies": {
-    "@effect-rx/rx-react": "^0.34.1",
-    "@effect/platform": "^0.80.12",
-    "effect": "^3.13.3",
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0",
-    "@dxos/react-ui": "0.8.4-main.a4bbb77",
-    "@dxos/react-ui-theme": "0.8.4-main.a4bbb77"
+    "@effect-atom/atom-react": "^0.5.0",
+    "@effect/platform": "0.94.4",
+    "effect": "3.20.0",
+    "react": "~19.2.3",
+    "react-dom": "~19.2.3",
+    "@dxos/react-ui": "0.8.4-main.abd8ff62ef",
+    "@dxos/ui-theme": "0.8.4-main.abd8ff62ef"
   },
   "publishConfig": {
     "access": "public"

package/src/HelpPlugin.test.ts

@@ -0,0 +1,30 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { ActivationEvents } from '@dxos/app-framework';
+import { createComposerTestApp } from '@dxos/plugin-testing/harness';
+
+import { HelpPlugin } from '#plugin';
+
+import { meta } from './meta';
+
+const moduleId = (name: string) => `${meta.id}.module.${name}`;
+
+describe('HelpPlugin', () => {
+  test('modules activate on the expected events', async ({ expect }) => {
+    await using harness = await createComposerTestApp({
+      plugins: [HelpPlugin({})],
+    });
+
+    expect(harness.manager.getActive()).toEqual(
+      expect.arrayContaining([moduleId('AppGraphBuilder'), moduleId('ReactSurface')]),
+    );
+
+    // Operation handlers are not loaded on startup — SetupOperationHandler fires lazily when an operation is invoked.
+    await harness.fire(ActivationEvents.SetupOperationHandler);
+    expect(harness.manager.getActive()).toContain(moduleId('OperationHandler'));
+  });
+});

package/src/HelpPlugin.tsx

@@ -2,54 +2,31 @@
 // Copyright 2023 DXOS.org
 //
 
-import { Capabilities, Events, contributes, createResolver, defineModule, definePlugin } from '@dxos/app-framework';
+import { ActivationEvents, Plugin } from '@dxos/app-framework';
+import { AppPlugin } from '@dxos/app-toolkit';
 
-import { AppGraphBuilder, HelpCapabilities, HelpState, ReactRoot, ReactSurface } from './capabilities';
-import { meta } from './meta';
-import { translations } from './translations';
-import { HelpAction, type Step } from './types';
+import { AppGraphBuilder, HelpState, OperationHandler, ReactRoot, ReactSurface } from '#capabilities';
+import { meta } from '#meta';
+import { translations } from '#translations';
+import { type Step } from '#types';
 
 export type HelpPluginOptions = { steps?: Step[] };
 
-export const HelpPlugin = definePlugin<HelpPluginOptions>(meta, ({ steps = [] }) => [
-  defineModule({
-    id: `${meta.id}/module/state`,
-    activatesOn: Events.Startup,
+export const HelpPlugin = Plugin.define<HelpPluginOptions>(meta).pipe(
+  AppPlugin.addAppGraphModule({ activate: AppGraphBuilder }),
+  AppPlugin.addOperationHandlerModule({ activate: OperationHandler }),
+  AppPlugin.addSurfaceModule({ activate: ReactSurface }),
+  AppPlugin.addTranslationsModule({ translations }),
+  Plugin.addModule({
+    activatesOn: ActivationEvents.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,
+  Plugin.addModule(({ steps = [] }) => ({
+    id: 'react-root',
+    activatesOn: ActivationEvents.Startup,
     activate: () => ReactRoot(steps),
-  }),
-  defineModule({
-    id: `${meta.id}/module/react-surface`,
-    activatesOn: Events.SetupReactSurface,
-    activate: ReactSurface,
-  }),
-  defineModule({
-    id: `${meta.id}/module/intent-resolver`,
-    activatesOn: Events.SetupIntentResolver,
-    activate: (context) =>
-      contributes(
-        Capabilities.IntentResolver,
-        createResolver({
-          intent: HelpAction.Start,
-          resolve: () => {
-            const state = context.getCapability(HelpCapabilities.MutableState);
-            state.running = true;
-          },
-        }),
-      ),
-  }),
-  defineModule({
-    id: `${meta.id}/module/app-graph-builder`,
-    activatesOn: Events.SetupAppGraph,
-    activate: AppGraphBuilder,
-  }),
-]);
+  })),
+  Plugin.make,
+);
+
+export default HelpPlugin;

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

@@ -2,76 +2,62 @@
 // Copyright 2025 DXOS.org
 //
 
-import { Rx } from '@effect-rx/rx-react';
-import { Option, pipe } from 'effect';
+import * as Effect from 'effect/Effect';
 
-import { Capabilities, LayoutAction, type PluginContext, contributes, createIntent } from '@dxos/app-framework';
-import { createExtension } from '@dxos/app-graph';
+import { Capabilities, Capability } from '@dxos/app-framework';
+import { GraphBuilder, Node, NodeMatcher } from '@dxos/app-graph';
+import { AppCapabilities, LayoutOperation } from '@dxos/app-toolkit';
+import { Operation } from '@dxos/compute';
 
-import { SHORTCUTS_DIALOG } from '../components';
-import { meta } from '../meta';
-import { HelpAction } from '../types';
+import { meta } from '#meta';
+import { HelpOperation } from '#operations';
+import { HelpCapabilities } from '#types';
 
-import { HelpCapabilities } from './capabilities';
+import { SHORTCUTS_DIALOG } from '../constants';
 
-export default (context: PluginContext) =>
-  contributes(
-    Capabilities.AppGraphBuilder,
-    createExtension({
-      id: meta.id,
-      actions: (node) =>
-        Rx.make((get) =>
-          pipe(
-            get(node),
-            Option.flatMap((node) => (node.id === 'root' ? Option.some(node) : Option.none())),
-            Option.map(() => [
-              {
-                id: HelpAction.Start._tag,
-                data: async () => {
-                  const { dispatchPromise: dispatch } = context.getCapability(Capabilities.IntentDispatcher);
-                  const state = context.getCapability(HelpCapabilities.MutableState);
-                  state.showHints = true;
-                  await dispatch(createIntent(HelpAction.Start));
-                },
-                properties: {
-                  label: ['open help tour', { ns: meta.id }],
-                  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',
-                },
+export default Capability.makeModule(
+  Effect.fnUntraced(function* () {
+    const extensions = yield* GraphBuilder.createExtension({
+      id: 'root',
+      match: NodeMatcher.whenRoot,
+      actions: () =>
+        Effect.succeed([
+          Node.makeAction({
+            id: HelpOperation.Start.meta.key,
+            data: Effect.fnUntraced(function* () {
+              yield* Capabilities.updateAtomValue(HelpCapabilities.State, (s) => ({ ...s, showHints: true }));
+              yield* Operation.invoke(HelpOperation.Start);
+            }),
+            properties: {
+              label: ['open-help-tour.message', { ns: meta.id }],
+              icon: 'ph--info--regular',
+              keyBinding: {
+                macos: 'shift+meta+/',
+                windows: 'shift+ctrl+/',
+                linux: 'shift+ctrl+?',
               },
-              {
-                id: `${meta.id}/open-shortcuts`,
-                data: async () => {
-                  const { dispatchPromise: dispatch } = context.getCapability(Capabilities.IntentDispatcher);
-                  const state = context.getCapability(HelpCapabilities.MutableState);
-                  state.showHints = true;
-                  await dispatch(
-                    createIntent(LayoutAction.UpdateDialog, {
-                      part: 'dialog',
-                      subject: SHORTCUTS_DIALOG,
-                      options: {
-                        blockAlign: 'center',
-                      },
-                    }),
-                  );
-                },
-                properties: {
-                  label: ['open shortcuts label', { ns: meta.id }],
-                  icon: 'ph--keyboard--regular',
-                  keyBinding: {
-                    macos: 'meta+ctrl+/',
-                  },
-                },
+              testId: 'helpPlugin.openHelp',
+            },
+          }),
+          Node.makeAction({
+            id: 'open-shortcuts',
+            data: Effect.fnUntraced(function* () {
+              yield* Capabilities.updateAtomValue(HelpCapabilities.State, (s) => ({ ...s, showHints: true }));
+              yield* Operation.invoke(LayoutOperation.UpdateDialog, {
+                subject: SHORTCUTS_DIALOG,
+              });
+            }),
+            properties: {
+              label: ['open-shortcuts.label', { ns: meta.id }],
+              icon: 'ph--keyboard--regular',
+              keyBinding: {
+                macos: 'meta+ctrl+/',
               },
-            ]),
-            Option.getOrElse(() => []),
-          ),
-        ),
-    }),
-  );
+            },
+          }),
+        ]),
+    });
+
+    return Capability.contributes(AppCapabilities.AppGraphBuilder, extensions);
+  }),
+);

package/src/capabilities/index.ts

@@ -2,11 +2,14 @@
 // Copyright 2025 DXOS.org
 //
 
-import { lazy } from '@dxos/app-framework';
+import { Capability } from '@dxos/app-framework';
+import { OperationHandlerSet } from '@dxos/compute';
 
-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';
+export const AppGraphBuilder = Capability.lazy('AppGraphBuilder', () => import('./app-graph-builder'));
+export const OperationHandler = Capability.lazy<OperationHandlerSet.OperationHandlerSet>(
+  'OperationHandler',
+  () => import('./operation-handler'),
+);
+export const ReactRoot = Capability.lazy('ReactRoot', () => import('./react-root'));
+export const ReactSurface = Capability.lazy('ReactSurface', () => import('./react-surface'));
+export const HelpState = Capability.lazy('HelpState', () => import('./state'));

package/src/capabilities/operation-handler.ts

@@ -0,0 +1,16 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capabilities, Capability } from '@dxos/app-framework';
+import type { OperationHandlerSet } from '@dxos/compute';
+
+import { HelpOperationHandlerSet } from '#operations';
+
+export default Capability.makeModule<OperationHandlerSet.OperationHandlerSet>(
+  Effect.fnUntraced(function* () {
+    return Capability.contributes(Capabilities.OperationHandler, HelpOperationHandlerSet);
+  }),
+);

package/src/capabilities/react-root.tsx

@@ -2,32 +2,35 @@
 // Copyright 2025 DXOS.org
 //
 
+import * as Effect from 'effect/Effect';
 import React from 'react';
 
-import { Capabilities, contributes, useCapability } from '@dxos/app-framework';
+import { Capabilities, Capability } from '@dxos/app-framework';
+import { useAtomCapabilityState } from '@dxos/app-framework/ui';
 
-import { WelcomeTour } from '../components';
-import { meta } from '../meta';
-import { type Step } from '../types';
+import { WelcomeTour } from '#components';
+import { meta } from '#meta';
+import { HelpCapabilities, type Step } from '#types';
 
-import { HelpCapabilities } from './capabilities';
-
-export default (steps: Step[]) =>
-  contributes(Capabilities.ReactRoot, {
-    id: meta.id,
-    root: () => {
-      const state = useCapability(HelpCapabilities.MutableState);
-      return (
-        <WelcomeTour
-          steps={steps}
-          running={state.running}
-          onRunningChanged={(newState) => {
-            state.running = newState;
-            if (!newState) {
-              state.showHints = false;
-            }
-          }}
-        />
-      );
-    },
-  });
+export default Capability.makeModule(
+  Effect.fnUntraced(function* (steps?: Step[]) {
+    return Capability.contributes(Capabilities.ReactRoot, {
+      id: meta.id,
+      root: () => {
+        const [state, updateState] = useAtomCapabilityState(HelpCapabilities.State);
+        return (
+          <WelcomeTour
+            steps={steps ?? []}
+            running={state.running}
+            onRunningChanged={(newState) => {
+              updateState((s) => ({ ...s, running: newState }));
+              if (!newState) {
+                updateState((s) => ({ ...s, showHints: false }));
+              }
+            }}
+          />
+        );
+      },
+    });
+  }),
+);

package/src/capabilities/react-surface.tsx

@@ -2,29 +2,35 @@
 // Copyright 2025 DXOS.org
 //
 
+import * as Effect from 'effect/Effect';
 import React from 'react';
 
-import { Capabilities, contributes, createSurface } from '@dxos/app-framework';
+import { Capabilities, Capability } from '@dxos/app-framework';
+import { Surface } from '@dxos/app-framework/ui';
+import { AppSurface } from '@dxos/app-toolkit/ui';
 
-import { SHORTCUTS_DIALOG, ShortcutsDialogContent, ShortcutsHints, ShortcutsList } from '../components';
-import { meta } from '../meta';
+import { ShortcutsDialogContent, ShortcutsHints, ShortcutsList } from '#containers';
 
-export default () =>
-  contributes(Capabilities.ReactSurface, [
-    createSurface({
-      id: `${meta.id}/hints`,
-      role: 'hints',
-      component: () => <ShortcutsHints />,
-    }),
-    createSurface({
-      id: `${meta.id}/keyshortcuts`,
-      role: 'keyshortcuts',
-      component: () => <ShortcutsList />,
-    }),
-    createSurface({
-      id: SHORTCUTS_DIALOG,
-      role: 'dialog',
-      filter: (data): data is any => data.component === SHORTCUTS_DIALOG,
-      component: () => <ShortcutsDialogContent />,
-    }),
-  ]);
+import { SHORTCUTS_DIALOG } from '../constants';
+
+export default Capability.makeModule(() =>
+  Effect.succeed(
+    Capability.contributes(Capabilities.ReactSurface, [
+      Surface.create({
+        id: 'hints',
+        role: 'hints',
+        component: () => <ShortcutsHints />,
+      }),
+      Surface.create({
+        id: 'keyshortcuts',
+        role: 'keyshortcuts',
+        component: () => <ShortcutsList />,
+      }),
+      Surface.create({
+        id: SHORTCUTS_DIALOG,
+        filter: AppSurface.component(AppSurface.Dialog, SHORTCUTS_DIALOG),
+        component: () => <ShortcutsDialogContent />,
+      }),
+    ]),
+  ),
+);

package/src/capabilities/state.ts

@@ -2,23 +2,26 @@
 // Copyright 2025 DXOS.org
 //
 
-import { contributes } from '@dxos/app-framework';
-import { LocalStorageStore } from '@dxos/local-storage';
+import * as Effect from 'effect/Effect';
 
-import { meta } from '../meta';
+import { Capability } from '@dxos/app-framework';
+import { createKvsStore } from '@dxos/effect';
 
-import { HelpCapabilities } from './capabilities';
+import { meta } from '#meta';
+import { HelpCapabilities } from '#types';
 
-export default () => {
-  const state = new LocalStorageStore<HelpCapabilities.State>(meta.id, {
-    running: false,
-    showHints: true,
-    showWelcome: true,
-  });
+export default Capability.makeModule(() =>
+  Effect.sync(() => {
+    const stateAtom = createKvsStore({
+      key: meta.id,
+      schema: HelpCapabilities.StateSchema,
+      defaultValue: () => ({
+        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);
-};
+    return Capability.contributes(HelpCapabilities.State, stateAtom);
+  }),
+);

package/src/components/Shortcuts/ShortcutsHints.tsx

@@ -5,12 +5,13 @@
 import React from 'react';
 
 import { type KeyBinding, Keyboard } from '@dxos/keyboard';
-import { Button, Icon, toLocalizedString, useTranslation } from '@dxos/react-ui';
+import { IconButton, toLocalizedString, useTranslation } from '@dxos/react-ui';
+import { osTranslations } from '@dxos/ui-theme';
 
 import { Key } from './Key';
 
 const Shortcut = ({ binding }: { binding: KeyBinding }) => {
-  const { t } = useTranslation('os');
+  const { t } = useTranslation(osTranslations);
   return (
     <div role='none' className='flex items-center gap-2 whitespace-nowrap'>
       <Key binding={binding.shortcut} />
@@ -31,9 +32,16 @@ export const ShortcutsHints = ({ onClose }: { onClose?: () => void }) => {
         <Shortcut key={binding.shortcut} binding={binding} />
       ))}
       {onClose && (
-        <Button variant='ghost' classNames='p-0 cursor-pointer' onClick={onClose}>
-          <Icon icon='ph--x--regular' size={4} />
-        </Button>
+        <IconButton
+          icon='ph--x--regular'
+          size={4}
+          label='Close'
+          iconOnly
+          noTooltip
+          variant='ghost'
+          classNames='p-0 cursor-pointer'
+          onClick={onClose}
+        />
       )}
     </div>
   );