@embeddables/forms 0.2.0 → 0.2.1

package/README.md

@@ -27,7 +27,7 @@ Example:
 ```tsx
 import { EmbeddablesProvider } from '@embeddables/core/react'
 import { analytics } from '@embeddables/analytics/react'
-import { forms, useForm, useFormField } from '@embeddables/forms/react'
+import { forms, useForm, useFormField, useFormFileUpload } from '@embeddables/forms/react'
 import { config } from './embeddables/_dist/config.ts'
 
 function SignupField() {
@@ -85,6 +85,35 @@ export function App() {
 - One live `FormInstance` per `schema.id` is shared across hooks in the same client.
 - Imperative consumers can also call `form.subscribe(listener)` to observe value and error changes.
 
+### File inputs
+
+For `type: file` fields, use `useFormFileUpload`. It uploads through the publishable-key API, commits the returned `FormFileRef`, and exposes `inputProps` for a native `<input type="file">`.
+
+Example:
+
+```tsx
+function IdPhotoField() {
+  const { form } = useForm({ formId: 'intake' })
+  const { value, error, isLoading, uploadError, inputProps } = useFormFileUpload({
+    form,
+    key: 'id_photo',
+  })
+
+  return (
+    <label>
+      ID photo
+      <input {...inputProps} accept="image/jpeg,image/png" />
+      {isLoading && <span>Uploading…</span>}
+      {uploadError && <span>{uploadError}</span>}
+      {error?.[0]}
+      {value?.name && <span>{value.name}</span>}
+    </label>
+  )
+}
+```
+
+Imperative equivalent: `const ref = await form.uploadFile({ key: 'id_photo', file })` then `await form.set({ id_photo: ref })`.
+
 ## Quick start
 
 ```typescript
@@ -127,10 +156,15 @@ from `embeddables/_dist` are already typed.
 ## Schema
 
 Each form is one object: `id`, optional `name`, and `fields`. Supported field
-types: `text`, `email`, `number`, `boolean`, `select`, `multiselect`, `json`.
+types: `text`, `email`, `number`, `boolean`, `select`, `multiselect`, `json`,
+`file`.
 
 Declarative rules: `required`, `minLength`, `maxLength`, `min`, `max`,
-`pattern`, `oneOf`, and optional synchronous `validations.custom`.
+`pattern`, `oneOf`, and optional synchronous `validations.custom`. File fields
+also accept `validations.accept` (MIME list) and `validations.maxSize` (bytes).
+Compatible field types may declare `protocolFieldId` to link a form field to a
+protocol question. `json` fields cannot. `FormFileRef` is exported for typed
+file values.
 
 A `select` or `multiselect` field declares its choices in a field-level `options`
 array of `{ value, label?, exclusive? }`, and the field's `type` — not the name of
@@ -159,6 +193,7 @@ on `initForms` / `forms()`.
 | `getValueByProtocolFieldId(protocolFieldId)` | Read by schema `protocolFieldId` (typed like `get()` for the backing field; `undefined` if unknown or unset) |
 | `validate({ … })` | Check values without writing or tracking |
 | `submit()` | Validate all fields, best-effort durable R2 write, and emit `form:submitted` when analytics is configured |
+| `uploadFile({ key, file, fileName? })` | Upload bytes for a `type: file` field; returns `FormFileRef` (caller commits with `.set()`) |
 | `errors()` | Current validation messages |
 | `clear()` | Remove this form's stored values |
 

package/dist/{form-Bt5pwVP6.js → form-7wmC3G_q.js}

@@ -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])?)*$/;
 /**
@@ -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.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 }) {
@@ -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) => 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,6 +523,67 @@ 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;
@@ -577,7 +663,8 @@ const FIELD_TYPES = [
 	"boolean",
 	"select",
 	"multiselect",
-	"json"
+	"json",
+	"file"
 ];
 const VALIDATION_RULES = [
 	"required",
@@ -587,14 +674,18 @@ 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 OPTION_KEYS = [
 	"value",
 	"label",
@@ -708,7 +799,10 @@ function validateOptions({ field, type, path }) {
 }
 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 +818,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 +1055,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 +1082,7 @@ function createFormsClient({ core, customValidations, serverFormData, analyticsI
 			analyticsInstance,
 			storage,
 			persistence: resolvedPersistence,
+			uploadConfig,
 			schema: entry.schema,
 			customValidations: entry.customValidations,
 			serverFormData: entry.serverFormData,
@@ -994,7 +1099,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
@@ -1370,6 +1475,27 @@ 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.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,
@@ -1380,10 +1506,11 @@ function createFormInstance({ analyticsInstance, storage, persistence, schema, c
 		validate,
 		errors: () => freeze(state.errors),
 		clear,
+		uploadFile,
 		subscribe
 	};
 }
 //#endregion
 export { FORM_DATA_KEY as a, SchemaError as c, seedServerFormsStorageFromCookies as i, ValidatorError as l, initForms as n, createMemoryFormsStorage as o, createNoopPersistence as r, FormsError as s, createFormsClient as t };
 
-//# sourceMappingURL=form-Bt5pwVP6.js.map
+//# sourceMappingURL=form-7wmC3G_q.js.map