@dxos/plugin-help 0.6.8-main.046e6cf

package/src/HelpPlugin.tsx

@@ -0,0 +1,140 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { type IconProps, Keyboard as KeyboardIcon, Info } from '@phosphor-icons/react';
+import React from 'react';
+
+import { resolvePlugin, type PluginDefinition, parseIntentPlugin, LayoutAction } from '@dxos/app-framework';
+import { createExtension, type Node } from '@dxos/app-graph';
+import { create } from '@dxos/echo-schema';
+import { LocalStorageStore } from '@dxos/local-storage';
+
+import { HelpContextProvider, ShortcutsDialogContent, ShortcutsHints, ShortcutsList } from './components';
+import meta, { HelpAction, HELP_PLUGIN } from './meta';
+import translations from './translations';
+import { type Step, type HelpPluginProvides } from './types';
+
+export type HelpSettingsProps = { showHints?: boolean; showWelcome?: boolean };
+
+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', storageKey: 'show-hints', type: LocalStorageStore.bool({ allowUndefined: true }) })
+        .prop({
+          key: 'showWelcome',
+          storageKey: 'show-welcome',
+          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: (props: IconProps) => <Info {...props} />,
+                  iconSymbol: '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: (props: IconProps) => <KeyboardIcon {...props} />,
+                  iconSymbol: 'ph--keyboard--regular',
+                  keyBinding: {
+                    macos: 'meta+/',
+                    windows: 'ctrl+/',
+                  },
+                },
+              },
+            ],
+          });
+        },
+      },
+      surface: {
+        component: ({ data, role }) => {
+          switch (role) {
+            case 'hints':
+              return settings.values.showHints ? (
+                <ShortcutsHints onClose={() => (settings.values.showHints = false)} />
+              ) : null;
+            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:
+              state.running = true;
+              break;
+          }
+        },
+      },
+    },
+  };
+};

package/src/components/HelpContextProvider/HelpContextProvider.stories.tsx

@@ -0,0 +1,112 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import '@dxosTheme';
+
+import { Circle } from '@phosphor-icons/react';
+import React, { type FC, useState } from 'react';
+import { type Step } from 'react-joyride';
+
+import { faker } from '@dxos/random';
+import { Button } from '@dxos/react-ui';
+import { type Meta, withTheme } from '@dxos/storybook-utils';
+
+import { HelpContextProvider } from './HelpContextProvider';
+import { useHelp } from '../../hooks';
+
+const App = () => {
+  const { running, start } = useHelp();
+  const [items, setItems] = useState(() => Array.from({ length: 5 }).map(() => faker.lorem.sentence()));
+  const handleAdd = () => {
+    setItems((items) => [...items, faker.lorem.sentence()]);
+  };
+
+  return (
+    <div className='flex flex-col h-full p-4 space-y-8'>
+      <div className='flex items-center gap-2 py-2'>
+        <Button data-joyride='basic/1' onClick={() => start()}>
+          Start
+        </Button>
+        <div className='grow' />
+        <div>{String(running)}</div>
+      </div>
+      <div>
+        <ul className='p-2 border border-blue-500 rounded-md' data-joyride='basic/2'>
+          {items.map((item, i) => (
+            <li key={i} className='flex items-center gap-2'>
+              <Circle />
+              <span>{item}</span>
+            </li>
+          ))}
+        </ul>
+      </div>
+      <div className='flex items-center gap-2 py-2'>
+        <Button data-joyride='basic/3' onClick={handleAdd}>
+          Add
+        </Button>
+      </div>
+      <div className='flex grow' />
+      <div className='flex items-center py-2'>
+        <div className='grow' />
+        <Circle data-joyride='basic/4' />
+        <Circle />
+        <Circle />
+      </div>
+    </div>
+  );
+};
+
+const Story: FC<{ steps?: Step[] }> = ({ steps = [] }) => (
+  <HelpContextProvider steps={steps}>
+    <div className='fixed inset-0 overflow-hidden'>
+      <App />
+    </div>
+  </HelpContextProvider>
+);
+
+/**
+ * IMPORTANT: Storybook must be run in separate tab.
+ */
+const meta: Meta = {
+  title: 'plugin-help/Joyride',
+  render: (args: any) => <Story {...args} />,
+  decorators: [withTheme],
+};
+
+export default meta;
+
+// TODO(burdon): Tour should prompt user to create a Stack -- and respond to it being created.
+//  Use beacon to simulate click.
+
+export const Default = {
+  args: {
+    // https://docs.react-joyride.com/step#options
+    steps: [
+      {
+        target: '[data-joyride="basic/1"]',
+        title: 'Step 1',
+        content: faker.lorem.paragraph(),
+        disableBeacon: true,
+        placement: 'right',
+      },
+      {
+        target: '[data-joyride="basic/2"]',
+        title: 'Step 2',
+        content: faker.lorem.paragraph(),
+      },
+      {
+        target: '[data-joyride="basic/3"]',
+        title: 'Step 3',
+        content: faker.lorem.paragraph(),
+        placement: 'right',
+      },
+      {
+        target: '[data-joyride="basic/4"]',
+        title: 'Step 4',
+        content: faker.lorem.paragraph(),
+        placement: 'top-end',
+      },
+    ],
+  },
+};

package/src/components/HelpContextProvider/HelpContextProvider.tsx

@@ -0,0 +1,176 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import React, { type PropsWithChildren, useState, useEffect } from 'react';
+import Joyride, { ACTIONS, EVENTS } from 'react-joyride';
+
+import { usePlugins, resolvePlugin, parseLayoutPlugin } from '@dxos/app-framework';
+import { useShellDisplay, ShellDisplay } from '@dxos/react-client';
+// import { useThemeContext } from '@dxos/react-ui';
+import { tailwindConfig, type TailwindConfig } from '@dxos/react-ui-theme';
+
+import { type Step, HelpContext } from '../../types';
+import { floaterProps, Tooltip } from '../Tooltip';
+
+export const tokens: TailwindConfig['theme'] = tailwindConfig({}).theme;
+
+const addStepClass = (target: string | HTMLElement) => {
+  const element = typeof target === 'string' ? document.querySelector(target) : target;
+  if (element) {
+    element.classList.add('joyride-target');
+  }
+};
+
+const removeTargetClass = (target: string | HTMLElement) => {
+  const element = typeof target === 'string' ? document.querySelector(target) : target;
+  if (element) {
+    element.classList.remove('joyride-target');
+  }
+};
+
+const getTarget = (step: Step) => {
+  return typeof step.target === 'string' ? document.querySelector(step.target) : step.target;
+};
+
+/**
+ * Wait for the target element to be in the document.
+ */
+const waitForTarget = async (step: Step) => {
+  if (typeof step.target === 'string') {
+    const target = step.target;
+    const element = document.querySelector(target);
+    if (element) {
+      return;
+    }
+
+    await new Promise<void>((resolve) => {
+      const observer = new MutationObserver((mutations) => {
+        mutations.forEach((mutation) => {
+          if (mutation.addedNodes.length > 0) {
+            const element = document.querySelector(target);
+            if (element) {
+              observer.disconnect();
+              resolve();
+            }
+          }
+        });
+      });
+
+      observer.observe(document.body, { childList: true, subtree: true });
+    });
+  }
+};
+
+export const HelpContextProvider = ({
+  children,
+  steps: initialSteps,
+  running: runningProp,
+  onRunningChanged,
+}: PropsWithChildren<{ steps: Step[]; running?: boolean; onRunningChanged?: (state: boolean) => any }>) => {
+  const shellDisplay = useShellDisplay();
+  const { plugins } = usePlugins();
+  const layoutPlugin = resolvePlugin(plugins, parseLayoutPlugin);
+  const [running, setRunning] = useState(!!runningProp && !!getTarget(initialSteps[0]));
+  const [stepIndex, _setStepIndex] = useState(0);
+  const [steps, setSteps] = useState(initialSteps);
+
+  const paused = shellDisplay !== ShellDisplay.NONE || layoutPlugin?.provides.layout.dialogOpen;
+
+  const setStepIndex = (index: number) => {
+    if (runningProp) {
+      const step = steps[index];
+      step?.before?.({ plugins, step });
+    }
+    _setStepIndex(index);
+  };
+
+  const setRunningChanged = (state: boolean) => {
+    if (typeof runningProp !== 'undefined') {
+      onRunningChanged?.(state);
+    } else {
+      if (state) {
+        setStepIndex(0);
+        setRunning(true);
+      } else {
+        setRunning(false);
+      }
+    }
+  };
+
+  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);
+  }, [runningProp]);
+
+  // https://docs.react-joyride.com/callback
+  const callback: Joyride['callback'] = async (options) => {
+    const { type, action, index, size } = options;
+    switch (type) {
+      case EVENTS.STEP_BEFORE:
+        addStepClass(options.step.target);
+        break;
+      case EVENTS.TOUR_END:
+        break;
+      case EVENTS.STEP_AFTER:
+        removeTargetClass(options.step.target);
+        switch (action) {
+          case ACTIONS.NEXT:
+            if (index < size - 1) {
+              setStepIndex(index + 1);
+            }
+            break;
+          case ACTIONS.PREV:
+            if (index > 0) {
+              setStepIndex(index - 1);
+            }
+            break;
+          case ACTIONS.CLOSE:
+            setRunningChanged(false);
+            setStepIndex(0);
+            break;
+        }
+        break;
+    }
+  };
+
+  return (
+    <HelpContext.Provider
+      value={{
+        running: running && !paused,
+        steps,
+        setSteps,
+        setIndex: setStepIndex,
+        start: () => setRunningChanged(true),
+        stop: () => setRunningChanged(false),
+      }}
+    >
+      <style>
+        {`.joyride-target {
+          --controls-opacity: 1;
+        }`}
+      </style>
+      <Joyride
+        continuous={true}
+        steps={steps}
+        stepIndex={stepIndex}
+        run={running && !paused}
+        callback={callback}
+        floaterProps={floaterProps}
+        tooltipComponent={Tooltip}
+      />
+      {children}
+    </HelpContext.Provider>
+  );
+};

package/src/components/HelpContextProvider/index.ts

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

package/src/components/Shortcuts/Key.tsx

@@ -0,0 +1,21 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import React from 'react';
+
+import { keySymbols } from '@dxos/keyboard';
+
+import { shortcutKey } from './styles';
+
+export const Key = ({ binding }: { binding: string }) => {
+  return (
+    <span role='term' className='inline-flex gap-1' aria-label={binding} id={binding}>
+      {keySymbols(binding).map((c, i) => (
+        <span key={i} className={shortcutKey}>
+          {c}
+        </span>
+      ))}
+    </span>
+  );
+};

package/src/components/Shortcuts/ShortcutsDialog.tsx

@@ -0,0 +1,30 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import React from 'react';
+
+import { Button, Dialog, useTranslation } from '@dxos/react-ui';
+
+import { ShortcutsList } from './ShortcutsList';
+import { HELP_PLUGIN } from '../../meta';
+
+export const ShortcutsDialogContent = () => {
+  const { t } = useTranslation(HELP_PLUGIN);
+
+  return (
+    <Dialog.Content classNames={'max-bs-[40rem] md:is-auto overflow-hidden'}>
+      <Dialog.Title>{t('shortcuts dialog title')}</Dialog.Title>
+
+      <div className='grow overflow-y-auto py-2'>
+        <ShortcutsList />
+      </div>
+
+      <Dialog.Close asChild>
+        <Button variant='primary' classNames='mbs-2'>
+          {t('close label', { ns: 'os' })}
+        </Button>
+      </Dialog.Close>
+    </Dialog.Content>
+  );
+};

package/src/components/Shortcuts/ShortcutsHints.tsx

@@ -0,0 +1,43 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { X } from '@phosphor-icons/react';
+import React from 'react';
+
+import { type KeyBinding, Keyboard } from '@dxos/keyboard';
+import { Button, DensityProvider, toLocalizedString, useTranslation } from '@dxos/react-ui';
+import { fixedBorder, groupSurface, mx } from '@dxos/react-ui-theme';
+
+import { Key } from './Key';
+
+export const ShortcutsHints = ({ onClose }: { onClose: () => void }) => {
+  const { t } = useTranslation('os');
+
+  // TODO(burdon): Display by context/weight/cycle.
+  const defaults = ['meta+k', 'meta+/', 'meta+,'];
+  const bindings = Keyboard.singleton.getBindings();
+  const hints = bindings.filter((binding) => defaults.includes(binding.shortcut));
+
+  const Shortcut = ({ binding }: { binding: KeyBinding }) => {
+    return (
+      <div role='none' className='flex items-center gap-2'>
+        <Key binding={binding.shortcut} />
+        <span className='text-sm'>{toLocalizedString(binding.data, t)}</span>
+      </div>
+    );
+  };
+
+  return (
+    <DensityProvider density='fine'>
+      <div className={mx('flex items-center border rounded px-2 gap-4', fixedBorder, groupSurface)}>
+        {hints.map((binding) => (
+          <Shortcut key={binding.shortcut} binding={binding} />
+        ))}
+        <Button variant='ghost' classNames='p-0 cursor-pointer' onClick={onClose}>
+          <X />
+        </Button>
+      </div>
+    </DensityProvider>
+  );
+};

package/src/components/Shortcuts/ShortcutsList.tsx

@@ -0,0 +1,35 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+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 { Key } from './Key';
+import { HELP_PLUGIN } from '../../meta';
+
+export const ShortcutsList = () => {
+  const { t } = useTranslation(HELP_PLUGIN);
+  const bindings = Keyboard.singleton.getBindings();
+
+  // TODO(burdon): Get shortcuts from TextEditor.
+  bindings.sort((a, b) => {
+    return toLocalizedString(a.data, t)?.toLowerCase().localeCompare(toLocalizedString(b.data, t)?.toLowerCase());
+  });
+
+  return (
+    <dl className={mx('is-fit grid grid-cols-[min-content_minmax(12rem,1fr)] gap-2 mlb-4 fg-subdued')}>
+      {bindings.map((binding, i) => (
+        <Fragment key={i}>
+          <Key binding={binding.shortcut} />
+          <span role='definition' className='mis-4' aria-labelledby={binding.shortcut}>
+            {toLocalizedString(binding.data, t)}
+          </span>
+        </Fragment>
+      ))}
+    </dl>
+  );
+};

package/src/components/Shortcuts/ShortcutsSection.tsx

@@ -0,0 +1,16 @@
+//
+// Copyright 2024 DXOS.org
+//
+import React from 'react';
+
+import { descriptionText } from '@dxos/react-ui-theme';
+
+import { ShortcutsList } from './ShortcutsList';
+
+export const ShortcutsSection = () => {
+  return (
+    <section className={descriptionText}>
+      <ShortcutsList />
+    </section>
+  );
+};

package/src/components/Shortcuts/index.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+export * from './ShortcutsDialog';
+export * from './ShortcutsHints';
+export * from './ShortcutsList';
+export * from './ShortcutsSection';
+export * from './Key';

package/src/components/Shortcuts/styles.ts

@@ -0,0 +1,10 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { mx } from '@dxos/react-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',
+);