API Reference

A condensed, complete reference. For narrative explanations and examples, see the Feature Guide.

`new SparkGuide(config)`

Option	Type	Description
`theme`	object	`primaryColor`, `textColor`, `backgroundColor`, `overlayColor`, `borderRadius`, `fontFamily`, `zIndex`
`storageKey`	string	`localStorage` namespace, default `"sparkguide"`
`user`	object	arbitrary attributes used by `segment` targeting rules

Instance methods

guide.on(event, handler)              // subscribe; returns an unsubscribe fn
guide.off(event, handler)
guide.identify(user)                  // merge new attributes into the current user

guide.addFlow(id, { steps, segment })
guide.start(id, { resume: true })
guide.startMatching()
guide.dismiss(id)
guide.resetFlow(id)

guide.addChecklist(id, { title, items })
guide.completeChecklistItem(checklistId, itemId)

guide.showBanner(opts)
guide.showModal(opts)
guide.showHotspot(opts)               // async — target may be a selector

guide.destroy()                       // remove all rendered UI (keeps saved progress)

Method	Details
`addFlow(id, def)`	`def` is `{ steps: Step[], segment?: SegmentRule }`. Registers a flow without starting it.
`start(id, opts?)`	Starts (or resumes) a flow if its segment matches. `{ resume: true }` is the default; `false` always replays from step 0 regardless of history. Returns the underlying `Guide` instance, or `null` if it didn't start.
`startMatching()`	Starts every registered flow whose segment matches and hasn't been completed/dismissed, one at a time — each is awaited to completion or dismissal before the next starts.
`dismiss(id)`	Closes an active flow early. Counts the same as completion for future auto-resume purposes.
`resetFlow(id)`	Clears a flow's saved progress and completion state entirely.
`identify(user)`	Shallow-merges new attributes into the current user object used by `segment` rules.
`addChecklist(id, def)`	`def` is `{ title?: string, items: {id, label}[] }`. Replaces any existing checklist with the same id.
`completeChecklistItem(checklistId, itemId)`	Programmatically marks an item done — call this from your own app's event handlers.
`showBanner(opts)`	`{ content, actionLabel?, onAction?, onClose? }`. Replaces any currently-shown banner.
`showModal(opts)`	`{ title?, content, primaryLabel?, secondaryLabel?, onPrimary?, onSecondary?, onClose? }`.
`showHotspot(opts)`	`{ target: string\|Element, title?, content?, placement? }`. `target` as a string is resolved the same way a flow step's target is (waits for it to appear).
`destroy()`	Removes every currently-rendered widget (tours, checklist, banner, hotspot). Does not touch saved progress in `localStorage`.

Step shape

{
  type: 'tooltip' | 'hotspot' | 'modal', // default: tooltip if `target` set, else modal
  target: '#css-selector',               // omit for modal steps
  title: 'string',
  content: 'string',
  placement: 'top' | 'bottom' | 'left' | 'right', // default 'bottom'
  advanceOn: 'click',                    // optional: auto-advance on target click
  showOverlay: true                      // tooltip-only: false skips the dimmed backdrop
}

Segment rule shape

All fields are optional; every one given must pass (logical AND).

{
  urlMatches: 'contains:/dashboard' | 'equals:/app' | /regex/,
  elementExists: '#some-selector',
  user: { plan: ['pro', 'trial'], role: 'admin' }   // value or array of allowed values
}

Events

Event	Arguments
`flow:start`	`(flowId)`
`flow:complete`	`(flowId)`
`flow:dismiss`	`(flowId, stepIndex)`
`step:show`	`(flowId, stepIndex, step)`
`step:complete`	`(flowId, stepIndex, step)`
`checklist:item`	`(checklistId, itemId, done)`
`checklist:complete`	`(checklistId)`

Named exports

Besides the default SparkGuide class, the package exports its building blocks for advanced use — a custom step type, a custom targeting rule, etc.

import {
  SparkGuide, Guide, EventBus, ProgressStore, Targeting,
  Tooltip, Hotspot, Modal, Banner, Checklist, ElementFinder
} from '@capsbharg/sparkguide-js';

Export	What it is
`SparkGuide`	The main entry point (also the default export).
`Guide`	Drives a single flow — walks its steps, persists progress, emits events.
`EventBus`	The minimal pub/sub used internally for all events.
`ProgressStore`	`localStorage`-backed persistence, with an in-memory fallback.
`Targeting`	The static segment/rule matcher — `Targeting.matches(rule, context)`.
`Tooltip`, `Hotspot`, `Modal`, `Banner`, `Checklist`	The individual UI components, usable standalone.
`ElementFinder`	Resolves a selector to an element asynchronously (`MutationObserver`-based) and watches for its removal.