@verbb/formie-browser 1.0.6 → 1.0.8

package/src/css/theme/fields/_survey-presentations.css

@@ -0,0 +1,396 @@
+@layer formie-theme {
+
+    .formie-likert-field-layout {
+        display: table;
+        width: 100%;
+        table-layout: fixed;
+        border-collapse: collapse;
+        border-spacing: 0;
+    }
+
+    .formie-likert-field-layout thead {
+        display: table-header-group;
+    }
+
+    .formie-likert-field-layout tbody {
+        display: table-row-group;
+    }
+
+    .formie-likert-field-layout tr {
+        display: table-row;
+    }
+
+    .formie-likert-field-layout th,
+    .formie-likert-field-layout td {
+        display: table-cell;
+    }
+
+    .formie-likert-column-label {
+        text-align: center;
+        color: var(--formie-survey-likert-label-color, var(--formie-color-heading));
+        word-break: break-word;
+        padding: 0 0.35rem 0.5rem;
+        vertical-align: bottom;
+        font-size: var(--formie-survey-likert-column-label-font-size, 0.875rem);
+        line-height: 1.3;
+    }
+
+    [data-formie-field-control]:has(> [data-formie-likert-multiple-rows]) {
+        overflow-x: auto;
+        -webkit-overflow-scrolling: touch;
+    }
+
+    @media (min-width: 40rem) {
+        .formie-likert-field-layout[data-formie-likert-multiple-rows] {
+            width: max-content;
+            min-width: 100%;
+        }
+
+        .formie-likert-field-layout[data-formie-likert-multiple-rows] .formie-likert-column-label {
+            min-width: var(--formie-survey-likert-column-min-width, 5.5rem);
+        }
+
+        .formie-likert-field-layout[data-formie-likert-multiple-rows] .formie-likert-option {
+            min-width: var(--formie-survey-likert-column-min-width, 5.5rem);
+        }
+    }
+
+    .formie-likert-row-label-header,
+    .formie-likert-row-label {
+        text-align: left;
+        color: var(--formie-survey-likert-label-color, var(--formie-color-heading));
+        word-break: break-word;
+        padding: 0.65rem 0.75rem 0.65rem 0;
+        vertical-align: middle;
+        font-weight: var(--formie-font-weight-medium);
+    }
+
+    .formie-likert-row-label-header {
+        padding-bottom: 0.5rem;
+        font-weight: var(--formie-font-weight-normal);
+    }
+
+    .formie-likert-field-layout[data-formie-likert-multiple-rows] {
+        table-layout: auto;
+    }
+
+    .formie-likert-field-layout[data-formie-likert-multiple-rows] .formie-likert-row-label-header,
+    .formie-likert-field-layout[data-formie-likert-multiple-rows] .formie-likert-row-label {
+        width: 1%;
+        white-space: nowrap;
+        padding-right: 1rem;
+    }
+
+    .formie-likert-field-layout[data-formie-likert-multiple-rows] .formie-likert-inputs-row .formie-likert-row-label {
+        border-top-left-radius: var(--formie-border-radius);
+        border-bottom-left-radius: var(--formie-border-radius);
+    }
+
+    .formie-likert-field-layout[data-formie-likert-multiple-rows] .formie-likert-inputs-row .formie-likert-option:first-child {
+        border-top-left-radius: 0;
+        border-bottom-left-radius: 0;
+    }
+
+    .formie-likert-inputs-row--alt .formie-likert-row-label,
+    .formie-likert-inputs-row--alt .formie-likert-option {
+        background-color: var(--formie-survey-likert-option-background-alt, var(--formie-color-surface));
+    }
+
+    .formie-likert-option {
+        text-align: center;
+        vertical-align: middle;
+        padding: 0.65rem 0.35rem;
+        background-color: var(--formie-survey-likert-option-background, var(--formie-color-surface-muted));
+    }
+
+    .formie-likert-inputs-row .formie-likert-option:first-child {
+        border-top-left-radius: var(--formie-border-radius);
+        border-bottom-left-radius: var(--formie-border-radius);
+    }
+
+    .formie-likert-inputs-row .formie-likert-option:last-child {
+        border-top-right-radius: var(--formie-border-radius);
+        border-bottom-right-radius: var(--formie-border-radius);
+    }
+
+    .formie-likert-option .formie-radio-option-label {
+        padding-left: 0;
+        width: var(--formie-check-size);
+        height: var(--formie-check-size);
+        line-height: var(--formie-check-size);
+        overflow: hidden;
+    }
+
+    .formie-likert-option .formie-likert-option-label-text {
+        display: none;
+    }
+
+    .formie-likert-option .formie-radio-option-label::before {
+        top: 0;
+        left: 0;
+    }
+
+    @media (max-width: 39.999rem) {
+        [data-formie-field-control]:has(> [data-formie-likert-field-layout]) {
+            overflow-x: visible;
+        }
+
+        .formie-likert-field-layout {
+            display: block;
+            width: 100%;
+            table-layout: auto;
+            border-radius: 0;
+            background-color: transparent;
+            padding: 0;
+        }
+
+        .formie-likert-column-labels {
+            position: absolute;
+            width: 1px;
+            height: 1px;
+            margin: -1px;
+            padding: 0;
+            overflow: hidden;
+            clip: rect(0, 0, 0, 0);
+            clip-path: inset(50%);
+            white-space: nowrap;
+            border: 0;
+        }
+
+        .formie-likert-field-layout thead,
+        .formie-likert-field-layout tbody,
+        .formie-likert-field-layout tr,
+        .formie-likert-field-layout th,
+        .formie-likert-field-layout td {
+            display: block;
+            width: 100%;
+        }
+
+        .formie-likert-inputs-row {
+            margin: 0 0 var(--formie-space-2);
+            padding: var(--formie-space-2) var(--formie-space-3);
+            border-radius: var(--formie-border-radius);
+            background-color: var(--formie-survey-likert-option-background, var(--formie-color-surface-muted));
+        }
+
+        .formie-likert-inputs-row:last-child {
+            margin-bottom: 0;
+        }
+
+        .formie-likert-inputs-row--alt {
+            background-color: var(--formie-survey-likert-option-background-alt, var(--formie-color-surface));
+        }
+
+        .formie-likert-option {
+            display: block;
+            padding: var(--formie-space-2) 0;
+            text-align: left;
+            background-color: transparent;
+            border-radius: 0;
+            min-width: 0;
+        }
+
+        .formie-likert-option:first-child {
+            padding-top: 0;
+        }
+
+        .formie-likert-option:last-child {
+            padding-bottom: 0;
+        }
+
+        .formie-likert-option .formie-radio-option-label {
+            width: auto;
+            height: auto;
+            overflow: visible;
+            padding-left: var(--formie-check-label-padding-left);
+            line-height: var(--formie-check-line-height);
+            font-weight: var(--formie-font-weight-normal);
+            color: var(--formie-color-text);
+        }
+
+        .formie-likert-option .formie-likert-option-label-text {
+            display: inline;
+        }
+
+        .formie-likert-field-layout[data-formie-likert-multiple-rows] .formie-likert-row-label {
+            display: block;
+            width: 100%;
+            padding: 0 0 var(--formie-space-2);
+            font-weight: var(--formie-font-weight-medium);
+            background-color: transparent;
+            white-space: normal;
+        }
+
+        .formie-likert-field-layout[data-formie-likert-multiple-rows] .formie-likert-inputs-row {
+            border-top: 0;
+        }
+
+        .formie-likert-field-layout[data-formie-likert-multiple-rows] .formie-likert-inputs-row .formie-likert-row-label {
+            border-radius: 0;
+        }
+
+        .formie-likert-field-layout[data-formie-likert-multiple-rows] .formie-likert-inputs-row .formie-likert-option:first-child {
+            border-radius: 0;
+        }
+
+        .formie-likert-field-layout[data-formie-likert-multiple-rows] .formie-likert-inputs-row .formie-likert-option:last-child {
+            border-radius: 0;
+        }
+    }
+
+    .formie-rank-field-layout {
+        width: 100%;
+    }
+
+    .formie-rank-list,
+    .formie-rank-field-layout .formie-rank-list.formie-field-options {
+        list-style: none;
+        margin: var(--formie-space-1) 0 0;
+        padding: 0;
+        display: flex;
+        flex-direction: column;
+        flex-wrap: nowrap;
+        gap: var(--formie-survey-rank-list-gap, var(--formie-space-2));
+    }
+
+    .formie-rank-list[data-formie-rank-sorting="true"] {
+        user-select: none;
+    }
+
+    .formie-rank-item {
+        display: flex;
+        align-items: center;
+        gap: var(--formie-space-2);
+        margin: 0;
+        padding: var(--formie-space-2) var(--formie-space-3);
+        border: var(--formie-border-width) solid var(--formie-survey-rank-item-border-color, var(--formie-color-border));
+        border-radius: var(--formie-border-radius);
+        background: var(--formie-survey-rank-item-background, var(--formie-color-surface));
+        cursor: move;
+        touch-action: none;
+    }
+
+    .formie-rank-placeholder {
+        box-sizing: border-box;
+        margin: 0;
+        padding: 0;
+        list-style: none;
+        border: 0;
+        background: transparent;
+    }
+
+    .formie-rank-handle {
+        display: inline-flex;
+        align-items: center;
+        justify-content: center;
+        width: 0.875rem;
+        height: 1.125rem;
+        padding: 0;
+        border: 0;
+        background: transparent;
+        color: var(--formie-survey-rank-handle-color, var(--formie-color-text-muted));
+        opacity: 0.6;
+        cursor: move;
+        flex-shrink: 0;
+        pointer-events: none;
+    }
+
+    .formie-rank-handle::before {
+        display: block;
+        width: 13px;
+        height: 0.875rem;
+        content: "";
+        background: currentColor;
+        mask: url("data:image/svg+xml;charset=utf8,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 640 640'%3E%3Cpath d='M288 128C288 92.7 259.3 64 224 64C188.7 64 160 92.7 160 128C160 163.3 188.7 192 224 192C259.3 192 288 163.3 288 128zM288 320C288 284.7 259.3 256 224 256C188.7 256 160 284.7 160 320C160 355.3 188.7 384 224 384C259.3 384 288 355.3 288 320zM160 512C160 547.3 188.7 576 224 576C259.3 576 288 547.3 288 512C288 476.7 259.3 448 224 448C188.7 448 160 476.7 160 512zM480 128C480 92.7 451.3 64 416 64C380.7 64 352 92.7 352 128C352 163.3 380.7 192 416 192C451.3 192 480 163.3 480 128zM352 320C352 355.3 380.7 384 416 384C451.3 384 480 355.3 480 320C480 284.7 451.3 256 416 256C380.7 256 352 284.7 352 320zM480 512C480 476.7 451.3 448 416 448C380.7 448 352 476.7 352 512C352 547.3 380.7 576 416 576C451.3 576 480 547.3 480 512z'/%3E%3C/svg%3E") center / contain no-repeat;
+    }
+
+    .formie-rank-option-label {
+        flex: 1 1 auto;
+        font-size: var(--formie-check-font-size);
+        line-height: var(--formie-check-line-height);
+    }
+
+    .formie-rank-input {
+        display: none;
+    }
+
+    .formie-rating-field-layout {
+        width: 100%;
+    }
+
+    .formie-rating-stars,
+    .formie-rating-field-layout .formie-rating-stars.formie-field-options {
+        display: inline-flex;
+        flex-wrap: nowrap;
+        align-items: center;
+        padding: var(--formie-space-2) 0;
+        gap: 0;
+        --formie-survey-rating-star-size: 26px;
+        --formie-survey-rating-star-spacing: var(--formie-space-1);
+        --formie-survey-rating-star-outline: url("data:image/svg+xml;charset=utf8,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%2024%2023%22%20fill%3D%22none%22%3E%3Cpath%20d%3D%22M22.2%208.05333L15.7466%207.49333L13.2266%201.56C12.7733%200.48%2011.2266%200.48%2010.7733%201.56L8.25331%207.50667L1.81331%208.05333C0.639975%208.14667%200.159975%209.61333%201.05331%2010.3867L5.94664%2014.6267L4.47998%2020.92C4.21331%2022.0667%205.45331%2022.9733%206.46664%2022.36L12%2019.0267L17.5333%2022.3733C18.5466%2022.9867%2019.7866%2022.08%2019.52%2020.9333L18.0533%2014.6267L22.9466%2010.3867C23.84%209.61333%2023.3733%208.14667%2022.2%208.05333ZM12%2016.5333L6.98664%2019.56L8.31998%2013.8533L3.89331%2010.0133L9.73331%209.50667L12%204.13333L14.28%209.52L20.12%2010.0267L15.6933%2013.8667L17.0266%2019.5733L12%2016.5333Z%22%20fill%3D%22%23E27730%22%2F%3E%3C%2Fsvg%3E");
+        --formie-survey-rating-star-filled: url("data:image/svg+xml;charset=utf8,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%2024%2023%22%20fill%3D%22none%22%3E%3Cpath%20d%3D%22M12%2019.0267L17.5333%2022.3733C18.5466%2022.9867%2019.7866%2022.08%2019.52%2020.9333L18.0533%2014.64L22.9466%2010.4C23.84%209.62667%2023.36%208.16%2022.1866%208.06667L15.7466%207.52L13.2266%201.57334C12.7733%200.493336%2011.2266%200.493336%2010.7733%201.57334L8.25331%207.50667L1.81331%208.05334C0.639975%208.14667%200.159975%209.61334%201.05331%2010.3867L5.94664%2014.6267L4.47997%2020.92C4.21331%2022.0667%205.45331%2022.9733%206.46664%2022.36L12%2019.0267Z%22%20fill%3D%22%23E27730%22%2F%3E%3C%2Fsvg%3E");
+    }
+
+    .formie-rating-option {
+        position: relative;
+        margin: 0;
+        gap: 0;
+        align-items: center;
+        cursor: pointer;
+    }
+
+    .formie-rating-input {
+        position: absolute;
+        width: 1px;
+        height: 1px;
+        margin: -1px;
+        padding: 0;
+        overflow: hidden;
+        clip: rect(0, 0, 0, 0);
+        clip-path: inset(50%);
+        white-space: nowrap;
+        border: 0;
+    }
+
+    .formie-rating-option-label {
+        display: inline-flex;
+        cursor: pointer;
+        padding-inline: calc(var(--formie-survey-rating-star-spacing, var(--formie-space-1)) / 2);
+    }
+
+    .formie-rating-star {
+        display: block;
+        width: var(--formie-survey-rating-star-size, 26px);
+        height: var(--formie-survey-rating-star-size, 26px);
+        background: center / contain no-repeat;
+        background-image: var(--formie-survey-rating-star-outline);
+    }
+
+    .formie-rating-stars:not([data-formie-rating-hover])[data-formie-rating-value="1"] .formie-rating-option:nth-child(-n+1) .formie-rating-star,
+    .formie-rating-stars:not([data-formie-rating-hover])[data-formie-rating-value="2"] .formie-rating-option:nth-child(-n+2) .formie-rating-star,
+    .formie-rating-stars:not([data-formie-rating-hover])[data-formie-rating-value="3"] .formie-rating-option:nth-child(-n+3) .formie-rating-star,
+    .formie-rating-stars:not([data-formie-rating-hover])[data-formie-rating-value="4"] .formie-rating-option:nth-child(-n+4) .formie-rating-star,
+    .formie-rating-stars:not([data-formie-rating-hover])[data-formie-rating-value="5"] .formie-rating-option:nth-child(-n+5) .formie-rating-star,
+    .formie-rating-stars:not([data-formie-rating-hover])[data-formie-rating-value="6"] .formie-rating-option:nth-child(-n+6) .formie-rating-star,
+    .formie-rating-stars:not([data-formie-rating-hover])[data-formie-rating-value="7"] .formie-rating-option:nth-child(-n+7) .formie-rating-star,
+    .formie-rating-stars:not([data-formie-rating-hover])[data-formie-rating-value="8"] .formie-rating-option:nth-child(-n+8) .formie-rating-star,
+    .formie-rating-stars:not([data-formie-rating-hover])[data-formie-rating-value="9"] .formie-rating-option:nth-child(-n+9) .formie-rating-star,
+    .formie-rating-stars:not([data-formie-rating-hover])[data-formie-rating-value="10"] .formie-rating-option:nth-child(-n+10) .formie-rating-star,
+    .formie-rating-stars[data-formie-rating-hover="1"] .formie-rating-option:nth-child(-n+1) .formie-rating-star,
+    .formie-rating-stars[data-formie-rating-hover="2"] .formie-rating-option:nth-child(-n+2) .formie-rating-star,
+    .formie-rating-stars[data-formie-rating-hover="3"] .formie-rating-option:nth-child(-n+3) .formie-rating-star,
+    .formie-rating-stars[data-formie-rating-hover="4"] .formie-rating-option:nth-child(-n+4) .formie-rating-star,
+    .formie-rating-stars[data-formie-rating-hover="5"] .formie-rating-option:nth-child(-n+5) .formie-rating-star,
+    .formie-rating-stars[data-formie-rating-hover="6"] .formie-rating-option:nth-child(-n+6) .formie-rating-star,
+    .formie-rating-stars[data-formie-rating-hover="7"] .formie-rating-option:nth-child(-n+7) .formie-rating-star,
+    .formie-rating-stars[data-formie-rating-hover="8"] .formie-rating-option:nth-child(-n+8) .formie-rating-star,
+    .formie-rating-stars[data-formie-rating-hover="9"] .formie-rating-option:nth-child(-n+9) .formie-rating-star,
+    .formie-rating-stars[data-formie-rating-hover="10"] .formie-rating-option:nth-child(-n+10) .formie-rating-star {
+        background-image: var(--formie-survey-rating-star-filled);
+    }
+
+    .formie-rating-input:focus-visible+.formie-rating-option-label .formie-rating-star {
+        outline: 2px solid var(--formie-color-focus-ring);
+        outline-offset: 2px;
+    }
+}

package/src/js/contracts/schema.ts

@@ -43,6 +43,11 @@ export type FormRedirect = {
     target?: 'same-tab' | 'new-tab';
 };
 
+export type FormClientEvent = {
+    event: string;
+    payload: Record<string, string>;
+};
+
 export type FormSubmitResult = {
     ok: boolean;
     action?: FormAction;
@@ -56,6 +61,7 @@ export type FormSubmitResult = {
     nextPage?: { id: string } | null;
     redirect?: FormRedirect | null;
     submitData?: unknown[];
+    clientEvents?: FormClientEvent[];
     meta?: Record<string, unknown>;
 };
 

package/src/js/core/create-formie-client.ts

@@ -11,7 +11,8 @@ import type { FormieModuleDefinition, FormieModuleInstance } from '#contracts/mo
 import type { FormEndpointPayload, FormModuleManifest, FormSubmitResult } from '#contracts/schema';
 import type { ThemeClassMap } from '#contracts/theme';
 import { dispatchFormieDomEvent } from '#core/dom-events';
-import { dispatchPageClientEventForSubmit } from '#core/page-client-event';
+import { getErrorAriaLivePreference } from '#core/error-aria-live';
+import { dispatchPageClientEventForSubmit, dispatchPendingClientEventsFromForm } from '#core/page-client-event';
 import { syncPageTabErrors } from '#core/page-tab-errors';
 import {
     enhanceServerRenderedFieldErrors,
@@ -27,11 +28,13 @@ import { loadModulesFromManifest } from '#modules/loader';
 import { registerThemeClassMap } from '#theme/theme-classes';
 import { runSubmitPipeline } from '#submit/pipeline';
 import { clearSubmissionOnUnload, requestGraphqlRender, requestRefreshTokens, requestRender, requestSetPage } from '#transport/forms-api';
+import { ensureFormStartedAt } from '#utils/form-started-at';
 import { createDebug } from '#utils/debug';
 import { createFormUnloadWarningGuard } from '#utils/unload-warning';
 import { getValidationScope } from '#validation/scope';
 import { FormieValidator } from '#validation/validator';
 import { bindSubmitReadiness } from '#validation/submit-readiness';
+import { bindEnterKeyGuard } from '#validation/enter-key-guard';
 
 type InternalInstanceState = {
     options: FormMountOptions;
@@ -989,6 +992,7 @@ export function createFormieClient(): FormieClient {
 
         const validator = form ? new FormieValidator(form, {
             live: parseBooleanDatasetValue(form.dataset.formieValidationOnFocus),
+            errorAriaLive: getErrorAriaLivePreference(form),
             errorMessage: form.dataset.formieErrorMessage || '',
             fieldContainerErrorClass: resolvedThemeClassMap.fieldLayoutError || [],
             inputErrorClass: resolvedThemeClassMap.fieldControlError || [],
@@ -1014,6 +1018,16 @@ export function createFormieClient(): FormieClient {
         }
 
         if (form) {
+            ensureFormStartedAt(form);
+
+            if (normalizedOptions.themeConfig && typeof normalizedOptions.themeConfig === 'object') {
+                form.setAttribute('data-formie-theme-config', JSON.stringify(normalizedOptions.themeConfig));
+            }
+
+            if (normalizedOptions.theme && normalizedOptions.theme !== 'formie') {
+                form.setAttribute('data-formie-frontend-theme', normalizedOptions.theme);
+            }
+
             if (renderPayload || normalizedOptions.endpoint || (target as HTMLElement).dataset.formieEndpoint) {
                 normalizeHeadlessManagedUrls(target, form, normalizedOptions);
             }
@@ -1166,6 +1180,7 @@ export function createFormieClient(): FormieClient {
 
             if (validator) {
                 unbinds.push(bindSubmitReadiness(form, validator, target));
+                unbinds.push(bindEnterKeyGuard(form));
             }
 
             await refreshTokensIfNeeded(target, normalizedOptions, form);
@@ -1242,6 +1257,11 @@ export function createFormieClient(): FormieClient {
             id,
             mode: normalizedOptions.mode as FormMode,
         });
+
+        if (form instanceof HTMLFormElement) {
+            dispatchPendingClientEventsFromForm(form);
+        }
+
         debug.log('Mount complete.', {
             id,
             target: getTargetDebugLabel(target),

package/src/js/core/error-aria-live.ts

@@ -0,0 +1,45 @@
+export type ErrorAriaLivePreference = 'polite' | 'assertive' | 'off';
+
+export function getErrorAriaLivePreference(form: HTMLFormElement): ErrorAriaLivePreference {
+    const value = (form.dataset.formieErrorAriaLive || 'polite').trim().toLowerCase();
+
+    if (value === 'assertive' || value === 'off') {
+        return value;
+    }
+
+    return 'polite';
+}
+
+export function resolveValidationErrorAriaLive(
+    preference: ErrorAriaLivePreference,
+    submitted: boolean,
+): 'polite' | 'assertive' | null {
+    if (preference === 'off') {
+        return null;
+    }
+
+    if (!submitted) {
+        return 'polite';
+    }
+
+    return preference;
+}
+
+export function resolveSubmitErrorAriaLive(preference: ErrorAriaLivePreference): 'polite' | 'assertive' | null {
+    if (preference === 'off') {
+        return null;
+    }
+
+    return preference;
+}
+
+export function applyErrorAriaLive(element: HTMLElement, ariaLive: 'polite' | 'assertive' | null): void {
+    if (ariaLive) {
+        element.setAttribute('aria-live', ariaLive);
+        element.setAttribute('aria-atomic', 'true');
+        return;
+    }
+
+    element.removeAttribute('aria-live');
+    element.removeAttribute('aria-atomic');
+}

package/src/js/core/page-client-event.ts

@@ -3,11 +3,17 @@ import { createDebug } from '#utils/debug';
 const debug = createDebug('general', 'page-client-event');
 
 const CLIENT_EVENT_ATTR = 'data-formie-client-event';
+const PENDING_CLIENT_EVENTS_ATTR = 'data-formie-pending-client-events';
 
 type ClientEventPayload = {
     fields?: Array<{ label?: string; value?: string }>;
 };
 
+export type ResolvedClientEvent = {
+    event: string;
+    payload: Record<string, string>;
+};
+
 function escapePageIdForSelector(pageId: string): string {
     if (typeof window !== 'undefined' && window.CSS?.escape) {
         return window.CSS.escape(pageId);
@@ -70,11 +76,83 @@ function buildPayloadObject(fields: Array<{ label?: string; value?: string }>):
     return out;
 }
 
+function normalizeResolvedClientEvents(events: unknown): ResolvedClientEvent[] {
+    if (!Array.isArray(events)) {
+        return [];
+    }
+
+    return events
+        .map((item) => {
+            if (!item || typeof item !== 'object') {
+                return null;
+            }
+
+            const record = item as ResolvedClientEvent;
+            const eventName = typeof record.event === 'string' ? record.event.trim() : '';
+            const payload = record.payload && typeof record.payload === 'object' ? record.payload : null;
+
+            if (!eventName || !payload) {
+                return null;
+            }
+
+            return {
+                event: eventName,
+                payload,
+            };
+        })
+        .filter((item): item is ResolvedClientEvent => item !== null);
+}
+
+export function dispatchResolvedClientEvents(form: HTMLFormElement, events: ResolvedClientEvent[]): void {
+    if (!events.length) {
+        return;
+    }
+
+    const win = window as Window & { dataLayer?: unknown[] };
+    win.dataLayer = win.dataLayer || [];
+
+    events.forEach((item) => {
+        win.dataLayer!.push(item.payload);
+
+        form.dispatchEvent(new CustomEvent('formie:client-event', {
+            bubbles: true,
+            detail: {
+                event: item.event,
+                payload: item.payload,
+            },
+        }));
+    });
+
+    debug.log('Dispatched resolved client events.', {
+        count: events.length,
+        events: events.map((item) => item.event),
+    });
+}
+
+export function dispatchPendingClientEventsFromForm(form: HTMLFormElement): void {
+    const rawAttr = form.getAttribute(PENDING_CLIENT_EVENTS_ATTR);
+
+    if (!rawAttr?.trim()) {
+        return;
+    }
+
+    try {
+        const parsed = JSON.parse(rawAttr) as unknown;
+        const events = normalizeResolvedClientEvents(parsed);
+
+        if (events.length) {
+            dispatchResolvedClientEvents(form, events);
+        }
+    } catch {
+        debug.warn('Invalid pending client events JSON on form element.');
+    } finally {
+        form.removeAttribute(PENDING_CLIENT_EVENTS_ATTR);
+    }
+}
+
 /**
- * When the builder enables JavaScript events for a page, the theme emits
- * `data-formie-client-event` on that page's section. On each successful
- * **submit** (not back/save), push the configured key/value object to
- * `window.dataLayer` (when present) and dispatch `formie:client-event`.
+ * Legacy static page attribute dispatch. Prefer server-resolved `clientEvents`
+ * from the submit response when available.
  */
 export function dispatchPageClientEventForSubmit(form: HTMLFormElement, action: string): void {
     if (action !== 'submit') {
@@ -112,18 +190,8 @@ export function dispatchPageClientEventForSubmit(form: HTMLFormElement, action:
     }
 
     const payload = buildPayloadObject(config.fields);
-    const win = window as Window & { dataLayer?: unknown[] };
-
-    win.dataLayer = win.dataLayer || [];
-    win.dataLayer.push(payload);
-
-    form.dispatchEvent(new CustomEvent('formie:client-event', {
-        bubbles: true,
-        detail: { payload },
-    }));
-
-    debug.log('Dispatched page client event.', {
-        pageId,
-        keys: Object.keys(payload),
-    });
+    dispatchResolvedClientEvents(form, [{
+        event: typeof payload.event === 'string' && payload.event !== '' ? payload.event : 'formPageSubmission',
+        payload,
+    }]);
 }

package/src/js/core/submit-result-state.ts

@@ -1,6 +1,7 @@
 import type { FormAction } from '#contracts/common';
 import type { FormSubmitResult } from '#contracts/schema';
-import { dispatchPageClientEventForSubmit } from '#core/page-client-event';
+import { dispatchFormieDomEvent } from '#core/dom-events';
+import { dispatchPageClientEventForSubmit, dispatchResolvedClientEvents } from '#core/page-client-event';
 import { syncPageTabErrors } from '#core/page-tab-errors';
 import { addThemeClasses, removeThemeClasses, toggleThemeClasses } from '#theme/theme-classes';
 import { createDebug } from '#utils/debug';
@@ -567,7 +568,11 @@ export function applySubmitResultState(form: HTMLFormElement, result: FormSubmit
         return;
     }
 
-    dispatchPageClientEventForSubmit(form, action);
+    if (Array.isArray(result.clientEvents) && result.clientEvents.length > 0) {
+        dispatchResolvedClientEvents(form, result.clientEvents);
+    } else {
+        dispatchPageClientEventForSubmit(form, action);
+    }
 
     if (result.nextPage?.id) {
         // Advancing pages is treated as a fresh validation cycle for the next page.
@@ -576,6 +581,9 @@ export function applySubmitResultState(form: HTMLFormElement, result: FormSubmit
         const validator = formWithValidationApi.formieValidation;
         validator?.resetLiveState();
         applyPageState(form, result.nextPage.id);
+        dispatchFormieDomEvent(form, 'formie:page:navigate:after', {
+            pageId: result.nextPage.id,
+        });
         debug.log('Advanced to next page.', {
             nextPageId: result.nextPage.id,
         });