@dxos/plugin-help 0.8.4-main.f9ba587 → 0.8.4-main.fcc0d83b33

package/src/components/Shortcuts/ShortcutsSection.tsx

@@ -4,13 +4,11 @@
 
 import React from 'react';
 
-import { descriptionText } from '@dxos/react-ui-theme';
-
 import { ShortcutsList } from './ShortcutsList';
 
 export const ShortcutsSection = () => {
   return (
-    <section className={descriptionText}>
+    <section className='text-description'>
       <ShortcutsList />
     </section>
   );

package/src/components/Shortcuts/index.ts

@@ -2,7 +2,6 @@
 // Copyright 2023 DXOS.org
 //
 
-export * from './ShortcutsDialog';
 export * from './ShortcutsHints';
 export * from './ShortcutsList';
 export * from './ShortcutsSection';

package/src/components/Shortcuts/styles.ts

@@ -2,9 +2,9 @@
 // Copyright 2023 DXOS.org
 //
 
-import { mx } from '@dxos/react-ui-theme';
+import { mx } from '@dxos/ui-theme';
 
 export const shortcutKey = mx(
-  'inline-flex min-is-[24px] bs-[24px] pli-0.5 justify-center items-center text-xs',
-  'rounded bg-neutral-100 dark:bg-neutral-900',
+  'inline-flex min-w-[24px] h-[24px] px-0.5 justify-center items-center text-xs',
+  'rounded-sm bg-neutral-100 dark:bg-neutral-900',
 );

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
@@ -40,7 +38,7 @@ export const Tooltip = forwardRef<HTMLDivElement, TooltipRenderProps>(
 
     return (
       <div
-        className='flex flex-col is-[15rem] min-bs-[10rem] overflow-hidden rounded-md shadow-xl bg-accentSurface text-accentSurfaceText'
+        className='flex flex-col w-[15rem] min-h-[10rem] overflow-hidden rounded-md shadow-xl bg-accent-surface text-accent-surface-text'
         role='tooltip'
         data-testid='helpPlugin.tooltip'
         data-step={index + 1}
@@ -48,37 +46,39 @@ export const Tooltip = forwardRef<HTMLDivElement, TooltipRenderProps>(
         ref={forwardedRef}
       >
         <div className='flex p-2'>
-          <h2 className='grow pli-2 plb-1 text-lg font-medium text-accentSurfaceText'>{title}</h2>
-          <Button
+          <h2 className='grow px-2 py-1 text-lg font-medium text-accent-surface-text'>{title}</h2>
+          <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 grow px-4 my-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='mx-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,24 +2,24 @@
 // 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 { faker } from '@dxos/random';
-import { Button } from '@dxos/react-ui';
-import { withTheme } from '@dxos/storybook-utils';
+import { withPluginManager } from '@dxos/app-framework/testing';
+import { StorybookPlugin } from '@dxos/plugin-testing';
+import { random } from '@dxos/random';
+import { Button, Icon } from '@dxos/react-ui';
+import { withTheme } from '@dxos/react-ui/testing';
+
+import { useHelp } from '#hooks';
 
 import { WelcomeTour, type WelcomeTourProps } from './WelcomeTour';
-import { useHelp } from '../../hooks';
 
 const App = () => {
   const { running, start } = useHelp();
-  const [items, setItems] = useState(() => Array.from({ length: 5 }).map(() => faker.lorem.sentence()));
+  const [items, setItems] = useState(() => Array.from({ length: 5 }).map(() => random.lorem.sentence()));
   const handleAdd = () => {
-    setItems((items) => [...items, faker.lorem.sentence()]);
+    setItems((items) => [...items, random.lorem.sentence()]);
   };
 
   return (
@@ -32,10 +32,10 @@ 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>
           ))}
@@ -49,9 +49,9 @@ const App = () => {
       <div className='flex grow' />
       <div className='flex items-center py-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>
   );
@@ -76,25 +76,25 @@ export const Default: StoryObj<typeof WelcomeTour> = {
       {
         target: '[data-joyride="basic/1"]',
         title: 'plugins/Step 1',
-        content: faker.lorem.paragraph(),
+        content: random.lorem.paragraph(),
         disableBeacon: true,
         placement: 'right',
       },
       {
         target: '[data-joyride="basic/2"]',
         title: 'plugins/Step 2',
-        content: faker.lorem.paragraph(),
+        content: random.lorem.paragraph(),
       },
       {
         target: '[data-joyride="basic/3"]',
         title: 'plugins/Step 3',
-        content: faker.lorem.paragraph(),
+        content: random.lorem.paragraph(),
         placement: 'right',
       },
       {
         target: '[data-joyride="basic/4"]',
         title: 'plugins/Step 4',
-        content: faker.lorem.paragraph(),
+        content: random.lorem.paragraph(),
         placement: 'top-end',
       },
     ],
@@ -104,11 +104,16 @@ export const Default: StoryObj<typeof WelcomeTour> = {
 /**
  * IMPORTANT: Run in separate tab.
  */
-const meta: Meta<typeof WelcomeTour> = {
-  title: 'plugins/plugin-help/WelcomeTour',
+const meta = {
+  title: 'plugins/plugin-help/components/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,16 @@
 // 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 { usePluginManager } from '@dxos/app-framework/ui';
+import { useLayout } from '@dxos/app-toolkit/ui';
+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 +78,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 +96,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
@@ -164,6 +163,7 @@ export const WelcomeTour = ({ steps: initialSteps, running: runningProp, onRunni
         callback={callback}
         floaterProps={floaterProps}
         tooltipComponent={Tooltip}
+        spotlightPadding={0}
       />
     </HelpContext.Provider>
   );

package/src/constants.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { meta } from '#meta';
+
+export const SHORTCUTS_DIALOG = `${meta.id}.ShortcutsDialog`;

package/src/containers/ShortcutsDialogContent/ShortcutsDialogContent.stories.tsx

@@ -0,0 +1,39 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React from 'react';
+
+import { withPluginManager } from '@dxos/app-framework/testing';
+import { Dialog } from '@dxos/react-ui';
+import { withTheme } from '@dxos/react-ui/testing';
+
+import { translations } from '#translations';
+
+import { ShortcutsDialogContent } from './ShortcutsDialogContent';
+
+const DefaultStory = () => (
+  <Dialog.Root defaultOpen>
+    <Dialog.Overlay>
+      <ShortcutsDialogContent />
+    </Dialog.Overlay>
+  </Dialog.Root>
+);
+
+const meta = {
+  title: 'plugins/plugin-help/containers/ShortcutsDialogContent',
+  component: ShortcutsDialogContent,
+  render: DefaultStory,
+  decorators: [withTheme(), withPluginManager()],
+  parameters: {
+    layout: 'fullscreen',
+    translations,
+  },
+} satisfies Meta<typeof ShortcutsDialogContent>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};

package/src/containers/ShortcutsDialogContent/ShortcutsDialogContent.tsx

@@ -0,0 +1,28 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import React from 'react';
+
+import { Dialog, useTranslation } from '@dxos/react-ui';
+
+import { ShortcutsList } from '#components';
+import { meta } from '#meta';
+
+export const ShortcutsDialogContent = () => {
+  const { t } = useTranslation(meta.id);
+
+  return (
+    <Dialog.Content>
+      <Dialog.Header>
+        <Dialog.Title>{t('shortcuts-dialog.title')}</Dialog.Title>
+        <Dialog.Close asChild>
+          <Dialog.CloseIconButton />
+        </Dialog.Close>
+      </Dialog.Header>
+      <Dialog.Body>
+        <ShortcutsList />
+      </Dialog.Body>
+    </Dialog.Content>
+  );
+};

package/src/containers/ShortcutsDialogContent/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+export { ShortcutsDialogContent as default } from './ShortcutsDialogContent';

package/src/containers/ShortcutsHints/ShortcutsHints.tsx

@@ -0,0 +1,5 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+export { ShortcutsHints } from '../../components';

package/src/containers/ShortcutsHints/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+export { ShortcutsHints as default } from './ShortcutsHints';

package/src/containers/ShortcutsList/ShortcutsList.tsx

@@ -0,0 +1,5 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export { ShortcutsList } from '../../components';

package/src/containers/ShortcutsList/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export { ShortcutsList as default } from './ShortcutsList';

package/src/containers/index.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { type ComponentType, lazy } from 'react';
+
+export const ShortcutsDialogContent: ComponentType<any> = lazy(() => import('./ShortcutsDialogContent'));
+export const ShortcutsHints: ComponentType<any> = lazy(() => import('./ShortcutsHints'));
+export const ShortcutsList: ComponentType<any> = lazy(() => import('./ShortcutsList'));

package/src/hooks/useHelp.tsx

@@ -6,7 +6,7 @@ import { useContext } from 'react';
 
 import { raise } from '@dxos/debug';
 
-import { HelpContext } from '../types';
+import { HelpContext } from '#types';
 
 export const useHelp = () => {
   return useContext(HelpContext) ?? raise(new Error('Missing HelpContext'));

package/src/index.ts

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

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: 'org.dxos.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/operations/definitions.ts

@@ -0,0 +1,19 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+import { Capability } from '@dxos/app-framework';
+import { Operation } from '@dxos/compute';
+
+import { meta } from '#meta';
+
+const HELP_OPERATION = `${meta.id}.operation`;
+
+export const Start = Operation.make({
+  meta: { key: `${HELP_OPERATION}.start`, name: 'Start Help' },
+  services: [Capability.Service],
+  input: Schema.Void,
+  output: Schema.Void,
+});

package/src/operations/index.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { OperationHandlerSet } from '@dxos/compute';
+
+export * as HelpOperation from './definitions';
+
+export const HelpOperationHandlerSet = OperationHandlerSet.lazy(() => import('./start'));

package/src/operations/start.ts

@@ -0,0 +1,21 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+
+import { Capabilities } from '@dxos/app-framework';
+import { Operation } from '@dxos/compute';
+
+import { HelpCapabilities } from '../types';
+import { Start } from './definitions';
+
+const handler: Operation.WithHandler<typeof Start> = Start.pipe(
+  Operation.withHandler(
+    Effect.fnUntraced(function* () {
+      yield* Capabilities.updateAtomValue(HelpCapabilities.State, (state) => ({ ...state, running: true }));
+    }),
+  ),
+);
+
+export default handler;

package/src/translations.ts

@@ -4,16 +4,16 @@
 
 import { type Resource } from '@dxos/react-ui';
 
-import { meta } from './meta';
+import { meta } from '#meta';
 
 export const translations = [
   {
     'en-US': {
       [meta.id]: {
-        'plugin name': 'Help',
-        'open help tour': 'Show welcome tour',
-        'open shortcuts label': 'Show shortcuts',
-        'shortcuts dialog title': 'Shortcuts',
+        'plugin.name': 'Help',
+        'open-help-tour.message': 'Show welcome tour',
+        'open-shortcuts.label': 'Show shortcuts',
+        'shortcuts-dialog.title': 'Shortcuts',
       },
     },
   },

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,13 @@
 // Copyright 2023 DXOS.org
 //
 
-import { Schema } from 'effect';
 import { type Context, createContext } from 'react';
 import { type Step as BaseStep } from 'react-joyride';
 
-import { type PluginContext } from '@dxos/app-framework';
-
-import { HELP_PLUGIN } from './meta';
+import { type CapabilityManager } from '@dxos/app-framework';
 
 export type Step = BaseStep & {
-  before?: (context: PluginContext) => void;
+  before?: (capabilities: CapabilityManager.CapabilityManager) => void;
 };
 
 export type HelpContextType = {
@@ -31,11 +28,3 @@ export const HelpContext: Context<HelpContextType> = createContext<HelpContextTy
   start: () => {},
   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,
-  }) {}
-}