@embeddables/forms 0.0.1

package/dist/index.js

@@ -0,0 +1,989 @@
+import { hc } from "hono/client";
+import { isValidPublishableKey } from "@embeddables/core";
+//#region src/errors.ts
+/**
+* Typed error hierarchy. Every failure this SDK raises on its own behalf is an
+* instance of one of these, so consumers branch on the type
+* (`if (e instanceof SchemaError) …`) instead of string-matching messages.
+* Catch `FormsError` to handle them all.
+*
+* An error thrown by a consumer's own custom validator is never wrapped in one
+* of these — it propagates with its original type and stack.
+*/
+/** Base class for every error the SDK throws. */
+var FormsError = class extends Error {
+	constructor(message, options) {
+		super(message, options);
+		this.name = "FormsError";
+	}
+};
+/** The schema is malformed. */
+var SchemaError = class extends FormsError {
+	constructor(message, options) {
+		super(message, options);
+		this.name = "SchemaError";
+	}
+};
+/** A custom validator returned a thenable, or a shape that is not a message. */
+var ValidatorError = class extends FormsError {
+	constructor(message, options) {
+		super(message, options);
+		this.name = "ValidatorError";
+	}
+};
+//#endregion
+//#region src/analytics.ts
+/** The ingest bound on a `data:updated` entry's `value`. */
+const MAX_VALUE_LENGTH = 1024;
+/** The ingest bound on a `data:updated` entry's `label`. */
+const MAX_LABEL_LENGTH = 256;
+/** Maps a form field's declared type to the analytics `field:updated` class. */
+function mapFieldUpdatedType(type) {
+	return type;
+}
+/**
+* Stringifies values for `data:updated` entries. `field:updated` carries the
+* raw `field_value`; only the batch event caps and stringifies for ingest.
+*/
+function formatFieldValue({ value }) {
+	return (typeof value === "string" ? value : JSON.stringify(value)).slice(0, MAX_VALUE_LENGTH);
+}
+/** One event carrying every key in one `.set()` call. */
+function buildDataUpdatedEvent({ fields, patch }) {
+	const byKey = new Map(fields.map((field) => [field.key, field]));
+	return {
+		event_name: "data:updated",
+		data: Object.fromEntries(Object.entries(patch).map(([key, value]) => {
+			const field = byKey.get(key);
+			return [key, {
+				value: formatFieldValue({
+					value,
+					field
+				}),
+				label: (field?.label ?? key).slice(0, MAX_LABEL_LENGTH)
+			}];
+		}))
+	};
+}
+/** One `field:updated` per changed key, emitted alongside `data:updated`. */
+function buildFieldUpdatedEvents({ fields, patch }) {
+	const byKey = new Map(fields.map((field) => [field.key, field]));
+	return Object.entries(patch).map(([key, value]) => {
+		const field = byKey.get(key);
+		const event = {
+			event_name: "field:updated",
+			field_key: key,
+			field_type: mapFieldUpdatedType(field?.type ?? "text"),
+			field_value: value
+		};
+		if (field?.registryFieldId !== void 0) event.registry_field_id = field.registryFieldId;
+		if (field?.protocolFieldId !== void 0) event.protocol_field_id = field.protocolFieldId;
+		return event;
+	});
+}
+/**
+* Returns null when persistence cannot be configured (missing publishable key
+* or fetch). The SDK keeps the no-op default in that case.
+*/
+function resolvePersistenceConfig(config) {
+	const core = config.core;
+	const publishableKey = config.publishableKey ?? core.getPublishableKey();
+	if (!publishableKey || !isValidPublishableKey(publishableKey)) return null;
+	const projectId = core.getProjectId();
+	const appUserId = core.getAppUserId();
+	if (!projectId || !appUserId) return null;
+	const fetchImpl = config.fetch ?? (typeof globalThis.fetch === "function" ? globalThis.fetch.bind(globalThis) : void 0);
+	if (!fetchImpl) return null;
+	return {
+		core,
+		projectId,
+		appUserId,
+		publishableKey,
+		baseUrl: config.baseUrl ?? "https://backend-worker.heysavvy.workers.dev",
+		fetch: fetchImpl,
+		timeoutMs: config.timeoutMs ?? 1e4
+	};
+}
+//#endregion
+//#region src/persistence.ts
+/**
+* The default: does nothing, never throws, and recovers nothing. With this in
+* place a form is pure local state, exactly as before the port existed.
+*/
+function createNoopPersistence() {
+	return {
+		savePartial: () => void 0,
+		saveFields: () => void 0,
+		saveSubmission: () => void 0,
+		recoverRegistryFields: () => ({})
+	};
+}
+//#endregion
+//#region src/persistence-client.ts
+const PUBLISHABLE_KEY_HEADER = "x-publishable-key";
+const hcWithType = (...args) => hc(...args);
+function withTimeout(fetchImpl, timeoutMs) {
+	return async (input, init) => {
+		const controller = new AbortController();
+		const timer = setTimeout(() => controller.abort(), timeoutMs);
+		const path = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+		try {
+			return await fetchImpl(input, {
+				...init,
+				signal: controller.signal
+			});
+		} catch (error) {
+			if (error instanceof Error && error.name === "AbortError") throw new Error(`Request to ${path} timed out after ${timeoutMs}ms`, { cause: error });
+			throw new Error(`Request to ${path} failed to reach the API`, { cause: error });
+		} finally {
+			clearTimeout(timer);
+		}
+	};
+}
+async function rpcCall(fn) {
+	const res = await fn();
+	if (!res.ok) {
+		const problem = await res.json().catch(() => null);
+		const message = problem?.detail ?? problem?.title ?? `forms persistence failed: ${res.status}`;
+		throw new Error(message);
+	}
+	return res.json();
+}
+function createApiPersistence(config) {
+	const root = config.baseUrl.replace(/\/+$/, "");
+	const rpc = hcWithType(`${root}/forms`, {
+		fetch: withTimeout(config.fetch, config.timeoutMs),
+		headers: { [PUBLISHABLE_KEY_HEADER]: config.publishableKey }
+	});
+	return {
+		savePartial({ formKey, values }) {
+			return rpcCall(() => rpc.v1.public.sessions.$post({ json: {
+				project_id: config.projectId,
+				app_user_id: config.appUserId,
+				form_id: formKey,
+				data: values
+			} })).then(() => void 0);
+		},
+		saveFields: () => void 0,
+		saveSubmission({ formKey, values }) {
+			return rpcCall(() => rpc.v1.public.submissions.$post({ json: {
+				project_id: config.projectId,
+				app_user_id: config.appUserId,
+				form_id: formKey,
+				values
+			} })).then(() => void 0);
+		},
+		recoverRegistryFields: () => ({})
+	};
+}
+function resolveDefaultPersistence(config) {
+	const resolved = resolvePersistenceConfig(config);
+	if (!resolved) return createNoopPersistence();
+	return createApiPersistence(resolved);
+}
+//#endregion
+//#region src/resolve.ts
+const FIELD_TYPES = [
+	"text",
+	"email",
+	"number",
+	"boolean",
+	"select",
+	"multiselect",
+	"json"
+];
+const VALIDATION_RULES = [
+	"required",
+	"minLength",
+	"maxLength",
+	"min",
+	"max",
+	"pattern",
+	"patternFlags",
+	"oneOf",
+	"custom"
+];
+const NUMERIC_RULES = [
+	"minLength",
+	"maxLength",
+	"min",
+	"max"
+];
+/** The ingest `z.string().max(128)` bound on a `data:updated` key. */
+const MAX_FIELD_KEY_LENGTH = 128;
+/** The ingest `z.string().max(128)` bound on a `form:submitted` key. */
+const MAX_FORM_KEY_LENGTH = 128;
+const VALID_PATTERN_FLAGS = /^[dgimsuvy]*$/;
+const RESOLVED_SCHEMAS = /* @__PURE__ */ new WeakMap();
+function resolveForm({ schema }) {
+	const memoized = RESOLVED_SCHEMAS.get(schema);
+	if (memoized) return memoized;
+	const resolved = validateAndCompile({ schema });
+	RESOLVED_SCHEMAS.set(schema, resolved);
+	return resolved;
+}
+function validateAndCompile({ schema }) {
+	const root = schema;
+	assertJsonRepresentable({ root });
+	if (!isObjectLike$1(root)) throw new SchemaError("schema: must be an object");
+	const formKey = root["id"];
+	if (typeof formKey !== "string" || formKey.trim() === "") throw new SchemaError("schema.id: must be a non-empty string");
+	if (formKey !== formKey.trim()) throw new SchemaError("schema.id: must not have leading or trailing whitespace");
+	if (formKey.length > MAX_FORM_KEY_LENGTH) throw new SchemaError(`schema.id: must be at most ${MAX_FORM_KEY_LENGTH} characters (received ${formKey.length})`);
+	const name = root["name"];
+	if (name !== void 0) {
+		if (typeof name !== "string") throw new SchemaError("schema.name: must be a string");
+		if (name.trim() === "") throw new SchemaError("schema.name: must be a non-empty string");
+	}
+	if (!Array.isArray(root["fields"])) throw new SchemaError("schema.fields: must be an array");
+	const fields = root["fields"];
+	if (fields.length === 0) throw new SchemaError("schema.fields: must declare at least one field");
+	const patterns = /* @__PURE__ */ new Map();
+	const seenKeys = /* @__PURE__ */ new Set();
+	fields.forEach((field, index) => {
+		validateField({
+			field,
+			path: `schema.fields[${index}]`,
+			seenKeys,
+			patterns
+		});
+	});
+	return {
+		formKey,
+		fields: [...fields],
+		patterns
+	};
+}
+function validateField({ field, path, seenKeys, patterns }) {
+	if (!isObjectLike$1(field)) throw new SchemaError(`${path}: must be an object`);
+	const key = field["key"];
+	if (typeof key !== "string" || key.trim() === "") throw new SchemaError(`${path}.key: must be a non-empty string`);
+	if (key.length > MAX_FIELD_KEY_LENGTH) throw new SchemaError(`${path}.key: must be at most ${MAX_FIELD_KEY_LENGTH} characters (received ${key.length})`);
+	if (seenKeys.has(key)) throw new SchemaError(`${path}.key: duplicate field key "${key}" in this form`);
+	seenKeys.add(key);
+	const label = field["label"];
+	if (typeof label !== "string" || label.trim() === "") throw new SchemaError(`${path}.label: must be a non-empty string`);
+	const type = field["type"];
+	if (typeof type !== "string" || !FIELD_TYPES.includes(type)) throw new SchemaError(`${path}.type: must be one of ${FIELD_TYPES.join(", ")}`);
+	const registryFieldId = field["registryFieldId"];
+	if (registryFieldId !== void 0 && typeof registryFieldId !== "string") throw new SchemaError(`${path}.registryFieldId: must be a string`);
+	const protocolFieldId = field["protocolFieldId"];
+	if (protocolFieldId !== void 0 && typeof protocolFieldId !== "string") throw new SchemaError(`${path}.protocolFieldId: must be a string`);
+	const validations = field["validations"];
+	if (validations === void 0) return;
+	validateValidations({
+		validations,
+		path: `${path}.validations`
+	});
+	if (!isObjectLike$1(validations)) return;
+	const pattern = validations["pattern"];
+	if (typeof pattern !== "string") return;
+	const flags = validations["patternFlags"];
+	patterns.set(key, compilePattern({
+		pattern,
+		flags: typeof flags === "string" ? flags : "",
+		path: `${path}.validations.pattern`
+	}));
+}
+function validateValidations({ validations, path }) {
+	if (!isObjectLike$1(validations)) throw new SchemaError(`${path}: must be an object`);
+	for (const rule of Object.keys(validations)) if (!VALIDATION_RULES.includes(rule)) throw new SchemaError(`${path}.${rule}: unknown validation rule; expected one of ${VALIDATION_RULES.join(", ")}`);
+	const required = validations["required"];
+	if (required !== void 0 && typeof required !== "boolean") throw new SchemaError(`${path}.required: must be a boolean`);
+	for (const rule of NUMERIC_RULES) {
+		const value = validations[rule];
+		if (value !== void 0 && !(typeof value === "number" && Number.isFinite(value))) throw new SchemaError(`${path}.${rule}: must be a finite number`);
+	}
+	const minLength = validations["minLength"];
+	const maxLength = validations["maxLength"];
+	if (typeof minLength === "number" && typeof maxLength === "number" && maxLength < minLength) throw new SchemaError(`${path}.maxLength: must be greater than or equal to minLength`);
+	const min = validations["min"];
+	const max = validations["max"];
+	if (typeof min === "number" && typeof max === "number" && max < min) throw new SchemaError(`${path}.max: must be greater than or equal to min`);
+	const oneOf = validations["oneOf"];
+	if (oneOf !== void 0 && !(Array.isArray(oneOf) && oneOf.length > 0)) throw new SchemaError(`${path}.oneOf: must be a non-empty array`);
+	const pattern = validations["pattern"];
+	if (pattern !== void 0 && typeof pattern !== "string") throw new SchemaError(`${path}.pattern: must be a string`);
+	const patternFlags = validations["patternFlags"];
+	if (patternFlags !== void 0 && !(typeof patternFlags === "string" && VALID_PATTERN_FLAGS.test(patternFlags))) throw new SchemaError(`${path}.patternFlags: must contain only the characters dgimsuvy`);
+	const custom = validations["custom"];
+	if (custom !== void 0 && typeof custom !== "function") throw new SchemaError(`${path}.custom: must be a function (received ${typeof custom})`);
+}
+function compilePattern({ pattern, flags, path }) {
+	try {
+		return new RegExp(pattern, flags.replace(/[gy]/g, ""));
+	} catch (error) {
+		throw new SchemaError(`${path}: invalid pattern — ${errorMessage(error)}`, { cause: error });
+	}
+}
+/**
+* Rejects every value in the config that would not survive
+* `JSON.parse(JSON.stringify(x))` — a function included, except at the one
+* permitted location, `validations.custom` on a field.
+*/
+function assertJsonRepresentable({ root }) {
+	const stripped = withoutFieldValidators(root);
+	const serialized = stringifyOrUndefined(stripped);
+	if (serialized === void 0) throw new SchemaError(`${findNonJsonPath({
+		value: stripped,
+		path: "schema",
+		seen: /* @__PURE__ */ new Set()
+	}) ?? "schema"}: value cannot be serialized to JSON`);
+	const mismatch = firstMismatch({
+		actual: stripped,
+		expected: JSON.parse(serialized),
+		path: "schema"
+	});
+	if (mismatch) throw new SchemaError(`${mismatch}: value does not survive a JSON round trip; only a field's validations.custom may hold a function, and every other value must be JSON-representable`);
+}
+function withoutFieldValidators(root) {
+	if (!isObjectLike$1(root)) return root;
+	if (!Array.isArray(root["fields"])) return root;
+	const fields = root["fields"];
+	return {
+		...root,
+		fields: fields.map(stripField)
+	};
+}
+function stripField(field) {
+	if (!isObjectLike$1(field)) return field;
+	const validations = field["validations"];
+	if (!isObjectLike$1(validations) || !("custom" in validations)) return field;
+	const { custom: _custom, ...rest } = validations;
+	return {
+		...field,
+		validations: rest
+	};
+}
+function stringifyOrUndefined(value) {
+	try {
+		return JSON.stringify(value);
+	} catch {
+		return;
+	}
+}
+/** The path of the first value `JSON.stringify` cannot handle at all. */
+function findNonJsonPath({ value, path, seen }) {
+	if (typeof value === "bigint" || typeof value === "symbol") return path;
+	if (value === null || typeof value !== "object") return void 0;
+	if (seen.has(value)) return path;
+	seen.add(value);
+	for (const [childPath, child] of childEntries({
+		value,
+		path
+	})) {
+		const found = findNonJsonPath({
+			value: child,
+			path: childPath,
+			seen
+		});
+		if (found) return found;
+	}
+	seen.delete(value);
+}
+function childEntries({ value, path }) {
+	if (Array.isArray(value)) return value.map((item, index) => [`${path}[${index}]`, item]);
+	return Object.entries(value).map(([key, item]) => [`${path}.${key}`, item]);
+}
+/** The path of the first value that changed across the round trip. */
+function firstMismatch({ actual, expected, path }) {
+	if (Array.isArray(actual) || Array.isArray(expected)) {
+		if (!Array.isArray(actual) || !Array.isArray(expected)) return path;
+		const actualItems = actual;
+		const expectedItems = expected;
+		if (actualItems.length !== expectedItems.length) return path;
+		for (const [index, item] of actualItems.entries()) {
+			const found = firstMismatch({
+				actual: item,
+				expected: expectedItems[index],
+				path: `${path}[${index}]`
+			});
+			if (found) return found;
+		}
+		return;
+	}
+	if (isJsonObject(actual) && isJsonObject(expected)) {
+		const actualKeys = Object.keys(actual);
+		const expectedKeys = Object.keys(expected);
+		if (actualKeys.length !== expectedKeys.length) {
+			const dropped = actualKeys.find((key) => !expectedKeys.includes(key));
+			return dropped === void 0 ? path : `${path}.${dropped}`;
+		}
+		for (const key of actualKeys) {
+			const found = firstMismatch({
+				actual: actual[key],
+				expected: expected[key],
+				path: `${path}.${key}`
+			});
+			if (found) return found;
+		}
+		return;
+	}
+	return actual === expected ? void 0 : path;
+}
+function isObjectLike$1(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Narrower than `isObjectLike`: a `Date`, `RegExp`, or class instance is not one. */
+function isJsonObject(value) {
+	if (!isObjectLike$1(value)) return false;
+	const prototype = Object.getPrototypeOf(value);
+	return prototype === Object.prototype || prototype === null;
+}
+function errorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+//#endregion
+//#region src/storage.ts
+/** Every form on the origin shares this one entry, indexed by form key. */
+const FORM_DATA_KEY = "EMBEDDABLES-FORM-DATA";
+const LIVE_DOCUMENTS = /* @__PURE__ */ new WeakMap();
+function readDocumentFromStorage({ storage }) {
+	try {
+		const raw = storage.getItem(FORM_DATA_KEY);
+		if (raw === null) return {};
+		const parsed = JSON.parse(raw);
+		if (!isObjectLike(parsed)) return {};
+		return parsed;
+	} catch {
+		return {};
+	}
+}
+/**
+* Load once per storage object; later calls reuse the in-memory document.
+*
+* There is no invalidation: a write from another tab or a user clearing site
+* data is never picked up, and the next write here overwrites it. Recovering
+* from an external mutation means constructing a new storage object.
+*/
+function loadDocument({ storage }) {
+	const cached = LIVE_DOCUMENTS.get(storage);
+	if (cached) return cached;
+	const document = readDocumentFromStorage({ storage });
+	LIVE_DOCUMENTS.set(storage, document);
+	return document;
+}
+function resolveStorage({ storage }) {
+	if (storage) return storage;
+	try {
+		const candidate = globalThis.localStorage;
+		candidate.getItem(FORM_DATA_KEY);
+		return candidate;
+	} catch {
+		return createMemoryStorage();
+	}
+}
+/**
+* A fresh in-memory shim seeded with the document as last read, for an instance
+* whose real storage started throwing mid-session.
+*/
+function degradeToMemory({ storage }) {
+	const shim = createMemoryStorage();
+	const snapshot = { ...LIVE_DOCUMENTS.get(storage) ?? readDocumentFromStorage({ storage }) };
+	shim.setItem(FORM_DATA_KEY, JSON.stringify(snapshot));
+	LIVE_DOCUMENTS.set(shim, snapshot);
+	return shim;
+}
+function readFields({ storage, formKey }) {
+	const bag = loadDocument({ storage })[formKey];
+	if (!isObjectLike(bag)) return {};
+	return bag;
+}
+function writeFields({ storage, formKey, fields }) {
+	const next = {
+		...loadDocument({ storage }),
+		[formKey]: { ...fields }
+	};
+	storage.setItem(FORM_DATA_KEY, JSON.stringify(next));
+	LIVE_DOCUMENTS.set(storage, next);
+}
+function removeFields({ storage, formKey }) {
+	const { [formKey]: _dropped, ...rest } = loadDocument({ storage });
+	if (Object.keys(rest).length === 0) {
+		storage.removeItem(FORM_DATA_KEY);
+		LIVE_DOCUMENTS.set(storage, rest);
+		return;
+	}
+	storage.setItem(FORM_DATA_KEY, JSON.stringify(rest));
+	LIVE_DOCUMENTS.set(storage, rest);
+}
+/**
+* Whether a value survives `JSON.stringify`. `undefined`, a function, and a
+* `Symbol` make it return `undefined`; a circular reference and a `BigInt` make
+* it throw. All five must be rejected before a write, because a value that
+* cannot stringify aborts a write carrying every form's data.
+*/
+function isSerializable({ value }) {
+	try {
+		return typeof JSON.stringify(value) === "string";
+	} catch {
+		return false;
+	}
+}
+function createMemoryStorage() {
+	const entries = /* @__PURE__ */ new Map();
+	return {
+		getItem: (key) => entries.get(key) ?? null,
+		setItem: (key, value) => {
+			entries.set(key, value);
+		},
+		removeItem: (key) => {
+			entries.delete(key);
+		}
+	};
+}
+function isObjectLike(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//#endregion
+//#region src/validation.ts
+/** Runtime counterpart to `FieldType`. Exhaustive by construction. */
+const FIELD_TYPE_PREDICATES = {
+	text: (value) => typeof value === "string",
+	email: (value) => typeof value === "string",
+	number: (value) => typeof value === "number",
+	boolean: (value) => typeof value === "boolean",
+	select: (value) => typeof value === "string",
+	multiselect: (value) => Array.isArray(value),
+	json: () => true
+};
+const EMAIL_PATTERN = /^[\w.!#$%&'*+/=?^`{|}~-]+@[a-zA-Z\d](?:[a-zA-Z\d-]{0,61}[a-zA-Z\d])?(?:\.[a-zA-Z\d](?:[a-zA-Z\d-]{0,61}[a-zA-Z\d])?)*$/;
+/**
+* Every message a single field's value earns. Empty means valid. Not generic:
+* the per-field types live at the instance boundary, and the cast down to
+* `JsonValue` happens once, in `initForm`.
+*/
+function validateValue({ field, value, values, pattern, validator }) {
+	const rules = field.validations;
+	const messages = [];
+	const isAbsent = value === void 0 || value === null;
+	const isBlank = isAbsent || value === "" || Array.isArray(value) && value.length === 0;
+	if (rules?.required === true && isBlank) messages.push(`${field.label} is required`);
+	if (isAbsent) return messages;
+	if (!FIELD_TYPE_PREDICATES[field.type](value)) messages.push(`${field.label} expects ${/^[aeiou]/.test(field.type) ? "an" : "a"} ${field.type} value`);
+	if (typeof value === "string") {
+		if (field.type === "email" && value !== "" && !EMAIL_PATTERN.test(value)) messages.push(`${field.label} must be a valid email address`);
+		if (rules?.minLength !== void 0 && value.length < rules.minLength) messages.push(`${field.label} must be at least ${rules.minLength} characters`);
+		if (rules?.maxLength !== void 0 && value.length > rules.maxLength) messages.push(`${field.label} must be at most ${rules.maxLength} characters`);
+		if (pattern && !pattern.test(value)) messages.push(`${field.label} is not in the expected format`);
+	}
+	if (Array.isArray(value)) {
+		if (rules?.minLength !== void 0 && value.length < rules.minLength) messages.push(`${field.label} must have at least ${rules.minLength} items`);
+		if (rules?.maxLength !== void 0 && value.length > rules.maxLength) messages.push(`${field.label} must have at most ${rules.maxLength} items`);
+	}
+	if (typeof value === "number") {
+		if (rules?.min !== void 0 && value < rules.min) messages.push(`${field.label} must be at least ${rules.min}`);
+		if (rules?.max !== void 0 && value > rules.max) messages.push(`${field.label} must be at most ${rules.max}`);
+	}
+	if (rules?.oneOf) {
+		const encoded = canonicalize(value);
+		if (!rules.oneOf.some((option) => canonicalize(option) === encoded)) messages.push(`${field.label} must be one of the allowed options`);
+	}
+	if (!validator || messages.length > 0) return messages;
+	return normalizeValidatorResult({
+		result: validator({
+			value,
+			values
+		}),
+		field
+	});
+}
+function normalizeValidatorResult({ result, field }) {
+	if (isThenable(result)) throw new ValidatorError(`Validator for "${field.key}" returned a promise; custom validators must be synchronous`);
+	if (result === null || result === void 0) return [];
+	if (typeof result === "string") return [result];
+	if (Array.isArray(result)) return result.filter((entry) => typeof entry === "string");
+	throw new ValidatorError(`Validator for "${field.key}" returned ${typeof result}; expected a string, an array of strings, or null`);
+}
+function isThenable(value) {
+	return typeof value?.then === "function";
+}
+/**
+* JSON encoding with object keys sorted at every depth, so two values compare
+* by content rather than by insertion order.
+*/
+function canonicalize(value) {
+	const walk = (input) => {
+		if (Array.isArray(input)) return input.map(walk);
+		if (input !== null && typeof input === "object") return Object.fromEntries(Object.entries(input).sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0).map(([key, item]) => [key, walk(item)]));
+		return input;
+	};
+	return JSON.stringify(walk(value));
+}
+//#endregion
+//#region src/form.ts
+const REQUIRED_CORE_METHODS = [
+	"getAppUserId",
+	"getProjectId",
+	"getPublishableKey"
+];
+function hasRequiredCoreMethods(value) {
+	if (typeof value !== "object" || value === null) return false;
+	return REQUIRED_CORE_METHODS.every((method) => typeof value[method] === "function");
+}
+function mergeCustomValidations({ schema, customValidations }) {
+	if (!customValidations) return schema;
+	const declared = new Set(schema.fields.map((field) => field.key));
+	for (const key of Object.keys(customValidations)) {
+		if (!declared.has(key)) throw new SchemaError(`customValidations: unknown field key "${key}"`);
+		if (typeof customValidations[key] !== "function") throw new SchemaError(`customValidations.${key}: must be a function`);
+	}
+	const fields = schema.fields.map((field) => {
+		const custom = customValidations[field.key];
+		if (!custom) return field;
+		return {
+			...field,
+			validations: {
+				...field.validations,
+				custom
+			}
+		};
+	});
+	return {
+		...schema,
+		fields
+	};
+}
+/**
+* Validates the core instance once, then returns a per-form `initForm`. Public
+* API — the Miro signature. Consumers pass only `core` and, optionally, an
+* analytics client.
+*/
+function initForms(options) {
+	return createFormsClient(options);
+}
+function createFormsClient({ core, analyticsInstance, baseUrl, storage, persistence }) {
+	if (!hasRequiredCoreMethods(core)) throw new FormsError("initForms requires an initialized Embeddables core instance.");
+	const resolvedPersistence = persistence ?? resolveDefaultPersistence({
+		core,
+		baseUrl
+	});
+	return { initForm: (options) => createFormInstance({
+		analyticsInstance,
+		storage,
+		persistence: resolvedPersistence,
+		schema: options.schema,
+		customValidations: options.customValidations
+	}) };
+}
+function createFormInstance({ analyticsInstance, storage, persistence, schema, customValidations }) {
+	const resolved = resolveForm({ schema: mergeCustomValidations({
+		schema,
+		customValidations
+	}) });
+	const declared = new Map(resolved.fields.map((field) => [field.key, field]));
+	const resolvedStorage = resolveStorage({ storage });
+	const state = {
+		storage: resolvedStorage,
+		bag: { ...readFields({
+			storage: resolvedStorage,
+			formKey: resolved.formKey
+		}) },
+		errors: /* @__PURE__ */ new Map()
+	};
+	const firePersistence = (run) => {
+		try {
+			const result = run();
+			if (result instanceof Promise) result.then(void 0, () => void 0);
+		} catch {}
+	};
+	const mergeRecovered = (recovered) => {
+		for (const [key, value] of Object.entries(recovered)) if (value !== void 0 && state.bag[key] === void 0) state.bag[key] = value;
+	};
+	const recoverable = resolved.fields.filter((field) => (field.registryFieldId !== void 0 || field.protocolFieldId !== void 0) && state.bag[field.key] === void 0).map((field) => ({
+		key: field.key,
+		registryFieldId: field.registryFieldId,
+		protocolFieldId: field.protocolFieldId
+	}));
+	if (recoverable.length > 0) try {
+		const result = persistence.recoverRegistryFields({
+			formKey: resolved.formKey,
+			fields: recoverable
+		});
+		if (result instanceof Promise) result.then((recovered) => mergeRecovered(recovered ?? {}), () => void 0);
+		else mergeRecovered(result);
+	} catch {}
+	const freeze = (entries) => Object.freeze(Object.fromEntries(entries));
+	const noErrors = () => freeze(/* @__PURE__ */ new Map());
+	/** The stored bag narrowed to the keys the config declares. */
+	const narrow = (bag) => {
+		const narrowed = {};
+		for (const field of resolved.fields) {
+			const value = bag[field.key];
+			if (value !== void 0) narrowed[field.key] = value;
+		}
+		return narrowed;
+	};
+	const readBag = () => state.bag;
+	const validatorFor = (field) => field.validations?.custom;
+	const validateDeclaredFields = ({ snapshot, keys }) => {
+		const errors = /* @__PURE__ */ new Map();
+		for (const key of keys) {
+			const field = declared.get(key);
+			if (!field) continue;
+			const messages = validateValue({
+				field,
+				value: snapshot[field.key],
+				values: snapshot,
+				pattern: resolved.patterns.get(key),
+				validator: validatorFor(field)
+			});
+			if (messages.length > 0) errors.set(key, messages);
+		}
+		return errors;
+	};
+	const replaceErrors = (errors) => {
+		state.errors.clear();
+		for (const [key, messages] of errors) state.errors.set(key, messages);
+	};
+	const applyPatchValidationErrors = ({ errors, patchKeys }) => {
+		for (const key of patchKeys) {
+			const messages = errors.get(key);
+			if (messages) state.errors.set(key, messages);
+			else state.errors.delete(key);
+		}
+	};
+	const set = (patch) => {
+		const changes = patch;
+		const entries = Object.entries(changes);
+		if (entries.length === 0) return Promise.resolve({
+			ok: true,
+			errors: noErrors()
+		});
+		const errors = /* @__PURE__ */ new Map();
+		for (const [key, value] of entries) {
+			const field = declared.get(key);
+			if (!field) {
+				errors.set(key, [`Unknown field: ${key}`]);
+				continue;
+			}
+			if (!isSerializable({ value })) errors.set(key, [`${field.label} value is not JSON-serializable`]);
+		}
+		const candidate = {
+			...readBag(),
+			...changes
+		};
+		const snapshot = narrow(candidate);
+		for (const [key, value] of entries) {
+			const field = declared.get(key);
+			if (!field || errors.has(key)) continue;
+			const messages = validateValue({
+				field,
+				value,
+				values: snapshot,
+				pattern: resolved.patterns.get(key),
+				validator: validatorFor(field)
+			});
+			if (messages.length > 0) errors.set(key, messages);
+		}
+		if (errors.size > 0) {
+			for (const [key, messages] of errors) state.errors.set(key, messages);
+			return Promise.resolve({
+				ok: false,
+				errors: freeze(errors)
+			});
+		}
+		for (const [key] of entries) state.errors.delete(key);
+		try {
+			writeFields({
+				storage: state.storage,
+				formKey: resolved.formKey,
+				fields: candidate
+			});
+			state.bag = candidate;
+		} catch {
+			return Promise.resolve(degradeAndReport({ entries }));
+		}
+		const persistedFields = entries.map(([key, value]) => {
+			const field = declared.get(key);
+			return {
+				key,
+				value,
+				registryFieldId: field?.registryFieldId,
+				protocolFieldId: field?.protocolFieldId
+			};
+		});
+		firePersistence(() => persistence.savePartial({
+			formKey: resolved.formKey,
+			values: snapshot
+		}));
+		firePersistence(() => persistence.saveFields({
+			formKey: resolved.formKey,
+			fields: persistedFields
+		}));
+		if (!analyticsInstance) return Promise.resolve({
+			ok: true,
+			errors: noErrors()
+		});
+		return analyticsInstance.trackEvent([buildDataUpdatedEvent({
+			fields: resolved.fields,
+			patch: changes
+		}), ...buildFieldUpdatedEvents({
+			fields: resolved.fields,
+			patch: changes
+		})]).then(() => ({
+			ok: true,
+			errors: noErrors()
+		})).catch((error) => ({
+			ok: true,
+			errors: noErrors(),
+			trackError: error
+		}));
+	};
+	const degradeAndReport = ({ entries }) => {
+		state.storage = degradeToMemory({ storage: state.storage });
+		const errors = /* @__PURE__ */ new Map();
+		for (const [key] of entries) {
+			const message = `${declared.get(key)?.label ?? key} could not be persisted; this form is now in-memory only`;
+			errors.set(key, [message]);
+			state.errors.set(key, [message]);
+		}
+		return {
+			ok: false,
+			errors: freeze(errors)
+		};
+	};
+	const get = (key) => {
+		const fieldKey = key;
+		if (!declared.has(fieldKey)) return void 0;
+		return state.bag[fieldKey];
+	};
+	const getAll = () => narrow(state.bag);
+	const submit = () => {
+		const snapshot = narrow(readBag());
+		const values = snapshot;
+		const errors = validateDeclaredFields({
+			snapshot,
+			keys: resolved.fields.map((field) => field.key)
+		});
+		if (errors.size > 0) {
+			replaceErrors(errors);
+			return Promise.resolve({
+				ok: false,
+				errors: freeze(errors),
+				values
+			});
+		}
+		state.errors.clear();
+		firePersistence(() => persistence.saveSubmission({
+			formKey: resolved.formKey,
+			values: snapshot
+		}));
+		if (!analyticsInstance) return Promise.resolve({
+			ok: true,
+			errors: noErrors(),
+			values
+		});
+		return analyticsInstance.trackEvent([{
+			event_name: "form:submitted",
+			form_key: resolved.formKey
+		}]).then(() => ({
+			ok: true,
+			errors: noErrors(),
+			values
+		})).catch((error) => ({
+			ok: true,
+			errors: noErrors(),
+			values,
+			trackError: error
+		}));
+	};
+	const validate = (patch) => {
+		if (patch === void 0) {
+			const snapshot = narrow(readBag());
+			const values = snapshot;
+			const errors = validateDeclaredFields({
+				snapshot,
+				keys: resolved.fields.map((field) => field.key)
+			});
+			if (errors.size > 0) {
+				replaceErrors(errors);
+				return Promise.resolve({
+					ok: false,
+					errors: freeze(errors),
+					values
+				});
+			}
+			state.errors.clear();
+			return Promise.resolve({
+				ok: true,
+				errors: noErrors(),
+				values
+			});
+		}
+		const changes = patch;
+		const entries = Object.entries(changes);
+		const values = narrow({
+			...readBag(),
+			...changes
+		});
+		if (entries.length === 0) return Promise.resolve({
+			ok: true,
+			errors: noErrors(),
+			values
+		});
+		const errors = /* @__PURE__ */ new Map();
+		const patchKeys = entries.map(([key]) => key);
+		for (const [key, value] of entries) {
+			const field = declared.get(key);
+			if (!field) {
+				errors.set(key, [`Unknown field: ${key}`]);
+				continue;
+			}
+			if (!isSerializable({ value })) errors.set(key, [`${field.label} value is not JSON-serializable`]);
+		}
+		const snapshot = narrow({
+			...readBag(),
+			...changes
+		});
+		for (const [key] of entries) {
+			if (errors.has(key)) continue;
+			const field = declared.get(key);
+			if (!field) continue;
+			const messages = validateValue({
+				field,
+				value: snapshot[key],
+				values: snapshot,
+				pattern: resolved.patterns.get(key),
+				validator: validatorFor(field)
+			});
+			if (messages.length > 0) errors.set(key, messages);
+		}
+		applyPatchValidationErrors({
+			errors,
+			patchKeys
+		});
+		if (errors.size > 0) return Promise.resolve({
+			ok: false,
+			errors: freeze(errors),
+			values
+		});
+		return Promise.resolve({
+			ok: true,
+			errors: noErrors(),
+			values
+		});
+	};
+	const clear = () => {
+		removeFields({
+			storage: state.storage,
+			formKey: resolved.formKey
+		});
+		state.bag = {};
+		state.errors.clear();
+	};
+	return {
+		key: schema.id,
+		set,
+		get,
+		getAll,
+		submit,
+		validate,
+		errors: () => freeze(state.errors),
+		clear
+	};
+}
+//#endregion
+export { FORM_DATA_KEY, FormsError, SchemaError, ValidatorError, initForms };
+
+//# sourceMappingURL=index.js.map