@verbb/formie-browser 1.0.13 → 1.0.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@verbb/formie-browser",
-  "version": "1.0.13",
+  "version": "1.0.14",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -28,19 +28,49 @@
     "**/*.css"
   ],
   "imports": {
-    "#theme/*": "./src/js/theme/*",
+    "#theme/*": {
+      "types": "./dist/js/theme/*.d.ts",
+      "default": "./src/js/theme/*"
+    },
     "#theme-css/*": "./src/css/theme/*",
     "#theme-base/*": "./src/css/theme-base/*",
     "#icons/*": "./src/icons/*",
-    "#contracts/*": "./src/js/contracts/*",
-    "#compatibility/*": "./src/js/compatibility/*",
-    "#core/*": "./src/js/core/*",
-    "#events/*": "./src/js/events/*",
-    "#modules/*": "./src/js/modules/*",
-    "#submit/*": "./src/js/submit/*",
-    "#transport/*": "./src/js/transport/*",
-    "#utils/*": "./src/js/utils/*",
-    "#validation/*": "./src/js/validation/*"
+    "#contracts/*": {
+      "types": "./dist/js/contracts/*.d.ts",
+      "default": "./src/js/contracts/*"
+    },
+    "#compatibility/*": {
+      "types": "./dist/js/compatibility/*.d.ts",
+      "default": "./src/js/compatibility/*"
+    },
+    "#core/*": {
+      "types": "./dist/js/core/*.d.ts",
+      "default": "./src/js/core/*"
+    },
+    "#events/*": {
+      "types": "./dist/js/events/*.d.ts",
+      "default": "./src/js/events/*"
+    },
+    "#modules/*": {
+      "types": "./dist/js/modules/*.d.ts",
+      "default": "./src/js/modules/*"
+    },
+    "#submit/*": {
+      "types": "./dist/js/submit/*.d.ts",
+      "default": "./src/js/submit/*"
+    },
+    "#transport/*": {
+      "types": "./dist/js/transport/*.d.ts",
+      "default": "./src/js/transport/*"
+    },
+    "#utils/*": {
+      "types": "./dist/js/utils/*.d.ts",
+      "default": "./src/js/utils/*"
+    },
+    "#validation/*": {
+      "types": "./dist/js/validation/*.d.ts",
+      "default": "./src/js/validation/*"
+    }
   },
   "exports": {
     ".": {
@@ -57,6 +87,7 @@
     "access": "public"
   },
   "scripts": {
+    "prebuild": "node ../../scripts/generate-browser-theme-state.mjs",
     "dev": "vite build --watch",
     "build": "vite build && tsc -p tsconfig.json"
   },
@@ -70,7 +101,7 @@
     "@placekit/autocomplete-js": "^2.2.1",
     "@uppy/core": "^5.2.0",
     "@uppy/xhr-upload": "^5.2.0",
-    "@verbb/formie-core": "1.0.13",
+    "@verbb/formie-core": "1.0.14",
     "expression-language": "^2.5.4",
     "flatpickr": "^4.6.13",
     "friendly-challenge": "^0.9.19",

package/src/css/formie-base.css

@@ -75,4 +75,107 @@
     [hidden] {
         display: none !important;
     }
-}
+
+    .formie-module-error--fallback {
+        margin-block: 0 1.5rem;
+        padding: 1rem;
+        border: 1px solid #f3a6a6;
+        border-inline-start: 4px solid #c92a2a;
+        border-radius: 0.375rem;
+        background: #fff5f5;
+        color: #5f2120;
+        font: 0.875rem/1.5 system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+    }
+
+    .formie-module-error--fallback .formie-module-error__notice {
+        display: flex;
+        align-items: flex-start;
+        gap: 0.75rem;
+    }
+
+    .formie-module-error--fallback .formie-module-error__indicator {
+        display: inline-flex;
+        flex: 0 0 auto;
+        align-items: center;
+        justify-content: center;
+        width: 1.5rem;
+        height: 1.5rem;
+        border-radius: 50%;
+        background: #c92a2a;
+        color: #fff;
+        font-weight: 700;
+        line-height: 1;
+    }
+
+    .formie-module-error--fallback .formie-module-error__content {
+        min-width: 0;
+    }
+
+    .formie-module-error--fallback .formie-module-error__title {
+        display: block;
+        margin-block-end: 0.125rem;
+        color: #842029;
+        font-size: 0.9375rem;
+    }
+
+    .formie-module-error--fallback .formie-module-error__details {
+        margin-block-start: 0.875rem;
+        padding-block-start: 0.75rem;
+        border-block-start: 1px solid #f3c2c2;
+    }
+
+    .formie-module-error--fallback .formie-module-error__details > summary {
+        width: fit-content;
+        cursor: pointer;
+        font-weight: 600;
+    }
+
+    .formie-module-error--fallback .formie-module-error__details > pre {
+        max-height: 16rem;
+        margin-block: 0.75rem;
+        padding: 0.75rem;
+        overflow: auto;
+        border: 1px solid #ead0d0;
+        border-radius: 0.25rem;
+        background: #fff;
+        color: #3f2929;
+        font: 0.75rem/1.5 ui-monospace, SFMono-Regular, Consolas, "Liberation Mono", monospace;
+        overflow-wrap: anywhere;
+        user-select: text;
+        white-space: pre-wrap;
+    }
+
+    .formie-module-error--fallback .formie-module-error__actions {
+        display: flex;
+        flex-wrap: wrap;
+        align-items: center;
+        gap: 0.75rem;
+    }
+
+    .formie-module-error--fallback .formie-module-error__copy {
+        padding: 0.375rem 0.625rem;
+        border: 1px solid #bd6464;
+        border-radius: 0.25rem;
+        background: #fff;
+        color: #6f1d1d;
+        cursor: pointer;
+        font: inherit;
+        font-weight: 600;
+    }
+
+    .formie-module-error--fallback .formie-module-error__copy:hover {
+        background: #fffafa;
+    }
+
+    .formie-module-error--fallback .formie-module-error__details > summary:focus-visible,
+    .formie-module-error--fallback .formie-module-error__copy:focus-visible,
+    .formie-module-error--fallback .formie-module-error__details > pre:focus-visible {
+        outline: 2px solid #7f1d1d;
+        outline-offset: 2px;
+    }
+
+    .formie-module-error--fallback .formie-module-error__copy-status {
+        color: #6f1d1d;
+        font-size: 0.8125rem;
+    }
+}

package/src/css/theme/_messages.css

@@ -24,6 +24,7 @@
     }
 
     .formie-message-error {
+        border: var(--formie-border-width) solid var(--formie-color-danger-border);
         background: var(--formie-color-danger-soft);
         color: var(--formie-color-danger-dark);
     }
@@ -33,6 +34,7 @@
     }
 
     .formie-message-success {
+        border: var(--formie-border-width) solid var(--formie-color-success-border);
         background: var(--formie-color-success-soft);
         color: var(--formie-color-success-dark);
     }

package/src/css/theme/_tokens.css

@@ -47,6 +47,7 @@
         --formie-black: #000000;
         --formie-white: #ffffff;
 
+        /* Matches Tailwind CSS's Slate color palette, with a custom 450 accessibility step. */
         --formie-neutral-50: #f8fafc;
         --formie-neutral-100: #f1f5f9;
         --formie-neutral-200: #e2e8f0;
@@ -61,6 +62,7 @@
         --formie-neutral-900: #0f172a;
         --formie-neutral-950: #020617;
 
+        /* Custom tonal scale based on #1c41e3. */
         --formie-primary-50: #e8ecfc;
         --formie-primary-100: #d2d9f9;
         --formie-primary-200: #a4b3f4;
@@ -73,29 +75,31 @@
         --formie-primary-900: #060d2d;
         --formie-primary-950: #040920;
 
-        --formie-danger-50: #fef2f2;
-        --formie-danger-100: #fee2e2;
-        --formie-danger-200: #fecaca;
-        --formie-danger-300: #fca5a5;
-        --formie-danger-400: #f87171;
-        --formie-danger-500: #ef4444;
-        --formie-danger-600: #dc2626;
-        --formie-danger-700: #b91c1c;
-        --formie-danger-800: #991b1b;
-        --formie-danger-900: #7f1d1d;
-        --formie-danger-950: #450a0a;
-
-        --formie-success-50: #f0fdf4;
-        --formie-success-100: #dcfce7;
-        --formie-success-200: #bbf7d0;
-        --formie-success-300: #86efac;
-        --formie-success-400: #4ade80;
-        --formie-success-500: #22c55e;
-        --formie-success-600: #16a34a;
-        --formie-success-700: #15803d;
-        --formie-success-800: #166534;
-        --formie-success-900: #14532d;
-        --formie-success-950: #052e16;
+        /* Matches Tailwind CSS's Rose color palette. */
+        --formie-danger-50: #fff1f2;
+        --formie-danger-100: #ffe4e6;
+        --formie-danger-200: #fecdd3;
+        --formie-danger-300: #fda4af;
+        --formie-danger-400: #fb7185;
+        --formie-danger-500: #f43f5e;
+        --formie-danger-600: #e11d48;
+        --formie-danger-700: #be123c;
+        --formie-danger-800: #9f1239;
+        --formie-danger-900: #881337;
+        --formie-danger-950: #4c0519;
+
+        /* Matches Tailwind CSS's Emerald color palette. */
+        --formie-success-50: #ecfdf5;
+        --formie-success-100: #d1fae5;
+        --formie-success-200: #a7f3d0;
+        --formie-success-300: #6ee7b7;
+        --formie-success-400: #34d399;
+        --formie-success-500: #10b981;
+        --formie-success-600: #059669;
+        --formie-success-700: #047857;
+        --formie-success-800: #065f46;
+        --formie-success-900: #064e3b;
+        --formie-success-950: #022c22;
 
         /* Semantic color aliases */
         --formie-color-background: var(--formie-white);
@@ -116,16 +120,18 @@
         --formie-color-primary-soft: var(--formie-primary-100);
         --formie-color-focus-ring: var(--formie-primary-300);
         --formie-color-danger: var(--formie-danger-600);
+        --formie-color-danger-border: var(--formie-danger-200);
         --formie-color-danger-soft: var(--formie-danger-50);
         --formie-color-danger-dark: var(--formie-danger-900);
         --formie-color-success: var(--formie-success-500);
+        --formie-color-success-border: var(--formie-success-200);
         --formie-color-success-soft: var(--formie-success-50);
         --formie-color-success-dark: var(--formie-success-900);
         --formie-color-button-text: var(--formie-color-surface);
 
         --formie-focus-ring-border-color: var(--formie-color-focus-ring);
         --formie-shadow-focus: 0 0 0 3px rgba(119, 141, 238, 0.45);
-        --formie-shadow-danger-focus: 0 0 0 3px rgba(248, 180, 180, 0.45);
+        --formie-shadow-danger-focus: 0 0 0 3px rgba(253, 164, 175, 0.45);
 
         /* Form */
         --formie-title-form-size: 1.4rem;
@@ -365,4 +371,4 @@
         -webkit-font-smoothing: antialiased;
         -moz-osx-font-smoothing: grayscale;
     }
-}
+}

package/src/css/theme/forms/_form.css

@@ -146,6 +146,10 @@
         gap: var(--formie-gap-field-errors);
     }
 
+    .formie-field-errors:empty {
+        position: absolute;
+    }
+
     .formie-page-tabs {
         display: flex;
         flex-wrap: wrap;
@@ -191,4 +195,4 @@
     .formie-tab-error.formie-tab-current .formie-tab-link:hover {
         color: var(--formie-color-danger);
     }
-}
+}

package/src/index.ts

@@ -1,7 +1,7 @@
 export { createFormieClient } from '#core/create-formie-client';
 export { hydrateFormieModules } from '#core/hydrate-modules';
 export { formie } from '#core/formie';
-export { ModuleRegistry } from '#modules/registry';
+export { ModuleRegistry, clientRenderedModuleRegistry } from '#modules/registry';
 export { FormieValidator } from '#validation/validator';
 export { bindLegacyDomEventCompatibility } from '#compatibility/dom-adapter';
 export { bindLegacyValidatorCompatibility } from '#compatibility/validator-adapter';
@@ -85,8 +85,12 @@ export type {
 } from '#compatibility/event-map';
 export type { FormAction, FormMode, FormTransport, SubmitStage } from '#contracts/common';
 export type {
-    FormieModuleDefinition,
-    FormieModuleInstance,
+    BrowserModuleDefinition,
+    BrowserModuleInstance,
+    BrowserModuleFailure,
+    BrowserModuleHydrationReport,
+    AfterSubmitContext,
+    BeforeSubmitContext,
     ModuleHookContext,
     ModuleMatchContext,
     ModuleRegistrationOptions,
@@ -95,17 +99,16 @@ export type {
 } from '#contracts/modules';
 export type {
     FormRefreshTokensPayload,
-    FormDefinitionField,
-    FormDefinitionPage,
-    FormDefinitionPayload,
     FormEndpointPayload,
-    FormModuleManifest,
+    BrowserModuleEntry,
+    BrowserModuleKind,
+    BrowserModuleManifest,
     FormModuleTarget,
     FormModuleTargetType,
     FormRedirect,
     FormSubmitResult,
 } from '#contracts/schema';
-export type { ThemeClassMap } from '#contracts/theme';
+export type { BrowserThemeClassMap, ThemeClassMap } from '#contracts/theme';
 export type {
     ValidationConfig,
     ValidationContext,
@@ -123,3 +126,5 @@ export type {
     ParsedFieldReference,
     ResolveFieldValueResult,
 } from '#utils/field-references';
+
+export { mountClientRenderedModules } from '#core/client-rendered-modules';

package/src/js/contracts/client.ts

@@ -1,11 +1,13 @@
 import type { LegacyCompatibilityOptions } from '#compatibility/event-map';
 import type { FormAction, FormMode, FormTransport } from '#contracts/common';
-import type { FormieModuleDefinition, ModuleRegistrationOptions } from '#contracts/modules';
+import type { BrowserModuleDefinition, ModuleRegistrationOptions } from '#contracts/modules';
 import type { FormEndpointPayload, FormSubmitResult } from '#contracts/schema';
 
 export type FormMountOptions = {
     mode: FormMode;
+    /** REST/GraphQL select the HTML source; submission always uses the normal form endpoint. */
     transport?: FormTransport;
+    profile?: import('@verbb/formie-core').BrowserRequestOptions['profile'];
     formHandle?: string;
     endpoint?: string;
     payload?: FormEndpointPayload;
@@ -35,9 +37,9 @@ export type FormieClient = {
     update: (target: Element, options: Partial<FormMountOptions>) => Promise<FormieFormInstance>;
     getInstance: (target: Element) => FormieFormInstance | null;
     refreshForCache: (targetOrId: Element | string) => Promise<void>;
-    registerModule: (moduleDefinition: FormieModuleDefinition, options?: ModuleRegistrationOptions) => boolean;
+    registerModule: (moduleDefinition: BrowserModuleDefinition, options?: ModuleRegistrationOptions) => boolean;
     unregisterModule: (moduleId: string) => void;
-    getRegisteredModules: () => FormieModuleDefinition[];
+    getRegisteredModules: () => BrowserModuleDefinition[];
     scan: (root?: ParentNode) => Promise<FormieFormInstance[]>;
     observe: (root?: ParentNode) => () => void;
 };

package/src/js/contracts/common.ts

@@ -1,14 +1,13 @@
 export type FormAction = 'submit' | 'back' | 'save';
 
-export type FormMode = 'server-rendered' | 'client-rendered';
+export type FormMode = 'server-rendered';
 
 export type FormTransport = 'rest' | 'graphql';
 
 export type SubmitStage =
     | 'prepare'
-    | 'normalize'
     | 'validate'
-    | 'screen'
-    | 'authorize'
-    | 'dispatch'
-    | 'finalize';
+    | 'challenge'
+    | 'payment'
+    | 'send'
+    | 'result';

package/src/js/contracts/modules.ts

@@ -1,13 +1,14 @@
-import type { FormAction, FormMode, SubmitStage } from '#contracts/common';
-import type { FormModuleManifest, FormModuleTargetType, FormSubmitResult } from '#contracts/schema';
+import type { FormAction } from '#contracts/common';
+import type { BrowserModuleEntry, FormModuleTargetType, FormSubmitResult } from '#contracts/schema';
+import type { BrowserModuleKind, BrowserSurface } from '@verbb/formie-core';
 
 export type ModuleMatchContext = {
     root: Element;
     form: HTMLFormElement | null;
     target: Element;
     scope: FormModuleTargetType;
-    mode: FormMode;
-    manifestItem: FormModuleManifest;
+    surface: BrowserSurface;
+    manifestItem: BrowserModuleEntry;
 };
 
 export type ModuleHookContext = {
@@ -20,6 +21,8 @@ export type ModuleHookContext = {
 };
 
 export type ModuleSetupContext = ModuleHookContext & {
+    entryKey?: string;
+    surface: BrowserSurface;
     options?: Record<string, unknown>;
     on: (eventName: string, callback: (payload: unknown) => void) => () => void;
     emit: (eventName: string, payload?: unknown) => Promise<void>;
@@ -31,23 +34,49 @@ export type ModuleRegistrationOptions = {
 
 export type SubmitHookContext = {
     form: HTMLFormElement;
-    stage: SubmitStage;
     action: FormAction;
     formData: FormData;
+};
+
+export type BeforeSubmitContext = SubmitHookContext & {
     abort: (reason?: string) => void;
     isAborted: () => boolean;
     abortReason: () => string | undefined;
 };
 
-export type FormieModuleInstance = {
+export type AfterSubmitContext = SubmitHookContext;
+
+export type BrowserModuleInstance = {
+    assertReady?: () => void;
+    key?: string;
+    moduleId?: string;
+    kind?: BrowserModuleKind;
+    target?: Element;
+    update?: (ctx: ModuleSetupContext) => void | Promise<void>;
     destroy: () => void | Promise<void>;
-    onBeforeStage?: (ctx: SubmitHookContext) => void | Promise<void>;
-    onAfterStage?: (ctx: SubmitHookContext, result?: FormSubmitResult) => void | Promise<void>;
+    beforeSubmit?: (ctx: BeforeSubmitContext) => void | Promise<void>;
+    afterSubmit?: (ctx: AfterSubmitContext, result: FormSubmitResult) => void | Promise<void>;
 };
 
-export type FormieModuleDefinition = {
-    id: string;
-    kind: 'field' | 'captcha' | 'payment' | 'address' | 'core';
+export type BrowserModuleDefinition = {
+    moduleId: string;
+    version: 2;
+    surfaces: BrowserSurface[];
+    kind: BrowserModuleKind;
     match: (ctx: ModuleMatchContext) => boolean;
-    setup: (ctx: ModuleSetupContext) => Promise<FormieModuleInstance | void>;
+    setup: (ctx: ModuleSetupContext) => Promise<BrowserModuleInstance | void>;
+};
+
+export type BrowserModuleFailure = {
+    key: string;
+    moduleId: string;
+    required: boolean;
+    surface: BrowserSurface;
+    code: 'MODULE_UNAVAILABLE';
+    message: string;
+};
+
+export type BrowserModuleHydrationReport = {
+    readonly instances: readonly BrowserModuleInstance[];
+    readonly failures: readonly BrowserModuleFailure[];
 };

package/src/js/contracts/schema.ts

@@ -1,32 +1,7 @@
+import type { BrowserModuleManifest, PaymentDecision } from '@verbb/formie-core';
 import type { FormAction, SubmitStage } from '#contracts/common';
 import type { ThemeClassMap } from '#contracts/theme';
 
-export type FormDefinitionField = {
-    id: string;
-    uid?: string;
-    handle: string;
-    type: string;
-    label?: string;
-    required?: boolean;
-    settings?: Record<string, unknown>;
-    children?: FormDefinitionField[];
-};
-
-export type FormDefinitionPage = {
-    id: string;
-    name?: string;
-    fields: FormDefinitionField[];
-    settings?: Record<string, unknown>;
-};
-
-export type FormDefinitionPayload = {
-    formId?: string;
-    handle?: string;
-    pages?: FormDefinitionPage[];
-    settings?: Record<string, unknown>;
-    theme?: ThemeClassMap;
-};
-
 export type FormRefreshTokensPayload = {
     csrf?: {
         param: string;
@@ -34,6 +9,7 @@ export type FormRefreshTokensPayload = {
     };
     requestToken?: string;
     renderId?: string;
+    uploadCreateToken?: string;
     captchas?: Record<string, { sessionKey: string; value?: string }>;
     meta?: Record<string, unknown>;
 };
@@ -43,6 +19,14 @@ export type FormRedirect = {
     target?: 'same-tab' | 'new-tab';
 };
 
+export type FormCompletion = {
+    behavior: 'message' | 'redirect' | 'reload' | 'reset';
+    url: string | null;
+    target: 'same-tab' | 'new-tab';
+    message: string | null;
+    hideForm: boolean;
+};
+
 export type FormClientEvent = {
     event: string;
     payload: Record<string, string>;
@@ -50,13 +34,19 @@ export type FormClientEvent = {
 
 export type FormSubmitResult = {
     ok: boolean;
+    outcome?: string;
+    version?: number | null;
+    submissionUid?: string | null;
+    errors?: unknown;
+    session?: unknown;
+    completion?: FormCompletion | null;
     action?: FormAction;
     stage?: SubmitStage;
     code?: string;
     message?: string;
     keepSubmitLoading?: boolean;
+    payment?: PaymentDecision | null;
     fieldErrors?: Record<string, string[]>;
-    pageFieldErrors?: Record<string, Record<string, string[]>>;
     formErrors?: string[];
     nextPage?: { id: string } | null;
     redirect?: FormRedirect | null;
@@ -68,22 +58,10 @@ export type FormSubmitResult = {
 export type FormEndpointPayload = {
     html?: string;
     theme?: ThemeClassMap;
-    modules?: FormModuleManifest[];
+    modules?: BrowserModuleManifest;
     refreshTokens?: FormRefreshTokensPayload;
 };
 
-export type FormModuleTargetType = 'form' | 'field' | 'page' | 'button' | 'selector';
-
-export type FormModuleTarget = {
-    targetType: FormModuleTargetType;
-    targetId: string;
-};
-
-export type FormModuleManifest = {
-    id: string;
-    src?: string;
-    type: string;
-    targets?: FormModuleTarget[];
-    renderTargets?: string[];
-    config?: Record<string, unknown>;
-};
+export type { BrowserModuleEntry, BrowserModuleKind, BrowserModuleManifest } from '@verbb/formie-core';
+export type FormModuleTarget = import('@verbb/formie-core').BrowserModuleTarget;
+export type FormModuleTargetType = FormModuleTarget['type'];

package/src/js/contracts/theme.ts

@@ -1 +1,6 @@
-export type ThemeClassMap = Record<string, string[] | string>;
+import type { BrowserThemeStateKey } from '#theme/browser-theme-state.generated';
+
+export type BrowserThemeClassMap = Partial<Record<BrowserThemeStateKey, string[] | string>> & Record<string, string[] | string>;
+
+/** @deprecated Use BrowserThemeClassMap. */
+export type ThemeClassMap = BrowserThemeClassMap;