@dxos/plugin-help 0.8.4-main.3f58842 → 0.8.4-main.3fbcb4aa9b

package/src/components/Shortcuts/ShortcutsHints.tsx

@@ -5,14 +5,15 @@
 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'>
+    <div className='flex items-center gap-2 whitespace-nowrap'>
       <Key binding={binding.shortcut} />
       <span className='text-sm'>{toLocalizedString(binding.data, t)}</span>
     </div>
@@ -26,14 +27,21 @@ export const ShortcutsHints = ({ onClose }: { onClose?: () => void }) => {
   const hints = bindings.filter((binding) => defaults.includes(binding.shortcut));
 
   return (
-    <div role='none' className='flex overflow-hidden px-2 gap-4'>
+    <div className='flex overflow-hidden px-2 gap-4'>
       {hints.map((binding) => (
         <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>
   );

package/src/components/Shortcuts/ShortcutsList.tsx

@@ -6,13 +6,14 @@ import React, { Fragment } from 'react';
 
 import { Keyboard } from '@dxos/keyboard';
 import { toLocalizedString, useTranslation } from '@dxos/react-ui';
-import { mx } from '@dxos/react-ui-theme';
+import { mx } from '@dxos/ui-theme';
+
+import { meta } from '#meta';
 
 import { Key } from './Key';
-import { HELP_PLUGIN } from '../../meta';
 
 export const ShortcutsList = () => {
-  const { t } = useTranslation(HELP_PLUGIN);
+  const { t } = useTranslation(meta.id);
   const bindings = Keyboard.singleton.getBindings();
 
   // TODO(burdon): Get shortcuts from TextEditor.
@@ -21,11 +22,11 @@ export const ShortcutsList = () => {
   });
 
   return (
-    <dl className={mx('is-fit grid grid-cols-[min-content_minmax(12rem,1fr)] gap-2 mlb-4 text-subdued select-none')}>
+    <dl className={mx('w-fit grid grid-cols-[min-content_minmax(12rem,1fr)] gap-2 my-4 text-subdued select-none')}>
       {bindings.map((binding, i) => (
         <Fragment key={i}>
           <Key binding={binding.shortcut} />
-          <span role='definition' className='mis-4' aria-labelledby={binding.shortcut}>
+          <span role='definition' className='ms-4' aria-labelledby={binding.shortcut}>
             {toLocalizedString(binding.data, t)}
           </span>
         </Fragment>

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

@@ -7,7 +7,7 @@ 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';
@@ -38,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}
@@ -46,7 +46,7 @@ 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>
+          <h2 className='grow px-2 py-1 text-lg font-medium text-accent-surface-text'>{title}</h2>
           <IconButton
             density='fine'
             icon='ph--x--bold'
@@ -58,7 +58,7 @@ export const Tooltip = forwardRef<HTMLDivElement, TooltipRenderProps>(
             data-testid='helpPlugin.tooltip.close'
           />
         </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}>
           {
             <IconButton
@@ -67,7 +67,6 @@ export const Tooltip = forwardRef<HTMLDivElement, TooltipRenderProps>(
               iconOnly
               label={backProps['aria-label']}
               onClick={backProps.onClick}
-              size={5}
               variant='primary'
               data-testid='helpPlugin.tooltip.back'
             />
@@ -79,7 +78,7 @@ export const Tooltip = forwardRef<HTMLDivElement, TooltipRenderProps>(
                   key={i}
                   icon={index === i ? 'ph--circle--fill' : 'ph--circle--regular'}
                   size={2}
-                  classNames='mli-1 cursor-pointer'
+                  classNames='mx-1 cursor-pointer'
                 />
               ))}
             </div>

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

@@ -2,23 +2,24 @@
 // Copyright 2023 DXOS.org
 //
 
-import '@dxos-theme';
-
 import { type Meta, type StoryObj } from '@storybook/react-vite';
 import React, { useState } from 'react';
 
-import { faker } from '@dxos/random';
+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/storybook-utils';
+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 (
@@ -31,7 +32,7 @@ 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'>
               <Icon icon='ph--circle--regular' />
@@ -75,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',
       },
     ],
@@ -103,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,7 @@
 // Copyright 2023 DXOS.org
 //
 
-export { HelpCapabilities } from './capabilities';
-export * from './components';
+export * from './constants';
 export * from './meta';
-export * from './HelpPlugin';
-export * from './hooks';
+export * from './operations';
 export * from './types';

package/src/meta.ts

@@ -2,13 +2,16 @@
 // 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',
+  tags: ['system'],
 };

package/src/operations/index.ts

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

package/src/operations/start.ts

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

package/src/plugin.ts

@@ -0,0 +1,12 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { Plugin } from '@dxos/app-framework';
+
+import { meta } from './meta';
+
+export const HelpPlugin = Plugin.lazy(meta, () => import('#plugin'));
+export type { HelpPluginOptions } from '#plugin';
+
+export { HelpOperationHandlerSet } from './operations';

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/HelpCapabilities.ts

@@ -0,0 +1,24 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// @import-as-namespace
+
+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 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/HelpOperation.ts

@@ -0,0 +1,21 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+// @import-as-namespace
+
+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/types/index.ts

@@ -2,4 +2,6 @@
 // Copyright 2025 DXOS.org
 //
 
+export * as HelpCapabilities from './HelpCapabilities';
+export * as HelpOperation from './HelpOperation';
 export * from './schema';

package/src/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 { meta } 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,10 +28,3 @@ export const HelpContext: Context<HelpContextType> = createContext<HelpContextTy
   start: () => {},
   stop: () => {},
 });
-
-export namespace HelpAction {
-  export class Start extends Schema.TaggedClass<Start>()(`${meta.id}/action/start`, {
-    input: Schema.Void,
-    output: Schema.Void,
-  }) {}
-}