@embeddables/forms 0.2.1 → 0.3.0

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

@@ -72,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`);
@@ -87,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`);
 			}
 		}
@@ -101,7 +101,7 @@ 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.type === "file" && isFormFileRef(value)) {
+	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({
@@ -223,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 }
@@ -305,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 }
@@ -325,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;
@@ -589,9 +589,22 @@ async function uploadFormFile(config, input) {
 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
@@ -604,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({
@@ -622,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;
@@ -645,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));
@@ -686,9 +706,17 @@ const NUMERIC_RULES = [
 	"maxSize"
 ];
 const FILE_ONLY_RULES = ["accept", "maxSize"];
-const OPTION_KEYS = [
-	"value",
-	"label",
+const FIELD_CLASSIFICATIONS = [
+	"user_input",
+	"computed",
+	"local_only"
+];
+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`. */
@@ -724,78 +752,141 @@ 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`);
@@ -1205,7 +1296,7 @@ function createFormInstance({ analyticsInstance, storage, persistence, uploadCon
 		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({
@@ -1291,15 +1382,22 @@ function createFormInstance({ analyticsInstance, storage, persistence, uploadCon
 			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) => ({
@@ -1333,6 +1431,11 @@ function createFormInstance({ analyticsInstance, storage, persistence, uploadCon
 		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;
@@ -1478,7 +1581,7 @@ function createFormInstance({ analyticsInstance, storage, persistence, uploadCon
 	const uploadFile = async ({ key, file, fileName }) => {
 		const field = declared.get(key);
 		if (!field) throw new FormsError(`Unknown field: ${key}`);
-		if (field.type !== "file") throw new FormsError(`Field "${key}" is not a file field`);
+		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";
@@ -1500,6 +1603,7 @@ function createFormInstance({ analyticsInstance, storage, persistence, uploadCon
 		key: schema.id,
 		set,
 		get,
+		getFieldByKey,
 		getValueByProtocolFieldId,
 		getAll,
 		submit,
@@ -1566,4 +1670,4 @@ Object.defineProperty(exports, "seedServerFormsStorageFromCookies", {
 	}
 });
 
-//# sourceMappingURL=form-CdIfHqNc.cjs.map
+//# sourceMappingURL=form-lmr-O7j7.cjs.map