@docentjs/dom 0.5.2 → 0.6.0

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { Alignment, ArrowStyle, ControllerOptions, Docent, DocentEnvironment, DocentOptions, Labels, Media, OverlayOptions, Placement, RenderContext, Renderer, Side, SpotlightOptions, SpotlightShape, StorageAdapter, Target, TargetSpec, Theme, Tour, TourController, defineTour } from "@docentjs/core";
+import { Alignment, Appearance, ArrowStyle, ControllerOptions, Docent, DocentEnvironment, DocentOptions, Labels, Media, OverlayOptions, Placement, RenderContext, Renderer, Side, SpotlightOptions, SpotlightShape, StorageAdapter, Target, TargetSpec, Theme, ThemeSpec, Tour, TourController, defineTour } from "@docentjs/core";
 //#region src/arrows.d.ts
 export declare const CONNECTOR_STYLES: readonly ["line", "dashed", "dotted", "curve", "curve-dashed", "squiggle", "loop", "elbow", "sketch", "pin"];
 type ConnectorStyle = (typeof CONNECTOR_STYLES)[number];
@@ -17,6 +17,15 @@ export declare const THEME_VARS: Record<keyof Theme, string>;
 /** Write theme tokens as inline custom properties on an element. Clears unset ones. */
 export declare function applyTheme(el: HTMLElement, theme: Theme | undefined): void;
 export declare function mergeThemes(...themes: Array<Theme | undefined>): Theme;
+/**
+ * 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.
+ */
+export declare function mergeThemeSpecs(base: ThemeSpec | undefined, override: ThemeSpec | undefined): ThemeSpec | undefined;
+/** `{ theme }` when there is one, or nothing, for spreading into options. */
+export declare function themeOption(theme: ThemeSpec | undefined): {
+  theme?: ThemeSpec;
+};
 /**
  * Regions of the built-in popover that can be replaced. Custom content is
  * projected through native Shadow DOM slots, so it lives in the page's DOM
@@ -39,7 +48,7 @@ type PopoverSlots = Partial<Record<SlotName, SlotRenderer>>;
  * that defines the template stays in the app.
  */
 interface PopoverTemplate {
-  theme?: Theme;
+  theme?: ThemeSpec;
   slots?: PopoverSlots;
   /** Arrow style for tours using this template. */
   arrow?: ArrowStyle;
@@ -72,8 +81,10 @@ interface DomRendererOptions {
   arrow?: ArrowStyle;
   /** Overlay defaults when a tour sets none: style, color, opacity, blur. */
   overlay?: OverlayOptions;
-  /** Base theme tokens. Tours and templates layer on top. */
-  theme?: Theme;
+  /** Base theme: a preset name, tokens, or both. Tours and templates layer on top. */
+  theme?: ThemeSpec;
+  /** Light (default), dark, or follow the reader's system setting. */
+  appearance?: Appearance;
   /** Replace regions of the built-in popover. */
   slots?: PopoverSlots;
   /** Named templates that tours select with `options.template`. */
@@ -115,6 +126,11 @@ export declare class DomRenderer implements Renderer {
   private connectorLoading;
   /** Arrow, spotlight and overlay settings for the current step. */
   private look;
+  /** Preset tokens, once loaded. */
+  private presets;
+  private presetLoad;
+  /** Set while `appearance: 'auto'` is following the system setting. */
+  private schemeQuery;
   /** Until then the step's own transition runs; scroll updates may animate. */
   private settleUntil;
   /** Play the connector draw-in on its next render. */
@@ -124,7 +140,8 @@ export declare class DomRenderer implements Renderer {
   hasTarget(target: Target): boolean;
   waitForTarget(target: Target, timeoutMs: number, signal: AbortSignal): Promise<boolean>;
   currentRoute(): string;
-  show(ctx: RenderContext): void;
+  show(ctx: RenderContext): void | Promise<void>;
+  private showNow;
   hide(): void;
   /**
    * Re-measure and re-position everything. Safe to call often. `tracking`
@@ -138,6 +155,18 @@ export declare class DomRenderer implements Renderer {
   private loadConnector;
   /** Add the connector layer and its styles, beneath any popover. */
   private attachConnector;
+  /** Does anything here need the built-in presets? */
+  private usesPresets;
+  private loadPresets;
+  private appearance;
+  /** The surface tokens for the current appearance: dark, or nothing for light. */
+  private appearanceTheme;
+  private prefersDark;
+  /** Renderer, then the appearance surface, then template, then tour. */
+  private themeFor;
+  /** With `appearance: 'auto'`, follow the system setting while the tour runs. */
+  private watchAppearance;
+  private onSchemeChange;
   private resolveLook;
   /** Expose the look to the stylesheet as host attributes and variables. */
   private applyLook;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Alignment, ArrowStyle, ControllerOptions, Docent, DocentEnvironment, DocentOptions, Labels, Media, OverlayOptions, Placement, RenderContext, Renderer, Side, SpotlightOptions, SpotlightShape, StorageAdapter, Target, TargetSpec, Theme, Tour, TourController, defineTour } from "@docentjs/core";
+import { Alignment, Appearance, ArrowStyle, ControllerOptions, Docent, DocentEnvironment, DocentOptions, Labels, Media, OverlayOptions, Placement, RenderContext, Renderer, Side, SpotlightOptions, SpotlightShape, StorageAdapter, Target, TargetSpec, Theme, ThemeSpec, Tour, TourController, defineTour } from "@docentjs/core";
 //#region src/arrows.d.ts
 export declare const CONNECTOR_STYLES: readonly ["line", "dashed", "dotted", "curve", "curve-dashed", "squiggle", "loop", "elbow", "sketch", "pin"];
 type ConnectorStyle = (typeof CONNECTOR_STYLES)[number];
@@ -17,6 +17,15 @@ export declare const THEME_VARS: Record<keyof Theme, string>;
 /** Write theme tokens as inline custom properties on an element. Clears unset ones. */
 export declare function applyTheme(el: HTMLElement, theme: Theme | undefined): void;
 export declare function mergeThemes(...themes: Array<Theme | undefined>): Theme;
+/**
+ * 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.
+ */
+export declare function mergeThemeSpecs(base: ThemeSpec | undefined, override: ThemeSpec | undefined): ThemeSpec | undefined;
+/** `{ theme }` when there is one, or nothing, for spreading into options. */
+export declare function themeOption(theme: ThemeSpec | undefined): {
+  theme?: ThemeSpec;
+};
 /**
  * Regions of the built-in popover that can be replaced. Custom content is
  * projected through native Shadow DOM slots, so it lives in the page's DOM
@@ -39,7 +48,7 @@ type PopoverSlots = Partial<Record<SlotName, SlotRenderer>>;
  * that defines the template stays in the app.
  */
 interface PopoverTemplate {
-  theme?: Theme;
+  theme?: ThemeSpec;
   slots?: PopoverSlots;
   /** Arrow style for tours using this template. */
   arrow?: ArrowStyle;
@@ -72,8 +81,10 @@ interface DomRendererOptions {
   arrow?: ArrowStyle;
   /** Overlay defaults when a tour sets none: style, color, opacity, blur. */
   overlay?: OverlayOptions;
-  /** Base theme tokens. Tours and templates layer on top. */
-  theme?: Theme;
+  /** Base theme: a preset name, tokens, or both. Tours and templates layer on top. */
+  theme?: ThemeSpec;
+  /** Light (default), dark, or follow the reader's system setting. */
+  appearance?: Appearance;
   /** Replace regions of the built-in popover. */
   slots?: PopoverSlots;
   /** Named templates that tours select with `options.template`. */
@@ -115,6 +126,11 @@ export declare class DomRenderer implements Renderer {
   private connectorLoading;
   /** Arrow, spotlight and overlay settings for the current step. */
   private look;
+  /** Preset tokens, once loaded. */
+  private presets;
+  private presetLoad;
+  /** Set while `appearance: 'auto'` is following the system setting. */
+  private schemeQuery;
   /** Until then the step's own transition runs; scroll updates may animate. */
   private settleUntil;
   /** Play the connector draw-in on its next render. */
@@ -124,7 +140,8 @@ export declare class DomRenderer implements Renderer {
   hasTarget(target: Target): boolean;
   waitForTarget(target: Target, timeoutMs: number, signal: AbortSignal): Promise<boolean>;
   currentRoute(): string;
-  show(ctx: RenderContext): void;
+  show(ctx: RenderContext): void | Promise<void>;
+  private showNow;
   hide(): void;
   /**
    * Re-measure and re-position everything. Safe to call often. `tracking`
@@ -138,6 +155,18 @@ export declare class DomRenderer implements Renderer {
   private loadConnector;
   /** Add the connector layer and its styles, beneath any popover. */
   private attachConnector;
+  /** Does anything here need the built-in presets? */
+  private usesPresets;
+  private loadPresets;
+  private appearance;
+  /** The surface tokens for the current appearance: dark, or nothing for light. */
+  private appearanceTheme;
+  private prefersDark;
+  /** Renderer, then the appearance surface, then template, then tour. */
+  private themeFor;
+  /** With `appearance: 'auto'`, follow the system setting while the tour runs. */
+  private watchAppearance;
+  private onSchemeChange;
   private resolveLook;
   /** Expose the look to the stylesheet as host attributes and variables. */
   private applyLook;

package/dist/index.js

@@ -78,6 +78,45 @@ 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/occlusion.ts
 function isPinned(el) {
 	const view = el.ownerDocument.defaultView;
@@ -677,18 +716,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 = {
@@ -720,6 +823,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. */
@@ -743,6 +851,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;
@@ -750,7 +864,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;
@@ -780,6 +895,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;
@@ -964,6 +1081,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 ??= import("./themes.js").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;
@@ -1364,6 +1530,7 @@ var DomTourController = class extends TourController {
 	followRoutes;
 	constructor(tour, options = {}) {
 		const { renderer: rendererOptions, followRoutes, ...rest } = options;
+		warnIfInvalid(tour);
 		const renderer = new DomRenderer(rendererOptions);
 		super({
 			...rest,
@@ -1469,7 +1636,7 @@ function createDocent(options = {}) {
 		...renderer,
 		document: doc
 	} : { ...renderer };
-	return new Docent({
+	const docent = new Docent({
 		...rest,
 		storage: rest.storage ?? createLocalStorage(),
 		environment: createDomEnvironment(doc),
@@ -1478,8 +1645,10 @@ function createDocent(options = {}) {
 			renderer: rendererOptions
 		})
 	});
+	warnAboutTours(docent);
+	return docent;
 }
 //#endregion
-export { CONNECTOR_STYLES, DEFAULT_LABELS, DomRenderer, DomTourController, NAME_ATTRIBUTE, Overlay, THEME_VARS, applyTheme, arrowGap, availableSpace, buildHeadlessShell, buildPopover, candidateSelectors, centerPosition, computePosition, createDocent, createDomEnvironment, createLocalStorage, createTour, defineTour, findOccluder, formatProgress, holePath, inflate, isConnector, isSafeUrl, mergeThemes, parsePlacement, queryAllDeep, renderBody, renderMedia, resolveSlots, resolveTarget, toSpec, uncover, waitForTarget };
+export { CONNECTOR_STYLES, DEFAULT_LABELS, DomRenderer, DomTourController, NAME_ATTRIBUTE, Overlay, THEME_VARS, applyTheme, arrowGap, availableSpace, buildHeadlessShell, buildPopover, candidateSelectors, centerPosition, computePosition, createDocent, createDomEnvironment, createLocalStorage, createTour, defineTour, findOccluder, formatProgress, holePath, inflate, isConnector, isSafeUrl, mergeThemeSpecs, mergeThemes, parsePlacement, queryAllDeep, renderBody, renderMedia, resolveSlots, resolveTarget, themeOption, toSpec, uncover, waitForTarget };
 
 //# sourceMappingURL=index.js.map