Adding types and props per component in Docummentation

[alexisruiz96]

Hi! I've created a simple Readme that i think that can be useful in order to check the different props per component of the library. I attach here the md file in case you think it can help others and below you have the content of it😄

react_joyride_props_types.md

React Joyride Props and Types

Table of Contents

• Common Types
  • Actions
  • Events
  • Lifecycle
  • Origin
  • Status
  • AnyObject
  • NarrowPlainObject
  • Locale
  • Placement
  • Styles
  • StylesWithFloaterStyles
  • StylesOptions
• Component Props
  • BaseProps
  • BeaconProps
  • CallBackProps
  • OverlayProps
  • State
  • Props
  • Step
  • StepMerged
  • StepProps
  • StoreHelpers
  • StoreOptions
  • TooltipProps
  • TooltipRenderProps
  • Props

Common Types

Actions

• ValueOf<typeof ACTIONS>

export const ACTIONS = {
  INIT: 'init',
  START: 'start',
  STOP: 'stop',
  RESET: 'reset',
  PREV: 'prev',
  NEXT: 'next',
  GO: 'go',
  CLOSE: 'close',
  SKIP: 'skip',
  UPDATE: 'update',
} as const;

Events

• ValueOf<typeof EVENTS>

export const EVENTS = {
  TOUR_START: 'tour:start',
  STEP_BEFORE: 'step:before',
  BEACON: 'beacon',
  TOOLTIP: 'tooltip',
  STEP_AFTER: 'step:after',
  TOUR_END: 'tour:end',
  TOUR_STATUS: 'tour:status',
  TARGET_NOT_FOUND: 'error:target_not_found',
  ERROR: 'error',
} as const;

Lifecycle

• ValueOf<typeof LIFECYCLE>

export const LIFECYCLE = {
  INIT: 'init',
  READY: 'ready',
  BEACON: 'beacon',
  TOOLTIP: 'tooltip',
  COMPLETE: 'complete',
  ERROR: 'error',
} as const;

Origin

• ValueOf<typeof ORIGIN>

export const ORIGIN = {
  BUTTON_CLOSE: 'button_close',
  BUTTON_PRIMARY: 'button_primary',
  KEYBOARD: 'keyboard',
  OVERLAY: 'overlay',
} as const;

Status

• ValueOf<typeof STATUS>

export const STATUS = {
  IDLE: 'idle',
  READY: 'ready',
  WAITING: 'waiting',
  RUNNING: 'running',
  PAUSED: 'paused',
  SKIPPED: 'skipped',
  FINISHED: 'finished',
  ERROR: 'error',
} as const;

AnyObject

export type AnyObject<T = any> = Record<string, T>;

NarrowPlainObject

export type NarrowPlainObject<T extends Record<string, any>> = Exclude<
  T,
  Array<unknown> | Function | Map<unknown, unknown> | Set<unknown>
>;

Locale

export interface Locale {
  back?: ReactNode; // Label for the back button. Default: 'Back'
  close?: ReactNode; // Label for the close button. Default: 'Close'
  last?: ReactNode; // Label for the last button. Default: 'Last'
  next?: ReactNode; // Label for the next button. Default: 'Next'
  nextLabelWithProgress?: ReactNode; // Label with progress placeholders. Default: 'Next (Step {step} of {steps})'
  open?: ReactNode; // Label for the open button. Default: 'Open the dialog'
  skip?: ReactNode; // Label for the skip button. Default: 'Skip'
}

Placement

export type Placement =
  | 'top'
  | 'top-start'
  | 'top-end'
  | 'bottom'
  | 'bottom-start'
  | 'bottom-end'
  | 'left'
  | 'left-start'
  | 'left-end'
  | 'right'
  | 'right-start'
  | 'right-end';

Styles

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;
}

StylesWithFloaterStyles

export interface StylesWithFloaterStyles extends Styles {
  floaterStyles: FloaterStyles;
}

StylesOptions

export interface StylesOptions {
  arrowColor: string;
  backgroundColor: string;
  beaconSize: number;
  overlayColor: string;
  primaryColor: string;
  spotlightShadow: string;
  textColor: string;
  width?: string | number;
  zIndex: number;
}

Component Props

BaseProps

export type BaseProps = {
  beaconComponent?: ElementType<BeaconRenderProps>; // A React component to use instead the default Beacon.
  disableCloseOnEsc?: boolean; // Disable closing the tooltip on ESC. Default: false
  disableOverlay?: boolean; // Don't show the overlay. Default: false
  disableOverlayClose?: boolean; // Don't close the tooltip when clicking the overlay. Default: false
  disableScrollParentFix?: boolean; // Disable the fix to handle "unused" overflow parents. Default: false
  disableScrolling?: boolean; // Default: false
  floaterProps?: Partial<FloaterProps>; // Options to be passed to react-floater
  hideBackButton?: boolean; // Hide the Back button. Default: false
  hideCloseButton?: boolean; // Hide the Close button. Default: false
  locale?: Locale; // The strings used in the tooltip.
  showProgress?: boolean; // Default: false
  showSkipButton?: boolean; // Default: false
  spotlightClicks?: boolean; // Default: false
  spotlightPadding?: number; // The padding of the spotlight. Default: 10
  styles?: PartialDeep<Styles>; // Override the styling of the Tooltip
  tooltipComponent?: ElementType<TooltipRenderProps>; // A React component to use instead the default Tooltip.
};

BeaconProps

export type BeaconProps = Simplify<
  Pick<Props, 'beaconComponent' | 'nonce'> & BeaconRenderProps & {
    locale: Locale;
    onClickOrHover: MouseEventHandler<HTMLElement>;
    shouldFocus: boolean;
    styles: Styles;
  }
>;

BeaconRenderProps

export type BeaconRenderProps = {
continuous: boolean;
index: number;
isLastStep: boolean;
size: number;
step: StepMerged;
};

CallBackProps

export type CallBackProps = {
  action: Actions; // The action that updated the state.
  controlled: boolean; // If the tour is in `controlled` mode.
  index: number; // The current step's index
  lifecycle: Lifecycle; // The step's lifecycle.
  origin: Origin | null; // The element that triggered the action (if available).
  size: number; // The number of steps
  status: Status; // The tour's status.
  step: Step; // The current step's data.
  type: Events; // The type of the event.
};

OverlayProps

export type OverlayProps = Simplify<
    StepMerged & {
    continuous: boolean;
    debug: boolean;
    lifecycle: Lifecycle;
    onClickOverlay: () => void;
}
>;

State

export type State = {
    action: Actions;
    controlled: boolean;
    index: number;
    lifecycle: Lifecycle;
    origin: Origin | null;
    size: number;
    status: Status;
};

Props

export type Props = Simplify<
  BaseProps & {
    callback?: Callback; // A function to be called when Joyride's state changes.
    continuous?: boolean; // The tour is played sequentially with the Next button. Default: false
    debug?: boolean; // Log Joyride's actions to the console. Default: false
    getHelpers?: (helpers: StoreHelpers) => void; // Get the store methods to control the tour programmatically.
    nonce?: string; // A nonce value for inline styles.
    run?: boolean; // Run/stop the tour. Default: true
    scrollDuration?: number; // The duration for scroll to element. Default: 300
    scrollOffset?: number; // The scroll distance from the element scrollTop value. Default: 20
    scrollToFirstStep?: boolean; // Scroll the page for the first step. Default: false
    stepIndex?: number; // Setting a number here will turn Joyride into `controlled` mode.
    steps: Array<Step>; // The tour's steps.
  }
>;

Step

export type Step = Simplify<
  BaseProps & {
    content: ReactNode; // The tooltip's body.
    data?: any; // Additional data you can add to the step.
    disableBeacon?: boolean; // Don't show the Beacon before the tooltip. Default: false
    event?: 'click' | 'hover'; // The event to trigger the beacon. Default: click
    floaterProps?: FloaterProps; // Options to be passed to react-floater
    hideFooter?: boolean; // Hide the tooltip's footer. Default: false
    isFixed?: boolean; // Force the step to be fixed. Default: false
    offset?: number; // Default: 10
    placement?: Placement | 'auto' | 'center'; // The placement of the beacon and tooltip.
    placementBeacon?: Placement; // The placement of the beacon.
    target: string | HTMLElement; // The target for the step.
    title?: ReactNode; // The tooltip's title.
  }
>;

StepMerged

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;
}
>;

StepProps

export type StepProps = Simplify<
State & {
callback: Callback;
continuous: boolean;
debug: boolean;
helpers: StoreHelpers;
nonce?: string;
shouldScroll: boolean;
step: StepMerged;
store: StoreInstance;
}
>;

StoreHelpers

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;
};

StoreOptions

export type StoreOptions = Simplify<
Props & {
controlled: boolean;
}
>;

TooltipProps

export type TooltipProps = {
  continuous: boolean;
  helpers: StoreHelpers;
  index: number;
  isLastStep: boolean;
  setTooltipRef: RefCallback<HTMLElement>;
  size: number;
  step: StepMerged;
};

TooltipRenderProps

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;
    };
}
>;

Props

export type { Props as FloaterProps } from 'react-floater';

[gilbarbara]

Hey @alexisruiz96

Have you checked the docs?
Almost everything is covered there, including links to the source files for detailed information. Sure, it can be updated with more details, but adding too much information can make it harder to understand.

Maintaining a separate file with duplicate values can cause the information to be out of sync, defeating the initial purpose.

Thanks anyway.

[alexisruiz96]

Yes! I've checked it and it's a pretty nice docummentation so congrats on that.

I was developing something and I was lacking some information more in detail, so i thought it was a good idea to have everything accessible through an md file. But in conclusion, I agree with your arguments and that the best option is to keep it like it is right now.

Thanks for your response, nice job😄

[alexisruiz96]

Btw the info was in the docs because i've rechecked it now and I missed it😅