# Popup Component — JSON Schema **Purpose:** Define the `PopupModal` JSON that the builder authors and the renderer consumes. This is **the data shape only**: how a host wires the editor and acts on the result is [`docs/EMBEDDING.md`](./docs/EMBEDDING.md), and the guided tour is the [README](./README.md). > The TypeScript in `src/schema/types.ts` is the source of truth; this document explains it. Where a field has an exported helper for reading it (`spanOf`, `placementOf`, `defaultCardWidth`, `effectiveTargets`), prefer the helper over defaulting at each call site. --- ## 1. Top-level object — `PopupModal` ```ts interface PopupModal { id: string; // unique id of this modal component name: string; // human label for the merchant (list view, not rendered) url: string; // merchant API endpoint hit on submit method: "GET" | "POST"; // request type to the merchant API trigger: PopupTrigger; // when the modal opens design: PopupDesign; // layout template placement?: PopupPlacement; // 'inline' (default) embeds in the page; 'modal' overlays it (see §7) formLayout?: PopupFormLayout; // 'stack' (default) or 'row' — how the body fields flow steps?: PopupSteps; // split the form across screens at its `page-break` items — omitted = one screen language?: "en" | "he"; // the language the popup speaks — decides its own wording and direction direction?: "ltr" | "rtl"; // text direction of the popup — default 'ltr', overruled by `language` launcher?: PopupLauncher; // the button that opens a `click`-triggered form (see §2) borderRadius?: number; // modal corner radius in px — default 14 fontFamily?: string; // 'host' to inherit the page's font, or a curated Google font name imageUrl?: string; // image source for the image-* designs // --- Card appearance (each overrides a built-in default) --- backgroundColor?: string; // card fill (hex) — default white backgroundOpacity?: number; // 0–1 alpha on backgroundColor — default opaque cardOpacity?: number; // 0–1 on the whole card, content included — default 1 backdropOpacity?: number; // 0–1 dim behind a modal — default 0.55 imageScrimOpacity?: number; // 0–1 scrim over the image-behind photo — default 0.45 imageFit?: "cover" | "contain"; // how the image fills its area — default 'cover' imagePosition?: "center" | "top" | "bottom" | "left" | "right"; // — default 'center' padding?: number; // body padding in px — default 28 width?: number; // card max width, in widthUnit (see §8) widthUnit?: "px" | "%"; // unit for width — default 'px' minHeight?: number; // card min height in px — default 350 htmlId?: string; // merchant-side mount point / page gate (see §7) urls?: string[]; // the page addresses it runs on — empty/absent = everywhere (see §7) dismissible?: boolean; // close button / overlay-click / esc — default true; forced on for a `click` trigger frequency?: PopupFrequency; // how often it may re-open — default 'always' onSuccess?: SubmitSuccess; // what the shopper sees after a successful submit (§6) onError?: SubmitError; // what the shopper sees after a failed submit (§6) onSubmitCallbackPayload?: CallbackPayloadEntry[]; // static extra key/value pairs sent with every submit (§6) submitTargets?: SubmitTarget[]; // extra hidden endpoints a host appends (§6) emailAutomations?: EmailAutomation[]; // declarative "email someone on submit" intents (§6) contentItems: ContentItem[]; // ordered items rendered in the modal body } interface CallbackPayloadEntry { key: string; // the payload key value: string; // the static value sent under that key } ``` | Field | Type | Notes | | -------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | `string` | Stable unique id for the modal. | | `name` | `string` | Internal name; shown in the Dashboard list, never rendered in the popup. | | `url` | `string` | The merchant's endpoint the form submits to. | | `method` | `'GET' \| 'POST'` | How the submit request is sent (see [§6 Submit assembly](#6-how-a-submit-is-assembled)). | | `trigger` | `PopupTrigger` | See [§2](#2-popuptrigger). | | `design` | `PopupDesign` | See [§3](#3-popupdesign). | | `placement` | `"inline" \| "modal"?` | `inline` (the default) embeds the form in the page flow at full width; `modal` is the full-page overlay. See [§7](#7-htmlid--merchant-controlled-placement). | | `formLayout` | `"stack" \| "row"?` | How the body fields flow. `stack` (default) gives each item its own line; `row` lays them out as a wide single-row signup bar. Independent of `placement`. | | `steps` | `PopupSteps?` | Splits the form across screens at its `page-break` items. Omitted → one screen, which is what every form did before steps existed. See [§3](#popupsteps--one-screen-at-a-time). | | `language` | `"en" \| "he"?` | The language the popup speaks: the renderer's own wording (Next, Submitting…, validation messages) and, through it, the direction it lays out in. Authored copy isn't translated. Independent of the builder UI language. | | `direction` | `"ltr" \| "rtl"?` | Text direction of the rendered popup. Default `ltr`, and overruled by `language` when the form carries one — the builder writes both together. A form saved before `language` existed is read as Hebrew when its direction is `rtl`, which is what that control meant at the time. | | `borderRadius` | `number?` | Corner radius of the modal card, in px. Default `14`. | | `fontFamily` | `string?` | Omitted → the built-in default (Arial). `'host'` → inherit the surrounding page's font (only meaningful on the live popup; the builder preview can't see it). Anything else is a curated Google font family, loaded on demand by the renderer. | | `imageUrl` | `string?` | Image URL used by `image-behind` / `image-right` / `image-left` / `image-top`. Ignored by `basic`. | | `backgroundColor` | `string?` | Card fill, as hex. Default white. See [§8](#8-card-sizing--appearance). | | `backgroundOpacity` | `number?` | `0`–`1` alpha applied to `backgroundColor` (a translucent card fill). Default opaque. | | `cardOpacity` | `number?` | `0`–`1` on the whole card, its content included. Default `1`. | | `backdropOpacity` | `number?` | `0`–`1` dim of the overlay behind a **modal**. Default `0.55`. Ignored when `placement` is `inline`. | | `imageScrimOpacity` | `number?` | `0`–`1` darkening scrim over the photo in the `image-behind` layout, so overlaid copy stays readable. Default `0.45`. | | `imageFit` | `"cover" \| "contain"?` | How the image fills its area. Default `cover` (crops to fill); `contain` fits the whole image. | | `imagePosition` | `"center" \| "top" \| "bottom" \| "left" \| "right"?` | Where the image sits in its area (a CSS `background-position` keyword). Default `center`. | | `padding` | `number?` | Card body padding in px. Default `28`. | | `width` | `number?` | Card max width, read in `widthUnit`. Picking a template writes the width it's designed around. See [§8](#8-card-sizing--appearance). | | `widthUnit` | `"px" \| "%"?` | Unit for `width`. Default `px`; `%` is read against the container the form sits in. | | `minHeight` | `number?` | Card minimum height in px. Default `350`. | | `htmlId` | `string?` | Page gate, and the anchor an `inline` form embeds into (see [§7](#7-htmlid--merchant-controlled-placement)). | | `urls` | `string[]?` | The page addresses the form runs on. Empty or absent means every page it's loaded on. See [§7](#urls--which-pages-it-runs-on). | | `dismissible` | `boolean?` | Whether the shopper can close it (X / overlay click / esc). Default `true`. Modal-only, like `trigger` and `frequency`: switching to `inline` normalizes all three. Ignored (always closable) when the trigger is `click` — a form the visitor opened is one they can always close. | | `frequency` | `PopupFrequency?` | Re-open cap, enforced via `localStorage`. Default `'always'`. Modal-only. | | `onSuccess` | `SubmitSuccess?` | Post-submit success behavior. See [§6](#after-submit--onsuccess--onerror). Default: close. | | `onError` | `SubmitError?` | Post-submit error behavior. See [§6](#after-submit--onsuccess--onerror). Default: inline message, form stays open. | | `onSubmitCallbackPayload` | `CallbackPayloadEntry[]?` | Static extra `key`/`value` pairs merged into every submit (the "custom submit callback values", currently hidden from the builder UI but still honored by the renderer). See [§6](#6-how-a-submit-is-assembled). | | `submitTargets` | `SubmitTarget[]?` | Extra hidden endpoints fired alongside the primary `url`: mailing-list automations, webhooks. Typically appended by the embedding host rather than authored in the builder. See [§6](#extra-submit-targets). | | `emailAutomations` | `EmailAutomation[]?` | Declarative "on submit → email this address" intents. **The builder and renderer never send anything** — the embedding host reads these off the JSON and sends the mail. See [§6](#email-automations). | | `contentItems` | `ContentItem[]` | See [§4](#4-contentitem). Rendered in `order` order. | --- ## 2. `PopupTrigger` Discriminated union on `type` — when the modal opens. ```ts type PopupTrigger = | { type: "delay"; seconds: number } // open N seconds after page load | { type: "scroll"; percent: number } // open after scrolling N% of the page | { type: "immediate" } // open as soon as the component mounts | { type: "click" }; // wait for a click — on our button, or on one of the site's own ``` ### `click` — opening from a button A `click` form renders nothing until something asks for it. Two things can: - **The launcher** — a button the merchant designs in the builder and the renderer draws where the form would have gone (inside the `htmlId` element, or at the end of `` when there is no id). Unstyled, it takes the submit button's fill, the card's rounding, and the renderer's own wording in the form's language, so a merchant who picks "on button click" and touches nothing else still gets a button that matches the form it opens. - **The site's own element** — anything on the page carrying `data-creaditor-open="
"`. The attribute may also be left empty (`data-creaditor-open`), which opens whichever form is mounted — with several click forms on a page it opens all of them, so name the id when there is more than one. Bound on the document, so an element rendered after the form mounted still works. Two mount-layer settings don't apply to a `click` form, because both describe a form that shows itself and this one waits to be asked: - **`frequency` is not consulted.** The button answers every press, on every visit. A cap here would spend itself on the first press and leave the page with a hole where the button was. - **`dismissible` is forced on** for a `click` modal. A visitor who opened something by choice has to be able to close it; a full-page overlay with no way out, entered deliberately, reads as a broken page. Use a timer trigger if a form genuinely must be read before it goes away. ```ts interface PopupLauncher { label?: string; // omitted → the renderer's own wording for the language styleProps?: StyleProps; // fill, text colour, size, width %, alignment borderRadius?: number; // omitted → the card's own borderRadius } ``` Unlike the other triggers, `click` survives a switch to `inline` placement: an embedded form can sit behind a button the same way a modal can, and it's the one mount-layer setting an inline form still honours. --- ## 3. `PopupDesign` A pre-defined layout template the merchant picks between. ```ts type PopupDesign = | "basic" // plain centered card, no image | "image-behind" // full-bleed background image (imageUrl), content overlaid | "image-right" // image (imageUrl) on the right, content on the left | "image-left" // image (imageUrl) on the left, content on the right | "image-top"; // image (imageUrl) across the top, content beneath ``` The image-based designs read the top-level `imageUrl`, and place it per `imageFit` / `imagePosition`. Only `image-behind` uses `imageScrimOpacity`. The design a form carries also decides its default card width — see [§8](#8-card-sizing--appearance). `design` is about *where the image sits*; [`formLayout`](#1-top-level-object--popupmodal) is about *how the fields flow*, and the two combine freely. ### `PopupSteps` — one screen at a time Present and `enabled`, the form is split at its `page-break` items. Absent or off, every item renders on one screen, which is what a form without this field has always done. ```ts interface PopupSteps { enabled: boolean; progress?: "bar" | "count" | "dots" | "none"; // the indicator above the fields — omitted = 'bar' autoAdvance?: boolean; // a radio choice moves to the next step on its own — omitted = off nextLabel?: string; // forward button on every step but the last — omitted = 'Next' backLabel?: string; // back button on every step but the first — omitted = 'Back' } ``` - The breaks live in `contentItems`, not here, so switching the mode off **keeps** them: an author trying it out and changing their mind gets their steps back on the way in. - `autoAdvance` is radio-only. A `checkbox` left unticked is a real answer, a `multi-select`'s first pick isn't its last, and a `select` fires `change` on arrow-key navigation in several browsers — any of those would advance a visitor before they had chosen. - The submit button needs no rule: it is sunk past every other item, page breaks included, so it is always on the last step. --- ## 4. `ContentItem` Each entry in `contentItems`. Shared shape below; per-`type` specifics in [§5](#5-per-type-details). ```ts interface ContentItem { id: string; // unique id for this item order: number; // sort order within the modal body type: ContentType; // what kind of item this is value?: string; // display text (heading / text); the markup for `html`; label for inputs / buttons placeholder?: string; // text-ish inputs — placeholder; falls back to `value` when omitted. On `select` it's the empty first row. height?: number; // spacer only — vertical gap in px (default 16) rows?: number; // textarea only — visible rows (default 4) min?: number; // number only — lowest value allowed; either bound may stand alone max?: number; // number only — highest value allowed span?: number; // columns of the 12-column body grid this item takes (see below) styleProps?: StyleProps; // merged into the React component's style options?: PopupOption[]; // radio / select / multi-select — the selectable choices (see §5) required?: boolean; // inputs only — block submit if empty private?: boolean; // inputs only — never rendered; value seeded from the page URL (see below) onSubmitRequest?: OnSubmitRequest; // how this item contributes to the request fieldKey?: string; // the host field this came from (CustomFieldDef.key); editor-only provenance, ignored by the renderer } type ContentType = | "heading" | "text" | "spacer" // a fixed-height vertical gap (see §5) | "html" // an author-written HTML block (see §5) | "page-break" // where a step form starts its next screen (see §1, `steps`) | "email" | "tel" | "date" | "number" | "radio" | "select" | "multi-select" | "checkbox" | "toggle" // the same yes/no as a checkbox, drawn as a switch | "free-text-input" | "textarea" | "hidden" // sent with the form, never rendered | "submit-button"; // the control that fires the submit (see §5) interface PopupOption { label: string; // shown to the shopper value: string; // sent in the request if selected } ``` ### `span` — the 12-column body grid The form body is a **12-column grid** and every item declares how many columns it takes. Two fields at `6` sit side by side; three at `4` make a row of thirds. Items flow onto one line while their spans fit and wrap when they don't, so there is **no "row" in the schema** — `contentItems` stays a flat, ordered list and reordering stays a splice. - Omitted → the full 12 columns, which is what every item did before spans existed. - Values are clamped to a whole `1`–`12`, and a line holds at most 4 items. - Read it through the exported `spanOf(item)`, which falls back to a percentage `styleProps.width` so forms authored against the older width control keep their proportions. ### `private` — a field the visitor never sees An input marked `private` is not rendered in the live popup, but it still submits. In the builder it appears dimmed, so the author can see and configure it, and the switch is labelled **Hidden**: the key is named `private` from before the [`hidden` content type](#content-types) existed, and the name stays only because forms are saved with it. Nothing user-facing says "private". Layout-only items ignore the flag. The flag only hides. Filling the field from the URL is not its doing, and never was exclusive to it: **every** field is seeded from the page URL's query string (see below), and a hidden one simply has no other way to be filled. ### Seeding a form from the page URL When a popup mounts, every field is matched against the **page URL's query string** by its submit key, and a match becomes that field's starting value. So `?email=dana@example.com` opens the form with the email box already filled, and the visitor can still edit or clear it. - A `hidden` item takes part too: carrying a value in from the link is the point of the type, so a param overrides the value the author fixed. With no param, the authored value stands. - A `radio` or `select` only accepts a param matching one of its authored `options`, and a `multi-select` keeps only the matching parts. A choice that was never offered is dropped rather than submitted. - A `number` ignores a param that isn't a number. ### `StyleProps` Applied to the rendered item's `style`. Each key has a default when omitted. ```ts interface StyleProps { align?: "left" | "center" | "right"; // default: 'center' (maps to textAlign) color?: string; // default: inherit / theme text color backgroundColor?: string; // default: transparent / theme background fontSize?: number; // px. default: the renderer's per-type size placeholderFontSize?: number; // px, the hint text inside a field. default: follows `fontSize` width?: number; // percent of the form column — superseded by `span`; still what the // canvas writes when a submit button is dragged narrower } ``` --- ## 5. Per-`type` details Which fields are meaningful per type: | `type` | `value` | `options` | `onSubmitRequest` | `required` | Renders as | | ----------------- | ----------------- | ----------- | ----------------- | ---------- | ----------------- | | `heading` | ✅ text shown | — | — | — | a heading | | `text` | ✅ text shown | — | — | — | a paragraph | | `spacer` | — | — | — | — | a vertical gap | | `html` | ✅ the markup | — | — | — | the markup itself | | `page-break` | — | — | — | — | nothing — it *is* the break | | `email` | field label | — | ✅ | optional | an email input | | `tel` | field label | — | ✅ | optional | a phone input | | `date` | field label | — | ✅ | optional | a date picker | | `number` | field label | — | ✅ | optional | a numeric input | | `radio` | group label | ✅ required | ✅ | optional | a radio group | | `select` | field label | ✅ required | ✅ | optional | a dropdown | | `multi-select` | group label | ✅ required | ✅ | optional | a checkbox list | | `checkbox` | label | — | ✅ | optional | a checkbox | | `toggle` | label | — | ✅ | optional | a switch | | `free-text-input` | field label | — | ✅ | optional | a text input | | `textarea` | field label | — | ✅ | optional | a multi-line box | | `hidden` | ✅ the fixed value | — | ✅ | — | nothing | | `submit-button` | ✅ button label | — | — | — | the submit button | - **`email` / `tel` / `number` / `free-text-input` / `textarea`** have a separate `placeholder`. `value` is the visible field label; `placeholder` is the greyed-out hint inside the input, edited independently in the builder. When `placeholder` is omitted it falls back to `value`. A `date` has no placeholder — the browser paints its own format hint. - **`spacer`** ignores `value`; it renders an empty block whose height is `height` px (default `16`). Use it to add breathing room between items. - **`page-break`** carries nothing and renders nothing: it marks *where* the next screen of a step form starts. A step is the run of items between two breaks, which is why there is no "step" object in the schema — `contentItems` stays one flat, ordered list and moving a field between steps is an ordinary reorder. Breaks are inert unless `steps.enabled` is on, so switching the mode off keeps them for when it's switched back on. See `steps` in [§1](#1-top-level-object--popupmodal). - **`html`** renders `value` as markup. It is sanitized first, and the result is what both the renderer and the builder canvas show: layout, text, table, ``, `` and `