{"_id":"@dezignerblake/tour","_rev":"7-b0bfaf63e4b71f3c079768a7976bd7cf","name":"@dezignerblake/tour","dist-tags":{"latest":"3.8.6"},"versions":{"3.8.0":{"name":"@dezignerblake/tour","version":"3.8.0","keywords":["react","tour","intro","guide","introduction","step-by-step","guide","walkthrough","joyride","tourist-guide","product-intro","presentation"],"license":"MIT","_id":"@dezignerblake/tour@3.8.0","maintainers":[{"name":"blake9201","email":"blakewatkin@hotmail.com"}],"homepage":"https://github.com/DezignerBlake/reactour/tree/main/packages/tour","bugs":{"url":"https://github.com/DezignerBlake/reactour/issues"},"dist":{"shasum":"0f00fd0c93b847e9fc8685b749809add29a7f8d5","tarball":"https://registry.npmjs.org/@dezignerblake/tour/-/tour-3.8.0.tgz","fileCount":8,"integrity":"sha512-HP3MriEKeJotVKu5/yXxZcla48xqIw5ZhsycHZWlrGJ91DyuOuK3AXpiPuVB783OjnJv/ZtfpAHktWfelybpcg==","signatures":[{"sig":"MEYCIQDaynk7jakG6Rjxj/Qnsqd6N+MaBBRC6e7jTUw2cSj8OgIhAJzZFp8umXPibsFXYEYIh3xbHz8iO2UTZDPxmUL9gZt0","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":108548},"main":"./dist/index.js","types":"./dist/index.d.ts","module":"./dist/index.mjs","gitHead":"871602529ee3ca7a7850198564dc48fd516fd62a","scripts":{"dev":"tsup index.tsx --format esm,cjs --watch --dts --external react","lint":"TIMING=1 eslint **/*.ts* --fix","build":"tsup index.tsx --format esm,cjs --dts --external react","clean":"rm -rf .turbo && rm -rf node_modules && rm -rf dist"},"_npmUser":{"name":"blake9201","email":"blakewatkin@hotmail.com"},"repository":{"url":"git+https://github.com/DezignerBlake/reactour.git","type":"git","directory":"packages/tour"},"_npmVersion":"11.3.0","description":"

\"Reactour\"

\"Reactour\"

\"Reactour\"

\"Reactour\"

\"Reactour\"

\"Reactour\"

\"Reactour\"

\"Reactour\"

\n\n \"Reactour\"\n

\n

\n Tourist Guide into your React Components\n

\n\n## Documentation\n\n[https://docs.reactour.dev](https://docs.reactour.dev/tour/quickstart)\n\n> This documentation is for the latest release, which uses [npm scoped package](https://docs.npmjs.com/cli/v7/using-npm/scope) `@reactour`. The original `reactour` is now on branch `v1` and its documentation can be found [here](https://github.com/DezignerBlake/reactour/tree/v1).\n\n## Install\n\n```zsh\nnpm i -S @dezignerblake/tour\n# or\nyarn add @dezignerblake/tour\n```\n\n## Usage\n\nAdd the `TourProvider` at the root of your Application, passing the `steps` of the elements to highlight during the _Tour_.\n\n```js\n// ...\nimport { TourProvider } from '@dezignerblake/tour'\n\nReactDOM.render(\n \n \n ,\n document.getElementById('root')\n)\n\nconst steps = [\n {\n selector: '.first-step',\n content: 'This is my first Step',\n },\n // ...\n]\n```\n\nThen somewhere down the Application tree, control the Tour using `useTour` hook.\n\n```js\nimport { useTour } from '@dezignerblake/tour'\n\nfunction App() {\n const { setIsOpen } = useTour()\n return (\n <>\n

\n Lorem ipsum dolor sit amet, consectetur adipiscing elit. Praesent at\n finibus nulla, quis varius justo. Vestibulum lorem lorem, viverra porta\n metus nec, porta luctus orci\n

\n \n \n )\n}\n```\n\n## Examples\n\n#### Playground\n\nThe [Playground](https://github.com/DezignerBlake/reactour/tree/main/packages/playground) is the perfect place to play aroud with all `@reactour` _Components_. [Here](https://reactour.vercel.app) is an online version.\n\n#### Sandboxes\n\n- [Using React Router](https://codesandbox.io/s/reactour-tour-demo-using-react-router-dom-kujql)\n- [Using React Router with automatic route switching](https://codesandbox.io/s/tour-demo-using-react-router-dom-with-automatic-route-switching-fhdnxb?file=/src/App.js)\n- [Using React Modal](https://codesandbox.io/s/reactour-tour-demo-using-react-modal-8v0eo)\n- [Using Semantic UI Modal](https://codesandbox.io/s/reactour-tour-demo-using-semantic-ui-modal-xmqee)\n- [Using React Bootstrap Modal](https://codesandbox.io/s/reactour-tour-demo-using-react-bootstrap-modal-qjws4)\n- [Tour with data fetching](https://codesandbox.io/s/tour-with-data-fetching-dv2q0?file=/src/index.js)\n\n[![Edit @dezignerblake/tour Demo Template](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/reactour-tour-demo-template-fglzv?fontsize=14&hidenavigation=1&theme=dark)\n\n> Feel free to make a PR proposing new sandboxes or demos to add in the playground.\n\n## `TourProvider`\n\n### `steps?: StepType[]`\n\nArray of elements to highlight with special info and props.\n\n
\n StepType\n \n #### `selector: string | Element`\n\nA string containing one [CSS Selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors) to match and highlight the element at the time of this step.\n\n#### `content: string | ({ setCurrentStep, transition, isHighlightingObserved, currentStep, setIsOpen }) => void`\n\nThe content to show inside the _Popover_ at the time of this step. Using a `function` have parameters to use inside content.\n\n#### `position?: 'top' | 'right' | 'bottom' | 'left' | 'center' | [number, number]`\n\nThe preferred postion to position the _Popover_ in relation with the highlighted element. Will be automatically calculated in case of unavailable space.\n\n#### `highlightedSelectors?: string[]`\n\nArray of [CSS Selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors) to be included (by union) in the highlighted region of the _Mask_.\n\n#### `mutationObservables?: string[]`\n\nArray of [CSS Selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors) that addition or removal will triggered a rerender of the _Mask_ shape.\n\n#### `resizeObservables?: string[]`\n\nArray of [CSS Selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors) that when resizeing each will triggered a rerender of the _Mask_ shape.\n\n#### `navDotAriaLabel?: string`\n\nString to assign to `aria-label` attribute of the _Dot_ of this step.\n\n#### `stepInteraction?: boolean`\n\nAllow to reenable the interaction for this specific step, when `disableInteraction` (from _TourProvider_) is `true`.\n\n#### `action?: (elem: Element | null) => void`\n\nAction fired when the _Tour_ arrives in this step.\n\n#### `actionAfter?: (elem: Element | null) => void`\n\nAction fired when the _Tour_ leaves this step.\n\n#### `disableActions?: boolean`\n\nAllow to disable all possible actions (interaction with _Mask_, _Navigation Arrows_, _Navigation Dots_, _Close_ button and keyboard events) when the _Tour_ is in this step.\n\n#### `padding?: Padding`\n\nControl padding spaces for this specific step.\n\n#### `bypassElem?: boolean`\n\nExcludes the main `selector` when calculating highlited area if present `highlightedSelectors`.\n\n#### `styles?: StylesObj & PopoverStylesObj & MaskStylesObj`\n\nCustomize styles fro this specific step.\n\n
\n\n### `components?: PopoverComponentsType`\n\nProp to customize granurally each Component inside the _Popover_.\n\n#### Components available\n\n| key | props |\n| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `Badge` | `styles` |\n| `Close` | `styles`, `onClick`, `disabled` |\n| `Content` | `content`,`setCurrentStep`,`transition`, `isHighlightingObserved`,`currentStep`,`setIsOpen` |\n| `Navigation` | `styles`,`setCurrentStep`, `steps`, `currentStep`, `disableDots`, `nextButton`, `prevButton`, `setIsOpen`, `hideButtons`, `hideDots`, `disableAll`, `rtl`, `Arrow`, |\n| `Arrow` | `styles`, `inverted`, `disabled` |\n\n
\n Example\n\n```js\nimport { components } from '@dezignerblake/tour'\n\nfunction Badge({ children }) {\n return (\n ({ ...base, backgroundColor: 'red' }) }}\n >\n 👉 {children} 👈\n \n )\n}\n\nfunction Close({ onClick }) {\n return (\n \n x\n \n )\n}\n\nconst steps = [\n /* ... */\n]\n\nexport default function App() {\n return (\n \n {/* ... */}\n \n )\n}\n```\n\n
\n\n### `styles?: StylesObj & PopoverStylesObj & MaskStylesObj`\n\nProp to customize styles for the different parts of the _Mask_, _Popover_ and _Tour_ using a function that allows to extend the base styles an take advantage of some state props.\n\n#### Style keys and props available\n\nRefer to [Mask docs](https://github.com/DezignerBlake/reactour/tree/main/packages/mask) and [Popover docs](https://github.com/DezignerBlake/reactour/tree/main/packages/popover) for its specific Components\n\n##### Tour Components\n\n| key | props |\n| ---------- | ----------------------------------- |\n| `badge` | |\n| `controls` | |\n| `button` | `disabled` |\n| `arrow` | `disabled` |\n| `dot` | `current`, `disabled`, `showNumber` |\n| `close` | `disabled` |\n\n
\n Example\n\n```js\nconst styles = {\n maskWrapper: (base) => ({\n ...base,\n color: 'red',\n }),\n highlightedArea: (base, { x, y }) => ({\n ...base,\n x: x + 10,\n y: y + 10,\n }),\n badge: (base) => ({ ...base, color: 'blue' }),\n}\n```\n\n
\n\n### `padding?: Padding`\n\n
\n Type details\n\n```ts\ntype Padding =\n | number\n | {\n mask?: ComponentPadding\n popover?: ComponentPadding\n wrapper?: ComponentPadding\n }\n\n// x and y same value or [x, y] or [top, x, bottom] or [top, right, bottom, left]\ntype ComponentPadding = number | number[]\n```\n\n
\n\nExtra space to add between the _Mask_ and the _Popover_ and the highlighted element. A single number coordinates both spaces. Otherwise, passing an `Object` specifying the Component space.\n\n### `position?: Position`\n\n
\n Type details\n\n```ts\ntype Position =\n | 'top'\n | 'right'\n | 'bottom'\n | 'left'\n | 'center'\n | [number, number]\n | ((postionsProps: PositionProps) => Position)\n\ntype PositionProps = {\n bottom: number\n height: number\n left: number\n right: number\n top: number\n width: number\n windowWidth: number\n windowHeight: number\n}\n```\n\n
\n\nSet a global position for the _Popover_ in all steps, fixed in case of `[number, number]`, calculated in case of position `string`\n\n### `setCurrentStep: Dispatch>`\n\nFunction to control the _Tour_ current step state.\n\n### `currentStep: number`\n\nCustom _Tour_ current `step` state.\n\nThis option could be overrided on specific steps using [`stepInteraction`](#stepinteraction-boolean) prop.\n\n### `disableInteraction?: boolean | ((clickProps: Pick) => boolean)`\n\nDisables the ability to click or interact in any way with the Highlighted element on every step.\n\nThis option could be overrided on specific steps using [`stepInteraction`](#stepinteraction-boolean) prop.\n\n### `disableFocusLock?: boolean`\n\nThe _Tour_ uses [FocusScope](https://react-spectrum.adobe.com/react-aria/FocusScope.html) in order to lock the `focus` iteration inside the _Popover_ when _Tour_ is active. This prop allows to disable this behaviour.\n\n### `disableDotsNavigation?: boolean`\n\nDisable interactivity with _Dot_ navigation inside _Popover_.\n\n### `disableWhenSelectorFalsy?: boolean`\n\nIf true, don't show tours when `selector` or `document.getElementById(step.selector)` is falsy.\n\n### `disableKeyboardNavigation?: boolean | KeyboardParts[]`\n\n
\n Type details\n\n```ts\ntype KeyboardParts = 'esc' | 'left' | 'right'\n```\n\n
\n\nDisable all keyboard navigation events when `true`, disable only selected keys when array.\n\ndefault: `false`\n\n### `className?: string`\n\n[Class](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/class) assigned to _Popover_.\n\ndefault: `reactour__popover`\n\n### `maskClassName?: string`\n\n[Class](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/class) assigned to _Mask_.\n\ndefault: `reactour__mask`\n\n### `highlightedMaskClassName?: string`\n\n[Class](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/class) assigned to highlighted part of _Mask_. Useful when using [`disableInteraction`](#disableinteraction-boolean).\n\n### `nextButton?: (props: BtnFnProps) => void`\n\n### `prevButton?: (props: BtnFnProps) => void`\n\n
\n Type details\n\n```ts\ntype BtnFnProps = {\n Button: React.FC\n setCurrentStep: Dispatch>\n stepsLength: number\n currentStep: number\n setIsOpen: Dispatch>\n}\n\ntype NavButtonProps = {\n onClick?: () => void\n kind?: 'next' | 'prev'\n hideArrow?: boolean\n}\n```\n\n
\n\nHelper functions to customize the _Next_ and _Prev_ buttons inside _Popover_, with useful parameters. It is possible to use the base `Button` and customize the props.\n\n### `afterOpen?: (target: Element | null) => void`\n\nAction fired just after the _Tour_ is open.\n\n### `beforeClose?: (target: Element | null) => void`\n\nAction fired just before the _Tour_ is closed.\n\n### `onClickMask?: (clickProps: ClickProps) => void`\n\n
\n Type details\n\n```ts\ntype ClickProps = {\n setIsOpen: Dispatch>\n setCurrentStep: Dispatch>\n setSteps: Dispatch>\n setMeta: Dispatch>\n currentStep: number\n steps: StepType[]\n meta: string\n}\n```\n\n
\n\nFunction that overrides the default close behavior of the _Mask_ click handler. Comes with useful parameters to play with.\n\n### `onClickClose?: (clickProps: ClickProps) => void`\n\n
\n Type details\n\n```ts\ntype ClickProps = {\n setIsOpen: Dispatch>\n setCurrentStep: Dispatch>\n setSteps: Dispatch>\n setMeta: Dispatch>\n currentStep: number\n steps: StepType[]\n meta: string\n}\n```\n\n
\n\nFunction that overrides the default close behavior of the _Close icon_ click handler. Comes with useful parameters to play with.\n\n### `onClickHighlighted?: (e: MouseEventHandler, clickProps: ClickProps) => void`\n\nClick handler for highlighted area. Only works when `disableInteraction` is active. Useful in case is needed to avoid `onClickMask` when clicking the highlighted element.\n\n
\n Example\n\n```jsx\n {\n console.log('No interaction at all')\n if (clickProps.currentStep < 2) {\n e.stopPropagation()\n event.preventDefault()\n clickProps.setCurrentStep(\n Math.min(clickProps.currentStep + 1, clickProps.steps.length - 1)\n )\n }\n }}\n>\n {/* ... */}\n\n```\n\n
\n\n
\n Type details\n\n```ts\ntype ClickProps = {\n setIsOpen: Dispatch>\n setCurrentStep: Dispatch>\n setSteps: Dispatch>\n setMeta: Dispatch>\n currentStep: number\n steps: StepType[]\n meta: string\n}\n```\n\n
\n\n### `keyboardHandler?: KeyboardHandler`\n\nFunction to handle keyboard events in a custom way.\n\n
\n Type details\n\n```ts\ntype KeyboardHandler = {\n keyboardHandler?: (\n e: KeyboardEvent,\n clickProps?: ClickProps,\n status?: {\n isEscDisabled?: boolean\n isRightDisabled?: boolean\n isLeftDisabled?: boolean\n }\n ) => void\n}\n```\n\n
\n\n
\n Example\n\n```jsx\n {\n if (e.key === 'ArrowRight') {\n clickProps.setCurrentStep(\n Math.min(clickProps.currentStep + 1, clickProps.steps.length - 1)\n )\n }\n if (e.key === 'ArrowLeft') {\n clickProps.setCurrentStep(Math.max(clickProps.currentStep - 1, 0))\n }\n if (e.key === 'Escape') {\n const nextStep = Math.floor(Math.random() * clickProps.steps.length)\n clickProps.setCurrentStep(nextStep)\n }\n }}\n>\n {/* ... */}\n\n```\n\n
\n\n### `badgeContent?: (badgeProps: BadgeProps) => any`\n\n
\n Type details\n\n```ts\ntype BadgeProps = {\n totalSteps: number\n currentStep: number\n transition: boolean\n}\n```\n\n
\n\nFunction to customize the content of the _Badge_ using helper parameters like the current and total steps and if the _Tour_ is transitioning between steps.\n\n### `showNavigation?: boolean`\n\nShow or hide the _Navigation_ (_Prev_ and _Next_ buttons and _Dots_) inside _Popover_.\n\n### `showPrevNextButtons?: boolean`\n\nShow or hide _Prev_ and _Next_ buttons inside _Popover_.\n\n### `showCloseButton?: boolean`\n\nShow or hide the _Close_ button inside _Popover_.\n\n### `showBadge?: boolean`\n\nShow or hide the _Badge_ inside _Popover_.\n\n### `showDots?: boolean`\n\nShow or hide _dots_ navigation inside _Popover_.\n\n### `scrollSmooth?: boolean`\n\nActivate `smooth` scroll behavior when steps are outside viewport.\n\ndefault: `false`\n\n### `inViewThreshold?: { x?: number, y?: number } | number`\n\nTolerance in pixels to add when calculating if the step element is outside viewport to scroll into view.\n\n### `accessibilityOptions?: A11yOptions`\n\n
\n Type details\n\n```ts\ntype A11yOptions = {\n ariaLabelledBy: string\n closeButtonAriaLabel: string\n showNavigationScreenReaders: boolean\n}\n```\n\n
\n\nConfigure generic accessibility related attributes like [aria-labelledby](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-labelledby_attribute), [aria-label](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-label_attribute) for _Close_ button and if show or hide _Dot_ navigation in screen readers.\n\n### `rtl?: boolean`\n\nOption to navigate and show _Navigation_ in right-to-left mode\n\n### `maskId?: string`\n\nMask ID to pass directly into the [Mask component](https://github.com/DezignerBlake/reactour/tree/main/packages/mask#maskid-string)\n\n### `clipId?: string`\n\nClip ID to pass directly into the [Mask component](https://github.com/DezignerBlake/reactour/tree/main/packages/mask#clipid-string)\n\n### `onTransition?: PositionType`\n\nFunction to control the behavior of _Popover_ when is transitioning/scrolling from one step to another, calculating with _Popover_ next position and previous one\n\n
\n Type details\n\n```ts\ntype PositionType = (\n postionsProps: PositionProps,\n prev: RectResult\n) => 'top' | 'right' | 'bottom' | 'left' | 'center' | [number, number]\n```\n\n
\n\n### `ContentComponent?: ComponentType`\n\nCompletelly custom component to render inside the _Popover_.\n\n
\n Type details\n\n```ts\ntype PopoverContentProps = {\n styles?: StylesObj & PopoverStylesObj & MaskStylesObj\n badgeContent?: (badgeProps: BadgeProps) => any\n components?: PopoverComponentsType\n accessibilityOptions?: A11yOptions\n disabledActions?: boolean\n onClickClose?: (clickProps: ClickProps) => void\n setCurrentStep: Dispatch>\n currentStep: number\n transition?: boolean\n isHighlightingObserved?: boolean\n setIsOpen: Dispatch>\n steps: StepType[]\n showNavigation?: boolean\n showPrevNextButtons?: boolean\n showCloseButton?: boolean\n showBadge?: boolean\n nextButton?: (props: BtnFnProps) => void\n prevButton?: (props: BtnFnProps) => void\n disableDotsNavigation?: boolean\n rtl?: boolean\n}\n```\n\n
\n\n
\n Example\n\n```js\nfunction ContentComponent(props) {\n const isLastStep = props.currentStep === props.steps.length - 1\n const content = props.steps[props.currentStep].content\n return (\n
\n {/* Check if the step.content is a function or a string */}\n {typeof content === 'function'\n ? content({ ...props, someOtherStuff: 'Custom Text' })\n : content}\n {\n if (isLastStep) {\n props.setIsOpen(false)\n } else {\n props.setCurrentStep((s) => s + 1)\n }\n }}\n >\n {isLastStep ? 'x' : '>'}\n \n
\n )\n}\n\nconst steps = [\n /* ... */\n]\n\nfunction App() {\n return (\n ({ ...base, padding: 0 }) }}\n >\n {/* ... */}\n \n )\n}\n```\n\n
\n\n### `Wrapper?: ComponentType`\n\nElement which wraps the Tour, useful in case is needed to port the Tour into a [Portal](https://reactjs.org/docs/portals.html). Defaults to `React.Fragment`\n\n## `useTour`\n\nLater in any Component down in the tree of _TourProvider_ you can control the _Tour_ in many ways\n\n```jsx\nimport { useTour } from '@dezignerblake/tour'\n\nfunction MyComponent() {\n const { isOpen, currentStep, steps, setIsOpen, setCurrentStep, setSteps } = useTour()\n return (\n <>\n

{isOpen ? 'Welcome to the tour!' : 'Thank you for participate!'}

\n

\n Now you are visiting the place {currentStep + 1} of {steps.length}\n

\n \n \n )\n}\n```\n\n### `isOpen: boolean`\n\nIs the _Tour_ open or close\n\n### `currentStep: number`\n\nThe current step. **zero based**\n\n### `steps: StepType[]`\n\nThe `Array` of steps set currently\n\n### `setIsOpen: Dispatch>`\n\n`SetState` function open or close _Tour_\n\n### `setSteps: Dispatch>`\n\n`SetState` function to update the `Array` of steps.\n\n### `meta: string`\n\nGlobal meta information that could be useful in complex Tour/s situtations\n\n### `setMeta: Dispatch>`\n\n`SetState` function to update the global meta info.\n\n> **Warning**: Make sure you reset the `currentStep` value using the `setCurrentStep` function to ensure the tour will be opened to the correct step after update. Otherwise, in case where a person has already interacted with the tour steps and closed the tours on step 5 for example, they might open to the incorrect step, or similarly if the new set of steps only has 3 steps nothing will open.\n\n\n\n## `withTour`\n\nIn case you needed there is an enhancer that allows you to have all `useTour` functionalities through a Higher Order Component.\n\n```jsx\nimport { Component } from 'react'\nimport { withTour } from '@dezignerblake/tour'\n\nclass MyComponent extends Component {\n render() {\n return (\n <>\n \n
{/* ... */}
\n \n )\n }\n}\n\nexport default withTour(MyCompnent)\n```\n","readmeFilename":"README.md"}