SenangWebs Zero

A framework-agnostic, vanilla-TypeScript user-onboarding tour library. Renders guided product tours / onboarding walkthroughs with step-by-step dialogs, backdrop highlights, and collision-aware positioning.

npm install senangwebs-zero

Quick Start

NPM / Bundler

import { SenangWebsZero } from 'senangwebs-zero';
import 'senangwebs-zero/dist/swz.css';

const tour = new SenangWebsZero({ /* options */ });
tour.start();       // ungrouped steps
tour.start('nav');  // steps with data-swz-group="nav"

CDN / Global

<link rel="stylesheet" href="https://unpkg.com/senangwebs-zero/dist/swz.css">
<script src="https://unpkg.com/senangwebs-zero/dist/swz.umd.js"></script>
<script>
  const tour = new swz.SenangWebsZero({ /* options */ });
  tour.start();
</script>

Declaring Steps

Method 1: DOM Data Attributes

Add data-swz-tour to any element. The element becomes the highlight target. Step content is rendered as HTML, so only pass trusted or sanitized content.

<div data-swz-tour="Welcome to the dashboard!" data-swz-title="Step 1">Dashboard</div>
<button data-swz-tour="Click here to save" data-swz-group="editor">Save</button>

| Attribute | Description | |---|---| | data-swz-tour | Required. Step content (HTML allowed). | | data-swz-title | Title shown in dialog header. | | data-swz-group | Group key; step only runs with start("group"). | | data-swz-order | Sort order (ascending). | | data-swz-fixed | Treat target as position:fixed for highlight positioning. | | data-swz-margin | Per-step scroll margin override (px). | | data-swz-placement | Per-step dialog placement: auto, top, right, bottom, or left. |

Method 2: JS Object Array

const tour = new SenangWebsZero({
  steps: [
    { content: 'Welcome!', title: 'Intro', target: '#header', order: 1 },
    { content: 'Click save to continue.', target: '#save-btn', placement: 'right', order: 2 },
    { content: 'Centered step with no target.', title: 'Done', order: 3 },
  ],
});
tour.start();

Object steps support content, title, target, order, group, margin, fixed, and placement. Use placement: 'auto' to let SWZ pick the best side for that step, or set top, right, bottom, or left to prefer a side while still allowing viewport-safe fallback.

API

Constructor

new SenangWebsZero(options?: SWZOptions)

Does not auto-start.

Methods

| Method | Description | |---|---| | start(group?) | Begin the tour. With group, only steps matching that group run. | | visitStep('next' \| 'prev' \| number) | Navigate to next, previous, or specific step index. | | nextStep() | Advance one step (or finish if last). | | prevStep() | Go back one step. | | exit() | Close the tour without recording completion. Fires onBeforeExit/onAfterExit. | | finishTour(exit?, group?) | Programmatically mark complete. If exit is true (default), also closes the tour. | | isFinished(group?) | boolean — whether the tour group was completed. | | deleteFinishedTour(group?) | Clear the completion record. | | addSteps(steps[]) | Append object steps to the tour. | | setOptions(options) | Shallow-merge options at runtime. | | refresh() | Recompute steps (rescan DOM + object steps), re-render. | | refreshDialog() | Re-render dialog content/position only (no step recompute). | | updatePositions() | Recompute backdrop + dialog geometry only. |

Properties

| Property | Type | Description | |---|---|---| | isVisible | boolean | true while the tour is on screen. | | activeStep | number | Zero-based current step index. Writable; pair with refreshDialog(). | | tourSteps | SWZStep[] | Resolved, ordered step list. Mutable. | | dialog | HTMLElement | Dialog DOM node. | | backdrop | HTMLElement | Backdrop DOM node. | | options | SWZOptions | Active resolved options. | | group | string \| undefined | Active group if start(group) was used. |

Lifecycle Hooks

Single-handler, last-registration-wins. Each handler may be sync or return a Promise. Rejecting (or resolving false) cancels the gated action.

| Hook | Fires | Gating | |---|---|---| | onBeforeStepChange(fn) | Before step transition | reject → cancel change | | onAfterStepChange(fn) | After new step renders | no | | onBeforeExit(fn) | Before exit (escape, click‑outside, close btn) | reject → stay open | | onAfterExit(fn) | After teardown | no | | onFinish(fn) | Finish button on last step | reject → cancel finish |

tour.onBeforeStepChange(() => {
  if (!canProceed) throw new Error('Blocked'); // cancels navigation
});

tour.onFinish(async () => {
  await api.markOnboardingComplete();
});

Options (SWZOptions)

| Option | Type | Default | Description | |---|---|---|---| | steps | SWZStep[] | [] | Steps declared as objects at construction. | | autoScroll | boolean | true | Scroll window so target is in view. | | autoScrollSmooth | boolean | true | Use smooth scrolling. | | autoScrollOffset | number | 20 | Margin (px) around target when scrolling. | | backdropColor | string | 'rgba(20,20,21,0.84)' | Overlay color (any valid CSS). | | backdropClass | string | '' | Extra CSS class on backdrop element. | | backdropAnimate | boolean | true | Animate cutout position between steps. | | targetPadding | number | 30 | Padding (px) of the highlight cut‑out. | | dialogClass | string | '' | Extra CSS class on dialog element. | | dialogZ | number | 999 | z-index of the dialog. | | dialogWidth | number | 0 | Fixed dialog width (px). 0 = auto. | | dialogMaxWidth | number | 340 | Max dialog width (px). | | dialogPlacement | 'auto'\|'top'\|'right'\|'bottom'\|'left' | undefined | Preferred side. auto or undefined lets SWZ choose. | | dialogAnimate | boolean | true | Animate dialog position between steps. | | closeButton | boolean | true | Show close (✕) button. | | nextLabel | string | 'Next' | Next button text. | | prevLabel | string | 'Back' | Back button text. | | finishLabel | string | 'Finish' | Final-step button text. | | hideNext | boolean | false | Hide next button. | | hidePrev | boolean | false | Hide back button. | | showButtons | boolean | true | Master toggle for nav buttons. | | showStepDots | boolean | true | Show progress dots. | | stepDotsPlacement | 'footer'\|'body' | 'footer' | Where dots render. | | showStepProgress | boolean | true | Show n/total progress text. | | progressBar | string | '' | Color string → renders progress bar. | | completeOnFinish | boolean | true | Persist completion in localStorage. | | rememberStep | boolean | false | Resume from last active step on reopen. | | exitOnEscape | boolean | true | Escape key exits the tour. | | exitOnClickOutside | boolean | true | Click outside dialog exits. | | keyboardControls | boolean | true | Arrow keys navigate, Escape exits. | | propagateEvents | boolean | false | Allow interaction with target through highlight. | | debug | boolean | true | Emit console diagnostics. |

Persistence

Completion is tracked in localStorage using swz:-prefixed keys keyed by group (default group = "tour").

tour.onFinish(() => console.log('done'));

tour.start('onboarding');
tour.isFinished('onboarding');  // true after finishing
tour.deleteFinishedTour('onboarding');  // reset

With rememberStep: true, the last active step is also stored and resumed on next start().

CSS Classes

All DOM elements use the .swz-* namespace:

.swz-backdrop          — full-viewport overlay
  .swz-cutout          — highlight hole (child of backdrop)
.swz-dialog            — floating popover
  .swz-dialog-header
    .swz-dialog-title
    .swz-dialog-close
  .swz-progressbar     — colored bar under header
  .swz-dialog-body
  .swz-dots            — step indicator dots
  .swz-dialog-footer
    .swz-prev          — back button
    .swz-progress      — "n/total" text
    .swz-next          — next/finish button
  .swz-arrow           — caret pointing at target

Pass dialogClass / backdropClass for custom styling hooks.

Accessibility

• Dialog has role="dialog", aria-modal, and aria-label from step title.
• Focus moves to dialog on each step; focus returns to trigger element on exit.
• Tab is trapped within the dialog while open.
• All buttons are real <button>s with accessible names.
• prefers-reduced-motion: reduce disables all animations and smooth scrolling.

TypeScript

Full type definitions ship with the package:

import type { SWZOptions, SWZPlacement, SWZStep } from 'senangwebs-zero';

Build

npm run build          # JS (rollup) + CSS (sass)
npm run build:js       # rollup only
npm run build:css      # sass only
npm run lint           # tsc --noEmit

Outputs:

| File | Format | |---|---| | dist/swz.esm.mjs | ES Module | | dist/swz.cjs.js | CommonJS | | dist/swz.umd.js | UMD (CDN global swz) | | dist/swz.css | Compiled CSS | | dist/types/ | .d.ts declarations |

License

MIT