@apollovisionlabs/guide-core 0.1.1 → 0.3.0

package/README.md

@@ -61,7 +61,7 @@ missing-target policy below from ever firing.
 
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
-| `labels` | `Partial<{ next, previous, finish, close }>` | `{ next: 'Next', previous: 'Back', finish: 'Finish', close: 'Close' }` | The popover's button labels. Defaults are English; override any subset. See "Translations". |
+| `labels` | `Partial<{ next, previous, finish, close, awaitingAction }>` | `{ next: 'Next', previous: 'Back', finish: 'Finish', close: 'Close', awaitingAction: 'Click the highlighted element to continue.' }` | The popover's button labels. Defaults are English; override any subset. See "Translations". |
 | `zIndex` | `number` | `theme.zIndex.modal` | Stacking level of the spotlight; the popover sits one above it. |
 | `padding` | `number` | `8` | Margin, in pixels, between the highlighted element and the edge of the spotlight hole. |
 | `radius` | `number` | `8` | Corner radius, in pixels, of the spotlight hole. |
@@ -101,43 +101,58 @@ the destination.
 
 ## Persistence
 
-`GuideStorage` is the two-method interface the provider reads from and writes to:
+`GuideStorage` is the two-method interface both `GuideProvider` and `ChecklistProvider` read from
+and write to. It is generic over the stored value, so one storage serves tour progress and
+checklist progress under different keys:
 
 ```ts
 interface GuideStorage {
-  read(tourId: string): Promise<TourProgress | null>
-  write(tourId: string, progress: TourProgress): Promise<void>
+  read<T>(key: string): Promise<T | null>
+  write<T>(key: string, value: T): Promise<void>
 }
 ```
 
+`GuideProvider` reads and writes tour progress under `tour:<id>`. `ChecklistProvider` reads and
+writes checklist progress under `checklist:<id>`. `HotspotProvider` reads and writes which
+hotspots have been opened under the single key `hotspots:seen`. See
+[ADR 0016](docs/adr/0016-one-storage-contract-for-tours-and-checklists.md) for why they share one
+interface.
+
 `@apollovisionlabs/guide-core` ships `createMemoryStorage()` for tests and `createBrowserStorage(namespace?)` for
 `localStorage`. Neither talks to a server. An implementation backed by your own API looks like
 this:
 
 ```ts
-import type { GuideStorage, TourProgress } from '@apollovisionlabs/guide-core'
+import type { GuideStorage } from '@apollovisionlabs/guide-core'
 
 function createServerStorage(): GuideStorage {
   return {
-    async read(tourId) {
-      const response = await fetch(`/api/tours/${tourId}/progress`)
+    async read<T>(key: string) {
+      const response = await fetch(`/api/guide/${key}`)
       if (!response.ok) return null
-      return (await response.json()) as TourProgress
+      return (await response.json()) as T
     },
-    async write(tourId, progress) {
-      await fetch(`/api/tours/${tourId}/progress`, {
+    async write<T>(key: string, value: T) {
+      await fetch(`/api/guide/${key}`, {
         method: 'PUT',
         headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify(progress),
+        body: JSON.stringify(value),
       })
     },
   }
 }
 ```
 
-Pass it as the `storage` prop. The provider reads on `start()` (unless an explicit `from` step
-index is passed, or `resume: false` is passed) and writes whenever a running tour advances or
-completes.
+Pass it as the `storage` prop on either provider. `GuideProvider` reads on `start()` (unless an
+explicit `from` step index is passed, or `resume: false` is passed) and writes whenever a running
+tour advances or completes. `ChecklistProvider` reads once on mount and writes whenever an item is
+ticked, completed or the checklist is dismissed.
+
+A value read back from storage is validated before it is trusted (`isTourProgress`,
+`isChecklistProgress`, `isHotspotsProgress`, all exported from `@apollovisionlabs/guide-core`): a
+value that does not
+match the expected shape, from a hand-edited store or an older version of this library, is treated
+the same as nothing stored, rather than crashing or resuming into a broken state.
 
 ## Translations
 
@@ -158,7 +173,8 @@ and nothing English remains:
 
 ## Events
 
-`onEvent` on `GuideProvider` receives every lifecycle event as a discriminated union:
+`onEvent` on `GuideProvider`, `ChecklistProvider` and `HotspotProvider` each receive their own
+lifecycle events, as a discriminated union of `GuideEvent`:
 
 | Event | Payload | When |
 | --- | --- | --- |
@@ -167,6 +183,11 @@ and nothing English remains:
 | `tour:stop` | `{ tourId, stepIndex }` | The tour is stopped before completion. |
 | `step:show` | `{ tourId, stepIndex, target }` | A step's target is resolved and the step becomes visible. |
 | `target:missing` | `{ tourId, stepIndex, target }` | A step's target didn't appear within `targetTimeoutMs`. |
+| `checklist:item-complete` | `{ checklistId, itemId }` | An item is completed, by finishing its linked tour or by a manual tick. Not emitted for an item already complete. |
+| `checklist:complete` | `{ checklistId }` | The last incomplete item in a checklist is completed. Fires on every transition into the complete state, so unticking an item and reticking it emits a second time. Deduplicate downstream if you count completions. |
+| `checklist:dismiss` | `{ checklistId }` | `dismiss()` is called. |
+| `hotspot:show` | `{ hotspotId }` | A hotspot's marker is actually drawn on screen. Emitted once per hotspot per mount. |
+| `hotspot:open` | `{ hotspotId }` | The hotspot's bubble is opened, which also marks it seen. Not emitted again for a bubble that is already open. |
 
 ## Accessibility
 
@@ -190,6 +211,265 @@ happens: `'skip'` moves to the next step, `'error'` stops the tour, and `'wait'`
 pauses and resumes automatically if the target appears later, for instance after a slow async
 render.
 
+## Advancing on an action
+
+A step can declare `advanceOn: 'click'` instead of ending on the popover's button:
+
+```ts
+{
+  target: 'project.share',
+  title: 'Share it',
+  body: 'Click the button yourself, this step is interactive.',
+  advanceOn: 'click',
+}
+```
+
+The step advances when the user clicks the target, not the popover. `advanceOn` implies
+`interactive`: a step that waits for a click has to let the click through, so `GuideProvider`
+derives both `interactive` and `awaitsAction` on `ActiveStep` from `advanceOn`, rather than
+requiring both to be set by hand. Read `activeStep.interactive` / `activeStep.awaitsAction`, not
+`step.interactive`, which is left `undefined` on a step that only sets `advanceOn`. See
+[ADR 0017](docs/adr/0017-advancing-on-an-action-implies-an-interactive-step.md).
+
+`@apollovisionlabs/guide-mui`'s popover reflects `awaitsAction`: no primary button, and the
+`awaitingAction` label in its place (see the `labels` row above). `ArrowRight` is ignored while a
+step awaits its action, since letting it through would be a way around the very thing the step is
+asking for; `Escape` and `ArrowLeft` still work.
+
+The click listener is attached, in the bubble phase, to the element resolved when the step
+opened, without `preventDefault` or `stopPropagation`, so your own click handler on the target
+still runs.
+
+If your application replaces that DOM node afterward, for instance by re-rendering a list, the
+listener goes with it and the step stops advancing. Nothing notices: the target was found once,
+so the timeout was already cleared, no `target:missing` is emitted and no `wait`, `skip` or
+`error` policy runs. The tour simply sits on that step. The consequence is specific to
+`advanceOn`, even though the cause is not: an `advanceOn` step offers no primary button and
+ignores `ArrowRight`, so a replaced node leaves the tour with `Escape` as its only exit. If the
+element a step points at can be re-created under it, either give it a stable target that survives
+the re-render or use an ordinary step with a Next button.
+
+## Checklist
+
+A checklist is a separate feature from the tour: a fixed list of items, each completed by
+finishing a linked tour or by a manual tick. An item can also carry an `href`, which navigates
+and nothing more. `ChecklistProvider` holds
+its state the way `GuideProvider` holds tour state, and nests inside it so that an item can launch
+a tour:
+
+```tsx
+import { GuideProvider, ChecklistProvider, type Tour, type Checklist } from '@apollovisionlabs/guide-core'
+import { GuideTour } from '@apollovisionlabs/guide-mui'
+import { ChecklistLauncher } from '@apollovisionlabs/guide-mui'
+
+const tour: Tour = {
+  id: 'welcome',
+  steps: [{ target: 'sidebar.projects', title: 'Your projects', body: 'Grouped under a project.' }],
+}
+
+const onboarding: Checklist = {
+  id: 'onboarding',
+  items: [
+    { id: 'tour', title: 'Take the tour', body: 'Two minutes.', tourId: 'welcome' },
+    { id: 'projects', title: 'Open your projects', body: 'See the list.', href: '/projects' },
+    { id: 'profile', title: 'Set your name', body: 'Manual, ticked by hand.' },
+  ],
+}
+
+function App() {
+  return (
+    <GuideProvider tours={[tour]} navigate={(path) => router.push(path)}>
+      <ChecklistProvider checklists={[onboarding]} navigate={(path) => router.push(path)}>
+        <Sidebar />
+        <GuideTour />
+        <ChecklistLauncher checklistId="onboarding" title="Get started" />
+      </ChecklistProvider>
+    </GuideProvider>
+  )
+}
+```
+
+An item with an `href`, or with neither `tourId` nor `href`, is completed by a manual tick only:
+activating an `href` item navigates and stops there, since arriving on a page is not evidence that
+anyone did anything on it. An item with `tourId`
+is completed automatically when that tour is finished (`next()` called on its last step); it can
+also be ticked by hand before that. Completion is idempotent: ticking an already-complete item, or
+finishing a tour whose item is already ticked, does nothing and emits no event.
+
+### `ChecklistProvider` props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `checklists` | `Checklist[]` | none | The checklists available to `useChecklist`. |
+| `children` | `ReactNode` | none | Your application. |
+| `storage` | `GuideStorage` | none | Persists checklist progress under `checklist:<id>`. See "Persistence". |
+| `translate` | `(key: string) => string` | none | Resolves `titleKey` / `bodyKey` on items. See "Translations". |
+| `navigate` | `(path: string) => void` | none | Called when an item with `href` is activated. |
+| `onEvent` | `(event: GuideEvent) => void` | none | Called for `checklist:item-complete`, `checklist:complete`, `checklist:dismiss`. See "Events". |
+
+### `useChecklist(checklistId)`
+
+Returns `{ items, completedCount, total, isComplete, dismissed, restored, activate, toggle, complete, dismiss, reset }`.
+`items` is `ResolvedChecklistItem[]`: `{ id, title, body, completed, tourId?, href? }`, with
+`title` / `body` already resolved through `translate`. `activate(itemId)` runs an item's default
+action (start its tour, navigate to its `href`, or toggle it if it has neither); `toggle` and
+`complete` change completion directly; `dismiss()` and `reset()` act on the whole checklist.
+`restored` is whether this checklist's own initial read from storage has settled: `true`
+immediately with no `storage` prop (there is nothing to wait for), and `true` once this
+checklist's own read has resolved or rejected. It settles independently per checklist, so a
+`ChecklistProvider` holding several checklists never lets a slow or hung read for one hold
+another one's `restored` false; each checklist's read runs concurrently with the others.
+
+### `Checklist` and `ChecklistLauncher` (`@apollovisionlabs/guide-mui`)
+
+`Checklist` renders the list inline: a progress bar, one row per item with a checkbox and a
+dismiss button. `ChecklistLauncher` wraps it behind a floating action button showing
+`completedCount/total`, opened as a popover. The popover stays open while items are ticked one
+after another, and closes when an item hands off to something that needs the screen: launching a
+tour or navigating to an `href`. It does not close on a plain tick.
+
+```tsx
+import { Checklist, ChecklistLauncher } from '@apollovisionlabs/guide-mui'
+
+<Checklist checklistId="onboarding" title="Get started" />
+// or, as a floating launcher:
+<ChecklistLauncher checklistId="onboarding" title="Get started" placement="bottom-right" />
+```
+
+With a `storage` prop configured on `ChecklistProvider`, both `Checklist` and `ChecklistLauncher`
+wait for their own checklist's restore to settle (`useChecklist(checklistId).restored`) before
+drawing anything, rather than rendering their empty initial state (nothing completed, not
+dismissed) for one paint. The tradeoff: with a slow storage backend, a checklist now appears later
+than it used to, instead of appearing at once and then jumping. A slow or broken read for one
+checklist never holds a different checklist back; each restores on its own.
+
+## Hotspots
+
+A hotspot marks one element outside any tour: a small marker that opens a short explanation, and
+optionally a button that starts a tour. Unlike a tour step, a hotspot has no route and no order;
+it just sits at its target until opened. `HotspotProvider` nests inside `GuideProvider`, the same
+way `ChecklistProvider` does, so a hotspot naming a `tourId` can start it:
+
+```tsx
+import {
+  GuideProvider,
+  HotspotProvider,
+  type Hotspot,
+  type Tour,
+} from '@apollovisionlabs/guide-core'
+import { GuideTour, Hotspots } from '@apollovisionlabs/guide-mui'
+
+const welcomeTour: Tour = {
+  id: 'welcome',
+  steps: [
+    { target: 'projects.create', title: 'Create a project', body: 'Start here.' },
+    { target: 'project.share', title: 'Share it', body: 'Send a link to your team.' },
+  ],
+}
+
+const hotspots: Hotspot[] = [
+  {
+    id: 'create',
+    target: 'projects.create',
+    title: 'Start a project',
+    body: 'Everything else in here hangs off a project.',
+  },
+  {
+    id: 'share',
+    target: 'project.share',
+    title: 'Share a project',
+    body: 'Send a link to anyone on your team.',
+    // Named tours must exist on the GuideProvider above, or starting one warns and does nothing.
+    tourId: 'welcome',
+  },
+]
+
+function App() {
+  return (
+    <GuideProvider tours={[welcomeTour]}>
+      <HotspotProvider hotspots={hotspots}>
+        <YourApplication />
+        <GuideTour />
+        <Hotspots />
+      </HotspotProvider>
+    </GuideProvider>
+  )
+}
+```
+
+Without a `GuideProvider` above it, starting a hotspot's tour warns once in the console and does
+nothing.
+
+### `HotspotProvider` props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `hotspots` | `Hotspot[]` | none | The hotspots to render. Ids must be unique. |
+| `children` | `ReactNode` | none | Your application. |
+| `storage` | `GuideStorage` | none | Persists which hotspots have been opened, under `hotspots:seen`. See "Persistence". |
+| `translate` | `(key: string) => string` | none | Resolves `titleKey` / `bodyKey` on hotspots. See "Translations". |
+| `onEvent` | `(event: GuideEvent) => void` | none | Called for `hotspot:show` and `hotspot:open`. See "Events". |
+
+### `useHotspots()`
+
+Returns `{ hotspots, restored, open, startTour, reset, notifyShown }`.
+
+- `hotspots` is `ResolvedHotspot[]`: every hotspot, each carrying its own `seen`, with `title` /
+  `body` already resolved through `translate`. It lists the seen ones too, rather than only the
+  unseen ones, because a renderer that keeps a marker mounted while its own bubble closes needs
+  the seen one as well; filtering to unseen-only is one line at the call site.
+- `restored` is whether the initial read from storage has settled: `true` immediately with no
+  `storage` prop (there is nothing to wait for), and `true` once the read resolves or rejects.
+  Wait for it before drawing any marker, or a hotspot already seen in storage can flash on screen
+  once before the restore lands.
+- `open(hotspotId)` marks a hotspot seen and emits `hotspot:open`.
+- `startTour(hotspotId)` starts the tour named by the hotspot's `tourId`, if it has one.
+- `reset()` clears the seen state for every hotspot.
+- `notifyShown(hotspotId)` is for renderers: call it once a marker is actually drawn on screen, so
+  `hotspot:show` fires once per hotspot per mount. `@apollovisionlabs/guide-mui`'s `Hotspots`
+  already calls it.
+
+### `Hotspots` (`@apollovisionlabs/guide-mui`)
+
+Renders a marker at each unseen hotspot's target; clicking it opens a bubble with the hotspot's
+title, body, and, when it names a `tourId`, a button that starts that tour.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `labels` | `Partial<{ marker, startTour, close }>` | see below | Wording. `marker` is a function of the hotspot's title, not a fixed string, because word order around a name varies by language. |
+| `placement` | `Placement` | `'bottom'` | Where the bubble opens relative to the marker. Overridable per hotspot through `Hotspot.placement`. |
+| `zIndex` | `number` | `theme.zIndex.drawer + 1` | Stacking level of the marker; the bubble sits one above it. |
+
+Default labels: `` { marker: (title) => `Show what is new: ${title}`, startTour: 'Show me', close: 'Close' } ``.
+
+No marker is drawn while a tour is running or paused. A hotspot is an ambient hint and must not
+compete with a guided flow the user is already in: a marker over the element a step points at
+would take the click meant for that step, and one over a non-interactive step would be drawn
+bright and pulsing yet inert behind the spotlight. The markers come back when the tour ends,
+unchanged: this suppresses them, it does not mark them seen. `Hotspots` reads the tour state
+through context and tolerates its absence, so hotspots work with no `GuideProvider` in the tree.
+
+`paused` counts, because a paused tour is waiting for its target rather than finished. Note what
+that implies at the edge: a tour paused on a target that never appears, the default `wait`
+policy, draws nothing itself and now hides every hotspot too, for as long as it stays paused,
+with `Escape` as the only way out and nothing on screen to suggest it. If your steps point at
+targets that may never mount, prefer the `skip` or `error` missing-target policy over `wait`.
+
+The default `zIndex` sits below `theme.zIndex.modal`, the level a running tour's spotlight uses,
+so a hotspot whose target lives inside your own modal dialog is covered by it. Raise `zIndex` on
+`Hotspots` to bring the marker above that dialog.
+
+A marker is drawn only for a target that has actual size on screen. An element that is in the DOM
+but not rendered, `display: none` for instance, measures an all-zero rectangle; that draws no
+marker and emits no `hotspot:show`, so a hotspot cannot be retired before the user has seen what
+it explains.
+
+Clicking a marker whose bubble is already open closes the bubble, and emits no second
+`hotspot:open`.
+
+With a `storage` prop configured on `HotspotProvider`, `Hotspots` waits for the initial restore to
+settle (`useHotspots().restored`) before drawing any marker.
+
 ## Compatibility
 
 | | Supported |