@guided-tour-s4marth/core 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 +53 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
# @guided-tour-s4marth/core
|
|
2
|
+
|
|
3
|
+
Framework-agnostic runtime for a data-driven product-tour system. This is the
|
|
4
|
+
low-level engine — **most apps should use
|
|
5
|
+
[`@guided-tour-s4marth/react`](https://www.npmjs.com/package/@guided-tour-s4marth/react)**,
|
|
6
|
+
which wraps this with a `TourProvider` + `useTour()`.
|
|
7
|
+
|
|
8
|
+
Use `core` directly if you're integrating with a non-React app or building your
|
|
9
|
+
own bindings.
|
|
10
|
+
|
|
11
|
+
## Install
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
npm i @guided-tour-s4marth/core driver.js
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
Import driver.js's CSS once in your app entry: `import 'driver.js/dist/driver.css'`.
|
|
18
|
+
|
|
19
|
+
## What's inside
|
|
20
|
+
|
|
21
|
+
- **`playTour(opts)`** — plays a tour: runs each step's prepare path, resolves the
|
|
22
|
+
target, animates the spotlight (single persistent driver.js instance), handles
|
|
23
|
+
next/skip/close, emits telemetry.
|
|
24
|
+
- **Locator + signature targeting** (`locator.ts`) — `buildLocator(el)` (capture),
|
|
25
|
+
`resolveLocator(loc)` (runtime, with self-heal), `encode/decodeLocator`,
|
|
26
|
+
`getXPath`, `signatureMatches`, `waitForLocator`. A locator is encoded into a
|
|
27
|
+
step's `anchorId` as `loc:<json>`; resolution tries `testid → domId → xpath`,
|
|
28
|
+
then self-heals to a unique element matching the signature.
|
|
29
|
+
- **`parseTour` / `parseTours`** — zod-validate tour data.
|
|
30
|
+
- **`isTourEligible`** — evaluate route/role/version/flag conditions.
|
|
31
|
+
- **`SeenStore`** adapters + **telemetry** (`setTelemetryHandler`).
|
|
32
|
+
|
|
33
|
+
## Minimal usage
|
|
34
|
+
|
|
35
|
+
```ts
|
|
36
|
+
import { parseTours, playTour } from '@guided-tour-s4marth/core';
|
|
37
|
+
import 'driver.js/dist/driver.css';
|
|
38
|
+
|
|
39
|
+
const tours = parseTours(await fetch('/api/tours').then(r => r.json()));
|
|
40
|
+
await playTour({
|
|
41
|
+
tour: tours[0],
|
|
42
|
+
navigate: route => router.push(route),
|
|
43
|
+
onComplete: () => markSeen(tours[0].id),
|
|
44
|
+
});
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
A step with no `anchorId` renders as a centered modal. Broken/missing targets are
|
|
48
|
+
skipped at runtime; if every step is missing, `onUnavailable` fires and the tour
|
|
49
|
+
isn't marked complete.
|
|
50
|
+
|
|
51
|
+
## License
|
|
52
|
+
|
|
53
|
+
MIT
|