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