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

package/src/components/Tooltip/Tooltip.tsx

@@ -0,0 +1,111 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+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';
+// 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';
+
+// https://docs.react-joyride.com/styling
+// https://github.com/gilbarbara/react-floater
+export const floaterProps: Props['floaterProps'] = {
+  styles: {
+    // Arrow color is set by joyride.
+    arrow: {
+      length: 8,
+      spread: 16,
+    },
+    floater: {
+      // TODO(burdon): Get tokens from theme.
+      filter: 'drop-shadow(0 0 0.75rem rgba(0, 0, 0, 0.2))',
+    },
+  },
+};
+
+// TODO(burdon): Add info link to docs.
+export const Tooltip = forwardRef<HTMLDivElement, TooltipRenderProps>(
+  ({ step: { title, content }, index, size, isLastStep, backProps, closeProps, primaryProps }, forwardedRef) => {
+    const arrowGroup = useArrowNavigationGroup({ axis: 'horizontal' });
+    const trapFocus = useFocusableGroup({ tabBehavior: 'limited-trap-focus' });
+
+    return (
+      <div
+        className='flex flex-col is-[15rem] min-bs-[10rem] overflow-hidden rounded-md shadow-xl surface-accent fg-inverse'
+        role='tooltip'
+        data-testid='helpPlugin.tooltip'
+        data-step={index + 1}
+        {...trapFocus}
+        ref={forwardedRef}
+      >
+        <div className='flex p-2'>
+          <h2 className='grow pli-2 plb-1 text-lg font-medium fg-inverse'>{title}</h2>
+          <Button
+            density='fine'
+            variant='primary'
+            onClick={closeProps.onClick}
+            title={closeProps['aria-label']}
+            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' {...arrowGroup}>
+          {
+            <Button
+              variant='primary'
+              onClick={backProps.onClick}
+              title={backProps['aria-label']}
+              classNames={[!(index > 0 && backProps) && 'invisible']}
+              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
+                  key={i}
+                  weight={index === i ? 'fill' : 'regular'}
+                  className={mx(getSize(2), 'mli-1 cursor-pointer')}
+                />
+              ))}
+            </div>
+          </div>
+          {isLastStep ? (
+            <Button
+              variant='primary'
+              onClick={closeProps.onClick}
+              title={closeProps['aria-label']}
+              autoFocus
+              data-testid='helpPlugin.tooltip.finish'
+            >
+              Done
+            </Button>
+          ) : (
+            <Button
+              variant='primary'
+              onClick={primaryProps.onClick}
+              title={primaryProps['aria-label']}
+              autoFocus
+              data-testid='helpPlugin.tooltip.next'
+            >
+              <CaretRight className={getSize(6)} />
+            </Button>
+          )}
+        </div>
+      </div>
+    );
+  },
+);

package/src/components/Tooltip/index.ts

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

package/src/components/index.ts

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

package/src/hooks/index.ts

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

package/src/hooks/useHelp.tsx

@@ -0,0 +1,13 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { useContext } from 'react';
+
+import { raise } from '@dxos/debug';
+
+import { HelpContext } from '../types';
+
+export const useHelp = () => {
+  return useContext(HelpContext) ?? raise(new Error('Missing HelpContext'));
+};

package/src/index.ts

@@ -0,0 +1,15 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { HelpPlugin } from './HelpPlugin';
+import { type Step } from './types';
+
+export type { Step };
+
+export * from './components';
+export * from './hooks';
+
+export * from './HelpPlugin';
+
+export default HelpPlugin;

package/src/meta.tsx

@@ -0,0 +1,23 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { Info, type IconProps } from '@phosphor-icons/react';
+import React from 'react';
+
+import { pluginMeta } from '@dxos/app-framework';
+
+// TODO(burdon): Rename Guide? Help?
+export const HELP_PLUGIN = 'dxos.org/plugin/help';
+
+export default pluginMeta({
+  id: HELP_PLUGIN,
+  name: 'Help',
+  iconComponent: (props: IconProps) => <Info {...props} />,
+  iconSymbol: 'ph--info--regular',
+});
+
+const HELP_ACTION = `${HELP_PLUGIN}/action`;
+export enum HelpAction {
+  START = `${HELP_ACTION}/start`,
+}

package/src/translations.ts

@@ -0,0 +1,18 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { HELP_PLUGIN } from './meta';
+
+export default [
+  {
+    'en-US': {
+      [HELP_PLUGIN]: {
+        'plugin name': 'Help',
+        'open help tour': 'Show welcome tour',
+        'open shortcuts label': 'Show shortcuts',
+        'shortcuts dialog title': 'Shortcuts',
+      },
+    },
+  },
+];

package/src/types.ts

@@ -0,0 +1,38 @@
+//
+// Copyright 2023 DXOS.org
+//
+
+import { type Context, createContext } from 'react';
+import { type Step as BaseStep } from 'react-joyride';
+
+import {
+  type Plugin,
+  type GraphBuilderProvides,
+  type IntentResolverProvides,
+  type SurfaceProvides,
+  type TranslationsProvides,
+} from '@dxos/app-framework';
+
+export type Step = BaseStep & {
+  before?: (context: { plugins: Plugin[]; step: Step }) => void;
+};
+
+export type HelpContextType = {
+  running: boolean;
+  steps: Step[];
+  setSteps: (steps: Step[]) => void;
+  setIndex: (index: number) => void;
+  start: () => void;
+  stop: () => void;
+};
+
+export const HelpContext: Context<HelpContextType> = createContext<HelpContextType>({
+  running: false,
+  steps: [],
+  setSteps: () => {},
+  setIndex: () => {},
+  start: () => {},
+  stop: () => {},
+});
+
+export type HelpPluginProvides = GraphBuilderProvides & IntentResolverProvides & SurfaceProvides & TranslationsProvides;