# Changelog

> Track what's new in Driver.js. See the latest features, changes, and fixes shipping in each release, plus what's currently in the works.

_Unreleased_ lists what is merged for the next release.

## Unreleased

### Fixed

- Tab no longer gets stuck on hidden or inert controls inside the highlighted element. ([#631](https://github.com/nilbuild/driver.js/pull/631))

## 1.14.0

### Added

- `waitForRemovedElement` sets how long a removed element gets to come back, separately from `waitForElement`. Both take `Infinity`.
- `scrollIntoView` takes `{ block, inline }` to say where the element ends up.
- `allowPageInteraction` lets the user use the whole page during a step.
- `focus` puts the keyboard on the popover, in the highlighted element, or leaves it where it is.
- In the headless build, `onInteraction` reports clicks on `allowedElements` as `region: "allowed"`.
- `onPopoverPositioned` runs every time the popover is placed, so you can move it somewhere else and keep it there.

### Changed

- The cutout and popover only cover the part of the element in view, so a row wider than its scrolling panel is highlighted inside the panel.
- The popover scrolls into view only as far as it needs to, so it no longer undoes where the element was scrolled to.
- When the tour ends, the keyboard goes back where it was only if it is still on the popover.

### Fixed

- The highlight follows a panel that scrolls inside the page.
- `onDestroyed` runs when the tour is closed before the first step has settled.
- A `waitForElement` longer than about 24 days no longer runs out at once.

## 1.13.0

### Added

- [`driver.js/headless`](https://driverjs.com/docs/headless-tours.md) runs a tour without drawing anything, so you can render your own UI.
- `scrollIntoView: false` stops driver.js from scrolling to the highlighted element and popover.
- `onWaitingForElement` tells you when a step starts waiting for its element, and its `signal` when the wait ends.
- `onElementReplaced` tells you when the app re-renders the highlighted element and the step moves to the new one.

## 1.12.1

### Changed

- A new popover focuses Next instead of the close button, so Enter no longer ends the tour.
- Your CSS can hide or restyle popover parts without `!important`.

### Fixed

- The popover shows above a dialog that opens mid-step instead of behind it.
- `pointer-events: none` inside the highlighted element is no longer overridden.

## 1.12.0

### Added

- `popover.instruction` makes a step an [action step](https://driverjs.com/docs/action-driven-tours.md#make-the-user-act): the user has to do what it says. Next looks disabled until they do.
- `advanceOn: { event, strict: true }` lets only that gesture through on the highlighted element.
- `advanceDelay` pauses on a completed step before moving on. Action steps show a done state meanwhile.
- `driverObj.advance()` completes the current step from your code, like `advanceOn` does.
- `driverObj.nudge("message")` shows a line of feedback in the popover and shakes it.
- `onElementMissing` takes `"stay"`, `"previous"` or `"previousAction"` as well as a function.
- `disableActiveInteraction: "clicks"` blocks clicks on the highlighted element but keeps hover working.
- `onHighlightStarted` gets the same `signal` as `onHighlighted`.
- A console warning when `disableActiveInteraction` makes a step's `advanceOn` impossible.
- A highlighted element inside an allowed element, like an item in an open menu, gets a ring instead of a hidden cutout.
- CSS variables for the instruction row, the feedback line and that ring. See [Theming](https://driverjs.com/docs/theming.md#css-variables).

### Changed

- Clicks on the padding around the highlighted element, or on an element with `disableActiveInteraction`, no longer reach your app's `document` and `body` listeners. Use [`onInteraction`](https://driverjs.com/docs/configuration.md#oninteraction) to see them.
- `disableActiveInteraction: true` also blocks Enter and Space on the highlighted element.
- A highlighted element that your framework re-renders is followed automatically.
- `overlayClickBehavior: "nextStep"` does nothing while the popover waits for an element.
- `onDestroyStarted` gets the step being entered when the tour is closed during its first animation, not `undefined`.
- The `State` type no longer lists the internal `__` keys added in 1.11.0.

### Fixed

- Steps inside a modal `<dialog>` now dim the dialog and cut out the highlighted element.
- `moveNext()`, `drive()` and `destroy()` now work when called from `onHighlightStarted`, `onHighlighted` or `onDeselected`.
- `moveTo()` starts the tour if it isn't running.
- `setSteps()` on a running tour ends it cleanly. Call `drive()` to start the new steps.
- A step's `showProgress: false` now wins over `showProgress: true` on the driver.
- A fast double-click no longer skips a step that advances on click. `advanceOnClick` ignores clicks while a step animates in, as before 1.11.0.
- The key that completes a step, like Enter, no longer presses a button in the next popover.
- The highlight and popover stay on their element when it changes size, when a framework rewrites its `className`, and when the page resizes mid-step.
- A highlighted element that is removed from the page no longer keeps driver.js classes and aria attributes.
- `drive()` without steps no longer locks the page when `onDestroyStarted` is set.
- Less layout work while scrolling with hints or a tour, and `waitForElement` checks the page at most once a frame.

## 1.11.0

### Added

- `advanceOn` completes a step on any event, like `"contextmenu"`, and `{ event, when }` only completes it when your check passes.
- `onInteraction` sees clicks, right-clicks and double-clicks during a step and can block them with `return false`.
- `allowedElements` keeps menus and popups opened by a step usable above the overlay.
- `onElementMissing` lets you recover when a step's element disappears or a wait times out. Return `false` on a timeout to stay on the current step.
- `driverObj.updatePopover()` changes the popover text in place and announces it to screen readers.
- `driverObj.nudge()` shakes the popover to draw attention, and `nudge({ description })` changes its text at the same time.
- `onHighlighted` gets a `signal` that aborts when the step is left.

### Changed

- While `waitForElement` waits, the popover stays visible in a waiting state, keeping the close button usable.
- Escape and arrow keys pressed in a text field, select or ARIA widget inside the highlighted element now go to your app instead of the tour.
- The popover no longer takes focus from the highlighted element when a step starts.
- `showButtons: []` in the driver config now hides all buttons instead of showing all of them.
- Highlighting no longer overwrites an element's own `aria-haspopup`, `aria-expanded` or `aria-controls`.
- `advanceOnClick` is deprecated in favor of `advanceOn: "click"`. It keeps working.
- The tour ignores Escape and arrow keys whose `keydown` your app prevented or stopped.

### Fixed

- Hints in an open `<dialog>` no longer get covered when the page styles
  every `[popover]`, for example with a dark background.
  ([#628](https://github.com/nilbuild/driver.js/issues/628))

## 1.10.2

### Fixed

- Hints and popovers in an open `<dialog>` with a `transform` or `filter`
  now stay next to their element, also after the dialog reopens.
  ([#627](https://github.com/nilbuild/driver.js/issues/627))
- Tour steps scrolled out of a visible scrollable container are now
  scrolled into view.
  ([#577](https://github.com/nilbuild/driver.js/issues/577))
- The popover title and footer are `div`s instead of `header` and `footer`
  landmarks, and the centered dummy element gets no aria attributes.
  ([#434](https://github.com/nilbuild/driver.js/issues/434))

## 1.10.1

### Added

- `launcher: false` on checklists drops the floating launcher, for pages
  that open the panel from their own button with `open()` or `toggle()`.
  Closing the panel hands focus back to whatever opened it.

### Fixed

- Hints, and popovers of tour steps, whose element is inside an open
  `<dialog>` now render inside that dialog, so they show above a modal
  opened with `showModal()` instead of behind it.
  ([#625](https://github.com/nilbuild/driver.js/issues/625))
- Clicking the popover no longer throws when the event's target is a text
  node. ([#626](https://github.com/nilbuild/driver.js/issues/626))

## 1.10.0

### Added

- Checklists: an onboarding widget in its own `driver.js/checklist` entry
  (with `dist/checklist.css`). Items start a tour, follow a link or run an
  action, and are ticked when the user finishes the tour, or by
  `completeWhen` and `complete()`, or by the user with `allowManualComplete`.
  Progress comes in through `completed` and goes out through `onProgress`;
  `onEvent` reports everything for analytics. It sits in any corner of the
  screen (`position`, `offset`), adapts to phones, and can show a different
  title and launcher text once everything is done. See the
  [Checklists guide](https://driverjs.com/docs/checklists.md), and
  [Checklist Themes](https://driverjs.com/docs/checklist-themes.md) for ready-made themes.
- `reason` in the options of `onDestroyStarted`, `onDestroyed` and the
  `onDeselected` that runs on destroy, telling apart a finished tour
  (`"done"`) from one that was closed (`"close"`, `"escape"`, `"overlay"`),
  replaced by another instance (`"replaced"`) or ended from code (`"api"`).
  A `destroy()` called from a hook keeps the reason of the user action that
  started it. The `DestroyReason` and `HookOpts` types are exported.

### Changed

- The popover's close button only darkens for keyboard focus
  (`:focus-visible`), so it no longer opens dark after a tour is started with
  a mouse click.

## 1.9.0

### Added

- `closeBtnLabel` (driver and step level) to set the close button's
  `aria-label`, for translated tours. Defaults to `Close`.
  ([#623](https://github.com/nilbuild/driver.js/issues/623))
- `overlayClickBehavior: "none"` to ignore overlay clicks while Escape and the
  close button still close the tour.
  ([#435](https://github.com/nilbuild/driver.js/issues/435))

### Changed

- Keyboard control follows the popover buttons: arrow keys do nothing when
  their button is hidden or disabled, and Escape does nothing when the close
  button is disabled.
  ([#589](https://github.com/nilbuild/driver.js/issues/589))
- The current popover is hidden while `waitForElement` waits for the next
  step's element, so a stale step no longer stays on screen.
  ([#578](https://github.com/nilbuild/driver.js/issues/578))
- Only one instance is on screen at a time. Starting a tour or highlight closes
  any other active instance; it gets `onDeselected` and `onDestroyed` but not
  `onDestroyStarted`.

### Fixed

- `destroy()` on an instance that is not active is now a no-op instead of
  tearing down another instance's tour.
  ([#504](https://github.com/nilbuild/driver.js/issues/504))
- The highlighted element's own `aria-controls`, `aria-expanded` and
  `aria-haspopup` are restored when the highlight moves on or the tour ends,
  instead of being removed.
  ([#495](https://github.com/nilbuild/driver.js/issues/495))
- No more small white square between steps without an element.
  ([#549](https://github.com/nilbuild/driver.js/issues/549))
- `onDeselected` now fires when moving between two steps on the same element,
  or between two steps without an element.
- The driver-level `disableButtons` now applies to tour steps. It used to be
  ignored during a tour. A step's own `disableButtons` still replaces it.

## 1.8.0

### Added

- Hints: pulsing beacons that open a popover on click; overlay optional, the
  page stays interactive. `driver.js/hints`, ~5KB gzip. [Guide](https://driverjs.com/docs/hints.md).
  ([#363](https://github.com/nilbuild/driver.js/issues/363))
- `advanceOnClick` (driver and step level) to advance the tour by clicking the
  highlighted element itself.
  ([#606](https://github.com/nilbuild/driver.js/issues/606))
- `waitForElement` (driver and step level) to wait up to N ms for a step's
  element before treating it as missing.
  ([#606](https://github.com/nilbuild/driver.js/issues/606))
- `sideEffects` field in package.json for better tree-shaking.

### Changed

- Popover internals shared between tours and hints; tour behaviour verified
  unchanged against 1.7.0.
- Build migrated from vite to tsdown; artifact names, exports map and CDN
  globals unchanged, sizes within ±2%.

### Fixed

- `skipMissingElement`: the last reachable step now shows Done and runs
  `onDoneClick`; step queries like `isLastStep()` account for skips.
  ([#616](https://github.com/nilbuild/driver.js/issues/616))

## 1.7.0

### Added

- `skipMissingElement` option (driver and step level) to skip a step whose
  target element is specified but not in the DOM, instead of showing the
  centered fallback popover. Element-less steps are never skipped.
  ([#489](https://github.com/nilbuild/driver.js/issues/489),
  [#395](https://github.com/nilbuild/driver.js/issues/395))
- `index` on the options passed to every hook, holding the currently active
  step index (same value as `driverObj.getActiveIndex()`).
  ([#490](https://github.com/nilbuild/driver.js/issues/490))
- `--driver-popover-font-family` CSS variable to set the popover font in one
  place, without overriding each text element individually.
  ([#607](https://github.com/nilbuild/driver.js/issues/607))

### Changed

- The popover title and description now render in the default font stack
  (`"Helvetica Neue", …`) instead of the browser's default `sans-serif`. An
  internal rule had been shadowing the intended font. Set
  `--driver-popover-font-family` to use your own.

### Fixed

- Icon fonts (Material Icons, Font Awesome, etc.) placed inside a step
  description are no longer overridden by the popover font and render correctly.
  ([#510](https://github.com/nilbuild/driver.js/issues/510),
  [#512](https://github.com/nilbuild/driver.js/issues/512))
- Each `driver()` call keeps its own config, steps and state, so creating a
  second instance no longer overwrites the first.
  ([#571](https://github.com/nilbuild/driver.js/issues/571))
- Popover no longer jumps when its content has images that load after render.

## 1.6.0

### Added

- `animationDuration` config to control how long the highlight transition takes.
  ([#104](https://github.com/nilbuild/driver.js/issues/104))
- `allowScroll` config to lock body scroll while a tour is active.
- `onDoneClick` hook, fired when the done button on the final step is clicked.
  ([#500](https://github.com/nilbuild/driver.js/issues/500))
- `data` property on a step for passing arbitrary data, accessible from hooks
  for custom per-step logic. ([#539](https://github.com/nilbuild/driver.js/issues/539))

### Changed

- <span class="breaking-badge">Breaking</span> Popover footer buttons are now styled through the
  `driver-popover-footer-btn` class instead of the `.driver-popover-footer button` selector. Buttons you add through
  `onPopoverRender` no longer inherit the default styling automatically. Add the `driver-popover-footer-btn` class to
  opt in, or leave it off to apply your own styles. The built-in next/previous buttons carry the class out of the box.
  ([#555](https://github.com/nilbuild/driver.js/issues/555))
- Custom buttons added through `onPopoverRender` now receive their own click
  events. Only the built-in next, previous, and close buttons have their default
  action intercepted by the library.
- The popover exposes `driver-popover-side-*` and `driver-popover-align-*`
  classes so you can target its position from CSS, and the arrow positioning was
  rewritten for more accurate placement.

### Fixed

- Document event listener leak in `onDriverClick` that left handlers attached
  after the tour was destroyed.
  ([#452](https://github.com/nilbuild/driver.js/issues/452))
- Dropped the CSS `:has()` selector for broader browser compatibility.
  ([#586](https://github.com/nilbuild/driver.js/issues/586))
- Positioned highlighted elements and their children (e.g. dropdown menus) no
  longer get clipped.
  ([#454](https://github.com/nilbuild/driver.js/issues/454),
  [#563](https://github.com/nilbuild/driver.js/issues/563))
- `removeChild` DOMException when re-rendering a popover whose wrapper was
  already detached from the DOM.
  ([#572](https://github.com/nilbuild/driver.js/issues/572))
- Close button on a single-element `highlight()` popover did nothing when
  clicked. It now closes the popover by default, respecting `allowClose` and any
  custom `onCloseClick`. ([#444](https://github.com/nilbuild/driver.js/issues/444))

## 1.5.0

### Added

- `getNextStep` method on the driver API.
  ([#420](https://github.com/nilbuild/driver.js/issues/420))
- `driver-popover-done-btn` class on the next button when it acts as the done
  button on the final step. ([#610](https://github.com/nilbuild/driver.js/issues/610))

### Changed

- The `onDestroyed` hook now receives the final tour state.
  ([#553](https://github.com/nilbuild/driver.js/issues/553))
- Removed the unicode characters from the default button labels.

### Fixed

- The tour no longer closes when pressing the left arrow on the first step.
  ([#564](https://github.com/nilbuild/driver.js/issues/564))
- Removed the button text-shadow that left ghost text behind.
  ([#605](https://github.com/nilbuild/driver.js/issues/605))
- `onNextClick` now fires when advancing the tour through an overlay click.
  ([#576](https://github.com/nilbuild/driver.js/issues/576))

For the release notes of other versions, see the
[GitHub releases](https://github.com/nilbuild/driver.js/releases) page.

## Migrating from 0.x to 1.x

See [Migrate to 1.x](https://driverjs.com/docs/migrating-from-0x.md) for the import, configuration and API changes.
