@dxos/plugin-help 0.8.4-main.84f28bd → 0.8.4-main.9735255

package/src/components/Tooltip/Tooltip.tsx

@@ -3,18 +3,16 @@
 //
 
 import { useArrowNavigationGroup, useFocusableGroup } from '@fluentui/react-tabster';
-import { CaretLeft, CaretRight, Circle, X } from '@phosphor-icons/react';
 import React, { forwardRef } from 'react';
 // TODO(thure): This needed to be imported in the package.json specifically to pacify TS2742. See if this is resolved with typescript@5.5.x.
 // eslint-disable-next-line unused-imports/no-unused-imports
 import _floater from 'react-floater';
-import { type TooltipRenderProps, type Props } from 'react-joyride';
+import { type Props, type TooltipRenderProps } from 'react-joyride';
 // TODO(thure): This needed to be imported in the package.json specifically to pacify TS2742. See if this is resolved with typescript@5.5.x.
 // eslint-disable-next-line unused-imports/no-unused-imports
 import _typefest from 'type-fest';
 
-import { Button } from '@dxos/react-ui';
-import { getSize, mx } from '@dxos/react-ui-theme';
+import { Button, Icon, IconButton } from '@dxos/react-ui';
 
 // https://docs.react-joyride.com/styling
 // https://github.com/gilbarbara/react-floater
@@ -49,36 +47,38 @@ export const Tooltip = forwardRef<HTMLDivElement, TooltipRenderProps>(
       >
         <div className='flex p-2'>
           <h2 className='grow pli-2 plb-1 text-lg font-medium text-accentSurfaceText'>{title}</h2>
-          <Button
+          <IconButton
             density='fine'
-            variant='primary'
+            icon='ph--x--bold'
+            iconOnly
+            label={closeProps['aria-label']}
             onClick={closeProps.onClick}
-            title={closeProps['aria-label']}
+            size={4}
+            variant='primary'
             data-testid='helpPlugin.tooltip.close'
-          >
-            <X weight='bold' className={getSize(4)} />
-          </Button>
+          />
         </div>
         <div className='flex grow pli-4 mlb-2'>{content}</div>
         <div className='flex p-2 items-center justify-between' {...arrowNavigationAttrs}>
           {
-            <Button
-              variant='primary'
-              onClick={backProps.onClick}
-              title={backProps['aria-label']}
+            <IconButton
               classNames={[!(index > 0 && backProps) && 'invisible']}
+              icon='ph--caret-left--regular'
+              iconOnly
+              label={backProps['aria-label']}
+              onClick={backProps.onClick}
+              variant='primary'
               data-testid='helpPlugin.tooltip.back'
-            >
-              <CaretLeft className={getSize(5)} />
-            </Button>
+            />
           }
           <div className='flex grow gap-2 justify-center'>
             <div className='flex'>
               {Array.from({ length: size }).map((_, i) => (
-                <Circle
+                <Icon
                   key={i}
-                  weight={index === i ? 'fill' : 'regular'}
-                  className={mx(getSize(2), 'mli-1 cursor-pointer')}
+                  icon={index === i ? 'ph--circle--fill' : 'ph--circle--regular'}
+                  size={2}
+                  classNames='mli-1 cursor-pointer'
                 />
               ))}
             </div>
@@ -94,15 +94,16 @@ export const Tooltip = forwardRef<HTMLDivElement, TooltipRenderProps>(
               Done
             </Button>
           ) : (
-            <Button
-              variant='primary'
-              onClick={primaryProps.onClick}
-              title={primaryProps['aria-label']}
+            <IconButton
               autoFocus
+              icon='ph--caret-right--regular'
+              iconOnly
+              label={primaryProps['aria-label']}
+              onClick={primaryProps.onClick}
+              size={6}
+              variant='primary'
               data-testid='helpPlugin.tooltip.next'
-            >
-              <CaretRight className={getSize(6)} />
-            </Button>
+            />
           )}
         </div>
       </div>

package/src/components/WelcomeTour/WelcomeTour.stories.tsx

@@ -2,19 +2,19 @@
 // Copyright 2023 DXOS.org
 //
 
-import '@dxos-theme';
-
-import { Circle } from '@phosphor-icons/react';
 import { type Meta, type StoryObj } from '@storybook/react-vite';
 import React, { useState } from 'react';
 
+import { withPluginManager } from '@dxos/app-framework/testing';
+import { StorybookPlugin } from '@dxos/plugin-testing';
 import { faker } from '@dxos/random';
-import { Button } from '@dxos/react-ui';
-import { withTheme } from '@dxos/storybook-utils';
+import { Button, Icon } from '@dxos/react-ui';
+import { withTheme } from '@dxos/react-ui/testing';
 
-import { WelcomeTour, type WelcomeTourProps } from './WelcomeTour';
 import { useHelp } from '../../hooks';
 
+import { WelcomeTour, type WelcomeTourProps } from './WelcomeTour';
+
 const App = () => {
   const { running, start } = useHelp();
   const [items, setItems] = useState(() => Array.from({ length: 5 }).map(() => faker.lorem.sentence()));
@@ -23,8 +23,8 @@ const App = () => {
   };
 
   return (
-    <div className='flex flex-col h-full p-4 space-y-8'>
-      <div className='flex items-center gap-2 py-2'>
+    <div className='flex flex-col bs-full p-4 space-y-8'>
+      <div className='flex items-center gap-2 plb-2'>
         <Button data-joyride='basic/1' onClick={() => start()}>
           Start
         </Button>
@@ -32,26 +32,26 @@ const App = () => {
         <div>{String(running)}</div>
       </div>
       <div>
-        <ul className='p-2 border border-blue-500 rounded-md' data-joyride='basic/2'>
+        <ul className='p-2 border border-primary-500 rounded-md' data-joyride='basic/2'>
           {items.map((item, i) => (
             <li key={i} className='flex items-center gap-2'>
-              <Circle />
+              <Icon icon='ph--circle--regular' />
               <span>{item}</span>
             </li>
           ))}
         </ul>
       </div>
-      <div className='flex items-center gap-2 py-2'>
+      <div className='flex items-center gap-2 plb-2'>
         <Button data-joyride='basic/3' onClick={handleAdd}>
           Add
         </Button>
       </div>
       <div className='flex grow' />
-      <div className='flex items-center py-2'>
+      <div className='flex items-center plb-2'>
         <div className='grow' />
-        <Circle data-joyride='basic/4' />
-        <Circle />
-        <Circle />
+        <Icon icon='ph--circle--regular' data-joyride='basic/4' />
+        <Icon icon='ph--circle--regular' />
+        <Icon icon='ph--circle--regular' />
       </div>
     </div>
   );
@@ -104,11 +104,16 @@ export const Default: StoryObj<typeof WelcomeTour> = {
 /**
  * IMPORTANT: Run in separate tab.
  */
-const meta: Meta<typeof WelcomeTour> = {
+const meta = {
   title: 'plugins/plugin-help/WelcomeTour',
   component: WelcomeTour,
   render: DefaultStory,
-  decorators: [withTheme],
-};
+  decorators: [
+    withTheme,
+    withPluginManager({
+      plugins: [StorybookPlugin({})],
+    }),
+  ],
+} satisfies Meta<typeof WelcomeTour>;
 
 export default meta;

package/src/components/WelcomeTour/WelcomeTour.tsx

@@ -2,13 +2,14 @@
 // Copyright 2023 DXOS.org
 //
 
-import React, { useState, useEffect } from 'react';
+import React, { useState } from 'react';
 import Joyride, { ACTIONS, EVENTS } from 'react-joyride';
 
-import { usePluginManager, useLayout } from '@dxos/app-framework';
+import { useLayout, usePluginManager } from '@dxos/app-framework/react';
+import { useAsyncEffect } from '@dxos/react-ui';
 
-import { type Step, HelpContext } from '../../types';
-import { floaterProps, Tooltip } from '../Tooltip';
+import { HelpContext, type Step } from '../../types';
+import { Tooltip, floaterProps } from '../Tooltip';
 
 const addStepClass = (target: string | HTMLElement) => {
   const element = typeof target === 'string' ? document.querySelector(target) : target;
@@ -75,7 +76,7 @@ export const WelcomeTour = ({ steps: initialSteps, running: runningProp, onRunni
   const setStepIndex = (index: number) => {
     if (runningProp) {
       const step = steps[index];
-      step?.before?.(manager.context);
+      step?.before?.(manager.capabilities);
     }
     _setStepIndex(index);
   };
@@ -93,20 +94,16 @@ export const WelcomeTour = ({ steps: initialSteps, running: runningProp, onRunni
     }
   };
 
-  useEffect(() => {
-    const timeout = setTimeout(async () => {
-      if (runningProp) {
-        // This handles the case when the target is not yet in the document.
-        // If the target is not in the document, when the joyride is turned on, it will not show the tooltip.
-        await waitForTarget(steps[stepIndex]);
-        setStepIndex(0);
-        setRunning(true);
-      } else if (typeof runningProp !== 'undefined') {
-        setRunning(false);
-      }
-    });
-
-    return () => clearTimeout(timeout);
+  useAsyncEffect(async () => {
+    if (runningProp) {
+      // This handles the case when the target is not yet in the document.
+      // If the target is not in the document, when the joyride is turned on, it will not show the tooltip.
+      await waitForTarget(steps[stepIndex]);
+      setStepIndex(0);
+      setRunning(true);
+    } else if (typeof runningProp !== 'undefined') {
+      setRunning(false);
+    }
   }, [runningProp]);
 
   // https://docs.react-joyride.com/callback

package/src/index.ts

@@ -2,7 +2,7 @@
 // Copyright 2023 DXOS.org
 //
 
-export { HelpCapabilities } from './capabilities';
+export { HelpCapabilities } from './types';
 export * from './components';
 export * from './meta';
 export * from './HelpPlugin';

package/src/meta.ts

@@ -2,13 +2,15 @@
 // Copyright 2023 DXOS.org
 //
 
-import { type PluginMeta } from '@dxos/app-framework';
+import { type Plugin } from '@dxos/app-framework';
+import { trim } from '@dxos/util';
 
-// TODO(burdon): Rename Guide? Help?
-export const HELP_PLUGIN = 'dxos.org/plugin/help';
-
-export const meta: PluginMeta = {
-  id: HELP_PLUGIN,
+export const meta: Plugin.Meta = {
+  id: 'dxos.org/plugin/help',
   name: 'Help',
+  description: trim`
+    Built-in help system with documentation, tutorials, and contextual assistance.
+    Access keyboard shortcuts, feature guides, and support resources.
+  `,
   icon: 'ph--info--regular',
 };

package/src/types/capabilities.ts

@@ -0,0 +1,24 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Atom } from '@effect-atom/atom-react';
+import * as Schema from 'effect/Schema';
+
+import { Capability } from '@dxos/app-framework';
+
+import { meta } from '../meta';
+
+export namespace HelpCapabilities {
+  export const StateSchema = Schema.mutable(
+    Schema.Struct({
+      running: Schema.Boolean,
+      showHints: Schema.Boolean,
+      showWelcome: Schema.Boolean,
+    }),
+  );
+
+  export type State = Schema.Schema.Type<typeof StateSchema>;
+
+  export const State = Capability.make<Atom.Writable<State>>(`${meta.id}/capability/state`);
+}

package/src/types/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './capabilities';
+export * from './schema';

package/src/{types.ts → types/schema.ts}

@@ -2,16 +2,17 @@
 // Copyright 2023 DXOS.org
 //
 
-import { Schema } from 'effect';
+import * as Schema from 'effect/Schema';
 import { type Context, createContext } from 'react';
 import { type Step as BaseStep } from 'react-joyride';
 
-import { type PluginContext } from '@dxos/app-framework';
+import { Capability, type CapabilityManager } from '@dxos/app-framework';
+import { Operation } from '@dxos/operation';
 
-import { HELP_PLUGIN } from './meta';
+import { meta } from '../meta';
 
 export type Step = BaseStep & {
-  before?: (context: PluginContext) => void;
+  before?: (capabilities: CapabilityManager.CapabilityManager) => void;
 };
 
 export type HelpContextType = {
@@ -32,10 +33,12 @@ export const HelpContext: Context<HelpContextType> = createContext<HelpContextTy
   stop: () => {},
 });
 
-export const HELP_ACTION = `${HELP_PLUGIN}/action`;
-export namespace HelpAction {
-  export class Start extends Schema.TaggedClass<Start>()(`${HELP_ACTION}/start`, {
-    input: Schema.Void,
-    output: Schema.Void,
-  }) {}
+const HELP_OPERATION = `${meta.id}/operation`;
+
+export namespace HelpOperation {
+  export const Start = Operation.make({
+    meta: { key: `${HELP_OPERATION}/start`, name: 'Start Help' },
+    services: [Capability.Service],
+    schema: { input: Schema.Void, output: Schema.Void },
+  });
 }

package/dist/lib/browser/app-graph-builder-IXCF4ZDE.mjs

@@ -1,79 +0,0 @@
-import {
-  SHORTCUTS_DIALOG
-} from "./chunk-27RZVOIE.mjs";
-import {
-  HelpAction
-} from "./chunk-WAN2NFYE.mjs";
-import {
-  HelpCapabilities
-} from "./chunk-LDRUZNSN.mjs";
-import {
-  HELP_PLUGIN
-} from "./chunk-3Y4CMOZP.mjs";
-
-// src/capabilities/app-graph-builder.ts
-import { Rx } from "@effect-rx/rx-react";
-import { Option, pipe } from "effect";
-import { Capabilities, contributes, createIntent, LayoutAction } from "@dxos/app-framework";
-import { createExtension } from "@dxos/app-graph";
-var app_graph_builder_default = (context) => contributes(Capabilities.AppGraphBuilder, createExtension({
-  id: HELP_PLUGIN,
-  actions: (node) => Rx.make((get) => pipe(get(node), Option.flatMap((node2) => node2.id === "root" ? Option.some(node2) : 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: 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.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: HELP_PLUGIN
-          }
-        ],
-        icon: "ph--keyboard--regular",
-        keyBinding: {
-          macos: "meta+ctrl+/"
-        }
-      }
-    }
-  ]), Option.getOrElse(() => [])))
-}));
-export {
-  app_graph_builder_default as default
-};
-//# sourceMappingURL=app-graph-builder-IXCF4ZDE.mjs.map

package/dist/lib/browser/app-graph-builder-IXCF4ZDE.mjs.map

@@ -1,7 +0,0 @@
-{
-  "version": 3,
-  "sources": ["../../../src/capabilities/app-graph-builder.ts"],
-  "sourcesContent": ["//\n// Copyright 2025 DXOS.org\n//\n\nimport { Rx } from '@effect-rx/rx-react';\nimport { Option, pipe } from 'effect';\n\nimport { Capabilities, contributes, createIntent, LayoutAction, type PluginContext } from '@dxos/app-framework';\nimport { createExtension } from '@dxos/app-graph';\n\nimport { HelpCapabilities } from './capabilities';\nimport { SHORTCUTS_DIALOG } from '../components';\nimport { HELP_PLUGIN } from '../meta';\nimport { HelpAction } from '../types';\n\nexport default (context: PluginContext) =>\n  contributes(\n    Capabilities.AppGraphBuilder,\n    createExtension({\n      id: HELP_PLUGIN,\n      actions: (node) =>\n        Rx.make((get) =>\n          pipe(\n            get(node),\n            Option.flatMap((node) => (node.id === 'root' ? Option.some(node) : Option.none())),\n            Option.map(() => [\n              {\n                id: HelpAction.Start._tag,\n                data: async () => {\n                  const { dispatchPromise: dispatch } = context.getCapability(Capabilities.IntentDispatcher);\n                  const state = context.getCapability(HelpCapabilities.MutableState);\n                  state.showHints = true;\n                  await dispatch(createIntent(HelpAction.Start));\n                },\n                properties: {\n                  label: ['open help tour', { ns: HELP_PLUGIN }],\n                  icon: 'ph--info--regular',\n                  keyBinding: {\n                    macos: 'shift+meta+/',\n                    // TODO(wittjosiah): Test on windows to see if it behaves the same as linux.\n                    windows: 'shift+ctrl+/',\n                    linux: 'shift+ctrl+?',\n                  },\n                  testId: 'helpPlugin.openHelp',\n                },\n              },\n              {\n                id: 'dxos.org/plugin/help/open-shortcuts',\n                data: async () => {\n                  const { dispatchPromise: dispatch } = context.getCapability(Capabilities.IntentDispatcher);\n                  const state = context.getCapability(HelpCapabilities.MutableState);\n                  state.showHints = true;\n                  await dispatch(\n                    createIntent(LayoutAction.UpdateDialog, {\n                      part: 'dialog',\n                      subject: SHORTCUTS_DIALOG,\n                      options: {\n                        blockAlign: 'center',\n                      },\n                    }),\n                  );\n                },\n                properties: {\n                  label: ['open shortcuts label', { ns: HELP_PLUGIN }],\n                  icon: 'ph--keyboard--regular',\n                  keyBinding: {\n                    macos: 'meta+ctrl+/',\n                  },\n                },\n              },\n            ]),\n            Option.getOrElse(() => []),\n          ),\n        ),\n    }),\n  );\n"],
-  "mappings": ";;;;;;;;;;;;;;AAIA,SAASA,UAAU;AACnB,SAASC,QAAQC,YAAY;AAE7B,SAASC,cAAcC,aAAaC,cAAcC,oBAAwC;AAC1F,SAASC,uBAAuB;AAOhC,IAAA,4BAAe,CAACC,YACdC,YACEC,aAAaC,iBACbC,gBAAgB;EACdC,IAAIC;EACJC,SAAS,CAACC,SACRC,GAAGC,KAAK,CAACC,QACPC,KACED,IAAIH,IAAAA,GACJK,OAAOC,QAAQ,CAACN,UAAUA,MAAKH,OAAO,SAASQ,OAAOE,KAAKP,KAAAA,IAAQK,OAAOG,KAAI,CAAA,GAC9EH,OAAOI,IAAI,MAAM;IACf;MACEZ,IAAIa,WAAWC,MAAMC;MACrBC,MAAM,YAAA;AACJ,cAAM,EAAEC,iBAAiBC,SAAQ,IAAKvB,QAAQwB,cAActB,aAAauB,gBAAgB;AACzF,cAAMC,QAAQ1B,QAAQwB,cAAcG,iBAAiBC,YAAY;AACjEF,cAAMG,YAAY;AAClB,cAAMN,SAASO,aAAaZ,WAAWC,KAAK,CAAA;MAC9C;MACAY,YAAY;QACVC,OAAO;UAAC;UAAkB;YAAEC,IAAI3B;UAAY;;QAC5C4B,MAAM;QACNC,YAAY;UACVC,OAAO;;UAEPC,SAAS;UACTC,OAAO;QACT;QACAC,QAAQ;MACV;IACF;IACA;MACElC,IAAI;MACJgB,MAAM,YAAA;AACJ,cAAM,EAAEC,iBAAiBC,SAAQ,IAAKvB,QAAQwB,cAActB,aAAauB,gBAAgB;AACzF,cAAMC,QAAQ1B,QAAQwB,cAAcG,iBAAiBC,YAAY;AACjEF,cAAMG,YAAY;AAClB,cAAMN,SACJO,aAAaU,aAAaC,cAAc;UACtCC,MAAM;UACNC,SAASC;UACTC,SAAS;YACPC,YAAY;UACd;QACF,CAAA,CAAA;MAEJ;MACAf,YAAY;QACVC,OAAO;UAAC;UAAwB;YAAEC,IAAI3B;UAAY;;QAClD4B,MAAM;QACNC,YAAY;UACVC,OAAO;QACT;MACF;IACF;GACD,GACDvB,OAAOkC,UAAU,MAAM,CAAA,CAAE,CAAA,CAAA;AAGjC,CAAA,CAAA;",
-  "names": ["Rx", "Option", "pipe", "Capabilities", "contributes", "createIntent", "LayoutAction", "createExtension", "context", "contributes", "Capabilities", "AppGraphBuilder", "createExtension", "id", "HELP_PLUGIN", "actions", "node", "Rx", "make", "get", "pipe", "Option", "flatMap", "some", "none", "map", "HelpAction", "Start", "_tag", "data", "dispatchPromise", "dispatch", "getCapability", "IntentDispatcher", "state", "HelpCapabilities", "MutableState", "showHints", "createIntent", "properties", "label", "ns", "icon", "keyBinding", "macos", "windows", "linux", "testId", "LayoutAction", "UpdateDialog", "part", "subject", "SHORTCUTS_DIALOG", "options", "blockAlign", "getOrElse"]
-}