@embeddables/forms 0.0.5 → 0.2.1

package/dist/{index-qfBhdk5L.d.ts → form-x4EJcR9A.d.ts}

@@ -1,27 +1,4 @@
 import { EmbeddablesInstance } from "@embeddables/core";
-//#region src/errors.d.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. */
-declare class FormsError extends Error {
-  constructor(message: string, options?: ErrorOptions);
-}
-/** The schema is malformed. */
-declare class SchemaError extends FormsError {
-  constructor(message: string, options?: ErrorOptions);
-}
-/** A custom validator returned a thenable, or a shape that is not a message. */
-declare class ValidatorError extends FormsError {
-  constructor(message: string, options?: ErrorOptions);
-}
-//#endregion
 //#region ../shared-types/dist/json.types.d.ts
 /**
  * Recursive JSON value, compatible with JSONB column values and public
@@ -31,8 +8,54 @@ type JsonValue = string | number | boolean | null | JsonValue[] | {
   [key: string]: JsonValue;
 };
 //#endregion
+//#region ../shared-types/dist/analytics-instance.types.d.ts
+/**
+ * Hono-free analytics client surface other SDKs accept without depending on
+ * `hono` or `@embeddables/analytics`. Precise ingest event types stay inferred
+ * from the Worker in analytics-sdk; this module is the structural instance, not
+ * the HTTP contract.
+ *
+ * `trackEvent` is a method (not a function property) so parameter checking
+ * stays bivariant: a precise analytics-sdk client remains assignable here, and
+ * callers without those types can still pass their payloads.
+ */
+/** Loose event payload other SDKs pass to `trackEvent`. */
+interface AnalyticsTrackEvent {
+  event_name: string;
+  [key: string]: unknown;
+}
+/** Body `trackEvent` resolves with — identity plus ingest outcome. */
+interface AnalyticsTrackResult {
+  app_user_id: string;
+  accepted: number;
+  forwarded: boolean;
+}
+/**
+ * Structural stand-in for `ReturnType<typeof initAnalytics>`. Other SDKs type
+ * injected clients against this; analytics-sdk's `AnalyticsClient` must remain
+ * assignable to it.
+ */
+interface AnalyticsInstance<TEvent = AnalyticsTrackEvent> {
+  trackEvent(input: TEvent | readonly TEvent[]): Promise<AnalyticsTrackResult>;
+  /** Live identity: the composed core instance's current user. */
+  getAppUserId(): string | null;
+  getProjectId(): string;
+}
+//#endregion
+//#region ../shared-types/dist/forms.types.d.ts
+/** Stored field value for `type: file` — bytes live in R2; JSON carries metadata only. */
+type FormFileRef = {
+  file_id: string;
+  name: string;
+  content_type: string;
+  size: number;
+  status: 'uploading' | 'done' | 'error';
+  uploaded_at?: string;
+  error?: string;
+} & Record<string, JsonValue>;
+//#endregion
 //#region src/core/config.d.ts
-type FieldType = 'text' | 'email' | 'number' | 'boolean' | 'select' | 'multiselect' | 'json';
+type FieldType = 'text' | 'email' | 'number' | 'boolean' | 'select' | 'multiselect' | 'json' | 'file';
 /** Runtime `type` literal → the TypeScript type of that field's value. */
 interface ValueOfFieldType {
   text: string;
@@ -42,22 +65,43 @@ interface ValueOfFieldType {
   select: string;
   multiselect: string[];
   json: JsonValue;
+  file: FormFileRef | null;
 }
 type FieldValidator<TValue extends JsonValue = JsonValue> = (args: {
   value: TValue;
   values: Readonly<Record<string, JsonValue>>;
 }) => string | readonly string[] | null;
+/** One declarable choice on a `select` or `multiselect` field. */
+interface FieldOption {
+  readonly value: string;
+  readonly label?: string;
+  /**
+   * `multiselect` only. A selected exclusive option cannot coexist with any
+   * other value: selecting it clears the rest, and selecting a regular
+   * option clears it.
+   */
+  readonly exclusive?: boolean;
+}
+type SelectFieldOption = Omit<FieldOption, 'exclusive'> & {
+  readonly exclusive?: never;
+};
 interface FieldValidationsFor<TType extends FieldType> {
   readonly required?: boolean;
   readonly minLength?: number;
   readonly maxLength?: number;
   readonly min?: number;
   readonly max?: number;
-  /** ECMAScript source without delimiters. */
+  /**
+   * ECMAScript source without delimiters. Flags go in an optional leading
+   * `(?flags)` prefix, e.g. `'(?u)^\\p{L}+$'`. Allowed: `dgimsuvy`; `g` and
+   * `y` are stripped before compilation.
+   */
   readonly pattern?: string;
-  /** Flags for `pattern`. `g` and `y` are stripped before compilation. */
-  readonly patternFlags?: string;
   readonly oneOf?: readonly JsonValue[];
+  /** MIME types or `type/*` wildcards. */
+  readonly accept?: TType extends 'file' ? readonly string[] : never;
+  /** Max bytes. */
+  readonly maxSize?: TType extends 'file' ? number : never;
   /** `value` is bound to this field's declared `type`. */
   readonly custom?: FieldValidator<ValueOfFieldType[TType]>;
 }
@@ -65,9 +109,16 @@ interface FieldConfigFor<TType extends FieldType> {
   readonly key: string;
   readonly label: string;
   readonly type: TType;
+  /**
+   * Declarable choices. `select` accepts one of these values, `multiselect`
+   * accepts any number of them. Typed as `never` on every other field type.
+   */
+  readonly options?: TType extends 'select' ? readonly SelectFieldOption[] : TType extends 'multiselect' ? readonly FieldOption[] : never;
   readonly validations?: FieldValidationsFor<TType>;
   readonly registryId?: string;
   readonly protocolFieldId?: string;
+  /** When true, the field value is persisted to a per-form browser cookie on `set`. */
+  readonly includeInCookies?: boolean;
 }
 type FieldConfig = { [T in FieldType]: FieldConfigFor<T>; }[FieldType];
 type FieldValidations = { [T in FieldType]: FieldValidationsFor<T>; }[FieldType];
@@ -84,90 +135,6 @@ type ProtocolFieldId<TSchema extends FormSchema> = [TSchema] extends [FormSchema
   protocolFieldId: string;
 }>['protocolFieldId'];
 //#endregion
-//#region src/storage/storage.d.ts
-/** Every form on the origin shares this one entry, indexed by form ID. */
-declare const FORM_DATA_KEY = "EMBEDDABLES-FORM-DATA";
-interface FormsStorage {
-  getItem(key: string): string | null;
-  setItem(key: string, value: string): void;
-  removeItem(key: string): void;
-}
-//#endregion
-//#region ../shared-types/dist/analytics-instance.types.d.ts
-/**
- * Hono-free analytics client surface other SDKs accept without depending on
- * `hono` or `@embeddables/analytics`. Precise ingest event types stay inferred
- * from the Worker in analytics-sdk; this module is the structural instance, not
- * the HTTP contract.
- *
- * `trackEvent` is a method (not a function property) so parameter checking
- * stays bivariant: a precise analytics-sdk client remains assignable here, and
- * callers without those types can still pass their payloads.
- */
-/** Loose event payload other SDKs pass to `trackEvent`. */
-interface AnalyticsTrackEvent {
-  event_name: string;
-  [key: string]: unknown;
-}
-/** Body `trackEvent` resolves with — identity plus ingest outcome. */
-interface AnalyticsTrackResult {
-  app_user_id: string;
-  accepted: number;
-  forwarded: boolean;
-}
-/**
- * Structural stand-in for `ReturnType<typeof initAnalytics>`. Other SDKs type
- * injected clients against this; analytics-sdk's `AnalyticsClient` must remain
- * assignable to it.
- */
-interface AnalyticsInstance<TEvent = AnalyticsTrackEvent> {
-  trackEvent(input: TEvent | readonly TEvent[]): Promise<AnalyticsTrackResult>;
-  /** Live identity: the composed core instance's current user. */
-  getAppUserId(): string | null;
-  getProjectId(): string;
-}
-//#endregion
-//#region ../shared-types/dist/analytics-ingest.types.d.ts
-type FieldUpdatedType = 'text' | 'email' | 'number' | 'boolean' | 'select' | 'multiselect' | 'json';
-/**
- * Raw `field_value` accepted by ingest. Every forms-sdk `ValueOfFieldType` is a
- * JSON value — scalar (`text`/`email`/`select` → string, `number` → number,
- * `boolean` → boolean), `multiselect` → `string[]`, `json` → arbitrary JSON —
- * so the contract collapses to `JsonValue`; the runtime ingest schema is what
- * bounds each shape.
- */
-type FieldUpdatedValue = JsonValue;
-type FunnelStepFields = {
-  is_funnel_step?: boolean;
-  funnel_step_label?: string;
-};
-type FieldUpdatedEvent = FunnelStepFields & {
-  event_name: 'field:updated';
-  /** Schema key of the updated field. */
-  field_key: string;
-  field_type: FieldUpdatedType;
-  field_value?: FieldUpdatedValue;
-  /** Field Registry identifier when the field is registry-backed. */
-  registry_field_id?: string;
-  /** Protocol question identifier when the field is protocol-backed. */
-  protocol_field_id?: string;
-};
-type DataUpdatedEntry = {
-  value: string;
-  label: string;
-};
-type DataUpdatedEvent = FunnelStepFields & {
-  event_name: 'data:updated';
-  data: Record<string, DataUpdatedEntry>;
-};
-type FormSubmittedEvent = FunnelStepFields & {
-  event_name: 'form:submitted';
-  form_key: string;
-};
-//#endregion
-//#region src/core/analytics.d.ts
-type FormsAnalyticsEvent = DataUpdatedEvent | FieldUpdatedEvent | FormSubmittedEvent;
-//#endregion
 //#region src/core/form.d.ts
 /** Per-key validation errors. An empty object means the operation succeeded. */
 type FieldErrors<TSchema extends FormSchema> = Readonly<Partial<Record<FormFieldKey<TSchema>, readonly string[]>>>;
@@ -229,16 +196,43 @@ interface FormInstance<TSchema extends FormSchema> {
   validate(patch?: Partial<FormValues<TSchema>>): Promise<ValidateResult<TSchema>>;
   errors(): FieldErrors<TSchema>;
   clear(): void;
+  /**
+   * Uploads a file for a declared `type: file` field. Returns a `FormFileRef`
+   * with `status: 'done'`; the caller commits it with `.set()`.
+   */
+  uploadFile(args: {
+    key: FormFieldKey<TSchema>;
+    file: Blob;
+    fileName?: string;
+  }): Promise<FormFileRef>;
   /** Synchronous listener for value and error mutations. Returns an unsubscribe function. */
   subscribe(listener: () => void): () => void;
 }
 /** Every form the app can open, keyed by form id — the shape `_dist` exports. */
 type FormSchemaMap = Readonly<Record<string, FormSchema>>;
 type CustomValidationsFor<TSchema extends FormSchema> = { readonly [K in FormFieldKey<TSchema>]?: FieldValidator; };
+interface FormCustomValidationsEntry<TSchema extends FormSchema = FormSchema> {
+  formId: Extract<TSchema['id'], string>;
+  customValidations: CustomValidationsFor<TSchema>;
+}
+/** Per-form SSR/hydration seed passed from `initFormsServer().getServerFormData()`. */
+interface FormServerDataEntry<TSchema extends FormSchema = FormSchema> {
+  formId: Extract<TSchema['id'], string>;
+  serverFormData: Partial<FormValues<TSchema>>;
+}
+type FormCustomValidationsEntriesFor<TSchemas extends FormSchemaMap> = ReadonlyArray<{ [K in keyof TSchemas & string]: FormCustomValidationsEntry<TSchemas[K]>; }[keyof TSchemas & string]>;
+type FormServerDataEntriesFor<TSchemas extends FormSchemaMap> = ReadonlyArray<{ [K in keyof TSchemas & string]: FormServerDataEntry<TSchemas[K]>; }[keyof TSchemas & string]>;
+interface FormsServerInitOptions<TSchemas extends FormSchemaMap = FormSchemaMap> {
+  server: EmbeddablesInstance;
+  customValidations?: FormCustomValidationsEntriesFor<TSchemas>;
+  analyticsInstance?: AnalyticsInstance;
+}
+type ServerFormInstance<TSchema extends FormSchema> = Pick<FormInstance<TSchema>, 'key' | 'set' | 'get' | 'getAll' | 'getValueByProtocolFieldId'>;
+type ServerFormDataByFormId<TSchemas extends FormSchemaMap> = { [K in keyof TSchemas]?: Partial<FormValues<TSchemas[K]>>; };
 interface InitFormsOptions<TSchemas extends FormSchemaMap = FormSchemaMap> {
   core: EmbeddablesInstance;
-  /** Keyed by form id; each schema's own `id` must equal its key. */
-  schemas: TSchemas;
+  customValidations?: FormCustomValidationsEntriesFor<TSchemas>;
+  serverFormData?: FormServerDataEntriesFor<TSchemas>;
   analyticsInstance?: AnalyticsInstance;
 }
 interface FormsClient<TSchemas extends FormSchemaMap = FormSchemaMap> {
@@ -250,20 +244,18 @@ interface FormsClient<TSchemas extends FormSchemaMap = FormSchemaMap> {
    * would not observe each other's writes and the later one's `.set()` would
    * overwrite the earlier one's storage, so the client never hands out a second.
    *
-   * ! `customValidations` therefore belong to the first call. A later call that
-   * ! passes different validators gets the instance that already exists, built
-   * ! with the original ones.
+   * ! `customValidations` belong to the matching form id on Core. `getForm`
+   * ! only selects which memoized instance to return.
    */
   getForm<K extends keyof TSchemas & string>(params: {
     formId: K;
-    customValidations?: CustomValidationsFor<TSchemas[K]>;
   }): FormInstance<TSchemas[K]>;
 }
 /**
- * Validates the core instance and the schema map once, then returns a client
- * whose `getForm` builds each form by id.
+ * Validates the core instance and registered form schemas once, then returns a
+ * client whose `getForm` builds each form by id.
  */
-declare function initForms<const TSchemas extends FormSchemaMap>(options: InitFormsOptions<TSchemas>): FormsClient<TSchemas>;
+declare function initForms<TSchemas extends FormSchemaMap = FormSchemaMap>(options: InitFormsOptions<TSchemas>): FormsClient<TSchemas>;
 //#endregion
-export { FormsError as A, FieldValidations as C, FormValues as D, FormSchema as E, ValidatorError as M, ProtocolFieldId as O, FieldType as S, FormFieldKey as T, AnalyticsTrackEvent as _, FormsClient as a, FormsStorage as b, SubmitResult as c, FormsAnalyticsEvent as d, DataUpdatedEvent as f, AnalyticsInstance as g, FormSubmittedEvent as h, FormSchemaMap as i, SchemaError as j, JsonValue as k, ValidateResult as l, FieldUpdatedType as m, FieldErrors as n, InitFormsOptions as o, FieldUpdatedEvent as p, FormInstance as r, SetResult as s, CustomValidationsFor as t, initForms as u, AnalyticsTrackResult as v, FieldValidator as w, FieldConfig as x, FORM_DATA_KEY as y };
-//# sourceMappingURL=index-qfBhdk5L.d.ts.map
+export { JsonValue as A, FormValues as C, AnalyticsInstance as D, FormFileRef as E, AnalyticsTrackEvent as O, FormSchema as S, SelectFieldOption as T, FieldOption as _, FormSchemaMap as a, FieldValidator as b, FormsServerInitOptions as c, ServerFormInstance as d, SetResult as f, FieldConfig as g, initForms as h, FormInstance as i, AnalyticsTrackResult as k, InitFormsOptions as l, ValidateResult as m, FieldErrors as n, FormServerDataEntry as o, SubmitResult as p, FormCustomValidationsEntry as r, FormsClient as s, CustomValidationsFor as t, ServerFormDataByFormId as u, FieldType as v, ProtocolFieldId as w, FormFieldKey as x, FieldValidations as y };
+//# sourceMappingURL=form-x4EJcR9A.d.ts.map

package/dist/form-x4EJcR9A.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"form-x4EJcR9A.d.ts","names":[],"sources":["../../shared-types/dist/json.types.d.ts","../../shared-types/dist/analytics-instance.types.d.ts","../../shared-types/dist/forms.types.d.ts","../src/core/config.ts","../src/core/form.ts"],"mappings":"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"}

package/dist/index-CmcgIxTH.d.ts

@@ -0,0 +1,78 @@
+import { A as JsonValue } from "./form-x4EJcR9A.js";
+//#region src/errors.d.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. */
+declare class FormsError extends Error {
+  constructor(message: string, options?: ErrorOptions);
+}
+/** The schema is malformed. */
+declare class SchemaError extends FormsError {
+  constructor(message: string, options?: ErrorOptions);
+}
+/** A custom validator returned a thenable, or a shape that is not a message. */
+declare class ValidatorError extends FormsError {
+  constructor(message: string, options?: ErrorOptions);
+}
+//#endregion
+//#region ../shared-types/dist/analytics-ingest.types.d.ts
+type FieldUpdatedType = 'text' | 'email' | 'number' | 'boolean' | 'select' | 'multiselect' | 'json' | 'file';
+/**
+ * Raw `field_value` accepted by ingest. Every forms-sdk `ValueOfFieldType` is a
+ * JSON value — scalar (`text`/`email`/`select` → string, `number` → number,
+ * `boolean` → boolean), `multiselect` → `string[]`, `json` → arbitrary JSON —
+ * so the contract collapses to `JsonValue`; the runtime ingest schema is what
+ * bounds each shape.
+ */
+type FieldUpdatedValue = JsonValue;
+type FunnelStepFields = {
+  is_funnel_step?: boolean;
+  funnel_step_label?: string;
+};
+type FieldUpdatedEvent = FunnelStepFields & {
+  event_name: 'field:updated';
+  /** Schema key of the updated field. */
+  field_key: string;
+  field_type: FieldUpdatedType;
+  field_value?: FieldUpdatedValue;
+  /** Field Registry identifier when the field is registry-backed. */
+  registry_field_id?: string;
+  /** Protocol question identifier when the field is protocol-backed. */
+  protocol_field_id?: string;
+  form_id: string;
+};
+type DataUpdatedEntry = {
+  value: string;
+  label: string;
+};
+type DataUpdatedEvent = FunnelStepFields & {
+  event_name: 'data:updated';
+  data: Record<string, DataUpdatedEntry>;
+  form_id: string;
+};
+type FormSubmittedEvent = FunnelStepFields & {
+  event_name: 'form:submitted';
+  form_key: string;
+};
+//#endregion
+//#region src/storage/storage.d.ts
+/** Every form on the origin shares this one entry, indexed by form ID. */
+declare const FORM_DATA_KEY = "EMBEDDABLES-FORM-DATA";
+interface FormsStorage {
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+  removeItem(key: string): void;
+}
+//#endregion
+//#region src/core/analytics.d.ts
+type FormsAnalyticsEvent = DataUpdatedEvent | FieldUpdatedEvent | FormSubmittedEvent;
+//#endregion
+export { FieldUpdatedEvent as a, FormsError as c, DataUpdatedEvent as i, SchemaError as l, FORM_DATA_KEY as n, FieldUpdatedType as o, FormsStorage as r, FormSubmittedEvent as s, FormsAnalyticsEvent as t, ValidatorError as u };
+//# sourceMappingURL=index-CmcgIxTH.d.ts.map

package/dist/index-CmcgIxTH.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-CmcgIxTH.d.ts","names":[],"sources":["../src/errors.ts","../../shared-types/dist/analytics-ingest.types.d.ts","../src/storage/storage.ts","../src/core/analytics.ts"],"mappings":";;;;;;;;;;;;cAWa,mBAAmB;EAClB,YAAA,iBAAiB,UAAU;;;cAO5B,oBAAoB;EACnB,YAAA,iBAAiB,UAAU;;;cAO5B,uBAAuB;EACtB,YAAA,iBAAiB,UAAU;;;;KCtB7B;;;;;;;;KAQA,oBAAoB;KACpB;EACR;EACA;;KA4CQ,oBAAoB;EAC5B;;EAEA;EACA,YAAY;EACZ,cAAc;;EAEd;;EAEA;EACA;;KAEQ;EACR;EACA;;KAEQ,mBAAmB;EAC3B;EACA,MAAM,eAAe;EACrB;;KAEQ,qBAAqB;EAC7B;EACA;;;;;cC/ES;UAEI;EACf,QAAQ;EACR,QAAQ,aAAa;EACrB,WAAW;;;;KCkBD,sBAAsB,mBAAmB,oBAAoB"}

package/dist/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_form = require("./form-DzfCc5X2.cjs");
+const require_form = require("./form-CdIfHqNc.cjs");
 exports.FORM_DATA_KEY = require_form.FORM_DATA_KEY;
 exports.FormsError = require_form.FormsError;
 exports.SchemaError = require_form.SchemaError;

package/dist/index.d.ts

@@ -1,2 +1,3 @@
-import { A as FormsError, C as FieldValidations, D as FormValues, E as FormSchema, M as ValidatorError, O as ProtocolFieldId, S as FieldType, T as FormFieldKey, _ as AnalyticsTrackEvent, a as FormsClient, b as FormsStorage, c as SubmitResult, d as FormsAnalyticsEvent, f as DataUpdatedEvent, g as AnalyticsInstance, h as FormSubmittedEvent, i as FormSchemaMap, j as SchemaError, k as JsonValue, l as ValidateResult, m as FieldUpdatedType, n as FieldErrors, o as InitFormsOptions, p as FieldUpdatedEvent, r as FormInstance, s as SetResult, t as CustomValidationsFor, u as initForms, v as AnalyticsTrackResult, w as FieldValidator, x as FieldConfig, y as FORM_DATA_KEY } from "./index-qfBhdk5L.js";
-export { type AnalyticsInstance, type AnalyticsTrackEvent, type AnalyticsTrackResult, type CustomValidationsFor, type DataUpdatedEvent, FORM_DATA_KEY, type FieldConfig, type FieldErrors, type FieldType, type FieldUpdatedEvent, type FieldUpdatedType, type FieldValidations, type FieldValidator, type FormFieldKey, type FormInstance, type FormSchema, type FormSchemaMap, type FormSubmittedEvent, type FormValues, type FormsAnalyticsEvent, type FormsClient, FormsError, type FormsStorage, type InitFormsOptions, type JsonValue, type ProtocolFieldId, SchemaError, type SetResult, type SubmitResult, type ValidateResult, ValidatorError, initForms };
+import { a as FieldUpdatedEvent, c as FormsError, i as DataUpdatedEvent, l as SchemaError, n as FORM_DATA_KEY, o as FieldUpdatedType, r as FormsStorage, s as FormSubmittedEvent, t as FormsAnalyticsEvent, u as ValidatorError } from "./index-CmcgIxTH.js";
+import { A as JsonValue, C as FormValues, D as AnalyticsInstance, E as FormFileRef, O as AnalyticsTrackEvent, S as FormSchema, T as SelectFieldOption, _ as FieldOption, a as FormSchemaMap, b as FieldValidator, c as FormsServerInitOptions, f as SetResult, g as FieldConfig, h as initForms, i as FormInstance, k as AnalyticsTrackResult, l as InitFormsOptions, m as ValidateResult, n as FieldErrors, o as FormServerDataEntry, p as SubmitResult, r as FormCustomValidationsEntry, s as FormsClient, t as CustomValidationsFor, v as FieldType, w as ProtocolFieldId, x as FormFieldKey, y as FieldValidations } from "./form-x4EJcR9A.js";
+export { type AnalyticsInstance, type AnalyticsTrackEvent, type AnalyticsTrackResult, type CustomValidationsFor, type DataUpdatedEvent, FORM_DATA_KEY, type FieldConfig, type FieldErrors, type FieldOption, type FieldType, type FieldUpdatedEvent, type FieldUpdatedType, type FieldValidations, type FieldValidator, type FormCustomValidationsEntry, type FormFieldKey, type FormFileRef, type FormInstance, type FormSchema, type FormSchemaMap, type FormServerDataEntry, type FormSubmittedEvent, type FormValues, type FormsAnalyticsEvent, type FormsClient, FormsError, type FormsServerInitOptions, type FormsStorage, type InitFormsOptions, type JsonValue, type ProtocolFieldId, SchemaError, type SelectFieldOption, type SetResult, type SubmitResult, type ValidateResult, ValidatorError, initForms };

package/dist/index.js

@@ -1,2 +1,2 @@
-import { a as ValidatorError, i as SchemaError, n as FORM_DATA_KEY, r as FormsError, t as initForms } from "./form-9Tp91g6a.js";
+import { a as FORM_DATA_KEY, c as SchemaError, l as ValidatorError, n as initForms, s as FormsError } from "./form-7wmC3G_q.js";
 export { FORM_DATA_KEY, FormsError, SchemaError, ValidatorError, initForms };

package/dist/react.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_form = require("./form-DzfCc5X2.cjs");
+const require_form = require("./form-CdIfHqNc.cjs");
 let react = require("react");
 let _embeddables_core_react = require("@embeddables/core/react");
 //#region src/react/use-form-store.ts
@@ -66,14 +66,9 @@ function useRegisteredFormsClient() {
 * (`useForm<'signup', OtherSchemas>`) only to work against a map other than the
 * registered one.
 */
-function useForm({ formId, customValidations }) {
+function useForm({ formId }) {
 	const client = useRegisteredFormsClient();
-	const customValidationsRef = (0, react.useRef)(customValidations);
-	customValidationsRef.current = customValidations;
-	const form = client === null ? null : client.getForm({
-		formId,
-		customValidations: customValidationsRef.current
-	});
+	const form = client === null ? null : client.getForm({ formId });
 	const { values, errors } = useFormSnapshot(form);
 	return {
 		form,
@@ -107,6 +102,11 @@ function useFormField({ form, key }) {
 	const setValue = (0, react.useCallback)((value) => {
 		setDraft(value);
 	}, []);
+	const commit = (0, react.useCallback)((value) => {
+		if (form === null) return noopSetValue();
+		setDraft(value);
+		return form.set({ [key]: value });
+	}, [form, key]);
 	const onBlur = (0, react.useCallback)(async () => {
 		if (form === null) return noopSetValue();
 		if (draft === committed) return {
@@ -124,16 +124,111 @@ function useFormField({ form, key }) {
 		value: void 0,
 		error: void 0,
 		setValue: () => void 0,
+		commit: async () => noopSetValue(),
 		onBlur: async () => noopSetValue()
 	};
 	return {
 		value: draft,
 		error: errors[key],
 		setValue,
+		commit,
 		onBlur
 	};
 }
 //#endregion
+//#region src/react/use-form-file-upload.ts
+const noopSetResult = async () => ({
+	ok: false,
+	errors: {}
+});
+/**
+* Reactive binding for a `type: file` field: uploads through the public API,
+* commits the returned `FormFileRef`, and exposes a native `<input type="file">`
+* handler.
+*/
+function useFormFileUpload({ form, key }) {
+	const { values, errors } = useFormSnapshot(form);
+	const [isLoading, setIsLoading] = (0, react.useState)(false);
+	const [uploadError, setUploadError] = (0, react.useState)(void 0);
+	const uploadGenerationRef = (0, react.useRef)(0);
+	(0, react.useEffect)(() => {
+		return () => {
+			uploadGenerationRef.current += 1;
+			setIsLoading(false);
+			setUploadError(void 0);
+		};
+	}, [form, key]);
+	const upload = (0, react.useCallback)(async (file) => {
+		if (form === null) return noopSetResult();
+		const generation = ++uploadGenerationRef.current;
+		setIsLoading(true);
+		setUploadError(void 0);
+		try {
+			const ref = await form.uploadFile({
+				key,
+				file
+			});
+			if (generation !== uploadGenerationRef.current) return {
+				ok: false,
+				errors: {}
+			};
+			return await form.set({ [key]: ref });
+		} catch (error) {
+			if (generation !== uploadGenerationRef.current) return {
+				ok: false,
+				errors: {}
+			};
+			const message = error instanceof require_form.FormsError ? error.message : "File upload failed.";
+			setUploadError(message);
+			return {
+				ok: false,
+				errors: {}
+			};
+		} finally {
+			if (generation === uploadGenerationRef.current) setIsLoading(false);
+		}
+	}, [form, key]);
+	const clear = (0, react.useCallback)(async () => {
+		if (form === null) return noopSetResult();
+		uploadGenerationRef.current += 1;
+		setIsLoading(false);
+		setUploadError(void 0);
+		return form.set({ [key]: null });
+	}, [form, key]);
+	const onChange = (0, react.useCallback)((event) => {
+		const file = event.target.files?.[0];
+		if (file === void 0) return;
+		upload(file);
+		event.target.value = "";
+	}, [upload]);
+	if (form === null) return {
+		value: void 0,
+		error: void 0,
+		isLoading: false,
+		uploadError: void 0,
+		upload: async () => noopSetResult(),
+		clear: async () => noopSetResult(),
+		inputProps: {
+			type: "file",
+			disabled: true,
+			onChange: () => void 0
+		}
+	};
+	return {
+		value: values[key],
+		error: errors[key],
+		isLoading,
+		uploadError,
+		upload,
+		clear,
+		inputProps: {
+			type: "file",
+			disabled: isLoading,
+			onChange
+		}
+	};
+}
+//#endregion
 //#region src/react/resolve-core-analytics.ts
 function resolveCoreAnalyticsInstance(core) {
 	if (typeof core.getAnalyticsInstance !== "function") return void 0;
@@ -141,10 +236,11 @@ function resolveCoreAnalyticsInstance(core) {
 }
 //#endregion
 //#region src/react/register-forms-client.ts
-function registerFormsClient({ core, ...options }) {
+function register({ disableAnalyticsFallback, ...options }) {
+	const { core } = options;
 	const existing = formsByCore.get(core);
 	if (existing !== void 0) return existing;
-	const analyticsInstance = options.analyticsInstance ?? resolveCoreAnalyticsInstance(core);
+	const analyticsInstance = disableAnalyticsFallback ? void 0 : options.analyticsInstance ?? resolveCoreAnalyticsInstance(core);
 	const client = require_form.initForms({
 		...options,
 		core,
@@ -153,15 +249,39 @@ function registerFormsClient({ core, ...options }) {
 	formsByCore.set(core, client);
 	return client;
 }
+function registerFormsClient(options) {
+	return register(options);
+}
+function registerFormsModuleClient(options) {
+	return register(options);
+}
 //#endregion
 //#region src/react/forms-module.ts
-function forms(options) {
+const ANALYTICS_MODULE_KEY = "analytics";
+function resolveInjectedAnalytics(value) {
+	if (value === void 0) return void 0;
+	if (typeof value !== "object" || value === null) throw new require_form.FormsError("Forms received an invalid Analytics module dependency.");
+	const candidate = value;
+	if (typeof candidate.trackEvent !== "function" || typeof candidate.getAppUserId !== "function" || typeof candidate.getProjectId !== "function") throw new require_form.FormsError("Forms received an invalid Analytics module dependency.");
+	return candidate;
+}
+function forms(options = {}) {
 	return {
 		key: FORMS_MODULE_KEY,
-		init: (core) => registerFormsClient({
-			core,
-			...options
-		})
+		dependencies: [{
+			key: ANALYTICS_MODULE_KEY,
+			optional: true
+		}],
+		init: (core, context) => {
+			const analyticsInstance = context?.analyticsExcluded ? void 0 : options.analyticsInstance ?? resolveInjectedAnalytics(context?.dependencies.get(ANALYTICS_MODULE_KEY));
+			return registerFormsModuleClient({
+				core,
+				customValidations: context?.parameters?.customValidations ?? options.customValidations,
+				serverFormData: context?.parameters?.serverFormData ?? options.serverFormData,
+				analyticsInstance,
+				disableAnalyticsFallback: context?.analyticsExcluded
+			});
+		}
 	};
 }
 //#endregion
@@ -171,5 +291,6 @@ exports.registerFormsClient = registerFormsClient;
 exports.useForm = useForm;
 exports.useFormErrors = useFormErrors;
 exports.useFormField = useFormField;
+exports.useFormFileUpload = useFormFileUpload;
 
 //# sourceMappingURL=react.cjs.map