](http://godban.github.io/browsers-support-badges/)Edge | [
](http://godban.github.io/browsers-support-badges/)Firefox | [
](http://godban.github.io/browsers-support-badges/)Chrome | [
](http://godban.github.io/browsers-support-badges/)Safari |
| --------- | --------- | --------- | --------- |
| Edge| last 2 versions| last 2 versions| last 2 versions
# Shepherd
Shepherd makes it simple to create custom user on-boarding tours, trainings and announcements to drive user adoption.
Shepherd enables you to guide users through a custom tour or journey within your app or website. Highly customizable with minimal styles, Shepherd allows for powerful customization while being easy to use. Various frameworks supported including React, Ember, Angular, Vue.js, ES Modules, or plain JavaScript.
# Demo
See Shepherd Live on our website by clicking on the image:
# Using Shepherd
### Shepherd Open Source Library
The Shepherd Standalone Library has been open source since the very beginning. Check out our tutorials here:
#### [React Shepherd Wrapper](packages/react)
#### [Angular Shepherd Wrapper](https://github.com/shipshapecode/angular-shepherd)
#### [Vue Shepherd Wrapper](https://github.com/shipshapecode/vue-shepherd)
#### [Ember Shepherd Wrapper](https://github.com/RobbieTheWagner/ember-shepherd)
# White Glove Services
If you have an idea or project in mind and would like to engage our team to build a custom tour, training or on-boarding experience, [get in touch](mailto:ahoy@shipshape.io)!
## Resources
- [Website](https://shepherdjs.dev/)
- [Documentation](https://docs.shepherdjs.dev/)
- [Demo](https://shepherdjs.dev/)
- [Discord](https://discord.gg/EGcDW5NSud)
## Contributing
We encourage contributions of all kinds. If you would like to contribute in some way, please review our [guidelines for contributing](CONTRIBUTING.md).
Our release process is mostly automated. For more details, see [RELEASE.md](RELEASE.md).
## Projects Already Using Shepherd
### Rails gems
### [abraham](https://github.com/actmd/abraham)
Rails engine that generates and tracks Shepherd tours within an application
### Websites and Apps
### [SimplePlanner](https://simpleplanner.io)
[SimplePlanner](https://simpleplanner.io) uses Shepherd to help new users get familiar with its collaborative scheduling approach.
You do need to sign up via OAuth or email to see the scheduling tour.
Check out the [Envato Tuts+ Startup Series on its codebase](https://code.tutsplus.com/series/building-your-startup-with-php--cms-742) which describes how Simple Planner was built.
### [LogSeq](https://logseq.com/)
[LogSeq](https://logseq.com/) uses Shepherd to guide users through initial setup steps.
### [Snapsure](https://snapsure.app)
[Snapsure](https://snapsure.app) uses Shepherd to help photographers learn how to set up alerts for their desired picture-perfect weather conditions.
### [Drupal](https://www.drupal.org/docs/8/core/modules/tour/overview)
The [Drupal](https://www.drupal.org/docs/8/core/modules/tour/overview) CMS uses Shepherd to offer tours of it's core modules, and allows developers to add Tours to their custom and contributed modules.
### [Budibase Shepherd Tour Plugin](https://github.com/JayP718/tour_shepherd_bb_plugin)
[Budibase](https://budibase.com/) is an open source application which allows you develop low code applications rapidly and efficiently.This [Budibase](https://budibase.com/) Shepherd tour plugin allows you to create interative walkthroughs for your application.
### Your Project Here
If you have a cool open-source library built on Shepherd, PR this doc.
## License
Shepherd.js is dual-licensed under AGPL-3.0 and a Commercial License.
- **Free for open source and non-commercial use** under AGPL-3.0
- **Commercial license required** for commercial products and revenue-generating companies
See [LICENSE.md](LICENSE.md) for complete details or visit [shepherdjs.dev/pricing](https://shepherdjs.dev/pricing) to purchase a commercial license.
[](https://app.fossa.com/projects/git%2Bgithub.com%2Fshipshapecode%2Fshepherd?ref=badge_large)
================================================
FILE: RELEASE.md
================================================
# Release Process
Releases in this repo are mostly automated using [release-plan](https://github.com/embroider-build/release-plan/). Once you label all your PRs correctly (see below) you will have an automatically generated PR that updates your CHANGELOG.md file and a `.release-plan.json` that is used to prepare the release once the PR is merged.
## Preparation
Since the majority of the actual release process is automated, the remaining tasks before releasing are:
- correctly labeling **all** pull requests that have been merged since the last release
- updating pull request titles so they make sense to our users
Some great information on why this is important can be found at [keepachangelog.com](https://keepachangelog.com/en/1.1.0/), but the overall
guiding principle here is that changelogs are for humans, not machines.
When reviewing merged PR's the labels to be used are:
- breaking - Used when the PR is considered a breaking change.
- enhancement - Used when the PR adds a new feature or enhancement.
- bug - Used when the PR fixes a bug included in a previous release.
- documentation - Used when the PR adds or updates documentation.
- internal - Internal changes or things that don't fit in any other category.
**Note:** `release-plan` requires that **all** PRs are labeled. If a PR doesn't fit in a category it's fine to label it as `internal`
## Release
Once the prep work is completed, the actual release is straight forward: you just need to merge the open [Plan Release](https://github.com/shipshapecode/shepherd/pulls?q=is%3Apr+is%3Aopen+%22Prepare+Release%22+in%3Atitle) PR
================================================
FILE: docs-src/.dockerignore
================================================
# build output
dist/
# generated types
.astro/
# dependencies
node_modules/
# logs
npm-debug.log*
yarn-debug.log*
yarn-error.log*
pnpm-debug.log*
# environment variables
.env
.env.production
# macOS-specific files
.DS_Store
================================================
FILE: docs-src/.gitignore
================================================
# build output
dist/
# generated types
.astro/
# dependencies
node_modules/
# generated api docs
src/content/docs/api/*
# logs
npm-debug.log*
yarn-debug.log*
yarn-error.log*
pnpm-debug.log*
# environment variables
.env
.env.production
# macOS-specific files
.DS_Store
================================================
FILE: docs-src/.vscode/extensions.json
================================================
{
"recommendations": ["astro-build.astro-vscode"],
"unwantedRecommendations": []
}
================================================
FILE: docs-src/.vscode/launch.json
================================================
{
"version": "0.2.0",
"configurations": [
{
"command": "./node_modules/.bin/astro dev",
"name": "Development server",
"request": "launch",
"type": "node-terminal"
}
]
}
================================================
FILE: docs-src/Dockerfile
================================================
# syntax = docker/dockerfile:1
# Adjust NODE_VERSION as desired
ARG NODE_VERSION=20.10.0
FROM node:${NODE_VERSION}-slim as base
LABEL fly_launch_runtime="Astro"
# Astro app lives here
WORKDIR /app
# Set production environment
ENV NODE_ENV="production"
# Install pnpm
ARG PNPM_VERSION=9.2.0
RUN npm install -g pnpm@$PNPM_VERSION
# Throw-away build stage to reduce size of final image
FROM base as build
# Install packages needed to build node modules
RUN apt-get update -qq && \
apt-get install --no-install-recommends -y build-essential node-gyp pkg-config python-is-python3
# Install node modules
COPY --link package.json pnpm-lock.yaml pnpm-workspace.yaml ./
# Copy library code
COPY --link ./shepherd.js ./shepherd.js
# Copy application code
COPY --link ./docs-src ./docs-src
RUN pnpm install --frozen-lockfile --prod=false
# Build application
RUN pnpm -F shepherd-docs run build
# Remove development dependencies
RUN pnpm prune --prod
# Final stage for app image
FROM nginx
# Copy built application
COPY --from=build /app/docs-src/dist /usr/share/nginx/html
# Start the server by default, this can be overwritten at runtime
EXPOSE 80
CMD [ "/usr/sbin/nginx", "-g", "daemon off;" ]
================================================
FILE: docs-src/README.md
================================================
# Starlight Starter Kit: Basics
[](https://starlight.astro.build)
```
npm create astro@latest -- --template starlight
```
[](https://stackblitz.com/github/withastro/starlight/tree/main/examples/basics)
[](https://codesandbox.io/p/sandbox/github/withastro/starlight/tree/main/examples/basics)
[](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fwithastro%2Fstarlight%2Ftree%2Fmain%2Fexamples%2Fbasics&project-name=my-starlight-docs&repository-name=my-starlight-docs)
> 🧑🚀 **Seasoned astronaut?** Delete this file. Have fun!
## 🚀 Project Structure
Inside of your Astro + Starlight project, you'll see the following folders and files:
```
.
├── public/
├── src/
│ ├── assets/
│ ├── content/
│ │ ├── docs/
│ │ └── config.ts
│ └── env.d.ts
├── astro.config.mjs
├── package.json
└── tsconfig.json
```
Starlight looks for `.md` or `.mdx` files in the `src/content/docs/` directory. Each file is exposed as a route based on its file name.
Images can be added to `src/assets/` and embedded in Markdown with a relative link.
Static assets, like favicons, can be placed in the `public/` directory.
## 🧞 Commands
All commands are run from the root of the project, from a terminal:
| Command | Action |
| :------------------------ | :----------------------------------------------- |
| `npm install` | Installs dependencies |
| `npm run dev` | Starts local dev server at `localhost:4321` |
| `npm run build` | Build your production site to `./dist/` |
| `npm run preview` | Preview your build locally, before deploying |
| `npm run astro ...` | Run CLI commands like `astro add`, `astro check` |
| `npm run astro -- --help` | Get help using the Astro CLI |
## 👀 Want to learn more?
Check out [Starlight’s docs](https://starlight.astro.build/), read [the Astro documentation](https://docs.astro.build), or jump into the [Astro Discord server](https://astro.build/chat).
================================================
FILE: docs-src/astro.config.mjs
================================================
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
import starlightTypeDoc, { typeDocSidebarGroup } from 'starlight-typedoc';
// https://astro.build/config
export default defineConfig({
integrations: [
starlight({
title: 'Documentation',
description:
'Shepherd is a way for guiding users through your app to that moment of "aha!".',
logo: {
src: './src/assets/Shepherd-Lamb.svg'
},
favicon: '/favicon.ico',
social: [
{
icon: 'github',
label: 'GitHub',
href: 'https://github.com/shipshapecode/shepherd'
},
{
icon: 'discord',
label: 'Discord',
href: 'https://discord.gg/EGcDW5NSud'
}
],
components: {
// Override the default `Head` component.
Head: './src/components/HeadWithPosthog.astro'
},
plugins: [
starlightTypeDoc({
entryPoints: ['./node_modules/shepherd.js/src/*.ts'],
tsconfig: './node_modules/shepherd.js/tsconfig.json',
typeDoc: {
entryPointStrategy: 'expand',
includeVersion: true
}
})
],
sidebar: [
{
label: 'Guides',
items: [
{
label: 'Install',
link: '/guides/install/'
},
{
label: 'Styling',
link: '/guides/styling/'
},
{
label: 'Usage',
link: '/guides/usage/'
},
{
label: 'License & Pricing',
link: '/guides/license/'
}
]
},
{
label: 'Recipes',
items: [
{
label: 'Cookbook',
link: '/recipes/cookbook/'
},
{
label: 'Analytics',
link: '/guides/analytics/'
},
{
label: 'React',
link: '/recipes/react/'
}
]
},
// {
// label: 'Reference',
// autogenerate: {
// directory: 'reference'
// }
// },
typeDocSidebarGroup
]
})
]
});
================================================
FILE: docs-src/fly.toml
================================================
# fly.toml app configuration file generated for shepherd-docs on 2024-04-23T14:17:39-07:00
#
# See https://fly.io/docs/reference/configuration/ for information about how to use this file.
#
app = 'shepherd-docs'
primary_region = 'dfw'
[build]
[http_service]
internal_port = 80
force_https = true
auto_stop_machines = true
auto_start_machines = true
min_machines_running = 0
processes = ['app']
[[vm]]
memory = '1gb'
cpu_kind = 'shared'
cpus = 1
================================================
FILE: docs-src/package.json
================================================
{
"name": "shepherd-docs",
"type": "module",
"version": "0.0.6",
"private": "true",
"scripts": {
"dev": "astro dev",
"start": "astro dev",
"build": "astro check && astro build",
"preview": "astro preview",
"astro": "astro"
},
"dependencies": {
"@astrojs/starlight": "^0.37.6",
"astro": "^5.18.0",
"shepherd.js": "workspace:*",
"starlight-typedoc": "^0.21.5"
},
"devDependencies": {
"@astrojs/check": "^0.9.8",
"@flydotio/dockerfile": "^0.7.10",
"sharp": "^0.34.5",
"typedoc": "^0.28.17",
"typedoc-plugin-markdown": "^4.10.0",
"typescript": "^5.9.3"
}
}
================================================
FILE: docs-src/src/components/HeadWithPosthog.astro
================================================
---
import type { Props } from '@astrojs/starlight/props';
import Default from '@astrojs/starlight/components/Head.astro';
import PostHog from './Posthog.astro';
---
.example-css-selector element.',
attachTo: {
element: '.example-css-selector',
on: 'bottom'
},
classes: 'example-step-extra-class',
buttons: [
{
text: 'Next',
action: tour.next
}
]
});
```
Finally, to start the tour, just call `start` on your `Tour` instance:
```javascript
tour.start();
```
If you need to remove a step from your tour, call `removeStep` on your `Tour`
instance. If the step currently being displayed is the one you're removing, and
there are steps left in the tour, then the first one will be shown, otherwise,
the tour will be cancelled.
```javascript
tour.removeStep('example-step');
```
### API
#### Global Shepherd Object
Shepherd exposes a single object onto the window, `Shepherd`.
That global object fires several events to let you link up actions with events
occurring in _any_ tour:
##### Methods
- `Shepherd.on(eventName, handler, [context])`: Bind an event
- `Shepherd.off(eventName, [handler])`: Unbind an event
- `Shepherd.once(eventName, handler, [context])`: Bind just the next instance of
an event
##### Events
The global Shepherd fires the following events whenever a `Tour` instance fires
them. It adds to the object passed to the event handlers a `tour` key pointing
to the instance which fired the event:
- `complete`
- `cancel`
- `hide`
- `show`
- `start`
- `active`
- `inactive`
For multiple events, you can use something like:
```javascript
['complete', 'cancel'].forEach((event) =>
shepherd.on(event, () => {
// some code here
})
);
```
##### Current Tour
The global `Shepherd` includes a property which is always set to the currently
active tour, or null if there is no active tour:
- `Shepherd.activeTour`
#### Tour Instances
##### Creation
You create a `Tour` object for each tour you'd like to create.
Tour's constructor accepts a hash of options:
```javascript
const myTour = new Shepherd.Tour(options);
```
##### Tour Options
- `classPrefix`: The prefix to add to the `shepherd-enabled` and
`shepherd-target` class names as well as the `data-shepherd-step-id`.
- `confirmCancel`:
- If true, will issue a `window.confirm` before cancelling
- If it is a function(support Async Function), it will be called and wait for
the return value, and will only be cancelled if the value returned is true
- `confirmCancelMessage`: The message to display in the confirm dialog
- `defaultStepOptions`: Default options for Steps created through `addStep`
- `exitOnEsc`: Exiting the tour with the escape key will be enabled unless this
is explicitly set to `false`.
- `keyboardNavigation`: Navigating the tour via left and right arrow keys will
be enabled unless this is explicitly set to `false`.
- `stepsContainer` An optional container element for the steps. If not set, the
steps will be appended to `document.body`.
- `modalContainer` An optional container element for the modal. If not set, the
modal will be appended to `document.body`.
- `steps`: An array of step options objects or Step instances to initialize the
tour with.
- `tourName`: An optional "name" for the tour. This will be appended to the the
tour's dynamically generated `id` property.
- `useModalOverlay`: Whether or not steps should be placed above a darkened
modal overlay. If true, the overlay will create an opening around the target
element so that it can remain interactive.
##### Tour Methods
- `addStep(options)`: Creates a new Step object with options, and returns the
`Step` instance it created. If the options hash doesn't include an `id`, one
will be generated. You can also pass an existing `Step` instance rather than
`options`, but note that Shepherd does not support a Step being attached to
multiple Tours.
- `addSteps([Steps])`: Add multiple steps to the tour
- `getById(id)`: Return a step with a specific id
- `isActive()`: Check if the tour is active
- `next()`: Advance to the next step, in the order they were added
- `back()`: Show the previous step, in the order they were added
- `cancel()`: Trigger cancel on the current step, hiding it without advancing
- `complete()`: Calls \_done() triggering the `complete` event
- `hide()`: Hide the current step
- `show([id])`: Show the step specified by id (if it's a string), or index (if
it's a number) provided. Defaults to the first step.
- `start()`: Show the first step and begin the tour
- `getCurrentStep()`: Returns the currently shown step
- `removeStep(id)`: Removes the step from the tour
- `on(eventName, handler, [context])`: Bind an event
- `off(eventName, [handler])`: Unbind an event
- `once(eventName, handler, [context])`: Bind just the next instance of an event
##### Tour Events
- `complete`: Triggered when the last step is advanced
- `cancel`
- `hide`
- `show`: Triggered with a hash of the `step` and the `previous` step
- `start`
Steps are instances of the Step object. They are generally created by the
`Tour::addStep` method, which returns the `Step` instance it created.
#### Steps
##### Step Options
- `text`: The text in the body of the step. It can be one of three types:
- HTML string
- `HTMLElement` object
- `Function` to be executed when the step is built. It must return one the two
options above.
- `title`: The step's title. It becomes an `h3` at the top of the step.
- `attachTo`: The element the step should be attached to on the page. An object
with properties `element` and `on`.
- `element`: An element selector string, a DOM element, or a function
(returning a selector, a DOM element, `null` or `undefined`).
- `on`: The optional direction to place the Floating UI tooltip relative to
the element.
- Possible string values: 'auto', 'auto-start', 'auto-end', 'top',
'top-start', 'top-end', 'bottom', 'bottom-start', 'bottom-end', 'right',
'right-start', 'right-end', 'left', 'left-start', 'left-end'
```js
const new Step(tour, {
attachTo: { element: '.some .selector-path', on: 'left' },
...moreOptions
});
```
If you don’t specify an `attachTo` the element will appear in the middle of the
screen. The same will happen if your `attachTo.element` callback returns `null`,
`undefined`, or a selector that does not exist in the DOM.
If you omit the `on` portion of `attachTo`, the element will still be
highlighted, but the tooltip will appear in the middle of the screen, without an
arrow pointing to the target.
If the element to highlight does not yet exist while instantiating tour steps,
you may use lazy evaluation by supplying a function to `attachTo.element`. The
function will be called in the `before-show` phase.
- `beforeShowPromise`: A function that returns a promise. When the promise
resolves, the rest of the `show` code for the step will execute. For example:
```javascript
beforeShowPromise: function() {
return new Promise(function(resolve) {
$('#my-bootstrap-modal').on('shown.bs.modal', function () {
resolve();
});
});
},
```
- `canClickTarget` A boolean, that when set to false, will set
`pointer-events: none` on the target
- `cancelIcon` Options for the cancel icon
- `attrs` Additional HTML attributes to apply to the cancel icon button
element. This is useful for adding data attributes for testing or analytics.
Note: These attributes cannot override critical properties like `type`,
`onclick`, `class`, or `aria-label`.
```javascript
cancelIcon: {
enabled: true,
label: 'Close Tour',
attrs: {
'data-test': 'close-tour-button',
'data-analytics-id': 'tour-close'
}
}
```
- `enabled` Should a cancel "✕" be shown in the header of the step?
- `label` The label to add for `aria-label`
- `classes`: A string of extra classes to add to the step's content element.
- `buttons`: An array of buttons to add to the step. These will be rendered in a
footer below the main body text. Each button in the array is an object of the
format:
- `attrs`: Additional HTML attributes to apply to the button element. Useful
for adding data attributes for testing or analytics.
- `label`: The label to add for `aria-label`. It can also be a function that
returns a string (useful with i18n solutions).
- `disabled`: A boolean that controls the `disabled` attribute. It can also be
a function that returns a boolean.
- `classes`: Extra classes to apply to the ``
- `secondary`: A boolean, that when true, adds a `shepherd-button-secondary`
class to the button
- `text`: The HTML text of the button. It can also be a function that returns
a string (useful with i18n solutions).
- `action`: A function executed when the button is clicked on. It is
automatically bound to the `tour` the step is associated with, so things
like `this.next` will work inside the action. You can use action to skip
steps or navigate to specific steps, with something like:
```javascript
action() {
return this.show('some_step_name');
}
```
- `extraHighlights`: An array of extra element selectors to highlight when the
overlay is shown The tooltip won’t be fixed to these elements, but they will
be highlighted just like the attachTo element.
- `advanceOn`: An action on the page which should advance shepherd to the next
step. It should be an object with a string `selector` and an `event` name. For
example: `{selector: '.some-element', event: 'click'}`. It doesn't have to be
an event inside the tour, it can be any event fired on any element on the
page. You can also always manually advance the Tour by calling
`myTour.next()`.
- `highlightClass`: An extra class to apply to the `attachTo` element when it is
highlighted (that is, when its step is active). You can then target that
selector in your CSS.
- `id`: The string to use as the `id` for the step. If an id is not passed one
will be generated.
- `modalOverlayOpeningPadding`: An amount of padding to add around the modal
overlay opening
- `modalOverlayOpeningRadius`: An amount of border radius to add around the
modal overlay opening. It can be either a number or an object with properties
`{ topLeft, bottomLeft, bottomRight, topRight }`
- `floatingUIOptions`: Extra options to pass to
[Floating UI](https://floating-ui.com/docs/getting-started)
- `showOn`: A function that, when it returns true, will show the step. If it
returns false, the step will be skipped.
- `scrollTo`: Should the element be scrolled to when this step is shown? If
true, uses the default `scrollIntoView`, if an object, passes that object as
the params to `scrollIntoView` i.e. `{behavior: 'smooth', block: 'center'}`
- `scrollToHandler`: A function that lets you override the default `scrollTo`
behavior and define a custom action to do the scrolling, and possibly other
logic.
- `when`: You can define show, hide, etc events inside when. For example:
```javascript
when: {
show: function() {
window.scrollTo(0, 0);
}
}
```
##### Step Methods
- `show()`: Show this step
- `hide()`: Hide this step
- `cancel()`: Hide this step and trigger the `cancel` event
- `complete()`: Hide this step and trigger the `complete` event
- `scrollTo()`: Scroll to this step's element
- `isOpen()`: Returns true if the step is currently shown
- `destroy()`: Remove the element
- `on(eventName, handler, [context])`: Bind an event
- `off(eventName, [handler])`: Unbind an event
- `once(eventName, handler, [context])`: Bind just the next instance of an event
##### Step Events
- `before-show`
- `show`
- `before-hide`
- `hide`
- `complete`
- `cancel`
- `destroy`
Please note that `complete` and `cancel` are only ever triggered if you call the
associated methods in your code.
### Advancing on Actions
You can use the `advanceOn` option, or the Next button, to advance steps. If you
would like however to have a step advance on a complex user action, you can do
the following:
```javascript
const myStep = myTour.addStep(options);
yourApp.on('some-event', () => {
if (myStep.isOpen()) {
Shepherd.activeTour.next();
}
});
```
### 🔼 Displaying Arrows
By default, Shepherd will generate and position an "arrow" element that points
to the target of a step. This is done by setting the `arrow` option to `true` on
each ``Step.options` — but you can disable the arrow manually by setting
it to false:
```js
myTour.addStep({
id: 'Step 1',
arrow: false
});
```
You can also provide an options object, to configure the arrow's
[padding](https://floating-ui.com/docs/arrow#padding). The padding is the
closest the arrow will get to the edge of the step.
```js
myTour.addStep({
id: 'Step 1',
arrow: { padding: 10 }
});
```
Furthermore, while Shepherd provides some basic arrow styling, you can style it
as you wish by targeting the `.shepherd-arrow` element.
================================================
FILE: docs-src/src/content/docs/recipes/cookbook.md
================================================
---
title: Cookbook
---
### Disable Scroll
Previously, disabling scrolling was built into Shepherd, but it was buggy
and bulky, so we opted to remove [body-scroll-lock](https://github.com/willmcpo/body-scroll-lock)
as a dependency, in favor of users installing it directly in their apps. To disable scrolling,
you can install `body-scroll-lock` and run `bodyScrollLock.disableBodyScroll();` before
starting the tour, then `bodyScrollLock.clearAllBodyScrollLocks();` after stopping the tour.
### Highlighting multiple elements
Highlighting multiple elements is supported by Shepherd out of the box. You can pass an array of selectors to the `extraHighlights` option in the step configuration. This will highlight all the elements in the array as well as the target element defined in the `attachTo` option.
```javascript
const tour = new Shepherd.Tour({
steps: [
{
text: 'This is a step with multiple highlights',
attachTo: {
element: '.target-element',
on: 'bottom'
},
extraHighlights: ['.example-selector', '.example-selector-2']
}
]
});
```
If an element to be highlighted is contained by another element that is also being highlighted, the contained element will not be highlighted. This is to prevent the contained element from being obscured by the containing element.
### Offsets
By default, FloatingUI instances are placed directly next to their target. However, if you need to apply some margin
between them or if you need to fine tune the position according to some custom logic, you can use an offset middleware.
For example:
```js
import { offset } from '@floating-ui/dom';
const tour = new Shepherd.Tour({
steps: [
{
...
floatingUIOptions: {
middleware: [offset({ mainAxis: 0, crossAxis: 12 })]
}
...
}
]
});
```
### Progress Indicator
Using the already exposed API, you could add a progress indicator of your choosing
for each step to let your users know how far into a tour they may be.
The example below uses the [Step](https://docs.shepherdjs.dev/api/step/classes/step/) `options`
object and adds to `when` on the `show` event. Within that, we create an element
to render in the header with text of what step out of all potential steps is now
being show.
```javascript
when: {
show() {
const currentStep = Shepherd.activeTour?.getCurrentStep();
const currentStepElement = currentStep?.getElement();
const header = currentStepElement?.querySelector('.shepherd-header');
const progress = document.createElement('span');
progress.style['margin-right'] = '315px';
progress.innerText = `${Shepherd.activeTour?.steps.indexOf(currentStep) + 1}/${Shepherd.activeTour?.steps.length}`;
header?.insertBefore(progress, currentStepElement.querySelector('.shepherd-cancel-icon'));
}
}
```
Another example, for anyone who wants to add progress indicators to the footer. Add the `shepherd-progress` className and some extra styles.
```javascript
when: {
show() {
const currentStep = Shepherd.activeTour?.getCurrentStep();
const currentStepElement = currentStep?.getElement();
const footer = currentStepElement?.querySelector('.shepherd-footer');
const progress = document.createElement('span');
progress.className = 'shepherd-progress';
progress.innerText = `${Shepherd.activeTour?.steps.indexOf(currentStep) + 1} of ${Shepherd.activeTour?.steps.length}`;
footer?.insertBefore(progress, currentStepElement.querySelector('.shepherd-button:last-child'));
}
}
```
```scss
.shepherd-footer {
align-items: center;
border-bottom-left-radius: 5px;
border-bottom-right-radius: 5px;
display: flex;
justify-content: space-between;
padding: 0 0.75rem 0.75rem;
.shepherd-button:last-child {
margin-right: 0;
}
.shepherd-progress {
font-size: 0.8rem;
}
}
```
================================================
FILE: docs-src/src/content/docs/recipes/react.md
================================================
---
title: React Usage
---
## Use in React
We've published a React package for years that really just exports the default Shepherd class and gives you some syntactical sugar for setting up Shepherd in a React app. This adds another layer from the root API and provides opinionated patterns. It's mainly a wrapper around the Shepherd library that exposes the tour object and methods to the context object that can be passed into props for dynamic interactivity. We think there's more than one way to create solutions and instead just prefer to provide a couple of examples on how you can do this.
### Custom hooks pattern
You can just create a hook that will let you setup and share a Tour instance and swap them out as needed.
```javascript
export const useShepherdTour = ({ tourOptions, steps }) => {
const tourObject = useMemo(() => {
const tourInstance = new Shepherd.Tour(tourOptions);
tourInstance.addSteps(steps);
return tourInstance;
}, [tourOptions, steps]);
return tourObject;
};
```
### Context/Provider pattern
```javascript
// App imports above, this is either in a root App.js/ts file or somewhere in your app
const ShepherdTourContext = React.createContext();
const ShepherdTourContextConsumer = ShepherdTourContext.Consumer;
const shepherdTourInstance = new Shepherd.Tour();
return (
Shepherd has full keyboard navigation support, focus trapping, and a11y compliance via aria attributes.
Shepherd's styles are kept minimal, allowing you to easily customize the look and feel, but still give you enough to drop in and be ready to go quickly.
Shepherd is ready to drop into your application using React, Ember, Angular, Vue.js, ES Modules, or plain Javascript!
Shepherd remains open-source software, and this commitment is unwavering. Our library serves as a foundation for countless solo developers and esteemed organizations, empowering them to create their applications. With a thriving community of users, the ongoing enhancement and upkeep of the library, documentation, and community engagement demand significant resources. Your support is essential for us to continue this mission. So, if you want to use Shepherd.js in your commercial app, website or plugin, you would need to obtain a commercial license.
$50 /lifetime
Everything necessary to get started.
$300 /lifetime
Partner to use on all your products.
Request a Quote
Let us help you get the most out of Shepherd
const tour = new Shepherd.Tour({
defaultStepOptions: {
classes: 'shadow-md bg-purple-dark',
scrollTo: true
}
});
tour.addStep({
title: 'Example Shepherd',
text: 'Creating a Shepherd is easy too! Just create ...',
attachTo: {
element: '.hero-example',
on: 'bottom'
},
advanceOn: {
selector: '.docs-link',
event: 'click'
},
id: 'example'
});
tour.start();
const tour = new Shepherd.Tour({
defaultStepOptions: {
classes: 'shadow-md bg-purple-dark',
scrollTo: true
}
});
tour.addStep({
title: 'Example Shepherd',
text: 'Creating a Shepherd is easy too! Just create ...',
attachTo: {
element: '.hero-example',
on: 'bottom'
},
advanceOn: {
selector: '.docs-link',
event: 'click'
},
id: 'example'
});
tour.start();
const tour = new Shepherd.Tour({
defaultStepOptions: {
classes: 'shadow-md bg-purple-dark',
scrollTo: true
}
});
tour.addStep({
title: 'Example Shepherd',
text: 'Creating a Shepherd is easy too! Just create ...',
attachTo: {
element: '.hero-example',
on: 'bottom'
},
advanceOn: {
selector: '.docs-link',
event: 'click'
},
id: 'example'
});
tour.start();
Shepherd is a JavaScript library for guiding users through your app. It uses Floating UI, another open source library, to render dialogs for each tour "step".
Among many things, Floating UI makes sure your steps never end up off screen or cropped by an overflow. (Try resizing your browser to see what we mean.)
`, attachTo: { element: '.hero-welcome', on: 'bottom' }, classes: 'shepherd-step-element shepherd-transparent-text first-step', buttons: [ { action: shepherd.cancel, classes: 'shepherd-button-secondary cancel-button', text: 'Exit' }, { action: shepherd.next, classes: 'shepherd-button-example-primary next-button', text: 'Next' } ], id: 'welcome' }, { title: 'Including', text: 'Including Shepherd is easy! Just include shepherd.js. The styles are bundled with the JS.', attachTo: { element: '.hero-including', on: 'bottom' }, buttons: [ { action: shepherd.back, classes: 'shepherd-button-secondary back-button', text: 'Back' }, { action: shepherd.next, classes: 'shepherd-button-example-primary next-button', text: 'Next' } ], id: 'including', classes: 'shepherd-step-element second-step' }, { title: 'Example Shepherd', text: 'Creating a Shepherd is easy too! Just create Shepherd and add as many steps as you want. Check out the documentation to learn more.', attachTo: { element: '.hero-example', on: 'bottom' }, buttons: [ { action: shepherd.back, classes: 'shepherd-button-secondary back-button', text: 'Back' }, { action: shepherd.next, classes: 'shepherd-button-example-primary next-button', text: 'Next' } ], id: 'example', classes: 'shepherd-step-element third-step' }, { title: 'Learn more', text: 'Star Shepherd on Github so you remember it for your next project', attachTo: { element: '.hero-followup', on: 'left' }, buttons: [ { action: shepherd.back, classes: 'shepherd-button-secondary back-button', text: 'Back' }, { action: shepherd.next, classes: 'shepherd-button-example-primary next-button', text: 'Done' } ], id: 'followup', classes: 'shepherd-step-element fourth-step' } ]; } ================================================ FILE: shepherd.js/test/cypress/utils/setup-tour.js ================================================ import defaultSteps from './default-steps'; /** * Setup a tour * @param {Shepherd} Shepherd The Shepherd instance * @param {Object} globalDefaults A hash of the `defaultStepOptions` * @param {function} customSteps An array of the steps to add to the tour * @param {Object} otherOptions A hash of other options to pass to Shepherd */ export default function (Shepherd, globalDefaults, customSteps, otherOptions) { const defaultStepOptions = Object.assign( {}, { cancelIcon: { enabled: true } }, globalDefaults ); const shepherdOptions = Object.assign( {}, { defaultStepOptions }, otherOptions ); const shepherd = new Shepherd.Tour(shepherdOptions); const steps = typeof customSteps === 'function' ? customSteps(shepherd) : defaultSteps(shepherd); shepherd.addSteps(steps); return shepherd; } ================================================ FILE: shepherd.js/test/unit/babel.config.cjs ================================================ module.exports = function (api) { api.cache(true); return { env: { development: { presets: [ [ '@babel/preset-env', { loose: true } ] ] }, test: { presets: [ ['@babel/preset-env', { targets: { node: 'current' } }], ['@babel/preset-typescript', { allowDeclareFields: true }] ] } } }; }; ================================================ FILE: shepherd.js/test/unit/components/shepherd-button.spec.js ================================================ import { afterEach, beforeEach, describe, expect, it } from 'vitest'; import { createShepherdButton } from '../../../src/components/shepherd-button.ts'; describe('component/ShepherdButton', () => { let container; beforeEach(() => { container = document.createElement('div'); document.body.appendChild(container); }); afterEach(() => { container.remove(); }); describe('disabled', () => { it('should be enabled by default', () => { const button = createShepherdButton({}, undefined); container.appendChild(button); expect(button.disabled).toBeFalsy(); }); it('is enabled when false', () => { const button = createShepherdButton({ disabled: false }, undefined); container.appendChild(button); expect(button.disabled).toBeFalsy(); }); it('can be disabled with boolean', () => { const button = createShepherdButton({ disabled: true }, undefined); container.appendChild(button); expect(button.disabled).toBeTruthy(); }); it('can be disabled with function', () => { const button = createShepherdButton({ disabled: () => true }, undefined); container.appendChild(button); expect(button.disabled).toBeTruthy(); }); }); describe('label', () => { it('string', () => { const button = createShepherdButton({ label: 'Test' }, undefined); container.appendChild(button); expect(button).toHaveAttribute('aria-label', 'Test'); }); it('number', () => { const button = createShepherdButton({ label: 5 }, undefined); container.appendChild(button); expect(button).toHaveAttribute('aria-label', '5'); }); it('function', () => { const button = createShepherdButton({ label: () => 'Test' }, undefined); container.appendChild(button); expect(button).toHaveAttribute('aria-label', 'Test'); }); it('function re-creation uses updated value', () => { let label = 'Test'; const button = createShepherdButton({ label: () => label }, undefined); container.appendChild(button); expect(button).toHaveAttribute('aria-label', 'Test'); label = 'Test 2'; const buttonUpdated = createShepherdButton( { label: () => label }, undefined ); container.appendChild(buttonUpdated); expect(buttonUpdated).toHaveAttribute('aria-label', 'Test 2'); }); it('null', () => { const button = createShepherdButton({ label: null }, undefined); container.appendChild(button); expect(button).not.toHaveAttribute('aria-label'); }); it('undefined', () => { const button = createShepherdButton({}, undefined); container.appendChild(button); expect(button).not.toHaveAttribute('aria-label'); }); }); describe('text', () => { it('string', () => { const button = createShepherdButton({ text: 'Test' }, undefined); container.appendChild(button); expect(button).toHaveTextContent('Test'); }); it('function', () => { const button = createShepherdButton({ text: () => 'Test' }, undefined); container.appendChild(button); expect(button).toHaveTextContent('Test'); }); it('function re-creation uses updated value', () => { let text = 'Test'; const button = createShepherdButton({ text: () => text }, undefined); container.appendChild(button); expect(button).toHaveTextContent('Test'); text = 'Test 2'; const buttonUpdated = createShepherdButton( { text: () => text }, undefined ); container.appendChild(buttonUpdated); expect(buttonUpdated).toHaveTextContent('Test 2'); }); }); describe('attrs', () => { it('applies single data attribute', () => { const button = createShepherdButton( { attrs: { 'data-test': 'my-button' } }, undefined ); container.appendChild(button); expect(button).toHaveAttribute('data-test', 'my-button'); }); it('applies multiple custom attributes', () => { const button = createShepherdButton( { attrs: { 'data-test': 'my-button', 'data-step': '1', 'data-analytics': 'click-event', title: 'Click me' } }, undefined ); container.appendChild(button); expect(button).toHaveAttribute('data-test', 'my-button'); expect(button).toHaveAttribute('data-step', '1'); expect(button).toHaveAttribute('data-analytics', 'click-event'); expect(button).toHaveAttribute('title', 'Click me'); }); it('converts number and boolean values to strings', () => { const button = createShepherdButton( { attrs: { 'data-count': 42, 'data-enabled': true, 'data-rate': 3.14 } }, undefined ); container.appendChild(button); expect(button).toHaveAttribute('data-count', '42'); expect(button).toHaveAttribute('data-enabled', 'true'); expect(button).toHaveAttribute('data-rate', '3.14'); }); it('does not override core button attributes', () => { const mockAction = () => {}; const mockStep = { tour: {} }; const button = createShepherdButton( { text: 'Next', classes: 'my-class', disabled: true, label: 'Next Step', action: mockAction, attrs: { type: 'submit', // Should NOT override class: 'wrong-class', // Should NOT override disabled: false, // Should NOT override 'aria-label': 'Wrong Label', // Should NOT override tabindex: '5', // Should NOT override 'data-test': 'next-btn' // SHOULD apply } }, mockStep ); container.appendChild(button); // Core attributes should be protected expect(button).toHaveAttribute('type', 'button'); expect(button.className).toContain('shepherd-button'); expect(button.className).toContain('my-class'); expect(button.disabled).toBeTruthy(); expect(button).toHaveAttribute('aria-label', 'Next Step'); expect(button).toHaveAttribute('tabindex', '0'); // Non-conflicting custom attribute should work expect(button).toHaveAttribute('data-test', 'next-btn'); }); it('works with empty attrs object', () => { const button = createShepherdButton({ attrs: {} }, undefined); container.appendChild(button); expect(button).toBeInTheDocument(); expect(button).toHaveAttribute('type', 'button'); expect(button.className).toContain('shepherd-button'); }); it('works with undefined attrs', () => { const button = createShepherdButton({}, undefined); container.appendChild(button); expect(button).toBeInTheDocument(); expect(button).toHaveAttribute('type', 'button'); }); it('works alongside all other button properties', () => { const mockAction = () => {}; const mockStep = { tour: {} }; const button = createShepherdButton( { text: 'Next Step', label: 'Proceed forward', classes: 'custom-class', secondary: true, disabled: false, action: mockAction, attrs: { 'data-test': 'next-btn', 'data-step-id': '5', id: 'my-button-id' } }, mockStep ); container.appendChild(button); expect(button).toHaveTextContent('Next Step'); expect(button).toHaveAttribute('aria-label', 'Proceed forward'); expect(button.className).toContain('custom-class'); expect(button.className).toContain('shepherd-button-secondary'); expect(button.disabled).toBeFalsy(); expect(button).toHaveAttribute('data-test', 'next-btn'); expect(button).toHaveAttribute('data-step-id', '5'); expect(button).toHaveAttribute('id', 'my-button-id'); }); it('handles special characters in attribute values', () => { const button = createShepherdButton( { attrs: { 'data-text': 'Hello "World"', 'data-path': '/api/v1/test', 'data-symbol': '<>&' } }, undefined ); container.appendChild(button); expect(button).toHaveAttribute('data-text', 'Hello "World"'); expect(button).toHaveAttribute('data-path', '/api/v1/test'); expect(button).toHaveAttribute('data-symbol', '<>&'); }); }); }); ================================================ FILE: shepherd.js/test/unit/components/shepherd-content.spec.js ================================================ import { afterEach, beforeEach, describe, expect, it } from 'vitest'; import { createShepherdContent } from '../../../src/components/shepherd-content.ts'; describe('components/ShepherdContent', () => { let container; beforeEach(() => { container = document.createElement('div'); document.body.appendChild(container); }); afterEach(() => { container.remove(); }); describe('header', () => { it('is rendered when title is present and cancelIcon is enabled', () => { const step = { options: { title: 'I am some test title.', cancelIcon: { enabled: true } } }; const el = createShepherdContent('test-desc', 'test-label', step); container.appendChild(el); expect( container.querySelector('.shepherd-content .shepherd-header') ).toBeInTheDocument(); }); it('is rendered when title is present', () => { const step = { options: { title: 'I am some test title.' } }; const el = createShepherdContent('test-desc', 'test-label', step); container.appendChild(el); expect( container.querySelector('.shepherd-content .shepherd-header') ).toBeInTheDocument(); }); it('is rendered when cancelIcon is enabled', () => { const step = { options: { cancelIcon: { enabled: true } } }; const el = createShepherdContent('test-desc', 'test-label', step); container.appendChild(el); expect( container.querySelector('.shepherd-content .shepherd-header') ).toBeInTheDocument(); }); it('is not rendered when title is not present and cancelIcon is disabled', () => { const step = { options: { title: undefined } }; const el = createShepherdContent('test-desc', 'test-label', step); container.appendChild(el); expect( container.querySelector('.shepherd-header') ).not.toBeInTheDocument(); }); }); }); ================================================ FILE: shepherd.js/test/unit/components/shepherd-element.spec.js ================================================ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; import { createShepherdElement } from '../../../src/components/shepherd-element.ts'; import { Step } from '../../../src/step'; import { Tour } from '../../../src/tour'; function fireKeyDown(el, keyCode, opts = {}) { el.dispatchEvent( new KeyboardEvent('keydown', { keyCode, bubbles: true, ...opts }) ); } describe('components/ShepherdElement', () => { let container; beforeEach(() => { container = document.createElement('div'); document.body.appendChild(container); }); afterEach(() => { container.remove(); }); describe('arrow', () => { it('arrows shown by default', () => { const testElement = document.createElement('div'); const tour = new Tour(); const step = new Step(tour, { attachTo: { element: testElement, on: 'top' } }); const { element, cleanup } = createShepherdElement({ descriptionId: 'test-desc', labelId: 'test-label', step }); container.appendChild(element); expect( container.querySelectorAll('.shepherd-element .shepherd-arrow').length ).toBe(1); cleanup(); }); it('arrow: false hides arrows', () => { const testElement = document.createElement('div'); const tour = new Tour(); const step = new Step(tour, { arrow: false, attachTo: { element: testElement, on: 'top' } }); const { element, cleanup } = createShepherdElement({ descriptionId: 'test-desc', labelId: 'test-label', step }); container.appendChild(element); expect( container.querySelectorAll('.shepherd-element .shepherd-arrow').length ).toBe(0); cleanup(); }); it('arrow: object with padding shows arrow', () => { const testElement = document.createElement('div'); const tour = new Tour(); const step = new Step(tour, { arrow: { padding: 10 }, attachTo: { element: testElement, on: 'top' } }); const { element, cleanup } = createShepherdElement({ descriptionId: 'test-desc', labelId: 'test-label', step }); container.appendChild(element); expect( container.querySelectorAll('.shepherd-element .shepherd-arrow').length ).toBe(1); cleanup(); }); it('arrow: empty object shows arrow', () => { const testElement = document.createElement('div'); const tour = new Tour(); const step = new Step(tour, { arrow: {}, attachTo: { element: testElement, on: 'top' } }); const { element, cleanup } = createShepherdElement({ descriptionId: 'test-desc', labelId: 'test-label', step }); container.appendChild(element); expect( container.querySelectorAll('.shepherd-element .shepherd-arrow').length ).toBe(1); cleanup(); }); }); describe('handleKeyDown', () => { it('exitOnEsc: true - ESC cancels the tour', () => { const tour = new Tour(); const step = new Step(tour, {}); const stepCancelSpy = vi.spyOn(step, 'cancel'); const { element, cleanup } = createShepherdElement({ descriptionId: 'test-desc', labelId: 'test-label', step }); container.appendChild(element); fireKeyDown(element, 27); expect(stepCancelSpy).toHaveBeenCalled(); cleanup(); }); it('exitOnEsc: false - ESC does not cancel the tour', () => { const tour = new Tour({ exitOnEsc: false }); const step = new Step(tour, {}); const stepCancelSpy = vi.spyOn(step, 'cancel'); const { element, cleanup } = createShepherdElement({ descriptionId: 'test-desc', labelId: 'test-label', step }); container.appendChild(element); fireKeyDown(element, 27); expect(stepCancelSpy).not.toHaveBeenCalled(); cleanup(); }); it('keyboardNavigation: true - arrow keys move between steps', () => { const tour = new Tour(); const step = new Step(tour, {}); let propagateValue = 0; const tourBackStub = vi.spyOn(tour, 'back').mockImplementation(() => {}); const tourNextStub = vi.spyOn(tour, 'next').mockImplementation(() => {}); // Add a keystroke listener to a parent to test event propagation const propagateHandler = (event) => { if ([27, 37, 39].includes(event.keyCode)) { propagateValue += 1; } }; document.body.addEventListener('keydown', propagateHandler); expect(tourBackStub).not.toHaveBeenCalled(); expect(tourNextStub).not.toHaveBeenCalled(); const { element, cleanup } = createShepherdElement({ descriptionId: 'test-desc', labelId: 'test-label', step }); container.appendChild(element); fireKeyDown(element, 39); expect(tourNextStub).toHaveBeenCalled(); // There should be no event propagation expect(propagateValue).toBe(0); fireKeyDown(element, 37); expect(tourBackStub).toHaveBeenCalled(); // There should be no event propagation expect(propagateValue).toBe(0); tourBackStub.mockRestore(); tourNextStub.mockRestore(); document.body.removeEventListener('keydown', propagateHandler); cleanup(); }); it('keyboardNavigation: false - arrow keys do not move between steps', () => { const tour = new Tour({ keyboardNavigation: false }); const step = new Step(tour, {}); let propagateValue = 0; const tourBackStub = vi.spyOn(tour, 'back').mockImplementation(() => {}); const tourNextStub = vi.spyOn(tour, 'next').mockImplementation(() => {}); // Add a keystroke listener to a parent to test event propagation const propagateHandler = (event) => { if ([27, 37, 39].includes(event.keyCode)) { propagateValue += 1; } }; document.body.addEventListener('keydown', propagateHandler); expect(tourBackStub).not.toHaveBeenCalled(); expect(tourNextStub).not.toHaveBeenCalled(); const { element, cleanup } = createShepherdElement({ descriptionId: 'test-desc', labelId: 'test-label', step }); container.appendChild(element); fireKeyDown(element, 39); expect(tourNextStub).not.toHaveBeenCalled(); // There should be event propagation expect(propagateValue).toBe(1); fireKeyDown(element, 37); expect(tourBackStub).not.toHaveBeenCalled(); // There should be another event propagation expect(propagateValue).toBe(2); tourBackStub.mockRestore(); tourNextStub.mockRestore(); document.body.removeEventListener('keydown', propagateHandler); cleanup(); }); it('Tab key: prevents default when no focusable elements exist', () => { const tour = new Tour(); // Step with no buttons, no cancel icon — dialog has no focusable children const step = new Step(tour, {}); const { element, cleanup } = createShepherdElement({ descriptionId: 'test-desc', labelId: 'test-label', step }); container.appendChild(element); const prevented = []; element.addEventListener( 'keydown', (e) => { prevented.push(e.defaultPrevented); }, { capture: false } ); fireKeyDown(element, 9, { cancelable: true }); expect(prevented[0]).toBe(true); cleanup(); }); it('Shift+Tab from first dialog element focuses last attachTo element', () => { const tour = new Tour(); const attachToEl = document.createElement('div'); const attachToBtn = document.createElement('button'); attachToBtn.textContent = 'Attach Button'; attachToEl.appendChild(attachToBtn); container.appendChild(attachToEl); const step = new Step(tour, { attachTo: { element: attachToEl, on: 'bottom' }, buttons: [{ text: 'Next', action: () => {} }] }); const { element, cleanup } = createShepherdElement({ descriptionId: 'test-desc', labelId: 'test-label', step }); container.appendChild(element); // First focusable dialog element is the "Next" button const dialogBtn = element.querySelector('button.shepherd-button'); expect(dialogBtn).toBeTruthy(); dialogBtn.focus(); const focusSpy = vi.spyOn(attachToBtn, 'focus'); fireKeyDown(element, 9, { shiftKey: true }); // The last focusable attachTo element (attachToBtn) should be focused expect(focusSpy).toHaveBeenCalled(); focusSpy.mockRestore(); cleanup(); }); it('Shift+Tab from first attachTo element focuses last dialog element', () => { const tour = new Tour(); const attachToEl = document.createElement('button'); attachToEl.textContent = 'Target'; container.appendChild(attachToEl); const step = new Step(tour, { attachTo: { element: attachToEl, on: 'bottom' }, buttons: [{ text: 'Next', action: () => {} }] }); const { element, cleanup } = createShepherdElement({ descriptionId: 'test-desc', labelId: 'test-label', step }); container.appendChild(element); // Focus the attachTo element (first focusable attach-to element) attachToEl.focus(); const dialogBtn = element.querySelector('button.shepherd-button'); const focusSpy = vi.spyOn(dialogBtn, 'focus'); // Fire on the attachTo element since it also has the keydown listener fireKeyDown(attachToEl, 9, { shiftKey: true }); expect(focusSpy).toHaveBeenCalled(); focusSpy.mockRestore(); cleanup(); }); it('forward Tab from last dialog element focuses first attachTo element', () => { const tour = new Tour(); const attachToEl = document.createElement('button'); attachToEl.textContent = 'Target'; container.appendChild(attachToEl); const step = new Step(tour, { attachTo: { element: attachToEl, on: 'bottom' }, buttons: [{ text: 'Next', action: () => {} }] }); const { element, cleanup } = createShepherdElement({ descriptionId: 'test-desc', labelId: 'test-label', step }); container.appendChild(element); // Focus the last dialog element (the button) const dialogBtn = element.querySelector('button.shepherd-button'); dialogBtn.focus(); const focusSpy = vi.spyOn(attachToEl, 'focus'); fireKeyDown(element, 9); // First focusable attachTo element should receive focus expect(focusSpy).toHaveBeenCalled(); focusSpy.mockRestore(); cleanup(); }); it('forward Tab from last attachTo element focuses first dialog element', () => { const tour = new Tour(); const attachToEl = document.createElement('button'); attachToEl.textContent = 'Target'; container.appendChild(attachToEl); const step = new Step(tour, { attachTo: { element: attachToEl, on: 'bottom' }, buttons: [{ text: 'Next', action: () => {} }] }); const { element, cleanup } = createShepherdElement({ descriptionId: 'test-desc', labelId: 'test-label', step }); container.appendChild(element); // Focus the last attachTo element (the button itself, since it's the only one) attachToEl.focus(); const dialogBtn = element.querySelector('button.shepherd-button'); const focusSpy = vi.spyOn(dialogBtn, 'focus'); // Fire on the attachTo element fireKeyDown(attachToEl, 9); expect(focusSpy).toHaveBeenCalled(); focusSpy.mockRestore(); cleanup(); }); it('unhandled key falls through to default case', () => { const tour = new Tour(); const step = new Step(tour, {}); const { element, cleanup } = createShepherdElement({ descriptionId: 'test-desc', labelId: 'test-label', step }); container.appendChild(element); // Press an unrelated key (e.g. 'A' = keyCode 65) and ensure nothing breaks fireKeyDown(element, 65); // No error thrown, element is still in DOM expect(element.parentNode).toBe(container); cleanup(); }); }); }); ================================================ FILE: shepherd.js/test/unit/components/shepherd-footer.spec.js ================================================ import { afterEach, beforeEach, describe, expect, it } from 'vitest'; import { createShepherdFooter } from '../../../src/components/shepherd-footer.ts'; import defaultButtons from '../../cypress/utils/default-buttons.js'; describe('components/ShepherdFooter', () => { let container; beforeEach(() => { container = document.createElement('div'); document.body.appendChild(container); }); afterEach(() => { container.remove(); }); it('renders no buttons if an empty array is passed to `options.buttons`', () => { const step = { options: { buttons: [] } }; const el = createShepherdFooter(step); container.appendChild(el); const buttons = container.querySelectorAll( '.shepherd-footer .shepherd-button' ); expect(buttons.length).toBe(0); }); it('renders no buttons if nothing is passed to `options.buttons`', () => { const step = { options: {} }; const el = createShepherdFooter(step); container.appendChild(el); const buttons = container.querySelectorAll( '.shepherd-footer .shepherd-button' ); expect(buttons.length).toBe(0); }); it('renders buttons for each item passed to `options.buttons`', () => { const step = { options: { buttons: [defaultButtons.cancel, defaultButtons.next] } }; const el = createShepherdFooter(step); container.appendChild(el); const buttons = container.querySelectorAll( '.shepherd-footer .shepherd-button' ); expect(buttons.length).toBe(2); const cancelButton = container.querySelector('footer .cancel-button'); expect(cancelButton).toHaveAttribute('tabindex', '0'); expect(cancelButton).toHaveClass( 'shepherd-button-secondary cancel-button shepherd-button' ); expect(cancelButton).toHaveTextContent('Exit'); const nextButton = container.querySelector('footer .next-button'); expect(nextButton).toHaveAttribute('tabindex', '0'); expect(nextButton).toHaveClass( 'shepherd-button-primary next-button shepherd-button' ); expect(nextButton).toHaveTextContent('Next'); }); }); ================================================ FILE: shepherd.js/test/unit/components/shepherd-header.spec.js ================================================ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; import { createShepherdHeader } from '../../../src/components/shepherd-header.ts'; import { Tour } from '../../../src/tour'; import { Step } from '../../../src/step'; describe('components/ShepherdHeader', () => { let container; beforeEach(() => { container = document.createElement('div'); document.body.appendChild(container); }); afterEach(() => { container.remove(); }); it('cancel icon is added when cancelIcon.enabled === true', () => { const step = { options: { cancelIcon: { enabled: true } } }; const el = createShepherdHeader('test-label', step); container.appendChild(el); const cancelIcon = container.querySelector('.shepherd-cancel-icon'); expect(cancelIcon).toBeInTheDocument(); expect(cancelIcon).toHaveAttribute('aria-label', 'Close Tour'); expect(cancelIcon).toHaveAttribute('type', 'button'); }); it('cancel icon is not added when cancelIcon.enabled === false', () => { const step = { options: { cancelIcon: { enabled: false } } }; const el = createShepherdHeader('test-label', step); container.appendChild(el); const cancelIcon = container.querySelector('.shepherd-cancel-icon'); expect(cancelIcon).not.toBeInTheDocument(); }); it('cancel icon aria-label overridden when cancelIcon.label is set', () => { const step = { options: { cancelIcon: { enabled: true, label: 'Test' } } }; const el = createShepherdHeader('test-label', step); container.appendChild(el); expect(container.querySelector('.shepherd-cancel-icon')).toHaveAttribute( 'aria-label', 'Test' ); }); it('cancel icon cancels the tour', async () => { const tour = new Tour(); const step = new Step(tour, { cancelIcon: { enabled: true } }); const stepCancelSpy = vi.spyOn(step, 'cancel'); const el = createShepherdHeader('test-label', step); container.appendChild(el); container.querySelector('.shepherd-cancel-icon').click(); expect(stepCancelSpy).toHaveBeenCalled(); }); describe('cancel icon attrs', () => { it('applies custom attributes to cancel icon', () => { const step = { options: { cancelIcon: { enabled: true, attrs: { 'data-test': 'close-tour', 'data-analytics': 'tour-cancel' } } } }; const el = createShepherdHeader('test-label', step); container.appendChild(el); const cancelIcon = container.querySelector('.shepherd-cancel-icon'); expect(cancelIcon).toHaveAttribute('data-test', 'close-tour'); expect(cancelIcon).toHaveAttribute('data-analytics', 'tour-cancel'); }); it('cancel icon attrs work with custom label', () => { const step = { options: { cancelIcon: { enabled: true, label: 'Custom Close', attrs: { 'data-test': 'custom-close', id: 'tour-close-btn' } } } }; const el = createShepherdHeader('test-label', step); container.appendChild(el); const cancelIcon = container.querySelector('.shepherd-cancel-icon'); expect(cancelIcon).toHaveAttribute('aria-label', 'Custom Close'); expect(cancelIcon).toHaveAttribute('data-test', 'custom-close'); expect(cancelIcon).toHaveAttribute('id', 'tour-close-btn'); }); it('cancel icon does not override core attributes via attrs', () => { const step = { options: { cancelIcon: { enabled: true, label: 'Close', attrs: { type: 'submit', // Should NOT override class: 'wrong-class', // Should NOT override 'aria-label': 'Wrong Label', // Should NOT override 'data-test': 'close-btn' // SHOULD apply } } } }; const el = createShepherdHeader('test-label', step); container.appendChild(el); const cancelIcon = container.querySelector('.shepherd-cancel-icon'); expect(cancelIcon).toHaveAttribute('type', 'button'); expect(cancelIcon).toHaveClass('shepherd-cancel-icon'); expect(cancelIcon).toHaveAttribute('aria-label', 'Close'); expect(cancelIcon).toHaveAttribute('data-test', 'close-btn'); }); it('cancel icon works with empty attrs', () => { const step = { options: { cancelIcon: { enabled: true, attrs: {} } } }; const el = createShepherdHeader('test-label', step); container.appendChild(el); const cancelIcon = container.querySelector('.shepherd-cancel-icon'); expect(cancelIcon).toBeInTheDocument(); expect(cancelIcon).toHaveAttribute('type', 'button'); }); it('cancel icon handles numeric and boolean attrs values', () => { const step = { options: { cancelIcon: { enabled: true, attrs: { 'data-count': 5, 'data-active': true } } } }; const el = createShepherdHeader('test-label', step); container.appendChild(el); const cancelIcon = container.querySelector('.shepherd-cancel-icon'); expect(cancelIcon).toHaveAttribute('data-count', '5'); expect(cancelIcon).toHaveAttribute('data-active', 'true'); }); }); }); ================================================ FILE: shepherd.js/test/unit/components/shepherd-modal.spec.js ================================================ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; import { createShepherdModal } from '../../../src/components/shepherd-modal.ts'; import { Step } from '../../../src/step'; import { Tour } from '../../../src/tour'; describe('components/ShepherdModal', () => { let container; beforeEach(() => { container = document.createElement('div'); document.body.appendChild(container); }); afterEach(() => { container.remove(); }); describe('closeModalOpening()', function () { it('sets values back to 0', () => { const modal = createShepherdModal(container); modal.positionModal(0, 0, 0, 0, null, { getBoundingClientRect() { return { height: 250, x: 20, y: 20, width: 500 }; } }); let modalPath = modal.getElement().querySelector('path'); expect(modalPath).toHaveAttribute( 'd', 'M1024,768H0V0H1024V768ZM20,20a0,0,0,0,0-0,0V270a0,0,0,0,0,0,0H520a0,0,0,0,0,0-0V20a0,0,0,0,0-0-0Z' ); modal.closeModalOpening(); modalPath = modal.getElement().querySelector('path'); expect(modalPath).toHaveAttribute( 'd', 'M1024,768H0V0H1024V768ZM0,0a0,0,0,0,0-0,0V0a0,0,0,0,0,0,0H0a0,0,0,0,0,0-0V0a0,0,0,0,0-0-0Z' ); }); }); describe('positionModal()', function () { it('sets the correct attributes when positioning modal opening', () => { const modal = createShepherdModal(container); let modalPath = modal.getElement().querySelector('path'); expect(modalPath).toHaveAttribute( 'd', 'M1024,768H0V0H1024V768ZM0,0a0,0,0,0,0-0,0V0a0,0,0,0,0,0,0H0a0,0,0,0,0,0-0V0a0,0,0,0,0-0-0Z' ); modal.closeModalOpening(); modalPath = modal.getElement().querySelector('path'); expect(modalPath).toHaveAttribute( 'd', 'M1024,768H0V0H1024V768ZM0,0a0,0,0,0,0-0,0V0a0,0,0,0,0,0,0H0a0,0,0,0,0,0-0V0a0,0,0,0,0-0-0Z' ); modal.positionModal(0, 0, 0, 0, null, { getBoundingClientRect() { return { height: 250, x: 20, y: 20, width: 500 }; } }); modalPath = modal.getElement().querySelector('path'); expect(modalPath).toHaveAttribute( 'd', 'M1024,768H0V0H1024V768ZM20,20a0,0,0,0,0-0,0V270a0,0,0,0,0,0,0H520a0,0,0,0,0,0-0V20a0,0,0,0,0-0-0Z' ); }); it('sets the correct attributes with padding', () => { const modal = createShepherdModal(container); let modalPath = modal.getElement().querySelector('path'); expect(modalPath).toHaveAttribute( 'd', 'M1024,768H0V0H1024V768ZM0,0a0,0,0,0,0-0,0V0a0,0,0,0,0,0,0H0a0,0,0,0,0,0-0V0a0,0,0,0,0-0-0Z' ); modal.positionModal(10, 0, 0, 0, null, { getBoundingClientRect() { return { height: 250, x: 20, y: 20, width: 500 }; } }); modalPath = modal.getElement().querySelector('path'); expect(modalPath).toHaveAttribute( 'd', 'M1024,768H0V0H1024V768ZM10,10a0,0,0,0,0-0,0V280a0,0,0,0,0,0,0H530a0,0,0,0,0,0-0V10a0,0,0,0,0-0-0Z' ); }); it('sets the correct attributes when positioning modal opening with border radius as number', () => { const modal = createShepherdModal(container); let modalPath = modal.getElement().querySelector('path'); expect(modalPath).toHaveAttribute( 'd', 'M1024,768H0V0H1024V768ZM0,0a0,0,0,0,0-0,0V0a0,0,0,0,0,0,0H0a0,0,0,0,0,0-0V0a0,0,0,0,0-0-0Z' ); modal.closeModalOpening(); modalPath = modal.getElement().querySelector('path'); expect(modalPath).toHaveAttribute( 'd', 'M1024,768H0V0H1024V768ZM0,0a0,0,0,0,0-0,0V0a0,0,0,0,0,0,0H0a0,0,0,0,0,0-0V0a0,0,0,0,0-0-0Z' ); modal.positionModal(0, 10, 0, 0, null, { getBoundingClientRect() { return { height: 250, x: 20, y: 20, width: 500 }; } }); modalPath = modal.getElement().querySelector('path'); expect(modalPath).toHaveAttribute( 'd', 'M1024,768H0V0H1024V768ZM30,20a10,10,0,0,0-10,10V260a10,10,0,0,0,10,10H510a10,10,0,0,0,10-10V30a10,10,0,0,0-10-10Z' ); }); it('sets the correct attributes when positioning modal opening with border radius as object', () => { const modal = createShepherdModal(container); let modalPath = modal.getElement().querySelector('path'); expect(modalPath).toHaveAttribute( 'd', 'M1024,768H0V0H1024V768ZM0,0a0,0,0,0,0-0,0V0a0,0,0,0,0,0,0H0a0,0,0,0,0,0-0V0a0,0,0,0,0-0-0Z' ); modal.closeModalOpening(); modalPath = modal.getElement().querySelector('path'); expect(modalPath).toHaveAttribute( 'd', 'M1024,768H0V0H1024V768ZM0,0a0,0,0,0,0-0,0V0a0,0,0,0,0,0,0H0a0,0,0,0,0,0-0V0a0,0,0,0,0-0-0Z' ); modal.positionModal( 0, { topLeft: 1, bottomLeft: 2, bottomRight: 3 }, 0, 0, null, { getBoundingClientRect() { return { height: 250, x: 20, y: 20, width: 500 }; } } ); modalPath = modal.getElement().querySelector('path'); expect(modalPath).toHaveAttribute( 'd', 'M1024,768H0V0H1024V768ZM21,20a1,1,0,0,0-1,1V268a2,2,0,0,0,2,2H517a3,3,0,0,0,3-3V20a0,0,0,0,0-0-0Z' ); }); it('sets the correct attributes when target is overflowing from scroll parent', () => { const modal = createShepherdModal(container); modal.positionModal( 0, 0, 0, 0, { getBoundingClientRect() { return { height: 250, x: 10, y: 100, width: 500 }; } }, { getBoundingClientRect() { return { height: 500, x: 10, y: 10, width: 500 }; } } ); const modalPath = modal.getElement().querySelector('path'); expect(modalPath).toHaveAttribute( 'd', 'M1024,768H0V0H1024V768ZM10,100a0,0,0,0,0-0,0V350a0,0,0,0,0,0,0H510a0,0,0,0,0,0-0V100a0,0,0,0,0-0-0Z' ); }); it('sets the correct attributes when target fits inside scroll parent', () => { const modal = createShepherdModal(container); modal.positionModal( 0, 0, 0, 0, { getBoundingClientRect() { return { height: 500, x: 10, y: 10, width: 500 }; } }, { getBoundingClientRect() { return { height: 250, x: 10, y: 100, width: 500 }; } } ); const modalPath = modal.getElement().querySelector('path'); expect(modalPath).toHaveAttribute( 'd', 'M1024,768H0V0H1024V768ZM10,100a0,0,0,0,0-0,0V350a0,0,0,0,0,0,0H510a0,0,0,0,0,0-0V100a0,0,0,0,0-0-0Z' ); }); it('allows setting an x-axis offset', () => { const modal = createShepherdModal(container); modal.positionModal(0, 0, 50, 0, null, { getBoundingClientRect() { return { height: 250, x: 10, y: 10, width: 500 }; } }); let modalPath = modal.getElement().querySelector('path'); expect(modalPath).toHaveAttribute( 'd', 'M1024,768H0V0H1024V768ZM60,10a0,0,0,0,0-0,0V260a0,0,0,0,0,0,0H560a0,0,0,0,0,0-0V10a0,0,0,0,0-0-0Z' ); modal.positionModal(0, 0, 100, 0, null, { getBoundingClientRect() { return { height: 250, x: 10, y: 10, width: 500 }; } }); modalPath = modal.getElement().querySelector('path'); expect(modalPath).toHaveAttribute( 'd', 'M1024,768H0V0H1024V768ZM110,10a0,0,0,0,0-0,0V260a0,0,0,0,0,0,0H610a0,0,0,0,0,0-0V10a0,0,0,0,0-0-0Z' ); }); it('allows setting a y-axis offset', () => { const modal = createShepherdModal(container); modal.positionModal(0, 0, 0, 35, null, { getBoundingClientRect() { return { height: 250, x: 10, y: 10, width: 500 }; } }); let modalPath = modal.getElement().querySelector('path'); expect(modalPath).toHaveAttribute( 'd', 'M1024,768H0V0H1024V768ZM10,45a0,0,0,0,0-0,0V295a0,0,0,0,0,0,0H510a0,0,0,0,0,0-0V45a0,0,0,0,0-0-0Z' ); modal.positionModal(0, 0, 0, 75, null, { getBoundingClientRect() { return { height: 250, x: 10, y: 10, width: 500 }; } }); modalPath = modal.getElement().querySelector('path'); expect(modalPath).toHaveAttribute( 'd', 'M1024,768H0V0H1024V768ZM10,85a0,0,0,0,0-0,0V335a0,0,0,0,0,0,0H510a0,0,0,0,0,0-0V85a0,0,0,0,0-0-0Z' ); }); it('sets the correct attributes with extraHighlights', () => { const modal = createShepherdModal(container); modal.positionModal( 0, 0, 0, 0, null, { getBoundingClientRect() { return { height: 250, x: 20, y: 20, width: 500 }; } }, [ { getBoundingClientRect() { return { height: 100, x: 50, y: 50, width: 100 }; } } ] ); const modalPath = modal.getElement().querySelector('path'); expect(modalPath).toHaveAttribute( 'd', 'M1024,768H0V0H1024V768ZM20,20a0,0,0,0,0-0,0V270a0,0,0,0,0,0,0H520a0,0,0,0,0,0-0V20a0,0,0,0,0-0-0ZM50,50a0,0,0,0,0-0,0V150a0,0,0,0,0,0,0H150a0,0,0,0,0,0-0V50a0,0,0,0,0-0-0Z' ); }); it('sets the correct attributes with multiple extraHighlights', () => { const modal = createShepherdModal(container); modal.positionModal( 0, 0, 0, 0, null, { getBoundingClientRect() { return { height: 250, x: 20, y: 20, width: 500 }; } }, [ { getBoundingClientRect() { return { height: 100, x: 50, y: 50, width: 100 }; } }, { getBoundingClientRect() { return { height: 50, x: 200, y: 200, width: 50 }; } } ] ); const modalPath = modal.getElement().querySelector('path'); expect(modalPath).toHaveAttribute( 'd', 'M1024,768H0V0H1024V768ZM20,20a0,0,0,0,0-0,0V270a0,0,0,0,0,0,0H520a0,0,0,0,0,0-0V20a0,0,0,0,0-0-0ZM50,50a0,0,0,0,0-0,0V150a0,0,0,0,0,0,0H150a0,0,0,0,0,0-0V50a0,0,0,0,0-0-0ZM200,200a0,0,0,0,0-0,0V250a0,0,0,0,0,0,0H250a0,0,0,0,0,0-0V200a0,0,0,0,0-0-0Z' ); }); it('skips duplicate elements in extraHighlights', () => { const modal = createShepherdModal(container); const sharedElement = { getBoundingClientRect() { return { height: 100, x: 50, y: 50, width: 100, top: 50, bottom: 150, left: 50, right: 150 }; } }; modal.positionModal( 0, 0, 0, 0, null, { getBoundingClientRect() { return { height: 250, x: 20, y: 20, width: 500, top: 20, bottom: 270, left: 20, right: 520 }; } }, // Pass the same element twice — both duplicates are skipped [sharedElement, sharedElement] ); const modalPath = modal.getElement().querySelector('path'); const d = modalPath.getAttribute('d'); // Duplicate elements are both skipped, only the main target cutout remains // Outer path close + target cutout close = 2 Z's const cutouts = d.split('Z').length - 1; expect(cutouts).toBe(2); }); }); describe('setupForStep()', function () { it('useModalOverlay: false hides the modal', () => { const modal = createShepherdModal(container); modal.show(); expect(modal.getElement()).toHaveClass('shepherd-modal-is-visible'); const tour = new Tour({ useModalOverlay: false }); const step = new Step(tour, {}); modal.setupForStep(step); expect(modal.getElement()).not.toHaveClass('shepherd-modal-is-visible'); }); it('useModalOverlay: true shows the modal and calls _styleForStep', () => { const modal = createShepherdModal(container); const rafSpy = vi .spyOn(window, 'requestAnimationFrame') .mockImplementation(() => 1); const targetEl = document.createElement('div'); container.appendChild(targetEl); const tour = new Tour({ useModalOverlay: true }); const step = new Step(tour, { attachTo: { element: targetEl, on: 'bottom' } }); // Resolve attachTo so step.target is set step._resolveAttachToOptions(); step.target = targetEl; modal.setupForStep(step); expect(modal.getElement()).toHaveClass('shepherd-modal-is-visible'); // _styleForStep calls rafLoop which calls requestAnimationFrame expect(rafSpy).toHaveBeenCalled(); rafSpy.mockRestore(); }); }); describe('show/hide', function () { it('show adds classes', () => { const modal = createShepherdModal(container); modal.show(); expect(modal.getElement()).toHaveClass('shepherd-modal-is-visible'); }); it('hide removes classes', () => { const modal = createShepherdModal(container); modal.show(); modal.hide(); expect(modal.getElement()).not.toHaveClass('shepherd-modal-is-visible'); }); }); describe('destroy()', function () { it('removes the modal element from the DOM', () => { const modal = createShepherdModal(container); expect( container.querySelector('.shepherd-modal-overlay-container') ).toBeTruthy(); modal.destroy(); expect( container.querySelector('.shepherd-modal-overlay-container') ).toBeNull(); }); }); describe('_getScrollParent (via setupForStep)', function () { it('recurses to find a scrollable parent element', () => { const modal = createShepherdModal(container); const rafSpy = vi .spyOn(window, 'requestAnimationFrame') .mockImplementation(() => 1); // Create a scrollable parent const scrollParent = document.createElement('div'); Object.defineProperty(scrollParent, 'scrollHeight', { value: 500 }); Object.defineProperty(scrollParent, 'clientHeight', { value: 200 }); container.appendChild(scrollParent); const targetEl = document.createElement('div'); scrollParent.appendChild(targetEl); // Mock getComputedStyle so the target has 'visible' overflow (not scrollable) // and the scroll parent has 'auto' overflow (scrollable), forcing recursion const origGetComputedStyle = window.getComputedStyle; vi.spyOn(window, 'getComputedStyle').mockImplementation((el) => { if (el === targetEl) { return { overflowY: 'visible' }; } if (el === scrollParent) { return { overflowY: 'auto' }; } return origGetComputedStyle(el); }); const tour = new Tour({ useModalOverlay: true }); const step = new Step(tour, { attachTo: { element: targetEl, on: 'bottom' } }); step._resolveAttachToOptions(); step.target = targetEl; // setupForStep triggers _styleForStep -> _getScrollParent modal.setupForStep(step); expect(modal.getElement()).toHaveClass('shepherd-modal-is-visible'); rafSpy.mockRestore(); vi.mocked(window.getComputedStyle).mockRestore(); }); }); describe('_preventModalBodyTouch (via _addStepEventListeners)', function () { it('prevents default on window touchmove after setupForStep', () => { const modal = createShepherdModal(container); const rafSpy = vi .spyOn(window, 'requestAnimationFrame') .mockImplementation(() => 1); const targetEl = document.createElement('div'); container.appendChild(targetEl); const tour = new Tour({ useModalOverlay: true }); const step = new Step(tour, { attachTo: { element: targetEl, on: 'bottom' } }); step._resolveAttachToOptions(); step.target = targetEl; modal.setupForStep(step); // _addStepEventListeners was called, so window has a touchmove listener const touchEvent = new Event('touchmove', { bubbles: true, cancelable: true }); const preventSpy = vi.spyOn(touchEvent, 'preventDefault'); window.dispatchEvent(touchEvent); expect(preventSpy).toHaveBeenCalled(); // Clean up: hide triggers _cleanupStepEventListeners which removes the listener modal.hide(); rafSpy.mockRestore(); }); }); describe('_preventModalOverlayTouch', function () { it('stops propagation on touchmove events', () => { const modal = createShepherdModal(container); const svgEl = modal.getElement(); const touchEvent = new Event('touchmove', { bubbles: true, cancelable: true }); const stopSpy = vi.spyOn(touchEvent, 'stopPropagation'); svgEl.dispatchEvent(touchEvent); expect(stopSpy).toHaveBeenCalled(); }); }); describe('_getIframeOffset (via setupForStep)', function () { it('accumulates offset when element is inside an iframe', () => { const modal = createShepherdModal(container); const rafSpy = vi .spyOn(window, 'requestAnimationFrame') .mockImplementation(() => 1); const targetEl = document.createElement('div'); container.appendChild(targetEl); // Simulate the element being inside an iframe by mocking ownerDocument.defaultView const fakeIframe = document.createElement('iframe'); Object.defineProperty(fakeIframe, 'getBoundingClientRect', { value: () => ({ top: 10, left: 20, width: 100, height: 100, x: 20, y: 10 }) }); Object.defineProperty(fakeIframe, 'scrollTop', { value: 5 }); Object.defineProperty(fakeIframe, 'scrollLeft', { value: 3 }); const fakeChildWindow = { frameElement: fakeIframe, parent: window }; const origDescriptor = Object.getOwnPropertyDescriptor( targetEl.ownerDocument, 'defaultView' ); Object.defineProperty(targetEl.ownerDocument, 'defaultView', { value: fakeChildWindow, configurable: true }); const tour = new Tour({ useModalOverlay: true }); const step = new Step(tour, { attachTo: { element: targetEl, on: 'bottom' } }); step._resolveAttachToOptions(); step.target = targetEl; // This triggers _styleForStep -> _getIframeOffset, which should // walk up through fakeChildWindow and accumulate the iframe offset modal.setupForStep(step); // Restore defaultView before any assertions (jsdom needs it for instanceof checks) if (origDescriptor) { Object.defineProperty( targetEl.ownerDocument, 'defaultView', origDescriptor ); } else { Object.defineProperty(targetEl.ownerDocument, 'defaultView', { value: window, configurable: true }); } expect(modal.getElement()).toHaveClass('shepherd-modal-is-visible'); rafSpy.mockRestore(); }); it('handles cross-origin iframe SecurityError gracefully', () => { // Regression test for https://github.com/shipshapecode/shepherd/issues/3087 // When Shepherd is loaded in a nested cross-origin iframe, accessing // window.frameElement throws a SecurityError due to Same-Origin Policy. // This test ensures the error is caught and handled gracefully. const modal = createShepherdModal(container); const rafSpy = vi .spyOn(window, 'requestAnimationFrame') .mockImplementation(() => 1); const targetEl = document.createElement('div'); container.appendChild(targetEl); // Simulate a cross-origin iframe by making frameElement access throw SecurityError const fakeChildWindow = { get frameElement() { // Simulate browser's SecurityError when accessing cross-origin frameElement const error = new Error( 'Blocked a frame with origin "https://example.com" from accessing a cross-origin frame.' ); error.name = 'SecurityError'; throw error; }, parent: window }; const origDescriptor = Object.getOwnPropertyDescriptor( targetEl.ownerDocument, 'defaultView' ); Object.defineProperty(targetEl.ownerDocument, 'defaultView', { value: fakeChildWindow, configurable: true }); const tour = new Tour({ useModalOverlay: true }); const step = new Step(tour, { attachTo: { element: targetEl, on: 'bottom' } }); step._resolveAttachToOptions(); step.target = targetEl; // This should NOT throw an error, even though frameElement access throws SecurityError expect(() => { modal.setupForStep(step); }).not.toThrow(); // Restore defaultView before any assertions if (origDescriptor) { Object.defineProperty( targetEl.ownerDocument, 'defaultView', origDescriptor ); } else { Object.defineProperty(targetEl.ownerDocument, 'defaultView', { value: window, configurable: true }); } expect(modal.getElement()).toHaveClass('shepherd-modal-is-visible'); rafSpy.mockRestore(); }); }); }); ================================================ FILE: shepherd.js/test/unit/components/shepherd-text.spec.js ================================================ import { afterEach, beforeEach, describe, expect, it } from 'vitest'; import { createShepherdText } from '../../../src/components/shepherd-text.ts'; describe('components/ShepherdText', () => { let container; beforeEach(() => { container = document.createElement('div'); document.body.appendChild(container); }); afterEach(() => { container.remove(); }); it('adds plain text to the content', () => { const step = { options: { text: 'I am some test text.' } }; const el = createShepherdText('test-desc', step); container.appendChild(el); expect(container.querySelector('.shepherd-text')).toHaveTextContent( 'I am some test text.' ); }); it('applies HTML element directly to content', () => { const step = { options: { text: 'I am some test text.
' } }; const el = createShepherdText('test-desc', step); container.appendChild(el); expect(container.querySelector('.shepherd-text')).toContainHTML( 'I am some test text.
' ); }); it('applies the text from a function', () => { const step = { options: { text: () => 'I am some test text.' } }; const el = createShepherdText('test-desc', step); container.appendChild(el); expect(container.querySelector('.shepherd-text')).toHaveTextContent( 'I am some test text.' ); }); it('appends an HTMLElement when text is a DOM node', () => { const paragraph = document.createElement('p'); paragraph.textContent = 'I am a DOM node.'; const step = { options: { text: paragraph } }; const el = createShepherdText('test-desc', step); container.appendChild(el); const textEl = container.querySelector('.shepherd-text'); expect(textEl.contains(paragraph)).toBe(true); expect(textEl).toHaveTextContent('I am a DOM node.'); }); }); ================================================ FILE: shepherd.js/test/unit/components/shepherd-title.spec.js ================================================ import { afterEach, beforeEach, describe, expect, it } from 'vitest'; import { createShepherdTitle } from '../../../src/components/shepherd-title.ts'; describe('components/ShepherdTitle', () => { let container; beforeEach(() => { container = document.createElement('div'); document.body.appendChild(container); }); afterEach(() => { container.remove(); }); it('adds plain title to the content', () => { const el = createShepherdTitle('test-label', 'I am some test title.'); container.appendChild(el); expect(container.querySelector('.shepherd-title')).toHaveTextContent( 'I am some test title.' ); }); it('applies the title from a function', () => { const el = createShepherdTitle('test-label', () => 'I am some test title.'); container.appendChild(el); expect(container.querySelector('.shepherd-title')).toHaveTextContent( 'I am some test title.' ); }); }); ================================================ FILE: shepherd.js/test/unit/evented.spec.js ================================================ import { beforeEach, describe, expect, it, vi } from 'vitest'; import { Evented } from '../../src/evented'; describe('Evented', () => { let testEvent, testOnTriggered; beforeEach(() => { testEvent = new Evented(); testEvent.on('testOn', () => (testOnTriggered = true)); testOnTriggered = false; }); describe('on()', () => { it('adds a new event binding', () => { expect(testEvent.bindings.testOn, 'custom event added').toBeTruthy(); }); }); describe('trigger()', () => { it('triggers a created event', () => { testEvent.trigger('testOn'); expect( testOnTriggered, 'true is returned from event trigger' ).toBeTruthy(); }); it('passes arguments to handler functions', () => { const handlerSpy = vi.fn(); testEvent.on('myEvent', handlerSpy); testEvent.trigger('myEvent', { step: { id: 'test', text: 'A step' }, previous: null }); expect(handlerSpy).toHaveBeenCalledWith({ previous: null, step: { id: 'test', text: 'A step' } }); }); }); describe('off()', () => { it('removes a generic event binding when no handler passed', () => { testEvent.off('testOn'); expect(testEvent.bindings.testOn, 'custom event removed').toBeUndefined(); }); it('removes a specific event binding when handler is passed', () => { const handler = () => {}; testEvent.on('testOn', handler); expect( testEvent.bindings.testOn.length, '2 event listeners for testOn' ).toBe(2); testEvent.off('testOn', handler); expect( testEvent.bindings.testOn.length, '1 event listener for testOn' ).toBe(1); }); it('does not remove uncreated events', () => { testEvent.off('testBlank'); expect( testEvent.bindings.testBlank, 'returns false for non created events' ).toBeFalsy(); }); }); describe('once()', () => { it('adds a new event binding that only triggers once', () => { testEvent.once('testOnce', () => true); testEvent.trigger('testOnce'); expect( testEvent.bindings.testOnce, 'custom event removed after one trigger' ).toBeTruthy(); }); }); }); ================================================ FILE: shepherd.js/test/unit/server.spec.js ================================================ /** * @jest-environment node */ import { describe, expect, it } from 'vitest'; import Shepherd from '../../src/shepherd'; describe('Server Side Render', function () { describe('Tour constructor', function () { it('does not start a tour when window is undefined', () => { const instance = new Shepherd.Tour(); expect(instance).toBeTruthy(); }); }); }); ================================================ FILE: shepherd.js/test/unit/setupTests.js ================================================ import { vi } from 'vitest'; import * as matchers from '@testing-library/jest-dom/matchers'; import { expect } from 'vitest'; expect.extend(matchers); // Set browser environment Object.defineProperty(globalThis, 'IS_BROWSER', { value: true, writable: false }); // Console errors are used for user information, do not display them during // tests. global.console = { ...console, error: vi.fn() }; global.sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)); // Add custom matchers for DOM testing if (typeof window !== 'undefined') { Object.defineProperty(window, 'matchMedia', { writable: true, value: vi.fn().mockImplementation((query) => ({ matches: false, media: query, onchange: null, addListener: vi.fn(), // deprecated removeListener: vi.fn(), // deprecated addEventListener: vi.fn(), removeEventListener: vi.fn(), dispatchEvent: vi.fn() })) }); } ================================================ FILE: shepherd.js/test/unit/step.spec.js ================================================ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; import Shepherd from '../../src/shepherd'; import { Step } from '../../src/step'; import { Tour } from '../../src/tour'; import ResizeObserver from 'resize-observer-polyfill'; import { offset } from '@floating-ui/dom'; // since importing non UMD, needs assignment window.Shepherd = Shepherd; window.ResizeObserver = ResizeObserver; const DEFAULT_STEP_CLASS = 'shepherd-step-tooltip'; describe('Tour | Step', () => { let tour; const showOn = () => { return true; }; const when = { show() {} }; beforeEach(() => { tour = new Tour(); }); describe('Shepherd.Step()', () => { const defaultOffsetMiddleware = offset({ mainAxis: 0, crossAxis: 32 }); const fooMiddleware = { name: 'foo', options: 'bar', fn: (args) => args }; const instance = new Shepherd.Tour({ defaultStepOptions: { classes: DEFAULT_STEP_CLASS, scrollTo: true, floatingUIOptions: { middleware: [defaultOffsetMiddleware] }, showOn, when } }); const testStep = instance.addStep({ attachTo: { element: 'body', on: 'top' }, highlightClass: 'highlight', text: 'This is a step for testing', buttons: [ { text: 'Next', action: instance.next } ], id: 'test', floatingUIOptions: { middleware: [fooMiddleware] } }); const showTestStep = instance.addStep({ buttons: [], id: 'test2', text: 'Another Step' }); // Add more steps for total _setupButtons coverage instance.addStep({ buttons: { text: 'Next', action: instance.next }, id: 'test3-id', text: 'Another Step part deux' }); const stepWithoutNameWithId = instance.addStep({ attachTo: { element: 'body' }, highlightClass: 'highlight', id: 'no-name', text: 'This is a step without a name, but with an id', buttons: [ { text: 'Next', action: instance.next } ] }); const stepWithoutNameWithoutIdOffsetMiddleware = offset({ mainAxis: 0, crossAxis: -32 }); const stepWithoutNameWithoutId = instance.addStep({ attachTo: { element: 'body' }, highlightClass: 'highlight', text: 'This is a step without a name, and without an id', buttons: [ { text: 'Next', action: instance.next } ], floatingUIOptions: { middleware: [stepWithoutNameWithoutIdOffsetMiddleware] } }); const beforeShowPromise = () => new Promise((resolve) => { setTimeout(() => { console.log('beforeShowPromise worked!'); resolve('beforeShowPromise worked!'); }, 1000); }); const beforeShowPromiseTestStep = instance.addStep({ text: 'Before Show Promise Step', id: 'test3', beforeShowPromise }); afterEach(() => { instance.complete(); }); it('has all the correct properties', () => { const values = [ 'arrow', 'classes', 'scrollTo', 'floatingUIOptions', 'showOn', 'when', 'attachTo', 'highlightClass', 'text', 'buttons', 'id' ]; expect(values).toEqual(Object.keys(testStep.options)); expect(testStep.id, 'passed name set as id').toBe('test'); expect(stepWithoutNameWithId.id, 'no name, id passed is set').toBe( 'no-name' ); expect( stepWithoutNameWithoutId.id, 'id is generated when no name or id passed' ).toMatch( /^step-[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/ ); }); it('deep clones defaultStepOptions and copies functions', () => { expect(testStep.options).toEqual({ arrow: true, attachTo: { element: 'body', on: 'top' }, buttons: [ { text: 'Next', action: instance.next } ], classes: DEFAULT_STEP_CLASS, highlightClass: 'highlight', id: 'test', scrollTo: true, text: 'This is a step for testing', floatingUIOptions: { middleware: [defaultOffsetMiddleware, fooMiddleware] }, showOn, when }); }); it('allows the step to override a previously defined modifier', () => { stepWithoutNameWithoutId.show(); const offsetMiddleware = stepWithoutNameWithoutId.options.floatingUIOptions.middleware.filter( ({ name }) => name === 'offset' ); const offsetResult = offsetMiddleware.reduce( (agg, current) => { agg.mainAxis += current.options.mainAxis; agg.crossAxis += current.options.crossAxis; return agg; }, { mainAxis: 0, crossAxis: 0 } ); expect(offsetResult).toEqual({ mainAxis: 0, crossAxis: 0 }); }); describe('.hide()', () => { it('detaches from the step target', () => { instance.start(); const targetElem = document.body; expect(targetElem.classList.contains('shepherd-enabled')).toBe(true); testStep.hide(); expect(targetElem.classList.contains('shepherd-enabled')).toBe(false); }); }); describe('.show()', () => { it('beforeShowPromise called before `show`', () => { console.log = vi.fn(); const promise = beforeShowPromiseTestStep.show(); return promise.then(() => { expect(console.log).toHaveBeenCalledWith('beforeShowPromise worked!'); }); }); it('shows step evoking method, regardless of order', () => { showTestStep.show(); expect( document.querySelector('[data-shepherd-step-id=test2]') ).toBeInTheDocument(); }); }); }); describe('cancel()', () => { it('triggers the cancel event and tour method', () => { let cancelCalled = false; let eventTriggered = false; const step = new Step( { cancel() { cancelCalled = true; } }, {} ); step.on('cancel', () => (eventTriggered = true)); step.cancel(); expect(cancelCalled, 'cancel method from tour called').toBeTruthy(); expect(eventTriggered, 'cancel event was triggered').toBeTruthy(); }); }); describe('complete()', () => { it('triggers the complete event and tour method', () => { let completeCalled = false; let eventTriggered = false; const step = new Step( { complete() { completeCalled = true; } }, {} ); step.on('complete', () => (eventTriggered = true)); step.complete(); expect(completeCalled, 'complete method from tour called').toBeTruthy(); expect(eventTriggered, 'complete event was triggered').toBeTruthy(); }); }); describe('destroy()', () => { it('triggers the destroy event', () => { const step = new Step(tour, {}); let eventTriggered = false; step.on('destroy', () => (eventTriggered = true)); step.destroy(); expect(eventTriggered, 'destroy event was triggered').toBeTruthy(); }); }); describe('hide()', () => { let beforeHideTriggered = false; let modalHideCalled = false; const step = new Step( { modal: { hide() { modalHideCalled = true; } } }, {} ); it('triggers the before-hide event', () => { step.on('before-hide', () => (beforeHideTriggered = true)); step.hide(); expect( beforeHideTriggered, 'before-hide event was triggered' ).toBeTruthy(); }); it('calls tour.modal.hide', () => { expect(modalHideCalled, 'tour.modal.hide called').toBeTruthy(); }); }); describe('updateStepOptions', () => { let step; beforeEach(() => { step = new Step(tour, { id: 'test-id', attachTo: { element: 'body', on: 'top' }, text: 'Lorem Ipsum', classes: 'classes-test', title: 'Test', scrollTo: false, buttons: [ { text: 'button one', disabled: false, classes: 'button1' }, { text: 'button two', disabled: true, classes: 'button2' } ] }); step.show(); }); afterEach(() => { step.destroy(); }); it('should update passed in properties', async () => { step.updateStepOptions({ text: 'updated', title: 'New title' }); expect(step.options.text).toBe('updated'); expect(step.options.title).toBe('New title'); await window.requestAnimationFrame( () => new Promise((resolve) => { return resolve(); }) ); expect(document.querySelector('.shepherd-text').textContent).toBe( 'updated' ); expect(document.querySelector('.shepherd-title').textContent).toBe( 'New title' ); }); it('should not affect other properties', async () => { step.updateStepOptions({ text: 'updated', title: 'New title' }); expect(step.options.id).toEqual('test-id'); expect(step.options.buttons).toEqual([ { text: 'button one', disabled: false, classes: 'button1' }, { text: 'button two', disabled: true, classes: 'button2' } ]); await window.requestAnimationFrame( () => new Promise((resolve) => { return resolve(); }) ); expect(document.querySelector('.button1').textContent).toBe('button one'); expect(document.querySelector('.button2').textContent).toBe('button two'); }); it('should update buttons', async () => { const buttons = [ { text: 'button one updated', disabled: true, classes: 'button1' }, { text: 'button two updated', disabled: false, classes: 'button2' } ]; step.updateStepOptions({ buttons }); expect(step.options.buttons).toEqual(buttons); await window.requestAnimationFrame( () => new Promise((resolve) => { return resolve(); }) ); const buttonOne = document.querySelector('.button1'); expect(buttonOne.textContent).toBe('button one updated'); expect(buttonOne.disabled).toBe(true); const buttonTwo = document.querySelector('.button2'); expect(buttonTwo.textContent).toBe('button two updated'); expect(buttonTwo.disabled).toBe(false); }); it('removing title should remove class', async () => { step.updateStepOptions({ title: '' }); expect(step.options.title).toEqual(''); await window.requestAnimationFrame( () => new Promise((resolve) => { return resolve(); }) ); const element = document.querySelector('.shepherd-element'); expect(element.classList.contains('shepherd-has-title')).toBeFalsy(); }); it('updating classes should update element classes', async () => { step.updateStepOptions({ classes: 'test-1 test-2' }); expect(step.options.classes).toEqual('test-1 test-2'); await window.requestAnimationFrame( () => new Promise((resolve) => { return resolve(); }) ); const element = document.querySelector('.shepherd-element'); expect(element.classList.contains('test-1')).toBeTruthy(); expect(element.classList.contains('test-2')).toBeTruthy(); expect(element.classList.contains('classes-test')).toBeFalsy(); }); }); describe('_setupElements()', () => { it('calls destroy on the step if the content element is already set', () => { const step = new Step(tour, {}); let destroyCalled = false; step.el = document.createElement('a'); step.destroy = () => (destroyCalled = true); step._setupElements(); expect( destroyCalled, '_setupElements method called destroy with element set' ).toBeTruthy(); }); it('calls destroy on the tooltip if it already exists', () => { const step = new Step(tour, {}); let destroyCalled = false; step.cleanup = () => { destroyCalled = true; }; step._setupElements(); expect( destroyCalled, '_setupElements method called destroy on the existing tooltip' ).toBe(true); }); }); describe('_scrollTo()', () => { it('calls the scroll native method', () => { const div = document.createElement('div'); let handlerCalled = false; div.classList.add('scroll-test'); document.body.appendChild(div); const step = new Step('test', { attachTo: { element: '.scroll-test', on: 'center' } }); div.scrollIntoView = () => (handlerCalled = true); step._scrollTo(); expect(handlerCalled).toBeTruthy(); }); it('calls the custom handler', () => { let handlerAdded = false; const step = new Step('test', { scrollToHandler: () => (handlerAdded = true) }); step._scrollTo(); expect(handlerAdded).toBeTruthy(); }); it('calls scroll native method after before-show promise resolution', () => { const resTester = document.createElement('div'); let resHandlerCalled = false; resTester.classList.add('post-res-scroll-test'); resTester.scrollIntoView = () => (resHandlerCalled = true); const resSpy = vi.spyOn(resTester, 'scrollIntoView'); document.body.appendChild(resTester); const beforeShowPromise = new Promise((resolve) => { return setTimeout(() => resolve('beforeShowPromise worked!'), 1000); }); const step = new Step('test', { attachTo: { element: '.post-res-scroll-test', on: 'center' }, beforeShowPromise: () => { return beforeShowPromise; } }); step.show(); step._scrollTo(); expect(resHandlerCalled).toBeTruthy(); expect(resSpy).toHaveBeenCalled(); }); it('calls the custom handler after before-show promise resolution', () => { let resHandlerAdded = false; const beforeShowPromise = new Promise((resolve) => { return setTimeout(() => resolve('beforeShowPromise worked!'), 1000); }); const step = new Step('test', { scrollToHandler: () => (resHandlerAdded = true), beforeShowPromise: () => { return beforeShowPromise; } }); const resSpy = vi.spyOn(step.options, 'scrollToHandler'); step.show(); step._scrollTo(); expect(resHandlerAdded).toBeTruthy(); expect(resSpy).toHaveBeenCalled(); }); }); describe('setOptions()', () => { it('calls event handlers passed in as properties to the `when` option', () => { let whenCalled = false; const step = new Step('test', { when: { destroy: () => (whenCalled = true) } }); step.destroy(); expect(whenCalled).toBeTruthy(); }); }); describe('getTour()', () => { it('returns the tour value', () => { const step = new Step(new Shepherd.Tour(), {}); expect(step.getTour() instanceof Shepherd.Tour).toBeTruthy(); }); }); describe('_createTooltipContent', () => { it('ARIA attributes set', () => { const step = new Step(tour, { id: 'test-step', text: 'Lorem Ipsum', title: 'Test' }); const element = step._createTooltipContent(); expect(element.getAttribute('aria-labelledby')).toBe('test-step-label'); expect(element.querySelector('.shepherd-title').id).toBe( 'test-step-label' ); expect(element.getAttribute('aria-describedby')).toBe( 'test-step-description' ); expect(element.querySelector('.shepherd-text').id).toBe( 'test-step-description' ); }); }); describe('correct operation of classes on body element when step not attached to an element', () => { const offsetMiddleware = offset({ crossAxis: 32 }); const defaultCallback = (args) => args; const instance = new Shepherd.Tour({ defaultStepOptions: { classes: DEFAULT_STEP_CLASS, scrollTo: true, floatingUIOptions: { middleware: [offsetMiddleware] }, showOn, when } }); const stepWithoutAttachment = instance.addStep({ highlightClass: 'highlight', text: 'This is a step for testing', buttons: [ { text: 'Next', action: instance.next } ], id: 'test', floatingUIOptions: { middleware: [{ name: 'foo', options: 'bar', fn: defaultCallback }] } }); afterEach(() => { instance.complete(); }); describe('.hide()', () => { it('detaches from the step target', () => { instance.start(); const targetElem = document.body; expect(targetElem.classList.contains('shepherd-enabled')).toBe(true); stepWithoutAttachment.hide(); expect(targetElem.classList.contains('shepherd-enabled')).toBe(false); }); }); describe('.destroy()', () => { it('detaches from the step target', () => { instance.start(); const targetElem = document.body; expect(targetElem.classList.contains('shepherd-enabled')).toBe(true); stepWithoutAttachment.destroy(); expect(targetElem.classList.contains('shepherd-enabled')).toBe(false); }); }); }); describe('lazy attachTo evaluation', () => { // We test this using attachTo.element callback. // Note that lazy evaluation largely relies on `parseAttachTo`, however this does // not it's implementation, only if the callback is called lazily. it('lazily evaluates attachTo.element callback', () => { const step1AttachToCallback = vi.fn(); const step2AttachToCallback = vi.fn(); const instance = new Shepherd.Tour({ steps: [ { text: 'step 1', attachTo: { element: step1AttachToCallback, on: 'auto' } }, { text: 'step 2', attachTo: { element: step2AttachToCallback, on: 'auto' } } ] }); instance.start(); expect(step1AttachToCallback).toHaveBeenCalled(); expect(step2AttachToCallback).not.toHaveBeenCalled(); instance.next(); expect(step2AttachToCallback).toHaveBeenCalled(); expect(step1AttachToCallback).toHaveBeenCalledTimes(1); expect(step2AttachToCallback).toHaveBeenCalledTimes(1); }); it('lazily evaluates attachTo.element selector', () => { const querySelectorSpy = vi.spyOn(document, 'querySelector'); const instance = new Shepherd.Tour({ steps: [ { text: 'step 1', attachTo: { element: '#step-1-attach-to-element', on: 'auto' } }, { text: 'step 2', attachTo: { element: '#step-2-attach-to-element', on: 'auto' } } ] }); instance.start(); expect(querySelectorSpy).toHaveBeenCalledWith( '#step-1-attach-to-element' ); expect(querySelectorSpy).not.toHaveBeenCalledWith( '#step-2-attach-to-element' ); instance.next(); expect(querySelectorSpy).toHaveBeenCalledWith( '#step-2-attach-to-element' ); }); it('evaluates attachTo on subsequent shows', () => { const step1AttachToCallback = vi.fn(); const step2AttachToCallback = vi.fn(); const instance = new Shepherd.Tour({ steps: [ { text: 'step 1', attachTo: { element: step1AttachToCallback, on: 'auto' } }, { text: 'step 2', attachTo: { element: step2AttachToCallback, on: 'auto' } } ] }); instance.start(); expect(step1AttachToCallback).toHaveBeenCalledTimes(1); instance.next(); instance.back(); expect(step1AttachToCallback).toHaveBeenCalledTimes(2); }); it('evaluates attachTo only once', () => { const instance = new Shepherd.Tour({ steps: [ { text: 'step 1', attachTo: { element: () => {}, on: 'auto' }, id: 'step1' }, { text: 'step 2', attachTo: { element: () => {}, on: 'auto' } } ] }); instance.start(); expect(instance.getCurrentStep().isOpen()).toBe(true); // Subsequent calls to the getter return the same object const result1 = instance.getCurrentStep()._getResolvedAttachToOptions(); expect(result1).not.toBeNull(); instance.next(); const result2 = instance.getById('step1')._getResolvedAttachToOptions(); expect(result1).toEqual(result2); }); it('can evaluate _getResolvedAttachToOptions before step before-show phase', () => { const instance = new Shepherd.Tour({ steps: [ { text: 'step 1', attachTo: { element: () => {}, on: 'auto' } }, { text: 'step 2', attachTo: { element: () => {}, on: 'auto' }, id: 'step2' } ] }); instance.start(); expect(instance.getById('step2')._getResolvedAttachToOptions()).toEqual({ element: undefined, on: 'auto' }); }); }); describe('tabIndex preservation', () => { let instance; let testElement; beforeEach(() => { // Create a test element testElement = document.createElement('div'); testElement.id = 'tabindex-test-element'; document.body.appendChild(testElement); instance = new Shepherd.Tour({ steps: [ { id: 'test-step', text: 'Test step', attachTo: { element: '#tabindex-test-element', on: 'top' } } ] }); }); afterEach(() => { instance.complete(); testElement?.remove(); }); it('stores and restores original tabIndex when element has no tabindex attribute', () => { // Initially, the element should have no tabindex attribute expect(testElement.hasAttribute('tabindex')).toBe(false); // Start the tour instance.start(); // During the tour, tabIndex should be set to 0 expect(testElement.tabIndex).toBe(0); expect(testElement.getAttribute('tabindex')).toBe('0'); // Hide the step instance.getCurrentStep().hide(); // After hiding, the tabindex attribute should be removed expect(testElement.hasAttribute('tabindex')).toBe(false); }); it('stores and restores original tabIndex when element has tabindex="-1"', () => { // Set tabindex to -1 initially testElement.setAttribute('tabindex', '-1'); expect(testElement.getAttribute('tabindex')).toBe('-1'); // Start the tour instance.start(); // During the tour, tabIndex should be set to 0 expect(testElement.tabIndex).toBe(0); expect(testElement.getAttribute('tabindex')).toBe('0'); // Hide the step instance.getCurrentStep().hide(); // After hiding, tabIndex should be restored to -1 expect(testElement.getAttribute('tabindex')).toBe('-1'); }); it('stores and restores original tabIndex when element has tabindex="5"', () => { // Set tabindex to 5 initially testElement.setAttribute('tabindex', '5'); expect(testElement.getAttribute('tabindex')).toBe('5'); // Start the tour instance.start(); // During the tour, tabIndex should be set to 0 expect(testElement.tabIndex).toBe(0); expect(testElement.getAttribute('tabindex')).toBe('0'); // Hide the step instance.getCurrentStep().hide(); // After hiding, tabIndex should be restored to 5 expect(testElement.getAttribute('tabindex')).toBe('5'); }); it('restores tabIndex when step is destroyed', () => { // Set tabindex to -1 initially testElement.setAttribute('tabindex', '-1'); // Start the tour instance.start(); // During the tour, tabIndex should be set to 0 expect(testElement.getAttribute('tabindex')).toBe('0'); // Destroy the step instance.getCurrentStep().destroy(); // After destroying, tabIndex should be restored to -1 expect(testElement.getAttribute('tabindex')).toBe('-1'); }); it('handles multiple show/hide cycles correctly', () => { // Set tabindex to 2 initially testElement.setAttribute('tabindex', '2'); // Start the tour (first show) instance.start(); expect(testElement.getAttribute('tabindex')).toBe('0'); // Hide the step instance.getCurrentStep().hide(); expect(testElement.getAttribute('tabindex')).toBe('2'); // Show again instance.getCurrentStep().show(); expect(testElement.getAttribute('tabindex')).toBe('0'); // Hide again instance.getCurrentStep().hide(); expect(testElement.getAttribute('tabindex')).toBe('2'); }); it('only stores the original value once, not intermediate values', () => { // Set tabindex to 3 initially testElement.setAttribute('tabindex', '3'); // Start the tour instance.start(); expect(testElement.getAttribute('tabindex')).toBe('0'); // Manually change tabIndex (simulating some other code changing it) testElement.setAttribute('tabindex', '7'); // Hide the step - should restore to original value (3), not intermediate (7) instance.getCurrentStep().hide(); expect(testElement.getAttribute('tabindex')).toBe('3'); }); }); }); ================================================ FILE: shepherd.js/test/unit/tour.spec.js ================================================ import _ from 'lodash'; import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; import Shepherd from '../../src/shepherd'; import ResizeObserver from 'resize-observer-polyfill'; import { setupTooltip } from '../../src/utils/floating-ui'; import { offset } from '@floating-ui/dom'; const { Step } = Shepherd; // since importing non UMD, needs assignment window.Shepherd = Shepherd; window.ResizeObserver = ResizeObserver; const DEFAULT_STEP_CLASS = 'shepherd-step-tooltip'; describe('Tour | Top-Level Class', function () { let instance, shouldShowStep; const showOn = () => { return true; }; const when = { show() {} }; const offsetMiddleware = offset({ crossAxis: 32 }); const defaultStepOptions = { classes: DEFAULT_STEP_CLASS, scrollTo: true, floatingUIOptions: { middleware: [offsetMiddleware] }, showOn, when }; afterEach(() => { instance.complete(); }); describe('constructor', function () { it('creates a new tour instance', function () { instance = new Shepherd.Tour({ defaultStepOptions }); expect(instance instanceof Shepherd.Tour).toBe(true); }); it('returns the default options on the instance', function () { instance = new Shepherd.Tour({ defaultStepOptions, steps: [ { scrollTo: false } ] }); expect(instance.options.defaultStepOptions).toEqual({ classes: DEFAULT_STEP_CLASS, scrollTo: true, floatingUIOptions: { middleware: [offsetMiddleware] }, showOn, when }); }); it('sets the correct bindings', function () { instance = new Shepherd.Tour({ defaultStepOptions }); const bindings = Object.keys(instance.bindings); const tourEvents = [ 'complete', 'cancel', 'start', 'show', 'active', 'inactive' ]; // Check that all bindings are included const difference = _.difference(tourEvents, bindings); expect(difference.length, 'all tour events bound').toBe(0); }); it('generates a unique `id` property, optionally based upon the `tourName` option', function () { const instance1 = new Shepherd.Tour(); const instance2 = new Shepherd.Tour({ tourName: 'select-avatar' }); expect(instance1.id.startsWith('tour--')).toBe(true); expect(instance2.id.startsWith('select-avatar--')).toBe(true); const [uniqueId1] = instance1.id.split('--')[1]; const uniqueId2 = instance2.id.split('--')[1]; expect(uniqueId1).not.toBe(uniqueId2); }); }); describe('methods', () => { beforeEach(() => { shouldShowStep = false; instance = new Shepherd.Tour({ defaultStepOptions }); instance.addStep({ id: 'test', title: 'This is a test step for our tour' }); instance.addStep({ id: 'test2', title: 'Another Step' }); instance.addStep({ classes: 'skipped', id: 'skipped-step', title: 'This step should be skipped', showOn() { return shouldShowStep; } }); instance.addStep({ id: 'test3', title: 'Yet, another test step' }); }); describe('.addStep()', function () { it('adds tour steps', function () { expect(instance.steps.length).toBe(4); expect( instance.getById('test').options.classes, 'classes passed to step options' ).toBe(DEFAULT_STEP_CLASS); }); it('adds tour steps at specified index', function () { expect(instance.steps[1].options.id, 'original step at index 1').toBe( 'test2' ); instance.addStep( { id: 'index-test', title: 'Test index insertion' }, 1 ); expect(instance.steps.length).toBe(5); expect(instance.steps[1].options.id, 'step inserted at index 1').toBe( 'index-test' ); }); it('adds steps with only one arg', function () { const step = instance.addStep({ id: 'one-arg' }); expect(instance.steps.length).toBe(5); expect(step.id, 'id applied to step with just one arg').toBe('one-arg'); }); it('adds steps that are already Step instances', function () { const step = instance.addStep( new Step(instance, { id: 'already-a-step' }) ); expect(instance.steps.length).toBe(5); expect(step.id, 'id applied to step instance').toBe('already-a-step'); expect(step.tour, 'tour is set to `this`').toBe(instance); }); }); describe('.getById()', function () { it('returns the step by ID with the right title', function () { expect(instance.steps.length).toBe(4); expect(instance.getById('test3').options.title).toBe( 'Yet, another test step' ); }); }); describe('.start()', function () { it('starts a tour that is the current active', function () { instance.start(); expect(instance).toBe(Shepherd.activeTour); }); }); describe('.getCurrentStep()', function () { it('returns the currently shown step', function () { instance.start(); expect(instance.getCurrentStep().id).toBe('test'); }); }); describe('.hide()', function () { it('hides the current step', () => { const [firstStep] = instance.steps; const hideStepSpy = vi.spyOn(firstStep, 'hide'); expect(firstStep.isOpen()).toBe(false); instance.start(); expect(firstStep.isOpen()).toBe(true); instance.hide(); expect(firstStep.isOpen()).toBe(false); expect(hideStepSpy).toHaveBeenCalledTimes(1); }); }); describe('isActive', function () { it('computes whether or not `Shepherd.activeTour` equals the instance', function () { Shepherd.activeTour = ''; expect(instance.isActive()).toBe(false); Shepherd.activeTour = instance; expect(instance.isActive()).toBe(true); Shepherd.activeTour = ''; expect(instance.isActive()).toBe(false); }); }); describe('.next()/.back()', function () { it('goes to the next/previous steps', function () { instance.start(); instance.next(); expect(instance.getCurrentStep().id).toBe('test2'); instance.back(); expect(instance.getCurrentStep().id).toBe('test'); }); it('next completes tour when on last step', function () { let completeFired = false; instance.on('complete', () => { completeFired = true; }); instance.start(); instance.show('test3'); expect(instance.getCurrentStep().id).toBe('test3'); instance.next(); expect( completeFired, 'complete is called when next is clicked on last step' ).toBeTruthy(); }); }); describe('.cancel()', function () { it('shows confirm dialog when confirmCancel is true', function () { instance = new Shepherd.Tour({ defaultStepOptions, confirmCancel: true, confirmCancelMessage: 'Confirm cancel?' }); instance.addStep({ id: 'test', title: 'This is a test step for our tour' }); let inactiveFired = false; instance.on('inactive', () => { inactiveFired = true; }); window.confirm = vi.fn(); const windowConfirmStub = vi .spyOn(window, 'confirm') .mockImplementation(() => false); instance.start(); expect(instance, 'activeTour is set to our tour').toBe( Shepherd.activeTour ); instance.cancel(); expect(windowConfirmStub).toHaveBeenCalled(); expect( inactiveFired, 'tour still going, since confirm returned false' ).toBeFalsy(); windowConfirmStub.mockImplementation(() => true); instance.cancel(); expect(windowConfirmStub).toHaveBeenCalled(); expect( inactiveFired, 'tour inactive, since confirm returned true' ).toBeTruthy(); }); it('tears down tour on cancel', function () { let inactiveFired = false; instance.on('inactive', () => { inactiveFired = true; }); instance.start(); expect(instance, 'activeTour is set to our tour').toBe( Shepherd.activeTour ); instance.cancel(); expect(Shepherd.activeTour, 'activeTour is torn down').toBeFalsy(); expect(inactiveFired, 'inactive event fired').toBeTruthy(); }); it('triggers cancel event when cancel function is called', function () { let cancelFired = false; instance.on('cancel', () => { cancelFired = true; }); instance.start(); instance.cancel(); expect(cancelFired, 'cancel event fired').toBeTruthy(); }); [ { status: 'normal', title: 'whether cancel depends on function return value' }, { status: 'async', title: 'whether cancel will wait for the value returned from the function' } ].map(({ status, title }) => { it('when confirmCancel is function, ' + title, async function () { const myMock = vi.fn(); if (status === 'async') { myMock .mockImplementationOnce(() => Promise.resolve(false)) .mockImplementationOnce(() => Promise.resolve(true)); } else { myMock.mockReturnValueOnce(false).mockReturnValueOnce(true); } instance = new Shepherd.Tour({ defaultStepOptions, confirmCancel: myMock, confirmCancelMessage: 'Confirm cancel?' }); instance.addStep({ id: 'test', title: 'This is a test step for our tour' }); let inactiveFired = false; instance.on('cancel', () => { inactiveFired = true; }); instance.start(); expect(instance, 'activeTour is set to our tour').toBe( Shepherd.activeTour ); await instance.cancel(); expect( myMock.mock.calls.length, 'confirmCancel callback called once' ).toBe(1); expect( await myMock.mock.results[0].value, 'confirmCancel callback returns false' ).toBe(false); expect( inactiveFired, 'tour still going, since confirmCancel callback returned false' ).toBeFalsy(); await instance.cancel(); expect( myMock.mock.calls.length, 'confirmCancel callback called twice' ).toBe(2); expect( await myMock.mock.results[1].value, 'confirmCancel callback returns true' ).toBe(true); expect( inactiveFired, 'tour inactive, since confirm returned true' ).toBeTruthy(); }); }); }); describe('.complete()', function () { it('triggers complete event when complete function is called', function () { let completeFired = false; instance.on('complete', () => { completeFired = true; }); instance.start(); instance.complete(); expect(completeFired, 'complete event fired').toBeTruthy(); }); it('calls `done()`', () => { const doneSpy = vi.spyOn(instance, '_done'); expect(doneSpy).toHaveBeenCalledTimes(0); instance.start(); instance.complete(); expect(doneSpy).toHaveBeenCalledTimes(1); }); }); describe('._done()', function () { it('tears down the active tour', function () { instance.start(); expect(instance, 'activeTour is set to our tour').toBe( Shepherd.activeTour ); instance.complete(); expect( Shepherd.activeTour, '`activeTour` is torn down and removed from the `Shepherd` global' ).toBe(null); }); it('removes any of its `Step` tooltip elements from the DOM', function () { const testStep = { id: 'element-removal-test', classes: 'element-removal-test', title: 'This is a test step for our tour' }; instance.addStep(testStep); instance.start(); instance.show('element-removal-test'); expect( document.querySelector('.element-removal-test'), 'a step is rendered in the DOM after the tour starts' ).toBeInTheDocument(); instance.complete(); expect( document.querySelector('.element-removal-test'), 'steps are removed from the DOM after the tour completes' ).not.toBeInTheDocument(); }); it('fires the `inactive` event', function () { let inactiveFired = false; instance.on('inactive', () => { inactiveFired = true; }); instance.start(); expect( inactiveFired, 'inactive event does not fire before `complete()`' ).toBe(false); instance.complete(); expect(inactiveFired, 'inactive event fires after `complete()`').toBe( true ); }); }); describe('.removeStep()', function () { it('removes the step when passed the id', function () { instance.start(); expect(instance.steps.length).toBe(4); instance.removeStep('test2'); expect(instance.steps.length).toBe(3); }); it('hides the step before removing', function () { let hideFired = false; instance.start(); expect(instance.steps.length).toBe(4); const step = instance.getById('test'); step.on('hide', () => { hideFired = true; }); instance.removeStep('test'); expect(instance.steps.length).toBe(3); expect( hideFired, 'hide is fired before step is destroyed' ).toBeTruthy(); }); }); describe('.show()', function () { it('show short-circuits if next is not found', function () { let showFired = false; instance.start(); instance.on('show', () => { showFired = true; }); instance.show('not-a-real-key'); expect( showFired, 'showFired is false because show short circuits' ).toBeFalsy(); }); it('showOn determines which steps to skip', function () { instance.start(); expect(instance.getCurrentStep().id).toBe('test'); instance.next(); expect(instance.getCurrentStep().id).toBe('test2'); instance.next(); expect(instance.getCurrentStep().id).toBe('test3'); expect( instance.getCurrentStep().id, 'step skipped because `showOn` returns false' ).not.toBe('skipped-step'); instance.back(); shouldShowStep = true; instance.next(); expect( instance.getCurrentStep().id, 'step shown because `showOn` returns true' ).toBe('skipped-step'); }); it('fires cancel when going back past first step with showOn returning false', function () { let cancelFired = false; const tourInstance = new Shepherd.Tour(); tourInstance.addStep({ id: 'first-hidden', title: 'This step is always hidden', showOn() { return false; } }); tourInstance.addStep({ id: 'second', title: 'Second step' }); tourInstance.on('cancel', () => { cancelFired = true; }); tourInstance.start(); expect( tourInstance.getCurrentStep().id, 'first hidden step is skipped on start' ).toBe('second'); tourInstance.back(); expect( cancelFired, 'cancel is fired when going back past all shown steps' ).toBeTruthy(); expect( Shepherd.activeTour, 'activeTour is null after cancel' ).toBeNull(); }); it("sets the instance on `Shepherd.activeTour` if it's not already set", function () { const setupFuncSpy = vi.spyOn(instance, '_setupActiveTour'); Shepherd.activeTour = null; expect(setupFuncSpy).toHaveBeenCalledTimes(0); instance.start(); expect(setupFuncSpy).toHaveBeenCalledTimes(1); expect(Shepherd.activeTour).toBe(instance); }); }); }); describe('floatingUIOptions', () => { it('applies the default modifiers from defaultStepOptions', function () { instance = new Shepherd.Tour({ defaultStepOptions }); const step = instance.addStep({ id: 'test', title: 'This is a test step for our tour' }); instance.start(); const floatingUIOptions = setupTooltip(step); expect(floatingUIOptions.middleware.length).toBe(1); }); it('adds a step modifer to default modifiers', function () { instance = new Shepherd.Tour({ defaultStepOptions }); const step = instance.addStep({ id: 'test', title: 'This is a test step for our tour', floatingUIOptions: { middleware: [{ name: 'foo', options: 'bar', fn: (args) => args }] } }); instance.start(); const floatingUIOptions = setupTooltip(step); expect(floatingUIOptions.middleware.length).toBe(2); }); it('correctly changes modifiers when going from centered to attached', function () { const div = document.createElement('div'); div.classList.add('modifiers-test'); document.body.appendChild(div); instance = new Shepherd.Tour({ defaultStepOptions }); const centeredStep = instance.addStep({ id: 'centered', title: 'This is a centered step for our tour', floatingUIOptions: { middleware: [{ name: 'foo', options: 'bar', fn: (args) => args }] } }); const attachedStep = instance.addStep({ attachTo: { element: '.modifiers-test', on: 'top' }, id: 'attached', title: 'This is an attached step for our tour', floatingUIOptions: { middleware: [{ name: 'foo', options: 'bar', fn: (args) => args }] } }); instance.start(); const centeredOptions = setupTooltip(centeredStep); const centeredMiddlewareNames = centeredOptions.middleware.map( ({ name }) => name ); expect(centeredOptions.middleware.length).toBe(2); expect(centeredMiddlewareNames.includes('offset')).toBe(true); expect(centeredMiddlewareNames.includes('foo')).toBe(true); expect(centeredMiddlewareNames.includes('arrow')).toBe(false); instance.next(); const options = setupTooltip(attachedStep); const middlewareNames = options.middleware.map(({ name }) => name); expect(options.middleware.length).toBe(5); expect(middlewareNames.includes('offset')).toBe(true); expect(middlewareNames.includes('foo')).toBe(true); expect(middlewareNames.includes('shift')).toBe(true); expect(middlewareNames.includes('arrow')).toBe(true); document.body.removeChild(div); }); it('renders step in stepsContainer', () => { const stepsContainer = document.createElement('div'); stepsContainer.setAttribute('id', 'customStepTarget'); document.body.appendChild(stepsContainer); expect(stepsContainer).toBeInTheDocument(); instance = new Shepherd.Tour({ stepsContainer, defaultStepOptions }); const step = instance.addStep({ title: 'This is a test step for our tour' }); instance.start(); const stepElement = step.getElement(); expect(stepsContainer.contains(stepElement)).toBe(true); }); it('adds autoPlacement middleware when attachTo.on is set to auto', () => { const div = document.createElement('div'); div.classList.add('modifiers-test'); document.body.appendChild(div); instance = new Shepherd.Tour(); const step1 = instance.addStep({ id: 'test', title: 'This is a test step for our tour', attachTo: { element: '.modifiers-test', on: 'auto' } }); const step2 = instance.addStep({ id: 'test', title: 'This is a test step for our tour', attachTo: { element: '.modifiers-test', on: 'auto-start' } }); const step3 = instance.addStep({ id: 'test', title: 'This is a test step for our tour', attachTo: { element: '.modifiers-test', on: 'auto-end' } }); instance.start(); const step1FloatingUIOptions = setupTooltip(step1); const step1MiddlewareNames = step1FloatingUIOptions.middleware.map( ({ name }) => name ); const step1PlacementMiddleware = step1FloatingUIOptions.middleware.find( ({ name }) => name === 'autoPlacement' ); expect(step1MiddlewareNames.includes('autoPlacement')).toBe(true); expect(step1MiddlewareNames.includes('flip')).toBe(false); expect(step1PlacementMiddleware.options.alignment).toBe(null); instance.next(); const step2FloatingUIOptions = setupTooltip(step2); const step2PlacementMiddleware = step2FloatingUIOptions.middleware.find( ({ name }) => name === 'autoPlacement' ); expect(step2PlacementMiddleware.options.alignment).toBe('start'); instance.next(); const step3FloatingUIOptions = setupTooltip(step3); const step3PlacementMiddleware = step3FloatingUIOptions.middleware.find( ({ name }) => name === 'autoPlacement' ); expect(step3PlacementMiddleware.options.alignment).toBe('end'); }); }); describe('shepherdModalOverlayContainer', function () { beforeEach(() => { instance = new Shepherd.Tour({ useModalOverlay: true }); }); it('appends shepherdModalOverlayContainer to DOM when it does not exist', async () => { expect( document.querySelector('.shepherd-modal-overlay-container') ).not.toBeInTheDocument(); instance.start(); setTimeout(() => { expect( document.querySelector('.shepherd-modal-overlay-container') ).toBeInTheDocument(); }, 200); }); it('removes shepherdModalOverlayContainer from DOM when it is complete', () => { instance.start(); setTimeout(() => { expect( document.querySelector('.shepherd-modal-overlay-container') ).toBeInTheDocument(); }, 200); instance.complete(); expect( document.querySelector('.shepherd-modal-overlay-container') ).not.toBeInTheDocument(); }); it('renders modal in modalContainer', () => { const modalContainer = document.createElement('div'); modalContainer.setAttribute('id', 'customModalTarget'); document.body.appendChild(modalContainer); expect(modalContainer).toBeInTheDocument(); instance = new Shepherd.Tour({ modalContainer, useModalOverlay: true }); instance.addStep({ title: 'This is a test step for our tour' }); instance.start(); const modalElement = instance.modal.getElement(); expect(modalContainer.contains(modalElement)).toBe(true); }); }); }); ================================================ FILE: shepherd.js/test/unit/utils/bind.spec.js ================================================ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; import { bindAdvance } from '../../../src/utils/bind'; import { Step } from '../../../src/step'; describe('Bind Utils', function () { describe('bindAdvance()', () => { let event, link; let hasAdvanced = false; const advanceOnSelector = 'test-selector'; const advanceOnEventName = 'test-event'; const tourProto = { next() { hasAdvanced = true; } }; beforeEach(() => { event = new Event(advanceOnEventName); link = document.createElement('a'); link.classList.add(advanceOnSelector); link.textContent = 'Click Me 👋'; document.body.appendChild(link); }); afterEach(() => { link.remove(); }); it('triggers the `advanceOn` option via object', () => { const step = new Step(tourProto, { advanceOn: { selector: `.${advanceOnSelector}`, event: advanceOnEventName } }); step.isOpen = () => true; bindAdvance(step); link.dispatchEvent(event); expect(link.classList.contains(advanceOnSelector)).toBe(true); expect(hasAdvanced, '`next()` triggered for advanceOn').toBe(true); }); it('captures events attached to no element', () => { const step = new Step(tourProto, { advanceOn: { event: advanceOnEventName } }); step.isOpen = () => true; bindAdvance(step); document.body.dispatchEvent(event); expect(hasAdvanced, '`next()` triggered for advanceOn').toBeTruthy(); }); it('should support bubbling events for nodes that do not exist yet', () => { const event = new Event('blur'); const step = new Step(tourProto, { text: 'Lorem ipsum dolor: sit amet', advanceOn: { selector: 'a[href="https://example.com"]', event: 'blur' } }); step.isOpen = () => true; bindAdvance(step); document.body.dispatchEvent(event); expect(hasAdvanced, '`next()` triggered for advanceOn').toBeTruthy(); }); it('calls `removeEventListener` when destroyed', () => { return new Promise((done) => { const bodySpy = vi.spyOn(document.body, 'removeEventListener'); const step = new Step(tourProto, { advanceOn: { event: advanceOnEventName } }); step.isOpen = () => true; bindAdvance(step); step.trigger('destroy'); expect(bodySpy).toHaveBeenCalled(); bodySpy.mockRestore(); done(); }); }); }); }); ================================================ FILE: shepherd.js/test/unit/utils/cleanup.spec.js ================================================ import { describe, expect, it } from 'vitest'; import { cleanupSteps } from '../../../src/utils/cleanup'; describe('Cleanup Utils', function () { // Create some elements to use to attach to const firstAttachElement = document.createElement('div'); firstAttachElement.classList.add('first-attach-to'); firstAttachElement.classList.add('shepherd-target-click-disabled'); document.body.appendChild(firstAttachElement); const secondAttachElement = document.createElement('div'); secondAttachElement.classList.add('second-attach-to'); secondAttachElement.classList.add('shepherd-target-click-disabled'); document.body.appendChild(secondAttachElement); // Element with extra highlights const thirdAttachElement = document.createElement('div'); thirdAttachElement.classList.add('third-attach-to'); thirdAttachElement.classList.add('shepherd-target-click-disabled'); document.body.appendChild(thirdAttachElement); // Extra highlight elements for the third step const extraHighlightElement = document.createElement('div'); extraHighlightElement.classList.add('extra-highlight'); extraHighlightElement.classList.add('shepherd-target-click-disabled'); document.body.appendChild(extraHighlightElement); const extraHighlightElement2 = document.createElement('div'); extraHighlightElement2.classList.add('extra-highlight'); extraHighlightElement2.classList.add('shepherd-target-click-disabled'); document.body.appendChild(extraHighlightElement2); const mockedTour = { steps: [ { options: { attachTo: { element: '.first-attach-to', on: 'bottom' }, canClickTarget: false }, // Manually add the target. The tour would do this, if it were a real tour target: firstAttachElement }, { options: { attachTo: { element: '.second-attach-to', on: 'bottom' }, canClickTarget: false }, // Manually add the target. The tour would do this, if it were a real tour target: secondAttachElement }, { options: { attachTo: { element: '.third-attach-to', on: 'bottom' }, canClickTarget: false }, // Manually add the target. The tour would do this, if it were a real tour target: thirdAttachElement, // Add extra highlights _resolvedExtraHighlightElements: [ extraHighlightElement, extraHighlightElement2 ] } ] }; describe('cleanupSteps', function () { it('cleans up steps and removes shepherd-target-click-disabled class', () => { expect(firstAttachElement).toHaveClass('shepherd-target-click-disabled'); expect(secondAttachElement).toHaveClass('shepherd-target-click-disabled'); expect(thirdAttachElement).toHaveClass('shepherd-target-click-disabled'); expect(extraHighlightElement).toHaveClass( 'shepherd-target-click-disabled' ); expect(extraHighlightElement2).toHaveClass( 'shepherd-target-click-disabled' ); cleanupSteps(mockedTour); expect(firstAttachElement).not.toHaveClass( 'shepherd-target-click-disabled' ); expect(secondAttachElement).not.toHaveClass( 'shepherd-target-click-disabled' ); expect(thirdAttachElement).not.toHaveClass( 'shepherd-target-click-disabled' ); expect(extraHighlightElement).not.toHaveClass( 'shepherd-target-click-disabled' ); expect(extraHighlightElement2).not.toHaveClass( 'shepherd-target-click-disabled' ); }); }); }); ================================================ FILE: shepherd.js/test/unit/utils/general.spec.js ================================================ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; import { Step } from '../../../src/step'; import { parseAttachTo, shouldCenterStep, parseExtraHighlights } from '../../../src/utils/general'; import { getFloatingUIOptions } from '../../../src/utils/floating-ui'; describe('General Utils', function () { let optionsElement; beforeEach(() => { optionsElement = document.createElement('div'); optionsElement.classList.add('options-test'); document.body.appendChild(optionsElement); }); afterEach(() => { document.body.removeChild(optionsElement); }); describe('parseAttachTo()', function () { it('fails if element does not exist', function () { const step = new Step( {}, { attachTo: { element: '.element-does-not-exist', on: 'center' } } ); const { element } = parseAttachTo(step); expect(element).toBeFalsy(); }); it('accepts callback function as element', function () { const callback = vi.fn(); const step = new Step( {}, { attachTo: { element: callback, on: 'center' } } ); parseAttachTo(step); expect(callback).toHaveBeenCalled(); }); it('correctly resolves elements when given function that returns a selector', function () { const step = new Step( {}, { attachTo: { element: () => 'body', on: 'center' } } ); const { element } = parseAttachTo(step); expect(element).toBe(document.body); }); it('binds element callback to step', function () { const step = new Step( {}, { attachTo: { element() { expect(this).toBe(step); }, on: 'center' } } ); parseAttachTo(step); }); }); describe('parseExtraHighlights()', function () { it('returns empty array if extraHighlights is not defined', function () { const step = new Step({}, {}); const highlights = parseExtraHighlights(step); expect(highlights).toEqual([]); }); it('returns empty array if extraHighlights is an empty array', function () { const step = new Step({}, { extraHighlights: [] }); const highlights = parseExtraHighlights(step); expect(highlights).toEqual([]); }); it('resolves extraHighlights selectors to HTMLElements', function () { const step = new Step({}, { extraHighlights: ['.options-test'] }); const highlights = parseExtraHighlights(step); expect(highlights).toEqual([optionsElement]); }); it('returns empty array if no elements match the extraHighlights selectors', function () { const step = new Step({}, { extraHighlights: ['.non-existent-class'] }); const highlights = parseExtraHighlights(step); expect(highlights).toEqual([]); }); }); describe('floatingUIOptions', function () { it('middleware options are passed in last', function () { const step = new Step( {}, { attachTo: { element: '.options-test', on: 'right' }, floatingUIOptions: { middleware: [ { name: 'preventOverflow', options: { altAxis: false } } ] } } ); const floatingUIOptions = getFloatingUIOptions( step.options.attachTo, step ); // Shepherd pushes in flip and shift by default, so this is 3rd expect(floatingUIOptions.middleware[2].options.altAxis).toBe(false); }); it('positioning strategy is explicitly set', function () { const step = new Step( {}, { attachTo: { element: '.options-test', on: 'center' }, options: { floatingUIOptions: { strategy: 'absolute' } } } ); const floatingUIOptions = getFloatingUIOptions( step.options.attachTo, step ); expect(floatingUIOptions.strategy).toBe('absolute'); }); }); describe('shouldCenterStep()', () => { it('Returns true when resolved attachTo options are falsy', () => { const emptyObjAttachTo = {}; const emptyArrAttachTo = []; const nullAttachTo = null; // FAILS Cannot read properties of null (reading 'element') const undefAttachTo = undefined; // FAILS Cannot read properties of undefined (reading 'element') expect(shouldCenterStep(emptyObjAttachTo)).toBe(true); expect(shouldCenterStep(emptyArrAttachTo)).toBe(true); expect(shouldCenterStep(nullAttachTo)).toBe(true); expect(shouldCenterStep(undefAttachTo)).toBe(true); }); it('Returns false when element and on properties are truthy', () => { const testAttachTo = { element: '.pseudo', on: 'right' }; expect(shouldCenterStep(testAttachTo)).toBe(false); }); it('Returns true when element property is null', () => { const elementAttachTo = { element: null }; // FAILS expect(shouldCenterStep(elementAttachTo)).toBe(true); }); }); }); ================================================ FILE: shepherd.js/tsconfig.json ================================================ { "$schema": "https://json.schemastore.org/tsconfig", "compilerOptions": { "target": "es2021", "module": "esnext", "moduleResolution": "bundler", // We don't want to include types dependencies in our compiled output, so tell TypeScript // to enforce using `import type` instead of `import` for Types. "verbatimModuleSyntax": true, "allowJs": true, "strict": true, "noUncheckedIndexedAccess": true, "allowArbitraryExtensions": true, "allowSyntheticDefaultImports": false, "allowImportingTsExtensions": true, "esModuleInterop": true, // --- Lint-style rules // TypeScript also supplies some lint-style checks; nearly all of them are // better handled by ESLint with the `@typescript-eslint`. This one is more // like a safety check, though, so we leave it on. "noPropertyAccessFromIndexSignature": true, // --- Compilation/integration settings // Setting `noEmitOnError` here allows tools trying to respect the tsconfig // to still emit code without breaking on errors. // Errors are still reported in the CLI when running `tsc`, // but the errors won't prevent code from being emitted. // This helps hasten development by allowing devs to prototype before coming // to a decision on what they want their types to be. "noEmitOnError": false, // We use Babel for emitting runtime code, because it's very important that // we always and only use the same transpiler for non-stable features. // If you were to change this to `true`, it could lead to accidentally // generating code with `tsc` instead of Babel, and could thereby // result in broken code at runtime. "emitDeclarationOnly": true, "declaration": true, "declarationMap": true, "declarationDir": "dist", "inlineSourceMap": true, "inlineSources": true, "skipLibCheck": true, "paths": { "src/*": ["./src/*"] } }, "include": ["src/**/*"], "exclude": ["node_modules", "dist"] } ================================================ FILE: shepherd.js/vitest.config.ts ================================================ import { defineConfig } from 'vitest/config'; export default defineConfig({ test: { globals: true, environment: 'happy-dom', setupFiles: ['./test/unit/setupTests.js'], coverage: { provider: 'v8', reporter: ['text', 'lcov', 'html'], reportsDirectory: './test/coverage', include: ['src/**/*.ts'], exclude: [ '**/*.spec.{js,ts}', '**/*.test.{js,ts}', '**/node_modules/**', '**/dist/**', '**/tmp/**', '**/test/**' ] } }, resolve: { alias: { 'shepherd.js': './src' }, conditions: ['browser'] }, define: { 'import.meta.vitest': undefined, 'import.meta.env.SSR': false } }); ================================================ FILE: stderr.log ================================================ Warning: unknown package "shepherd-docs" Warning: unknown package "landing" Warning: unknown package "shepherd-docs" Warning: unknown package "shepherd-docs" Warning: unknown package "shepherd-docs" Warning: unknown package "landing" Warning: unknown package "cypress-tests" Warning: unknown package "unit-tests" Warning: unknown package "landing" Warning: unknown package "cypress-tests" Warning: unknown package "landing" Warning: unknown package "shepherd-docs" Warning: unknown package "landing" Warning: unknown package "shepherd-docs" Warning: unknown package "landing" Warning: unknown package "shepherd-docs" Warning: unknown package "unit-tests" Warning: unknown package "shepherd-docs" Warning: unknown package "landing" Warning: unknown package "unit-tests" Warning: unknown package "landing" Warning: unknown package "landing" (node:2262) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead. (Use `node --trace-deprecation ...` to show where the warning was created) Warning: unknown package "shepherd-docs" Warning: unknown package "unit-tests" (node:2337) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead. (Use `node --trace-deprecation ...` to show where the warning was created) Warning: unknown package "shepherd-docs" Warning: unknown package "unit-tests" (node:2278) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead. (Use `node --trace-deprecation ...` to show where the warning was created) (node:2403) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead. (Use `node --trace-deprecation ...` to show where the warning was created) Warning: unknown package "cypress-tests" Warning: unknown package "landing" (node:2504) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead. (Use `node --trace-deprecation ...` to show where the warning was created) Warning: unknown package "shepherd-docs" Warning: unknown package "cypress-tests" Warning: unknown package "unit-tests" Warning: unknown package "shepherd-docs" Warning: unknown package "landing" Warning: unknown package "cypress-tests" Warning: unknown package "unit-tests"