CompositeRule

A composite conditional: multiple ConditionalRules combined with AND or OR.

Serialises to:
{"logic": "and", "rules": [{"field":"x","operator":"equal","value":"y"}, ...]}

Usage:
CompositeRule::all(
ConditionalRule::whenEqual('type', 'business'),
ConditionalRule::whenEqual('region', 'nl'),
)

ConditionalRule

A single conditional rule: show/hide a field when another field's value
satisfies a comparison.

This value object serialises to the JSON format expected by form-enhanced.js:

{"field": "type", "operator": "equal", "value": "business"}

Usage:
ConditionalRule::when('type', RuleOperator::Equal, 'business')

RuleEvaluator

Evaluates ConditionalRule / CompositeRule against a flat values map.

Extracted from Form::process() so that ConditionalValidator (or any other
code that needs to test a rule against submitted values) can reuse the
exact same semantics without duplication.

RuleOperator

Comparison operators for conditional field rules.

These values are serialised as strings in the data-conditional JSON
attribute consumed by form-enhanced.js on the client.

FormSchemaException

Thrown when a JSON form schema cannot be parsed or contains invalid data.

The message always describes which part of the schema is invalid so
CMS developers get actionable feedback.

AbstractField

Base class for typed form field definitions.

A field is a pure data+metadata object — it carries no HTML knowledge.
The FormRenderer decides how to present each field (label placement,
wrapper elements, error styles, etc.).

Usage:
TextField::create('first_name')
->label('Voornaam')
->placeholder('Jan')
->required();

AddressField

Composite veld voor postadressen.
Submit-shape: `<name>[street]`, `<name>[number]`, `<name>[zipcode]`,
`<name>[city]`, en optioneel `<name>[country]`.

Default-opmaak: NL — postcode + plaats op één regel, daaronder straat + nr.

CheckboxField

A single <input type="checkbox">.

Het label naast de checkbox wordt gezet via {@see checkboxLabel()}. Dat
kan ofwel een plain string zijn (auto-escaped) ofwel een {@see NodeInterface}
(El, ElCollection, fragment) — handig om links in te bouwen, bv:

CheckboxField::create('terms')
->checkboxLabel(El::fragment()
->text('Ik accepteer de ')
->add(El::make('a', ['href' => '/voorwaarden'])->text('algemene voorwaarden'))
);

Voor het veelvoorkomende "tekst — link — tekst"-patroon is er de helper
{@see checkboxLabelWithLink()} zodat je geen El-builder hoeft te kennen.

CompositeFieldInterface

Marker-interface voor velden die uit meerdere sub-inputs bestaan.

Een composite field heeft één naam in het schema (`klantnaam`) maar levert
server-side meerdere `<input>`-tags op (`klantnaam[first]`, `klantnaam[last]`,
etc.). De submit-data komt binnen als geneste array.

Form::process() en validators behandelen composites anders dan atomic-velden:
- $values[$name] is een array, niet een string
- validate() krijgt de array door, niet trim() of (string)cast

Render: composites leveren hun eigen `renderComposite(): string` die de
sub-inputs in één wrapper plaatst. FormRenderer delegeert daaraan.

Countries

Centrale landen-lijst voor zowel het losse `country`-type
(CountryField via FormFactory) als de `address.country` sub-velden.

Sleutels = ISO-3166-1 alpha-2 codes (uppercase).
Labels = NL-talige landnaam.

Niet uitputtend — meest gebruikte landen + EU. Caller kan eigen lijst
opgeven via `options()` op SelectField of `salutationOptions()`-achtige
setters in andere fields.

CreditCardField

Composite veld voor creditcard-invoer.

Submit-shape: `<name>[number]`, `<name>[expiry]`, `<name>[cvc]`.

Geen pretentie van PCI-compliance — bedoeld als front-end widget;
gevoelige data hoort sowieso niet door de eigen server te gaan, gebruik
een payment-provider tokenisatie. We valideren format (Luhn-check op
card-number, MM/YY-format, 3-4-cijfer cvc).

DateField

Single-date field. Form-value is altijd ISO `YYYY-MM-DD` (of
`YYYY-MM-DDTHH:MM` als time enabled is). De zichtbare display
komt van de JS-component `public/modules/date-picker.js` en
volgt de actieve locale (of de format-override).

DateField::create('birthdate')
->label('Geboortedatum')
->min('1900-01-01')
->max(date('Y-m-d'))
->locale('nl-NL')
->months(1);

DateRangeField

Range-date field — twee form-velden (from + till) onder één UI.

DateRangeField::create('stay')
->from('checkin', 'Aankomst')
->till('checkout', 'Vertrek')
->min('2026-01-01')
->max('2027-12-31')
->locale('nl-NL')
->months(2)
->patterns([
['key' => 'weekend', 'label' => 'Weekend', 'anchor' => [5,6,0], 'nights' => 3],
['key' => 'week', 'label' => 'Week', 'anchor' => [5,6,0], 'nights' => 7],
]);

AbstractField->name wordt gebruikt voor de wrapper-id en als prefix voor de
input-namen wanneer from()/till() niet expliciet geset zijn.

EmailField

MultiCheckboxField

Een groep checkboxes — meerdere selecties tegelijk mogelijk.

Submit-shape: `<name>[]` (PHP-stijl array). FormResult slaat 'm op als
array van geselecteerde waarden, vergelijkbaar met een composite maar
platter (geen vaste sub-keys, alle items horen tot dezelfde lijst).

In het JSON-schema:
{ "type": "multicheckbox", "name": "talen", "options": {"nl": "Nederlands", ...} }

Niet `composite: true` — gebruikt z'n eigen render-pad maar de submit-data
is een homogene array van strings, niet een geneste struct met sub-keys.

PersonalNameField

Composite veld voor persoonsnamen.

Submit-shape:
`<name>[first]`, `<name>[middle]`, `<name>[last]`
en optioneel `<name>[salutation]` als `includeSalutation()` aan staat.

Gebruik:
PersonalNameField::create('klantnaam')
->includeSalutation(true)
->required();

In het JSON-schema:
{ "type": "personalname", "name": "klantnaam", "includeSalutation": true }

PhoneNumberField

Telefoonnummer — atomisch text-veld met `type=tel` en optionele
format-validatie per language. Geen composite (geen sub-velden); de
country-prefix is gewoon onderdeel van de tekstwaarde.

RadioField

A group of <input type="radio"> buttons.

Example:
RadioField::create('type')
->label('Account type')
->options(['private' => 'Particulier', 'business' => 'Zakelijk']);

ReCaptchaField

Form-field voor Google reCAPTCHA. Drie modi:

ReCaptchaField::create()->siteKey('6Lc...')->mode(ReCaptchaMode::V2_CHECKBOX);
ReCaptchaField::create()->siteKey('6Lc...')->mode(ReCaptchaMode::V3)->action('contact');

De FormRenderer plaatst een placeholder-div (`.g-recaptcha`) en zorgt dat
de Google API geladen wordt. Server-side verificatie gebeurt apart via
{@see \Framework\Security\ReCaptcha\ReCaptchaVerifier} — dit veld zelf
doet alleen de UI.

De default `name` is `g-recaptcha-response` (Google's eigen veld).

SelectField

A `<select>` field.

Default krijgt het veld de `data-mm-select` attribuut, waardoor
`public/modules/custom-select.js` 'm automatisch upgraded naar
een dropdown met search + keyboard navigation. Per veld uit te
zetten met `->customSelect(false)`.

SelectField::create('country')
->label('Land')
->options(['nl' => 'Nederland', 'be' => 'België'])
->placeholder('Kies een land…')
->searchMode('always') // 'auto' | 'always' | 'never'
->searchThreshold(8); // toon search vanaf N opties (mode auto)

TextField

TextareaField

ZipcodeField

Postcode-veld met optionele "afstand tot"-dropdown.

- Atomic mode: één tekstveld met regex-validatie per language.
- Composite mode (`withDistance(true)`): tekstveld + select met km-keuzes.

Submit-shape:
- zonder distance: `<name>` = "1234 AB"
- met distance: `<name>[code]` = "1234 AB", `<name>[distance]` = "10"

Form

A form definition — an ordered collection of fields and layout rows.

Usage with plain fields:
$form = Form::create('contact', '/contact/submit')
->add(TextField::create('name')->label('Naam'))
->add(EmailField::create('email')->label('E-mail'));

Usage with side-by-side layout:
$form = Form::create('registratie', '/submit')
->add(FieldRow::of(
SelectField::create('land')->label('Land'),
TextField::create('telefoon')->label('Telefoonnummer'),
))
->add(FieldRow::of($postcode, $plaats)->widths([1, 2]));

$result = $form->process($_POST);

FormElementInterface

Marker interface for anything that can be added to a Form.

Both AbstractField and FieldRow implement this, so Form::add()
accepts either without losing type safety.

FormFactory

Builds a Form from a JSON schema string (typically stored in the database
by the CMS form editor).

This is the bridge between CMS storage and the PHP Form Builder renderer.
The renderer knows nothing about JSON; the CMS knows nothing about PHP classes.

Usage:
$form = FormFactory::fromJson($jsonFromDatabase);
$html = (new FormRenderer())->render($form, $result);

Schema shape:
{
"id": "contact",
"action": "/contact/submit",
"method": "POST", // optional, default POST
"elements": [
{
"type": "field",
"field": { ... }
},
{
"type": "row",
"widths": [1, 2], // optional, CSS fr units
"conditional": { ... }, // optional, row-level
"fields": [ { ... }, ... ]
}
]
}

Field shape:
{
"type": "text|email|textarea|select|checkbox|radio",
"name": "field_name",
"label": "Label tekst", // optional
"placeholder": "...", // optional
"hint": "Hulptekst", // optional
"default": "standaard waarde", // optional
"required": true, // optional
"disabled": false, // optional
"options": {"value": "Label"}, // select / radio only
"rows": 4, // textarea only
"inputType": "password", // text only, overrides type attr
"checkboxLabel": "Ik ga akkoord", // checkbox only
"validators": [ ... ], // optional
"conditional": { ... } // optional, field-level
}

Validator shapes:
{"type": "required"}
{"type": "minLength", "min": 2}
{"type": "maxLength", "max": 255}
{"type": "email"}
{"type": "regex", "pattern": "/^[0-9]+$/", "message": "{label} mag alleen cijfers bevatten."}

Conditional shapes (single):
{"field": "type", "operator": "equal", "value": "zakelijk"}

Conditional shapes (composite):
{"logic": "and", "rules": [ {...}, {...} ]}
{"logic": "or", "rules": [ {...}, {...} ]}

FormRenderer

Renders a Form definition into an El tree.

The renderer is the only place where HTML presentation decisions are made.
Fields know nothing about HTML; FormRenderer knows nothing about validation
rules — it only reads field metadata.

FormResult

Immutable result of Form::process().

Usage:
$result = $form->process($_POST);

if ($result->isValid()) {
$name = $result->value('name'); // atomic veld
$email = $result->value('email');
$klant = $result->valueArray('klantnaam'); // composite veld
}

$errors = $result->errorsFor('email'); // string[]

FieldRow

Groups fields side-by-side in a CSS grid row.

Basic usage — equal columns:
FieldRow::of(
SelectField::create('land')->label('Land'),
TextField::create('telefoon')->label('Telefoonnummer'),
)

Custom column widths (CSS fr units):
FieldRow::of($postcode, $plaats)->widths([1, 2])
// → "1fr 2fr" — postcode ≈ 1/3, plaats ≈ 2/3

The whole row can be conditionally hidden:
FieldRow::of($vat, $chamber)->showWhen(ConditionalRule::whenEqual('type', 'zakelijk'))

Responsive: on screens narrower than 640 px the columns collapse to a
single stack — no extra config needed, the CSS handles it.

ConditionalValidator

Decorator that wraps another ValidatorInterface and only delegates to it
when a `when`-rule evaluates true against the other submitted values.

This is what makes "verplicht als type=zakelijk" possible without changing
the inner validator. Used by FormFactory when a validator definition has
a `when`-clausule in its JSON-shape.

EmailValidator

MaxLengthValidator

MinLengthValidator

ReCaptchaValidator

Server-side validator voor een reCAPTCHA-token.

$form->add(ReCaptchaField::create()->siteKey($siteKey))
->validator('g-recaptcha-response',
new ReCaptchaValidator(
verifier: new ReCaptchaVerifier($secretKey),
remoteIp: $kernel->request->clientIp(),
));

Voor v3: geef `minScore` mee (default 0.5).

`remoteIp` is optioneel — Google accepteert het verzoek ook zonder, maar
met IP is de risk-scoring iets accurater. Geef 'm bij voorkeur door uit
`ServerRequest::clientIp()`.

RegexValidator

RequiredValidator

ValidatorInterface

A field validator.

Returns null on success, or a human-readable error message on failure.