@docentjs/core 0.5.2 → 0.7.0

package/dist/validate.cjs

@@ -0,0 +1,861 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/schema/spec.ts
+const field = (spec, doc, extra = {}) => ({
+	spec,
+	...doc === void 0 ? {} : { doc },
+	...extra
+});
+const required = (spec, doc) => field(spec, doc, { required: true });
+const ref = (name) => ({
+	kind: "ref",
+	name
+});
+const str = { kind: "string" };
+const num = { kind: "number" };
+const bool = { kind: "boolean" };
+const enums = (...values) => ({
+	kind: "enum",
+	values
+});
+/** A size, time or opacity token: a CSS string, or a number in the token's unit. */
+const themeValue = {
+	kind: "union",
+	of: [str, num]
+};
+const ARROW_STYLES = [
+	"caret",
+	"none",
+	"line",
+	"dashed",
+	"dotted",
+	"curve",
+	"curve-dashed",
+	"squiggle",
+	"loop",
+	"elbow",
+	"sketch",
+	"pin"
+];
+const SPOTLIGHT_SHAPES = [
+	"rounded",
+	"rect",
+	"pill",
+	"circle"
+];
+const SPOTLIGHT_RINGS = [
+	"hairline",
+	"none",
+	"glow",
+	"pulse",
+	"dashed",
+	"solid"
+];
+const OVERLAY_STYLES = [
+	"dim",
+	"blur",
+	"vignette",
+	"none"
+];
+const THEME_NAMES = [
+	"light",
+	"dark",
+	"minimal",
+	"contrast"
+];
+const PLACEMENTS = [
+	"auto",
+	"top",
+	"right",
+	"bottom",
+	"left",
+	"top-start",
+	"top-end",
+	"right-start",
+	"right-end",
+	"bottom-start",
+	"bottom-end",
+	"left-start",
+	"left-end"
+];
+const TRAIT_OPERATORS = [
+	"eq",
+	"neq",
+	"gt",
+	"gte",
+	"lt",
+	"lte",
+	"in",
+	"nin",
+	"contains",
+	"exists",
+	"missing"
+];
+const TOUR_STATES = [
+	"not-started",
+	"in-progress",
+	"completed",
+	"skipped"
+];
+const target = {
+	kind: "union",
+	of: [{
+		kind: "string",
+		doc: "A CSS selector."
+	}, {
+		kind: "object",
+		fields: {
+			name: field(str, "Logical name, matching `data-docent=\"<name>\"`. The sturdiest anchor."),
+			selectors: field({
+				kind: "array",
+				items: str
+			}, "CSS fallbacks, tried in order."),
+			native: field(str, "Native identifier, when it differs from the name."),
+			within: field(str, "Selector of a container to search inside."),
+			nth: field(num, "Which match to use, counting from 0.")
+		}
+	}]
+};
+const advance = {
+	kind: "union",
+	by: "on",
+	of: [
+		{
+			kind: "enum",
+			values: ["button"],
+			doc: "The reader presses Next (the default)."
+		},
+		{
+			kind: "object",
+			doc: "The reader clicks the target.",
+			fields: {
+				on: required(enums("click")),
+				target: field(ref("target"))
+			}
+		},
+		{
+			kind: "object",
+			doc: "What the reader types matches a regular expression.",
+			fields: {
+				on: required(enums("input")),
+				target: field(ref("target")),
+				match: field(str, "Regular expression the value must match.")
+			}
+		},
+		{
+			kind: "object",
+			doc: "Your code reports a named event.",
+			fields: {
+				on: required(enums("event")),
+				name: required(str)
+			}
+		},
+		{
+			kind: "object",
+			doc: "An element appears on the page.",
+			fields: {
+				on: required(enums("element")),
+				target: required(ref("target"))
+			}
+		},
+		{
+			kind: "object",
+			doc: "After a delay.",
+			fields: {
+				on: required(enums("delay")),
+				ms: required({
+					kind: "number",
+					min: 0
+				})
+			}
+		}
+	]
+};
+const trigger = {
+	kind: "union",
+	by: "type",
+	of: [
+		{
+			kind: "object",
+			doc: "Only starts from code.",
+			fields: { type: required(enums("manual")) }
+		},
+		{
+			kind: "object",
+			doc: "When the page loads.",
+			fields: {
+				type: required(enums("auto")),
+				delay: field({
+					kind: "number",
+					min: 0
+				})
+			}
+		},
+		{
+			kind: "object",
+			doc: "On a matching path.",
+			fields: {
+				type: required(enums("route")),
+				pattern: required(str, "Path pattern, such as `/invoices/**`."),
+				delay: field({
+					kind: "number",
+					min: 0
+				})
+			}
+		},
+		{
+			kind: "object",
+			doc: "When an element appears.",
+			fields: {
+				type: required(enums("element")),
+				target: required(ref("target")),
+				delay: field({
+					kind: "number",
+					min: 0
+				})
+			}
+		},
+		{
+			kind: "object",
+			doc: "When your code reports an event.",
+			fields: {
+				type: required(enums("event")),
+				name: required(str)
+			}
+		}
+	]
+};
+const traitValue = {
+	kind: "union",
+	of: [
+		str,
+		num,
+		bool,
+		{
+			kind: "array",
+			items: str
+		}
+	]
+};
+const condition = {
+	kind: "union",
+	by: "type",
+	of: [
+		{
+			kind: "object",
+			doc: "Compare one of the user's traits.",
+			fields: {
+				type: required(enums("trait")),
+				key: required(str),
+				op: required({
+					kind: "enum",
+					values: TRAIT_OPERATORS
+				}),
+				value: field(traitValue)
+			}
+		},
+		{
+			kind: "object",
+			doc: "The current path matches.",
+			fields: {
+				type: required(enums("route")),
+				pattern: required(str)
+			}
+		},
+		{
+			kind: "object",
+			doc: "An element is, or is not, on the page.",
+			fields: {
+				type: required(enums("element")),
+				target: required(ref("target")),
+				exists: field(bool, "Set false to require the element to be absent.")
+			}
+		},
+		{
+			kind: "object",
+			doc: "Another tour's progress for this user.",
+			fields: {
+				type: required(enums("tour")),
+				id: required(str),
+				state: required({
+					kind: "enum",
+					values: TOUR_STATES
+				})
+			}
+		},
+		{
+			kind: "object",
+			doc: "Every condition holds.",
+			fields: {
+				type: required(enums("all")),
+				conditions: required({
+					kind: "array",
+					items: ref("condition")
+				})
+			}
+		},
+		{
+			kind: "object",
+			doc: "At least one condition holds.",
+			fields: {
+				type: required(enums("any")),
+				conditions: required({
+					kind: "array",
+					items: ref("condition")
+				})
+			}
+		},
+		{
+			kind: "object",
+			doc: "The inner condition does not hold.",
+			fields: {
+				type: required(enums("not")),
+				condition: required(ref("condition"))
+			}
+		},
+		{
+			kind: "object",
+			doc: "A predicate your app registered by name.",
+			fields: {
+				type: required(enums("custom")),
+				name: required(str),
+				args: field({
+					kind: "record",
+					values: traitValue
+				})
+			}
+		}
+	]
+};
+const theme = {
+	kind: "object",
+	doc: "Visual tokens. Each becomes a `--docent-*` custom property.",
+	fields: {
+		preset: field({
+			kind: "enum",
+			values: THEME_NAMES
+		}, "Start from a built-in preset, then override tokens below."),
+		background: field(str),
+		foreground: field(str),
+		muted: field(str, "Secondary text."),
+		accent: field(str, "The Next button. Its text colour is chosen for you unless you set one."),
+		accentForeground: field(str),
+		connector: field(str, "Colour of drawn arrows."),
+		ring: field(str, "Colour of the spotlight ring."),
+		radius: field(themeValue, "Popover corners. A number means px."),
+		shadow: field(str),
+		font: field(str, "Defaults to the page's own font."),
+		width: field(themeValue, "Popover width. A number means px."),
+		overlay: field(str, "Backdrop colour.", { deprecated: "Prefer `options.overlay.color`." }),
+		overlayOpacity: field(themeValue, "Backdrop opacity, 0 to 1.", { deprecated: "Prefer `options.overlay.opacity`." }),
+		duration: field(themeValue, "Transition time. A number means ms."),
+		zIndex: field(themeValue)
+	}
+};
+const themeSpec = {
+	kind: "union",
+	of: [{
+		kind: "enum",
+		values: THEME_NAMES,
+		doc: "A built-in preset by name."
+	}, theme]
+};
+const spotlight = {
+	kind: "object",
+	fields: {
+		padding: field(num, "Space around the target, in px."),
+		radius: field(num, "Corner radius of the cutout, in px."),
+		shape: field({
+			kind: "enum",
+			values: SPOTLIGHT_SHAPES
+		}),
+		ring: field({
+			kind: "enum",
+			values: SPOTLIGHT_RINGS
+		}),
+		animate: field(bool, "Animate the cutout as it moves between steps.")
+	}
+};
+const overlay = {
+	kind: "object",
+	fields: {
+		style: field({
+			kind: "enum",
+			values: OVERLAY_STYLES
+		}),
+		color: field(str),
+		opacity: field({
+			kind: "number",
+			min: 0,
+			max: 1
+		}),
+		blur: field({
+			kind: "number",
+			min: 0
+		}, "Blur radius for the `blur` style, in px.")
+	}
+};
+const scroll = {
+	kind: "object",
+	fields: {
+		enabled: field(bool),
+		behavior: field(enums("auto", "smooth")),
+		block: field(enums("start", "center", "end", "nearest"))
+	}
+};
+const labels = {
+	kind: "object",
+	fields: {
+		next: field(str),
+		back: field(str),
+		skip: field(str),
+		done: field(str),
+		close: field(str),
+		progress: field(str, "Supports `{current}` and `{total}`.")
+	}
+};
+const options = {
+	kind: "object",
+	fields: {
+		persist: field(bool, "Remember the current step so `resume()` can continue."),
+		frequency: field(enums("once", "until-completed", "always")),
+		showProgress: field(bool),
+		allowClose: field(bool, "Allow Escape and the close button."),
+		closeOnOverlayClick: field(bool),
+		keyboard: field(bool, "Arrow-key navigation."),
+		arrow: field({
+			kind: "enum",
+			values: ARROW_STYLES
+		}),
+		spotlight: field(spotlight),
+		overlay: field(overlay),
+		scroll: field(scroll),
+		labels: field(labels),
+		theme: field(themeSpec),
+		appearance: field(enums("light", "dark", "auto"), "`auto` follows the reader's system setting."),
+		template: field(str, "A built-in look ('spotlight', 'hint' or 'announcement') or a template the app registered.")
+	}
+};
+const step = {
+	kind: "object",
+	fields: {
+		id: required(str, "Unique within the tour. Keep it stable once shipped."),
+		target: field(ref("target"), "Leave out for a centred card."),
+		title: field(str),
+		body: field(str),
+		format: field(enums("text", "markdown"), "Markdown is a safe subset; HTML is never injected."),
+		media: field({
+			kind: "object",
+			fields: {
+				type: required(enums("image", "video")),
+				src: required(str),
+				alt: field(str)
+			}
+		}),
+		placement: field({
+			kind: "enum",
+			values: PLACEMENTS
+		}),
+		arrow: field({
+			kind: "enum",
+			values: ARROW_STYLES
+		}),
+		spotlight: field(spotlight),
+		overlay: field(overlay),
+		advance: field(advance, "How the step finishes."),
+		interaction: field(enums("block", "allow"), "Whether the target can be used during the step."),
+		condition: field(ref("condition"), "Skip this step when the condition is false."),
+		onMissing: field(enums("skip", "wait", "abort"), "When the target is not on the page."),
+		waitFor: field({
+			kind: "number",
+			min: 0
+		}, "How long to wait for the target, in ms."),
+		route: field(str, "Path pattern this step belongs to."),
+		buttons: field({
+			kind: "object",
+			fields: {
+				back: field(bool),
+				next: field(bool),
+				skip: field(bool),
+				close: field(bool)
+			}
+		}),
+		scroll: field(scroll),
+		meta: field({
+			kind: "record",
+			values: { kind: "any" }
+		})
+	}
+};
+const SPECS = {
+	tour: {
+		kind: "object",
+		doc: "A guided tour: what to show, to whom, and when.",
+		fields: {
+			$schema: field(str, "Optional link to this schema, for editors: https://docentjs.dev/schema/tour-v1.json"),
+			schemaVersion: field({
+				kind: "number",
+				min: 1,
+				max: 1
+			}, "`defineTour` sets this for you."),
+			id: required(str, "Stable identifier, used for progress and analytics."),
+			version: field(num, "Bump to show the tour again to people who saw an older one."),
+			name: field(str),
+			description: field(str),
+			steps: required({
+				kind: "array",
+				items: ref("step")
+			}),
+			trigger: field(ref("trigger"), "What starts the tour. Without one, only code can."),
+			conditions: field({
+				kind: "array",
+				items: ref("condition")
+			}, "All must hold."),
+			options: field(options),
+			meta: field({
+				kind: "record",
+				values: { kind: "any" }
+			})
+		}
+	},
+	step,
+	target,
+	advance,
+	trigger,
+	condition,
+	theme
+};
+//#endregion
+//#region src/schema/json-schema.ts
+const SCHEMA_ID = "https://docentjs.dev/schema/tour-v1.json";
+/** The whole schema document, ready to write to a file. */
+function tourJsonSchema() {
+	const definitions = {};
+	for (const name of Object.keys(SPECS)) {
+		if (name === "tour") continue;
+		definitions[name] = convert(SPECS[name]);
+	}
+	return {
+		$schema: "https://json-schema.org/draft/2020-12/schema",
+		$id: SCHEMA_ID,
+		title: "Docent tour",
+		description: "A guided product tour. See https://docentjs.dev/reference/schema/.",
+		...convert(SPECS.tour),
+		$defs: definitions
+	};
+}
+function convert(spec) {
+	const doc = spec.doc ? { description: spec.doc } : {};
+	switch (spec.kind) {
+		case "ref": return {
+			$ref: `#/$defs/${spec.name}`,
+			...doc
+		};
+		case "any": return { ...doc };
+		case "string": return {
+			type: "string",
+			...doc
+		};
+		case "boolean": return {
+			type: "boolean",
+			...doc
+		};
+		case "number": return {
+			type: "number",
+			...spec.min === void 0 ? {} : { minimum: spec.min },
+			...spec.max === void 0 ? {} : { maximum: spec.max },
+			...doc
+		};
+		case "enum": return {
+			enum: [...spec.values],
+			...doc
+		};
+		case "array": return {
+			type: "array",
+			items: convert(spec.items),
+			...doc
+		};
+		case "record": return {
+			type: "object",
+			additionalProperties: convert(spec.values),
+			...doc
+		};
+		case "union": return {
+			anyOf: spec.of.map(convert),
+			...doc
+		};
+		case "object": {
+			const properties = {};
+			const requiredKeys = [];
+			for (const [key, field] of Object.entries(spec.fields)) {
+				const description = field.deprecated ? `${field.doc ? `${field.doc} ` : ""}${field.deprecated}` : field.doc;
+				properties[key] = {
+					...convert(field.spec),
+					...description ? { description } : {},
+					...field.deprecated ? { deprecated: true } : {}
+				};
+				if (field.required) requiredKeys.push(key);
+			}
+			return {
+				type: "object",
+				properties,
+				...requiredKeys.length > 0 ? { required: requiredKeys } : {},
+				...doc
+			};
+		}
+	}
+}
+//#endregion
+//#region src/schema/validate.ts
+/**
+* Check a tour. An empty result means it matches the schema; it does not mean
+* the targets exist on the page, which the devtools Audit tab checks.
+*/
+function validateTour(tour, options = {}) {
+	const issues = [];
+	check(tour, {
+		kind: "ref",
+		name: "tour"
+	}, "", issues, options.unknownFields !== false);
+	if (isObject(tour) && Array.isArray(tour.steps)) {
+		const seen = /* @__PURE__ */ new Set();
+		tour.steps.forEach((step, i) => {
+			const id = isObject(step) ? step.id : void 0;
+			if (typeof id !== "string") return;
+			if (seen.has(id)) issues.push({
+				level: "error",
+				path: `steps[${i}].id`,
+				message: `Duplicate step id "${id}". Ids must be unique within a tour.`
+			});
+			seen.add(id);
+		});
+	}
+	return issues;
+}
+/** True when the tour matches the schema. */
+function isValidTour(tour) {
+	return validateTour(tour).every((issue) => issue.level !== "error");
+}
+/** One line per issue, for a console warning or a CI log. */
+function formatIssues(issues) {
+	return issues.map((issue) => {
+		const where = issue.path === "" ? "tour" : issue.path;
+		const hint = issue.suggestion ? ` Did you mean "${issue.suggestion}"?` : "";
+		return `${issue.level === "error" ? "✗" : "!"} ${where}: ${issue.message}${hint}`;
+	}).join("\n");
+}
+function check(value, spec, path, issues, unknownFields) {
+	switch (spec.kind) {
+		case "ref":
+			check(value, SPECS[spec.name], path, issues, unknownFields);
+			return;
+		case "any": return;
+		case "string":
+			if (typeof value !== "string") issues.push(wrongType(path, "a string", value));
+			return;
+		case "boolean":
+			if (typeof value !== "boolean") issues.push(wrongType(path, "true or false", value));
+			return;
+		case "number":
+			if (typeof value !== "number" || Number.isNaN(value)) {
+				issues.push(wrongType(path, "a number", value));
+				return;
+			}
+			if (spec.min !== void 0 && value < spec.min) issues.push({
+				level: "error",
+				path,
+				message: `${value} is below the minimum ${spec.min}.`
+			});
+			if (spec.max !== void 0 && value > spec.max) issues.push({
+				level: "error",
+				path,
+				message: `${value} is above the maximum ${spec.max}.`
+			});
+			return;
+		case "enum": {
+			if (typeof value === "string" && spec.values.includes(value)) return;
+			const near = typeof value === "string" ? nearest(value, spec.values) : void 0;
+			issues.push({
+				level: "error",
+				path,
+				message: `${show(value)} is not one of: ${spec.values.join(", ")}.`,
+				...near ? { suggestion: near } : {}
+			});
+			return;
+		}
+		case "array":
+			if (!Array.isArray(value)) {
+				issues.push(wrongType(path, "a list", value));
+				return;
+			}
+			value.forEach((item, i) => {
+				check(item, spec.items, `${path}[${i}]`, issues, unknownFields);
+			});
+			return;
+		case "record":
+			if (!isObject(value)) {
+				issues.push(wrongType(path, "an object", value));
+				return;
+			}
+			for (const [key, item] of Object.entries(value)) check(item, spec.values, join(path, key), issues, unknownFields);
+			return;
+		case "object":
+			if (!isObject(value)) {
+				issues.push(wrongType(path, "an object", value));
+				return;
+			}
+			checkFields(value, spec.fields, path, issues, unknownFields);
+			return;
+		case "union": {
+			const branch = pickBranch(value, spec, path, issues);
+			if (branch) check(value, branch, path, issues, unknownFields);
+			return;
+		}
+	}
+}
+function checkFields(value, fields, path, issues, unknownFields) {
+	for (const [key, field] of Object.entries(fields)) {
+		const item = value[key];
+		if (item === void 0) {
+			if (field.required) issues.push({
+				level: "error",
+				path: join(path, key),
+				message: "Required field is missing."
+			});
+			continue;
+		}
+		if (field.deprecated) issues.push({
+			level: "warning",
+			path: join(path, key),
+			message: field.deprecated
+		});
+		check(item, field.spec, join(path, key), issues, unknownFields);
+	}
+	if (!unknownFields) return;
+	const known = Object.keys(fields);
+	for (const key of Object.keys(value)) {
+		if (known.includes(key)) continue;
+		const near = nearest(key, known);
+		issues.push({
+			level: "warning",
+			path: join(path, key),
+			message: "Unknown field, which Docent will ignore.",
+			...near ? { suggestion: near } : {}
+		});
+	}
+}
+/** Choose the branch of a union, using its discriminator when it has one. */
+function pickBranch(value, spec, path, issues) {
+	const objects = spec.of.filter((s) => s.kind === "object");
+	const others = spec.of.filter((s) => s.kind !== "object");
+	if (!isObject(value)) {
+		if (others.some((s) => matches(value, s))) return void 0;
+		const names = spec.of.map(describe).join(", or ");
+		const near = typeof value === "string" ? nearest(value, others.flatMap((s) => s.kind === "enum" ? [...s.values] : [])) : void 0;
+		issues.push({
+			level: "error",
+			path,
+			message: `${show(value)} is not valid here. Expected ${names}.`,
+			...near ? { suggestion: near } : {}
+		});
+		return;
+	}
+	if (objects.length === 1) return objects[0];
+	const by = spec.by;
+	if (!by) return objects.find((s) => matches(value, s)) ?? objects[0];
+	const tag = value[by];
+	const tags = objects.flatMap((s) => {
+		const f = s.kind === "object" ? s.fields[by]?.spec : void 0;
+		return f?.kind === "enum" ? [...f.values] : [];
+	});
+	const found = objects.find((s) => {
+		const f = s.kind === "object" ? s.fields[by]?.spec : void 0;
+		return f?.kind === "enum" && typeof tag === "string" && f.values.includes(tag);
+	});
+	if (found) return found;
+	const near = typeof tag === "string" ? nearest(tag, tags) : void 0;
+	issues.push({
+		level: "error",
+		path: join(path, by),
+		message: tag === void 0 ? `Required field is missing. Expected one of: ${tags.join(", ")}.` : `${show(tag)} is not one of: ${tags.join(", ")}.`,
+		...near ? { suggestion: near } : {}
+	});
+}
+/** A quick shape test, without collecting issues. */
+function matches(value, spec) {
+	const issues = [];
+	check(value, spec, "", issues, false);
+	return issues.every((i) => i.level !== "error");
+}
+function describe(spec) {
+	switch (spec.kind) {
+		case "string": return "a string";
+		case "number": return "a number";
+		case "boolean": return "true or false";
+		case "enum": return `one of: ${spec.values.join(", ")}`;
+		case "array": return "a list";
+		case "object":
+		case "record": return "an object";
+		default: return "a value";
+	}
+}
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const join = (path, key) => path === "" ? key : `${path}.${key}`;
+function wrongType(path, expected, value) {
+	return {
+		level: "error",
+		path,
+		message: `Expected ${expected}, found ${show(value)}.`
+	};
+}
+function show(value) {
+	if (typeof value === "string") return `"${value}"`;
+	if (value === void 0) return "nothing";
+	if (Array.isArray(value)) return "a list";
+	if (typeof value === "object" && value !== null) return "an object";
+	return String(value);
+}
+/** The closest option, when one is close enough to be worth suggesting. */
+function nearest(value, options) {
+	let best;
+	let bestDistance = Number.POSITIVE_INFINITY;
+	for (const option of options) {
+		const d = distance(value.toLowerCase(), option.toLowerCase());
+		if (d < bestDistance) {
+			bestDistance = d;
+			best = option;
+		}
+	}
+	const allowed = Math.max(1, Math.round(value.length / 3));
+	return best !== void 0 && bestDistance <= allowed ? best : void 0;
+}
+/** Levenshtein distance, two rows at a time. */
+function distance(a, b) {
+	if (a === b) return 0;
+	let previous = Array.from({ length: b.length + 1 }, (_, i) => i);
+	for (let i = 1; i <= a.length; i++) {
+		const current = [i];
+		for (let j = 1; j <= b.length; j++) {
+			const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+			current[j] = Math.min((current[j - 1] ?? 0) + 1, (previous[j] ?? 0) + 1, (previous[j - 1] ?? 0) + cost);
+		}
+		previous = current;
+	}
+	return previous[b.length] ?? 0;
+}
+//#endregion
+exports.ARROW_STYLES = ARROW_STYLES;
+exports.OVERLAY_STYLES = OVERLAY_STYLES;
+exports.PLACEMENTS = PLACEMENTS;
+exports.SCHEMA_ID = SCHEMA_ID;
+exports.SPOTLIGHT_RINGS = SPOTLIGHT_RINGS;
+exports.SPOTLIGHT_SHAPES = SPOTLIGHT_SHAPES;
+exports.THEME_NAMES = THEME_NAMES;
+exports.TOUR_STATES = TOUR_STATES;
+exports.TRAIT_OPERATORS = TRAIT_OPERATORS;
+exports.formatIssues = formatIssues;
+exports.isValidTour = isValidTour;
+exports.nearest = nearest;
+exports.tourJsonSchema = tourJsonSchema;
+exports.validateTour = validateTour;
+
+//# sourceMappingURL=validate.cjs.map