@10x-media/form-builder 0.1.0-beta.0 → 0.1.0-beta.10

package/dist/poll/resultsField.js

@@ -0,0 +1,21 @@
+import { fieldNamesOfType } from "../fields/fieldNamesOfType.js";
+import { keys } from "../translations/keys.js";
+import { asTranslate } from "../translations/server.js";
+//#region src/poll/resultsField.ts
+/** Slugs of registered field types choosable as a poll's results field (`pollEligible: true`). */
+const pollEligibleTypes = (registry) => [...registry.values()].filter((definition) => definition.pollEligible === true).map((definition) => definition.type);
+/**
+* Validate for `poll.resultsField`, closed over the eligible type slugs derived from the registry
+* at collection-build time (mirrors the confirmation action's `toField`): unset is fine, otherwise
+* the value must name an existing, named field instance whose type is poll-eligible. Payload skips
+* the validate while the poll is disabled (the field's `admin.condition`), so a stale reference on
+* a disabled poll never blocks a save.
+*/
+const buildValidateResultsField = (eligibleTypes) => (value, { data, req }) => {
+	if (typeof value !== "string" || value.length === 0) return true;
+	return fieldNamesOfType(data && typeof data === "object" ? data.fields : void 0, eligibleTypes).includes(value) ? true : asTranslate(req.t)(keys.validationResultsFieldUnknown);
+};
+//#endregion
+export { buildValidateResultsField, pollEligibleTypes };
+
+//# sourceMappingURL=resultsField.js.map

package/dist/poll/resultsField.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resultsField.js","names":[],"sources":["../../src/poll/resultsField.ts"],"sourcesContent":["import type { PayloadRequest } from 'payload'\nimport { fieldNamesOfType } from '../fields/fieldNamesOfType'\nimport type { FieldTypeRegistry } from '../fields/registry'\nimport { keys } from '../translations/keys'\nimport { asTranslate } from '../translations/server'\n\n/** Slugs of registered field types choosable as a poll's results field (`pollEligible: true`). */\nexport const pollEligibleTypes = (registry: FieldTypeRegistry): string[] =>\n\t[...registry.values()]\n\t\t.filter((definition) => definition.pollEligible === true)\n\t\t.map((definition) => definition.type)\n\n/**\n * Validate for `poll.resultsField`, closed over the eligible type slugs derived from the registry\n * at collection-build time (mirrors the confirmation action's `toField`): unset is fine, otherwise\n * the value must name an existing, named field instance whose type is poll-eligible. Payload skips\n * the validate while the poll is disabled (the field's `admin.condition`), so a stale reference on\n * a disabled poll never blocks a save.\n */\nexport const buildValidateResultsField =\n\t(eligibleTypes: readonly string[]) =>\n\t(value: unknown, { data, req }: { data?: unknown; req: PayloadRequest }): string | true => {\n\t\tif (typeof value !== 'string' || value.length === 0) {\n\t\t\treturn true\n\t\t}\n\t\tconst fields =\n\t\t\tdata && typeof data === 'object' ? (data as Record<string, unknown>).fields : undefined\n\t\treturn fieldNamesOfType(fields, eligibleTypes).includes(value)\n\t\t\t? true\n\t\t\t: asTranslate(req.t)(keys.validationResultsFieldUnknown)\n\t}\n"],"mappings":";;;;;AAOA,MAAa,qBAAqB,aACjC,CAAC,GAAG,SAAS,OAAO,CAAC,EACnB,QAAQ,eAAe,WAAW,iBAAiB,IAAI,EACvD,KAAK,eAAe,WAAW,IAAI;;;;;;;;AAStC,MAAa,6BACX,mBACA,OAAgB,EAAE,MAAM,UAAkE;CAC1F,IAAI,OAAO,UAAU,YAAY,MAAM,WAAW,GACjD,OAAO;CAIR,OAAO,iBADN,QAAQ,OAAO,SAAS,WAAY,KAAiC,SAAS,KAAA,GAC/C,aAAa,EAAE,SAAS,KAAK,IAC1D,OACA,YAAY,IAAI,CAAC,EAAE,KAAK,6BAA6B;AACzD"}

package/dist/prefill/valuesFromSearchParams.d.ts

@@ -0,0 +1,18 @@
+import { FormFieldInstance } from "../submissions/types.js";
+import { FieldTypeRegistry } from "../fields/registry.js";
+
+//#region src/prefill/valuesFromSearchParams.d.ts
+type PrefillOptions = {
+  /** Map a query-param name to a field name. Unmapped params use their own name. */map?: Record<string, string>; /** If set, only these field names may be prefilled. */
+  allow?: string[]; /** These field names may never be prefilled. */
+  deny?: string[];
+};
+/**
+ * Map URL/query params to typed initial values for KNOWN fields only, coerced by each field's value
+ * kind. Unknown, denied, or un-allowed params are ignored; invalid numbers are dropped. Prefilled
+ * values are never trusted -- they still validate on submit. Pass the result to `<Form initialValues>`.
+ */
+declare const valuesFromSearchParams: (params: URLSearchParams | Record<string, string>, fields: FormFieldInstance[], registry: FieldTypeRegistry, options?: PrefillOptions) => Record<string, unknown>;
+//#endregion
+export { PrefillOptions, valuesFromSearchParams };
+//# sourceMappingURL=valuesFromSearchParams.d.ts.map

package/dist/prefill/valuesFromSearchParams.js

@@ -0,0 +1,41 @@
+import { isNamedField } from "../fields/fieldKey.js";
+import { isTruthyString } from "../submissions/coerceBoolean.js";
+//#region src/prefill/valuesFromSearchParams.ts
+const coerce = (kind, raw, all) => {
+	switch (kind) {
+		case "number": {
+			const n = Number(raw);
+			return Number.isNaN(n) ? void 0 : n;
+		}
+		case "boolean": return isTruthyString(raw);
+		case "text[]": return all;
+		default: return raw;
+	}
+};
+/**
+* Map URL/query params to typed initial values for KNOWN fields only, coerced by each field's value
+* kind. Unknown, denied, or un-allowed params are ignored; invalid numbers are dropped. Prefilled
+* values are never trusted -- they still validate on submit. Pass the result to `<Form initialValues>`.
+*/
+const valuesFromSearchParams = (params, fields, registry, options = {}) => {
+	const isSearch = params instanceof URLSearchParams;
+	const paramKeys = isSearch ? [...new Set(params.keys())] : Object.keys(params);
+	const byName = new Map(fields.filter(isNamedField).map((field) => [field.name, field]));
+	const result = {};
+	for (const param of paramKeys) {
+		const fieldName = options.map?.[param] ?? param;
+		if (options.allow && !options.allow.includes(fieldName)) continue;
+		if (options.deny?.includes(fieldName)) continue;
+		const field = byName.get(fieldName);
+		const definition = field && registry.get(field.blockType);
+		if (!field || !definition || definition.value === "none") continue;
+		const all = isSearch ? params.getAll(param) : [params[param]];
+		const value = coerce(definition.value, all[0] ?? "", all);
+		if (value !== void 0) result[fieldName] = value;
+	}
+	return result;
+};
+//#endregion
+export { valuesFromSearchParams };
+
+//# sourceMappingURL=valuesFromSearchParams.js.map

package/dist/prefill/valuesFromSearchParams.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"valuesFromSearchParams.js","names":[],"sources":["../../src/prefill/valuesFromSearchParams.ts"],"sourcesContent":["import { isNamedField } from '../fields/fieldKey'\nimport type { FieldTypeRegistry } from '../fields/registry'\nimport type { FormFieldValueKind } from '../fields/types'\nimport { isTruthyString } from '../submissions/coerceBoolean'\nimport type { FormFieldInstance } from '../submissions/types'\n\nexport type PrefillOptions = {\n\t/** Map a query-param name to a field name. Unmapped params use their own name. */\n\tmap?: Record<string, string>\n\t/** If set, only these field names may be prefilled. */\n\tallow?: string[]\n\t/** These field names may never be prefilled. */\n\tdeny?: string[]\n}\n\nconst coerce = (kind: FormFieldValueKind, raw: string, all: string[]): unknown => {\n\tswitch (kind) {\n\t\tcase 'number': {\n\t\t\tconst n = Number(raw)\n\t\t\treturn Number.isNaN(n) ? undefined : n\n\t\t}\n\t\tcase 'boolean':\n\t\t\treturn isTruthyString(raw)\n\t\tcase 'text[]':\n\t\t\treturn all\n\t\tdefault:\n\t\t\treturn raw\n\t}\n}\n\n/**\n * Map URL/query params to typed initial values for KNOWN fields only, coerced by each field's value\n * kind. Unknown, denied, or un-allowed params are ignored; invalid numbers are dropped. Prefilled\n * values are never trusted -- they still validate on submit. Pass the result to `<Form initialValues>`.\n */\n// biome-ignore lint/complexity/useMaxParams: four positional args are the minimal surface (params, fields, registry, options)\nexport const valuesFromSearchParams = (\n\tparams: URLSearchParams | Record<string, string>,\n\tfields: FormFieldInstance[],\n\tregistry: FieldTypeRegistry,\n\toptions: PrefillOptions = {}\n): Record<string, unknown> => {\n\tconst isSearch = params instanceof URLSearchParams\n\tconst paramKeys = isSearch ? [...new Set(params.keys())] : Object.keys(params)\n\tconst byName = new Map(fields.filter(isNamedField).map((field) => [field.name, field]))\n\tconst result: Record<string, unknown> = {}\n\n\tfor (const param of paramKeys) {\n\t\tconst fieldName = options.map?.[param] ?? param\n\n\t\tif (options.allow && !options.allow.includes(fieldName)) {\n\t\t\tcontinue\n\t\t}\n\t\tif (options.deny?.includes(fieldName)) {\n\t\t\tcontinue\n\t\t}\n\n\t\tconst field = byName.get(fieldName)\n\t\tconst definition = field && registry.get(field.blockType)\n\t\t// 'none'-kind (display-only) fields carry no value, so a param under their name is ignored.\n\t\tif (!field || !definition || definition.value === 'none') {\n\t\t\tcontinue\n\t\t}\n\n\t\tconst all = isSearch ? params.getAll(param) : [params[param] as string]\n\t\tconst value = coerce(definition.value, all[0] ?? '', all)\n\t\tif (value !== undefined) {\n\t\t\tresult[fieldName] = value\n\t\t}\n\t}\n\n\treturn result\n}\n"],"mappings":";;;AAeA,MAAM,UAAU,MAA0B,KAAa,QAA2B;CACjF,QAAQ,MAAR;EACC,KAAK,UAAU;GACd,MAAM,IAAI,OAAO,GAAG;GACpB,OAAO,OAAO,MAAM,CAAC,IAAI,KAAA,IAAY;EACtC;EACA,KAAK,WACJ,OAAO,eAAe,GAAG;EAC1B,KAAK,UACJ,OAAO;EACR,SACC,OAAO;CACT;AACD;;;;;;AAQA,MAAa,0BACZ,QACA,QACA,UACA,UAA0B,CAAC,MACE;CAC7B,MAAM,WAAW,kBAAkB;CACnC,MAAM,YAAY,WAAW,CAAC,GAAG,IAAI,IAAI,OAAO,KAAK,CAAC,CAAC,IAAI,OAAO,KAAK,MAAM;CAC7E,MAAM,SAAS,IAAI,IAAI,OAAO,OAAO,YAAY,EAAE,KAAK,UAAU,CAAC,MAAM,MAAM,KAAK,CAAC,CAAC;CACtF,MAAM,SAAkC,CAAC;CAEzC,KAAK,MAAM,SAAS,WAAW;EAC9B,MAAM,YAAY,QAAQ,MAAM,UAAU;EAE1C,IAAI,QAAQ,SAAS,CAAC,QAAQ,MAAM,SAAS,SAAS,GACrD;EAED,IAAI,QAAQ,MAAM,SAAS,SAAS,GACnC;EAGD,MAAM,QAAQ,OAAO,IAAI,SAAS;EAClC,MAAM,aAAa,SAAS,SAAS,IAAI,MAAM,SAAS;EAExD,IAAI,CAAC,SAAS,CAAC,cAAc,WAAW,UAAU,QACjD;EAGD,MAAM,MAAM,WAAW,OAAO,OAAO,KAAK,IAAI,CAAC,OAAO,MAAgB;EACtE,MAAM,QAAQ,OAAO,WAAW,OAAO,IAAI,MAAM,IAAI,GAAG;EACxD,IAAI,UAAU,KAAA,GACb,OAAO,aAAa;CAEtB;CAEA,OAAO;AACR"}

package/dist/presentations/defaults.d.ts

@@ -0,0 +1,33 @@
+//#region src/presentations/defaults.d.ts
+declare const DEFAULT_PRESENTATION_NAME = "page";
+declare const defaultPresentationDescriptors: {
+  page: {
+    name: string;
+    label: "formBuilder:presentation.page";
+    surface: "page";
+    density: "comfortable";
+  };
+  inline: {
+    name: string;
+    label: "formBuilder:presentation.inline";
+    surface: "inline";
+    density: "comfortable";
+  };
+  modal: {
+    name: string;
+    label: "formBuilder:presentation.modal";
+    surface: "overlay";
+    density: "comfortable";
+    dismissOnSuccess: true;
+  };
+  drawer: {
+    name: string;
+    label: "formBuilder:presentation.drawer";
+    surface: "overlay";
+    density: "comfortable";
+    dismissOnSuccess: true;
+  };
+};
+//#endregion
+export { DEFAULT_PRESENTATION_NAME, defaultPresentationDescriptors };
+//# sourceMappingURL=defaults.d.ts.map

package/dist/presentations/defaults.js

@@ -0,0 +1,35 @@
+import { keys } from "../translations/keys.js";
+//#region src/presentations/defaults.ts
+const DEFAULT_PRESENTATION_NAME = "page";
+const defaultPresentationDescriptors = {
+	page: {
+		name: "page",
+		label: keys.presentationPage,
+		surface: "page",
+		density: "comfortable"
+	},
+	inline: {
+		name: "inline",
+		label: keys.presentationInline,
+		surface: "inline",
+		density: "comfortable"
+	},
+	modal: {
+		name: "modal",
+		label: keys.presentationModal,
+		surface: "overlay",
+		density: "comfortable",
+		dismissOnSuccess: true
+	},
+	drawer: {
+		name: "drawer",
+		label: keys.presentationDrawer,
+		surface: "overlay",
+		density: "comfortable",
+		dismissOnSuccess: true
+	}
+};
+//#endregion
+export { DEFAULT_PRESENTATION_NAME, defaultPresentationDescriptors };
+
+//# sourceMappingURL=defaults.js.map

package/dist/presentations/defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.js","names":[],"sources":["../../src/presentations/defaults.ts"],"sourcesContent":["import { keys } from '../translations/keys'\nimport type { PresentationDescriptor } from './types'\n\nexport const DEFAULT_PRESENTATION_NAME = 'page'\n\nexport const defaultPresentationDescriptors = {\n\tpage: { name: 'page', label: keys.presentationPage, surface: 'page', density: 'comfortable' },\n\tinline: {\n\t\tname: 'inline',\n\t\tlabel: keys.presentationInline,\n\t\tsurface: 'inline',\n\t\tdensity: 'comfortable',\n\t},\n\tmodal: {\n\t\tname: 'modal',\n\t\tlabel: keys.presentationModal,\n\t\tsurface: 'overlay',\n\t\tdensity: 'comfortable',\n\t\tdismissOnSuccess: true,\n\t},\n\tdrawer: {\n\t\tname: 'drawer',\n\t\tlabel: keys.presentationDrawer,\n\t\tsurface: 'overlay',\n\t\tdensity: 'comfortable',\n\t\tdismissOnSuccess: true,\n\t},\n} satisfies Record<string, PresentationDescriptor>\n"],"mappings":";;AAGA,MAAa,4BAA4B;AAEzC,MAAa,iCAAiC;CAC7C,MAAM;EAAE,MAAM;EAAQ,OAAO,KAAK;EAAkB,SAAS;EAAQ,SAAS;CAAc;CAC5F,QAAQ;EACP,MAAM;EACN,OAAO,KAAK;EACZ,SAAS;EACT,SAAS;CACV;CACA,OAAO;EACN,MAAM;EACN,OAAO,KAAK;EACZ,SAAS;EACT,SAAS;EACT,kBAAkB;CACnB;CACA,QAAQ;EACP,MAAM;EACN,OAAO,KAAK;EACZ,SAAS;EACT,SAAS;EACT,kBAAkB;CACnB;AACD"}

package/dist/presentations/types.d.ts

@@ -0,0 +1,19 @@
+//#region src/presentations/types.d.ts
+/** How a presentation surfaces the form. Drives wrapper selection and CSS. */
+type PresentationSurface = 'inline' | 'page' | 'overlay';
+type PresentationDensity = 'comfortable' | 'compact';
+/**
+ * Serializable, framework-agnostic description of a presentation. `presentations/defaults.ts`
+ * ships the built-ins the React presentation registry wraps with a `Wrapper` (see `./react`). No
+ * React here.
+ */
+type PresentationDescriptor = {
+  name: string; /** i18n key or literal shown in the admin select. */
+  label: string;
+  surface: PresentationSurface;
+  density: PresentationDensity; /** Overlay surfaces request dismissal after a successful submit. */
+  dismissOnSuccess?: boolean;
+};
+//#endregion
+export { PresentationDensity, PresentationDescriptor, PresentationSurface };
+//# sourceMappingURL=types.d.ts.map

package/dist/react/Form.d.ts

@@ -0,0 +1,128 @@
+import { AnyFormFieldDefinition } from "../fields/types.js";
+import { BodyConverter } from "../actions/body/converters.js";
+import { FormButtonSettings, FormDocument, FormPollSettings, FormResponseSettings } from "../form/types.js";
+import { RendererTranslate } from "./contract.js";
+import { FormEventSink } from "../events/types.js";
+import { AnyValidationRuleDefinition } from "../validation/types.js";
+import { BackButtonRenderProps, NextButtonRenderProps, SubmitButtonRenderProps } from "./FormControls.js";
+import { FormPresentation } from "./presentation/types.js";
+import { PresentationsConfig } from "./presentation/registry.js";
+import { RenderersConfig } from "./registry.js";
+import { SubmitHandler } from "./submitForm.js";
+import { ReactNode } from "react";
+
+//#region src/react/Form.d.ts
+/**
+ * The success response passed to `onSuccess`, recall-resolved and (for a message) serialized with the
+ * form's active converters, so a host can render or toast the resolved response without re-deriving it.
+ */
+type FormSuccessResponse = {
+  type: 'message';
+  html?: string;
+} | {
+  type: 'redirect';
+  url?: string;
+};
+/** The second argument to `onSuccess`: the resolved success response (an object, so it can grow). */
+type FormSuccessResult = {
+  response?: FormSuccessResponse;
+};
+type FormProps = {
+  form: FormDocument;
+  fieldTypes?: AnyFormFieldDefinition[];
+  rules?: AnyValidationRuleDefinition[];
+  renderers?: RenderersConfig;
+  apiRoute?: string;
+  onSubmit?: SubmitHandler;
+  /**
+   * Called after a successful submission with the submission id and the resolved success response
+   * (recall-applied, serialized with `converters`), so a host can toast or render it. Fires in both
+   * `successBehavior` modes and on the custom-`children` path.
+   */
+  onSuccess?: (submissionId?: string, result?: FormSuccessResult) => void;
+  onError?: (message: string) => void;
+  /**
+   * Custom Lexical block converters (e.g. host `icon`/`badge` blocks) spread over the defaults for the
+   * client serializer, so those blocks survive in the success message and in the `onSuccess` response.
+   */
+  converters?: Record<string, BodyConverter>;
+  /**
+   * What happens on a successful submit. `'replace'` (default) swaps the form for the success screen;
+   * `'reset'` clears the fields in place and shows no success screen, so a host can toast via `onSuccess`
+   * and keep the form usable.
+   */
+  successBehavior?: 'replace' | 'reset';
+  events?: FormEventSink;
+  t?: RendererTranslate;
+  locale?: string;
+  layout?: boolean; /** Submit button label. Precedence: this prop, then the form's `buttons.submitLabel`, then the translated default. */
+  submitLabel?: string; /** "Next" button label for multi-step forms. Precedence: this prop, then the form's `buttons.nextLabel`, then the translated default. */
+  nextLabel?: string; /** "Back" button label for multi-step forms. Precedence: this prop, then the form's `buttons.prevLabel`, then the translated default. */
+  prevLabel?: string; /** Label for the overlay close control (modal/drawer). */
+  closeLabel?: string;
+  successMessage?: string; /** Active presentation: a name into the registry or an inline presentation. Defaults to `'page'` when omitted. */
+  presentation?: string | FormPresentation; /** Per-render presentation overrides merged onto the defaults (add, replace, or `false` to remove). */
+  presentations?: PresentationsConfig; /** Invoked when an overlay presentation dismisses (close button, Escape, outside click, or `dismissOnSuccess`). */
+  onClose?: () => void;
+  /**
+   * Accessible name for an overlay surface (modal/drawer). Hosts choosing between a trigger
+   * label and the form's own admin title should prefer `form.title` when set, falling back to
+   * their own label otherwise.
+   */
+  title?: string; /** Seed initial field values (e.g. from `valuesFromSearchParams`). Still validated on submit. */
+  initialValues?: Record<string, unknown>; /** Honeypot decoy (on by default). `false` removes it; `{ name }` matches a customized server `spam.honeypot.fieldName`. */
+  honeypot?: false | {
+    name?: string;
+  }; /** A token from your captcha widget; verified server-side when a captcha provider is configured. */
+  captchaToken?: string; /** Custom layout: render fields with `useField`/`useFormState` instead of the auto-rendered field loop. */
+  children?: ReactNode; /** Chrome rendered inside the form, above the fields, in default mode (e.g. `<FormSteps />`). */
+  header?: ReactNode; /** Additional CSS class names applied to the root `<form>` element (and the success node). */
+  className?: string; /** Replace the default submit button entirely. Receives the resolved label and submitting state. */
+  renderSubmit?: (props: SubmitButtonRenderProps) => ReactNode; /** Replace the default "Next" button in multi-step forms. */
+  renderNext?: (props: NextButtonRenderProps) => ReactNode; /** Replace the default "Back" button in multi-step forms. */
+  renderBack?: (props: BackButtonRenderProps) => ReactNode; /** CSS class forwarded to the default submit `<button>`. Ignored when `renderSubmit` is provided. */
+  submitButtonClassName?: string; /** CSS class forwarded to the default "Next" `<button>`. Ignored when `renderNext` is provided. */
+  nextButtonClassName?: string; /** CSS class forwarded to the default "Back" `<button>`. Ignored when `renderBack` is provided. */
+  backButtonClassName?: string;
+};
+/** The headless form controller: state, progressive client validation, conditional visibility, submission, events. */
+declare const Form: ({
+  form,
+  fieldTypes,
+  rules,
+  renderers,
+  apiRoute,
+  onSubmit,
+  onSuccess,
+  onError,
+  converters,
+  successBehavior,
+  events,
+  t,
+  locale,
+  layout,
+  submitLabel,
+  nextLabel,
+  prevLabel,
+  closeLabel,
+  successMessage,
+  presentation,
+  presentations,
+  onClose,
+  title,
+  initialValues,
+  honeypot,
+  captchaToken,
+  children,
+  header,
+  className,
+  renderSubmit,
+  renderNext,
+  renderBack,
+  submitButtonClassName,
+  nextButtonClassName,
+  backButtonClassName
+}: FormProps) => import("react/jsx-runtime").JSX.Element;
+//#endregion
+export { Form, FormProps, FormSuccessResponse, FormSuccessResult };
+//# sourceMappingURL=Form.d.ts.map