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

package/dist/fields/types.d.ts

@@ -1,11 +1,17 @@
-import { FileRef } from "../uploads/types.js";
 import { ConditionFieldType } from "../conditions/fieldTypes.js";
-import { Field } from "payload";
+import { PollOption } from "../poll/definePollOptionSource.js";
+import { FormFieldInstance } from "../submissions/types.js";
+import { FileRef } from "../uploads/types.js";
+import { Field, Payload, PayloadRequest } from "payload";
 import { StandardSchemaV1 } from "@standard-schema/spec";
 
 //#region src/fields/types.d.ts
-/** The stored value shapes a field type can declare. Drives `validate`/`format` typing and value coercion. */
-type FormFieldValueKind = 'text' | 'number' | 'boolean' | 'date' | 'text[]' | 'file' | 'repeater';
+/**
+ * The stored value shapes a field type can declare. Drives `validate`/`format` typing and value
+ * coercion. `'none'` marks a display-only type (e.g. `message`): the engine never seeds, validates,
+ * or stores a value for it, and a client-sent value under its name is dropped.
+ */
+type FormFieldValueKind = 'text' | 'number' | 'boolean' | 'date' | 'text[]' | 'file' | 'repeater' | 'none';
 type ValueKindTypeMap = {
   text: string;
   number: number;
@@ -14,10 +20,17 @@ type ValueKindTypeMap = {
   'text[]': string[];
   file: FileRef;
   repeater: Array<Record<string, unknown>>;
+  none: never;
 };
 type ValueOfKind<K extends FormFieldValueKind> = ValueKindTypeMap[K];
 /** Resolved per-instance config values for a field type (loose at the DB boundary, narrowed by the author's generic). */
 type FormFieldConfigValues = Record<string, unknown>;
+/**
+ * The shared config fields a type may drop via {@link FormFieldDefinition.omitShared}. `name` is
+ * deliberately absent and can never be dropped: it is the storage key every read and write path
+ * gates on (see `isNamedField`), so a named field without it would silently store nothing.
+ */
+type OmittableSharedField = 'label' | 'placeholder' | 'description' | 'width' | 'required';
 /** A `t`-like resolver. The engine supplies one from the request i18n; the renderer will supply the client i18n. */
 type Translate = (key: string) => string;
 type FormFieldValidateArgs<K extends FormFieldValueKind, TConfig extends FormFieldConfigValues> = {
@@ -37,6 +50,16 @@ type FormFieldFormatArgs<K extends FormFieldValueKind, TConfig extends FormField
   t: Translate;
 };
 type FormFieldFormat<K extends FormFieldValueKind, TConfig extends FormFieldConfigValues> = (args: FormFieldFormatArgs<K, TConfig>) => string;
+/** Arguments a {@link FormFieldDefinition.resolveOptions} implementation receives. */
+type ResolveFieldOptionsArgs = {
+  /** The configured field instance, so the resolver can read the values the author selected. */instance: FormFieldInstance;
+  form: {
+    id: number | string;
+    title?: string;
+  };
+  payload: Payload;
+  req?: PayloadRequest;
+};
 /**
  * A field type, authored once. `value` drives typed `validate`/`format`; `config` is a Payload
  * `Field[]` for the add-field drawer; `Field` is the client renderer import-map ref;
@@ -47,13 +70,53 @@ type FormFieldDefinition<K extends FormFieldValueKind = FormFieldValueKind, TCon
   label: string;
   value: K;
   config?: Field[];
+  /**
+   * Extra per-type fields for the Advanced tab, after `visibleWhen`/`hidden`. Lets a type add
+   * behavior settings (e.g. `autocomplete`) without crowding the Field tab.
+   */
+  advancedConfig?: Field[];
   validate?: FormFieldValidate<K, TConfig>;
   format?: FormFieldFormat<K, TConfig>;
-  Field?: string; /** Optional Standard Schema validator (Zod/Valibot/etc.), run by the engine after the intrinsic validator. */
+  Field?: string;
+  /**
+   * Import-map ref for a custom block row Label, replacing the default `FieldBlockLabel` for this
+   * type's add-field block. Receives the same `{ typeLabelKey }` clientProps. The `consent` type
+   * uses this to resolve and show the referenced source's name.
+   */
+  blockLabel?: string; /** Optional Standard Schema validator (Zod/Valibot/etc.), run by the engine after the intrinsic validator. */
   schema?: StandardSchemaV1;
   icon?: string;
   group?: string; /** How this field appears in the condition builder. Defaults from `value` (see `defaultConditionType`). */
   conditionType?: ConditionFieldType;
+  /**
+   * Bare definitions render without the shared chrome: no name/label/width/required/placeholder/
+   * description and no validation tabs; the definition's `config` IS the entire block. Instances
+   * are nameless (identified by Payload's hidden block row `id`, see `fieldKey`), so bare types
+   * must be display-only (`value: 'none'`): with no name there is nothing to validate or store.
+   */
+  bare?: boolean;
+  /**
+   * Shared config fields this type never uses, so authors are not offered a setting the renderer
+   * ignores (e.g. a placeholder on a checkbox). Unlike `bare`, which drops the shared chrome
+   * wholesale, this keeps the rest of it. An emptied layout row collapses and a lone survivor
+   * spans the row (see `sharedFieldConfig`).
+   */
+  omitShared?: OmittableSharedField[];
+  /**
+   * The type can be chosen as a poll's results field. Its instances must produce enumerable
+   * answers: either authored `options` or options resolved from a poll option source.
+   */
+  pollEligible?: boolean;
+  /**
+   * Source this `pollEligible` type's poll choices from the field instance itself, instead of
+   * authored `options` or a poll `optionSource`. A type that holds enumerable data (for example a
+   * `hasMany` relationship to the voteable records) returns one {@link PollOption} per selectable
+   * value, read from the live instance the author configured (so it can `payload.find` over the
+   * ids it holds). The result backs submission validation, the admin winner select, and results
+   * labeling exactly like a source would; it is consulted after an `optionSource` and before the
+   * instance's authored `options`.
+   */
+  resolveOptions?: (args: ResolveFieldOptionsArgs) => PollOption[] | Promise<PollOption[]>;
 };
 /** The erased shape stored in the heterogeneous registry. Value is `unknown`; config re-narrows per matched type at execution. */
 type AnyFormFieldValidate = (args: {
@@ -75,15 +138,21 @@ type AnyFormFieldDefinition = {
   type: string;
   label: string;
   value: FormFieldValueKind;
-  config?: Field[];
+  config?: Field[]; /** See `FormFieldDefinition.advancedConfig`: extra per-type fields for the Advanced tab. */
+  advancedConfig?: Field[];
   validate?: AnyFormFieldValidate;
   format?: AnyFormFieldFormat;
-  Field?: string;
+  Field?: string; /** See `FormFieldDefinition.blockLabel`: import-map ref for a custom block row Label. */
+  blockLabel?: string;
   schema?: StandardSchemaV1;
   icon?: string;
   group?: string; /** How this field appears in the condition builder. Defaults from `value` (see `defaultConditionType`). */
-  conditionType?: ConditionFieldType;
+  conditionType?: ConditionFieldType; /** See `FormFieldDefinition.bare`: the block is the definition's `config` alone, instances are nameless. */
+  bare?: boolean; /** See `FormFieldDefinition.omitShared`: shared config fields this type never uses, never authored. */
+  omitShared?: OmittableSharedField[]; /** See `FormFieldDefinition.pollEligible`: choosable as a poll's results field. */
+  pollEligible?: boolean; /** See `FormFieldDefinition.resolveOptions`: source poll choices from the instance itself. */
+  resolveOptions?: (args: ResolveFieldOptionsArgs) => PollOption[] | Promise<PollOption[]>;
 };
 //#endregion
-export { AnyFormFieldDefinition, FormFieldConfigValues, FormFieldDefinition, FormFieldFormat, FormFieldValidate, FormFieldValueKind, Translate };
+export { AnyFormFieldDefinition, FormFieldConfigValues, FormFieldDefinition, FormFieldFormat, FormFieldValidate, FormFieldValueKind, OmittableSharedField, ResolveFieldOptionsArgs, Translate };
 //# sourceMappingURL=types.d.ts.map

package/dist/flow/engine.d.ts

@@ -3,14 +3,16 @@ import { FormFlow } from "./types.js";
 //#region src/flow/engine.d.ts
 /** The entry step id (the first step), or `undefined` for an empty flow. */
 declare const firstStepId: (flow: FormFlow) => string | undefined;
-/** The field machine names a step renders (empty for an unknown step). */
+/** The field keys a step renders (names for named fields, block row ids for bare blocks; empty for an unknown step). */
 declare const stepFieldNames: (flow: FormFlow, id: string) => string[];
 /**
- * Resolve the next step id from the current step + answers: the first transition whose `when` matches
- * (via `evaluateCondition`), else the default `next`, else `undefined` (terminal). Pure + isomorphic.
+ * Resolve the next step id from the current step + answers. Precedence: the first transition whose
+ * `when` matches (via `evaluateCondition`) wins, else the step's `next` (a step id to jump to, or
+ * `null` for an explicit end), else the next step in array order (the last step ends the flow).
+ * Returns `undefined` when the flow ends here. Pure + isomorphic.
  */
 declare const resolveNextStepId: (flow: FormFlow, currentId: string, answers: Record<string, unknown>) => string | undefined;
-/** Whether the current step is terminal (no matching transition + no default next). */
+/** Whether the flow ends at the current step (`resolveNextStepId` finds no step to advance to). */
 declare const isTerminalStepId: (flow: FormFlow, currentId: string, answers: Record<string, unknown>) => boolean;
 //#endregion
 export { firstStepId, isTerminalStepId, resolveNextStepId, stepFieldNames };

package/dist/flow/engine.js

@@ -4,19 +4,24 @@ import { evaluateCondition } from "../conditions/evaluate.js";
 const firstStepId = (flow) => flow.steps[0]?.id;
 /** The step with the given id, or `undefined`. */
 const getStep = (flow, id) => flow.steps.find((step) => step.id === id);
-/** The field machine names a step renders (empty for an unknown step). */
+/** The field keys a step renders (names for named fields, block row ids for bare blocks; empty for an unknown step). */
 const stepFieldNames = (flow, id) => getStep(flow, id)?.fields ?? [];
 /**
-* Resolve the next step id from the current step + answers: the first transition whose `when` matches
-* (via `evaluateCondition`), else the default `next`, else `undefined` (terminal). Pure + isomorphic.
+* Resolve the next step id from the current step + answers. Precedence: the first transition whose
+* `when` matches (via `evaluateCondition`) wins, else the step's `next` (a step id to jump to, or
+* `null` for an explicit end), else the next step in array order (the last step ends the flow).
+* Returns `undefined` when the flow ends here. Pure + isomorphic.
 */
 const resolveNextStepId = (flow, currentId, answers) => {
-	const step = getStep(flow, currentId);
+	const index = flow.steps.findIndex((step) => step.id === currentId);
+	const step = flow.steps[index];
 	if (!step) return;
 	for (const transition of step.transitions ?? []) if (evaluateCondition(transition.when, answers)) return transition.to;
-	return step.next;
+	if (step.next === null) return;
+	if (step.next !== void 0) return step.next;
+	return flow.steps[index + 1]?.id;
 };
-/** Whether the current step is terminal (no matching transition + no default next). */
+/** Whether the flow ends at the current step (`resolveNextStepId` finds no step to advance to). */
 const isTerminalStepId = (flow, currentId, answers) => resolveNextStepId(flow, currentId, answers) === void 0;
 //#endregion
 export { firstStepId, isTerminalStepId, resolveNextStepId, stepFieldNames };

package/dist/flow/engine.js.map

@@ -1 +1 @@
-{"version":3,"file":"engine.js","names":[],"sources":["../../src/flow/engine.ts"],"sourcesContent":["import { evaluateCondition } from '../conditions/evaluate'\nimport type { FlowStep, FormFlow } from './types'\n\n/** The entry step id (the first step), or `undefined` for an empty flow. */\nexport const firstStepId = (flow: FormFlow): string | undefined => flow.steps[0]?.id\n\n/** The step with the given id, or `undefined`. */\nexport const getStep = (flow: FormFlow, id: string): FlowStep | undefined =>\n\tflow.steps.find((step) => step.id === id)\n\n/** The field machine names a step renders (empty for an unknown step). */\nexport const stepFieldNames = (flow: FormFlow, id: string): string[] =>\n\tgetStep(flow, id)?.fields ?? []\n\n/**\n * Resolve the next step id from the current step + answers: the first transition whose `when` matches\n * (via `evaluateCondition`), else the default `next`, else `undefined` (terminal). Pure + isomorphic.\n */\nexport const resolveNextStepId = (\n\tflow: FormFlow,\n\tcurrentId: string,\n\tanswers: Record<string, unknown>\n): string | undefined => {\n\tconst step = getStep(flow, currentId)\n\tif (!step) {\n\t\treturn undefined\n\t}\n\tfor (const transition of step.transitions ?? []) {\n\t\tif (evaluateCondition(transition.when, answers)) {\n\t\t\treturn transition.to\n\t\t}\n\t}\n\treturn step.next\n}\n\n/** Whether the current step is terminal (no matching transition + no default next). */\nexport const isTerminalStepId = (\n\tflow: FormFlow,\n\tcurrentId: string,\n\tanswers: Record<string, unknown>\n): boolean => resolveNextStepId(flow, currentId, answers) === undefined\n"],"mappings":";;;AAIA,MAAa,eAAe,SAAuC,KAAK,MAAM,IAAI;;AAGlF,MAAa,WAAW,MAAgB,OACvC,KAAK,MAAM,MAAM,SAAS,KAAK,OAAO,EAAE;;AAGzC,MAAa,kBAAkB,MAAgB,OAC9C,QAAQ,MAAM,EAAE,GAAG,UAAU,CAAC;;;;;AAM/B,MAAa,qBACZ,MACA,WACA,YACwB;CACxB,MAAM,OAAO,QAAQ,MAAM,SAAS;CACpC,IAAI,CAAC,MACJ;CAED,KAAK,MAAM,cAAc,KAAK,eAAe,CAAC,GAC7C,IAAI,kBAAkB,WAAW,MAAM,OAAO,GAC7C,OAAO,WAAW;CAGpB,OAAO,KAAK;AACb;;AAGA,MAAa,oBACZ,MACA,WACA,YACa,kBAAkB,MAAM,WAAW,OAAO,MAAM,KAAA"}
+{"version":3,"file":"engine.js","names":[],"sources":["../../src/flow/engine.ts"],"sourcesContent":["import { evaluateCondition } from '../conditions/evaluate'\nimport type { FlowStep, FormFlow } from './types'\n\n/** The entry step id (the first step), or `undefined` for an empty flow. */\nexport const firstStepId = (flow: FormFlow): string | undefined => flow.steps[0]?.id\n\n/** The step with the given id, or `undefined`. */\nexport const getStep = (flow: FormFlow, id: string): FlowStep | undefined =>\n\tflow.steps.find((step) => step.id === id)\n\n/** The field keys a step renders (names for named fields, block row ids for bare blocks; empty for an unknown step). */\nexport const stepFieldNames = (flow: FormFlow, id: string): string[] =>\n\tgetStep(flow, id)?.fields ?? []\n\n/**\n * Resolve the next step id from the current step + answers. Precedence: the first transition whose\n * `when` matches (via `evaluateCondition`) wins, else the step's `next` (a step id to jump to, or\n * `null` for an explicit end), else the next step in array order (the last step ends the flow).\n * Returns `undefined` when the flow ends here. Pure + isomorphic.\n */\nexport const resolveNextStepId = (\n\tflow: FormFlow,\n\tcurrentId: string,\n\tanswers: Record<string, unknown>\n): string | undefined => {\n\tconst index = flow.steps.findIndex((step) => step.id === currentId)\n\tconst step = flow.steps[index]\n\tif (!step) {\n\t\treturn undefined\n\t}\n\tfor (const transition of step.transitions ?? []) {\n\t\tif (evaluateCondition(transition.when, answers)) {\n\t\t\treturn transition.to\n\t\t}\n\t}\n\tif (step.next === null) {\n\t\treturn undefined\n\t}\n\tif (step.next !== undefined) {\n\t\treturn step.next\n\t}\n\treturn flow.steps[index + 1]?.id\n}\n\n/** Whether the flow ends at the current step (`resolveNextStepId` finds no step to advance to). */\nexport const isTerminalStepId = (\n\tflow: FormFlow,\n\tcurrentId: string,\n\tanswers: Record<string, unknown>\n): boolean => resolveNextStepId(flow, currentId, answers) === undefined\n"],"mappings":";;;AAIA,MAAa,eAAe,SAAuC,KAAK,MAAM,IAAI;;AAGlF,MAAa,WAAW,MAAgB,OACvC,KAAK,MAAM,MAAM,SAAS,KAAK,OAAO,EAAE;;AAGzC,MAAa,kBAAkB,MAAgB,OAC9C,QAAQ,MAAM,EAAE,GAAG,UAAU,CAAC;;;;;;;AAQ/B,MAAa,qBACZ,MACA,WACA,YACwB;CACxB,MAAM,QAAQ,KAAK,MAAM,WAAW,SAAS,KAAK,OAAO,SAAS;CAClE,MAAM,OAAO,KAAK,MAAM;CACxB,IAAI,CAAC,MACJ;CAED,KAAK,MAAM,cAAc,KAAK,eAAe,CAAC,GAC7C,IAAI,kBAAkB,WAAW,MAAM,OAAO,GAC7C,OAAO,WAAW;CAGpB,IAAI,KAAK,SAAS,MACjB;CAED,IAAI,KAAK,SAAS,KAAA,GACjB,OAAO,KAAK;CAEb,OAAO,KAAK,MAAM,QAAQ,IAAI;AAC/B;;AAGA,MAAa,oBACZ,MACA,WACA,YACa,kBAAkB,MAAM,WAAW,OAAO,MAAM,KAAA"}

package/dist/flow/normalizeFlow.js

@@ -1,24 +1,43 @@
 //#region src/flow/normalizeFlow.ts
 const isRecord = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
 /**
-* Pure guard that normalizes a raw (possibly untrusted) flow value against the
-* form's current field list. Returns `undefined` when the flow is absent, empty,
-* or resolves to fewer than two steps (a single step is an ordinary form).
+* Pure guard that normalizes a raw (possibly untrusted) flow value against the form's current
+* field keys (machine names for named fields, block row ids for bare blocks; see `fieldKey`).
+* Returns `undefined` when the flow is absent, empty, or resolves to fewer than two steps
+* (a single step is an ordinary form). A field assigned to multiple steps keeps only its
+* first occurrence in step order. `next: null` (explicit end of form) is preserved as distinct
+* from an absent `next` (sequential fall-through); a `next` pointing at an unknown step is
+* dropped to absent.
+*
+* A step is kept even when it ends up with no fields, which happens when every field it named was
+* deleted from the form. Dropping it would be wrong twice over: a host can render its own content
+* per step off `useFormStep()`, so an empty step is not necessarily an empty page, and dropping
+* one would strand the `next` and transition targets that point at it. The visitor gets a page with
+* only navigation on it, which is visible to the author in the flow builder and recoverable there.
+*
+* When `normalizeWhen` is provided, each transition's `when` is laundered through it (the same field
+* condition normalization); a transition whose `when` strips to nothing (an operand field was deleted)
+* is dropped rather than kept as an always-true route that would force navigation.
 */
-const normalizeFlow = (raw, fieldNames) => {
+const normalizeFlow = (raw, fieldKeys, normalizeWhen) => {
 	if (!isRecord(raw) || !Array.isArray(raw.steps)) return;
-	const knownFields = new Set(fieldNames);
+	const knownFields = new Set(fieldKeys);
 	const rawSteps = raw.steps.filter((s) => isRecord(s) && typeof s.id === "string");
 	const knownIds = new Set(rawSteps.map((s) => s.id));
 	if (knownIds.size < 2) return;
+	const seenFields = /* @__PURE__ */ new Set();
 	return { steps: rawSteps.map((s) => {
 		const id = s.id;
-		const fields = Array.isArray(s.fields) ? s.fields.filter((f) => typeof f === "string" && knownFields.has(f)) : [];
+		const fields = Array.isArray(s.fields) ? s.fields.filter((f) => {
+			if (typeof f !== "string" || !knownFields.has(f) || seenFields.has(f)) return false;
+			seenFields.add(f);
+			return true;
+		}) : [];
 		const transitions = (Array.isArray(s.transitions) ? s.transitions : []).filter((t) => isRecord(t) && typeof t.to === "string" && knownIds.has(t.to) && isRecord(t.when)).map((t) => ({
-			when: t.when,
+			when: normalizeWhen ? normalizeWhen(t.when) : t.when,
 			to: t.to
-		}));
-		const next = typeof s.next === "string" && knownIds.has(s.next) ? s.next : void 0;
+		})).filter((t) => t.when !== void 0);
+		const next = s.next === null ? null : typeof s.next === "string" && knownIds.has(s.next) ? s.next : void 0;
 		const step = {
 			id,
 			fields

package/dist/flow/normalizeFlow.js.map

@@ -1 +1 @@
-{"version":3,"file":"normalizeFlow.js","names":[],"sources":["../../src/flow/normalizeFlow.ts"],"sourcesContent":["import type { Where } from 'payload'\nimport type { FlowStep, FormFlow } from './types'\n\nconst isRecord = (v: unknown): v is Record<string, unknown> =>\n\tv !== null && typeof v === 'object' && !Array.isArray(v)\n\n/**\n * Pure guard that normalizes a raw (possibly untrusted) flow value against the\n * form's current field list. Returns `undefined` when the flow is absent, empty,\n * or resolves to fewer than two steps (a single step is an ordinary form).\n */\nexport const normalizeFlow = (raw: unknown, fieldNames: string[]): FormFlow | undefined => {\n\tif (!isRecord(raw) || !Array.isArray(raw.steps)) {\n\t\treturn undefined\n\t}\n\n\tconst knownFields = new Set(fieldNames)\n\n\tconst rawSteps = raw.steps.filter(\n\t\t(s): s is Record<string, unknown> => isRecord(s) && typeof s.id === 'string'\n\t)\n\n\tconst knownIds = new Set(rawSteps.map((s) => s.id as string))\n\n\tif (knownIds.size < 2) {\n\t\treturn undefined\n\t}\n\n\tconst steps: FlowStep[] = rawSteps.map((s) => {\n\t\tconst id = s.id as string\n\n\t\tconst fields = Array.isArray(s.fields)\n\t\t\t? s.fields.filter((f): f is string => typeof f === 'string' && knownFields.has(f))\n\t\t\t: []\n\n\t\tconst rawTransitions = Array.isArray(s.transitions) ? s.transitions : []\n\t\tconst transitions = rawTransitions\n\t\t\t.filter(\n\t\t\t\t(t): t is Record<string, unknown> =>\n\t\t\t\t\tisRecord(t) &&\n\t\t\t\t\ttypeof t.to === 'string' &&\n\t\t\t\t\tknownIds.has(t.to as string) &&\n\t\t\t\t\tisRecord(t.when)\n\t\t\t)\n\t\t\t.map((t) => ({ when: t.when as Where, to: t.to as string }))\n\n\t\tconst next = typeof s.next === 'string' && knownIds.has(s.next) ? (s.next as string) : undefined\n\n\t\tconst step: FlowStep = { id, fields }\n\t\tif (typeof s.title === 'string') step.title = s.title\n\t\tif (transitions.length > 0) step.transitions = transitions\n\t\tif (next !== undefined) step.next = next\n\n\t\treturn step\n\t})\n\n\treturn { steps }\n}\n"],"mappings":";AAGA,MAAM,YAAY,MACjB,MAAM,QAAQ,OAAO,MAAM,YAAY,CAAC,MAAM,QAAQ,CAAC;;;;;;AAOxD,MAAa,iBAAiB,KAAc,eAA+C;CAC1F,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC,MAAM,QAAQ,IAAI,KAAK,GAC7C;CAGD,MAAM,cAAc,IAAI,IAAI,UAAU;CAEtC,MAAM,WAAW,IAAI,MAAM,QACzB,MAAoC,SAAS,CAAC,KAAK,OAAO,EAAE,OAAO,QACrE;CAEA,MAAM,WAAW,IAAI,IAAI,SAAS,KAAK,MAAM,EAAE,EAAY,CAAC;CAE5D,IAAI,SAAS,OAAO,GACnB;CA+BD,OAAO,EAAE,OA5BiB,SAAS,KAAK,MAAM;EAC7C,MAAM,KAAK,EAAE;EAEb,MAAM,SAAS,MAAM,QAAQ,EAAE,MAAM,IAClC,EAAE,OAAO,QAAQ,MAAmB,OAAO,MAAM,YAAY,YAAY,IAAI,CAAC,CAAC,IAC/E,CAAC;EAGJ,MAAM,eADiB,MAAM,QAAQ,EAAE,WAAW,IAAI,EAAE,cAAc,CAAC,GAErE,QACC,MACA,SAAS,CAAC,KACV,OAAO,EAAE,OAAO,YAChB,SAAS,IAAI,EAAE,EAAY,KAC3B,SAAS,EAAE,IAAI,CACjB,EACC,KAAK,OAAO;GAAE,MAAM,EAAE;GAAe,IAAI,EAAE;EAAa,EAAE;EAE5D,MAAM,OAAO,OAAO,EAAE,SAAS,YAAY,SAAS,IAAI,EAAE,IAAI,IAAK,EAAE,OAAkB,KAAA;EAEvF,MAAM,OAAiB;GAAE;GAAI;EAAO;EACpC,IAAI,OAAO,EAAE,UAAU,UAAU,KAAK,QAAQ,EAAE;EAChD,IAAI,YAAY,SAAS,GAAG,KAAK,cAAc;EAC/C,IAAI,SAAS,KAAA,GAAW,KAAK,OAAO;EAEpC,OAAO;CACR,CAEa,EAAE;AAChB"}
+{"version":3,"file":"normalizeFlow.js","names":[],"sources":["../../src/flow/normalizeFlow.ts"],"sourcesContent":["import type { Where } from 'payload'\nimport type { FlowStep, FormFlow } from './types'\n\nconst isRecord = (v: unknown): v is Record<string, unknown> =>\n\tv !== null && typeof v === 'object' && !Array.isArray(v)\n\n/**\n * Pure guard that normalizes a raw (possibly untrusted) flow value against the form's current\n * field keys (machine names for named fields, block row ids for bare blocks; see `fieldKey`).\n * Returns `undefined` when the flow is absent, empty, or resolves to fewer than two steps\n * (a single step is an ordinary form). A field assigned to multiple steps keeps only its\n * first occurrence in step order. `next: null` (explicit end of form) is preserved as distinct\n * from an absent `next` (sequential fall-through); a `next` pointing at an unknown step is\n * dropped to absent.\n *\n * A step is kept even when it ends up with no fields, which happens when every field it named was\n * deleted from the form. Dropping it would be wrong twice over: a host can render its own content\n * per step off `useFormStep()`, so an empty step is not necessarily an empty page, and dropping\n * one would strand the `next` and transition targets that point at it. The visitor gets a page with\n * only navigation on it, which is visible to the author in the flow builder and recoverable there.\n *\n * When `normalizeWhen` is provided, each transition's `when` is laundered through it (the same field\n * condition normalization); a transition whose `when` strips to nothing (an operand field was deleted)\n * is dropped rather than kept as an always-true route that would force navigation.\n */\nexport const normalizeFlow = (\n\traw: unknown,\n\tfieldKeys: string[],\n\tnormalizeWhen?: (raw: unknown) => Where | undefined\n): FormFlow | undefined => {\n\tif (!isRecord(raw) || !Array.isArray(raw.steps)) {\n\t\treturn undefined\n\t}\n\n\tconst knownFields = new Set(fieldKeys)\n\n\tconst rawSteps = raw.steps.filter(\n\t\t(s): s is Record<string, unknown> => isRecord(s) && typeof s.id === 'string'\n\t)\n\n\tconst knownIds = new Set(rawSteps.map((s) => s.id as string))\n\n\tif (knownIds.size < 2) {\n\t\treturn undefined\n\t}\n\n\tconst seenFields = new Set<string>()\n\n\tconst steps: FlowStep[] = rawSteps.map((s) => {\n\t\tconst id = s.id as string\n\n\t\tconst fields = Array.isArray(s.fields)\n\t\t\t? s.fields.filter((f): f is string => {\n\t\t\t\t\tif (typeof f !== 'string' || !knownFields.has(f) || seenFields.has(f)) return false\n\t\t\t\t\tseenFields.add(f)\n\t\t\t\t\treturn true\n\t\t\t\t})\n\t\t\t: []\n\n\t\tconst rawTransitions = Array.isArray(s.transitions) ? s.transitions : []\n\t\tconst transitions = rawTransitions\n\t\t\t.filter(\n\t\t\t\t(t): t is Record<string, unknown> =>\n\t\t\t\t\tisRecord(t) &&\n\t\t\t\t\ttypeof t.to === 'string' &&\n\t\t\t\t\tknownIds.has(t.to as string) &&\n\t\t\t\t\tisRecord(t.when)\n\t\t\t)\n\t\t\t.map((t) => ({\n\t\t\t\twhen: normalizeWhen ? normalizeWhen(t.when) : (t.when as Where),\n\t\t\t\tto: t.to as string,\n\t\t\t}))\n\t\t\t.filter((t): t is { when: Where; to: string } => t.when !== undefined)\n\n\t\tconst next =\n\t\t\ts.next === null\n\t\t\t\t? null\n\t\t\t\t: typeof s.next === 'string' && knownIds.has(s.next)\n\t\t\t\t\t? (s.next as string)\n\t\t\t\t\t: undefined\n\n\t\tconst step: FlowStep = { id, fields }\n\t\tif (typeof s.title === 'string') step.title = s.title\n\t\tif (transitions.length > 0) step.transitions = transitions\n\t\tif (next !== undefined) step.next = next\n\n\t\treturn step\n\t})\n\n\treturn { steps }\n}\n"],"mappings":";AAGA,MAAM,YAAY,MACjB,MAAM,QAAQ,OAAO,MAAM,YAAY,CAAC,MAAM,QAAQ,CAAC;;;;;;;;;;;;;;;;;;;;AAqBxD,MAAa,iBACZ,KACA,WACA,kBAC0B;CAC1B,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC,MAAM,QAAQ,IAAI,KAAK,GAC7C;CAGD,MAAM,cAAc,IAAI,IAAI,SAAS;CAErC,MAAM,WAAW,IAAI,MAAM,QACzB,MAAoC,SAAS,CAAC,KAAK,OAAO,EAAE,OAAO,QACrE;CAEA,MAAM,WAAW,IAAI,IAAI,SAAS,KAAK,MAAM,EAAE,EAAY,CAAC;CAE5D,IAAI,SAAS,OAAO,GACnB;CAGD,MAAM,6BAAa,IAAI,IAAY;CA2CnC,OAAO,EAAE,OAzCiB,SAAS,KAAK,MAAM;EAC7C,MAAM,KAAK,EAAE;EAEb,MAAM,SAAS,MAAM,QAAQ,EAAE,MAAM,IAClC,EAAE,OAAO,QAAQ,MAAmB;GACpC,IAAI,OAAO,MAAM,YAAY,CAAC,YAAY,IAAI,CAAC,KAAK,WAAW,IAAI,CAAC,GAAG,OAAO;GAC9E,WAAW,IAAI,CAAC;GAChB,OAAO;EACR,CAAC,IACA,CAAC;EAGJ,MAAM,eADiB,MAAM,QAAQ,EAAE,WAAW,IAAI,EAAE,cAAc,CAAC,GAErE,QACC,MACA,SAAS,CAAC,KACV,OAAO,EAAE,OAAO,YAChB,SAAS,IAAI,EAAE,EAAY,KAC3B,SAAS,EAAE,IAAI,CACjB,EACC,KAAK,OAAO;GACZ,MAAM,gBAAgB,cAAc,EAAE,IAAI,IAAK,EAAE;GACjD,IAAI,EAAE;EACP,EAAE,EACD,QAAQ,MAAwC,EAAE,SAAS,KAAA,CAAS;EAEtE,MAAM,OACL,EAAE,SAAS,OACR,OACA,OAAO,EAAE,SAAS,YAAY,SAAS,IAAI,EAAE,IAAI,IAC/C,EAAE,OACH,KAAA;EAEL,MAAM,OAAiB;GAAE;GAAI;EAAO;EACpC,IAAI,OAAO,EAAE,UAAU,UAAU,KAAK,QAAQ,EAAE;EAChD,IAAI,YAAY,SAAS,GAAG,KAAK,cAAc;EAC/C,IAAI,SAAS,KAAA,GAAW,KAAK,OAAO;EAEpC,OAAO;CACR,CAEa,EAAE;AAChB"}

package/dist/flow/stepLabel.js

@@ -0,0 +1,15 @@
+//#region src/flow/stepLabel.ts
+/**
+* Display label for a step: its trimmed title, else the fallback template with
+* `{n}` replaced by the 1-based index. Step ids never surface in the UI.
+* Lives with the flow engine (not the admin client module) because the frontend
+* `<FormSteps>` indicator resolves labels with the same semantics.
+*/
+const stepLabel = (step, index, fallbackTemplate) => {
+	const title = step.title?.trim();
+	return title !== void 0 && title.length > 0 ? title : fallbackTemplate.replace("{n}", String(index + 1));
+};
+//#endregion
+export { stepLabel };
+
+//# sourceMappingURL=stepLabel.js.map

package/dist/flow/stepLabel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stepLabel.js","names":[],"sources":["../../src/flow/stepLabel.ts"],"sourcesContent":["import type { FlowStep } from './types'\n\n/**\n * Display label for a step: its trimmed title, else the fallback template with\n * `{n}` replaced by the 1-based index. Step ids never surface in the UI.\n * Lives with the flow engine (not the admin client module) because the frontend\n * `<FormSteps>` indicator resolves labels with the same semantics.\n */\nexport const stepLabel = (\n\tstep: Pick<FlowStep, 'title'>,\n\tindex: number,\n\tfallbackTemplate: string\n): string => {\n\tconst title = step.title?.trim()\n\treturn title !== undefined && title.length > 0\n\t\t? title\n\t\t: fallbackTemplate.replace('{n}', String(index + 1))\n}\n"],"mappings":";;;;;;;AAQA,MAAa,aACZ,MACA,OACA,qBACY;CACZ,MAAM,QAAQ,KAAK,OAAO,KAAK;CAC/B,OAAO,UAAU,KAAA,KAAa,MAAM,SAAS,IAC1C,QACA,iBAAiB,QAAQ,OAAO,OAAO,QAAQ,CAAC,CAAC;AACrD"}

package/dist/flow/types.d.ts

@@ -9,9 +9,18 @@ type FlowTransition = {
 /** A flow step: a named group of fields, ordered transitions, and a default next edge. */
 type FlowStep = {
   id: string;
-  title?: string; /** Field machine names rendered in this step (a subset of the form's fields). */
-  fields: string[]; /** Default next step id when no transition matches. Absent -> this step is terminal. */
-  next?: string; /** Ordered conditional edges; the first whose `when` matches the answers wins. */
+  title?: string;
+  /**
+   * Field keys rendered in this step (a subset of the form's fields): machine names for named
+   * fields, block row ids for bare (nameless) blocks. See `fieldKey`.
+   */
+  fields: string[];
+  /**
+   * Default next edge when no transition matches. Absent -> fall through to the next step in
+   * array order (the last step ends the form). `null` -> explicit end of form regardless of
+   * position. A step id -> jump to that step.
+   */
+  next?: string | null; /** Ordered conditional edges; the first whose `when` matches the answers wins. */
   transitions?: FlowTransition[];
 };
 /** A serializable multi-step flow layered over the form's flat field list. */

package/dist/flow/types.js

@@ -0,0 +1,11 @@
+//#region src/flow/types.ts
+/**
+* Reserved value the flow builder's next select maps to `next: null` (explicit end of form).
+* Builder-generated step ids are UUIDs (hex digits + dashes) and can never equal it;
+* `validateFlow` rejects API-authored steps claiming it as an id so the mapping stays unambiguous.
+*/
+const END_OF_FORM = "__end__";
+//#endregion
+export { END_OF_FORM };
+
+//# sourceMappingURL=types.js.map

package/dist/flow/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","names":[],"sources":["../../src/flow/types.ts"],"sourcesContent":["import type { Where } from 'payload'\n\n/** A conditional edge: when `when` matches the answers, route to step `to`. */\nexport type FlowTransition = { when: Where; to: string }\n\n/** A flow step: a named group of fields, ordered transitions, and a default next edge. */\nexport type FlowStep = {\n\tid: string\n\ttitle?: string\n\t/**\n\t * Field keys rendered in this step (a subset of the form's fields): machine names for named\n\t * fields, block row ids for bare (nameless) blocks. See `fieldKey`.\n\t */\n\tfields: string[]\n\t/**\n\t * Default next edge when no transition matches. Absent -> fall through to the next step in\n\t * array order (the last step ends the form). `null` -> explicit end of form regardless of\n\t * position. A step id -> jump to that step.\n\t */\n\tnext?: string | null\n\t/** Ordered conditional edges; the first whose `when` matches the answers wins. */\n\ttransitions?: FlowTransition[]\n}\n\n/** A serializable multi-step flow layered over the form's flat field list. */\nexport type FormFlow = { steps: FlowStep[] }\n\n/**\n * Reserved value the flow builder's next select maps to `next: null` (explicit end of form).\n * Builder-generated step ids are UUIDs (hex digits + dashes) and can never equal it;\n * `validateFlow` rejects API-authored steps claiming it as an id so the mapping stays unambiguous.\n */\nexport const END_OF_FORM = '__end__'\n"],"mappings":";;;;;;AAgCA,MAAa,cAAc"}

package/dist/form/pollState.d.ts

@@ -0,0 +1,23 @@
+//#region src/form/pollState.d.ts
+/** Poll settings as loaded from a forms document (server) or a `FormDocument` (client). */
+type PollConfigLike = {
+  resultsField?: string | null;
+  resultsVisibility?: string | null;
+  closesAt?: string | null;
+  allowChange?: boolean | null; /** The outcome-resolution strategy slug (`poll.types` registry). Absent is treated as `manual`. */
+  type?: string | null;
+  optionSource?: string | null;
+  sourceConfig?: Record<string, unknown> | null;
+  outcome?: {
+    winningValues?: (string | null)[] | null;
+    resolvedAt?: string | null;
+  } | null;
+};
+/**
+ * Whether the poll's `closesAt` has passed. An unset or unparseable `closesAt` never closes;
+ * framework-agnostic so the server guard, the results gate, and the client `<Poll>` agree.
+ */
+declare const isPollClosed: (poll: PollConfigLike | null | undefined, now?: number) => boolean;
+//#endregion
+export { PollConfigLike, isPollClosed };
+//# sourceMappingURL=pollState.d.ts.map

package/dist/form/pollState.js

@@ -0,0 +1,17 @@
+//#region src/form/pollState.ts
+/** Narrow a forms document's untyped `poll` member. */
+const pollConfigOf = (poll) => poll != null && typeof poll === "object" ? poll : void 0;
+/**
+* Whether the poll's `closesAt` has passed. An unset or unparseable `closesAt` never closes;
+* framework-agnostic so the server guard, the results gate, and the client `<Poll>` agree.
+*/
+const isPollClosed = (poll, now = Date.now()) => {
+	const closesAt = poll?.closesAt;
+	if (typeof closesAt !== "string" || closesAt.length === 0) return false;
+	const ts = Date.parse(closesAt);
+	return Number.isFinite(ts) && ts <= now;
+};
+//#endregion
+export { isPollClosed, pollConfigOf };
+
+//# sourceMappingURL=pollState.js.map

package/dist/form/pollState.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pollState.js","names":[],"sources":["../../src/form/pollState.ts"],"sourcesContent":["/** Poll settings as loaded from a forms document (server) or a `FormDocument` (client). */\nexport type PollConfigLike = {\n\tresultsField?: string | null\n\tresultsVisibility?: string | null\n\tclosesAt?: string | null\n\tallowChange?: boolean | null\n\t/** The outcome-resolution strategy slug (`poll.types` registry). Absent is treated as `manual`. */\n\ttype?: string | null\n\toptionSource?: string | null\n\tsourceConfig?: Record<string, unknown> | null\n\toutcome?: { winningValues?: (string | null)[] | null; resolvedAt?: string | null } | null\n}\n\n/** Narrow a forms document's untyped `poll` member. */\nexport const pollConfigOf = (poll: unknown): PollConfigLike | undefined =>\n\tpoll != null && typeof poll === 'object' ? (poll as PollConfigLike) : undefined\n\n/**\n * Whether the poll's `closesAt` has passed. An unset or unparseable `closesAt` never closes;\n * framework-agnostic so the server guard, the results gate, and the client `<Poll>` agree.\n */\nexport const isPollClosed = (\n\tpoll: PollConfigLike | null | undefined,\n\tnow: number = Date.now()\n): boolean => {\n\tconst closesAt = poll?.closesAt\n\tif (typeof closesAt !== 'string' || closesAt.length === 0) {\n\t\treturn false\n\t}\n\tconst ts = Date.parse(closesAt)\n\treturn Number.isFinite(ts) && ts <= now\n}\n"],"mappings":";;AAcA,MAAa,gBAAgB,SAC5B,QAAQ,QAAQ,OAAO,SAAS,WAAY,OAA0B,KAAA;;;;;AAMvE,MAAa,gBACZ,MACA,MAAc,KAAK,IAAI,MACV;CACb,MAAM,WAAW,MAAM;CACvB,IAAI,OAAO,aAAa,YAAY,SAAS,WAAW,GACvD,OAAO;CAER,MAAM,KAAK,KAAK,MAAM,QAAQ;CAC9B,OAAO,OAAO,SAAS,EAAE,KAAK,MAAM;AACrC"}

package/dist/form/toFormDocument.d.ts

@@ -0,0 +1,110 @@
+import { PollOption } from "../poll/definePollOptionSource.js";
+import { CalcResolved } from "../calc/evaluate.js";
+import { ConsentStatements } from "../consent/resolveConsentStatements.js";
+import { FormDocument } from "./types.js";
+
+//#region src/form/toFormDocument.d.ts
+type ToFormDocumentOptions = {
+  /**
+   * Source-resolved poll options (from `resolvePollOptions`), injected as the options of the
+   * field instance named by the form's `poll.resultsField` so the client renders the host's
+   * current choices instead of hand-authored ones.
+   */
+  pollOptions?: PollOption[];
+  /**
+   * Source-resolved consent statements (from `resolveConsentStatements`), injected into the
+   * consent field instances they name. A form stores only a source id, so without these its
+   * consent fields render with no statement at all.
+   */
+  consentStatements?: ConsentStatements;
+  /**
+   * Resolve an internal redirect `reference` to a same-site URL. Called only when
+   * `response.type === 'redirect'`, a `reference` is present, and no `redirect.url` is set. Keep it
+   * sync: operate on the already-loaded (populated) reference, since resolving a Doc to a URL is host
+   * routing knowledge the plugin cannot supply. The result is written to `redirect.url`, so `<Form>`
+   * navigates with no client change.
+   */
+  resolveRedirect?: (reference: {
+    relationTo: string;
+    value: number | string | object;
+  }) => string | null | undefined;
+};
+/**
+ * Narrows a Payload-generated form document (from `getPayload().findByID()` or `fetch`) to
+ * `FormDocument` without an unsafe `as` cast. Handles the small structural mismatches between
+ * the auto-generated collection types and what `<Form>` expects:
+ * - `fields` may be a typed blocks-union array or null; normalized to `FormFieldInstance[]`
+ *   (nameless bare rows, e.g. message blocks, pass through with their row `id` intact)
+ * - `flow` is stored as opaque JSON; typed as `FormFlow | undefined`
+ * - `response` may be null; coerced to `undefined`, otherwise passed through wholesale, which
+ *   includes `response.redirect.reference` (present only when the plugin's `redirectRelationships`
+ *   option is set): `value` may be a bare id (`depth: 0`) or a populated document, and the host
+ *   resolves it to a URL either by writing `redirect.url` or by passing `options.resolveRedirect`
+ * - the button labels (`submitLabel`/`prevLabel`/`nextLabel`) live at the document root now (there
+ *   is no `buttons` group); the non-empty ones are reassembled into `FormDocument.buttons`
+ * - `title` may be null; coerced to `undefined`
+ * - `multistep`/`pollEnabled` are the two top-level form-type flags, coerced to strict booleans
+ * - `poll` may be null; coerced to `undefined` (`resultsField`, `optionSource`, and
+ *   `sourceConfig` are dropped: server-side only; `outcome` passes through `winningValues` only)
+ *
+ * Unknown keys survive on `response` but not on `poll`, which is deliberate rather than incidental.
+ * `response` is a visitor-facing group a host is meant to extend (`overrides.forms.fields`) and read
+ * back off `FormDocument` in custom chrome, so it is cast wholesale. `poll` is plugin-owned config
+ * that is split between
+ * client-safe lifecycle state and server-only members, so it is rebuilt from an allowlist: a
+ * passthrough would ship whatever a host put in `sourceConfig` (domain config, ids, credentials)
+ * to every anonymous visitor. Adding a client-visible poll member means naming it here.
+ *
+ * Pure and framework-agnostic (no 'use client'): safe to call from a Server Component or any
+ * other server-side code before handing the result to the client `<Form>`.
+ */
+declare function toFormDocument(form: {
+  id: number | string;
+  fields?: {
+    blockType: string;
+    name?: string;
+    [key: string]: unknown;
+  }[] | null;
+  flow?: unknown;
+  response?: {
+    type?: string | null;
+    message?: unknown;
+    redirect?: {
+      url?: string | null;
+      reference?: {
+        relationTo?: string | null;
+        value?: number | string | object | null;
+      } | null;
+    } | null;
+  } | null;
+  submitLabel?: string | null;
+  prevLabel?: string | null;
+  nextLabel?: string | null;
+  title?: string | null;
+  multistep?: boolean | null;
+  pollEnabled?: boolean | null;
+  poll?: {
+    resultsField?: string | null;
+    resultsVisibility?: string | null;
+    closesAt?: string | null;
+    allowChange?: boolean | null;
+    outcome?: {
+      winningValues?: (string | null)[] | null;
+    } | null;
+  } | null;
+  /**
+   * Consent statements resolved onto the doc by the plugin's forms `afterRead` hook (when
+   * `consent.sources` is set), so consent renders on any fetch path (modal/client, not just RSC).
+   * An explicit `options.consentStatements` takes precedence when both are present.
+   */
+  consentStatements?: ConsentStatements;
+  /**
+   * Calc source values resolved onto the doc by the plugin's forms `afterRead` hook (when calc
+   * sources are registered and used); passed through so the client's live preview computes with
+   * real values. `functions` can never ride a document, hence the Pick.
+   */
+  calcResolved?: Pick<CalcResolved, 'sources' | 'weights'>;
+}, options?: ToFormDocumentOptions): FormDocument;
+//#endregion
+export { ToFormDocumentOptions, toFormDocument };
+//# sourceMappingURL=toFormDocument.d.ts.map

package/dist/form/toFormDocument.js

@@ -0,0 +1,89 @@
+import { applyPollOptions } from "../poll/applyPollOptions.js";
+import { applyConsentStatements } from "../consent/applyConsentStatements.js";
+//#region src/form/toFormDocument.ts
+/**
+* Reassemble the client button labels from the document's top-level `submitLabel`/`prevLabel`/
+* `nextLabel` fields, keeping only non-empty strings (mirroring the client's own `storedLabel`
+* fallback). Returns `undefined` when the author set no label, so the client uses its defaults.
+*/
+const buttonSettingsOf = (form) => {
+	const label = (value) => typeof value === "string" && value.length > 0 ? value : void 0;
+	const settings = {};
+	const submitLabel = label(form.submitLabel);
+	const prevLabel = label(form.prevLabel);
+	const nextLabel = label(form.nextLabel);
+	if (submitLabel !== void 0) settings.submitLabel = submitLabel;
+	if (prevLabel !== void 0) settings.prevLabel = prevLabel;
+	if (nextLabel !== void 0) settings.nextLabel = nextLabel;
+	return Object.keys(settings).length > 0 ? settings : void 0;
+};
+/**
+* Narrows a Payload-generated form document (from `getPayload().findByID()` or `fetch`) to
+* `FormDocument` without an unsafe `as` cast. Handles the small structural mismatches between
+* the auto-generated collection types and what `<Form>` expects:
+* - `fields` may be a typed blocks-union array or null; normalized to `FormFieldInstance[]`
+*   (nameless bare rows, e.g. message blocks, pass through with their row `id` intact)
+* - `flow` is stored as opaque JSON; typed as `FormFlow | undefined`
+* - `response` may be null; coerced to `undefined`, otherwise passed through wholesale, which
+*   includes `response.redirect.reference` (present only when the plugin's `redirectRelationships`
+*   option is set): `value` may be a bare id (`depth: 0`) or a populated document, and the host
+*   resolves it to a URL either by writing `redirect.url` or by passing `options.resolveRedirect`
+* - the button labels (`submitLabel`/`prevLabel`/`nextLabel`) live at the document root now (there
+*   is no `buttons` group); the non-empty ones are reassembled into `FormDocument.buttons`
+* - `title` may be null; coerced to `undefined`
+* - `multistep`/`pollEnabled` are the two top-level form-type flags, coerced to strict booleans
+* - `poll` may be null; coerced to `undefined` (`resultsField`, `optionSource`, and
+*   `sourceConfig` are dropped: server-side only; `outcome` passes through `winningValues` only)
+*
+* Unknown keys survive on `response` but not on `poll`, which is deliberate rather than incidental.
+* `response` is a visitor-facing group a host is meant to extend (`overrides.forms.fields`) and read
+* back off `FormDocument` in custom chrome, so it is cast wholesale. `poll` is plugin-owned config
+* that is split between
+* client-safe lifecycle state and server-only members, so it is rebuilt from an allowlist: a
+* passthrough would ship whatever a host put in `sourceConfig` (domain config, ids, credentials)
+* to every anonymous visitor. Adding a client-visible poll member means naming it here.
+*
+* Pure and framework-agnostic (no 'use client'): safe to call from a Server Component or any
+* other server-side code before handing the result to the client `<Form>`.
+*/
+function toFormDocument(form, options) {
+	const rawWinningValues = form.poll?.outcome?.winningValues;
+	const winningValues = Array.isArray(rawWinningValues) ? rawWinningValues.filter((value) => typeof value === "string" && value.length > 0) : [];
+	const poll = form.poll ? {
+		resultsVisibility: form.poll.resultsVisibility ?? void 0,
+		closesAt: form.poll.closesAt ?? void 0,
+		...form.poll.allowChange === true ? { allowChange: true } : {},
+		...winningValues.length > 0 ? { outcome: { winningValues } } : {}
+	} : void 0;
+	let fields = form.fields ?? [];
+	if (options?.pollOptions) fields = applyPollOptions(fields, form.poll?.resultsField, options.pollOptions);
+	const consentStatements = options?.consentStatements ?? form.consentStatements;
+	if (consentStatements) fields = applyConsentStatements(fields, consentStatements);
+	let response = form.response ?? void 0;
+	if (options?.resolveRedirect && response?.type === "redirect" && response.redirect?.reference && !response.redirect.url) {
+		const url = options.resolveRedirect(response.redirect.reference);
+		if (url) response = {
+			...response,
+			redirect: {
+				...response.redirect,
+				url
+			}
+		};
+	}
+	return {
+		id: form.id,
+		fields,
+		flow: form.flow,
+		response,
+		buttons: buttonSettingsOf(form),
+		title: form.title ?? void 0,
+		multistep: form.multistep === true,
+		pollEnabled: form.pollEnabled === true,
+		poll,
+		calcResolved: form.calcResolved
+	};
+}
+//#endregion
+export { toFormDocument };
+
+//# sourceMappingURL=toFormDocument.js.map

package/dist/form/toFormDocument.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toFormDocument.js","names":[],"sources":["../../src/form/toFormDocument.ts"],"sourcesContent":["import type { CalcResolved } from '../calc/evaluate'\nimport { applyConsentStatements } from '../consent/applyConsentStatements'\nimport type { ConsentStatements } from '../consent/resolveConsentStatements'\nimport type { FormFlow } from '../flow/types'\nimport { applyPollOptions } from '../poll/applyPollOptions'\nimport type { PollOption } from '../poll/definePollOptionSource'\nimport type { FormFieldInstance } from '../submissions/types'\nimport type { FormButtonSettings, FormDocument, FormResponseSettings } from './types'\n\nexport type ToFormDocumentOptions = {\n\t/**\n\t * Source-resolved poll options (from `resolvePollOptions`), injected as the options of the\n\t * field instance named by the form's `poll.resultsField` so the client renders the host's\n\t * current choices instead of hand-authored ones.\n\t */\n\tpollOptions?: PollOption[]\n\t/**\n\t * Source-resolved consent statements (from `resolveConsentStatements`), injected into the\n\t * consent field instances they name. A form stores only a source id, so without these its\n\t * consent fields render with no statement at all.\n\t */\n\tconsentStatements?: ConsentStatements\n\t/**\n\t * Resolve an internal redirect `reference` to a same-site URL. Called only when\n\t * `response.type === 'redirect'`, a `reference` is present, and no `redirect.url` is set. Keep it\n\t * sync: operate on the already-loaded (populated) reference, since resolving a Doc to a URL is host\n\t * routing knowledge the plugin cannot supply. The result is written to `redirect.url`, so `<Form>`\n\t * navigates with no client change.\n\t */\n\tresolveRedirect?: (reference: {\n\t\trelationTo: string\n\t\tvalue: number | string | object\n\t}) => string | null | undefined\n}\n\n/**\n * Reassemble the client button labels from the document's top-level `submitLabel`/`prevLabel`/\n * `nextLabel` fields, keeping only non-empty strings (mirroring the client's own `storedLabel`\n * fallback). Returns `undefined` when the author set no label, so the client uses its defaults.\n */\nconst buttonSettingsOf = (form: {\n\tsubmitLabel?: string | null\n\tprevLabel?: string | null\n\tnextLabel?: string | null\n}): FormButtonSettings | undefined => {\n\tconst label = (value: unknown): string | undefined =>\n\t\ttypeof value === 'string' && value.length > 0 ? value : undefined\n\tconst settings: FormButtonSettings = {}\n\tconst submitLabel = label(form.submitLabel)\n\tconst prevLabel = label(form.prevLabel)\n\tconst nextLabel = label(form.nextLabel)\n\tif (submitLabel !== undefined) settings.submitLabel = submitLabel\n\tif (prevLabel !== undefined) settings.prevLabel = prevLabel\n\tif (nextLabel !== undefined) settings.nextLabel = nextLabel\n\treturn Object.keys(settings).length > 0 ? settings : undefined\n}\n\n/**\n * Narrows a Payload-generated form document (from `getPayload().findByID()` or `fetch`) to\n * `FormDocument` without an unsafe `as` cast. Handles the small structural mismatches between\n * the auto-generated collection types and what `<Form>` expects:\n * - `fields` may be a typed blocks-union array or null; normalized to `FormFieldInstance[]`\n *   (nameless bare rows, e.g. message blocks, pass through with their row `id` intact)\n * - `flow` is stored as opaque JSON; typed as `FormFlow | undefined`\n * - `response` may be null; coerced to `undefined`, otherwise passed through wholesale, which\n *   includes `response.redirect.reference` (present only when the plugin's `redirectRelationships`\n *   option is set): `value` may be a bare id (`depth: 0`) or a populated document, and the host\n *   resolves it to a URL either by writing `redirect.url` or by passing `options.resolveRedirect`\n * - the button labels (`submitLabel`/`prevLabel`/`nextLabel`) live at the document root now (there\n *   is no `buttons` group); the non-empty ones are reassembled into `FormDocument.buttons`\n * - `title` may be null; coerced to `undefined`\n * - `multistep`/`pollEnabled` are the two top-level form-type flags, coerced to strict booleans\n * - `poll` may be null; coerced to `undefined` (`resultsField`, `optionSource`, and\n *   `sourceConfig` are dropped: server-side only; `outcome` passes through `winningValues` only)\n *\n * Unknown keys survive on `response` but not on `poll`, which is deliberate rather than incidental.\n * `response` is a visitor-facing group a host is meant to extend (`overrides.forms.fields`) and read\n * back off `FormDocument` in custom chrome, so it is cast wholesale. `poll` is plugin-owned config\n * that is split between\n * client-safe lifecycle state and server-only members, so it is rebuilt from an allowlist: a\n * passthrough would ship whatever a host put in `sourceConfig` (domain config, ids, credentials)\n * to every anonymous visitor. Adding a client-visible poll member means naming it here.\n *\n * Pure and framework-agnostic (no 'use client'): safe to call from a Server Component or any\n * other server-side code before handing the result to the client `<Form>`.\n */\nexport function toFormDocument(\n\tform: {\n\t\tid: number | string\n\t\tfields?: { blockType: string; name?: string; [key: string]: unknown }[] | null\n\t\tflow?: unknown\n\t\tresponse?: {\n\t\t\ttype?: string | null\n\t\t\tmessage?: unknown\n\t\t\tredirect?: {\n\t\t\t\turl?: string | null\n\t\t\t\treference?: { relationTo?: string | null; value?: number | string | object | null } | null\n\t\t\t} | null\n\t\t} | null\n\t\tsubmitLabel?: string | null\n\t\tprevLabel?: string | null\n\t\tnextLabel?: string | null\n\t\ttitle?: string | null\n\t\tmultistep?: boolean | null\n\t\tpollEnabled?: boolean | null\n\t\tpoll?: {\n\t\t\tresultsField?: string | null\n\t\t\tresultsVisibility?: string | null\n\t\t\tclosesAt?: string | null\n\t\t\tallowChange?: boolean | null\n\t\t\toutcome?: { winningValues?: (string | null)[] | null } | null\n\t\t} | null\n\t\t/**\n\t\t * Consent statements resolved onto the doc by the plugin's forms `afterRead` hook (when\n\t\t * `consent.sources` is set), so consent renders on any fetch path (modal/client, not just RSC).\n\t\t * An explicit `options.consentStatements` takes precedence when both are present.\n\t\t */\n\t\tconsentStatements?: ConsentStatements\n\t\t/**\n\t\t * Calc source values resolved onto the doc by the plugin's forms `afterRead` hook (when calc\n\t\t * sources are registered and used); passed through so the client's live preview computes with\n\t\t * real values. `functions` can never ride a document, hence the Pick.\n\t\t */\n\t\tcalcResolved?: Pick<CalcResolved, 'sources' | 'weights'>\n\t},\n\toptions?: ToFormDocumentOptions\n): FormDocument {\n\tconst rawWinningValues = form.poll?.outcome?.winningValues\n\tconst winningValues = Array.isArray(rawWinningValues)\n\t\t? rawWinningValues.filter(\n\t\t\t\t(value): value is string => typeof value === 'string' && value.length > 0\n\t\t\t)\n\t\t: []\n\tconst poll = form.poll\n\t\t? {\n\t\t\t\tresultsVisibility: (form.poll.resultsVisibility ?? undefined) as\n\t\t\t\t\t| 'afterVote'\n\t\t\t\t\t| 'afterClose'\n\t\t\t\t\t| undefined,\n\t\t\t\tclosesAt: form.poll.closesAt ?? undefined,\n\t\t\t\t...(form.poll.allowChange === true ? { allowChange: true } : {}),\n\t\t\t\t...(winningValues.length > 0 ? { outcome: { winningValues } } : {}),\n\t\t\t}\n\t\t: undefined\n\tlet fields = (form.fields ?? []) as FormFieldInstance[]\n\tif (options?.pollOptions) {\n\t\tfields = applyPollOptions(fields, form.poll?.resultsField, options.pollOptions)\n\t}\n\tconst consentStatements = options?.consentStatements ?? form.consentStatements\n\tif (consentStatements) {\n\t\tfields = applyConsentStatements(fields, consentStatements)\n\t}\n\tlet response = (form.response as FormResponseSettings | null | undefined) ?? undefined\n\t// A host that passes `resolveRedirect` gets internal references turned into `redirect.url` (all\n\t// `<Form>` navigates by), but only when the author set no explicit url. Non-mutating: clone the group.\n\tif (\n\t\toptions?.resolveRedirect &&\n\t\tresponse?.type === 'redirect' &&\n\t\tresponse.redirect?.reference &&\n\t\t!response.redirect.url\n\t) {\n\t\tconst url = options.resolveRedirect(response.redirect.reference)\n\t\tif (url) {\n\t\t\tresponse = { ...response, redirect: { ...response.redirect, url } }\n\t\t}\n\t}\n\treturn {\n\t\tid: form.id,\n\t\tfields,\n\t\tflow: form.flow as FormFlow | undefined,\n\t\tresponse,\n\t\tbuttons: buttonSettingsOf(form),\n\t\ttitle: form.title ?? undefined,\n\t\tmultistep: form.multistep === true,\n\t\tpollEnabled: form.pollEnabled === true,\n\t\tpoll,\n\t\tcalcResolved: form.calcResolved,\n\t}\n}\n"],"mappings":";;;;;;;;AAwCA,MAAM,oBAAoB,SAIY;CACrC,MAAM,SAAS,UACd,OAAO,UAAU,YAAY,MAAM,SAAS,IAAI,QAAQ,KAAA;CACzD,MAAM,WAA+B,CAAC;CACtC,MAAM,cAAc,MAAM,KAAK,WAAW;CAC1C,MAAM,YAAY,MAAM,KAAK,SAAS;CACtC,MAAM,YAAY,MAAM,KAAK,SAAS;CACtC,IAAI,gBAAgB,KAAA,GAAW,SAAS,cAAc;CACtD,IAAI,cAAc,KAAA,GAAW,SAAS,YAAY;CAClD,IAAI,cAAc,KAAA,GAAW,SAAS,YAAY;CAClD,OAAO,OAAO,KAAK,QAAQ,EAAE,SAAS,IAAI,WAAW,KAAA;AACtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+BA,SAAgB,eACf,MAsCA,SACe;CACf,MAAM,mBAAmB,KAAK,MAAM,SAAS;CAC7C,MAAM,gBAAgB,MAAM,QAAQ,gBAAgB,IACjD,iBAAiB,QAChB,UAA2B,OAAO,UAAU,YAAY,MAAM,SAAS,CACzE,IACC,CAAC;CACJ,MAAM,OAAO,KAAK,OACf;EACA,mBAAoB,KAAK,KAAK,qBAAqB,KAAA;EAInD,UAAU,KAAK,KAAK,YAAY,KAAA;EAChC,GAAI,KAAK,KAAK,gBAAgB,OAAO,EAAE,aAAa,KAAK,IAAI,CAAC;EAC9D,GAAI,cAAc,SAAS,IAAI,EAAE,SAAS,EAAE,cAAc,EAAE,IAAI,CAAC;CAClE,IACC,KAAA;CACH,IAAI,SAAU,KAAK,UAAU,CAAC;CAC9B,IAAI,SAAS,aACZ,SAAS,iBAAiB,QAAQ,KAAK,MAAM,cAAc,QAAQ,WAAW;CAE/E,MAAM,oBAAoB,SAAS,qBAAqB,KAAK;CAC7D,IAAI,mBACH,SAAS,uBAAuB,QAAQ,iBAAiB;CAE1D,IAAI,WAAY,KAAK,YAAwD,KAAA;CAG7E,IACC,SAAS,mBACT,UAAU,SAAS,cACnB,SAAS,UAAU,aACnB,CAAC,SAAS,SAAS,KAClB;EACD,MAAM,MAAM,QAAQ,gBAAgB,SAAS,SAAS,SAAS;EAC/D,IAAI,KACH,WAAW;GAAE,GAAG;GAAU,UAAU;IAAE,GAAG,SAAS;IAAU;GAAI;EAAE;CAEpE;CACA,OAAO;EACN,IAAI,KAAK;EACT;EACA,MAAM,KAAK;EACX;EACA,SAAS,iBAAiB,IAAI;EAC9B,OAAO,KAAK,SAAS,KAAA;EACrB,WAAW,KAAK,cAAc;EAC9B,aAAa,KAAK,gBAAgB;EAClC;EACA,cAAc,KAAK;CACpB;AACD"}