@matthesketh/react-guidetour 1.0.0

package/src/types/common.ts

@@ -0,0 +1,110 @@
+import { CSSProperties, ReactNode } from 'react';
+import { Styles as FloaterStyles } from 'react-floater';
+import { ValueOf } from 'type-fest';
+
+import { ACTIONS, EVENTS, LIFECYCLE, ORIGIN, STATUS } from '~/literals';
+
+export type Actions = ValueOf<typeof ACTIONS>;
+export type Events = ValueOf<typeof EVENTS>;
+export type Lifecycle = ValueOf<typeof LIFECYCLE>;
+export type Origin = ValueOf<typeof ORIGIN>;
+export type Status = ValueOf<typeof STATUS>;
+
+export type AnyObject<T = any> = Record<string, T>;
+
+export type NarrowPlainObject<T extends Record<string, any>> = Exclude<
+  T,
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+  Array<unknown> | Function | Map<unknown, unknown> | Set<unknown>
+>;
+
+export interface Locale {
+  /**
+   * Label for the back button.
+   * @default 'Back'
+   */
+  back?: ReactNode;
+  /**
+   * Label for the close button.
+   * @default 'Close'
+   */
+  close?: ReactNode;
+  /**
+   * Label for the last button.
+   * @default 'Last'
+   */
+  last?: ReactNode;
+  /**
+   * Label for the next button.
+   * @default 'Next'
+   */
+  next?: ReactNode;
+  /**
+   * Label for the next button with `showProgress`.
+   * Use the `{step}` and `{steps}` placeholders to display the current step and the total steps.
+   * @default 'Next (Step {step} of {steps})'
+   */
+  nextLabelWithProgress?: ReactNode;
+  /**
+   * Label for the open button.
+   * @default 'Open the dialog'
+   */
+  open?: ReactNode;
+  /**
+   * Label for the skip button.
+   * @default 'Skip'
+   */
+  skip?: ReactNode;
+}
+
+export type Placement =
+  | 'top'
+  | 'top-start'
+  | 'top-end'
+  | 'bottom'
+  | 'bottom-start'
+  | 'bottom-end'
+  | 'left'
+  | 'left-start'
+  | 'left-end'
+  | 'right'
+  | 'right-start'
+  | 'right-end';
+
+export interface Styles {
+  beacon: CSSProperties;
+  beaconInner: CSSProperties;
+  beaconOuter: CSSProperties;
+  buttonBack: CSSProperties;
+  buttonClose: CSSProperties;
+  buttonNext: CSSProperties;
+  buttonSkip: CSSProperties;
+  options: Partial<StylesOptions>;
+  overlay: CSSProperties;
+  overlayLegacy: CSSProperties;
+  overlayLegacyCenter: CSSProperties;
+  spotlight: CSSProperties;
+  spotlightLegacy: CSSProperties;
+  tooltip: CSSProperties;
+  tooltipContainer: CSSProperties;
+  tooltipContent: CSSProperties;
+  tooltipFooter: CSSProperties;
+  tooltipFooterSpacer: CSSProperties;
+  tooltipTitle: CSSProperties;
+}
+
+export interface StylesWithFloaterStyles extends Styles {
+  floaterStyles: FloaterStyles;
+}
+
+export interface StylesOptions {
+  arrowColor: string;
+  backgroundColor: string;
+  beaconSize: number;
+  overlayColor: string;
+  primaryColor: string;
+  spotlightShadow: string;
+  textColor: string;
+  width?: string | number;
+  zIndex: number;
+}

package/src/types/components.ts

@@ -0,0 +1,382 @@
+import { ElementType, MouseEventHandler, ReactNode, RefCallback } from 'react';
+import { Props as FloaterProps } from 'react-floater';
+import { PartialDeep, SetRequired, Simplify } from 'type-fest';
+
+import type { StoreInstance } from '~/modules/store';
+
+import { Actions, Events, Lifecycle, Locale, Origin, Placement, Status, Styles } from './common';
+
+export type BaseProps = {
+  /**
+   * A React component to use instead the default Beacon.
+   */
+  beaconComponent?: ElementType<BeaconRenderProps>;
+  /**
+   * Disable closing the tooltip on ESC.
+   * @default false
+   */
+  disableCloseOnEsc?: boolean;
+  /**
+   * Don't show the overlay.
+   * @default false
+   */
+  disableOverlay?: boolean;
+  /**
+   * Don't close the tooltip when clicking the overlay.
+   * @default false
+   */
+  disableOverlayClose?: boolean;
+  /**
+   * Disable the fix to handle "unused" overflow parents.
+   * @default false
+   */
+  disableScrollParentFix?: boolean;
+  /**
+   * @default false
+   */
+  disableScrolling?: boolean;
+  /**
+   * Options to be passed to react-floater
+   */
+  floaterProps?: Partial<FloaterProps>;
+  /**
+   * Hide the Back button.
+   * @default false
+   */
+  hideBackButton?: boolean;
+  /**
+   * Hide the Close button.
+   * @default false
+   */
+  hideCloseButton?: boolean;
+  /**
+   * The strings used in the tooltip.
+   */
+  locale?: Locale;
+  /**
+   * @default false
+   */
+  showProgress?: boolean;
+  /**
+   * @default false
+   */
+  showSkipButton?: boolean;
+  /**
+   * @default false
+   */
+  spotlightClicks?: boolean;
+  /**
+   * The padding of the spotlight.
+   * @default 10
+   */
+  spotlightPadding?: number;
+  /**
+   * Override the styling of the Tooltip
+   */
+  styles?: PartialDeep<Styles>;
+  /**
+   * A React component to use instead the default Tooltip.
+   */
+  tooltipComponent?: ElementType<TooltipRenderProps>;
+};
+
+export type BeaconProps = Simplify<
+  Pick<Props, 'beaconComponent' | 'nonce'> &
+    BeaconRenderProps & {
+      locale: Locale;
+      onClickOrHover: MouseEventHandler<HTMLElement>;
+      shouldFocus: boolean;
+      styles: Styles;
+    }
+>;
+
+export type BeaconRenderProps = {
+  continuous: boolean;
+  index: number;
+  isLastStep: boolean;
+  size: number;
+  step: StepMerged;
+};
+
+export type Callback = (data: CallBackProps) => void;
+
+export type CallBackProps = {
+  /**
+   * The action that updated the state.
+   */
+  action: Actions;
+  /**
+   * It the tour is in `controlled` mode.
+   * (using the `stepIndex` prop)
+   */
+  controlled: boolean;
+  /**
+   * The current step's index
+   */
+  index: number;
+  /**
+   *  The step's lifecycle.
+   */
+  lifecycle: Lifecycle;
+  /**
+   * The element that triggered the action (if available).
+   */
+  origin: Origin | null;
+  /**
+   * The number of steps
+   */
+  size: number;
+  /**
+   * The tour's status.
+   */
+  status: Status;
+  /**
+   * The current step's data.
+   */
+  step: Step;
+  /**
+   * The type of the event.
+   */
+  type: Events;
+};
+
+export type OverlayProps = Simplify<
+  StepMerged & {
+    continuous: boolean;
+    debug: boolean;
+    lifecycle: Lifecycle;
+    onClickOverlay: () => void;
+  }
+>;
+
+export type Props = Simplify<
+  BaseProps & {
+    /**
+     * A function to be called when Joyride's state changes.
+     * It returns a single parameter with the state.
+     */
+    callback?: Callback;
+    /**
+     * The tour is played sequentially with the Next button.
+     * @default false
+     */
+    continuous?: boolean;
+    /**
+     * Log Joyride's actions to the console.
+     * @default false
+     */
+    debug?: boolean;
+    /**
+     * Get the store methods to control the tour programmatically. `prev, next, go, close, skip, reset, info`
+     */
+    getHelpers?: (helpers: StoreHelpers) => void;
+    /**
+     * A nonce value for inline styles (Content Security Policy - CSP)
+     */
+    nonce?: string;
+    /**
+     * Run/stop the tour.
+     * @default true
+     */
+    run?: boolean;
+    /**
+     * The duration for scroll to element.
+     * @default 300
+     */
+    scrollDuration?: number;
+    /**
+     * The scroll distance from the element scrollTop value.
+     * @default 20
+     */
+    scrollOffset?: number;
+    /**
+     * Scroll the page for the first step.
+     * @default false
+     */
+    scrollToFirstStep?: boolean;
+    /**
+     * Setting a number here will turn Joyride into `controlled` mode.
+     * You'll have to keep an internal state by yourself and update it with the events in the `callback`.
+     */
+    stepIndex?: number;
+    /**
+     * The tour's steps.
+     */
+    steps: Array<Step>;
+  }
+>;
+
+export type State = {
+  action: Actions;
+  controlled: boolean;
+  index: number;
+  lifecycle: Lifecycle;
+  origin: Origin | null;
+  size: number;
+  status: Status;
+};
+
+export type Step = Simplify<
+  BaseProps & {
+    /**
+     * The tooltip's body.
+     */
+    content: ReactNode;
+    /**
+     * Additional data you can add to the step.
+     */
+    data?: any;
+    /**
+     * Don't show the Beacon before the tooltip.
+     * @default false
+     */
+    disableBeacon?: boolean;
+    /**
+     * The event to trigger the beacon.
+     * @default click
+     */
+    event?: 'click' | 'hover';
+    /**
+     * Options to be passed to react-floater
+     */
+    floaterProps?: FloaterProps;
+    /**
+     * Hide the tooltip's footer.
+     * @default false
+     */
+    hideFooter?: boolean;
+    /**
+     * Force the step to be fixed.
+     * @default false
+     */
+    isFixed?: boolean;
+    /**
+     * @default 10
+     */
+    offset?: number;
+    /**
+     * The placement of the beacon and tooltip. It will re-position itself if there's no space available.
+     * @default bottom
+     */
+    placement?: Placement | 'auto' | 'center';
+    /**
+     * The placement of the beacon. It will use the `placement` if nothing is passed
+     */
+    placementBeacon?: Placement;
+    /**
+     * The target for the step.
+     * It can be a CSS selector or an HTMLElement ref.
+     */
+    target: string | HTMLElement;
+    /**
+     * The tooltip's title.
+     */
+    title?: ReactNode;
+  }
+>;
+
+export type StepMerged = Simplify<
+  SetRequired<
+    Step,
+    | 'disableBeacon'
+    | 'disableCloseOnEsc'
+    | 'disableOverlay'
+    | 'disableOverlayClose'
+    | 'disableScrollParentFix'
+    | 'disableScrolling'
+    | 'event'
+    | 'hideBackButton'
+    | 'hideCloseButton'
+    | 'hideFooter'
+    | 'isFixed'
+    | 'locale'
+    | 'offset'
+    | 'placement'
+    | 'showProgress'
+    | 'showSkipButton'
+    | 'spotlightClicks'
+    | 'spotlightPadding'
+  > & {
+    styles: Styles;
+  }
+>;
+
+export type StepProps = Simplify<
+  State & {
+    callback: Callback;
+    continuous: boolean;
+    debug: boolean;
+    helpers: StoreHelpers;
+    nonce?: string;
+    shouldScroll: boolean;
+    step: StepMerged;
+    store: StoreInstance;
+  }
+>;
+
+export type StoreHelpers = {
+  close: (origin?: Origin | null) => void;
+  go: (nextIndex: number) => void;
+  info: () => State;
+  next: () => void;
+  open: () => void;
+  prev: () => void;
+  reset: (restart: boolean) => void;
+  skip: () => void;
+};
+
+export type StoreOptions = Simplify<
+  Props & {
+    controlled: boolean;
+  }
+>;
+
+export type TooltipProps = {
+  continuous: boolean;
+  helpers: StoreHelpers;
+  index: number;
+  isLastStep: boolean;
+  setTooltipRef: RefCallback<HTMLElement>;
+  size: number;
+  step: StepMerged;
+};
+
+export type TooltipRenderProps = Simplify<
+  BeaconRenderProps & {
+    backProps: {
+      'aria-label': string;
+      'data-action': string;
+      onClick: MouseEventHandler<HTMLElement>;
+      role: string;
+      title: string;
+    };
+    closeProps: {
+      'aria-label': string;
+      'data-action': string;
+      onClick: MouseEventHandler<HTMLElement>;
+      role: string;
+      title: string;
+    };
+    primaryProps: {
+      'aria-label': string;
+      'data-action': string;
+      onClick: MouseEventHandler<HTMLElement>;
+      role: string;
+      title: string;
+    };
+    skipProps: {
+      'aria-label': string;
+      'data-action': string;
+      onClick: MouseEventHandler<HTMLElement>;
+      role: string;
+      title: string;
+    };
+    tooltipProps: {
+      'aria-modal': boolean;
+      ref: RefCallback<HTMLElement>;
+      role: string;
+    };
+  }
+>;
+
+export type { Props as FloaterProps } from 'react-floater';

package/src/types/index.ts

@@ -0,0 +1,2 @@
+export * from './common';
+export * from './components';