Add support for HTML attributes on buttons and cancelIcon (#3370)

* Add support for HTML attributes on buttons and cancelIcon

* Update usage.md

* Update usage.md

Author: RobbieTheWagner

docs-src/src/content/docs/guides/usage.md

@@ -4,8 +4,8 @@ title: Usage
 
 ### Rollup/Webpack Based Builds
 
-The latest versions of Rollup and Webpack support ES6 imports. Shepherd ships as an ES module
-which should allow you to import using standard ES import syntax.
+The latest versions of Rollup and Webpack support ES6 imports. Shepherd ships as
+an ES module which should allow you to import using standard ES import syntax.
 
 i.e.
 
@@ -25,8 +25,8 @@ const tour = new Shepherd.Tour({
 });
 ```
 
-The `defaultStepOptions` option allows you to specify any options which should be applied
-to all this tour's steps by default.
+The `defaultStepOptions` option allows you to specify any options which should
+be applied to all this tour's steps by default.
 
 Next, add your steps:
 
@@ -54,7 +54,10 @@ Finally, to start the tour, just call `start` on your `Tour` instance:
 tour.start();
 ```
 
-If you need to remove a step from your tour, call `removeStep` on your `Tour` instance. If the step currently being displayed is the one you're removing, and there are steps left in the tour, then the first one will be shown, otherwise, the tour will be cancelled.
+If you need to remove a step from your tour, call `removeStep` on your `Tour`
+instance. If the step currently being displayed is the one you're removing, and
+there are steps left in the tour, then the first one will be shown, otherwise,
+the tour will be cancelled.
 
 ```javascript
 tour.removeStep('example-step');
@@ -73,12 +76,14 @@ occurring in _any_ tour:
 
 - `Shepherd.on(eventName, handler, [context])`: Bind an event
 - `Shepherd.off(eventName, [handler])`: Unbind an event
-- `Shepherd.once(eventName, handler, [context])`: Bind just the next instance of an event
+- `Shepherd.once(eventName, handler, [context])`: Bind just the next instance of
+  an event
 
 ##### Events
 
-The global Shepherd fires the following events whenever a `Tour` instance fires them. It adds to the object passed to the
-event handlers a `tour` key pointing to the instance which fired the event:
+The global Shepherd fires the following events whenever a `Tour` instance fires
+them. It adds to the object passed to the event handlers a `tour` key pointing
+to the instance which fired the event:
 
 - `complete`
 - `cancel`
@@ -100,7 +105,8 @@ For multiple events, you can use something like:
 
 ##### Current Tour
 
-The global `Shepherd` includes a property which is always set to the currently active tour, or null if there is no active tour:
+The global `Shepherd` includes a property which is always set to the currently
+active tour, or null if there is no active tour:
 
 - `Shepherd.activeTour`
 
@@ -118,25 +124,37 @@ const myTour = new Shepherd.Tour(options);
 
 ##### Tour Options
 
-- `classPrefix`: The prefix to add to the `shepherd-enabled` and `shepherd-target` class names as well as the `data-shepherd-step-id`.
+- `classPrefix`: The prefix to add to the `shepherd-enabled` and
+  `shepherd-target` class names as well as the `data-shepherd-step-id`.
 - `confirmCancel`:
   - If true, will issue a `window.confirm` before cancelling
-  - If it is a function(support Async Function), it will be called and wait for the return value, and will only be cancelled if the value returned is true
+  - If it is a function(support Async Function), it will be called and wait for
+    the return value, and will only be cancelled if the value returned is true
 - `confirmCancelMessage`: The message to display in the confirm dialog
 - `defaultStepOptions`: Default options for Steps created through `addStep`
-- `exitOnEsc`: Exiting the tour with the escape key will be enabled unless this is explicitly set to `false`.
-- `keyboardNavigation`: Navigating the tour via left and right arrow keys will be enabled unless this is explicitly set to `false`.
-- `stepsContainer` An optional container element for the steps. If not set, the steps will be appended to `document.body`.
-- `modalContainer` An optional container element for the modal. If not set, the modal will be appended to `document.body`.
-- `steps`: An array of step options objects or Step instances to initialize the tour with.
-- `tourName`: An optional "name" for the tour. This will be appended to the the tour's
-  dynamically generated `id` property.
-- `useModalOverlay`: Whether or not steps should be placed above a darkened modal overlay. If true, the overlay will create an opening around the target element so that it can remain interactive.
+- `exitOnEsc`: Exiting the tour with the escape key will be enabled unless this
+  is explicitly set to `false`.
+- `keyboardNavigation`: Navigating the tour via left and right arrow keys will
+  be enabled unless this is explicitly set to `false`.
+- `stepsContainer` An optional container element for the steps. If not set, the
+  steps will be appended to `document.body`.
+- `modalContainer` An optional container element for the modal. If not set, the
+  modal will be appended to `document.body`.
+- `steps`: An array of step options objects or Step instances to initialize the
+  tour with.
+- `tourName`: An optional "name" for the tour. This will be appended to the the
+  tour's dynamically generated `id` property.
+- `useModalOverlay`: Whether or not steps should be placed above a darkened
+  modal overlay. If true, the overlay will create an opening around the target
+  element so that it can remain interactive.
 
 ##### Tour Methods
 
-- `addStep(options)`: Creates a new Step object with options, and returns the `Step` instance it created. If the options hash doesn't include an `id`, one will be generated.
-  You can also pass an existing `Step` instance rather than `options`, but note that Shepherd does not support a Step being attached to multiple Tours.
+- `addStep(options)`: Creates a new Step object with options, and returns the
+  `Step` instance it created. If the options hash doesn't include an `id`, one
+  will be generated. You can also pass an existing `Step` instance rather than
+  `options`, but note that Shepherd does not support a Step being attached to
+  multiple Tours.
 - `addSteps([Steps])`: Add multiple steps to the tour
 - `getById(id)`: Return a step with a specific id
 - `isActive()`: Check if the tour is active
@@ -145,7 +163,8 @@ const myTour = new Shepherd.Tour(options);
 - `cancel()`: Trigger cancel on the current step, hiding it without advancing
 - `complete()`: Calls \_done() triggering the `complete` event
 - `hide()`: Hide the current step
-- `show([id])`: Show the step specified by id (if it's a string), or index (if it's a number) provided. Defaults to the first step.
+- `show([id])`: Show the step specified by id (if it's a string), or index (if
+  it's a number) provided. Defaults to the first step.
 - `start()`: Show the first step and begin the tour
 - `getCurrentStep()`: Returns the currently shown step
 - `removeStep(id)`: Removes the step from the tour
@@ -161,8 +180,8 @@ const myTour = new Shepherd.Tour(options);
 - `show`: Triggered with a hash of the `step` and the `previous` step
 - `start`
 
-Steps are instances of the Step object. They are generally created by the `Tour::addStep` method, which returns the `Step` instance it
-created.
+Steps are instances of the Step object. They are generally created by the
+`Tour::addStep` method, which returns the `Step` instance it created.
 
 #### Steps
 
@@ -171,12 +190,18 @@ created.
 - `text`: The text in the body of the step. It can be one of three types:
   - HTML string
   - `HTMLElement` object
-  - `Function` to be executed when the step is built. It must return one the two options above.
+  - `Function` to be executed when the step is built. It must return one the two
+    options above.
 - `title`: The step's title. It becomes an `h3` at the top of the step.
-- `attachTo`: The element the step should be attached to on the page. An object with properties `element` and `on`.
-  - `element`: An element selector string, a DOM element, or a function (returning a selector, a DOM element, `null` or `undefined`).
-  - `on`: The optional direction to place the Floating UI tooltip relative to the element.
-    - Possible string values: 'auto', 'auto-start', 'auto-end', 'top', 'top-start', 'top-end', 'bottom', 'bottom-start', 'bottom-end', 'right', 'right-start', 'right-end', 'left', 'left-start', 'left-end'
+- `attachTo`: The element the step should be attached to on the page. An object
+  with properties `element` and `on`.
+  - `element`: An element selector string, a DOM element, or a function
+    (returning a selector, a DOM element, `null` or `undefined`).
+  - `on`: The optional direction to place the Floating UI tooltip relative to
+    the element.
+    - Possible string values: 'auto', 'auto-start', 'auto-end', 'top',
+      'top-start', 'top-end', 'bottom', 'bottom-start', 'bottom-end', 'right',
+      'right-start', 'right-end', 'left', 'left-start', 'left-end'
 
 ```js
 const new Step(tour, {
@@ -185,16 +210,20 @@ const new Step(tour, {
 });
 ```
 
-If you don’t specify an `attachTo` the element will appear in the middle of the screen. The same will happen if your
-`attachTo.element` callback returns `null`, `undefined`, or a selector that does not exist in the DOM.
+If you don’t specify an `attachTo` the element will appear in the middle of the
+screen. The same will happen if your `attachTo.element` callback returns `null`,
+`undefined`, or a selector that does not exist in the DOM.
 
-If you omit the `on` portion of `attachTo`, the element will still be highlighted, but the tooltip will appear
-in the middle of the screen, without an arrow pointing to the target.
+If you omit the `on` portion of `attachTo`, the element will still be
+highlighted, but the tooltip will appear in the middle of the screen, without an
+arrow pointing to the target.
 
-If the element to highlight does not yet exist while instantiating tour steps, you may use lazy evaluation by supplying a function to `attachTo.element`. The function will be called in the `before-show` phase.
+If the element to highlight does not yet exist while instantiating tour steps,
+you may use lazy evaluation by supplying a function to `attachTo.element`. The
+function will be called in the `before-show` phase.
 
-- `beforeShowPromise`: A function that returns a promise. When the promise resolves, the rest of the `show` code for
-  the step will execute. For example:
+- `beforeShowPromise`: A function that returns a promise. When the promise
+  resolves, the rest of the `show` code for the step will execute. For example:
   ```javascript
   beforeShowPromise: function() {
     return new Promise(function(resolve) {
@@ -204,38 +233,81 @@ If the element to highlight does not yet exist while instantiating tour steps, y
     });
   },
   ```
-- `canClickTarget` A boolean, that when set to false, will set `pointer-events: none` on the target
+- `canClickTarget` A boolean, that when set to false, will set
+  `pointer-events: none` on the target
 - `cancelIcon` Options for the cancel icon
-  - `enabled` Should a cancel “✕” be shown in the header of the step?
+  - `attrs` Additional HTML attributes to apply to the cancel icon button
+    element. This is useful for adding data attributes for testing or analytics.
+    Note: These attributes cannot override critical properties like `type`,
+    `onclick`, `class`, or `aria-label`.
+
+  ```javascript
+  cancelIcon: {
+    enabled: true,
+    label: 'Close Tour',
+    attrs: {
+      'data-test': 'close-tour-button',
+      'data-analytics-id': 'tour-close'
+    }
+  }
+  ```
+
+  - `enabled` Should a cancel "✕" be shown in the header of the step?
   - `label` The label to add for `aria-label`
+
 - `classes`: A string of extra classes to add to the step's content element.
-- `buttons`: An array of buttons to add to the step. These will be rendered in a footer below the main body text. Each button in the array is an object of the format:
-  - `label`: The label to add for `aria-label`. It can also be a function that returns a string (useful with i18n solutions).
-  - `disabled`: A boolean that controls the `disabled` attribute. It can also be a function that returns a boolean.
+- `buttons`: An array of buttons to add to the step. These will be rendered in a
+  footer below the main body text. Each button in the array is an object of the
+  format:
+  - `attrs`: Additional HTML attributes to apply to the button element. Useful
+    for adding data attributes for testing or analytics.
+  - `label`: The label to add for `aria-label`. It can also be a function that
+    returns a string (useful with i18n solutions).
+  - `disabled`: A boolean that controls the `disabled` attribute. It can also be
+    a function that returns a boolean.
   - `classes`: Extra classes to apply to the `<a>`
-  - `secondary`: A boolean, that when true, adds a `shepherd-button-secondary` class to the button
-  - `text`: The HTML text of the button. It can also be a function that returns a string (useful with i18n solutions).
-  - `action`: A function executed when the button is clicked on.
-    It is automatically bound to the `tour` the step is associated with, so things like `this.next` will
-    work inside the action. You can use action to skip steps or navigate to specific steps, with something like:
+  - `secondary`: A boolean, that when true, adds a `shepherd-button-secondary`
+    class to the button
+  - `text`: The HTML text of the button. It can also be a function that returns
+    a string (useful with i18n solutions).
+  - `action`: A function executed when the button is clicked on. It is
+    automatically bound to the `tour` the step is associated with, so things
+    like `this.next` will work inside the action. You can use action to skip
+    steps or navigate to specific steps, with something like:
   ```javascript
     action() {
       return this.show('some_step_name');
     }
   ```
-- `extraHighlights`: An array of extra element selectors to highlight when the overlay is shown The tooltip won’t be fixed to these elements, but they will be highlighted just like the attachTo element.
-- `advanceOn`: An action on the page which should advance shepherd to the next step. It should be an object with a string `selector` and an `event` name.
-  For example: `{selector: '.some-element', event: 'click'}`. It doesn't have to be an event inside the tour, it can be any event fired on any element on the page.
-  You can also always manually advance the Tour by calling `myTour.next()`.
-- `highlightClass`: An extra class to apply to the `attachTo` element when it is highlighted (that is, when its step is active). You can then target that selector in your CSS.
-- `id`: The string to use as the `id` for the step. If an id is not passed one will be generated.
-- `modalOverlayOpeningPadding`: An amount of padding to add around the modal overlay opening
-- `modalOverlayOpeningRadius`: An amount of border radius to add around the modal overlay opening. It can be either a number or an object with properties `{ topLeft, bottomLeft, bottomRight, topRight }`
-- `floatingUIOptions`: Extra options to pass to [Floating UI](https://floating-ui.com/docs/getting-started)
-- `showOn`: A function that, when it returns true, will show the step. If it returns false, the step will be skipped.
-- `scrollTo`: Should the element be scrolled to when this step is shown? If true, uses the default `scrollIntoView`, if an object, passes that object as the params to `scrollIntoView` i.e. `{behavior: 'smooth', block: 'center'}`
-- `scrollToHandler`: A function that lets you override the default `scrollTo` behavior and define a custom action to do the scrolling,
-  and possibly other logic.
+- `extraHighlights`: An array of extra element selectors to highlight when the
+  overlay is shown The tooltip won’t be fixed to these elements, but they will
+  be highlighted just like the attachTo element.
+- `advanceOn`: An action on the page which should advance shepherd to the next
+  step. It should be an object with a string `selector` and an `event` name. For
+  example: `{selector: '.some-element', event: 'click'}`. It doesn't have to be
+  an event inside the tour, it can be any event fired on any element on the
+  page. You can also always manually advance the Tour by calling
+  `myTour.next()`.
+- `highlightClass`: An extra class to apply to the `attachTo` element when it is
+  highlighted (that is, when its step is active). You can then target that
+  selector in your CSS.
+- `id`: The string to use as the `id` for the step. If an id is not passed one
+  will be generated.
+- `modalOverlayOpeningPadding`: An amount of padding to add around the modal
+  overlay opening
+- `modalOverlayOpeningRadius`: An amount of border radius to add around the
+  modal overlay opening. It can be either a number or an object with properties
+  `{ topLeft, bottomLeft, bottomRight, topRight }`
+- `floatingUIOptions`: Extra options to pass to
+  [Floating UI](https://floating-ui.com/docs/getting-started)
+- `showOn`: A function that, when it returns true, will show the step. If it
+  returns false, the step will be skipped.
+- `scrollTo`: Should the element be scrolled to when this step is shown? If
+  true, uses the default `scrollIntoView`, if an object, passes that object as
+  the params to `scrollIntoView` i.e. `{behavior: 'smooth', block: 'center'}`
+- `scrollToHandler`: A function that lets you override the default `scrollTo`
+  behavior and define a custom action to do the scrolling, and possibly other
+  logic.
 - `when`: You can define show, hide, etc events inside when. For example:
 
 ```javascript
@@ -269,12 +341,14 @@ when: {
 - `cancel`
 - `destroy`
 
-Please note that `complete` and `cancel` are only ever triggered if you call the associated methods in your code.
+Please note that `complete` and `cancel` are only ever triggered if you call the
+associated methods in your code.
 
 ### Advancing on Actions
 
-You can use the `advanceOn` option, or the Next button, to advance steps. If you would like however to have a step advance on a
-complex user action, you can do the following:
+You can use the `advanceOn` option, or the Next button, to advance steps. If you
+would like however to have a step advance on a complex user action, you can do
+the following:
 
 ```javascript
 const myStep = myTour.addStep(options);
@@ -288,8 +362,10 @@ yourApp.on('some-event', () => {
 
 ### 🔼 Displaying Arrows
 
-By default, Shepherd will generate and position an "arrow" element that points to the target
-of a step. This is done by setting the `arrow` option to `true` on each ``Step.options` &mdash; but you can disable the arrow manually by setting it to false:
+By default, Shepherd will generate and position an "arrow" element that points
+to the target of a step. This is done by setting the `arrow` option to `true` on
+each ``Step.options` &mdash; but you can disable the arrow manually by setting
+it to false:
 
 ```js
 myTour.addStep({
@@ -298,7 +374,9 @@ myTour.addStep({
 });
 ```
 
-You can also provide an options object, to configure the arrow's [padding](https://floating-ui.com/docs/arrow#padding). The padding is the closest the arrow will get to the edge of the step.
+You can also provide an options object, to configure the arrow's
+[padding](https://floating-ui.com/docs/arrow#padding). The padding is the
+closest the arrow will get to the edge of the step.
 
 ```js
 myTour.addStep({
@@ -307,5 +385,5 @@ myTour.addStep({
 });
 ```
 
-
-Furthermore, while Shepherd provides some basic arrow styling, you can style it as you wish by targeting the `.shepherd-arrow` element.
+Furthermore, while Shepherd provides some basic arrow styling, you can style it
+as you wish by targeting the `.shepherd-arrow` element.

shepherd.js/src/components/shepherd-button.ts

@@ -22,6 +22,7 @@ export function createShepherdButton(
   const text = config.text ? getConfigOption(config.text, step) : null;
 
   const btn = h('button', {
+    ...(config.attrs || {}),
     'aria-label': label || null,
     class: `${config.classes || ''} shepherd-button ${
       config.secondary ? 'shepherd-button-secondary' : ''

shepherd.js/src/components/shepherd-cancel-icon.ts

@@ -14,6 +14,7 @@ export function createShepherdCancelIcon(
   const btn = h(
     'button',
     {
+      ...(cancelIcon.attrs || {}),
       'aria-label': cancelIcon.label ? cancelIcon.label : 'Close Tour',
       class: 'shepherd-cancel-icon',
       onclick: handleCancelClick,