@docentjs/core 0.1.0

package/dist/index.js

@@ -0,0 +1,670 @@
+//#region src/schema/tour.ts
+/**
+* Tour schema — the JSON contract shared by the core engine, every renderer,
+* the visual builder and the hosted service.
+*
+* Everything in this file must stay JSON-serialisable. Functions (hooks) live
+* in `hooks.ts` and are attached at runtime, keyed by step id.
+*/
+/** Current schema version. Bump only on breaking changes to this file. */
+const SCHEMA_VERSION = 1;
+//#endregion
+//#region src/define.ts
+/**
+* Identity helper that gives hand-written tours full type inference and
+* fills in the schema version. Returns the same object.
+*/
+function defineTour(tour) {
+	return {
+		...tour,
+		schemaVersion: 1
+	};
+}
+//#endregion
+//#region src/engine/route.ts
+/**
+* Route pattern matching for `route` triggers, conditions and step routes.
+*
+* Patterns are path globs:
+* - `/settings`          exact
+* - `/users/:id`         one segment (named for readability, value ignored)
+* - `/users/*`           one segment
+* - `/docs/**`           zero or more segments
+*
+* Query strings and hashes are ignored. Trailing slashes are tolerated.
+*/
+function segments(path) {
+	return (path.split(/[?#]/, 1)[0] ?? "").split("/").filter(Boolean);
+}
+function matchSegments(pattern, path, pi = 0, si = 0) {
+	if (pi === pattern.length) return si === path.length;
+	const p = pattern[pi];
+	if (p === "**") {
+		for (let k = si; k <= path.length; k++) if (matchSegments(pattern, path, pi + 1, k)) return true;
+		return false;
+	}
+	if (si === path.length) return false;
+	if (p === "*" || p?.startsWith(":") || p === path[si]) return matchSegments(pattern, path, pi + 1, si + 1);
+	return false;
+}
+function matchRoute(pattern, path) {
+	return matchSegments(segments(pattern), segments(path));
+}
+//#endregion
+//#region src/engine/conditions.ts
+function sameValue(a, b) {
+	if (Array.isArray(a) && Array.isArray(b)) return a.length === b.length && a.every((v, i) => v === b[i]);
+	return a === b;
+}
+function compare(a, b) {
+	if (typeof a === "number" && typeof b === "number") return a - b;
+	if (typeof a === "string" && typeof b === "string") return a < b ? -1 : a > b ? 1 : 0;
+	return null;
+}
+function contains(haystack, needle) {
+	if (Array.isArray(haystack)) return typeof needle === "string" && haystack.includes(needle);
+	if (typeof haystack === "string") return (typeof needle === "string" || typeof needle === "number") && haystack.includes(String(needle));
+	return false;
+}
+function inList(value, list) {
+	if (!Array.isArray(list)) return false;
+	if (Array.isArray(value)) return value.some((v) => list.includes(v));
+	return typeof value === "string" && list.includes(value);
+}
+function evaluateTrait(actual, op, expected) {
+	switch (op) {
+		case "exists": return actual !== void 0 && actual !== null;
+		case "missing": return actual === void 0 || actual === null;
+		case "eq": return sameValue(actual, expected);
+		case "neq": return !sameValue(actual, expected);
+		case "in": return inList(actual, expected);
+		case "nin": return !inList(actual, expected);
+		case "contains": return contains(actual, expected);
+		case "gt":
+		case "gte":
+		case "lt":
+		case "lte": {
+			const c = compare(actual, expected);
+			if (c === null) return false;
+			if (op === "gt") return c > 0;
+			if (op === "gte") return c >= 0;
+			if (op === "lt") return c < 0;
+			return c <= 0;
+		}
+	}
+}
+function evaluateCondition(condition, env) {
+	switch (condition.type) {
+		case "trait": return evaluateTrait(env.identity.traits[condition.key], condition.op, condition.value);
+		case "route": return env.route !== void 0 && matchRoute(condition.pattern, env.route);
+		case "element": return (env.elementExists?.(condition.target) ?? false) === (condition.exists ?? true);
+		case "tour": return (env.tourState?.(condition.id) ?? "not-started") === condition.state;
+		case "all": return condition.conditions.every((c) => evaluateCondition(c, env));
+		case "any": return condition.conditions.some((c) => evaluateCondition(c, env));
+		case "not": return !evaluateCondition(condition.condition, env);
+		case "custom": return env.custom?.[condition.name]?.(condition.args) ?? false;
+	}
+}
+/** All conditions must hold. An empty or missing list holds. */
+function evaluateAll(conditions, env) {
+	return (conditions ?? []).every((c) => evaluateCondition(c, env));
+}
+//#endregion
+//#region src/seams.ts
+const ANONYMOUS_IDENTITY = { traits: {} };
+//#endregion
+//#region src/engine/progress.ts
+const STORAGE_PREFIX = "docent:";
+function storageKey(tourId) {
+	return `${STORAGE_PREFIX}${tourId}`;
+}
+function tourVersion(tour) {
+	return tour.version ?? 1;
+}
+/** Whether a tour should be offered given what the user has already done. */
+function shouldShow(tour, record) {
+	if (!record) return true;
+	if (record.version < tourVersion(tour)) return true;
+	switch (tour.options?.frequency ?? "once") {
+		case "always": return true;
+		case "until-completed": return record.state !== "completed";
+		case "once": return record.state === "not-started" || record.state === "in-progress";
+	}
+}
+var ProgressStore = class {
+	storage;
+	constructor(storage) {
+		this.storage = storage;
+	}
+	async get(tourId) {
+		const raw = await this.storage.get(storageKey(tourId));
+		if (!raw) return null;
+		try {
+			const parsed = JSON.parse(raw);
+			if (parsed.tourId !== tourId || typeof parsed.version !== "number" || !parsed.state) return null;
+			return parsed;
+		} catch {
+			return null;
+		}
+	}
+	async set(record) {
+		await this.storage.set(storageKey(record.tourId), JSON.stringify(record));
+	}
+	async clear(tourId) {
+		await this.storage.remove(storageKey(tourId));
+	}
+};
+/** In-memory adapter. Default when no storage is configured, and handy in tests. */
+function createMemoryStorage() {
+	const map = /* @__PURE__ */ new Map();
+	return {
+		get: (key) => map.get(key) ?? null,
+		set: (key, value) => {
+			map.set(key, value);
+		},
+		remove: (key) => {
+			map.delete(key);
+		}
+	};
+}
+//#endregion
+//#region src/engine/events.ts
+function createEvent(type, input) {
+	const event = {
+		type,
+		tourId: input.tour.id,
+		tourVersion: tourVersion(input.tour),
+		timestamp: (input.now ?? Date.now)(),
+		identity: input.identity
+	};
+	if (input.stepIndex !== void 0 && input.stepIndex >= 0) {
+		const step = input.tour.steps[input.stepIndex];
+		event.stepIndex = input.stepIndex;
+		if (step) event.stepId = step.id;
+	}
+	return event;
+}
+/** Sink that drops everything. Default when none is configured. */
+const NOOP_SINK = { emit() {} };
+/** Fan out to several sinks. */
+function combineSinks(...sinks) {
+	return { emit: (e) => {
+		for (const s of sinks) s.emit(e);
+	} };
+}
+//#endregion
+//#region src/engine/reducer.ts
+const IDLE_STATE = Object.freeze({
+	status: "idle",
+	index: -1,
+	history: []
+});
+function resolveStepIndex(tour, ref) {
+	if (typeof ref === "number") return ref >= 0 && ref < tour.steps.length ? ref : -1;
+	return tour.steps.findIndex((s) => s.id === ref);
+}
+/** First eligible index at or after `from` (or at or before, when `dir` is -1). -1 if none. */
+function findEligible(ctx, from, dir = 1) {
+	const total = ctx.tour.steps.length;
+	for (let i = from; i >= 0 && i < total; i += dir) if (ctx.isEligible(i)) return i;
+	return -1;
+}
+function advance(state, ctx, record) {
+	const next = findEligible(ctx, state.index + 1);
+	if (next === -1) return {
+		status: "completed",
+		index: state.index,
+		history: state.history
+	};
+	return {
+		status: "running",
+		index: next,
+		history: record ? [...state.history, state.index] : state.history
+	};
+}
+function reduce(state, action, ctx) {
+	switch (action.type) {
+		case "start": {
+			const at = action.at === void 0 ? 0 : resolveStepIndex(ctx.tour, action.at);
+			if (at === -1) return {
+				status: "aborted",
+				index: -1,
+				history: [],
+				reason: "unknown-step"
+			};
+			const first = findEligible(ctx, at);
+			if (first === -1) return {
+				status: "aborted",
+				index: -1,
+				history: [],
+				reason: "no-eligible-steps"
+			};
+			return {
+				status: "running",
+				index: first,
+				history: []
+			};
+		}
+		case "next":
+			if (state.status !== "running") return state;
+			return advance(state, ctx, true);
+		case "stepMissing":
+			if (state.status !== "running") return state;
+			if (ctx.tour.steps[state.index]?.onMissing === "abort") return {
+				...state,
+				status: "aborted",
+				reason: "target-missing"
+			};
+			return advance(state, ctx, false);
+		case "stepSkipped":
+			if (state.status !== "running") return state;
+			return advance(state, ctx, false);
+		case "back": {
+			if (state.status !== "running") return state;
+			const history = [...state.history];
+			let prev = history.pop();
+			while (prev !== void 0 && !ctx.isEligible(prev)) prev = history.pop();
+			if (prev === void 0) return state;
+			return {
+				status: "running",
+				index: prev,
+				history
+			};
+		}
+		case "go": {
+			if (state.status !== "running") return state;
+			const to = resolveStepIndex(ctx.tour, action.to);
+			if (to === -1 || to === state.index || !ctx.isEligible(to)) return state;
+			return {
+				status: "running",
+				index: to,
+				history: [...state.history, state.index]
+			};
+		}
+		case "pause":
+			if (state.status !== "running") return state;
+			return {
+				...state,
+				status: "paused",
+				reason: action.reason
+			};
+		case "resume": {
+			if (state.status !== "paused") return state;
+			const { reason: _reason, ...rest } = state;
+			return {
+				...rest,
+				status: "running"
+			};
+		}
+		case "skip":
+			if (state.status !== "running" && state.status !== "paused") return state;
+			return {
+				status: "skipped",
+				index: state.index,
+				history: state.history
+			};
+		case "complete":
+			if (state.status !== "running" && state.status !== "paused") return state;
+			return {
+				status: "completed",
+				index: state.index,
+				history: state.history
+			};
+		case "abort":
+			if (state.status !== "running" && state.status !== "paused") return state;
+			return {
+				...state,
+				status: "aborted",
+				reason: action.reason
+			};
+	}
+}
+function isActive(state) {
+	return state.status === "running" || state.status === "paused";
+}
+function isFinished(state) {
+	return state.status === "completed" || state.status === "skipped" || state.status === "aborted";
+}
+function canGoBack(state, ctx) {
+	return state.status === "running" && state.history.some((i) => ctx.isEligible(i));
+}
+/** True when another eligible step follows. False on the last step. */
+function hasNext(state, ctx) {
+	return state.status === "running" && findEligible(ctx, state.index + 1) !== -1;
+}
+/** Position over all steps, ineligible ones included, so numbers stay stable. */
+function progress(state, ctx) {
+	return {
+		current: state.index + 1,
+		total: ctx.tour.steps.length
+	};
+}
+//#endregion
+//#region src/engine/controller.ts
+const DEFAULT_WAIT_MS = 3e3;
+var TourController = class {
+	tour;
+	state = IDLE_STATE;
+	renderer;
+	identity;
+	store;
+	sink;
+	hooks;
+	custom;
+	tourStateOf;
+	defaultWaitMs;
+	now;
+	listeners = /* @__PURE__ */ new Set();
+	/** Bumped whenever an async flow must be abandoned. */
+	generation = 0;
+	pendingAbort;
+	pendingTimer;
+	constructor(options) {
+		this.tour = options.tour;
+		this.renderer = options.renderer;
+		this.identity = options.identity ?? ANONYMOUS_IDENTITY;
+		this.store = new ProgressStore(options.storage ?? createMemoryStorage());
+		this.sink = options.sink ?? NOOP_SINK;
+		this.hooks = options.hooks ?? {};
+		this.custom = options.custom ?? {};
+		this.tourStateOf = options.tourState;
+		this.defaultWaitMs = options.defaultWaitMs ?? DEFAULT_WAIT_MS;
+		this.now = options.now ?? Date.now;
+	}
+	getState() {
+		return this.state;
+	}
+	subscribe(listener) {
+		this.listeners.add(listener);
+		return () => this.listeners.delete(listener);
+	}
+	/** Start from the first eligible step, or from `at` (step id or index). */
+	async start(at) {
+		if (this.state.status === "running" || this.state.status === "paused") return;
+		this.cancelPending();
+		this.dispatch(at === void 0 ? { type: "start" } : {
+			type: "start",
+			at
+		});
+		if (isFinished(this.state)) return this.finish();
+		this.emit("tour:started");
+		this.hooks.onStart?.(this.tour);
+		await this.persist("in-progress");
+		await this.showCurrent();
+	}
+	/** Start where the user left off, according to persisted progress. */
+	async resume() {
+		const record = await this.store.get(this.tour.id);
+		if (record?.state === "in-progress" && record.version === tourVersion(this.tour)) return this.start(record.stepId);
+		return this.start();
+	}
+	async next() {
+		if (this.state.status !== "running") return;
+		await this.leaveCurrent();
+		this.emit("step:completed", this.state.index);
+		this.dispatch({ type: "next" });
+		await this.afterTransition();
+	}
+	async back() {
+		if (!canGoBack(this.state, this.context())) return;
+		await this.leaveCurrent();
+		this.dispatch({ type: "back" });
+		await this.afterTransition();
+	}
+	async goTo(step) {
+		if (this.state.status !== "running") return;
+		const before = this.state;
+		const after = reduce(before, {
+			type: "go",
+			to: step
+		}, this.context());
+		if (after === before) return;
+		await this.leaveCurrent();
+		this.setState(after);
+		await this.afterTransition();
+	}
+	/** The user gave up on the tour (Skip button, close, Escape). */
+	async skip() {
+		if (!this.isActive()) return;
+		const ctx = this.stepContext();
+		await this.leaveCurrent();
+		this.dispatch({ type: "skip" });
+		await this.finish();
+		if (ctx) this.hooks.onSkip?.(ctx);
+	}
+	async abort(reason) {
+		if (!this.isActive()) return;
+		await this.leaveCurrent();
+		this.dispatch({
+			type: "abort",
+			reason
+		});
+		await this.finish();
+	}
+	/** Report a named application event. Advances a step waiting on it. */
+	notify(eventName) {
+		const advance = this.currentStep()?.advance;
+		if (typeof advance === "object" && advance.on === "event" && advance.name === eventName) this.next();
+	}
+	/** Tell the controller the route changed. Pauses or resumes route-bound steps. */
+	async routeChanged() {
+		const step = this.currentStep();
+		if (!step) return;
+		const onRoute = this.stepOnRoute(step);
+		if (this.state.status === "paused" && this.state.reason === "route" && onRoute) {
+			this.dispatch({ type: "resume" });
+			await this.showCurrent();
+		} else if (this.state.status === "running" && !onRoute) {
+			this.cancelPending();
+			this.dispatch({
+				type: "pause",
+				reason: "route"
+			});
+			await this.renderer.hide();
+		}
+	}
+	/** Stop everything and clear the screen without recording an outcome. */
+	async destroy() {
+		this.cancelPending();
+		this.listeners.clear();
+		await this.renderer.hide();
+		this.state = IDLE_STATE;
+	}
+	isActive() {
+		return this.state.status === "running" || this.state.status === "paused";
+	}
+	currentStep() {
+		return this.isActive() ? this.tour.steps[this.state.index] : void 0;
+	}
+	conditionEnv() {
+		const env = {
+			identity: this.identity,
+			elementExists: (t) => this.renderer.hasTarget(t),
+			custom: this.custom
+		};
+		const route = this.renderer.currentRoute?.();
+		if (route !== void 0) env.route = route;
+		if (this.tourStateOf) env.tourState = this.tourStateOf;
+		return env;
+	}
+	context() {
+		const env = this.conditionEnv();
+		return {
+			tour: this.tour,
+			isEligible: (i) => {
+				const step = this.tour.steps[i];
+				if (!step) return false;
+				return step.condition ? evaluateCondition(step.condition, env) : true;
+			}
+		};
+	}
+	stepOnRoute(step) {
+		const route = this.renderer.currentRoute?.();
+		if (!step.route || route === void 0) return true;
+		return matchRoute(step.route, route);
+	}
+	dispatch(action) {
+		this.setState(reduce(this.state, action, this.context()));
+	}
+	setState(next) {
+		if (next === this.state) return;
+		this.state = next;
+		for (const l of this.listeners) l(next);
+	}
+	stepContext() {
+		const step = this.currentStep();
+		if (!step) return void 0;
+		return {
+			tour: this.tour,
+			step,
+			index: this.state.index,
+			total: this.tour.steps.length
+		};
+	}
+	emit(type, stepIndex) {
+		const input = {
+			tour: this.tour,
+			identity: this.identity,
+			now: this.now
+		};
+		if (stepIndex !== void 0) input.stepIndex = stepIndex;
+		this.sink.emit(createEvent(type, input));
+	}
+	async persist(state) {
+		const record = {
+			tourId: this.tour.id,
+			version: tourVersion(this.tour),
+			state,
+			updatedAt: this.now()
+		};
+		const step = this.currentStep();
+		if (state === "in-progress" && step) record.stepId = step.id;
+		await this.store.set(record);
+	}
+	cancelPending() {
+		this.generation++;
+		this.pendingAbort?.abort();
+		this.pendingAbort = void 0;
+		if (this.pendingTimer !== void 0) clearTimeout(this.pendingTimer);
+		this.pendingTimer = void 0;
+	}
+	/** Run `beforeHide` for the step being left, if any. */
+	async leaveCurrent() {
+		const ctx = this.stepContext();
+		this.cancelPending();
+		if (ctx && this.state.status === "running") await this.hooks.steps?.[ctx.step.id]?.beforeHide?.(ctx);
+	}
+	async afterTransition() {
+		if (this.state.status === "running") return this.showCurrent();
+		if (isFinished(this.state)) return this.finish();
+	}
+	async finish() {
+		this.cancelPending();
+		await this.renderer.hide();
+		switch (this.state.status) {
+			case "completed":
+				this.emit("tour:completed");
+				await this.persist("completed");
+				this.hooks.onComplete?.(this.tour);
+				break;
+			case "skipped":
+				this.emit("tour:skipped");
+				await this.persist("skipped");
+				break;
+			case "aborted":
+				this.emit("tour:aborted");
+				await this.persist("skipped");
+				this.hooks.onAbort?.(this.tour, this.state.reason ?? "unknown");
+		}
+	}
+	async showCurrent() {
+		this.cancelPending();
+		const generation = this.generation;
+		const stale = () => generation !== this.generation;
+		const ctx = this.stepContext();
+		if (!ctx) return;
+		const { step } = ctx;
+		if (!this.stepOnRoute(step)) {
+			this.dispatch({
+				type: "pause",
+				reason: "route"
+			});
+			await this.renderer.hide();
+			return;
+		}
+		const proceed = await this.hooks.steps?.[step.id]?.beforeShow?.(ctx);
+		if (stale()) return;
+		if (proceed === false) {
+			this.emit("step:skipped", this.state.index);
+			this.dispatch({ type: "stepSkipped" });
+			return this.afterTransition();
+		}
+		if (step.target !== void 0 && !await this.ensureTarget(step, generation)) {
+			if (stale()) return;
+			this.emit("step:missing", this.state.index);
+			this.dispatch({ type: "stepMissing" });
+			return this.afterTransition();
+		}
+		if (stale()) return;
+		await this.renderer.show(this.renderContext(ctx));
+		if (stale()) return;
+		this.emit("step:shown", this.state.index);
+		this.hooks.onStepChange?.(ctx);
+		await this.persist("in-progress");
+		await this.hooks.steps?.[step.id]?.afterShow?.(ctx);
+		if (stale()) return;
+		this.armAdvance(step, generation);
+	}
+	/** Resolve `true` when the target is present, waiting if the step allows it. */
+	async ensureTarget(step, generation) {
+		const target = step.target;
+		if (target === void 0) return true;
+		if (this.renderer.hasTarget(target)) return true;
+		const waitMs = step.waitFor ?? (step.onMissing === "wait" ? this.defaultWaitMs : 0);
+		if (waitMs <= 0) return false;
+		const abort = new AbortController();
+		this.pendingAbort = abort;
+		const found = await this.renderer.waitForTarget(target, waitMs, abort.signal);
+		if (generation !== this.generation) return false;
+		this.pendingAbort = void 0;
+		return found;
+	}
+	/** Set up automatic advancement for `delay` and `element` steps. */
+	armAdvance(step, generation) {
+		const advance = step.advance;
+		if (typeof advance !== "object") return;
+		if (advance.on === "delay") this.pendingTimer = setTimeout(() => {
+			this.pendingTimer = void 0;
+			if (generation === this.generation) this.next();
+		}, advance.ms);
+		else if (advance.on === "element") {
+			const abort = new AbortController();
+			this.pendingAbort = abort;
+			this.renderer.waitForTarget(advance.target, Number.POSITIVE_INFINITY, abort.signal).then((found) => {
+				if (found && generation === this.generation) this.next();
+			});
+		}
+	}
+	renderContext(ctx) {
+		const engineCtx = this.context();
+		return {
+			tour: this.tour,
+			step: ctx.step,
+			index: ctx.index,
+			progress: progress(this.state, engineCtx),
+			isFirst: this.state.history.length === 0,
+			isLast: !hasNext(this.state, engineCtx),
+			canGoBack: canGoBack(this.state, engineCtx),
+			actions: {
+				next: () => void this.next(),
+				back: () => void this.back(),
+				skip: () => void this.skip(),
+				goTo: (s) => void this.goTo(s)
+			}
+		};
+	}
+};
+//#endregion
+export { ANONYMOUS_IDENTITY, IDLE_STATE, NOOP_SINK, ProgressStore, SCHEMA_VERSION, STORAGE_PREFIX, TourController, canGoBack, combineSinks, createEvent, createMemoryStorage, defineTour, evaluateAll, evaluateCondition, evaluateTrait, findEligible, hasNext, isActive, isFinished, matchRoute, progress, reduce, resolveStepIndex, shouldShow, storageKey, tourVersion };
+
+//# sourceMappingURL=index.js.map