@u-krupaveho-kraba/form-editor-schemas 0.1.0

package/README.md

@@ -0,0 +1,85 @@
+# @topol/form-editor-schemas
+
+Zod v4 schemas for the **Topol Form Editor's host-facing contract** — the
+options a Host App passes to `TopolEditor.init()`, the `CampaignItem` shape it
+loads and gets back on save, and the theme library it owns. Built on
+[`zod/mini`](https://zod.dev/packages/mini) for a smaller runtime footprint.
+
+## Install
+
+```bash
+npm install @topol/form-editor-schemas @topol/form-schemas zod
+```
+
+`zod` (`^4.1.11`) and `@topol/form-schemas` (`^0.4.0`) are peer dependencies,
+not bundled.
+
+## What's in here
+
+- **`TopolFormEditorOptionsSchema`** — the whole `init()` contract: the mount
+  target, locale, theme library, the `item`/`items` being edited, the file
+  manager config, and every Host callback (`onSave`, `onThemeSave`, …).
+- **`CampaignItemSchema` / `VariantSchema`** — the *editor-facing* item shape,
+  carrying a resolved `form` rather than the wire schema's `definition` (the
+  editor only ever holds real content to render, never a lazy `{ref}`
+  pointer). Their envelope fields come straight from `@topol/form-schemas`'
+  `CampaignItemBaseSchema`.
+
+  `form` is **nullable**. Inbound, `null` means a brand-new, never-saved
+  variant, and opens on a blank canvas. It is reachable outbound too, but
+  only narrowly: `onSave` mirrors back what the editor holds for a variant it
+  was handed and never asked to load: once a variant has been through
+  `load()`, a blank canvas has been substituted and it never saves back
+  `null`. A *missing* `form` key is rejected either way: an item carries
+  `form` or `variants`, never neither.
+- **`ThemeGroupSchema` / `ThemeEntrySchema` / `ThemeSavePayloadSchema`** — the
+  Host-owned theme library and the payload the Theme Panel sends back to it.
+- **`FileManagerOptionsSchema`** — an inlined mirror of `@topol/image-picker`'s
+  `FileOptions`, until that package gets a publish story of its own.
+
+## Usage
+
+```ts
+import {
+  TopolFormEditorOptionsSchema,
+  type TopolFormEditorOptions,
+} from "@topol/form-editor-schemas";
+
+const result = TopolFormEditorOptionsSchema.safeParse(options);
+if (!result.success) {
+  // result.error describes exactly which field failed and why
+}
+```
+
+The editor validates both `init()`'s options and `load()`'s payload against
+these schemas at runtime and **hard-stops** on failure — it refuses to mount,
+or refuses to apply, and reports through the `onError` callback (plus a
+`console.error`, since `onError` is optional) rather than rendering a
+partially-broken editor.
+
+## Why this is separate from `@topol/form-schemas`
+
+`@topol/form-schemas` describes the **published campaign JSON** — a stored
+artifact consumed by the form widget on customer sites and by backend publish
+jobs, which needs long-lived backward compatibility.
+
+This package describes **how a host boots the editor UI** — a live integration
+surface, not a stored artifact, with a different audience and a different
+compatibility promise. One version number can't clearly signal both "is my
+published campaign JSON still valid" and "did my editor integration just
+break". The dependency runs one way only: this package peer-depends on
+`@topol/form-schemas` for `Form`/`FormTheme`, never the reverse.
+
+## Versioning
+
+This package's version tracks the editor's own contract changes and is bumped
+in the same change that alters the contract. It is independent of
+`@topol/form-schemas`' version line.
+
+## Source
+
+Part of the [Topol](https://topol.io) editors monorepo, which is a private
+repository — the `repository` field above won't resolve for external
+visitors. This package is published publicly because its contents (schema
+shapes, no business logic or credentials) are safe to distribute even though
+the source repo isn't.

package/index.js

@@ -0,0 +1,4 @@
+export * from "./schemas/campaignItem.js";
+export * from "./schemas/theme.js";
+export * from "./schemas/fileManager.js";
+export * from "./schemas/options.js";

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@u-krupaveho-kraba/form-editor-schemas",
+  "version": "0.1.0",
+  "description": "Zod schemas for the Topol Form Editor's host-facing init/save contract",
+  "author": "Topol.io",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TOPOL-io/editors.git",
+    "directory": "packages/form-editor-schemas"
+  },
+  "type": "module",
+  "main": "./index.js",
+  "module": "./index.js",
+  "types": "./types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "import": "./index.js",
+      "require": "./index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@u-krupaveho-kraba/form-schemas": "^0.4.0",
+    "zod": "^4.1.11"
+  }
+}

package/schemas/campaignItem.js

@@ -0,0 +1,56 @@
+import * as z from "zod/mini";
+import { CampaignItemBaseSchema, FormSchema } from "@u-krupaveho-kraba/form-schemas";
+/**
+ * One AB-test alternative inside a `CampaignItem` (ADR 0028) -- its own
+ * `form` content lives right here, not behind a separate `load()` envelope.
+ *
+ * `form` (not the wire schema's `definition`) because the editor can only
+ * ever hold real content to render/edit, never a lazy `{ref}` pointer --
+ * see ADR 0028's "Considered and rejected" for why that union doesn't carry
+ * over to this layer.
+ *
+ * Nullable, not optional: a brand-new, never-saved variant (a `topol_forms`
+ * row with no definition yet) is sent as `form: null` and opens on a blank
+ * canvas (ticket 138). A *missing* `form` key is still rejected -- that's
+ * how the item union below enforces ADR 0028's "either `form` or
+ * `variants`, never neither".
+ *
+ * `null` is also reachable on the way *out*, though only narrowly: `onSave`
+ * mirrors back what the editor holds for a variant it was handed but never
+ * asked to load content for. Once a variant has been through `load()` the
+ * editor has substituted a blank canvas, so a loaded variant never saves
+ * back `null`.
+ */
+export const VariantSchema = z.object({
+    id: z.string(),
+    name: z.string(),
+    form: z.nullable(FormSchema),
+    trafficWeight: z.optional(z.number()),
+});
+/**
+ * The unit of independent client-side evaluation the editor session reads/
+ * edits (ADR 0028, reopening ticket 102/110). Carries its own content
+ * directly -- either a single `form` (the common, non-AB case) or
+ * `variants` (opt-in AB test), never both, never neither -- mirroring
+ * `@topol/form-schemas`' wire `CampaignItem` one-for-one except for that
+ * `form`/`definition` naming (see `VariantSchema`'s doc comment).
+ *
+ * The envelope fields (`id`, `name`, `targeting`, `trigger`,
+ * `exclusiveWith`, `campaignId`) are spread from `@topol/form-schemas`'
+ * `CampaignItemBaseSchema` rather than restated here -- the whole point of
+ * peer-depending on that package (ADR 0029 decision 2's one-directional
+ * dependency). `targeting`/`trigger` are this item's own rule, editable via
+ * the editor's targeting panel; `exclusiveWith` is shown read-only and is
+ * never editable there.
+ *
+ * Kept as a plain `z.union` rather than a `z.discriminatedUnion`, same as
+ * the wire schema: there is no literal tag field to discriminate on, the
+ * two branches are told apart structurally.
+ */
+export const CampaignItemSchema = z.union([
+    z.object({
+        ...CampaignItemBaseSchema.shape,
+        variants: z.array(VariantSchema),
+    }),
+    z.object({ ...CampaignItemBaseSchema.shape, form: z.nullable(FormSchema) }),
+]);

package/schemas/fileManager.js

@@ -0,0 +1,69 @@
+import * as z from "zod/mini";
+/**
+ * Locales the file manager UI ships translations for -- mirrors
+ * `@topol/image-picker`'s own `ILanguage`.
+ */
+export const FileManagerLanguageSchema = z.enum([
+    "en",
+    "fr",
+    "pt",
+    "es",
+    "ja",
+    "zh",
+    "ru",
+    "tr",
+    "de",
+    "sv",
+    "sk",
+    "nl",
+    "it",
+    "fi",
+    "ro",
+    "cs",
+    "pl",
+    "ko",
+    "vi",
+    "he",
+    "ar",
+]);
+/**
+ * `TopolFormEditorOptions.fileManager` -- the image picker / file manager's
+ * own configuration, forwarded through the editor untouched.
+ *
+ * **Inlined deliberately** (ADR 0029's "What's deliberately not built
+ * here"): the real declaration is `FileOptions` in `@topol/image-picker`,
+ * which is `"private": true` and has no publish story of its own. Giving it
+ * one is ticket 166, split off so this package wouldn't stall on a second
+ * package's plumbing. Until then this mirrors that type by hand -- and so
+ * must be re-checked against it whenever it changes, exactly the drift risk
+ * ADR 0029 exists to remove everywhere else.
+ */
+export const FileManagerOptionsSchema = z.object({
+    imageMaxSize: z.number(),
+    language: z.optional(FileManagerLanguageSchema),
+    urls: z.object({
+        folders: z.string(),
+        lambda: z.optional(z.string()),
+        imageUpload: z.string(),
+        GCS_SIGNED_URL: z.optional(z.string()),
+    }),
+    type: z.optional(z.string()),
+    id: z.optional(z.string()),
+    userId: z.string(),
+    apiKey: z.string(),
+    imageCompressionOptions: z.optional(z.object({
+        qualityJpeg: z.number(),
+        qualityPng: z.number(),
+        maxWidth: z.optional(z.number()),
+        enableAutoResize: z.optional(z.boolean()),
+    })),
+    pexelsApiKey: z.optional(z.string()),
+    light: z.optional(z.boolean()),
+    imageCreation: z.optional(z.boolean()),
+    disallowRemove: z.optional(z.boolean()),
+    preferences: z.optional(z.object({
+        defaultTilesView: z.optional(z.boolean()),
+        hidePexelsIntegration: z.optional(z.boolean()),
+        maxUploadingFiles: z.optional(z.number()),
+    })),
+});

package/schemas/options.js

@@ -0,0 +1,218 @@
+import * as z from "zod/mini";
+import { FormThemeSchema, InputFieldSchema, PreferenceSchema, } from "@u-krupaveho-kraba/form-schemas";
+import { CampaignItemSchema, } from "./campaignItem.js";
+import { FileManagerOptionsSchema } from "./fileManager.js";
+import { ThemeGroupSchema, } from "./theme.js";
+/**
+ * A Host-supplied callback. Functions can't be described structurally by
+ * Zod (and never survive the postMessage hop into the child iframe anyway,
+ * see `ChildInitOptions` in the editor itself), so validation is "is this
+ * callable" and the *signature* is carried by the type parameter, which is
+ * what `z.infer` reports.
+ */
+const callback = () => z.custom((value) => typeof value === "function");
+/**
+ * The Form Editor's own authoring-UI locale -- which language the person
+ * *building* a form sees the editor chrome in.
+ *
+ * Deliberately its own enum rather than a reuse of `@topol/form-schemas`'
+ * `FormLanguageSchema`, even though both list exactly `["en", "cs"]` today.
+ * That one is the locale of a *form's content* (`Form.language`, what an End
+ * Customer reads); this one is an editor-UI concern. Aliasing them would
+ * mean the day either list grows -- a new widget translation, or a new
+ * editor translation -- it silently widens the other contract too.
+ */
+export const EditorLanguageSchema = z.enum(["en", "cs"]);
+/** Comments left-panel section config. Omit, or leave `url` unset, to disable it. */
+export const CommentsConfigSchema = z.object({
+    /** Endpoint for the Comments feature (list/get/post/resolve), same pattern as `aiUrl`. Required for the panel to show at all. */
+    url: z.optional(z.string()),
+    /** Force-disables the panel even when `url` is set. Has no effect the other way -- omitting `url` disables it regardless of this flag. */
+    enabled: z.optional(z.boolean()),
+});
+/** Autosaves left-panel section config. Omit, or leave `url` unset, to disable it. */
+export const AutosaveConfigSchema = z.object({
+    /** Endpoint for the Autosaves feature (list/get/save), same pattern as `aiUrl`. Required for the panel to show at all. */
+    url: z.optional(z.string()),
+    /** Force-disables the panel even when `url` is set. Has no effect the other way -- omitting `url` disables it regardless of this flag. */
+    enabled: z.optional(z.boolean()),
+    /** Autosave interval in seconds. Minimum 30s in production; defaults to 60s. */
+    interval: z.optional(z.number()),
+});
+/** Display identity for a person shown as the author on comments/autosaves. */
+export const EditorUserSchema = z.object({
+    userId: z.union([z.string(), z.number()]),
+    name: z.string(),
+    avatarUrl: z.optional(z.string()),
+});
+export const EditorAuthorizeSchema = z.object({
+    apiKey: z.string(),
+    userId: z.union([z.string(), z.number()]),
+});
+export const EditorCallbacksSchema = z.object({
+    /**
+     * Fires on Save, carrying the complete, current `item`/`items` tree --
+     * whichever shape was configured at init, mirrored exactly, never
+     * wrapped/unwrapped the other way (ADR 0028). No dirty-only filtering: a
+     * host diffs against its own last-saved copy if it wants to know what
+     * changed.
+     */
+    onSave: z.optional(callback()),
+    onCreatePreference: z.optional(callback()),
+    /** Fired when the editor fails to initialize, or when a payload the Host sent fails validation (ADR 0029 decision 3). */
+    onError: z.optional(callback()),
+    /** Fired when the user clicks the WindowBar's close button (requires `"close"` in `windowBar`). The Host is responsible for tearing down/hiding the editor -- the child does not attempt its own teardown. */
+    onEditorClose: z.optional(callback()),
+    /**
+     * Fired when the user clicks the WindowBar's rename pencil, carrying the
+     * *current* `name` -- same delegate-to-Host shape as LPE's
+     * `onTemplateRename`. The child does not rename anything itself; the Host
+     * is expected to run its own rename UI and, if it commits a change, push
+     * the new value back down through a later `init()`/`name` update.
+     * Presence of this callback (not a separate boolean flag) is what shows
+     * the rename pencil.
+     */
+    onFormRename: z.optional(callback()),
+    /** Fired INSTEAD OF `onSave` when the user picks "Save and close" -- carries the same payload `onSave` would, plus signals the Host App to tear down/hide the editor. `onSave` does not also fire for this action. */
+    onSaveAndClose: z.optional(callback()),
+    /**
+     * Fired when the user saves a diverged theme from the Theme Panel (ticket
+     * 151, ADR 0022) -- `id` present means "update this owned theme in
+     * place," absent means "fork a new one" (the Host assigns the new id, the
+     * panel never generates one). The Host persists it and resolves with the
+     * complete, current `ThemeGroup[]` -- the panel replaces its local copy
+     * with whatever comes back rather than computing placement itself.
+     * Presence of this callback (not a separate boolean flag) is what shows
+     * the Save affordance at all.
+     */
+    onThemeSave: z.optional(callback()),
+    /**
+     * Renames an owned (unlocked) theme in place -- ticket 151, ADR 0022. A
+     * Locked Theme has no rename affordance, so `id` always refers to
+     * something the Host already owns. Resolves with the complete, current
+     * `ThemeGroup[]`, same replace-local-copy convention as `onThemeSave`.
+     */
+    onThemeRename: z.optional(callback()),
+    /**
+     * Deletes an owned (unlocked) theme -- ticket 151, ADR 0022. Same id/
+     * resolution/no-Locked-affordance rules as `onThemeRename`. The panel
+     * asks for confirmation itself before calling this.
+     */
+    onThemeRemove: z.optional(callback()),
+});
+/**
+ * ADR 0028: `item` and `items` are mutually exclusive -- a Host sends
+ * exactly one, or neither. Sending both isn't a runtime crash today (the
+ * editor's `options.item ?? options.items` picks `item` and silently
+ * discards `items`), which is precisely why it needs rejecting: quietly
+ * editing half the session a Host asked for is the "partially-broken"
+ * outcome ADR 0029 decision 3 exists to prevent.
+ *
+ * An *empty* `items` doesn't count as "sent": `items`' own doc says 0 entries
+ * behaves like neither was sent at all, so `{item, items: []}` has no
+ * ambiguity to reject -- there is nothing in `items` to silently discard.
+ * Rejecting it would contradict the field one line below it.
+ *
+ * Validity polarity (true = satisfies the rule) so `z.refine` reads the way
+ * `form-schemas`' own cross-field checks do.
+ */
+function onlyOneOfItemAndItems(options) {
+    const carriesItems = Array.isArray(options.items) && options.items.length > 0;
+    return options.item == null || !carriesItems;
+}
+const ITEM_AND_ITEMS_EXCLUSIVE_MESSAGE = "item and items are mutually exclusive -- send one or the other, not both";
+/**
+ * Everything a Host App passes to `TopolEditor.init()` -- the whole boot
+ * contract for embedding the Form Editor, and the reason this package
+ * exists (ADR 0029: it used to live only in `apps/form-editor/src/types/`,
+ * so every host hand-mirrored it and drifted).
+ *
+ * Validated at runtime by `init()` itself, with a hard stop on failure
+ * (ADR 0029 decision 3) -- a Host with a malformed payload has no safe
+ * partial state to mount into.
+ *
+ * Deliberately *not* here: `apps/form-editor`'s own transport internals
+ * (`ChildInitOptions`'s `hasOn*` flags, `CallbackName`, `EditorCallbacks`),
+ * which are an implementation detail of the postMessage bridge rather than
+ * part of the contract a Host authors against.
+ */
+/**
+ * `el` is `z.nullish`, not `z.optional`: a Vue host mounting the editor
+ * holds its container as a template ref typed `HTMLElement | null`, so
+ * `el: containerRef.value` legitimately carries `null` before that ref
+ * resolves. `null` here means "no container given" and falls back to
+ * `document.body`, exactly as an absent key does.
+ *
+ * Every *other* field stays strict. Widening them all would push
+ * `T | null | undefined` onto every Host writing TypeScript against this
+ * contract -- a real ergonomic cost -- to tolerate a `null` that, outside
+ * `el`, has no evidenced Host pattern behind it and is more likely a
+ * mistake worth surfacing (ADR 0029 decision 3).
+ */
+export const TopolFormEditorOptionsSchema = z
+    .object({
+    /** Container element (or CSS selector) to mount the editor iframe into. Defaults to document.body. */
+    el: z.nullish(z.union([
+        z.string(),
+        // Duck-typed on nodeType rather than `instanceof HTMLElement`: an
+        // element handed over from another window/iframe realm is not an
+        // `instanceof` of *this* realm's HTMLElement, and rejecting one here
+        // would refuse to mount for a Host that previously worked.
+        z.custom((value) => value?.nodeType === 1),
+    ])),
+    /** Editor authoring-UI locale. Defaults to "en". Read once at bootstrap -- there is no mechanism to change it after the editor mounts. */
+    language: z.optional(EditorLanguageSchema),
+    /** Per-key overrides for editor UI strings, keyed by dot-path (e.g. "controls.autosaves.title"). Applied once at bootstrap, merged into whichever locale ends up active. */
+    textOverride: z.optional(z.record(z.string(), z.string())),
+    /** Accepts the legacy flat shape for backward compatibility; a Host App is encouraged to move to `ThemeGroup[]` to supply locked/Brand Kit themes. */
+    themes: z.optional(z.union([z.array(FormThemeSchema), z.array(ThemeGroupSchema)])),
+    previewUrl: z.optional(z.string()),
+    /**
+     * A single `CampaignItem` this session reads/edits (ADR 0028) -- no array
+     * wrapper for something that isn't structurally a list. Mutually
+     * exclusive with `items` below; a host sends exactly one of the two.
+     */
+    item: z.optional(CampaignItemSchema),
+    /**
+     * Multiple `CampaignItem`s this session reads/edits (ADR 0028, reopening
+     * ticket 102/110) -- mutually exclusive with `item` above. 0 entries
+     * behaves like neither was sent at all.
+     */
+    items: z.optional(z.array(CampaignItemSchema)),
+    /** Which variant (inside whichever `item`/`items` entry contains it) the tab row should open on. For an entry with no `variants` (a bare `form`), matches that entry's own `id`. Defaults to the first entry of the first item. */
+    activeVariantId: z.optional(z.string()),
+    /** The account's registered website(s). 0: unchanged demo preview. 1: previewed directly, no picker. 2+: a picker in the Preview panel lets the user switch between them. */
+    websites: z.optional(z.array(z.string())),
+    inputFields: z.optional(z.union([
+        z.array(InputFieldSchema),
+        z.object({ extends: z.array(InputFieldSchema) }),
+    ])),
+    preferences: z.optional(z.array(PreferenceSchema)),
+    customPreferences: z.optional(z.boolean()),
+    /** Which buttons the WindowBar strip above TopBar shows. Omit, or leave empty, to keep the WindowBar hidden entirely (mirrors LPE's `windowBar` option). */
+    windowBar: z.optional(z.array(z.enum(["close", "fullscreen"]))),
+    /** Form/template name shown on the WindowBar's left side (mirrors LPE's `title`). Showing this alone (with no `windowBar` buttons) is enough to reveal the WindowBar strip. */
+    name: z.optional(z.string()),
+    callbacks: z.optional(EditorCallbacksSchema),
+    fileManager: z.optional(FileManagerOptionsSchema),
+    authorize: z.optional(EditorAuthorizeSchema),
+    /**
+     * Display identity for the current user -- shown as the author on
+     * comments/autosaves. Separate from `authorize`: `authorize.userId` is an
+     * account/license id sent to the real `/authorize` handshake, while
+     * `user.userId` identifies the specific person for comment/autosave
+     * attribution -- the two are independent and may differ (matching LPE's
+     * `authorize`/`currentUser` split).
+     */
+    user: z.optional(EditorUserSchema),
+    /** The account's team roster, used to resolve any OTHER author's name/avatar (not just the current user's own) on comments/autosaves. No need to exclude the current user -- self is always resolved from `user` first regardless. */
+    teamUsers: z.optional(z.array(EditorUserSchema)),
+    aiUrl: z.optional(z.string()),
+    widgetUrl: z.optional(z.union([
+        z.string(),
+        z.object({ overwrite: z.literal(true), script: z.string() }),
+    ])),
+    comments: z.optional(CommentsConfigSchema),
+    autosaves: z.optional(AutosaveConfigSchema),
+})
+    .check(z.refine(onlyOneOfItemAndItems, ITEM_AND_ITEMS_EXCLUSIVE_MESSAGE));

package/schemas/theme.js

@@ -0,0 +1,32 @@
+import * as z from "zod/mini";
+import { FormThemeSchema } from "@u-krupaveho-kraba/form-schemas";
+/**
+ * One theme in the Host-owned theme library (ticket 151, ADR 0022). `id` is
+ * absent for a preset the Host never persisted; `locked` marks a Brand Kit
+ * theme the editor may select but not edit in place.
+ */
+export const ThemeEntrySchema = z.object({
+    id: z.optional(z.string()),
+    name: z.string(),
+    locked: z.boolean(),
+    value: FormThemeSchema,
+});
+/**
+ * A label-only grouping of themes ("Presets", "Your saved themes") -- the
+ * Host owns both the labels and the placement; the Theme Panel never
+ * computes either (ADR 0022).
+ */
+export const ThemeGroupSchema = z.object({
+    label: z.string(),
+    themes: z.array(ThemeEntrySchema),
+});
+/**
+ * What the panel sends to `onThemeSave` (ADR 0022). `id` present means
+ * "update this owned theme in place"; absent means "fork a new one" -- the
+ * Host assigns the new id, the panel never generates one itself.
+ */
+export const ThemeSavePayloadSchema = z.object({
+    id: z.optional(z.string()),
+    name: z.string(),
+    value: FormThemeSchema,
+});

package/types/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./schemas/campaignItem.js";
+export * from "./schemas/theme.js";
+export * from "./schemas/fileManager.js";
+export * from "./schemas/options.js";