@docentjs/core 0.1.0 → 0.2.0

package/README.md

@@ -22,6 +22,7 @@ export const welcome: Tour = defineTour({
 ## What's here
 
 - **Schema types**: `Tour`, `Step`, `Target`, `Condition`, `Trigger`, `Theme`, and the rest of the JSON contract.
+- **`Docent`**: the tour manager. Watches triggers, checks conditions and frequency per user, runs one tour at a time. Use `createDocent` from `@docentjs/dom` in the browser.
 - **`TourController`**: drives one tour against a `Renderer`; handles hooks, lazy targets, route pauses, persistence and events.
 - **Engine helpers**: `reduce`, `evaluateCondition`, `matchRoute`, `shouldShow`, `ProgressStore`, `createEvent`.
 - **Seams**: `TourSource`, `Identity`, `StorageAdapter`, `EventSink` so tours can come from and report to anywhere.

package/dist/index.cjs

@@ -666,7 +666,346 @@ var TourController = class {
 	}
 };
 //#endregion
+//#region src/manager/scoped-storage.ts
+/**
+* Prefix every key with the user id so progress on a shared browser (or a
+* developer switching test accounts) never leaks between users.
+* Anonymous visitors use the unprefixed keys.
+*/
+function scopeStorage(base, userId) {
+	if (!userId) return base;
+	const prefix = `u:${userId}:`;
+	return {
+		get: (key) => base.get(prefix + key),
+		set: (key, value) => base.set(prefix + key, value),
+		remove: (key) => base.remove(prefix + key)
+	};
+}
+//#endregion
+//#region src/manager/docent.ts
+/**
+* The tour manager. Holds many tours, watches their triggers, checks
+* conditions and frequency, and starts at most one at a time. This is what
+* turns the rules in the tour JSON into behaviour.
+*/
+function isTourSource(value) {
+	return !!value && !Array.isArray(value) && typeof value.load === "function";
+}
+var Docent = class {
+	/** Resolves once tours and progress are loaded and triggers are armed. */
+	ready;
+	options;
+	env;
+	baseStorage;
+	identity;
+	store;
+	tours = /* @__PURE__ */ new Map();
+	records = /* @__PURE__ */ new Map();
+	controller;
+	activeId = null;
+	/** Tours whose trigger fired while another tour was running. */
+	queue = [];
+	triggerCleanups = [];
+	/** `auto` triggers fire once per manager instance (per page load), not on every re-arm. */
+	autoFired = /* @__PURE__ */ new Set();
+	cleanups = [];
+	timers = /* @__PURE__ */ new Set();
+	listeners = /* @__PURE__ */ new Set();
+	destroyed = false;
+	constructor(options) {
+		this.options = options;
+		this.env = options.environment;
+		this.identity = options.identity ?? ANONYMOUS_IDENTITY;
+		this.baseStorage = options.storage ?? createMemoryStorage();
+		this.store = new ProgressStore(scopeStorage(this.baseStorage, this.identity.id));
+		this.ready = this.init();
+	}
+	getState() {
+		return {
+			active: this.activeId,
+			tours: [...this.tours.keys()]
+		};
+	}
+	subscribe(listener) {
+		this.listeners.add(listener);
+		return () => this.listeners.delete(listener);
+	}
+	/** The controller of the running tour, for fine-grained control. */
+	get activeController() {
+		return this.controller;
+	}
+	/**
+	* Set who the user is. Progress is stored per user id, and traits feed
+	* `trait` conditions. Re-evaluates triggers, since the user may now qualify.
+	*/
+	async identify(id, traits = {}) {
+		await this.ready;
+		const userChanged = id !== this.identity.id;
+		this.identity = id === void 0 ? { traits } : {
+			id,
+			traits
+		};
+		if (userChanged) {
+			this.autoFired.clear();
+			this.store = new ProgressStore(scopeStorage(this.baseStorage, id));
+			await this.loadRecords();
+		}
+		this.armTriggers();
+	}
+	/**
+	* Report something that happened in your app. Starts tours with a matching
+	* `event` trigger and advances a running step waiting on that event.
+	*/
+	track(eventName) {
+		this.controller?.notify(eventName);
+		for (const tour of this.tours.values()) {
+			const t = tour.trigger;
+			if (t?.type === "event" && t.name === eventName) this.fire(tour.id);
+		}
+	}
+	/**
+	* Start a tour now, ignoring its trigger, conditions and frequency. Use for
+	* "take the tour" buttons. Stops any tour already running.
+	*/
+	async start(tourId, options = {}) {
+		await this.ready;
+		const tour = this.tours.get(tourId);
+		if (!tour) return false;
+		await this.stopActive();
+		await this.run(tour, options.at, true);
+		return true;
+	}
+	/** Whether a tour's conditions hold and its frequency allows showing it now. */
+	isEligible(tourId) {
+		const tour = this.tours.get(tourId);
+		if (!tour) return false;
+		return shouldShow(tour, this.records.get(tourId) ?? null) && evaluateAll(tour.conditions, this.conditionEnv());
+	}
+	/** Progress state of a tour for the current user. */
+	tourState(tourId) {
+		const tour = this.tours.get(tourId);
+		const record = this.records.get(tourId);
+		if (!record) return "not-started";
+		if (tour && record.version < tourVersion(tour)) return "not-started";
+		return record.state;
+	}
+	/** Forget progress for one tour, or all of them, so they show again. */
+	async reset(tourId) {
+		await this.ready;
+		const ids = tourId ? [tourId] : [...this.tours.keys()];
+		for (const id of ids) {
+			await this.store.clear(id);
+			this.records.set(id, null);
+			this.autoFired.delete(id);
+		}
+		this.armTriggers();
+	}
+	/**
+	* Re-check triggers and tell the running tour the route may have changed.
+	* Call after navigation if your router does not emit browser navigation events.
+	*/
+	async refresh() {
+		await this.ready;
+		this.armTriggers();
+		await this.controller?.routeChanged();
+	}
+	/** Stop the running tour (recorded as skipped). */
+	async stop() {
+		await this.controller?.skip();
+	}
+	async destroy() {
+		this.destroyed = true;
+		this.disarmTriggers();
+		for (const c of this.cleanups) c();
+		this.cleanups.length = 0;
+		const controller = this.controller;
+		this.controller = void 0;
+		this.activeId = null;
+		await controller?.destroy();
+		this.listeners.clear();
+	}
+	async init() {
+		const source = this.options.tours;
+		const initial = isTourSource(source) ? await source.load() : source ?? [];
+		this.setTours(initial);
+		await this.loadRecords();
+		if (this.destroyed) return;
+		if (isTourSource(source) && source.subscribe) this.cleanups.push(source.subscribe((tours) => {
+			this.setTours(tours);
+			this.loadRecords().then(() => this.armTriggers());
+		}));
+		if (this.env.onRouteChange) this.cleanups.push(this.env.onRouteChange(() => this.armTriggers()));
+		this.armTriggers();
+	}
+	setTours(tours) {
+		this.tours = new Map(tours.map((t) => [t.id, t]));
+		this.queue = this.queue.filter((id) => this.tours.has(id));
+		this.emitState();
+	}
+	async loadRecords() {
+		const entries = await Promise.all([...this.tours.keys()].map(async (id) => [id, await this.store.get(id)]));
+		this.records = new Map(entries);
+	}
+	disarmTriggers() {
+		for (const c of this.triggerCleanups) c();
+		this.triggerCleanups = [];
+		for (const t of this.timers) clearTimeout(t);
+		this.timers.clear();
+	}
+	/**
+	* (Re)arm every trigger. Cheap; called on load, identify, route change,
+	* source updates and after a tour finishes (so chained tours can start).
+	* `except` skips one tour, used for the tour that just finished.
+	*/
+	armTriggers(except) {
+		if (this.destroyed) return;
+		this.disarmTriggers();
+		for (const tour of this.tours.values()) {
+			const trigger = tour.trigger;
+			if (!trigger || tour.id === except) continue;
+			this.arm(tour, trigger);
+		}
+	}
+	arm(tour, trigger) {
+		switch (trigger.type) {
+			case "manual":
+			case "event": return;
+			case "auto":
+				if (this.autoFired.has(tour.id)) return;
+				this.fireAfter(tour.id, trigger.delay);
+				return;
+			case "route": {
+				const route = this.env.currentRoute?.();
+				if (route !== void 0 && matchRoute(trigger.pattern, route)) this.fireAfter(tour.id, trigger.delay);
+				return;
+			}
+			case "element":
+				if (!this.env.watchTarget) {
+					if (this.env.hasTarget(trigger.target)) this.fireAfter(tour.id, trigger.delay);
+					return;
+				}
+				this.triggerCleanups.push(this.env.watchTarget(trigger.target, () => this.fireAfter(tour.id, trigger.delay)));
+		}
+	}
+	fireAfter(tourId, delay) {
+		if (!delay) {
+			this.fire(tourId);
+			return;
+		}
+		const timer = setTimeout(() => {
+			this.timers.delete(timer);
+			this.fire(tourId);
+		}, delay);
+		this.timers.add(timer);
+	}
+	/** A trigger fired: start the tour if eligible, or queue it behind the running one. */
+	fire(tourId) {
+		if (this.destroyed || tourId === this.activeId) return;
+		if (!this.isEligible(tourId) || !this.triggerStillHolds(tourId)) return;
+		if (this.tours.get(tourId)?.trigger?.type === "auto") this.autoFired.add(tourId);
+		if (this.activeId) {
+			if (!this.queue.includes(tourId)) this.queue.push(tourId);
+			return;
+		}
+		const tour = this.tours.get(tourId);
+		if (tour) this.run(tour, void 0, false);
+	}
+	/** Route triggers are only valid while the user is still on a matching route. */
+	triggerStillHolds(tourId) {
+		const trigger = this.tours.get(tourId)?.trigger;
+		if (trigger?.type !== "route") return true;
+		const route = this.env.currentRoute?.();
+		return route !== void 0 && matchRoute(trigger.pattern, route);
+	}
+	conditionEnv() {
+		const env = {
+			identity: this.identity,
+			elementExists: (t) => this.env.hasTarget(t),
+			tourState: (id) => this.tourState(id),
+			custom: this.options.custom ?? {}
+		};
+		const route = this.env.currentRoute?.();
+		if (route !== void 0) env.route = route;
+		return env;
+	}
+	sharedOptions(tour) {
+		const shared = {
+			identity: this.identity,
+			storage: scopeStorage(this.baseStorage, this.identity.id),
+			tourState: (id) => this.tourState(id)
+		};
+		if (this.options.sink) shared.sink = this.options.sink;
+		const hooks = this.options.hooks?.[tour.id];
+		if (hooks) shared.hooks = hooks;
+		if (this.options.custom) shared.custom = this.options.custom;
+		if (this.options.now) shared.now = this.options.now;
+		return shared;
+	}
+	async run(tour, at, manual) {
+		this.queue = this.queue.filter((id) => id !== tour.id);
+		const controller = this.options.createController(tour, this.sharedOptions(tour));
+		this.controller = controller;
+		this.activeId = tour.id;
+		this.emitState();
+		const off = controller.subscribe((state) => {
+			if (state.status === "completed" || state.status === "skipped" || state.status === "aborted") {
+				off();
+				this.finished(controller, tour, state.status === "completed" ? "completed" : "skipped");
+			}
+		});
+		if (!manual && at === void 0 && tour.options?.persist) await controller.resume();
+		else await controller.start(at);
+		if (controller.getState().status === "idle" && this.controller === controller) {
+			off();
+			this.release(controller);
+		}
+	}
+	/**
+	* The controller emits the final status before it finishes writing storage,
+	* so record the outcome here directly instead of reading it back.
+	*/
+	finished(controller, tour, state) {
+		if (this.controller !== controller) return;
+		this.records.set(tour.id, {
+			tourId: tour.id,
+			version: tourVersion(tour),
+			state,
+			updatedAt: (this.options.now ?? Date.now)()
+		});
+		this.release(controller, tour.id);
+	}
+	release(controller, finishedId) {
+		this.controller = void 0;
+		this.activeId = null;
+		this.emitState();
+		setTimeout(() => {
+			controller.destroy();
+			this.drainQueue();
+			if (!this.activeId) this.armTriggers(finishedId);
+		}, 0);
+	}
+	/** Stop the running tour without recording an outcome (used before a manual start). */
+	async stopActive() {
+		const controller = this.controller;
+		if (!controller) return;
+		this.controller = void 0;
+		this.activeId = null;
+		await controller.destroy();
+	}
+	drainQueue() {
+		while (this.queue.length > 0 && !this.activeId) {
+			const next = this.queue.shift();
+			if (next) this.fire(next);
+		}
+	}
+	emitState() {
+		const state = this.getState();
+		for (const l of this.listeners) l(state);
+	}
+};
+//#endregion
 exports.ANONYMOUS_IDENTITY = ANONYMOUS_IDENTITY;
+exports.Docent = Docent;
 exports.IDLE_STATE = IDLE_STATE;
 exports.NOOP_SINK = NOOP_SINK;
 exports.ProgressStore = ProgressStore;
@@ -689,6 +1028,7 @@ exports.matchRoute = matchRoute;
 exports.progress = progress;
 exports.reduce = reduce;
 exports.resolveStepIndex = resolveStepIndex;
+exports.scopeStorage = scopeStorage;
 exports.shouldShow = shouldShow;
 exports.storageKey = storageKey;
 exports.tourVersion = tourVersion;