@apollovisionlabs/guide-core 0.2.0 → 0.3.1

package/README.md

@@ -2,9 +2,11 @@
 
 `guide` is a headless React library for building in-app product tours. `@apollovisionlabs/guide-core` owns the
 state machine, target resolution, routing, persistence and accessibility concerns, and exposes
-them as hooks with no rendering opinion. `@apollovisionlabs/guide-mui` consumes those hooks to render a tour with
-[MUI](https://mui.com) components (a spotlight overlay and a popover), so you get a complete tour
-out of the box, or you can render your own UI on top of `@apollovisionlabs/guide-core` directly.
+them as hooks with no rendering opinion. Two packages render on top of those hooks out of the box:
+`@apollovisionlabs/guide-mui` with [MUI](https://mui.com) components (a spotlight overlay and a
+popover), and `@apollovisionlabs/guide-unstyled` with the same parts as plain DOM elements and an
+optional stylesheet. You can also render your own UI on top of `@apollovisionlabs/guide-core`
+directly.
 
 This repository includes a runnable demo. From the repo root, run `pnpm --filter demo dev` and
 open `http://localhost:5173` to try a three-page tour end to end.
@@ -61,7 +63,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. |
@@ -113,8 +115,10 @@ interface GuideStorage {
 ```
 
 `GuideProvider` reads and writes tour progress under `tour:<id>`. `ChecklistProvider` reads and
-writes checklist progress under `checklist:<id>`. See [ADR 0016](docs/adr/0016-one-storage-contract-for-tours-and-checklists.md)
-for why the two share one interface.
+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
@@ -147,7 +151,8 @@ tour advances or completes. `ChecklistProvider` reads once on mount and writes w
 ticked, completed or the checklist is dismissed.
 
 A value read back from storage is validated before it is trusted (`isTourProgress`,
-`isChecklistProgress`, both exported from `@apollovisionlabs/guide-core`): a value that does not
+`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.
 
@@ -170,8 +175,8 @@ and nothing English remains:
 
 ## Events
 
-`onEvent` on `GuideProvider` and on `ChecklistProvider` each receive their own lifecycle events, as
-a discriminated union of `GuideEvent`:
+`onEvent` on `GuideProvider`, `ChecklistProvider` and `HotspotProvider` each receive their own
+lifecycle events, as a discriminated union of `GuideEvent`:
 
 | Event | Payload | When |
 | --- | --- | --- |
@@ -183,6 +188,8 @@ a discriminated union of `GuideEvent`:
 | `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
 
@@ -206,6 +213,44 @@ 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
@@ -266,11 +311,16 @@ finishing a tour whose item is already ticked, does nothing and emits no event.
 
 ### `useChecklist(checklistId)`
 
-Returns `{ items, completedCount, total, isComplete, dismissed, activate, toggle, complete, dismiss, reset }`.
+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`)
 
@@ -288,12 +338,147 @@ import { Checklist, ChecklistLauncher } from '@apollovisionlabs/guide-mui'
 <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 |
 | --- | --- |
 | React | 19 |
 | MUI (`@apollovisionlabs/guide-mui` only) | 7, 9 |
+| `@apollovisionlabs/guide-unstyled` | no UI toolkit; peers on `react` and `react-dom` only |
 | Rendering | ESM and CommonJS, with `"use client"` for Next's App Router |
 
 ## Prior art
@@ -301,8 +486,9 @@ import { Checklist, ChecklistLauncher } from '@apollovisionlabs/guide-mui'
 The spotlight-and-popover approach is inspired by [driver.js](https://driverjs.com) (MIT), as are
 [react-joyride](https://github.com/gilbarbara/react-joyride) (MIT) and
 [reactour](https://github.com/elrumordelaluz/reactour) (MIT). `guide` differs from all three mainly
-in splitting the state machine (`@apollovisionlabs/guide-core`) from rendering (`@apollovisionlabs/guide-mui`), so the logic can be
-reused with a different design system. Contributors must also read the licence discipline in
+in splitting the state machine (`@apollovisionlabs/guide-core`) from rendering, which ships as two
+packages, `@apollovisionlabs/guide-mui` and `@apollovisionlabs/guide-unstyled`, so the same logic
+renders through a design system or through plain DOM. Contributors must also read the licence discipline in
 `CONTRIBUTING.md` before looking at any other tour library.
 
 ## Documentation