@guided-tour-s4marth/react 0.1.0 → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +102 -0
- package/package.json +2 -2
package/README.md
ADDED
|
@@ -0,0 +1,102 @@
|
|
|
1
|
+
# @guided-tour-s4marth/react
|
|
2
|
+
|
|
3
|
+
React bindings for a data-driven product-tour system. Tours are **data** (fetched
|
|
4
|
+
from your backend), so you author and change them **without a deploy**. Steps
|
|
5
|
+
target elements by a resilient multi-signal locator + signature (no build-time
|
|
6
|
+
`data-tour` attributes), with runtime self-heal when the UI drifts.
|
|
7
|
+
|
|
8
|
+
Built on [driver.js](https://github.com/kamranahmedse/driver.js).
|
|
9
|
+
|
|
10
|
+
## Install
|
|
11
|
+
|
|
12
|
+
```bash
|
|
13
|
+
npm i @guided-tour-s4marth/react @guided-tour-s4marth/core driver.js
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
`react` / `react-dom` (>=18) are peer dependencies. Import driver.js's CSS once
|
|
17
|
+
in your app entry (the popover is unstyled without it):
|
|
18
|
+
|
|
19
|
+
```ts
|
|
20
|
+
import 'driver.js/dist/driver.css';
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
## Quick start
|
|
24
|
+
|
|
25
|
+
Wrap your app in `TourProvider`, give it a way to fetch tours, and start tours
|
|
26
|
+
with `useTour()`.
|
|
27
|
+
|
|
28
|
+
```tsx
|
|
29
|
+
import { TourProvider, useTour } from '@guided-tour-s4marth/react';
|
|
30
|
+
import 'driver.js/dist/driver.css';
|
|
31
|
+
|
|
32
|
+
function Root() {
|
|
33
|
+
return (
|
|
34
|
+
<TourProvider
|
|
35
|
+
fetchTours={() => fetch('/api/tours').then(r => r.json())}
|
|
36
|
+
appVersion="1.4.0"
|
|
37
|
+
userContext={{ userId: currentUser.id, role: currentUser.role }}
|
|
38
|
+
navigate={route => router.push(route)} // for steps that span screens
|
|
39
|
+
theme={{ primaryColor: '#6366f1' }} // optional CSS-variable overrides
|
|
40
|
+
>
|
|
41
|
+
<App />
|
|
42
|
+
</TourProvider>
|
|
43
|
+
);
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
function PlayButton({ tourId }: { tourId: string }) {
|
|
47
|
+
const { startTour } = useTour();
|
|
48
|
+
return <button onClick={() => startTour(tourId)}>Take the tour</button>;
|
|
49
|
+
}
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
The newest unseen active **release** tour auto-plays once per session (set
|
|
53
|
+
`autoPlay={false}` to disable). "Seen" is tracked via a pluggable `seenStore`
|
|
54
|
+
(defaults to `localStorage`; pass your own to persist per-user on the backend).
|
|
55
|
+
|
|
56
|
+
## Tour data shape
|
|
57
|
+
|
|
58
|
+
`fetchTours` returns an array of tours. Minimal example:
|
|
59
|
+
|
|
60
|
+
```jsonc
|
|
61
|
+
{
|
|
62
|
+
"id": "v1.4",
|
|
63
|
+
"title": "v1.4",
|
|
64
|
+
"type": "release", // "release" | "onboarding"
|
|
65
|
+
"status": "active",
|
|
66
|
+
"steps": [
|
|
67
|
+
{ "title": "Welcome", "body": "Here's what's new." }, // no anchorId → centered modal
|
|
68
|
+
{
|
|
69
|
+
"title": "Export",
|
|
70
|
+
"body": "Click here to export.",
|
|
71
|
+
"anchorId": "loc:{…}" // a captured locator (see @guided-tour-s4marth/recorder)
|
|
72
|
+
}
|
|
73
|
+
]
|
|
74
|
+
}
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
You typically don't hand-write `anchorId` — record tours with
|
|
78
|
+
[`@guided-tour-s4marth/recorder`](https://www.npmjs.com/package/@guided-tour-s4marth/recorder),
|
|
79
|
+
which captures the locator for you.
|
|
80
|
+
|
|
81
|
+
## `TourProvider` props
|
|
82
|
+
|
|
83
|
+
| Prop | Required | Description |
|
|
84
|
+
|---|---|---|
|
|
85
|
+
| `fetchTours` | ✓ | `() => Promise<unknown[]>` — your tours from the backend |
|
|
86
|
+
| `appVersion` | ✓ | used by version-gated conditions |
|
|
87
|
+
| `userContext` | ✓ | `{ userId?, role?, flags? }` for eligibility + seen |
|
|
88
|
+
| `navigate` | | router push, so steps can change routes |
|
|
89
|
+
| `waitForElement` | | `(selector, timeoutMs)` for async/modal targets |
|
|
90
|
+
| `seenStore` | | persistence adapter (default: `localStorage`) |
|
|
91
|
+
| `theme` | | `ThemeOverrides` (CSS variables) |
|
|
92
|
+
| `autoPlay` | | default `true` |
|
|
93
|
+
|
|
94
|
+
## `useTour()`
|
|
95
|
+
|
|
96
|
+
```ts
|
|
97
|
+
const { tours, eligibleTours, activeTourId, currentStepIndex, startTour, stopTour } = useTour();
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
## License
|
|
101
|
+
|
|
102
|
+
MIT
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@guided-tour-s4marth/react",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.1",
|
|
4
4
|
"description": "React bindings for the guided tour runtime",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"author": "DataGenie",
|
|
@@ -32,7 +32,7 @@
|
|
|
32
32
|
"dist"
|
|
33
33
|
],
|
|
34
34
|
"dependencies": {
|
|
35
|
-
"@guided-tour-s4marth/core": "0.1.
|
|
35
|
+
"@guided-tour-s4marth/core": "0.1.1"
|
|
36
36
|
},
|
|
37
37
|
"peerDependencies": {
|
|
38
38
|
"react": ">=18.0.0",
|