tutor-ai 0.0.0-stage → 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/LICENSE +21 -0
- package/README.md +206 -2
- package/assets/tutor-ai.png +0 -0
- package/dist/index.cjs +1148 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +241 -0
- package/dist/index.d.ts +241 -0
- package/dist/index.mjs +1119 -0
- package/dist/index.mjs.map +1 -0
- package/dist/styles.css +266 -0
- package/package.json +77 -4
- package/scripts/copy-css.mjs +12 -0
- package/scripts/install-skills.mjs +192 -0
- package/scripts/uninstall-skills.mjs +127 -0
- package/skills/tutor-ai/SKILL.md +160 -0
- package/skills/tutor-ai/references/api.md +146 -0
- package/skills/tutor-ai-authoring/SKILL.md +149 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 pauvalls
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,207 @@
|
|
|
1
|
-
|
|
1
|
+
<p align="center">
|
|
2
|
+
<img src="https://raw.githubusercontent.com/pauvalls/TutorAI/main/assets/tutor-ai.png" alt="TutorAI — AI-first guided tours for React" width="100%" />
|
|
3
|
+
</p>
|
|
2
4
|
|
|
3
|
-
|
|
5
|
+
# TutorAI
|
|
6
|
+
|
|
7
|
+
Generic, AI-First guided tours (coachmarks / spotlights) for React 18+ — data-driven, zero app copy, and Agent Skills generated in your project on install.
|
|
8
|
+
|
|
9
|
+
## AI First
|
|
10
|
+
|
|
11
|
+
Installing `tutor-ai` automatically writes two Agent Skills into the consumer project:
|
|
12
|
+
|
|
13
|
+
- `.claude/skills/tutor-ai` — how to install, configure and troubleshoot the library.
|
|
14
|
+
- `.claude/skills/tutor-ai-authoring` — how to design and author tours.
|
|
15
|
+
|
|
16
|
+
The same skills are copied to `.agents/skills`. An AI assistant in your repo can read them and author tours using your real selectors, context and labels — without you pasting documentation into every prompt. Install is idempotent; existing `SKILL.md` files are never overwritten.
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
TUTOR_AI_SKIP_SKILLS=1 npm install tutor-ai # disable
|
|
20
|
+
TUTOR_AI_SKILLS_FORCE=1 npm install tutor-ai # overwrite
|
|
21
|
+
TUTOR_AI_SKILLS_DIR=docs/skills npm install tutor-ai # extra destination
|
|
22
|
+
node node_modules/tutor-ai/scripts/uninstall-skills.mjs # remove generated skills
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
## Install
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
npm install tutor-ai
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
React 18+ and react-dom 18+ are peer dependencies. There are no other runtime dependencies.
|
|
32
|
+
|
|
33
|
+
## Quickstart
|
|
34
|
+
|
|
35
|
+
```tsx
|
|
36
|
+
import 'tutor-ai/styles.css';
|
|
37
|
+
import {
|
|
38
|
+
TutorProvider, TutorialGate, TutorialOverlay, TourResumePill,
|
|
39
|
+
type TourConfig,
|
|
40
|
+
} from 'tutor-ai';
|
|
41
|
+
|
|
42
|
+
const tour: TourConfig = {
|
|
43
|
+
id: 'basics',
|
|
44
|
+
title: 'Basics tour',
|
|
45
|
+
chapters: [{
|
|
46
|
+
id: 'getting-started',
|
|
47
|
+
steps: [
|
|
48
|
+
{
|
|
49
|
+
id: 'new',
|
|
50
|
+
title: 'Create a new item',
|
|
51
|
+
content: 'Click here to create your first item.',
|
|
52
|
+
target: '[data-test="new-item"]',
|
|
53
|
+
placement: 'bottom',
|
|
54
|
+
},
|
|
55
|
+
{
|
|
56
|
+
id: 'dialog',
|
|
57
|
+
title: 'The dialog',
|
|
58
|
+
content: 'This step follows the user into the modal.',
|
|
59
|
+
target: '[data-test="new-item"]',
|
|
60
|
+
targetWhen: { selector: '[role="dialog"]', when: 'visible' },
|
|
61
|
+
},
|
|
62
|
+
],
|
|
63
|
+
}],
|
|
64
|
+
gate: [{ id: 'basics', label: 'Take the basics tour', tourId: 'basics' }],
|
|
65
|
+
topics: [{ id: 'create', label: 'Creating', tourId: 'basics', keywords: ['new'] }],
|
|
66
|
+
};
|
|
67
|
+
|
|
68
|
+
export function App() {
|
|
69
|
+
return (
|
|
70
|
+
<TutorProvider
|
|
71
|
+
config={tour}
|
|
72
|
+
context={{ roles: ['editor'], capabilities: [], meta: {} }}
|
|
73
|
+
labels={{ gateTitle: 'Welcome!', next: 'Continue' }}
|
|
74
|
+
>
|
|
75
|
+
<TutorialGate />
|
|
76
|
+
<TutorialOverlay />
|
|
77
|
+
<TourResumePill />
|
|
78
|
+
{/* your application */}
|
|
79
|
+
</TutorProvider>
|
|
80
|
+
);
|
|
81
|
+
}
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
Keyboard shortcuts while a tour is running: `ArrowRight`/`Enter` = next, `ArrowLeft` = previous, `Escape` = skip. Inputs and textareas are ignored.
|
|
85
|
+
|
|
86
|
+
## API
|
|
87
|
+
|
|
88
|
+
| Export | Purpose |
|
|
89
|
+
| --- | --- |
|
|
90
|
+
| `TutorProvider` | Holds state; props: `config` (one or many `TourConfig`), `context?`, `labels?`. |
|
|
91
|
+
| `useTutor()` | Returns `state`, `currentStep`, `currentChapter`, `currentIndex`/`currentStepIndex`, `total`/`totalSteps`, `doneStepIds`, `completedTours`, `resumableTours`, `isRunning`, `isHeld`, `context`, `labels`, `tours`, `topics`, `config`, and commands below. |
|
|
92
|
+
| Commands | `start(tourId?, stepId?)`, `startTour` (alias), `startTopic(id)`, `openGate()`, `resume()`, `next()`, `prev()`, `goTo(stepId)`, `finish()`, `skip()`, `stop()`, `hold()`, `release()`, `resetProgress(tourId?)`, `filterTopics(query?)`, `resolveTopicSteps(id)`. |
|
|
93
|
+
| `TutorialGate` | Renders on `pending`; shows `gate` options, topic shortcuts and a topic filter. |
|
|
94
|
+
| `TutorialOverlay` | Optional manual mount: portal spotlight, card, progress, target waiting. |
|
|
95
|
+
| `TourResumePill` | Floating resume button for unfinished tours; opt out with `showResumePill: false`. |
|
|
96
|
+
| `holdTour()`, `releaseTour()`, `isTourHeld()` | Module-level pause switch (use `hold`/`release` from context inside components). |
|
|
97
|
+
| `createLocalStorage()`, `noopStorage` | Storage adapters. |
|
|
98
|
+
| `DEFAULT_LABELS` | English default strings. |
|
|
99
|
+
| Types | `TourConfig`, `TourChapter`, `TourStep`, `TourTopic`, `TourContext`, `TourLabels`, `GateOption`, `TourState`, `TourStorage`, `Placement`, `TargetResolver`, `TargetWhen`, `CoachmarkRenderProps`, plus other render-props and provider props. |
|
|
100
|
+
|
|
101
|
+
Key `TourConfig` options: `id`, `title`, `description`, `chapters`, `gate`, `topics`, `labels`, `context`, `storage`, `storageKey`, `defaultWaitForTarget` (1500 ms), `showProgress` (true), `showResumePill` (true), `scrollIntoView` (true), `isStepDone`, `renderGate`, `renderResumePill`, `renderCoachmark`.
|
|
102
|
+
|
|
103
|
+
Key `TourStep` options: `id`, `title`, `content`, `target` (selector or resolver), `targetWhen`, `placement`, `padding` (8), `when`, `isStepDone`, `onEnter`, `onExit`, `waitForTarget`, `advanceWhenHidden`, `scrollIntoView`.
|
|
104
|
+
|
|
105
|
+
All conditions are predicates over a generic context: `{ capabilities: string[], roles: string[], meta: Record<string, unknown> }`. No routes, roles or copy are baked into the library.
|
|
106
|
+
|
|
107
|
+
### Persistence and resume
|
|
108
|
+
|
|
109
|
+
Each tour stores JSON under `tutor-ai:<tourId>`: `{ done, stepId, updatedAt }`. Completed tours never show the gate again. Unfinished tours expose `resumableTours`, power `TourResumePill`, and can be restarted with `resume()`. Override with `storageKey` or a `storage` adapter; clear everything with `resetProgress()`.
|
|
110
|
+
|
|
111
|
+
### Hold / release
|
|
112
|
+
|
|
113
|
+
For a sensitive flow (e.g. a payment), freeze the engine without unmounting:
|
|
114
|
+
|
|
115
|
+
```ts
|
|
116
|
+
import { holdTour, releaseTour } from 'tutor-ai';
|
|
117
|
+
|
|
118
|
+
holdTour();
|
|
119
|
+
try {
|
|
120
|
+
await openPayment();
|
|
121
|
+
} finally {
|
|
122
|
+
releaseTour();
|
|
123
|
+
}
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
While held, commands are ignored, keyboard shortcuts are disabled, and the overlay is hidden. The current step is preserved.
|
|
127
|
+
|
|
128
|
+
### Topics
|
|
129
|
+
|
|
130
|
+
`TourTopic` groups steps: `{ id, label, description?, tourId, stepIds?, keywords? }`. `startTopic(id)` launches the tour at the first listed step and limits visible steps to that list; `filterTopics(query)` matches label, description and keywords. Omitting `stepIds` includes all steps.
|
|
131
|
+
|
|
132
|
+
## Theming
|
|
133
|
+
|
|
134
|
+
All classes are prefixed `tutorai-`. Override these custom properties:
|
|
135
|
+
|
|
136
|
+
```css
|
|
137
|
+
:root {
|
|
138
|
+
--tutorai-primary: #6d5efc;
|
|
139
|
+
--tutorai-surface: #ffffff;
|
|
140
|
+
--tutorai-text: #1f2430;
|
|
141
|
+
--tutorai-overlay: rgba(15, 18, 30, 0.55);
|
|
142
|
+
--tutorai-radius: 12px;
|
|
143
|
+
--tutorai-shadow: 0 18px 50px rgba(15, 18, 30, 0.24);
|
|
144
|
+
}
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
No fonts are loaded; typography inherits from your app.
|
|
148
|
+
|
|
149
|
+
## Gate customization
|
|
150
|
+
|
|
151
|
+
`gate` supplies generic options `{ id, label, description?, tourId? }`. For full control provide `renderGate`:
|
|
152
|
+
|
|
153
|
+
```tsx
|
|
154
|
+
renderGate: ({ options, topics, labels, start, startTopic, skip, filterTopics }) => (
|
|
155
|
+
<MyGate options={options} topics={topics} labels={labels}
|
|
156
|
+
onStart={start} onTopic={startTopic} onSkip={skip} filterTopics={filterTopics} />
|
|
157
|
+
)
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
The same pattern applies to `renderResumePill`.
|
|
161
|
+
|
|
162
|
+
## Coachmark customization
|
|
163
|
+
|
|
164
|
+
`renderCoachmark` is a custom coachmark renderer for apps with their own design system or analytics/test hooks. `TutorialOverlay` keeps measuring the target, waiting for late selectors and driving navigation; your renderer only supplies the card UI. It receives `step`, `chapter`, `index` (0-based), `total`, `context`, `labels`, `isHeld`, `target`, `hole`, `placement`, `cardSize`, `missing`, and the `next`/`prev`/`skip`/`finish` commands.
|
|
165
|
+
|
|
166
|
+
```tsx
|
|
167
|
+
renderCoachmark: ({ step, index, total, hole, next, skip }) => (
|
|
168
|
+
<MyCoachmark
|
|
169
|
+
title={step.title}
|
|
170
|
+
body={step.content}
|
|
171
|
+
progress={`${index + 1}/${total}`}
|
|
172
|
+
rect={hole}
|
|
173
|
+
data-testid={`coachmark-${step.id}`}
|
|
174
|
+
onNext={() => void next()}
|
|
175
|
+
onSkip={() => void skip()}
|
|
176
|
+
/>
|
|
177
|
+
)
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
## i18n
|
|
181
|
+
|
|
182
|
+
Every visible string comes from `labels` (English defaults). Pass a translated partial object at provider or tour level. Step `title` and `content` are data — translate them in your app before building the config.
|
|
183
|
+
|
|
184
|
+
## Migrating from hardcoded tours
|
|
185
|
+
|
|
186
|
+
1. Move titles/content out of components into `TourStep.title` and `.content`.
|
|
187
|
+
2. Replace hardcoded `if (role === ...)` checks with `when: (ctx) => ...` over `TourContext`.
|
|
188
|
+
3. Replace manual "already seen" flags with `isStepDone` or default storage persistence.
|
|
189
|
+
4. Replace `document.querySelector` calls with `target` selectors or resolvers.
|
|
190
|
+
5. Wrap steps that depend on a modal with `targetWhen`.
|
|
191
|
+
6. Delete app-specific wrappers and mount `TutorialGate` + `TutorialOverlay` once.
|
|
192
|
+
|
|
193
|
+
## Development
|
|
194
|
+
|
|
195
|
+
```bash
|
|
196
|
+
npm install
|
|
197
|
+
npm run dev # tsup watch
|
|
198
|
+
npm run typecheck # tsc --noEmit
|
|
199
|
+
npm test # vitest + installer tests
|
|
200
|
+
npm run build # tsup + CSS copy
|
|
201
|
+
npm run skills:install
|
|
202
|
+
npm run skills:uninstall
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
## License
|
|
206
|
+
|
|
207
|
+
MIT © 2026 pauvalls
|
|
Binary file
|