Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/packages/form-widget/src/schema.ts
T
2026-07-08 16:15:37 +02:00

194 lines
6.7 KiB
TypeScript

/**
* Zod schemas for form definitions, themes and submission payloads.
*
* The Form-Builder produces JSON that conforms to {@link FormDefinitionSchema}.
* The embedded renderer + submission API both parse against the same schemas
* so the contract is enforced at every boundary.
*
* AK-P16c field-type set: 12 user-facing types plus the hidden honeypot
* system field. The public renderer and submit API parse the same schema so
* builder changes cannot bypass server validation.
*/
import { z } from "zod";
/** Field-types accepted by the AK-P16c form-builder. */
export const FieldTypeSchema = z.enum([
"text",
"textarea",
"number",
"date",
"time",
"select",
"multiselect",
"boolean",
"email",
"phone",
"file",
"photo",
"honeypot",
]);
/** Stable key used for honeypot fields in payloads / UIs. */
export const HONEYPOT_FIELD_KEY = "hp_extra_data" as const;
export type FormFieldType = z.infer<typeof FieldTypeSchema>;
const FieldOption = z.object({
value: z.string().min(1).max(120),
label: z.string().min(1).max(200),
});
export const ConditionalOperatorSchema = z.enum([
"equals",
"not_equals",
"contains",
"not_empty",
"empty",
"in",
]);
export const ConditionalLogicRuleSchema = z.object({
fieldKey: z.string().min(1).max(64),
operator: ConditionalOperatorSchema,
value: z.union([z.string().max(500), z.number(), z.boolean(), z.array(z.string().max(120)).max(50), z.null()]).optional(),
});
export const FieldValidationRulesSchema = z.object({
minLength: z.number().int().min(0).max(10000).optional(),
maxLength: z.number().int().min(1).max(10000).optional(),
min: z.number().optional(),
max: z.number().optional(),
pattern: z.string().max(500).optional(),
minSelected: z.number().int().min(0).max(50).optional(),
maxSelected: z.number().int().min(1).max(50).optional(),
acceptedFileTypes: z.array(z.string().min(1).max(100)).max(50).optional(),
maxFileSizeMb: z.number().int().min(1).max(100).optional(),
});
export type ConditionalLogicRule = z.infer<typeof ConditionalLogicRuleSchema>;
export type FieldValidationRules = z.infer<typeof FieldValidationRulesSchema>;
export const FormFieldSchema = z
.object({
key: z
.string()
.min(1)
.max(64)
.regex(/^[a-zA-Z][a-zA-Z0-9_]*$/, "key must start with a letter and contain only alphanumerics or underscores"),
type: FieldTypeSchema,
label: z.string().min(1).max(200),
helpText: z.string().max(500).optional(),
placeholder: z.string().max(200).optional(),
required: z.boolean().default(false),
options: z.array(FieldOption).max(50).optional(),
conditionalLogic: z.array(ConditionalLogicRuleSchema).max(20).default([]),
validationRules: FieldValidationRulesSchema.default({}),
minLength: z.number().int().min(0).max(10000).optional(),
maxLength: z.number().int().min(1).max(10000).optional(),
})
.superRefine((field, ctx) => {
if ((field.type === "select" || field.type === "multiselect") && (!field.options || field.options.length === 0)) {
ctx.addIssue({
code: z.ZodIssueCode.custom,
message: `field ${field.key}: type ${field.type} requires at least one option`,
});
}
if (field.minLength !== undefined && field.maxLength !== undefined && field.minLength > field.maxLength) {
ctx.addIssue({
code: z.ZodIssueCode.custom,
message: `field ${field.key}: minLength must be <= maxLength`,
});
}
const rules = field.validationRules ?? {};
if (rules.minLength !== undefined && rules.maxLength !== undefined && rules.minLength > rules.maxLength) {
ctx.addIssue({
code: z.ZodIssueCode.custom,
message: `field ${field.key}: validationRules.minLength must be <= maxLength`,
});
}
if (rules.min !== undefined && rules.max !== undefined && rules.min > rules.max) {
ctx.addIssue({
code: z.ZodIssueCode.custom,
message: `field ${field.key}: validationRules.min must be <= max`,
});
}
if (rules.minSelected !== undefined && rules.maxSelected !== undefined && rules.minSelected > rules.maxSelected) {
ctx.addIssue({
code: z.ZodIssueCode.custom,
message: `field ${field.key}: validationRules.minSelected must be <= maxSelected`,
});
}
});
export type FormField = z.infer<typeof FormFieldSchema>;
export const FormThemeSchema = z.object({
primaryColor: z
.string()
.regex(/^#[0-9a-fA-F]{3,8}$/u, "primaryColor must be a hex color")
.optional(),
backgroundColor: z
.string()
.regex(/^#[0-9a-fA-F]{3,8}$/u, "backgroundColor must be a hex color")
.optional(),
textColor: z
.string()
.regex(/^#[0-9a-fA-F]{3,8}$/u, "textColor must be a hex color")
.optional(),
fontFamily: z.string().max(200).optional(),
borderRadius: z.string().max(40).optional(),
});
export type FormTheme = z.infer<typeof FormThemeSchema>;
export const FormDefinitionSchema = z
.object({
title: z.string().min(1).max(200),
description: z.string().max(2000).optional(),
submitLabel: z.string().min(1).max(100).default("Submit"),
successMessage: z.string().min(1).max(500).default("Thanks — we received your submission."),
gdprConsentLabel: z.string().min(1).max(500).default("I agree to the processing of my data for this request."),
captchaEnabled: z.boolean().default(true),
fields: z.array(FormFieldSchema).min(1).max(50),
})
.superRefine((def, ctx) => {
const seen = new Set<string>();
for (const field of def.fields) {
if (seen.has(field.key)) {
ctx.addIssue({ code: z.ZodIssueCode.custom, message: `duplicate field key: ${field.key}` });
}
seen.add(field.key);
for (const rule of field.conditionalLogic ?? []) {
if (rule.fieldKey === field.key) {
ctx.addIssue({ code: z.ZodIssueCode.custom, message: `field ${field.key}: conditional rule cannot reference itself` });
}
}
}
});
export type FormDefinition = z.infer<typeof FormDefinitionSchema>;
/** Payload accepted by the submission API. Field-values are typed loosely
* here because each form has a different shape; the route handler validates
* required-ness + length against the form's stored definition. */
export const FormSubmissionPayloadSchema = z.object({
values: z.record(
z.string().max(64),
z.union([
z.string().max(10000),
z.boolean(),
z.number(),
z.array(z.string().max(1000)).max(50),
z.null(),
]),
),
origin: z.string().max(500).optional(),
turnstileToken: z.string().max(4096).optional(),
captchaToken: z.string().max(4096).optional(),
gdprAccepted: z.boolean().optional(),
idempotencyKey: z.string().min(8).max(120).optional(),
});
export type FormSubmissionPayload = z.infer<typeof FormSubmissionPayloadSchema>;