@docentjs/dom 0.5.2 → 0.7.0

package/dist/index.cjs

@@ -79,6 +79,80 @@ function renderMedia(doc, media) {
 	return video;
 }
 //#endregion
+//#region src/dev.ts
+const checked = /* @__PURE__ */ new WeakSet();
+/**
+* Written exactly like this on purpose: bundlers replace
+* `process.env.NODE_ENV` literally, so a production build turns this into
+* `false`, and the check plus its import are dropped. Without a bundler
+* `process` is simply not defined, and the catch treats that as development.
+*/
+function isProduction() {
+	try {
+		return process.env.NODE_ENV === "production";
+	} catch {
+		return false;
+	}
+}
+/**
+* Check every tour the manager knows, as they load. Tours that never start
+* still get checked, which is where a broken condition usually hides.
+*/
+function warnAboutTours(docent) {
+	if (isProduction()) return;
+	const check = () => {
+		for (const tour of docent.getTours()) warnIfInvalid(tour);
+	};
+	docent.subscribe(check);
+	check();
+}
+/** Warn about anything wrong with this tour, once per tour, in development. */
+function warnIfInvalid(tour) {
+	if (!tour || isProduction() || checked.has(tour)) return;
+	checked.add(tour);
+	import("@docentjs/core/validate").then(({ formatIssues, validateTour }) => {
+		const issues = validateTour(tour);
+		if (issues.length === 0) return;
+		const label = issues.filter((issue) => issue.level === "error").length > 0 ? "error" : "warning";
+		console.warn(`[docent] Tour "${tour.id}" has ${issues.length} ${label}${issues.length === 1 ? "" : "s"}:\n${formatIssues(issues)}\nThis check runs in development only. See https://docentjs.dev/reference/schema/`);
+	}).catch(() => {});
+}
+//#endregion
+//#region src/looks.ts
+const BUILT_IN_LOOKS = {
+	/** The default: a dimmed page, a soft cutout, a small caret. */
+	spotlight: {},
+	/**
+	* A light touch for tips beside a feature: the page stays usable and
+	* clickable, with a glowing ring and a drawn curve instead of a scrim.
+	*/
+	hint: {
+		overlay: { style: "none" },
+		spotlight: {
+			ring: "glow",
+			padding: 6
+		},
+		arrow: "curve",
+		theme: { width: 300 }
+	},
+	/**
+	* For something to read rather than something to do: the page blurs away,
+	* nothing points anywhere, and the card is wider.
+	*/
+	announcement: {
+		overlay: {
+			style: "blur",
+			blur: 6
+		},
+		spotlight: {
+			ring: "none",
+			padding: 10
+		},
+		arrow: "none",
+		theme: { width: 420 }
+	}
+};
+//#endregion
 //#region src/occlusion.ts
 function isPinned(el) {
 	const view = el.ownerDocument.defaultView;
@@ -678,18 +752,82 @@ const THEME_VARS = {
 	connector: "connector",
 	ring: "ring"
 };
+/** Tokens that take a unit when given as a number. */
+const UNITS = {
+	radius: "px",
+	width: "px",
+	duration: "ms"
+};
+/** `12` becomes `12px`, `220` becomes `220ms`, strings are passed through. */
+function cssValue(key, value) {
+	return typeof value === "number" ? `${value}${UNITS[key] ?? ""}` : value;
+}
 /** Write theme tokens as inline custom properties on an element. Clears unset ones. */
 function applyTheme(el, theme) {
 	for (const key of Object.keys(THEME_VARS)) {
 		const value = theme?.[key];
 		const prop = `--docent-${THEME_VARS[key]}`;
 		if (value === void 0) el.style.removeProperty(prop);
-		else el.style.setProperty(prop, value);
+		else el.style.setProperty(prop, cssValue(key, value));
+	}
+	if (theme?.accent !== void 0 && theme.accentForeground === void 0) {
+		const light = isLightColor(el, cssValue("accent", theme.accent));
+		if (light !== void 0) el.style.setProperty("--docent-accent-fg", light ? "var(--docent-fg)" : "var(--docent-bg)");
+	}
+}
+/**
+* Is this colour light enough to need dark text on it? Resolves the colour
+* through the browser, so any CSS colour works. Undefined when it cannot tell.
+*/
+function isLightColor(el, color) {
+	const view = el.ownerDocument.defaultView;
+	if (!view) return void 0;
+	const previous = el.style.color;
+	el.style.color = color;
+	const computed = view.getComputedStyle(el).color;
+	el.style.color = previous;
+	const rgb = computed.match(/^(?:rgba?|color\(srgb)[( ]([^)]+)\)?/);
+	if (rgb?.[1]) {
+		const [r = 0, g = 0, b = 0] = rgb[1].split(/[\s,/]+/).slice(0, 3).map((n) => n.endsWith("%") ? Number.parseFloat(n) / 100 * 255 : Number.parseFloat(n));
+		const scale = computed.startsWith("color(") ? 255 : 1;
+		return (.2126 * r * scale + .7152 * g * scale + .0722 * b * scale) / 255 > .55;
 	}
+	const ok = computed.match(/^oklch\(\s*([\d.]+)(%?)/);
+	if (ok?.[1]) return Number.parseFloat(ok[1]) / (ok[2] === "%" ? 100 : 1) > .62;
 }
 function mergeThemes(...themes) {
 	return Object.assign({}, ...themes.filter(Boolean));
 }
+/**
+* Layer one theme over another when either may be a preset name. Used by the
+* framework adapters to merge a provider's defaults with a local theme.
+*/
+function mergeThemeSpecs(base, override) {
+	if (base === void 0) return override;
+	if (override === void 0) return base;
+	const first = typeof base === "string" ? { preset: base } : base;
+	const second = typeof override === "string" ? { preset: override } : override;
+	return {
+		...first,
+		...second
+	};
+}
+/** `{ theme }` when there is one, or nothing, for spreading into options. */
+function themeOption(theme) {
+	return theme === void 0 ? {} : { theme };
+}
+/** True when this theme cannot be resolved without the built-in presets. */
+function needsPresets(spec) {
+	return typeof spec === "string" || !!spec && typeof spec === "object" && "preset" in spec;
+}
+/** A preset name, tokens, or a preset with tokens on top, flattened to tokens. */
+function resolveTheme(spec, presets) {
+	if (spec === void 0) return void 0;
+	if (typeof spec === "string") return presets?.[spec];
+	const { preset, ...tokens } = spec;
+	if (preset === void 0) return tokens;
+	return mergeThemes(presets?.[preset], tokens);
+}
 //#endregion
 //#region src/renderer.ts
 const DEFAULT_LOOK = {
@@ -721,6 +859,11 @@ var DomRenderer = class {
 	connectorLoading;
 	/** Arrow, spotlight and overlay settings for the current step. */
 	look = DEFAULT_LOOK;
+	/** Preset tokens, once loaded. */
+	presets;
+	presetLoad;
+	/** Set while `appearance: 'auto'` is following the system setting. */
+	schemeQuery;
 	/** Until then the step's own transition runs; scroll updates may animate. */
 	settleUntil = 0;
 	/** Play the connector draw-in on its next render. */
@@ -744,6 +887,12 @@ var DomRenderer = class {
 		return `${pathname}${search}`;
 	}
 	show(ctx) {
+		if (this.presets === void 0 && this.usesPresets(ctx)) return this.loadPresets().then(() => {
+			this.showNow(ctx);
+		});
+		this.showNow(ctx);
+	}
+	showNow(ctx) {
 		const firstStep = !this.host;
 		const host = this.mount();
 		const from = this.popover?.style.transform || null;
@@ -751,7 +900,8 @@ var DomRenderer = class {
 		this.ctx = ctx;
 		this.target = ctx.step.target === void 0 ? null : resolveTarget(ctx.step.target, this.doc);
 		const template = this.template(ctx);
-		applyTheme(host, mergeThemes(this.options.theme, template?.theme, ctx.tour.options?.theme));
+		this.watchAppearance(ctx);
+		applyTheme(host, this.themeFor(ctx, template));
 		this.setTemplateCss(template?.css);
 		this.applyLook(host, this.resolveLook(ctx, template));
 		this.settleUntil = performance.now() + this.duration(host) * 1.5;
@@ -781,6 +931,8 @@ var DomRenderer = class {
 	}
 	hide() {
 		this.teardownStep();
+		this.schemeQuery?.removeEventListener("change", this.onSchemeChange);
+		this.schemeQuery = void 0;
 		if (this.host) {
 			this.host.remove();
 			this.host = void 0;
@@ -965,6 +1117,55 @@ var DomRenderer = class {
 		shadow.insertBefore(style, before);
 		shadow.insertBefore(this.connector.el, before);
 	}
+	/** Does anything here need the built-in presets? */
+	usesPresets(ctx) {
+		return this.appearance(ctx) !== "light" || needsPresets(this.options.theme) || needsPresets(ctx.tour.options?.theme) || needsPresets(this.template(ctx)?.theme);
+	}
+	loadPresets() {
+		this.presetLoad ??= Promise.resolve().then(() => require("./themes.cjs")).then((mod) => {
+			this.presets = {
+				light: mod.light,
+				dark: mod.dark,
+				minimal: mod.minimal,
+				contrast: mod.contrast
+			};
+		});
+		return this.presetLoad;
+	}
+	appearance(ctx) {
+		return ctx.tour.options?.appearance ?? this.options.appearance ?? "light";
+	}
+	/** The surface tokens for the current appearance: dark, or nothing for light. */
+	appearanceTheme(ctx) {
+		const appearance = this.appearance(ctx);
+		if (appearance === "dark") return this.presets?.dark;
+		if (appearance !== "auto") return void 0;
+		return this.prefersDark() ? this.presets?.dark : this.presets?.light;
+	}
+	prefersDark() {
+		return this.doc.defaultView?.matchMedia?.("(prefers-color-scheme: dark)").matches ?? false;
+	}
+	/** Renderer, then the appearance surface, then template, then tour. */
+	themeFor(ctx, template) {
+		const presets = this.presets;
+		return mergeThemes(resolveTheme(this.options.theme, presets), this.appearanceTheme(ctx), resolveTheme(template?.theme, presets), resolveTheme(ctx.tour.options?.theme, presets));
+	}
+	/** With `appearance: 'auto'`, follow the system setting while the tour runs. */
+	watchAppearance(ctx) {
+		const wanted = this.appearance(ctx) === "auto";
+		if (wanted === (this.schemeQuery !== void 0)) return;
+		if (!wanted) {
+			this.schemeQuery?.removeEventListener("change", this.onSchemeChange);
+			this.schemeQuery = void 0;
+			return;
+		}
+		this.schemeQuery = this.doc.defaultView?.matchMedia?.("(prefers-color-scheme: dark)");
+		this.schemeQuery?.addEventListener("change", this.onSchemeChange);
+	}
+	onSchemeChange = () => {
+		const ctx = this.ctx;
+		if (ctx && this.host) applyTheme(this.host, this.themeFor(ctx, this.template(ctx)));
+	};
 	resolveLook(ctx, template) {
 		const tour = ctx.tour.options ?? {};
 		const step = ctx.step;
@@ -1088,9 +1289,11 @@ var DomRenderer = class {
 		win.addEventListener("scrollend", finish, { once: true });
 		this.cleanups.push(stop);
 	}
+	/** The tour's template: one the app registered, or a built-in look. */
 	template(ctx) {
 		const name = ctx.tour.options?.template ?? this.options.template;
-		return name === void 0 ? void 0 : this.options.templates?.[name];
+		if (name === void 0) return void 0;
+		return this.options.templates?.[name] ?? BUILT_IN_LOOKS[name];
 	}
 	buildDefault(ctx, host, template) {
 		const slots = {
@@ -1365,6 +1568,7 @@ var DomTourController = class extends _docentjs_core.TourController {
 	followRoutes;
 	constructor(tour, options = {}) {
 		const { renderer: rendererOptions, followRoutes, ...rest } = options;
+		warnIfInvalid(tour);
 		const renderer = new DomRenderer(rendererOptions);
 		super({
 			...rest,
@@ -1470,7 +1674,7 @@ function createDocent(options = {}) {
 		...renderer,
 		document: doc
 	} : { ...renderer };
-	return new _docentjs_core.Docent({
+	const docent = new _docentjs_core.Docent({
 		...rest,
 		storage: rest.storage ?? createLocalStorage(),
 		environment: createDomEnvironment(doc),
@@ -1479,8 +1683,11 @@ function createDocent(options = {}) {
 			renderer: rendererOptions
 		})
 	});
+	warnAboutTours(docent);
+	return docent;
 }
 //#endregion
+exports.BUILT_IN_LOOKS = BUILT_IN_LOOKS;
 exports.CONNECTOR_STYLES = require_arrows.CONNECTOR_STYLES;
 exports.DEFAULT_LABELS = DEFAULT_LABELS;
 exports.DomRenderer = DomRenderer;
@@ -1512,6 +1719,7 @@ exports.holePath = holePath;
 exports.inflate = inflate;
 exports.isConnector = require_arrows.isConnector;
 exports.isSafeUrl = isSafeUrl;
+exports.mergeThemeSpecs = mergeThemeSpecs;
 exports.mergeThemes = mergeThemes;
 exports.parsePlacement = parsePlacement;
 exports.queryAllDeep = queryAllDeep;
@@ -1519,6 +1727,7 @@ exports.renderBody = renderBody;
 exports.renderMedia = renderMedia;
 exports.resolveSlots = resolveSlots;
 exports.resolveTarget = resolveTarget;
+exports.themeOption = themeOption;
 exports.toSpec = toSpec;
 exports.uncover = uncover;
 exports.waitForTarget = waitForTarget;