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 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
- # Temporary Holding Version
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
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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