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

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.js

@@ -1,17 +1,13 @@
+import { isNamedField } from "../fields/fieldKey.js";
+import { isTruthyString } from "../submissions/coerceBoolean.js";
 //#region src/prefill/valuesFromSearchParams.ts
-const TRUTHY = new Set([
-	"true",
-	"1",
-	"on",
-	"yes"
-]);
 const coerce = (kind, raw, all) => {
 	switch (kind) {
 		case "number": {
 			const n = Number(raw);
 			return Number.isNaN(n) ? void 0 : n;
 		}
-		case "boolean": return TRUTHY.has(raw.toLowerCase());
+		case "boolean": return isTruthyString(raw);
 		case "text[]": return all;
 		default: return raw;
 	}
@@ -24,7 +20,7 @@ const coerce = (kind, raw, all) => {
 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.map((field) => [field.name, field]));
+	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;
@@ -32,7 +28,7 @@ const valuesFromSearchParams = (params, fields, registry, options = {}) => {
 		if (options.deny?.includes(fieldName)) continue;
 		const field = byName.get(fieldName);
 		const definition = field && registry.get(field.blockType);
-		if (!field || !definition) continue;
+		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;

package/dist/prefill/valuesFromSearchParams.js.map

@@ -1 +1 @@
-{"version":3,"file":"valuesFromSearchParams.js","names":[],"sources":["../../src/prefill/valuesFromSearchParams.ts"],"sourcesContent":["import type { FieldTypeRegistry } from '../fields/registry'\nimport type { FormFieldValueKind } from '../fields/types'\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 TRUTHY = new Set(['true', '1', 'on', 'yes'])\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 TRUTHY.has(raw.toLowerCase())\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.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\tif (!field || !definition) {\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":";AAaA,MAAM,SAAS,IAAI,IAAI;CAAC;CAAQ;CAAK;CAAM;AAAK,CAAC;AAEjD,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,OAAO,IAAI,IAAI,YAAY,CAAC;EACpC,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,KAAK,UAAU,CAAC,MAAM,MAAM,KAAK,CAAC,CAAC;CACjE,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;EACxD,IAAI,CAAC,SAAS,CAAC,YACd;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"}
+{"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/types.d.ts

@@ -3,8 +3,9 @@
 type PresentationSurface = 'inline' | 'page' | 'overlay';
 type PresentationDensity = 'comfortable' | 'compact';
 /**
- * Serializable, framework-agnostic description of a presentation. The admin select and the
- * stored `defaultPresentation` use only this; the React `Wrapper` is added in `./react`. No React here.
+ * 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. */

package/dist/react/Form.d.ts

@@ -1,9 +1,10 @@
 import { AnyFormFieldDefinition } from "../fields/types.js";
-import { FormFieldInstance } from "../submissions/types.js";
-import { FormFlow } from "../flow/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";
@@ -11,11 +12,20 @@ import { SubmitHandler } from "./submitForm.js";
 import { ReactNode } from "react";
 
 //#region src/react/Form.d.ts
-type FormDocument = {
-  id: number | string;
-  fields: FormFieldInstance[];
-  flow?: FormFlow; /** Stored presentation name; overridden by the `presentation` prop. */
-  defaultPresentation?: string;
+/**
+ * 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;
@@ -24,28 +34,62 @@ type FormProps = {
   renderers?: RenderersConfig;
   apiRoute?: string;
   onSubmit?: SubmitHandler;
-  onSuccess?: (submissionId?: string) => void;
+  /**
+   * 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;
-  submitLabel?: string;
-  nextLabel?: string;
-  backLabel?: string; /** Label for the overlay close control (modal/drawer). */
+  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. Overrides the form's stored default. */
+  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. */
+  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; /** Additional CSS class names applied to the root `<form>` element (and the success node). */
-  className?: string;
+  captchaToken?: string;
+  /**
+   * A signed form-context token from `signFormContext` (server/RSC), tying this render to a document
+   * (e.g. the profile page it is on). Carried alongside the answers, verified server-side, and
+   * available to `email.recipientSources`; it is never stored as an answer.
+   */
+  context?: 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: ({
@@ -57,13 +101,15 @@ declare const Form: ({
   onSubmit,
   onSuccess,
   onError,
+  converters,
+  successBehavior,
   events,
   t,
   locale,
   layout,
   submitLabel,
   nextLabel,
-  backLabel,
+  prevLabel,
   closeLabel,
   successMessage,
   presentation,
@@ -73,9 +119,17 @@ declare const Form: ({
   initialValues,
   honeypot,
   captchaToken,
+  context,
   children,
-  className
+  header,
+  className,
+  renderSubmit,
+  renderNext,
+  renderBack,
+  submitButtonClassName,
+  nextButtonClassName,
+  backButtonClassName
 }: FormProps) => import("react/jsx-runtime").JSX.Element;
 //#endregion
-export { Form, FormDocument, FormProps };
+export { Form, FormProps, FormSuccessResponse, FormSuccessResult };
 //# sourceMappingURL=Form.d.ts.map