@numidev/react-joyride 1.0.1

package/src/types/common.ts

@@ -0,0 +1,315 @@
+import type { CSSProperties, ReactNode, SVGAttributes } from 'react';
+
+import { ACTIONS, EVENTS, LIFECYCLE, ORIGIN, STATUS } from '~/literals';
+
+import type { TourData } from './events';
+import type { ValueOf } from './utilities';
+
+/** The action that triggered the state update. */
+export type Actions = ValueOf<typeof ACTIONS>;
+
+/** A hook that runs after a step completes. Fire-and-forget. */
+export type AfterHook = (data: TourData) => void;
+
+/** A hook that runs before a step is shown. The tour waits for the promise to resolve. */
+export type BeforeHook = (data: TourData) => Promise<void>;
+
+/** The buttons to show in the tooltip. */
+export type ButtonType = 'back' | 'close' | 'primary' | 'skip';
+
+/** The event type passed to the `onEvent` callback. */
+export type Events = ValueOf<typeof EVENTS>;
+
+/** The reason a step failed during the tour. */
+export type FailureReason = 'before_hook' | 'target_not_found';
+
+/** The rendering phase of the current step. */
+export type Lifecycle = ValueOf<typeof LIFECYCLE>;
+
+/** The UI element that triggered the action. */
+export type Origin = ValueOf<typeof ORIGIN>;
+
+/** Tooltip and beacon placement positions. */
+export type Placement =
+  | 'top'
+  | 'top-start'
+  | 'top-end'
+  | 'bottom'
+  | 'bottom-start'
+  | 'bottom-end'
+  | 'left'
+  | 'left-start'
+  | 'left-end'
+  | 'right'
+  | 'right-start'
+  | 'right-end';
+
+/** The current state of the tour. */
+export type Status = ValueOf<typeof STATUS>;
+
+/** Tooltip button and navigation labels. */
+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 `{current}` and `{total}` placeholders to display the current step and the total steps.
+   * @default 'Next ({current} of {total})'
+   */
+  nextWithProgress?: ReactNode;
+  /**
+   * Label for the open button.
+   * @default 'Open the dialog'
+   */
+  open?: ReactNode;
+  /**
+   * Label for the skip button.
+   * @default 'Skip'
+   */
+  skip?: ReactNode;
+}
+
+/** Step options for behavior, theming, and layout. Shared between Props and Step. */
+export interface Options {
+  /**
+   * A hook that runs after the step completes (user clicked next, prev, close, or skip).
+   * Fire-and-forget — does not block the tour.
+   */
+  after?: AfterHook;
+  /**
+   * Width of the arrow base edge in pixels.
+   * @default 32
+   */
+  arrowBase: number;
+  /**
+   * Arrow fill color.
+   * @default '#ffffff'
+   */
+  arrowColor: string;
+  /**
+   * Height/depth of the arrow (tip to base edge) in pixels.
+   * @default 16
+   */
+  arrowSize: number;
+  /**
+   * The distance between the arrow and the edge of the tooltip.
+   * @default 12
+   */
+  arrowSpacing: number;
+  /**
+   * Tooltip background color.
+   * @default '#ffffff'
+   */
+  backgroundColor: string;
+  /**
+   * Beacon diameter in pixels.
+   * @default 36
+   */
+  beaconSize: number;
+  /**
+   * The interaction that triggers the beacon to show the tooltip.
+   * @default 'click'
+   */
+  beaconTrigger: 'click' | 'hover';
+  /**
+   * A hook that runs before the step is shown.
+   * The tour waits for the returned promise to resolve and shows the loader while waiting (after `loaderDelay`).
+   * Max duration capped by `beforeTimeout`.
+   */
+  before?: BeforeHook;
+  /**
+   * Max time (ms) to wait for a `before` hook to resolve. 0 = no timeout.
+   * @default 5000
+   */
+  beforeTimeout: number;
+  /**
+   * Block pointer events on the highlighted element through the spotlight cutout.
+   * @default false
+   */
+  blockTargetInteraction: boolean;
+  /**
+   * The buttons to show in the tooltip.
+   * @default ['back', 'close', 'primary']
+   */
+  buttons: ButtonType[];
+  /**
+   * The action to take when the close button is clicked.
+   * - `'close'`: Advances to the next step (default behavior).
+   * - `'skip'`: Ends the tour entirely.
+   * - `'replay'`: Replays the current step.
+   * @default 'close'
+   */
+  closeButtonAction: 'close' | 'skip' | 'replay';
+  /**
+   * Disable the focus trap for the tooltip.
+   * @default false
+   */
+  disableFocusTrap: boolean;
+  /**
+   * The action to take when the ESC key is pressed.
+   * - `'close'`: Closes the step (shows beacon on next step in continuous mode).
+   * - `'next'`: Advances to the next step (skips beacon in continuous mode).
+   * - `'replay'`: Replays the current step.
+   * - `false`: Disables ESC key.
+   * @default 'close'
+   */
+  dismissKeyAction: 'close' | 'next' | 'replay' | false;
+  /**
+   * Don't show the overlay.
+   * @default false
+   */
+  hideOverlay: boolean;
+  /**
+   * Delay (ms) before showing the loader while the tour is waiting.
+   * @default 300
+   */
+  loaderDelay: number;
+  /**
+   * The distance in pixels between the tooltip and the spotlight.
+   * @default 10
+   */
+  offset: number;
+  /**
+   * The action to take when the overlay is clicked.
+   * - `'close'`: Closes the step (fires a CLOSE action).
+   * - `'next'`: Advances to the next step (ends the tour on the last step).
+   * - `'replay'`: Replays the current step.
+   * - `false`: Disables overlay click.
+   * @default 'close'
+   */
+  overlayClickAction: 'close' | 'next' | 'replay' | false;
+  /**
+   * Overlay backdrop color.
+   * @default '#00000080'
+   */
+  overlayColor: string;
+  /**
+   * Primary button and beacon color.
+   * @default '#000000'
+   */
+  primaryColor: string;
+  /**
+   * The scroll animation duration in milliseconds.
+   * @default 300
+   */
+  scrollDuration: number;
+  /**
+   * The scroll distance from the element scrollTop value.
+   * @default 20
+   */
+  scrollOffset: number;
+  /**
+   * Show the progress (1 of 5) in the tooltip.
+   * @default false
+   */
+  showProgress: boolean;
+  /**
+   * Don't show the Beacon before the tooltip.
+   * @default false
+   */
+  skipBeacon: boolean;
+  /**
+   * Skip scrolling to the target.
+   * @default false
+   */
+  skipScroll: boolean;
+  /**
+   * The padding of the spotlight.
+   * Accepts a number for equal padding on all sides, or an object with `top`, `right`, `bottom`, `left`.
+   * @default 10
+   */
+  spotlightPadding: number | SpotlightPadding;
+  /**
+   * The border radius of the spotlight cutout in pixels.
+   * @default 4
+   */
+  spotlightRadius: number;
+  /**
+   * Max time (ms) to wait for the target to appear. 0 = no waiting.
+   * @default 1000
+   */
+  targetWaitTimeout: number;
+  /**
+   * Tooltip text color.
+   * @default '#000000'
+   */
+  textColor: string;
+  /**
+   * Tooltip width in pixels or CSS string.
+   * @default 380
+   */
+  width?: string | number;
+  /**
+   * z-index for the overlay and tooltip.
+   * @default 100
+   */
+  zIndex: number;
+}
+
+/** Padding around the spotlight cutout in pixels. */
+export interface SpotlightPadding {
+  bottom?: number;
+  left?: number;
+  right?: number;
+  top?: number;
+}
+
+/** CSS styles for all Joyride UI elements. */
+export interface Styles {
+  /** Arrow element styles. */
+  arrow: CSSProperties;
+  /** Beacon visual styles (size, border-radius). Applied to the default beacon content. */
+  beacon: CSSProperties;
+  /** Beacon inner pulse element styles. */
+  beaconInner: CSSProperties;
+  /** Beacon outer ring element styles. */
+  beaconOuter: CSSProperties;
+  /** Beacon wrapper button styles (interaction, layout). */
+  beaconWrapper: CSSProperties;
+  /** Back button styles. */
+  buttonBack: CSSProperties;
+  /** Close button styles. */
+  buttonClose: CSSProperties;
+  /** Next/Last button styles. */
+  buttonPrimary: CSSProperties;
+  /** Skip button styles. */
+  buttonSkip: CSSProperties;
+  /** Floating container styles. */
+  floater: CSSProperties;
+  /** Loader wrapper styles. */
+  loader: CSSProperties;
+  /** Overlay backdrop styles. */
+  overlay: CSSProperties;
+  /** Spotlight styles (SVG Path). */
+  spotlight: SVGAttributes<SVGPathElement>;
+  /** Tooltip wrapper styles. */
+  tooltip: CSSProperties;
+  /** Tooltip inner container styles. */
+  tooltipContainer: CSSProperties;
+  /** Tooltip body content styles. */
+  tooltipContent: CSSProperties;
+  /** Tooltip footer styles. */
+  tooltipFooter: CSSProperties;
+  /** Tooltip footer spacer styles. */
+  tooltipFooterSpacer: CSSProperties;
+  /** Tooltip title styles. */
+  tooltipTitle: CSSProperties;
+}

package/src/types/components.ts

@@ -0,0 +1,84 @@
+import type { MouseEventHandler } from 'react';
+
+import type { Controls } from '~/types/state';
+
+import type { Placement } from './common';
+import type { StepMerged } from './step';
+import type { Simplify } from './utilities';
+
+/** Props passed to a custom arrow component. */
+export type ArrowRenderProps = {
+  /** Width of the arrow base in pixels. */
+  base: number;
+  /** The computed placement of the tooltip. */
+  placement: Placement;
+  /** Height of the arrow in pixels. */
+  size: number;
+};
+
+/** Props passed to a custom beacon component.
+ * Must render a span since it's placed inside a `<button>` wrapper.
+ */
+export type BeaconRenderProps = {
+  /** Whether the tour is in continuous mode. */
+  continuous: boolean;
+  /** The current step index. */
+  index: number;
+  /** Whether this is the last step. */
+  isLastStep: boolean;
+  /** The total number of steps. */
+  size: number;
+  /** The current step data. */
+  step: StepMerged;
+};
+
+/** Props passed to a custom loader component. */
+export type LoaderRenderProps = {
+  /** The current step data. */
+  step: StepMerged;
+};
+
+/** Props passed to a custom tooltip component. */
+export type TooltipRenderProps = Simplify<
+  BeaconRenderProps & {
+    /** Props to spread on the back button. */
+    backProps: {
+      'aria-label': string;
+      'data-action': string;
+      onClick: MouseEventHandler<HTMLElement>;
+      role: string;
+      title: string;
+    };
+    /** Props to spread on the close button. */
+    closeProps: {
+      'aria-label': string;
+      'data-action': string;
+      onClick: MouseEventHandler<HTMLElement>;
+      role: string;
+      title: string;
+    };
+    /** Methods to programmatically control the tour. */
+    controls: Controls;
+    /** Props to spread on the next/last button. */
+    primaryProps: {
+      'aria-label': string;
+      'data-action': string;
+      onClick: MouseEventHandler<HTMLElement>;
+      role: string;
+      title: string;
+    };
+    /** Props to spread on the skip button. */
+    skipProps: {
+      'aria-label': string;
+      'data-action': string;
+      onClick: MouseEventHandler<HTMLElement>;
+      role: string;
+      title: string;
+    };
+    /** Props to spread on the tooltip container. */
+    tooltipProps: {
+      'aria-modal': boolean;
+      role: string;
+    };
+  }
+>;

package/src/types/events.ts

@@ -0,0 +1,89 @@
+import type { Actions, Events, Lifecycle, Origin, Status } from './common';
+import type { Controls } from './state';
+import type { StepMerged } from './step';
+import type { Simplify } from './utilities';
+
+/** The payload passed to the `onEvent` callback. Extends `TourData` with event-specific fields. */
+export type EventData = Simplify<
+  TourData & {
+    /**
+     * The error that occurred (only populated for ERROR events).
+     */
+    error: Error | null;
+    /**
+     * Scroll data (only populated for SCROLL_START/SCROLL_END events).
+     */
+    scroll: ScrollData | null;
+    /**
+     * Whether the tour is currently scrolling to a target.
+     */
+    scrolling: boolean;
+    /**
+     * The type of the event.
+     */
+    type: Events;
+    /**
+     * Whether the tour is blocked waiting for a before hook or target to appear.
+     */
+    waiting: boolean;
+  }
+>;
+
+/** Callback signature for the `onEvent` prop. */
+export type EventHandler = (data: EventData, controls: Controls) => void;
+
+/** Scroll position details for `scroll:start` and `scroll:end` events. */
+export type ScrollData = {
+  /**
+   * The scroll duration in milliseconds.
+   */
+  duration: number;
+  /**
+   * The element being scrolled.
+   */
+  element: Element;
+  /**
+   * The scroll position before scrolling.
+   */
+  initial: number;
+  /**
+   * The computed scroll destination.
+   */
+  target: number;
+};
+
+/** Base event payload with tour state at the time of the event. */
+export interface TourData {
+  /**
+   * The action that triggered the state update.
+   */
+  action: Actions;
+  /**
+   * Whether the tour is in `controlled` mode (using the `stepIndex` prop).
+   */
+  controlled: boolean;
+  /**
+   * The current step's index.
+   */
+  index: number;
+  /**
+   * The step's rendering phase.
+   */
+  lifecycle: Lifecycle;
+  /**
+   * The UI element that triggered the action (if available).
+   */
+  origin: Origin | null;
+  /**
+   * The total number of steps.
+   */
+  size: number;
+  /**
+   * The tour's current status.
+   */
+  status: Status;
+  /**
+   * The current step's data.
+   */
+  step: StepMerged;
+}

package/src/types/floating.ts

@@ -0,0 +1,60 @@
+import type {
+  AutoUpdateOptions,
+  FlipOptions,
+  Middleware,
+  MiddlewareData,
+  ShiftOptions,
+  Strategy,
+} from '@floating-ui/react-dom';
+
+import type { Placement } from './common';
+
+/** Tooltip and beacon positioning configuration using Floating UI. */
+export interface FloatingOptions {
+  /**
+   * Options passed to autoUpdate (ancestorScroll, elementResize, animationFrame, etc).
+   */
+  autoUpdate?: Partial<AutoUpdateOptions>;
+  /**
+   * Beacon positioning config.
+   */
+  beaconOptions?: { offset?: number };
+  /**
+   * Options for the flip middleware, or `false` to disable flipping.
+   * Defaults: crossAxis false, padding 20, smart fallbackPlacements for left/right.
+   */
+  flipOptions?: Partial<FlipOptions> | false;
+  /**
+   * Hide the arrow element.
+   * Centered placement already hides the arrow.
+   *
+   * @default false
+   */
+  hideArrow?: boolean;
+  /**
+   * Additional Floating UI middleware appended to defaults (offset, flip/autoPlacement, shift, arrow).
+   */
+  middleware?: Array<Middleware>;
+  /**
+   * Called after each position calculation.
+   */
+  onPosition?: (data: PositionData) => void;
+  /**
+   * Options for the shift middleware.
+   * Default: padding 10.
+   */
+  shiftOptions?: Partial<ShiftOptions>;
+  /**
+   * Positioning strategy.
+   * Defaults to 'fixed' when step.isFixed is true, 'absolute' otherwise.
+   */
+  strategy?: Strategy;
+}
+
+/** Computed position data returned by Floating UI after each calculation. */
+export interface PositionData {
+  middlewareData: MiddlewareData;
+  placement: Placement;
+  x: number;
+  y: number;
+}

package/src/types/index.ts

@@ -0,0 +1,8 @@
+export * from './common';
+export * from './components';
+export * from './events';
+export * from './floating';
+export * from './props';
+export * from './state';
+export * from './step';
+export * from './utilities';

package/src/types/props.ts

@@ -0,0 +1,124 @@
+import type { ElementType, ReactElement } from 'react';
+
+import type {
+  ArrowRenderProps,
+  BeaconRenderProps,
+  LoaderRenderProps,
+  TooltipRenderProps,
+} from '~/types/components';
+import type { FloatingOptions } from '~/types/floating';
+
+import type { Events, FailureReason, Locale, Options, Styles } from './common';
+import type { EventHandler } from './events';
+import type { Controls, State } from './state';
+import type { SelectorOrElement, Step, StepMerged } from './step';
+import type { PartialDeep, Simplify } from './utilities';
+
+export type Props = Simplify<
+  SharedProps & {
+    /**
+     * The tour is played sequentially with the Next button.
+     * @default false
+     */
+    continuous?: boolean;
+    /**
+     * Log Joyride's actions to the console.
+     * @default false
+     */
+    debug?: boolean;
+    /**
+     * The initial step index for uncontrolled tours.
+     * Ignored when stepIndex is set (controlled mode).
+     * @default 0
+     */
+    initialStepIndex?: number;
+    /**
+     * A nonce value for inline styles (Content Security Policy).
+     */
+    nonce?: string;
+    /**
+     * A function called when Joyride fires an event.
+     */
+    onEvent?: EventHandler;
+    /**
+     * Default options for all steps.
+     */
+    options?: Partial<Options>;
+    /**
+     * Render all Joyride components inside a specific element.
+     */
+    portalElement?: SelectorOrElement;
+    /**
+     * Run/stop the tour.
+     * @default false
+     */
+    run?: boolean;
+    /**
+     * 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 `onEvent`.
+     */
+    stepIndex?: number;
+    /**
+     * The tour's steps.
+     */
+    steps: Array<Step>;
+  }
+>;
+/** Shared configuration inherited by both `Props` and `Step`. */
+export type SharedProps = {
+  /**
+   * Custom Arrow component.
+   */
+  arrowComponent?: ElementType<ArrowRenderProps>;
+  /**
+   * Custom Beacon component.
+   */
+  beaconComponent?: ElementType<BeaconRenderProps>;
+  /**
+   * Options for the floating tooltip positioning.
+   */
+  floatingOptions?: Partial<FloatingOptions>;
+  /**
+   * Custom Loader component. Set to `null` to disable.
+   */
+  loaderComponent?: ElementType<LoaderRenderProps> | null;
+  /**
+   * The strings used in the tooltip.
+   */
+  locale?: Locale;
+  /**
+   * Override the styling of the Tooltip.
+   */
+  styles?: PartialDeep<Styles>;
+  /**
+   * Custom Tooltip component.
+   */
+  tooltipComponent?: ElementType<TooltipRenderProps>;
+};
+
+/** Return value of the `useJoyride` hook. */
+export type UseJoyrideReturn = {
+  /** Methods to programmatically control the tour. */
+  controls: Controls;
+  /** Steps that failed during the current tour run (target not found, before hook errors). Clears on start/reset. */
+  failures: StepFailure[];
+  /** Subscribe to a specific event type. Returns an unsubscribe function. */
+  on: (eventType: Events, handler: EventHandler) => () => void;
+  /** The current tour state. */
+  state: State;
+  /** The current merged step, or null if no step is active. */
+  step: StepMerged | null;
+  /** The tour React element to render. */
+  Tour: ReactElement | null;
+};
+
+/** A step that failed during the tour. */
+export interface StepFailure {
+  reason: FailureReason;
+  step: StepMerged;
+}