@vectoriox/iox-ui 4.32.0 → 4.33.1

package/forms-core/index.d.ts

@@ -307,5 +307,70 @@ declare function addableActions(existing?: readonly {
     type: string;
 }[]): ActionDescriptor[];
 
-export { ACTION_DESCRIPTORS, ControlType, DEFAULT_EN_MESSAGES, FIELD_NODE_TYPE, FORM_ERROR_KEYS, FORM_NODE_TYPE, FeedbackTiming, IMPLIED_PATTERN, INITIAL_FORM_STATE, MESSAGE_NAMESPACE, MULTI_VALUE_CONTROLS, PATTERN_MESSAGE_KEYS, PATTERN_PRESETS, PATTERN_PRESET_OPTIONS, PatternPreset, RULE_DESCRIPTORS, RULE_MESSAGE_KEYS, RuleName, RuleParamKind, STORE_ACTION, addableActions, addableRules, applyServerErrors, collectFieldNodes, collectFormSpec, deriveFieldName, firstInvalidField, onFieldBlur, onFieldChange, onSubmitAttempt, resetFormState, rulesFor, shouldShowError, uniqueFieldName, validateField, validateForm };
-export type { ActionDescriptor, FieldError, FieldOption, FieldOptionSource, FieldResult, FieldSpec, FormNodeLike, FormResult, FormRuntimeState, FormSpec, RuleDescriptor, SubmitAction, ValidationRule };
+/**
+ * The submit transport CONTRACT — what a host must provide to make a form actually send.
+ *
+ * The Form component deliberately owns no HTTP: the builder canvas must never post (an author
+ * clicking Submit while designing would file a real submission), and the SSR engine posts through
+ * Angular's HttpClient. What IS shared is everything around the call — the endpoint's shape, the
+ * anti-spam fields, and how the server's answer maps onto the form's state. Those live here so the
+ * two hosts cannot drift, and so a third host (a hand-built integration) has one thing to read.
+ *
+ * ⚠️ Framework-free, like the rest of forms-core. No Angular, no RxJS, no fetch.
+ */
+
+/** The field a honeypot input uses. Must match `iox-cms` `anti-spam.ts` — hence the comment there. */
+declare const HONEYPOT_FIELD = "_iox_hp";
+/** When the form was rendered, so the server can measure fill time. */
+declare const RENDERED_AT_FIELD = "_iox_t";
+/**
+ * What the form hands its host. There is deliberately no `orgId`: the tenant is the HOST's
+ * knowledge, not the form's, and a form that had to be told its org would be one more trait an
+ * author could get wrong.
+ */
+interface SubmitRequest {
+    formId: string;
+    values: Record<string, any>;
+}
+/**
+ * The server's answer, normalised. Mirrors `SubmitResult` in `iox-cms`
+ * `form-submissions.service.ts` — the two are one contract, so change them together.
+ */
+interface SubmitResponse {
+    ok: boolean;
+    /** Per-field verdicts from the server's own validation pass, keyed by field name. */
+    errors?: Record<string, FieldError>;
+    /** Where to send the visitor after a successful submit, when the form has a redirect action. */
+    redirect?: string;
+}
+/**
+ * The one function a host implements. Rejecting (or throwing) means the call never reached the
+ * server — the form shows its Error state, which is the honest thing to show for a dropped network.
+ */
+type FormTransport = (request: SubmitRequest) => Promise<SubmitResponse>;
+/**
+ * The public submit path. Built here rather than interpolated at each call site, so the engine and
+ * any future host cannot disagree about it — and so changing it is one edit.
+ *
+ * Deliberately relative and WITHOUT a leading slash: the engine mounts under a per-org base href.
+ */
+declare function submitEndpointPath(orgId: string, formId: string): string;
+/**
+ * Add the anti-spam fields to the collected values.
+ *
+ * Both are invisible to a real visitor and cost them nothing (decision D12). `renderedAt` is the
+ * time the form was rendered, NOT the time of submit — the server measures the difference to catch
+ * a script that fills and posts instantly.
+ */
+declare function withAntiSpamFields(values: Record<string, any>, renderedAt: number, honeypotValue?: string): Record<string, any>;
+/**
+ * Normalise whatever came back into a `SubmitResponse`.
+ *
+ * Fails CLOSED: anything that is not a recognisable success is treated as a failure. A malformed
+ * body must never show the visitor a Success state for a submission that was not stored — that is
+ * the one lie this feature must not tell.
+ */
+declare function interpretSubmitResponse(body: any): SubmitResponse;
+
+export { ACTION_DESCRIPTORS, ControlType, DEFAULT_EN_MESSAGES, FIELD_NODE_TYPE, FORM_ERROR_KEYS, FORM_NODE_TYPE, FeedbackTiming, HONEYPOT_FIELD, IMPLIED_PATTERN, INITIAL_FORM_STATE, MESSAGE_NAMESPACE, MULTI_VALUE_CONTROLS, PATTERN_MESSAGE_KEYS, PATTERN_PRESETS, PATTERN_PRESET_OPTIONS, PatternPreset, RENDERED_AT_FIELD, RULE_DESCRIPTORS, RULE_MESSAGE_KEYS, RuleName, RuleParamKind, STORE_ACTION, addableActions, addableRules, applyServerErrors, collectFieldNodes, collectFormSpec, deriveFieldName, firstInvalidField, interpretSubmitResponse, onFieldBlur, onFieldChange, onSubmitAttempt, resetFormState, rulesFor, shouldShowError, submitEndpointPath, uniqueFieldName, validateField, validateForm, withAntiSpamFields };
+export type { ActionDescriptor, FieldError, FieldOption, FieldOptionSource, FieldResult, FieldSpec, FormNodeLike, FormResult, FormRuntimeState, FormSpec, FormTransport, RuleDescriptor, SubmitAction, SubmitRequest, SubmitResponse, ValidationRule };

package/index.d.ts

@@ -988,6 +988,44 @@ interface FormRuntimeState {
     submitting: boolean;
 }
 
+/**
+ * The submit transport CONTRACT — what a host must provide to make a form actually send.
+ *
+ * The Form component deliberately owns no HTTP: the builder canvas must never post (an author
+ * clicking Submit while designing would file a real submission), and the SSR engine posts through
+ * Angular's HttpClient. What IS shared is everything around the call — the endpoint's shape, the
+ * anti-spam fields, and how the server's answer maps onto the form's state. Those live here so the
+ * two hosts cannot drift, and so a third host (a hand-built integration) has one thing to read.
+ *
+ * ⚠️ Framework-free, like the rest of forms-core. No Angular, no RxJS, no fetch.
+ */
+
+/**
+ * What the form hands its host. There is deliberately no `orgId`: the tenant is the HOST's
+ * knowledge, not the form's, and a form that had to be told its org would be one more trait an
+ * author could get wrong.
+ */
+interface SubmitRequest {
+    formId: string;
+    values: Record<string, any>;
+}
+/**
+ * The server's answer, normalised. Mirrors `SubmitResult` in `iox-cms`
+ * `form-submissions.service.ts` — the two are one contract, so change them together.
+ */
+interface SubmitResponse {
+    ok: boolean;
+    /** Per-field verdicts from the server's own validation pass, keyed by field name. */
+    errors?: Record<string, FieldError>;
+    /** Where to send the visitor after a successful submit, when the form has a redirect action. */
+    redirect?: string;
+}
+/**
+ * The one function a host implements. Rejecting (or throwing) means the call never reached the
+ * server — the form shows its Error state, which is the honest thing to show for a dropped network.
+ */
+type FormTransport = (request: SubmitRequest) => Promise<SubmitResponse>;
+
 /**
  * How a message KEY becomes text a visitor reads.
  *
@@ -1049,6 +1087,15 @@ declare class FormRuntimeService {
     static ɵprov: i0.ɵɵInjectableDeclaration<FormRuntimeService>;
 }
 
+/**
+ * How a host makes the form actually send. The SSR engine provides one (an HttpClient POST); the
+ * builder canvas deliberately does NOT — an author pressing Submit while designing must never file
+ * a real submission. Without it the component keeps its original behaviour and only emits
+ * `formSubmit`, which is also the escape hatch for a host that wants the transport itself.
+ */
+declare const IOX_FORM_TRANSPORT: InjectionToken<FormTransport>;
+/** Where a successful submit sends the visitor. Provided by the host; absent on the canvas. */
+declare const IOX_FORM_NAVIGATOR: InjectionToken<(url: string) => void>;
 /** Which of the form's four states the canvas / runtime is showing. */
 declare enum FormRenderState {
     Idle = "idle",
@@ -1072,9 +1119,11 @@ declare enum FormRenderState {
  * ⚠️ `novalidate` is deliberate: the browser's native bubbles would pre-empt our own messages,
  * which are styleable, translated and announced. Validation still runs — ours does it.
  */
-declare class IoxFormComponent implements OnChanges {
+declare class IoxFormComponent implements OnChanges, OnInit {
     private readonly runtime;
     private readonly host;
+    private readonly transport;
+    private readonly navigate;
     nodeId: string;
     /** Stable id the submit endpoint resolves the saved spec by. */
     formId: string;
@@ -1094,16 +1143,35 @@ declare class IoxFormComponent implements OnChanges {
     /** Emitted when a submit attempt was refused locally, so a host can react (analytics, focus). */
     validationFailed: EventEmitter<Record<string, any>>;
     childrenHost: ViewContainerRef;
+    /** Exposed to the template so the input's name and the server's check cannot drift. */
+    readonly honeypotField = "_iox_hp";
+    /** When this form was rendered — the fill-time signal the server checks. */
+    private renderedAt;
+    /** Guards against a double submit while a POST is in flight. */
+    private inFlight;
     /**
      * Constructor injection rather than `inject()`, for the same reason as Field: this library's
      * specs construct components directly. `runtime` is provided by THIS component (see
      * `providers`), so every Field created into `childrenHost` resolves this instance by ancestry.
      */
-    constructor(runtime: FormRuntimeService, host: ElementRef<HTMLElement>);
+    constructor(runtime: FormRuntimeService, host: ElementRef<HTMLElement>, transport?: FormTransport | null, navigate?: ((url: string) => void) | null);
+    ngOnInit(): void;
     ngOnChanges(): void;
     onSubmit(event: Event): void;
+    /**
+     * The submit lifecycle, owned HERE so both hosts get the same one: submitting → the server's
+     * verdict → success (and an optional redirect) or error. Only the HTTP call itself is the
+     * host's, which is the one part that genuinely differs between the engine and anything else.
+     */
+    private send;
+    /** Turn the server's answer into what the visitor sees. Public so a host-owned transport can reuse it. */
+    applyResponse(response: SubmitResponse): void;
+    /** The honeypot input's value, if the host rendered one. Absent reads as empty — never as spam. */
+    private honeypotValue;
+    /** Blank the real DOM controls after a success. The runtime state alone would leave them filled. */
+    private resetControls;
     private focusFirstInvalid;
-    static ɵfac: i0.ɵɵFactoryDeclaration<IoxFormComponent, never>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<IoxFormComponent, [null, null, { optional: true; }, { optional: true; }]>;
     static ɵcmp: i0.ɵɵComponentDeclaration<IoxFormComponent, "form[iox-form]", never, { "nodeId": { "alias": "nodeId"; "required": false; }; "formId": { "alias": "formId"; "required": false; }; "name": { "alias": "name"; "required": false; }; "renderState": { "alias": "renderState"; "required": false; }; "feedback": { "alias": "feedback"; "required": false; }; }, { "formSubmit": "formSubmit"; "validationFailed": "validationFailed"; }, never, never, false, never>;
 }
 
@@ -2373,5 +2441,5 @@ declare class GalleryLoop {
     private emit;
 }
 
-export { AOSService, AnalyticsService, BREAKPOINTS, Breakpoint, BreakpointQueryKind, BuilderButtonComponent, BuilderDividerComponent, BuilderHeadingComponent, BuilderIconComponent, BuilderImageComponent, BuilderLinkComponent, BuilderSpacerComponent, ButtonBlockComponent, CMSClientInfraModule, CONTEXT_ACTION_TYPES, CardComponent, ClientGalleryComponent, ClientListComponent, ClientListItemComponent, ClientRepeaterComponent, ClientSliderContainerComponent, ClientSliderSlideComponent, ComponentInstanceRegistryService, ConsentService, ContainerComponent, ContentService, ContextStore, DEFAULT_GALLERY_SCHEDULER, DEFAULT_PAGE_TRANSITION, DEFAULT_PAGE_TRANSITION_DURATION, DEFAULT_PAGE_TRANSITION_EASING, DEFAULT_PAGE_TRANSITION_PERSPECTIVE, DEFAULT_WIDTH_BY_TYPE, DeclarationContext, ENVIRONMENT, FormRenderState, FormRuntimeService, GALLERY_EFFECTS, GALLERY_EFFECT_DESCRIPTORS, GalleryLoop, IOX_BUILDER_EVENTS, IOX_FORM_MESSAGES, IS_PREVIEW, IoxAnimateContainer, IoxAosDirective, IoxAosModule, IoxBuilderComponentsModule, IoxComponentRegistryService, IoxFieldComponent, IoxFormComponent, IoxFormErrorComponent, IoxFormSuccessComponent, IoxPageComponent, IoxPageModule, IoxSubmitButtonComponent, IoxUiModule, LinkedContainerComponent, PAGE_TRANSITION_CATEGORIES, PAGE_TRANSITION_PRESETS, PIPE_DESCRIPTORS, PIPE_REGISTRY, PageScrollProvider, PrivacyModalComponent, PrivacyModalService, PrivacyModelEvent, RESERVED_ALIAS_PREFIX, SUPPRESSED_STYLE_PROPS_BY_TYPE, SWIPER_RESPONSIVE_TRAITS, SectionComponent, TRANSITION_FEELS, TextBlockComponent, VIRTUAL_TRAIT_GROUPS, VIRTUAL_TRAIT_KEYS, ViewPositionDirective, ViewPositionModule, WebSettingsService, activeActions, applyBindingPipes, applyFeel, breakpointDef, breakpointForWidth, breakpointQueryFor, buildDataSourceFilter, buildRelatedFilter, buildSwiperBreakpoints, buildTargetedStateSelector, buildTransitionTimeline, cascadeChain, clearInputOverride, clearOverride, collectContextSlotKeys, collectReferencedAliases, compileDeclarations, composeVirtualTraits, computeRelative, contextActionEffect, contextSlotKeys, countOverrides, dataSourcePlanToRequest, declaredInputNames, defaultMessageResolver, effectiveTransitionId, excludeSelf, feelFor, getByPath, initialSlotValues, isActionEnabled, isContextAction, isInputOverriddenAt, isOverriddenAt, isReservedAlias, isValidSlotKey, legacyEnterToTransition, matchRouteParams, mediaQueryFor, mergeSwiperBreakpoints, nearestCommonAncestorId, nodeCssId, nodeUsesContext, normalizeCollectionResult, normalizeGalleryImage, parentBreakpoint, parseUrlList, planDataSource, planResponsiveRules, referencedDataSources, referencedDataSourcesDeep, renderDefaultDeclarations, resolveContextValue, resolveDerivedInto, resolveGalleryEffect, resolveGalleryUrls, resolveInputChain, resolveInputs, resolvePageTransition, resolvePath, resolveRelativeInto, resolveRepeaterItems, resolveSiblings, resolveSingleItemId, resolveStateStyles, resolveStyleProps, resolveValueChain, rewriteViewportUnits, safeSetInput, setInputOverride, setOverride, stateNamesIn, stripSuppressedProps, styleKeyToKebab, variableAliases, variableItemsFrom, withContextSlots, wrapInBreakpointQuery, wrapInMediaQuery };
+export { AOSService, AnalyticsService, BREAKPOINTS, Breakpoint, BreakpointQueryKind, BuilderButtonComponent, BuilderDividerComponent, BuilderHeadingComponent, BuilderIconComponent, BuilderImageComponent, BuilderLinkComponent, BuilderSpacerComponent, ButtonBlockComponent, CMSClientInfraModule, CONTEXT_ACTION_TYPES, CardComponent, ClientGalleryComponent, ClientListComponent, ClientListItemComponent, ClientRepeaterComponent, ClientSliderContainerComponent, ClientSliderSlideComponent, ComponentInstanceRegistryService, ConsentService, ContainerComponent, ContentService, ContextStore, DEFAULT_GALLERY_SCHEDULER, DEFAULT_PAGE_TRANSITION, DEFAULT_PAGE_TRANSITION_DURATION, DEFAULT_PAGE_TRANSITION_EASING, DEFAULT_PAGE_TRANSITION_PERSPECTIVE, DEFAULT_WIDTH_BY_TYPE, DeclarationContext, ENVIRONMENT, FormRenderState, FormRuntimeService, GALLERY_EFFECTS, GALLERY_EFFECT_DESCRIPTORS, GalleryLoop, IOX_BUILDER_EVENTS, IOX_FORM_MESSAGES, IOX_FORM_NAVIGATOR, IOX_FORM_TRANSPORT, IS_PREVIEW, IoxAnimateContainer, IoxAosDirective, IoxAosModule, IoxBuilderComponentsModule, IoxComponentRegistryService, IoxFieldComponent, IoxFormComponent, IoxFormErrorComponent, IoxFormSuccessComponent, IoxPageComponent, IoxPageModule, IoxSubmitButtonComponent, IoxUiModule, LinkedContainerComponent, PAGE_TRANSITION_CATEGORIES, PAGE_TRANSITION_PRESETS, PIPE_DESCRIPTORS, PIPE_REGISTRY, PageScrollProvider, PrivacyModalComponent, PrivacyModalService, PrivacyModelEvent, RESERVED_ALIAS_PREFIX, SUPPRESSED_STYLE_PROPS_BY_TYPE, SWIPER_RESPONSIVE_TRAITS, SectionComponent, TRANSITION_FEELS, TextBlockComponent, VIRTUAL_TRAIT_GROUPS, VIRTUAL_TRAIT_KEYS, ViewPositionDirective, ViewPositionModule, WebSettingsService, activeActions, applyBindingPipes, applyFeel, breakpointDef, breakpointForWidth, breakpointQueryFor, buildDataSourceFilter, buildRelatedFilter, buildSwiperBreakpoints, buildTargetedStateSelector, buildTransitionTimeline, cascadeChain, clearInputOverride, clearOverride, collectContextSlotKeys, collectReferencedAliases, compileDeclarations, composeVirtualTraits, computeRelative, contextActionEffect, contextSlotKeys, countOverrides, dataSourcePlanToRequest, declaredInputNames, defaultMessageResolver, effectiveTransitionId, excludeSelf, feelFor, getByPath, initialSlotValues, isActionEnabled, isContextAction, isInputOverriddenAt, isOverriddenAt, isReservedAlias, isValidSlotKey, legacyEnterToTransition, matchRouteParams, mediaQueryFor, mergeSwiperBreakpoints, nearestCommonAncestorId, nodeCssId, nodeUsesContext, normalizeCollectionResult, normalizeGalleryImage, parentBreakpoint, parseUrlList, planDataSource, planResponsiveRules, referencedDataSources, referencedDataSourcesDeep, renderDefaultDeclarations, resolveContextValue, resolveDerivedInto, resolveGalleryEffect, resolveGalleryUrls, resolveInputChain, resolveInputs, resolvePageTransition, resolvePath, resolveRelativeInto, resolveRepeaterItems, resolveSiblings, resolveSingleItemId, resolveStateStyles, resolveStyleProps, resolveValueChain, rewriteViewportUnits, safeSetInput, setInputOverride, setOverride, stateNamesIn, stripSuppressedProps, styleKeyToKebab, variableAliases, variableItemsFrom, withContextSlots, wrapInBreakpointQuery, wrapInMediaQuery };
 export type { BreakpointDef, BuildRelatedFilterOptions, ContextActionEffect, ContextActionLike, ContextItemRef, ContextSlotDefault, ContextValueSpec, ContextWriteScope, DataSourceDomain, DataSourceEndpoints, DataSourceMode, DataSourcePlan, DataSourceQueryFilter, DataSourceRequest, DataSourceRequestSpec, DataSourceRouteFilter, DataSourceSpec, FormMessageResolver, GalleryBoundSource, GalleryDurations, GalleryEffect, GalleryEffectDescriptor, GalleryImage, GalleryLoopOptions, GalleryLoopScheduler, GalleryLoopState, GallerySlideState, IBuilderEventEmitter, InputMap, IoxContextSlot, IoxPipe, OverrideBreakpoint, PageTransitionCategory, PageTransitionCategoryMeta, PageTransitionOptions, PageTransitionPreset, PipeArgSpec, PipeContext, PipeDescriptor, RelativeInputs, RelativeSourceKind, RelativeSourceSpec, ResolveSiblingsOptions, ResolvedPageTransition, ResponsiveLayer, ResponsiveOverrides, ResponsiveRuleSet, RouteContext, SetContextParams, SiblingsResult, StateStyleMap, StyleMap, StyleTreeNode, SwiperBreakpointMap, ToggleableAction, TransitionFeel, TransitionPhase, TransitionTimelineInput, ValueSource, VirtualTraitGroup };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectoriox/iox-ui",
-  "version": "4.32.0",
+  "version": "4.33.1",
   "peerDependencies": {
     "@angular/common": ">=20.0.0",
     "@angular/core": ">=20.0.0",

package/src/forms-core/public-api.ts

@@ -16,3 +16,4 @@ export * from './validate';
 export * from './collect';
 export * from './runtime';
 export * from './rule-catalog';
+export * from './transport';

package/src/forms-core/transport.ts

@@ -0,0 +1,103 @@
+/**
+ * The submit transport CONTRACT — what a host must provide to make a form actually send.
+ *
+ * The Form component deliberately owns no HTTP: the builder canvas must never post (an author
+ * clicking Submit while designing would file a real submission), and the SSR engine posts through
+ * Angular's HttpClient. What IS shared is everything around the call — the endpoint's shape, the
+ * anti-spam fields, and how the server's answer maps onto the form's state. Those live here so the
+ * two hosts cannot drift, and so a third host (a hand-built integration) has one thing to read.
+ *
+ * ⚠️ Framework-free, like the rest of forms-core. No Angular, no RxJS, no fetch.
+ */
+
+import { FieldError } from './validate';
+
+/** The field a honeypot input uses. Must match `iox-cms` `anti-spam.ts` — hence the comment there. */
+export const HONEYPOT_FIELD = '_iox_hp';
+/** When the form was rendered, so the server can measure fill time. */
+export const RENDERED_AT_FIELD = '_iox_t';
+
+/**
+ * What the form hands its host. There is deliberately no `orgId`: the tenant is the HOST's
+ * knowledge, not the form's, and a form that had to be told its org would be one more trait an
+ * author could get wrong.
+ */
+export interface SubmitRequest {
+    formId: string;
+    values: Record<string, any>;
+}
+
+/**
+ * The server's answer, normalised. Mirrors `SubmitResult` in `iox-cms`
+ * `form-submissions.service.ts` — the two are one contract, so change them together.
+ */
+export interface SubmitResponse {
+    ok: boolean;
+    /** Per-field verdicts from the server's own validation pass, keyed by field name. */
+    errors?: Record<string, FieldError>;
+    /** Where to send the visitor after a successful submit, when the form has a redirect action. */
+    redirect?: string;
+}
+
+/**
+ * The one function a host implements. Rejecting (or throwing) means the call never reached the
+ * server — the form shows its Error state, which is the honest thing to show for a dropped network.
+ */
+export type FormTransport = (request: SubmitRequest) => Promise<SubmitResponse>;
+
+/**
+ * The public submit path. Built here rather than interpolated at each call site, so the engine and
+ * any future host cannot disagree about it — and so changing it is one edit.
+ *
+ * Deliberately relative and WITHOUT a leading slash: the engine mounts under a per-org base href.
+ */
+export function submitEndpointPath(orgId: string, formId: string): string {
+    return `api/site/${encodeURIComponent(orgId)}/forms/${encodeURIComponent(formId)}/submit`;
+}
+
+/**
+ * Add the anti-spam fields to the collected values.
+ *
+ * Both are invisible to a real visitor and cost them nothing (decision D12). `renderedAt` is the
+ * time the form was rendered, NOT the time of submit — the server measures the difference to catch
+ * a script that fills and posts instantly.
+ */
+export function withAntiSpamFields(
+    values: Record<string, any>,
+    renderedAt: number,
+    honeypotValue = '',
+): Record<string, any> {
+    return { ...values, [HONEYPOT_FIELD]: honeypotValue, [RENDERED_AT_FIELD]: renderedAt };
+}
+
+/**
+ * Normalise whatever came back into a `SubmitResponse`.
+ *
+ * Fails CLOSED: anything that is not a recognisable success is treated as a failure. A malformed
+ * body must never show the visitor a Success state for a submission that was not stored — that is
+ * the one lie this feature must not tell.
+ */
+export function interpretSubmitResponse(body: any): SubmitResponse {
+    if (!body || typeof body !== 'object' || body.ok !== true) {
+        return {
+            ok: false,
+            errors: normaliseErrors(body?.errors),
+        };
+    }
+    const redirect = typeof body.redirect === 'string' && body.redirect.trim()
+        ? body.redirect.trim()
+        : undefined;
+    return { ok: true, redirect };
+}
+
+/** Keep only entries that actually carry a message, so a junk key cannot blank a field's error. */
+function normaliseErrors(raw: any): Record<string, FieldError> | undefined {
+    if (!raw || typeof raw !== 'object') return undefined;
+    const errors: Record<string, FieldError> = {};
+    for (const [name, value] of Object.entries(raw as Record<string, any>)) {
+        const messageKey = typeof value?.messageKey === 'string' ? value.messageKey : '';
+        if (!messageKey) continue;
+        errors[name] = value?.params ? { messageKey, params: value.params } : { messageKey };
+    }
+    return Object.keys(errors).length ? errors : undefined;
+}