@embedpdf/engine-core 3.0.0-next.14 → 3.0.0-next.15

package/dist/validation.cjs

@@ -0,0 +1,578 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_value = require("./value-BFS1R8ek.cjs");
+const require_resolveAnnotationDraft = require("./resolveAnnotationDraft-7Ke4nV7F.cjs");
+const require_format = require("./format-Bp3QFSH1.cjs");
+const require_pageRefs = require("./pageRefs-B3ur7Ckm.cjs");
+const require_schema = require("./schema-C-gU4vj7.cjs");
+//#region src/annotation/checkWrite.ts
+/**
+* A prepared create's data checked against its kind's schema. The caller
+* writes its own data, not the schema's output, so nothing is reshaped on its
+* way in.
+*/
+function assertAnnotationDraft(draft, options = {}) {
+	const declaration = require_schema.declarationOf(String(draft.subtype));
+	const linked = options.linked ?? [];
+	const checked = (declaration && linked.length > 0 ? declaration.fileSchemas.create.omit(Object.fromEntries(linked.map((name) => [name, true]))) : require_schema.FileAnnotationDraftSchema).safeParse(draft);
+	if (!checked.success) throw invalidWrite(checked.error, `${String(draft.subtype)} create`);
+}
+/**
+* A prepared update's data (`pdfPrepareAnnotationPatch`) checked against the
+* kind of `current`. A `readBack()` value still in it is a change, as
+* preparation drops one sent back as it reads, so one a write can't make is
+* refused; the rest is checked against the kind's update schema.
+*/
+function assertAnnotationPatch(current, prepared) {
+	if (current.subtype === "unsupported") return;
+	const values = prepared;
+	for (const [name, write] of Object.entries(require_schema.KIND_BY_SUBTYPE[current.subtype].readBackWrites)) {
+		const value = values[name];
+		if (value === void 0 || write?.safeParse(value).success) continue;
+		throw new require_format.EngineError(require_format.EngineErrorCode.InvalidArg, write ? `${current.subtype} update field '${name}': this value can be read but not written; send it back unchanged or replace it` : `${current.subtype} update field '${name}': the engine works this out; send it back unchanged or leave it out`, { details: { field: name } });
+	}
+	const parsed = require_schema.fileAnnotationPatchSchemaOf(current.subtype).safeParse(prepared);
+	if (!parsed.success) throw invalidWrite(parsed.error, `${current.subtype} update`);
+}
+/**
+* The draft the engine writes for `draft`, in the file's coordinates:
+* prepared (`pdfPrepareAnnotationDraft`), checked against its kind, and
+* every field that follows from it stated (`pdfDeriveAnnotationDraft`). A
+* viewer predicts the same without schema validation
+* (`pdfPredictAnnotationDraft`).
+*
+* Throws `InvalidArg` for a draft the engine refuses. Pure: it reads nothing
+* but its arguments.
+*/
+function pdfResolveAnnotationDraft(draft, options = {}) {
+	const prepared = require_resolveAnnotationDraft.pdfPrepareAnnotationDraft(draft);
+	assertAnnotationDraft(prepared, { linked: options.linked ?? [] });
+	return require_resolveAnnotationDraft.pdfDeriveAnnotationDraft(prepared, options);
+}
+/**
+* The patch the engine writes for `patch` on `current`, in the file's
+* coordinates: prepared (`pdfPrepareAnnotationPatch`), checked against its
+* kind (`assertAnnotationPatch`), and every field that follows from it
+* stated (`pdfDeriveAnnotationPatch`). A viewer predicts the same without
+* schema validation (`pdfPredictAnnotationPatch`).
+*
+* Throws `InvalidArg` for a patch the engine refuses. Pure: it reads nothing
+* but its arguments.
+*/
+function pdfResolveAnnotationPatch(current, patch, options = {}) {
+	const prepared = require_resolveAnnotationDraft.pdfPrepareAnnotationPatch(current, patch);
+	assertAnnotationPatch(current, prepared);
+	return require_resolveAnnotationDraft.pdfDeriveAnnotationPatch(current, prepared, options);
+}
+function invalidWrite(error, where) {
+	const issue = error.issues[0];
+	const field = issue.path.join(".");
+	return new require_format.EngineError(require_format.EngineErrorCode.InvalidArg, `${where}${field ? ` field '${field}'` : ""}: ${issue.message}`, { details: field ? { field } : {} });
+}
+//#endregion
+//#region src/transfer/planAnnotationImport.ts
+/**
+* What an import of `bundle` into the `target` pages creates, and what it
+* leaves out. Nothing here touches a document, so an import refuses before
+* its first write:
+*
+* - `InvalidArg` when an item's data isn't valid for its kind, or when a
+*   page an item is on or points at maps to no target page (naming them);
+* - `NotFound` when a page list maps to a page the target doesn't have.
+*
+* Unsupported items and unresolved relationships are left out in this order:
+*
+* 1. an item of an unsupported kind, and a form field's widget; a field
+*    marker leaves out only that field;
+* 2. an item whose `reply.to` or `parent` is no item of the bundle on the
+*    same target page (`parent-missing`);
+* 3. an item whose name is used on its target page, or by an earlier item
+*    going to the same page (`name-conflict`);
+* 4. then, until nothing changes, an item whose `reply.to` or `parent` was
+*    left out (`parent-dropped`), so a whole branch goes together.
+*
+* `nameTaken(page, nm)` answers for the target page as it is before the import.
+*/
+function planAnnotationImport(input) {
+	const { bundle, target, nameTaken } = input;
+	const items = bundle.items.map((item) => item.data);
+	const mapPage = require_resolveAnnotationDraft.bundlePageMapping({
+		bundlePages: bundle.pages,
+		pages: input.pages ?? "same",
+		target,
+		named: items.flatMap(pagesNamedBy)
+	});
+	const drops = /* @__PURE__ */ new Map();
+	const fieldDrops = /* @__PURE__ */ new Map();
+	const drafts = /* @__PURE__ */ new Map();
+	items.forEach((data, index) => {
+		if (data.subtype === "unsupported") {
+			drops.set(index, "unsupported-kind");
+			return;
+		}
+		if (data.subtype === "widget") {
+			drops.set(index, "widget");
+			return;
+		}
+		if (data.subtype === "popup" && data.parent === null) {
+			drops.set(index, "parent-missing");
+			return;
+		}
+		const unwritable = unwritableValuesOf(data);
+		if (unwritable === "item") {
+			drops.set(index, "unsupported-value");
+			return;
+		}
+		const markers = [...fieldMarkersOf(data), ...unwritable];
+		if (markers.length > 0) fieldDrops.set(index, markers);
+		drafts.set(index, draftOf$1(data, markers, mapPage, index));
+	});
+	const byKey = /* @__PURE__ */ new Map();
+	items.forEach((data, index) => {
+		const key = require_format.annotationKey(data.ref);
+		if (!byKey.has(key)) byKey.set(key, index);
+	});
+	const pageOf = (index) => require_format.encodePageKey(mapPage(items[index].ref.page));
+	const resolve = (ref, from) => {
+		const found = byKey.get(require_format.annotationKey(ref));
+		return found !== void 0 && pageOf(found) === pageOf(from) ? found : void 0;
+	};
+	const linksOf = (data) => [data.reply?.to, data.subtype === "popup" ? data.parent : null].filter((ref) => ref != null);
+	items.forEach((data, index) => {
+		if (drops.has(index)) return;
+		if (linksOf(data).some((ref) => resolve(ref, index) === void 0)) drops.set(index, "parent-missing");
+	});
+	const popupOf = /* @__PURE__ */ new Map();
+	items.forEach((data, index) => {
+		if (drops.has(index) || data.subtype !== "popup" || !data.parent) return;
+		const parent = resolve(data.parent, index);
+		if (popupOf.has(parent)) drops.set(index, "popup-taken");
+		else popupOf.set(parent, index);
+	});
+	const claimed = /* @__PURE__ */ new Set();
+	items.forEach((data, index) => {
+		if (drops.has(index) || !data.nm) return;
+		const page = mapPage(data.ref.page);
+		const claim = `${require_format.encodePageKey(page)}\u0000${data.nm}`;
+		if (claimed.has(claim) || nameTaken(page, data.nm)) drops.set(index, "name-conflict");
+		else claimed.add(claim);
+	});
+	for (let changed = true; changed;) {
+		changed = false;
+		items.forEach((data, index) => {
+			if (drops.has(index)) return;
+			if (linksOf(data).some((ref) => drops.has(resolve(ref, index)))) {
+				drops.set(index, "parent-dropped");
+				changed = true;
+			}
+		});
+	}
+	const planned = /* @__PURE__ */ new Map();
+	items.forEach((_data, index) => {
+		if (!drops.has(index)) planned.set(index, planned.size);
+	});
+	const creates = [...planned.keys()].map((index) => {
+		const data = items[index];
+		const replyTo = data.reply ? planned.get(resolve(data.reply.to, index)) : void 0;
+		const parent = data.subtype === "popup" && data.parent ? planned.get(resolve(data.parent, index)) : void 0;
+		return {
+			item: index,
+			page: mapPage(data.ref.page),
+			draft: drafts.get(index),
+			...replyTo !== void 0 ? { replyTo: {
+				planned: replyTo,
+				type: data.reply.type
+			} } : {},
+			...parent !== void 0 ? { parent } : {}
+		};
+	});
+	const dropped = [];
+	items.forEach((data, index) => {
+		const reason = drops.get(index);
+		if (reason) dropped.push({
+			ref: data.ref,
+			reason
+		});
+		else for (const drop of fieldDrops.get(index) ?? []) dropped.push({
+			ref: data.ref,
+			...drop
+		});
+	});
+	return {
+		creates,
+		dropped
+	};
+}
+/**
+* The pages an item is on or points at, apart from its links to other
+* annotations (`reply.to`, `parent`, `popup`), which resolve in the bundle.
+*/
+function pagesNamedBy(data) {
+	const { ref, reply: _reply, popup: _popup, ...rest } = data;
+	const fields = { ...rest };
+	if (data.subtype === "popup") delete fields.parent;
+	return [ref.page, ...require_pageRefs.pageRefsIn(fields)];
+}
+/** The fields of `data` that are markers for something the engine can't write. */
+function fieldMarkersOf(data) {
+	const markers = [];
+	const measure = data.measure;
+	if (measure?.subtype === "geospatial") markers.push({
+		field: "measure",
+		reason: "geospatial"
+	});
+	if (measure?.subtype === "unknown") markers.push({
+		field: "measure",
+		reason: "unknown-measure"
+	});
+	const target = data.subtype === "link" ? data.target : null;
+	const carriedTarget = !!target && isWritableLinkTarget(target);
+	if (target && !carriedTarget) markers.push({
+		field: "target",
+		reason: "unsupported-action"
+	});
+	const { actions } = data;
+	if (Object.entries(actions ?? {}).some(([trigger, tree]) => data.subtype !== "link" || trigger !== "activate" ? true : carriedTarget && !writtenAsIs(tree))) markers.push({
+		field: "actions",
+		reason: "unsupported-action"
+	});
+	return markers;
+}
+/**
+* The values `data` reads that a write can't make (a `readBack()` field's
+* read-only values), each left out; `'item'` when one is a field every
+* create needs. A link's target is reported by {@link fieldMarkersOf}.
+*/
+function unwritableValuesOf(data) {
+	const unwritable = [];
+	const declaration = require_schema.declarationOf(data.subtype);
+	for (const [name, spec] of Object.entries(declaration?.fields ?? {})) {
+		const { owner, readBack, required } = spec.traits;
+		if (owner !== "data" || !readBack || name === "target") continue;
+		const value = data[name];
+		if (value == null || spec.write.safeParse(value).success) continue;
+		if (required) return "item";
+		unwritable.push({
+			field: name,
+			reason: "unsupported-value"
+		});
+	}
+	return unwritable;
+}
+/** Whether a link's `/A` is what writing its target writes again. */
+function writtenAsIs(tree) {
+	const root = tree?.root;
+	if (!tree || tree.incomplete || !root || root.next.length > 0) return false;
+	return !(root.type === "uri" && root.isMap);
+}
+/** Whether a write can make a link's target; the others read as markers. */
+function isWritableLinkTarget(target) {
+	return target.kind === "named" ? STANDARD_NAMED_ACTIONS.has(target.name ?? "") : target.kind === "goto" || target.kind === "uri";
+}
+const STANDARD_NAMED_ACTIONS = /* @__PURE__ */ new Set([
+	"NextPage",
+	"PrevPage",
+	"FirstPage",
+	"LastPage"
+]);
+/** The create an item becomes, checked against its kind's create schema. */
+function draftOf$1(data, markers, mapPage, index) {
+	const fields = { ...data };
+	delete fields.reply;
+	const declared = require_schema.declarationOf(data.subtype)?.fields ?? {};
+	for (const { field } of markers) if (declared[field]?.traits.writeNullable) fields[field] = null;
+	else delete fields[field];
+	const checked = require_schema.AnnotationDraftSchema.safeParse(fields);
+	if (data.subtype === "popup") delete fields.parent;
+	if (!checked.success) {
+		const issue = checked.error.issues[0];
+		const path = issue.path.join(".");
+		throw new require_format.EngineError(require_format.EngineErrorCode.InvalidArg, `import: item ${index}${path ? ` field '${path}'` : ""}: ${issue.message}`, { details: {
+			item: index,
+			...path ? { field: path } : {}
+		} });
+	}
+	return require_pageRefs.mapPageRefs(fields, mapPage);
+}
+//#endregion
+//#region src/transfer/planFormImport.ts
+/**
+* What a form import writes and leaves out, decided before its first write: a design import's
+* fields checked against the create schema, a values import's values matched to the form's
+* fields. Built with zod, so it runs where the engine does, from
+* `@embedpdf/engine-core/validation`; the facts an import commits are in `formImport.ts`.
+*/
+/**
+* What a design import of `bundle` into the `target` pages creates, and what
+* it leaves out. Nothing here touches a document, so an import refuses
+* before its first write:
+*
+* - `InvalidArg` when a field's data isn't valid for its family, or when a
+*   page a widget is on or points at maps to no target page;
+* - `NotFound` when a page list maps to a page the target doesn't have.
+*
+* Left out, in bundle order: a field of an unknown family, a field whose
+* name is taken (`nameTaken`, for the document as it is before the
+* import), a widget whose field isn't in the bundle, and each action that
+* is a script, a submit or a link when `mayScript` is false
+* (`doc.forms.script`), or that a write can't make. Each field keeps every
+* widget it has. With `values`, each field gets the value the bundle holds.
+*/
+function planFormImport(input) {
+	const { bundle, mayScript } = input;
+	const mapPage = require_resolveAnnotationDraft.bundlePageMapping({
+		bundlePages: bundle.pages,
+		pages: input.pages ?? "same",
+		target: input.target,
+		named: bundle.widgets.flatMap((row) => require_pageRefs.pageRefsIn(row.data))
+	});
+	const rowByKey = new Map(bundle.widgets.map((row, index) => [require_format.annotationKey(row.data.ref), index]));
+	const owned = /* @__PURE__ */ new Set();
+	const dropped = [];
+	const claimed = /* @__PURE__ */ new Set();
+	const creates = [];
+	bundle.fields.forEach(({ data: field }, index) => {
+		const rows = field.widgets.flatMap((widget) => {
+			const row = widget.ref ? rowByKey.get(require_format.annotationKey(widget.ref)) : void 0;
+			return row === void 0 ? [] : [row];
+		});
+		for (const row of rows) owned.add(row);
+		if (field.family === "unknown") {
+			dropped.push({
+				ref: field.ref,
+				reason: "unsupported-family"
+			});
+			return;
+		}
+		if (claimed.has(field.name) || input.nameTaken(field.name)) {
+			dropped.push({
+				ref: field.ref,
+				reason: "name-conflict"
+			});
+			return;
+		}
+		claimed.add(field.name);
+		const draft = draftOf(field, fieldActionsOf(field, mayScript, dropped), rows.map((row) => placementOf(field, bundle.widgets[row].data, mapPage, mayScript, dropped)), index);
+		const value = input.values && holdsValue(field) ? require_value.fieldValueOf(field) : null;
+		creates.push({
+			field: index,
+			draft,
+			widgets: rows,
+			flags: rows.map((row) => flagsOf(bundle.widgets[row].data)),
+			...value ? { value } : {}
+		});
+	});
+	bundle.widgets.forEach((row, index) => {
+		if (!owned.has(index)) dropped.push({
+			ref: row.data.field,
+			widget: row.data.ref,
+			reason: "no-field"
+		});
+	});
+	return {
+		creates,
+		calculationOrder: bundle.calculationOrder.flatMap((ref) => {
+			const at = creates.findIndex((create) => require_format.encodeFieldRefKey(bundle.fields[create.field].data.ref) === require_format.encodeFieldRefKey(ref) && create.draft.actions?.calculate);
+			return at < 0 ? [] : [at];
+		}),
+		dropped
+	};
+}
+/**
+* What a values import of `bundle` writes into a form whose fields are
+* `target`: each field the bundle holds a value for gets it, matched by full
+* name. Left out, in bundle order: a field the document doesn't have
+* (`no-field`), one of another family (`wrong-family`), and one `refusal`
+* names a reason for: a value the field can't take, a field a signature
+* locked, a field the session may not fill in. So everything is decided
+* before the first write.
+*/
+function planFormValuesImport(input) {
+	const writes = [];
+	const dropped = [];
+	input.bundle.fields.forEach(({ data: field }, index) => {
+		const value = holdsValue(field) ? require_value.fieldValueOf(field) : null;
+		if (!value) return;
+		const target = input.target.find((candidate) => require_value.fieldMatches(candidate, {
+			kind: "fqn",
+			name: field.name
+		}));
+		if (!target) dropped.push({
+			ref: field.ref,
+			reason: "no-field"
+		});
+		else if (target.family !== field.family) dropped.push({
+			ref: field.ref,
+			reason: "wrong-family"
+		});
+		else {
+			const refused = input.refusal?.(target, value);
+			if (refused) dropped.push({
+				ref: field.ref,
+				reason: refused
+			});
+			else writes.push({
+				field: index,
+				target,
+				value
+			});
+		}
+	});
+	return {
+		writes,
+		dropped
+	};
+}
+/** Whether a field read holds a value a write can set. */
+function holdsValue(field) {
+	return field.valueEntry.kind === "scalar" || field.valueEntry.kind === "array";
+}
+/** A field's scripts as a create writes them; each left out is reported. */
+function fieldActionsOf(field, mayScript, dropped) {
+	const actions = {};
+	for (const [event, tree] of Object.entries(field.actions ?? {})) {
+		if (!tree) continue;
+		const script = require_value.fieldScriptOf(tree);
+		const member = `actions.${event}`;
+		if (!script) dropped.push({
+			ref: field.ref,
+			field: member,
+			reason: "unsupported-action"
+		});
+		else if (!mayScript) dropped.push({
+			ref: field.ref,
+			field: member,
+			reason: "script-not-allowed"
+		});
+		else actions[event] = script;
+	}
+	return actions;
+}
+/** A widget row as a create places it: on its mapped page, with its look and actions. */
+function placementOf(field, row, mapPage, mayScript, dropped) {
+	const actions = {};
+	for (const event of require_value.WIDGET_ACTION_EVENTS) {
+		const tree = row.actions?.[event];
+		if (!tree) continue;
+		const write = require_value.actionWriteOf(tree);
+		const drop = (reason) => dropped.push({
+			ref: field.ref,
+			widget: row.ref,
+			field: `actions.${event}`,
+			reason
+		});
+		if (!write) drop("unsupported-action");
+		else if (!mayScript && require_value.needsScriptRight(write)) drop("script-not-allowed");
+		else actions[event] = require_pageRefs.mapPageRefs(write, mapPage);
+	}
+	const toggle = field.family === "checkbox" || field.family === "radio" ? field.widgets.find((widget) => widget.ref && require_format.annotationKey(widget.ref) === require_format.annotationKey(row.ref)) : void 0;
+	const look = {
+		color: row.color,
+		interiorColor: row.interiorColor,
+		fontFamily: row.fontFamily,
+		fontSize: row.fontSize,
+		fontColor: row.fontColor,
+		caption: field.family === "pushbutton" ? row.caption : null
+	};
+	return {
+		page: mapPage(row.page),
+		rect: row.rect,
+		...row.rotation ? { rotation: row.rotation } : {},
+		strokeWidth: row.strokeWidth,
+		borderStyle: row.borderStyle,
+		textAlign: row.textAlign,
+		...Object.fromEntries(Object.entries(look).filter(([, value]) => value != null)),
+		...toggle && "exportValue" in toggle ? { exportValue: toggle.exportValue } : {},
+		...Object.keys(actions).length > 0 ? { actions } : {}
+	};
+}
+function flagsOf(row) {
+	return Object.fromEntries(require_value.WIDGET_FLAG_NAMES.map((name) => [name, row[name]]));
+}
+/** The create a field row becomes, checked against the create schema. */
+function draftOf(field, actions, widgets, index) {
+	const base = {
+		name: field.name,
+		readOnly: field.readOnly,
+		required: field.required,
+		noExport: field.noExport,
+		...field.alternateName !== null ? { alternateName: field.alternateName } : {},
+		...field.mappingName !== null ? { mappingName: field.mappingName } : {},
+		...field.groupId !== null ? { groupId: field.groupId } : {},
+		...Object.keys(actions).length > 0 ? { actions } : {},
+		widgets
+	};
+	const hasDefault = field.defaultValueEntry.kind !== "none";
+	const options = (list) => list.map(({ label, value }) => ({
+		label,
+		value
+	}));
+	let draft;
+	switch (field.family) {
+		case "text":
+			draft = {
+				...base,
+				family: "text",
+				...hasDefault ? { defaultValue: field.defaultValue } : {},
+				...field.maxLength !== null ? { maxLength: field.maxLength } : {},
+				multiline: field.multiline,
+				password: field.password,
+				comb: field.comb
+			};
+			break;
+		case "radio":
+			draft = {
+				...base,
+				family: "radio",
+				radiosInUnison: field.radiosInUnison,
+				noToggleToOff: field.noToggleToOff
+			};
+			break;
+		case "combobox":
+			draft = {
+				...base,
+				family: "combobox",
+				edit: field.edit,
+				options: options(field.options),
+				...hasDefault ? { defaultValue: field.defaultValue } : {}
+			};
+			break;
+		case "listbox":
+			draft = {
+				...base,
+				family: "listbox",
+				multiSelect: field.multiSelect,
+				options: options(field.options),
+				...hasDefault ? { defaultValue: field.defaultValue } : {}
+			};
+			break;
+		case "checkbox":
+		case "pushbutton":
+		case "signature":
+			draft = {
+				...base,
+				family: field.family
+			};
+			break;
+		default: throw new require_format.EngineError(require_format.EngineErrorCode.InvalidArg, `import: field ${index} has no family`);
+	}
+	const checked = require_schema.FormFieldDraftSchema.safeParse(draft);
+	if (!checked.success) {
+		const issue = checked.error.issues[0];
+		const path = issue.path.join(".");
+		throw new require_format.EngineError(require_format.EngineErrorCode.InvalidArg, `import: field ${index}${path ? ` member '${path}'` : ""}: ${issue.message}`, { details: {
+			item: index,
+			...path ? { field: path } : {}
+		} });
+	}
+	return draft;
+}
+//#endregion
+exports.assertAnnotationDraft = assertAnnotationDraft;
+exports.assertAnnotationPatch = assertAnnotationPatch;
+exports.pdfResolveAnnotationDraft = pdfResolveAnnotationDraft;
+exports.pdfResolveAnnotationPatch = pdfResolveAnnotationPatch;
+exports.planAnnotationImport = planAnnotationImport;
+exports.planFormImport = planFormImport;
+exports.planFormValuesImport = planFormValuesImport;
+
+//# sourceMappingURL=validation.cjs.map