@robertlinde/react-tour-kit 0.8.9 → 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog
+
+Releases are published automatically from `main`; each GitHub release lists its commits. This file describes the larger changes.
+
+## 1.0.1
+
+### Fixed
+
+- Targets moved by animations that report no events are followed: a React Native screen sliding in with the native driver (a stack navigator, for example), or an animation of the Web Animations API. Until such an animation ends, the target is measured where it started:
+  - when that was on screen, the highlight and tooltip stayed there instead of following the target;
+  - when it was off screen (a screen sliding in from the side), the step was skipped.
+
+## 1.0.0
+
+A rewrite for reliability, smoothness and accessibility. The everyday API is unchanged; see [MIGRATION.md](./MIGRATION.md) for the breaking changes.
+
+### Breaking
+
+- Custom tooltips (`TooltipComponent`) only render content; the tour measures, positions, animates and focuses them. `position`, `isPositioned`, `onMeasured`, `theme` and `i18n` props and `forwardRef` are gone; `step`, `placement`, `arrowOffset`, `titleId` and `descriptionId` are new.
+- `OverlayComponent` and the `platform` prop are removed, as are the internal exports (`TourContext`, `TourOverlay`, `TourTooltip`, `calculateTooltipPosition`, `findVisibleElement`, the platform adapters, the target registry, the `DOT_*` constants and the `Rect` and `TourOverlayProps` types).
+- React Native: the tour is drawn in the app's root view instead of a `<Modal>`. `TourProvider` must wrap the app root, outside `SafeAreaView`. `react-native-svg` is no longer used. React Native 0.79 or newer is required.
+- `TourEndReason` has a new member, `'error'`.
+- Step types are wider: `title` and `content` are `ReactNode`, `target` is optional, and `onBeforeStep` receives `TourTarget | undefined` and a `{signal}`.
+- Default primary colour `#2563eb` and title colour `#111827` (WCAG AA contrast); the same default texts on both platforms (`'Finish'`, `'{current} of {total}'`).
+- ESM-only package.
+
+### Added
+
+- **Never out of sight**: targets are scrolled into view through every scroll container (vertical and horizontal), clear of sticky headers, banners and floating buttons; the tooltip always stays inside the visible screen and its safe areas, on every screen size, orientation and zoom level, and flips sides when there is no room.
+- Targets are awaited (up to 5 seconds) after `onBeforeStep`: no more polling or delays.
+- Smooth animations: the highlight glides between steps together with the scroll, the tooltip enters from its side, and the tour fades in and out. Reduced motion is respected.
+- Steps without a `target` are shown in the centre. `title` and `content` accept any React content. On the web, `target` can be a ref.
+- `onBeforeStep` receives an `AbortSignal` that is aborted when the step is abandoned. Errors end the tour with `'error'` and `info.error`.
+- Web: the tour is a modal `<dialog>` in the browser's top layer — above every `z-index` and stacking context — with focus management, screen-reader announcements and right-to-left support. Page scrolling is blocked while a tour is open. Presses, focus and keys inside the tour do not reach the page's own listeners (menus that close on "click outside" stay open). Global styles such as Tailwind's preflight cannot break it. Stable `rtk-*` classes and CSS variables for styling, in a cascade layer that app CSS overrides. Elements with `overflow: hidden` (carousels) are never scrolled by the tour.
+- React Native: `useTourScrollView()` lets the tour scroll `ScrollView`, `FlatList` and `SectionList`; `<TourHost />` shows tours in native modal screens; an `insets` prop for safe areas (with conservative defaults); the on-screen keyboard is avoided; the Android back button closes the tour; screen-reader focus moves to the tooltip and step changes are announced; stable `testID`s for UI tests.
+- Server rendering and Next.js App Router support (`'use client'`).
+
+### Fixed
+
+- No work while idle: 0.x re-rendered, re-measured and called `scrollTo` about 19 times a second while a step was open, pulling the page back when the user scrolled.
+- `onBeforeStep` runs exactly once per step; it used to run again whenever the app re-rendered with a new `onTourEnd` function.
+- React 18 works (0.x used React 19-only APIs).
+- The package loads in Node (0.x failed with `ERR_UNSUPPORTED_DIR_IMPORT`).
+- Android: no white strip over the navigation bar under edge to edge (caused by the `<Modal>` window).
+- The highlight lines up exactly on React Native, including with translucent status bars.
+- Double clicks no longer skip steps; arrow keys no longer act while typing in a text field; clicks inside the highlight no longer close the tour; going back no longer skips forward over missing targets.
+- `onTourEnd` fires exactly once per tour, also when a tour is replaced by another one.
+- Accessibility: dialog semantics, labelled buttons, keyboard support, AA contrast and Windows high-contrast mode (0.x had none of these).

package/MIGRATION.md

@@ -0,0 +1,205 @@
+# Migrating from 0.x to 1.0
+
+1.0 is a rewrite. The everyday API — `TourProvider`, `useTour()`, `startTour(steps, id, {onTourEnd})`, the step fields, `theme`, `i18n`, `onTourEnd`, `closeOnOverlayClick` and `useTourTarget` — is unchanged. What changed is mostly what you no longer have to do yourself.
+
+## Checklist
+
+- [ ] **Custom tooltip?** Make it content-only: no `forwardRef`, no `position`, no `isPositioned`. → [details](#custom-tooltips-are-content-only)
+- [ ] **Custom overlay?** Remove `OverlayComponent`; use `theme.overlayColor` or CSS. → [details](#overlaycomponent-and-platform-are-removed)
+- [ ] **Polling or delays in `onBeforeStep`?** Delete them. → [details](#onbeforestep-no-polling-no-delays)
+- [ ] **React Native:** move `TourProvider` to the root, outside `SafeAreaView`, pass `insets`, remove `react-native-svg` if nothing else uses it. → [details](#react-native)
+- [ ] **Exhaustive `switch` on `info.reason`?** Add `'error'`. → [details](#a-new-end-reason-error)
+- [ ] **Imports of internals** (`webPlatformAdapter`, `calculateTooltipPosition`, `TourContext`, …)? Remove them. → [details](#removed-exports)
+- [ ] **TypeScript code that reads steps** (`step.title` as a `string`, `onBeforeStep(target: TourTarget)`)? See [step types](#step-types).
+- [ ] **Snapshot or end-to-end tests** that check labels or colours? Check the [new defaults](#changed-defaults).
+
+## Custom tooltips are content-only
+
+In 0.x a custom tooltip had to position itself, forward a ref so it could be measured, and hide itself until it was positioned. In 1.0 the tour does all of that — measuring, placing, flipping, keeping it on screen, animating, focusing — and your component only renders the content.
+
+**Before**
+
+```tsx
+const MyTooltip = forwardRef<HTMLDivElement, TourTooltipProps>(
+  ({title, content, currentStep, totalSteps, position, isPositioned, onNext, onPrev, onClose}, ref) => (
+    <div
+      ref={ref}
+      className="my-tooltip"
+      style={{position: 'fixed', top: position.top, left: position.left, opacity: isPositioned ? 1 : 0}}
+    >
+      <h3>{title}</h3>
+      <p>{content}</p>
+      <button onClick={onPrev}>Back</button>
+      <button onClick={onNext}>Next</button>
+    </div>
+  ),
+);
+```
+
+**After**
+
+```tsx
+function MyTooltip({step, currentStep, totalSteps, onNext, onPrev, onClose, titleId, descriptionId}: TourTooltipProps) {
+  return (
+    <div className="my-tooltip">
+      <h3 id={titleId}>{step.title}</h3>
+      <div id={descriptionId}>{step.content}</div>
+      <button onClick={onPrev}>Back</button>
+      <button onClick={onNext}>Next</button>
+    </div>
+  );
+}
+```
+
+`TourTooltipProps`:
+
+| 0.x                                                                      | 1.0                                                                                                            |
+| ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
+| `title`, `content`                                                       | `step.title`, `step.content`                                                                                   |
+| `position`, `isPositioned`                                               | removed — the tour positions and reveals the tooltip                                                           |
+| `onMeasured` (React Native)                                              | removed — the tour measures the tooltip                                                                        |
+| `theme`, `i18n`                                                          | removed — use your own design tokens and texts in your component                                               |
+| `currentStep`, `totalSteps`, `onNext`, `onPrev`, `onClose`, `onGoToStep` | unchanged                                                                                                      |
+| —                                                                        | new: `placement` and `arrowOffset` (to draw an arrow), `titleId` and `descriptionId` (web, for screen readers) |
+
+Remove positioning styles (`position: fixed/absolute`, `top`, `left`, `z-index`, `opacity` for hiding) from your tooltip. The card around your content provides the background, rounded corners and shadow from the theme.
+
+## `OverlayComponent` and `platform` are removed
+
+A custom overlay could not keep the guarantees 1.0 makes (the highlight follows the target while scrolling, clicks inside the highlight are ignored, the overlay is above everything). Colour the overlay with `theme.overlayColor`; on the web you can also style `.rtk-spotlight` (see [Styling with CSS](./README.md#styling-with-css-web)).
+
+The `platform` prop (a custom platform adapter) is removed as well; each entry point has its platform built in.
+
+## `onBeforeStep`: no polling, no delays
+
+The tour now waits for the target to appear (up to 5 seconds, event-driven) after `onBeforeStep` finishes, and scrolls it into view. Remove polling loops and timeouts:
+
+**Before**
+
+```ts
+onBeforeStep: async (target) => {
+  navigate('/settings');
+  while (!document.querySelector(target as string)) {
+    await new Promise((resolve) => setTimeout(resolve, 50));
+  }
+},
+```
+
+```ts
+// React Native
+onBeforeStep: async () => {
+  navigation.navigate('Settings');
+  await new Promise((resolve) => setTimeout(resolve, 300));
+},
+```
+
+**After**
+
+```ts
+onBeforeStep() {
+  navigate('/settings');
+},
+```
+
+`onBeforeStep` now runs again when the user comes back to the step with Back, so make it idempotent (navigating to the page that is already open is fine; on the web, skip `navigate` when already on the path to avoid duplicate history entries). It also receives a second argument, `{signal}`, which is aborted when the step is abandoned.
+
+If `onBeforeStep` throws or rejects, the tour ends with the new reason `'error'` (in 0.x the rejection went unhandled and the step never appeared).
+
+## React Native
+
+### Place `TourProvider` at the root and pass `insets`
+
+1.0 draws the tour inside your app's root view instead of a React Native `<Modal>`. This fixes the white navigation-bar strip on Android with edge-to-edge, makes the highlight line up exactly, and lets the Android back button close the tour. For that, the provider has to fill the window:
+
+**Before**
+
+```tsx
+<SafeAreaView style={{flex: 1}}>
+  <TourProvider>
+    <App />
+  </TourProvider>
+</SafeAreaView>
+```
+
+**After**
+
+```tsx
+function Root() {
+  const insets = useSafeAreaInsets(); // react-native-safe-area-context
+  return (
+    <TourProvider insets={insets}>
+      <SafeAreaView style={{flex: 1}}>
+        <App />
+      </SafeAreaView>
+    </TourProvider>
+  );
+}
+```
+
+In development, a warning tells you when the provider does not fill the window.
+
+### Native modal screens need a `<TourHost />`
+
+Screens presented as native modals (react-navigation `presentation: 'modal'`, React Native `<Modal>`) are drawn above your root view. To highlight elements in them, render `<TourHost />` as the last child of the modal screen. See [Modal screens](./README.md#modal-screens).
+
+### Scroll views
+
+To let the tour scroll targets into view, register the scroll views around them with the new `useTourScrollView()` hook. Without it, steps whose target is off screen are skipped.
+
+### Android navigation bar
+
+To keep the navigation bar transparent behind the tour (no contrast scrim), set `enforceContrast: false` — see [Android navigation bar](./README.md#android-navigation-bar). The `statusBarTranslucent`/`navigationBarTranslucent` workarounds for the 0.x modal are no longer needed.
+
+### `react-native-svg` is no longer needed
+
+The overlay is drawn with plain views. Uninstall `react-native-svg` unless your app uses it elsewhere.
+
+### Minimum version
+
+React Native 0.79 (Expo SDK 53), whose Metro reads the package's `exports`. In TypeScript, `moduleResolution` must be `bundler`, `node16` or `nodenext` (the defaults of current React Native, Expo, Next.js and Vite projects).
+
+## A new end reason: `'error'`
+
+`TourEndReason` has a new member, `'error'`, used when `onBeforeStep` throws or rejects (`info.error` holds the error). A `switch` that TypeScript checks for exhaustiveness needs a new case.
+
+## Missing targets
+
+0.x checked for the target once, right after `onBeforeStep`; if it was not there yet it skipped to the next step — also when the user was going back — and ended the tour on the last step. 1.0 waits up to 5 seconds for the target to appear, then skips in the direction the user is going (with a warning in development). Going back past the first step returns to the step the user came from. The tour ends with `'target-missing'` only when no remaining step can be shown.
+
+## Starting tours
+
+- Calling `startTour` with the id of the tour that is already running does nothing (it used to restart it). This makes "start on mount" effects safe in Strict Mode.
+- Starting a different tour while one is running ends the running one with the reason `'closed'`, so its `onTourEnd` callbacks run.
+
+## Removed exports
+
+These were internals and are no longer exported: `TourContext`, `TourOverlay`, `TourTooltip`, `TourOverlayProps`, `Rect`, `calculateTooltipPosition`, `findVisibleElement`, `webPlatformAdapter`, `nativePlatformAdapter`, `targetRegistry`, `MAX_VISIBLE_DOTS`, `DOT_SIZE`, `DOT_GAP`, `DOTS_CONTAINER_WIDTH`.
+
+Still exported: `TourProvider`, `useTour`, `useTourTarget` (React Native), `getTruncatedDots` and the types `TourStep`, `TourTarget`, `TourContextType`, `TourProviderProps`, `TourTooltipProps`, `TourTheme`, `TourI18n`, `TourEndReason`, `TourEndInfo`, `TourEndCallback`, `StartTourOptions`, `DotItem`. New: the types `TourPlacement` and `TourStepContext`; `useTourScrollView`, `TourHost` and `TourInsets` (React Native).
+
+`getTruncatedDots` returns ellipsis items with a `position` (`'start'` or `'end'`); `steps` in `useTour()` is now a `readonly` array.
+
+## Changed defaults
+
+| Setting                                   | 0.x                                                                         | 1.0                                                 |
+| ----------------------------------------- | --------------------------------------------------------------------------- | --------------------------------------------------- |
+| `theme.primaryColor`                      | `'#3b82f6'`                                                                 | `'#2563eb'` (WCAG AA)                               |
+| `theme.titleColor`                        | `'#1f2937'`                                                                 | `'#111827'`                                         |
+| `i18n.finishLabel`                        | `'Finish'` (web), `'Done'` (React Native)                                   | `'Finish'`                                          |
+| `i18n.stepCounterTemplate`                | `'{current} / {total}'` (web), `'Step {current} of {total}'` (React Native) | `'{current} of {total}'`                            |
+| Page scrolling while a tour is open (web) | allowed                                                                     | blocked, so the step cannot be scrolled away        |
+| Arrow keys (web)                          | captured globally, also while typing                                        | only while the tour has focus, never in text fields |
+
+`i18n.closeAriaLabel` and `i18n.dotAriaLabelTemplate` are now used on React Native too.
+
+## Step types
+
+Steps can do more, so their types are wider. Writing steps needs no change; TypeScript code that _reads_ them may:
+
+- `title` and `content` accept any React content (`ReactNode`), not only strings. Code that uses `step.title` as a `string` (for example `info.step.title` in analytics) has to handle other content, or keep its own string.
+- `target` is optional: a step without a target is shown in the centre of the screen. `onBeforeStep` therefore receives `TourTarget | undefined`, plus a second argument `{signal}`; an annotated `(target: TourTarget) => …` becomes `(target: TourTarget | undefined) => …`.
+- On the web, `target` can also be a ref to an element.
+
+## Package format
+
+The package is ESM-only, with the entry points `@robertlinde/react-tour-kit/react` and `@robertlinde/react-tour-kit/react-native` as before. Bundlers (Vite, webpack, Next.js, Metro) and Node's `import` work as before; 0.x's broken CommonJS entry is gone. Jest (CommonJS by default) has to transform the package, on the web and with React Native's preset (see [Testing your app](./README.md#testing-your-app)).