@u-krupaveho-kraba/form-schemas 0.1.0

package/schemas/campaign.js

@@ -0,0 +1,64 @@
+import * as z from "zod/mini";
+import { FormSchema } from "./form.js";
+export const FormReferenceSchema = z.object({
+    ref: z.string(),
+});
+export const CampaignFormDefinitionSchema = z.union([FormSchema, FormReferenceSchema]);
+export const VariantSchema = z.object({
+    id: z.string(),
+    name: z.string(),
+    definition: CampaignFormDefinitionSchema,
+    trafficWeight: z.number(),
+});
+export const FrequencyTargetingSchema = z.object({
+    minVisitCount: z.optional(z.number()),
+    maxDisplays: z.optional(z.number()),
+    minHoursBetweenDisplays: z.optional(z.number()),
+});
+export const CampaignTargetingSchema = z.object({
+    urlPatterns: z.optional(z.array(z.string())),
+    frequency: z.optional(FrequencyTargetingSchema),
+});
+export const CampaignScheduleSchema = z.object({
+    startsAt: z.optional(z.string()),
+    endsAt: z.optional(z.string()),
+});
+export const ImmediateTriggerSchema = z.object({ type: z.literal("immediate") });
+export const DelayTriggerSchema = z.object({ type: z.literal("delay"), seconds: z.number() });
+export const ScrollDepthTriggerSchema = z.object({
+    type: z.literal("scroll_depth"),
+    percent: z.number(),
+});
+export const ExitIntentTriggerSchema = z.object({ type: z.literal("exit_intent") });
+export const TriggerConditionSchema = z.discriminatedUnion("type", [
+    ImmediateTriggerSchema,
+    DelayTriggerSchema,
+    ScrollDepthTriggerSchema,
+    ExitIntentTriggerSchema,
+]);
+export const CampaignSchema = z.object({
+    id: z.string(),
+    name: z.string(),
+    version: z.literal(1),
+    targeting: CampaignTargetingSchema,
+    schedule: z.optional(CampaignScheduleSchema),
+    trigger: TriggerConditionSchema,
+    variants: z.array(VariantSchema),
+});
+// Ticket 113: field names match the real, already-deployed Ecomail publish
+// job's actual index-entry output, not FormReferenceSchema's {ref} shape.
+export const CampaignEntryRefSchema = z.object({
+    id: z.string(),
+    url: z.string(),
+    rules: z.optional(z.unknown()),
+});
+export const CampaignEntrySchema = z.union([CampaignEntryRefSchema, CampaignSchema]);
+// The campaigns.json v1 envelope (ADR 0008) -- see the CampaignsFile doc
+// comment in form-shared/src/types/campaign.ts for how this relates to the
+// shipped index+per-file HTTP delivery split.
+export const CampaignsFileSchema = z.object({
+    formatVersion: z.literal(1),
+    account: z.string(),
+    website: z.string(),
+    campaigns: z.array(CampaignSchema),
+});

package/schemas/element.js

@@ -0,0 +1,88 @@
+import * as z from "zod/mini";
+import { BaseElementPropertiesSchema, ButtonElementPropertiesSchema, CheckboxElementPropertiesSchema, HtmlElementPropertiesSchema, ImageElementPropertiesSchema, RadioElementPropertiesSchema, SelectElementPropertiesSchema, SpacerElementPropertiesSchema, TextElementPropertiesSchema, TextInputElementPropertiesSchema, } from "./elementProperties.js";
+export const ElementTypeSchema = z.enum([
+    "text_input",
+    "text",
+    "block",
+    "button",
+    "image",
+    "column",
+    "checkbox",
+    "radio",
+    "select",
+    "html",
+    "spacer",
+]);
+// mirrors the Element<T, P> generic helper in form-shared/types/element.ts.
+// Takes a raw shape (not a ZodMiniObject) — matching zod's own `extend()`
+// signature — because spreading a generic ZodMiniObject's `.shape` loses the
+// specific property types under TS's return-type inference; a raw shape
+// generic preserves them.
+function elementSchema(type, propertiesShape) {
+    return z.object({
+        id: z.string(),
+        type: z.literal(type),
+        properties: z.object({
+            ...BaseElementPropertiesSchema.shape,
+            ...propertiesShape,
+        }),
+    });
+}
+export const ButtonElementSchema = elementSchema("button", ButtonElementPropertiesSchema.shape);
+export const TextElementSchema = elementSchema("text", TextElementPropertiesSchema.shape);
+export const TextInputElementSchema = elementSchema("text_input", TextInputElementPropertiesSchema.shape);
+export const ImageElementSchema = elementSchema("image", ImageElementPropertiesSchema.shape);
+export const CheckboxElementSchema = elementSchema("checkbox", CheckboxElementPropertiesSchema.shape);
+export const RadioElementSchema = elementSchema("radio", RadioElementPropertiesSchema.shape);
+export const SelectElementSchema = elementSchema("select", SelectElementPropertiesSchema.shape);
+export const HtmlElementSchema = elementSchema("html", HtmlElementPropertiesSchema.shape);
+export const SpacerElementSchema = elementSchema("spacer", SpacerElementPropertiesSchema.shape);
+export const BlockColumnElementSchema = z.object({
+    id: z.string(),
+    type: z.literal("column"),
+    get properties() {
+        return z.object({
+            ...BaseElementPropertiesSchema.shape,
+            width: z.number(),
+            elements: z.array(FormElementSchema),
+        });
+    },
+});
+const blockLayoutBase = {
+    ...BaseElementPropertiesSchema.shape,
+};
+export const BlockElementPropertiesSchema = z.discriminatedUnion("block_type", [
+    z.object({
+        ...blockLayoutBase,
+        block_type: z.literal("single_column"),
+        columns: z.tuple([BlockColumnElementSchema]),
+    }),
+    z.object({
+        ...blockLayoutBase,
+        block_type: z.literal("double_column"),
+        columns: z.tuple([BlockColumnElementSchema, BlockColumnElementSchema]),
+    }),
+    z.object({
+        ...blockLayoutBase,
+        block_type: z.literal("triple_column"),
+        columns: z.tuple([BlockColumnElementSchema, BlockColumnElementSchema, BlockColumnElementSchema]),
+    }),
+]);
+export const BlockElementSchema = z.object({
+    id: z.string(),
+    type: z.literal("block"),
+    properties: BlockElementPropertiesSchema,
+});
+export const FormElementSchema = z.discriminatedUnion("type", [
+    ButtonElementSchema,
+    TextElementSchema,
+    TextInputElementSchema,
+    ImageElementSchema,
+    CheckboxElementSchema,
+    RadioElementSchema,
+    SelectElementSchema,
+    BlockElementSchema,
+    BlockColumnElementSchema,
+    HtmlElementSchema,
+    SpacerElementSchema,
+]);

package/schemas/elementProperties.js

@@ -0,0 +1,117 @@
+import * as z from "zod/mini";
+import { DistancePropertySchema, HexSchema } from "./helpers.js";
+import { FormBorderSchema } from "./formDisplay.js";
+export const BaseContainerPropertiesSchema = z.object({
+    hideOnMobile: z.boolean(),
+    hideOnDesktop: z.boolean(),
+    padding: z.optional(DistancePropertySchema),
+    border: z.optional(FormBorderSchema),
+    backgroundColor: z.optional(z.string()),
+});
+export const BaseElementPropertiesSchema = z.object({
+    ...BaseContainerPropertiesSchema.shape,
+    margin: z.optional(DistancePropertySchema),
+});
+export const LinkTargetSchema = z.object({
+    url: z.string(),
+    openInNewTab: z.optional(z.boolean()),
+});
+export const ButtonActionSchema = z.discriminatedUnion("type", [
+    z.object({ type: z.literal("next_step") }),
+    z.object({ type: z.literal("send") }),
+    z.object({ type: z.literal("close") }),
+    z.object({ type: z.literal("jump_to"), targetStepId: z.string() }),
+    z.object({ type: z.literal("redirect"), ...LinkTargetSchema.shape }),
+    z.object({ type: z.literal("call"), phoneNumber: z.string() }),
+]);
+export const ButtonWidthSchema = z.union([
+    z.literal("full"),
+    z.literal("auto"),
+    z.object({ unit: z.enum(["px", "%"]), value: z.number() }),
+]);
+export const ButtonAlignSchema = z.enum(["left", "center", "right"]);
+export const ButtonElementPropertiesSchema = z.object({
+    text: z.string(),
+    action: ButtonActionSchema,
+    fontColor: z.optional(z.string()),
+    fontFamily: z.optional(z.string()),
+    fontSize: z.optional(z.number()),
+    fontWeight: z.optional(z.enum(["normal", "bold"])),
+    fontStyle: z.optional(z.enum(["normal", "italic"])),
+    hover: z.optional(z.object({
+        backgroundColor: z.optional(z.string()),
+        fontColor: z.optional(z.string()),
+    })),
+    countAsConversion: z.optional(z.boolean()),
+    width: z.optional(ButtonWidthSchema),
+    height: z.optional(z.number()),
+    align: z.optional(ButtonAlignSchema),
+});
+export const InputTypeSchema = z.enum(["text", "email", "telephone", "number", "date", "url"]);
+export const InputFieldSchema = z.object({
+    type: InputTypeSchema,
+    name: z.string(),
+    label: z.string(),
+});
+export const TextInputElementPropertiesSchema = z.object({
+    ...InputFieldSchema.shape,
+    placeholder: z.string(),
+    labelColor: z.optional(HexSchema),
+});
+export const PreferenceOptionSchema = z.object({
+    value: z.string(),
+    label: z.string(),
+});
+export const PreferenceTypeSchema = z.enum(["checkbox", "hidden", "radio", "select"]);
+export const PreferenceSchema = z.object({
+    id: z.union([z.string(), z.number()]),
+    name: z.string(),
+    options: z.array(PreferenceOptionSchema),
+    type: z.optional(PreferenceTypeSchema),
+});
+export const PreferenceElementPropertiesSchema = z.object({
+    label: z.string(),
+    preference: z.nullable(PreferenceSchema),
+    custom_options: z.optional(z.array(PreferenceOptionSchema)),
+    required: z.boolean(),
+});
+export const SelectElementPropertiesSchema = z.object({
+    ...PreferenceElementPropertiesSchema.shape,
+    placeholder: z.string(),
+});
+export const CheckboxElementPropertiesSchema = PreferenceElementPropertiesSchema;
+export const RadioElementPropertiesSchema = PreferenceElementPropertiesSchema;
+export const TextElementPropertiesSchema = z.object({
+    text: z.string(),
+    color: z.string(),
+    fontFamily: z.optional(z.string()),
+    rotation: z.optional(z.number()),
+    textShadow: z.optional(z.object({
+        offsetX: z.number(),
+        offsetY: z.number(),
+        blur: z.number(),
+        color: z.string(),
+    })),
+});
+export const HtmlElementPropertiesSchema = z.object({
+    html: z.string(),
+});
+export const ImageElementPropertiesSchema = z.object({
+    src: z.string(),
+    link: z.optional(LinkTargetSchema),
+    width: z.optional(z.object({ unit: z.enum(["px", "%"]), value: z.number() })),
+    align: z.optional(z.enum(["left", "center", "right"])),
+    objectFit: z.optional(z.enum(["cover", "contain", "fill"])),
+    objectPosition: z.optional(z.string()),
+});
+// pre-authored for the upcoming floating_image element (currently commented
+// out in form-shared's ElementType/FormElementSchema) — not yet a consumer.
+export const FloatingImageElementPropertiesSchema = z.object({
+    src: z.string(),
+});
+export const SpacerElementPropertiesSchema = z.object({
+    height: z.number(),
+    showDivider: z.optional(z.boolean()),
+    dividerColor: z.optional(z.string()),
+    dividerThickness: z.optional(z.number()),
+});

package/schemas/form.js

@@ -0,0 +1,33 @@
+import * as z from "zod/mini";
+import { HexSchema } from "./helpers.js";
+import { StepSchema } from "./step.js";
+import { BasicFormDisplaySchema, MobilePopupFormDisplaySchema, PopupFormDisplaySchema, SliderFormDisplaySchema, } from "./formDisplay.js";
+export const FormTypeSchema = z.enum(["popup", "basic", "slider", "mobile_popup"]);
+export const FormLanguageSchema = z.enum(["cs", "en"]);
+export const FormThemeSchema = z.object({
+    corners: z.enum(["none", "sm", "md", "lg"]),
+    mainColor: HexSchema,
+    secondaryColor: z.tuple([HexSchema, HexSchema, HexSchema, HexSchema]),
+    backgroundColor: HexSchema,
+    fontFamily: z.string(),
+});
+const formBase = {
+    language: FormLanguageSchema,
+    steps: z.array(StepSchema),
+    theme: FormThemeSchema,
+    version: z.literal(1),
+    usedFonts: z.array(z.string()),
+};
+export const FormSchema = z.discriminatedUnion("type", [
+    z.object({ ...formBase, type: z.literal("basic"), display: BasicFormDisplaySchema }),
+    z.object({ ...formBase, type: z.literal("popup"), display: PopupFormDisplaySchema }),
+    z.object({ ...formBase, type: z.literal("slider"), display: SliderFormDisplaySchema }),
+    z.object({ ...formBase, type: z.literal("mobile_popup"), display: MobilePopupFormDisplaySchema }),
+]);
+// Renamed from FormCampaignSchema (ADR 0016) -- mirrors MountedForm in form-shared.
+export const MountedFormSchema = z.object({
+    id: z.string(),
+    name: z.string(),
+    definition: FormSchema,
+    variantId: z.optional(z.string()),
+});

package/schemas/formDisplay.js

@@ -0,0 +1,61 @@
+import * as z from "zod/mini";
+import { DistancePropertySchema, HexSchema } from "./helpers.js";
+export const BorderStyleSchema = z.enum(["none", "solid", "dashed", "dotted"]);
+export const FormBorderSchema = z.object({
+    width: z.number(),
+    color: HexSchema,
+    style: BorderStyleSchema,
+    sides: z.optional(z.enum(["all", "top", "right", "bottom", "left"])),
+    useTheme: z.optional(z.boolean()),
+});
+export const FormShadowSchema = z.object({
+    offsetX: z.number(),
+    offsetY: z.number(),
+    blur: z.number(),
+    spread: z.number(),
+    color: z.string(),
+    raw: z.optional(z.string()),
+});
+export const TeaserPropertiesSchema = z.object({
+    text: z.string(),
+    backgroundColor: z.string(),
+    textColor: z.string(),
+});
+export const CloseIconPropertiesSchema = z.object({
+    color: z.string(),
+    size: z.number(),
+    padding: DistancePropertySchema,
+    position: z.optional(z.object({ top: z.number(), right: z.number() })),
+    visibilityDelay: z.optional(z.number()),
+    closeOnEscape: z.optional(z.boolean()),
+});
+// mirrors FormPositionId in form-shared/types/form.ts
+export const FormPositionIdSchema = z.literal([1, 2, 3, 4, 5, 6, 7, 8, 9]);
+export const BaseFormDisplaySchema = z.object({
+    border: FormBorderSchema,
+    shadow: z.optional(FormShadowSchema),
+});
+export const BasicFormDisplaySchema = z.object({
+    ...BaseFormDisplaySchema.shape,
+    maxWidth: z.number(),
+});
+export const PopupFormDisplaySchema = z.object({
+    ...BaseFormDisplaySchema.shape,
+    position: z.object({
+        distance: DistancePropertySchema,
+        id: FormPositionIdSchema,
+    }),
+    closeIcon: CloseIconPropertiesSchema,
+    teaser: z.optional(TeaserPropertiesSchema),
+});
+export const SliderFormDisplaySchema = z.object({
+    ...BaseFormDisplaySchema.shape,
+    position: z.enum(["bottom-left", "bottom-center", "bottom-right"]),
+    closeIcon: CloseIconPropertiesSchema,
+    teaser: z.optional(TeaserPropertiesSchema),
+});
+export const MobilePopupFormDisplaySchema = z.object({
+    ...BaseFormDisplaySchema.shape,
+    closeIcon: CloseIconPropertiesSchema,
+    teaser: z.optional(TeaserPropertiesSchema),
+});

package/schemas/helpers.js

@@ -0,0 +1,12 @@
+import * as z from "zod/mini";
+// mirrors HEX = `#${string}` in form-shared/types/helpers.ts
+export const HexSchema = z.templateLiteral(["#", z.string()]);
+// mirrors DistanceProperty in form-shared/types/elementProperties.ts
+// (lives here so formDisplay and elementProperties can both import it without a cycle)
+export const DistancePropertySchema = z.object({
+    left: z.number(),
+    right: z.number(),
+    top: z.number(),
+    bottom: z.number(),
+    independent: z.boolean(),
+});

package/schemas/step.js

@@ -0,0 +1,15 @@
+import * as z from "zod/mini";
+import { FormElementSchema } from "./element.js";
+import { DistancePropertySchema, HexSchema } from "./helpers.js";
+export const StepDisplayPropertiesSchema = z.object({
+    padding: DistancePropertySchema,
+    backgroundColor: z.optional(HexSchema),
+    minHeight: z.optional(z.number()),
+});
+export const StepSchema = z.object({
+    type: z.literal("step"),
+    name: z.string(),
+    elements: z.array(FormElementSchema),
+    id: z.string(),
+    displayProperties: StepDisplayPropertiesSchema,
+});

package/types/index.d.ts

@@ -0,0 +1,18 @@
+export * from "./schemas/helpers.js";
+export * from "./schemas/formDisplay.js";
+export * from "./schemas/elementProperties.js";
+export * from "./schemas/element.js";
+export * from "./schemas/step.js";
+export * from "./schemas/form.js";
+export * from "./schemas/campaign.js";
+/**
+ * Serializes the full form type tree as standard JSON Schema —
+ * used to tell an LLM the exact shape of valid form JSON (issue 024).
+ */
+export declare function getFormJsonSchema(): Record<string, unknown>;
+/**
+ * Serializes the Campaign contract as standard JSON Schema — the artifact
+ * exported to ecomailapp so its PHP publish job can validate against the
+ * real schema instead of drifting silently (ticket 115/118, ADR 0017).
+ */
+export declare function getCampaignJsonSchema(): Record<string, unknown>;