@embeddables/forms 0.2.0 → 0.3.0

package/dist/{form-BOHdxeuO.cjs → form-lmr-O7j7.cjs}

@@ -32,6 +32,21 @@ var ValidatorError = class extends FormsError {
 	}
 };
 //#endregion
+//#region src/types/form-file.ts
+function contentTypeMatchesAccept({ contentType, accept }) {
+	const normalized = contentType.split(";", 1)[0]?.trim().toLowerCase() || "";
+	return accept.some((entry) => {
+		const pattern = entry.trim().toLowerCase();
+		if (pattern.endsWith("/*")) return normalized.startsWith(pattern.slice(0, -1));
+		return normalized === pattern;
+	});
+}
+function isFormFileRef(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const record = value;
+	return typeof record.file_id === "string" && typeof record.name === "string" && typeof record.content_type === "string" && typeof record.size === "number" && Number.isFinite(record.size) && (record.status === "uploading" || record.status === "done" || record.status === "error");
+}
+//#endregion
 //#region src/core/validation.ts
 /** Runtime counterpart to `FieldType`. Exhaustive by construction. */
 const FIELD_TYPE_PREDICATES = {
@@ -41,7 +56,8 @@ const FIELD_TYPE_PREDICATES = {
 	boolean: (value) => typeof value === "boolean",
 	select: (value) => typeof value === "string",
 	multiselect: (value) => Array.isArray(value),
-	json: () => true
+	json: () => true,
+	file: (value) => value === null || isFormFileRef(value)
 };
 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])?)*$/;
 /**
@@ -56,9 +72,9 @@ function validateValue({ field, value, values, pattern, validator }) {
 	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 (!FIELD_TYPE_PREDICATES[field.value_type](value)) messages.push(`${field.label} expects ${/^[aeiou]/.test(field.value_type) ? "an" : "a"} ${field.value_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 (field.value_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`);
@@ -71,12 +87,12 @@ function validateValue({ field, value, values, pattern, validator }) {
 		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 (field.type === "select" || field.type === "multiselect") {
+	if (field.value_type === "select" || field.value_type === "multiselect") {
 		const options = field.options;
 		if (options) {
-			const allowed = new Set(options.map((option) => option.value));
-			if (field.type === "select" && typeof value === "string" && !allowed.has(value)) messages.push(`${field.label} must be one of the allowed options`);
-			if (field.type === "multiselect" && Array.isArray(value)) {
+			const allowed = new Set(options.map((option) => option.key));
+			if (field.value_type === "select" && typeof value === "string" && !allowed.has(value)) messages.push(`${field.label} must be one of the allowed options`);
+			if (field.value_type === "multiselect" && Array.isArray(value)) {
 				if (value.some((entry) => typeof entry !== "string" || !allowed.has(entry))) messages.push(`${field.label} has values that are not allowed options`);
 			}
 		}
@@ -85,6 +101,14 @@ function validateValue({ field, value, values, pattern, validator }) {
 		const encoded = canonicalize(value);
 		if (!rules.oneOf.some((option) => canonicalize(option) === encoded)) messages.push(`${field.label} must be one of the allowed options`);
 	}
+	if (field.value_type === "file" && isFormFileRef(value)) {
+		if (value.status !== "done") messages.push(`${field.label} upload is not complete`);
+		if (rules?.maxSize !== void 0 && value.size > rules.maxSize) messages.push(`${field.label} must be at most ${rules.maxSize} bytes`);
+		if (rules?.accept !== void 0 && !contentTypeMatchesAccept({
+			contentType: value.content_type,
+			accept: rules.accept
+		})) messages.push(`${field.label} must be one of the allowed file types`);
+	}
 	if (!validator || messages.length > 0) return messages;
 	return normalizeValidatorResult({
 		result: validator({
@@ -127,7 +151,8 @@ const FIELD_TYPES$2 = [
 	"boolean",
 	"select",
 	"multiselect",
-	"json"
+	"json",
+	"file"
 ];
 const LIVE_DOCUMENTS = /* @__PURE__ */ new WeakMap();
 function readDocumentFromStorage({ storage }) {
@@ -198,7 +223,7 @@ function writeFields({ storage, formKey, fields, fieldDefinitions }) {
 		if (value === void 0) continue;
 		nextForm[field.key] = {
 			value,
-			type: field.type,
+			type: field.value_type,
 			label: field.label,
 			...field.registryId === void 0 ? {} : { registryId: field.registryId },
 			...field.protocolFieldId === void 0 ? {} : { protocolFieldId: field.protocolFieldId }
@@ -280,7 +305,7 @@ function buildCookiePayloadFromBag({ bag, fieldDefinitions }) {
 		if (value === void 0) continue;
 		payload[field.key] = {
 			value,
-			type: field.type,
+			type: field.value_type,
 			label: field.label,
 			...field.registryId === void 0 ? {} : { registryId: field.registryId },
 			...field.protocolFieldId === void 0 ? {} : { protocolFieldId: field.protocolFieldId }
@@ -300,10 +325,10 @@ function isStoredField(value) {
 	return true;
 }
 function entryMatchesFieldDefinition(entry, field) {
-	if (entry.type !== field.type || entry.label !== field.label) return false;
+	if (entry.type !== field.value_type || entry.label !== field.label) return false;
 	if ((entry.registryId ?? void 0) !== (field.registryId ?? void 0)) return false;
 	if ((entry.protocolFieldId ?? void 0) !== (field.protocolFieldId ?? void 0)) return false;
-	return FIELD_TYPE_PREDICATES[field.type](entry.value);
+	return FIELD_TYPE_PREDICATES[field.value_type](entry.value);
 }
 function serializeBrowserCookie(key, value) {
 	const locationRef = globalThis.location;
@@ -436,7 +461,7 @@ function createNoopPersistence() {
 }
 //#endregion
 //#region src/storage/persistence-client.ts
-const PUBLISHABLE_KEY_HEADER = "x-publishable-key";
+const PUBLISHABLE_KEY_HEADER$1 = "x-publishable-key";
 const hcWithType = (...args) => (0, hono_client.hc)(...args);
 function withTimeout(fetchImpl, timeoutMs) {
 	return async (input, init) => {
@@ -469,7 +494,7 @@ 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 }
+		headers: { [PUBLISHABLE_KEY_HEADER$1]: config.publishableKey }
 	});
 	return {
 		savePartial({ formKey, values }) {
@@ -498,14 +523,88 @@ function resolveDefaultPersistence(config) {
 	return createApiPersistence(resolved);
 }
 //#endregion
+//#region src/storage/upload-client.ts
+const PUBLISHABLE_KEY_HEADER = "x-publishable-key";
+function mapUploadErrorMessage(problem, status) {
+	const code = problem?.code;
+	if (code === "validation.file_too_large") return problem?.detail ?? "Maximum upload size is 25 MiB.";
+	if (code === "validation.unsupported_content_type") return problem?.detail ?? "Unsupported file type.";
+	if (code === "validation.upload_failed") return problem?.detail ?? "Upload could not be completed.";
+	if (code === "service.form_uploads_not_configured") return problem?.detail ?? "File uploads are not configured for this project.";
+	if (code === "validation.failed") return problem?.detail ?? "Upload metadata is invalid.";
+	return problem?.detail ?? problem?.title ?? `File upload failed (${status}).`;
+}
+function uploadResultToFormFileRef(result) {
+	return {
+		file_id: result.file_id,
+		name: result.name,
+		content_type: result.content_type,
+		size: result.size,
+		status: "done",
+		uploaded_at: result.uploaded_at
+	};
+}
+function toUploadFetchError(error, path, timeoutMs) {
+	if (error instanceof FormsError) return error;
+	if (error instanceof Error && error.name === "AbortError") return new FormsError(`Request to ${path} timed out after ${timeoutMs}ms`, { cause: error });
+	return new FormsError(`Request to ${path} failed to reach the API`, { cause: error });
+}
+function toUploadDecodeError(error, path) {
+	return new FormsError(`Upload response from ${path} could not be decoded`, { cause: error });
+}
+async function uploadFormFile(config, input) {
+	const url = `${config.baseUrl.replace(/\/+$/, "")}/forms/v1/public/uploads`;
+	const formData = new FormData();
+	formData.append("project_id", config.projectId);
+	formData.append("app_user_id", config.appUserId);
+	formData.append("form_id", input.formId);
+	formData.append("field_key", input.fieldKey);
+	const fileName = input.fileName ?? (typeof File !== "undefined" && input.file instanceof File ? input.file.name : "upload");
+	formData.append("file", input.file, fileName);
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), config.timeoutMs);
+	try {
+		const res = await config.fetch(url, {
+			method: "POST",
+			headers: { [PUBLISHABLE_KEY_HEADER]: config.publishableKey },
+			body: formData,
+			signal: controller.signal
+		});
+		clearTimeout(timer);
+		if (!res.ok) throw new FormsError(mapUploadErrorMessage(await res.json().catch(() => null), res.status));
+		try {
+			return uploadResultToFormFileRef(await res.json());
+		} catch (error) {
+			throw toUploadDecodeError(error, url);
+		}
+	} catch (error) {
+		throw toUploadFetchError(error, url, config.timeoutMs);
+	} finally {
+		clearTimeout(timer);
+	}
+}
+//#endregion
 //#region src/core/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;
+/** Maps a form field's declared value type to the analytics `field:updated` class. */
+function mapFieldUpdatedType(valueType) {
+	return valueType;
+}
+function resolvedFieldClassification(field) {
+	return field.field_type ?? "user_input";
+}
+function isAnalyticsExcludedField(field) {
+	return resolvedFieldClassification(field) === "local_only";
+}
+function analyticsPatchEntries({ fields, patch }) {
+	const byKey = new Map(fields.map((field) => [field.key, field]));
+	return Object.entries(patch).filter(([key]) => {
+		const field = byKey.get(key);
+		return field === void 0 || !isAnalyticsExcludedField(field);
+	});
 }
 /**
 * Stringifies values for `data:updated` entries. `field:updated` carries the
@@ -518,9 +617,13 @@ function formatFieldValue({ value }) {
 /** One event carrying every key in one `.set()` call. */
 function buildDataUpdatedEvent({ fields, patch, formId }) {
 	const byKey = new Map(fields.map((field) => [field.key, field]));
+	const entries = analyticsPatchEntries({
+		fields,
+		patch
+	});
 	return {
 		event_name: "data:updated",
-		data: Object.fromEntries(Object.entries(patch).map(([key, value]) => {
+		data: Object.fromEntries(entries.map(([key, value]) => {
 			const field = byKey.get(key);
 			return [key, {
 				value: formatFieldValue({
@@ -536,12 +639,15 @@ function buildDataUpdatedEvent({ fields, patch, formId }) {
 /** One `field:updated` per changed key, emitted alongside `data:updated`. */
 function buildFieldUpdatedEvents({ fields, patch, formId }) {
 	const byKey = new Map(fields.map((field) => [field.key, field]));
-	return Object.entries(patch).map(([key, value]) => {
+	return analyticsPatchEntries({
+		fields,
+		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_type: mapFieldUpdatedType(field?.value_type ?? "text"),
 			form_id: formId
 		};
 		if (value !== void 0) event.field_value = value;
@@ -559,7 +665,7 @@ function buildFieldUpdatedEvents({ fields, patch, formId }) {
 * values passes through.
 */
 function normalizeExclusiveSelection({ next, previous, options }) {
-	const exclusive = new Set(options.filter((option) => option.exclusive === true).map((option) => option.value));
+	const exclusive = new Set(options.filter((option) => option.exclusive === true).map((option) => option.key));
 	if (exclusive.size === 0) return next;
 	const previousValues = new Set(previous);
 	const added = next.filter((entry) => !previousValues.has(entry));
@@ -577,7 +683,8 @@ const FIELD_TYPES = [
 	"boolean",
 	"select",
 	"multiselect",
-	"json"
+	"json",
+	"file"
 ];
 const VALIDATION_RULES = [
 	"required",
@@ -587,17 +694,29 @@ const VALIDATION_RULES = [
 	"max",
 	"pattern",
 	"oneOf",
+	"accept",
+	"maxSize",
 	"custom"
 ];
 const NUMERIC_RULES = [
 	"minLength",
 	"maxLength",
 	"min",
-	"max"
+	"max",
+	"maxSize"
+];
+const FILE_ONLY_RULES = ["accept", "maxSize"];
+const FIELD_CLASSIFICATIONS = [
+	"user_input",
+	"computed",
+	"local_only"
 ];
-const OPTION_KEYS = [
-	"value",
-	"label",
+const SNAKE_CASE_FIELD_KEY = /^[a-z][a-z0-9_]*$/;
+/** Keys allowed on a raw option object before normalization. */
+const OPTION_INPUT_KEYS = [
+	"key",
+	"display_text",
+	"display_description",
 	"exclusive"
 ];
 /** The two field types whose choices are declared through a field-level `options`. */
@@ -633,82 +752,148 @@ function validateAndCompile({ schema }) {
 	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();
+	const compiledFields = [];
 	fields.forEach((field, index) => {
-		validateField({
+		compiledFields.push(compileField({
 			field,
 			path: `schema.fields[${index}]`,
 			seenKeys,
 			patterns
-		});
+		}));
 	});
 	return {
 		formKey,
-		fields: [...fields],
+		fields: compiledFields,
 		patterns
 	};
 }
-function validateField({ field, path, seenKeys, patterns }) {
+function compileField({ field, path, seenKeys, patterns }) {
 	if (!isObjectLike(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 (!SNAKE_CASE_FIELD_KEY.test(key)) throw new SchemaError(`${path}.key: must be lowercase snake_case`);
 	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(", ")}`);
+	if (field["type"] !== void 0) throw new SchemaError(`${path}.type: is not supported; use value_type`);
+	const valueTypeRaw = field["value_type"];
+	if (typeof valueTypeRaw !== "string" || valueTypeRaw.trim() === "") throw new SchemaError(`${path}.value_type: must be a non-empty string`);
+	const valueType = valueTypeRaw;
+	if (!FIELD_TYPES.includes(valueType)) throw new SchemaError(`${path}.value_type: must be one of ${FIELD_TYPES.join(", ")}`);
+	const displayText = field["display_text"];
+	if (displayText !== void 0) {
+		if (typeof displayText !== "string" || displayText.trim() === "") throw new SchemaError(`${path}.display_text: must be a non-empty string`);
+	}
+	const displayDescription = field["display_description"];
+	if (displayDescription !== void 0) {
+		if (typeof displayDescription !== "string" || displayDescription.trim() === "") throw new SchemaError(`${path}.display_description: must be a non-empty string`);
+	}
+	const fieldTypeRaw = field["field_type"];
+	let fieldType = "user_input";
+	if (fieldTypeRaw !== void 0) {
+		if (typeof fieldTypeRaw !== "string" || !FIELD_CLASSIFICATIONS.includes(fieldTypeRaw)) throw new SchemaError(`${path}.field_type: must be one of ${FIELD_CLASSIFICATIONS.join(", ")}`);
+		fieldType = fieldTypeRaw;
+	}
 	const registryId = field["registryId"];
 	if (registryId !== void 0 && typeof registryId !== "string") throw new SchemaError(`${path}.registryId: 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 includeInCookies = field["includeInCookies"];
 	if (includeInCookies !== void 0 && typeof includeInCookies !== "boolean") throw new SchemaError(`${path}.includeInCookies: must be a boolean`);
-	validateOptions({
+	const normalizedOptions = normalizeOptions({
 		field,
-		type,
+		valueType,
 		path
 	});
 	const validations = field["validations"];
-	if (validations === void 0) return;
-	validateValidations({
-		validations,
-		type,
-		path: `${path}.validations`
-	});
-	if (!isObjectLike(validations)) return;
-	const pattern = validations["pattern"];
-	if (typeof pattern !== "string") return;
-	patterns.set(key, compilePattern({
-		pattern,
-		path: `${path}.validations.pattern`
-	}));
+	if (validations !== void 0) {
+		validateValidations({
+			validations,
+			type: valueType,
+			path: `${path}.validations`
+		});
+		if (isObjectLike(validations)) {
+			const pattern = validations["pattern"];
+			if (typeof pattern === "string") patterns.set(key, compilePattern({
+				pattern,
+				path: `${path}.validations.pattern`
+			}));
+		}
+	}
+	const compiled = {
+		...field,
+		key,
+		label,
+		value_type: valueType
+	};
+	delete compiled["type"];
+	compiled["field_type"] = fieldType;
+	if (displayText !== void 0) compiled["display_text"] = displayText;
+	if (displayDescription !== void 0) compiled["display_description"] = displayDescription;
+	if (normalizedOptions !== void 0) compiled["options"] = normalizedOptions;
+	if (validations !== void 0) compiled["validations"] = cloneValidations(validations);
+	return compiled;
+}
+function cloneValidations(validations) {
+	if (!isObjectLike(validations)) return validations;
+	const cloned = {};
+	for (const [ruleKey, ruleValue] of Object.entries(validations)) {
+		if (ruleKey === "custom") {
+			cloned[ruleKey] = ruleValue;
+			continue;
+		}
+		if (ruleKey === "oneOf" || ruleKey === "accept") {
+			cloned[ruleKey] = Array.isArray(ruleValue) ? [...ruleValue] : ruleValue;
+			continue;
+		}
+		cloned[ruleKey] = ruleValue;
+	}
+	return cloned;
 }
-function validateOptions({ field, type, path }) {
+function normalizeOptions({ field, valueType, path }) {
 	const options = field["options"];
-	if (options === void 0) return;
-	if (!OPTION_FIELD_TYPES.includes(type)) throw new SchemaError(`${path}.options: only a select or multiselect field may declare options`);
+	if (options === void 0) return void 0;
+	if (!OPTION_FIELD_TYPES.includes(valueType)) throw new SchemaError(`${path}.options: only a select or multiselect field may declare options`);
 	if (!(Array.isArray(options) && options.length > 0)) throw new SchemaError(`${path}.options: must be a non-empty array`);
 	const entries = options;
-	const seenValues = /* @__PURE__ */ new Set();
+	const seenKeys = /* @__PURE__ */ new Set();
+	const normalized = [];
 	entries.forEach((option, index) => {
 		const at = `${path}.options[${index}]`;
 		if (!isObjectLike(option)) throw new SchemaError(`${at}: must be an object`);
-		for (const optionKey of Object.keys(option)) if (!OPTION_KEYS.includes(optionKey)) throw new SchemaError(`${at}.${optionKey}: unknown option key; expected one of ${OPTION_KEYS.join(", ")}`);
-		const value = option["value"];
-		if (typeof value !== "string" || value.trim() === "") throw new SchemaError(`${at}.value: must be a non-empty string`);
-		const label = option["label"];
-		if (label !== void 0 && typeof label !== "string") throw new SchemaError(`${at}.label: must be a string`);
+		for (const optionKey of Object.keys(option)) if (!OPTION_INPUT_KEYS.includes(optionKey)) throw new SchemaError(`${at}.${optionKey}: unknown option key; expected one of ${OPTION_INPUT_KEYS.join(", ")}`);
+		const optionKey = option["key"];
+		const displayTextRaw = option["display_text"];
+		const displayDescription = option["display_description"];
+		if (typeof optionKey !== "string" || optionKey.trim() === "") throw new SchemaError(`${at}.key: must be a non-empty string`);
+		if (typeof displayTextRaw !== "string" || displayTextRaw.trim() === "") throw new SchemaError(`${at}.display_text: must be a non-empty string`);
+		const key = optionKey;
+		const displayText = displayTextRaw;
+		if (displayDescription !== void 0) {
+			if (typeof displayDescription !== "string" || displayDescription.trim() === "") throw new SchemaError(`${at}.display_description: must be a non-empty string`);
+		}
 		const exclusive = option["exclusive"];
 		if (exclusive !== void 0 && typeof exclusive !== "boolean") throw new SchemaError(`${at}.exclusive: must be a boolean`);
-		if (exclusive === true && type === "select") throw new SchemaError(`${at}.exclusive: only a multiselect field may declare an exclusive option`);
-		if (seenValues.has(value)) throw new SchemaError(`${at}.value: duplicate option value "${value}" on this field`);
-		seenValues.add(value);
+		if (exclusive !== void 0 && valueType === "select") throw new SchemaError(`${at}.exclusive: only a multiselect field may declare an exclusive option`);
+		if (seenKeys.has(key)) throw new SchemaError(`${at}.key: duplicate option key "${key}" on this field`);
+		seenKeys.add(key);
+		normalized.push({
+			key,
+			display_text: displayText,
+			...displayDescription === void 0 ? {} : { display_description: displayDescription },
+			...exclusive === void 0 ? {} : { exclusive }
+		});
 	});
+	return normalized;
 }
 function validateValidations({ validations, type, path }) {
 	if (!isObjectLike(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(", ")}`);
+	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(", ")}`);
+		if (type !== "file" && FILE_ONLY_RULES.includes(rule)) throw new SchemaError(`${path}.${rule}: is only valid for file fields`);
+	}
 	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) {
@@ -724,6 +909,10 @@ function validateValidations({ validations, type, path }) {
 	const oneOf = validations["oneOf"];
 	if (oneOf !== void 0 && OPTION_FIELD_TYPES.includes(type)) throw new SchemaError(`${path}.oneOf: not allowed on a ${type} field; declare choices through the field's options instead`);
 	if (oneOf !== void 0 && !(Array.isArray(oneOf) && oneOf.length > 0)) throw new SchemaError(`${path}.oneOf: must be a non-empty array`);
+	const accept = validations["accept"];
+	if (accept !== void 0 && !(Array.isArray(accept) && accept.length > 0 && accept.every((entry) => typeof entry === "string" && entry.trim() !== ""))) throw new SchemaError(`${path}.accept: must be a non-empty array of strings`);
+	const maxSize = validations["maxSize"];
+	if (maxSize !== void 0 && !(typeof maxSize === "number" && Number.isFinite(maxSize) && maxSize > 0)) throw new SchemaError(`${path}.maxSize: must be a positive finite number`);
 	const pattern = validations["pattern"];
 	if (pattern !== void 0 && typeof pattern !== "string") throw new SchemaError(`${path}.pattern: must be a string`);
 	const custom = validations["custom"];
@@ -957,16 +1146,22 @@ function resolveInitConfig({ core, customValidations, serverFormData }) {
 	}
 	return registry;
 }
-function createFormsClient({ core, customValidations, serverFormData, analyticsInstance, baseUrl, storage, persistence }) {
+function createFormsClient({ core, customValidations, serverFormData, analyticsInstance, baseUrl, fetch: fetchImpl, storage, persistence }) {
 	if (!hasRequiredCoreMethods(core)) throw new FormsError("initForms requires an initialized Embeddables core instance.");
 	const registry = resolveInitConfig({
 		core,
 		customValidations,
 		serverFormData
 	});
+	const uploadConfig = resolvePersistenceConfig({
+		core,
+		baseUrl,
+		fetch: fetchImpl
+	});
 	const resolvedPersistence = persistence ?? resolveDefaultPersistence({
 		core,
-		baseUrl
+		baseUrl,
+		fetch: fetchImpl
 	});
 	const instances = /* @__PURE__ */ new Map();
 	return { getForm({ formId }) {
@@ -978,6 +1173,7 @@ function createFormsClient({ core, customValidations, serverFormData, analyticsI
 			analyticsInstance,
 			storage,
 			persistence: resolvedPersistence,
+			uploadConfig,
 			schema: entry.schema,
 			customValidations: entry.customValidations,
 			serverFormData: entry.serverFormData,
@@ -994,7 +1190,7 @@ function mergeInitialBag({ fromStorage, serverFormData }) {
 		...serverFormData
 	};
 }
-function createFormInstance({ analyticsInstance, storage, persistence, schema, customValidations, serverFormData, projectId }) {
+function createFormInstance({ analyticsInstance, storage, persistence, uploadConfig, schema, customValidations, serverFormData, projectId }) {
 	const resolved = resolveForm({ schema: mergeCustomValidations({
 		schema,
 		customValidations
@@ -1100,7 +1296,7 @@ function createFormInstance({ analyticsInstance, storage, persistence, schema, c
 		const previousBag = readBag();
 		for (const [key, value] of Object.entries(changes)) {
 			const field = declared.get(key);
-			if (!field || field.type !== "multiselect" || !field.options) continue;
+			if (!field || field.value_type !== "multiselect" || !field.options) continue;
 			if (!Array.isArray(value) || !value.every((entry) => typeof entry === "string")) continue;
 			const stored = previousBag[key];
 			changes[key] = [...normalizeExclusiveSelection({
@@ -1186,15 +1382,22 @@ function createFormInstance({ analyticsInstance, storage, persistence, schema, c
 			ok: true,
 			errors: noErrors()
 		});
-		return analyticsInstance.trackEvent([buildDataUpdatedEvent({
+		const dataUpdated = buildDataUpdatedEvent({
 			fields: resolved.fields,
 			patch: changes,
 			formId: schema.id
-		}), ...buildFieldUpdatedEvents({
+		});
+		const fieldUpdated = buildFieldUpdatedEvents({
 			fields: resolved.fields,
 			patch: changes,
 			formId: schema.id
-		})]).then(() => ({
+		});
+		const analyticsEvents = [...Object.keys(dataUpdated.data).length > 0 ? [dataUpdated] : [], ...fieldUpdated];
+		if (analyticsEvents.length === 0) return Promise.resolve({
+			ok: true,
+			errors: noErrors()
+		});
+		return analyticsInstance.trackEvent(analyticsEvents).then(() => ({
 			ok: true,
 			errors: noErrors()
 		})).catch((error) => ({
@@ -1228,6 +1431,11 @@ function createFormInstance({ analyticsInstance, storage, persistence, schema, c
 		return get(fieldKey);
 	});
 	const getAll = () => narrow(state.bag);
+	const getFieldByKey = (key) => {
+		const fieldKey = key;
+		if (!declared.has(fieldKey)) return void 0;
+		return declared.get(fieldKey);
+	};
 	const submit = () => {
 		const snapshot = narrow(readBag());
 		const values = snapshot;
@@ -1370,16 +1578,39 @@ function createFormInstance({ analyticsInstance, storage, persistence, schema, c
 			listeners.delete(listener);
 		};
 	};
+	const uploadFile = async ({ key, file, fileName }) => {
+		const field = declared.get(key);
+		if (!field) throw new FormsError(`Unknown field: ${key}`);
+		if (field.value_type !== "file") throw new FormsError(`Field "${key}" is not a file field`);
+		if (!uploadConfig) throw new FormsError("File uploads require a valid publishable key and initialized Embeddables core instance.");
+		const rules = field.validations;
+		const contentType = file.type || "application/octet-stream";
+		const byteLength = file.size;
+		if (byteLength > 26214400) throw new FormsError("Maximum upload size is 25 MiB.");
+		if (rules?.maxSize !== void 0 && byteLength > rules.maxSize) throw new FormsError(`${field.label} must be at most ${rules.maxSize} bytes`);
+		if (rules?.accept !== void 0 && !contentTypeMatchesAccept({
+			contentType,
+			accept: rules.accept
+		})) throw new FormsError(`${field.label} must be one of the allowed file types`);
+		return uploadFormFile(uploadConfig, {
+			formId: resolved.formKey,
+			fieldKey: key,
+			file,
+			fileName
+		});
+	};
 	return {
 		key: schema.id,
 		set,
 		get,
+		getFieldByKey,
 		getValueByProtocolFieldId,
 		getAll,
 		submit,
 		validate,
 		errors: () => freeze(state.errors),
 		clear,
+		uploadFile,
 		subscribe
 	};
 }
@@ -1439,4 +1670,4 @@ Object.defineProperty(exports, "seedServerFormsStorageFromCookies", {
 	}
 });
 
-//# sourceMappingURL=form-BOHdxeuO.cjs.map
+//# sourceMappingURL=form-lmr-O7j7.cjs.map