added AGENTS.md & DOCS

Author: dg

.gitattributes

@@ -1,8 +1,10 @@
 .gitattributes  export-ignore
 .github/        export-ignore
 .gitignore      export-ignore
+AGENTS.md       export-ignore
 ncs.*           export-ignore
 phpstan*.neon   export-ignore
+docs/           export-ignore
 tests/          export-ignore
 
 *.php*          diff=php

AGENTS.md

@@ -0,0 +1,70 @@
+# To My Agents!
+
+It is my fervent wish that this file guide every AI coding agent working with code in this repository.
+
+## Documentation
+
+Any distilled, agent-facing documentation for this package - how it works
+internally and the rationale behind key design decisions - lives in `docs/`.
+Consult it before non-trivial changes; it is the source of truth from which the
+public manual is distilled.
+
+The data flow, validation evaluation, control value semantics, rendering, and
+the client-side engine each carry sharp traps (the `:valid` re-validation loop,
+accumulating filters, message-override keying, silently skipped client
+validators). Read `docs/internals/` before touching them; it describes the code
+on the current branch - nothing more, nothing less.
+
+## Project Overview
+
+Nette Forms (since 2004) creates, validates, and processes web forms with **both**
+server-side (PHP) and client-side (`netteForms.ts`) validation kept in sync.
+
+- **PHP Version**: 8.3 - 8.5
+- **Package**: `nette/forms`
+- **Dependencies**: nette/component-model, nette/http, nette/utils; Latte 3.1.4+.
+
+## Essential Commands
+
+```bash
+# PHP tests / static analysis
+vendor/bin/tester tests -s -C        # or: composer tester
+vendor/bin/tester tests/Forms/ -s -C
+composer phpstan                     # PHPStan level 8
+
+# JavaScript (client-side validator) - uses npm
+npm install
+npm run build       # UMD + minified + .d.ts into src/assets/; runs JS tests after
+npm run test        # Vitest (jsdom); test:watch / test:ui also available
+npm run lint:fix    # ESLint with @nette/eslint-plugin
+npm run typecheck
+```
+
+## Conventions
+
+- Every PHP file starts with `declare(strict_types=1);`; **tabs** for indentation;
+  everything typed; single quotes unless the string has an apostrophe; Nette Coding
+  Standard. JS source is TypeScript in `src/assets/`, built by Rollup (a
+  `spaces2tabs()` plugin enforces tabs, `fix()` adds the header + auto-init).
+- PHP tests are Nette Tester `.phpt` (`tests/Forms/`, `tests/Forms.DI/`,
+  `tests/Forms.Latte/`); JS tests are Vitest specs in `tests/netteForms/`.
+
+## Working in this repo
+
+- **Validation is dual-sided: a rule lives in BOTH places.** A server rule is a
+  `Validator::validateXxx` method; its client twin goes in `src/assets/validators.ts`
+  and is exported via `data-nette-rules`. Adding/changing a rule means editing PHP
+  *and* TypeScript, then `npm run build`.
+- **`:valid` toggle evaluation is a known trap.** Computing toggle states runs full
+  validation (with filters and `addError`) and there is **no recursion guard**, so
+  it can mutate values and add phantom errors. Filters also **accumulate** (each pass
+  re-applies to the already-filtered value). See `docs/internals/validation.md`.
+- **Custom-message override is keyed by the operation string** and only reaches
+  string validators - a callable/object validator never picks it up.
+- **CSRF defaults to same-origin `Sec-Fetch-Site` checking** (token-based protection
+  is deprecated); `allowCrossOrigin()` disables protection entirely - use with care.
+- **A new control needs a PHP class** (`src/Forms/Controls/`, extend `BaseControl`),
+  optional `Validator.php` support, a client validator, and tests on both sides.
+- User-facing how-to (Latte tags, validation-rule catalog, conditions/toggles, NEON
+  messages, data mapping, rendering customization, JS loading) is manual material
+  and lives in the public web docs, not here.

docs/internals/client-side.md

@@ -0,0 +1,69 @@
+# Client-side validation
+
+The TypeScript sources in `src/assets/` re-implement the server's rule evaluation
+in the browser. `formValidator.ts` is the engine (`FormValidator` class:
+evaluation, toggles, form wiring), `validators.ts` holds the rule twins
+(`Validators` class, one method per op), `index.umd.ts` glues them into the
+exported `Nette` object (plus `version` and `webalize`). The Rollup build's
+`fix()` plugin rewrites the UMD banner so the built file **auto-runs
+`initOnLoad()`** unless the page pre-sets `Nette = {noInit: true}`.
+
+The engine mirrors `Rules::validate()` semantics — `emptyOptional` computed via
+`:filled`, a `:blank` condition resetting it in the branch, `~` negation parsed
+from the op string, conditions recursing — but the invariants around it differ
+from PHP in ways an agent must know.
+
+## Op resolution: unknown validators are skipped silently
+
+`validateRule()` maps `':minLength'` → `Validators.minLength`; an exported static
+callable `Custom::method` becomes method name `Custom_method` (`::` → `_`,
+backslashes stripped). **A missing method returns `null` and the rule is simply
+skipped** — the exact opposite of PHP, where an unknown string op throws in
+`addRule()`. A server rule exported without a JS twin therefore validates as if
+it did not exist, with no error anywhere. Validators may themselves return `null`
+("cannot decide", e.g. malformed regexp) with the same skip effect.
+
+## Values: filters never touch the DOM
+
+`getValue()` normalizes per element type (radio/checkbox-list expansion via
+`RadioNodeList`, `FileList` for uploads, trimmed strings for text inputs).
+`getEffectiveValue()` additionally maps the `data-nette-empty-value` attribute
+(exported by `TextBase`) to `''` and can apply filters — but filtering runs the
+rules with a `{value}` **ref object**; normalizing validators (`url`, `integer`,
+`float`) write into that ref, never into the input. Combined with the
+`#preventFiltering` re-entrancy guard, the client is immune to both PHP traps:
+**filters do not accumulate and validation does not mutate visible state**.
+
+## Form wiring (`initForm`)
+
+Forms without any `data-nette-rules` element are left alone. Otherwise the
+engine computes initial toggles and — unless the form already had `novalidate` —
+sets `form.noValidate = true` (taking over from HTML5) and installs a `submit`
+handler that cancels submission on failure. `validateForm()` first lets the
+browser report any `badInput` element (`reportValidity`), then walks elements
+with rules; a sender with `formnovalidate` narrows validation via a **regex
+built from `data-nette-validation-scope`** matched against the rewritten control
+name (`a[b][c]` → `a-b-c-`). Errors accumulate in `formErrors` and are shown at
+the end in a `<dialog>` modal (fallback `alert`), focusing the first offender.
+`reset` re-runs toggles; a GET form with `data-nette-compact` compacts
+checkbox-list values into one comma-joined field via the `formdata` event.
+
+`elem.validity.badInput` also short-circuits `validateRule` itself: such an
+element counts as *filled* but nothing else.
+
+## Toggles
+
+`toggleForm()` recomputes **all** toggles from scratch into `#formToggles`,
+OR-combining states per id, then applies them via `toggle()` — which treats a
+`^\w[\w.:-]*$` selector as an id, otherwise as a CSS selector, and flips
+`hidden`. On the first pass each control participating in a condition gets a
+`change` listener (deduplicated through a `WeakMap`) that re-runs `toggleForm`.
+`toggle()` receives the source element and event precisely so userland can
+override it (animations etc.).
+
+## `:submitted` depends on an external writer
+
+`Validators.submitted` compares `elem.form['nette-submittedBy'] === elem`, but
+**nothing in this package ever assigns that property** — integrations (e.g.
+Naja) set it on button click. Without one, a client-side `:submitted` condition
+is always false.

docs/internals/container-and-data.md

@@ -0,0 +1,104 @@
+# Container tree & HTTP data flow
+
+`Form extends Container extends Nette\ComponentModel\Container`. The tree and the
+way submitted data reaches each control are one emergent model.
+
+## Data is pulled, per control, from one flat array
+
+There is **no central distribution** of submitted data. Each control pulls its own
+value, lazily, driven by the component monitor:
+
+- `BaseControl`'s constructor registers `monitor(Form::class, …)`; when a
+  **non-disabled** control is attached to an **anchored, submitted** form it calls
+  `loadHttpData()` (`BaseControl::loadHttpData` →
+  `setValue(getHttpData(Form::DataText))`). `loadHttpData` is the template-method
+  hook overridden by `SubmitButton`, `CsrfProtection`, etc.
+- `BaseControl::getHttpData()` asks `Form::getHttpData($type, $htmlName)`, where
+  `$htmlName` is the full bracketed path (`getHtmlName()` →
+  `Helpers::generateHtmlName(lookupPath(Form::class))`); an explicitly set `name`
+  attribute overrides the generated one, and setting it on a submitted form
+  re-triggers `loadHttpData()`.
+- `Form::getHttpData()` **lazily** fills `Form::$httpData` **once**, from
+  `receiveHttpData()`, and sets `$submittedBy = is_array($data)`. This is the only
+  place `$httpData` is populated.
+- `Helpers::extractHttpData()` walks that flat array by the path: it strips `]`,
+  turns `.`→`_`, splits on `[`, then `Arrays::get`s down the keys. A trailing `[]`
+  triggers per-element sanitization; `DataKeys` preserves keys, otherwise
+  `array_values` renumbers.
+
+**Sanitization is by data-type bit** (`Helpers::sanitize`): `DataText` normalizes
+newlines only; `DataLine` collapses newlines to spaces and trims (single-line
+inputs); `DataFile` passes only a real `FileUpload` (else `null`). An agent adding a
+control picks the bit that matches; picking `DataText` for a single-line field
+leaks newlines.
+
+## Submission detection lives in `receiveHttpData`
+
+`Form::receiveHttpData()` returns `null` (not submitted) unless **all** hold:
+
+1. the HTTP method matches the form's method;
+2. for POST, the request passes the **same-origin** check
+   (`!crossOrigin && $request->isFrom(FetchSite::SameOrigin)`) — the actual
+   Sec-Fetch-Site / cookie logic lives in **nette/http**, not here; Forms only calls
+   `isFrom`. `allowCrossOrigin()` disables this (and token protection via
+   `CsrfProtection`/`addProtection()` is deprecated in favor of it);
+3. the **`_form_` tracker** (present only for a **named** form) equals the form's
+   name. An unnamed form has no tracker, so detection rests on method + data alone;
+   for GET an **empty query string** already means "not submitted".
+
+`submittedBy` starts as the bool `true` and is **narrowed to a `SubmitButton`
+instance** by `SubmitButton::loadHttpData()` when that button is filled — that is
+how "which button submitted" is known.
+
+## `fireEvents` order
+
+`Form::fireEvents()` runs a fixed sequence: return if not submitted; validate only
+if there are no errors yet; then `$submittedBy->onClick`/`onInvalidClick` (for a
+`SubmitButton`), then `onSuccess` (if valid), then `onError` (if invalid), then
+always `onSubmit`; a warning fires if nothing was handled. `invokeHandlers`
+inspects each handler's first parameter type by reflection to pass `$form` / the
+button / `getValues($type)` (a second parameter, if present, always gets
+`getValues`), and **stops the chain the moment a handler invalidates the form**.
+
+`Form::validate()` (override) pulls the validation scope from the clicked
+`SubmitterControl`, runs `validateMaxPostSize()` (a form-level error when
+`CONTENT_LENGTH` exceeds `post_max_size` — reusing the `MaxFileSize` message),
+then delegates to `Container::validate($controls)`.
+
+## Reading values back out of the tree
+
+- **`getValues()` = `getUntrustedValues()` + guards.** It **throws** if called
+  during validation (`validated === null`), warns if the form is invalid, applies
+  the validation-scope narrowing, then delegates.
+- **`getUntrustedValues()`** walks the component tree: non-omitted `Control`s
+  contribute `getValue()` (with enum coercion against the target property type),
+  nested `Container`s recurse. The return shape is `ArrayHash` by default, or
+  `$mappedType` (`setMappedType`), or a class you pass — a **DTO class** is built by
+  reflection (constructor with required params, else property assignment).
+- **`isOmitted()`** controls exclusion (`setOmitted`, or a disabled control with
+  `omitted === null`); the tracker, buttons, and CSRF field are omitted.
+- **`setDefaults()` on a submitted form only fills *disabled* controls**
+  (`onlyDisabled: form->isSubmitted()`), which is why setting defaults after submit
+  appears to "do nothing" for normal fields.
+
+## Validation scope
+
+A `SubmitButton::setValidationScope(iterable)` accepts `Container`/`Control`
+targets or component-name strings (resolved via `$form->getComponent()`); anything
+else throws. `Form::validate()` passes them down; `Container::validate($controls)`
+validates only that subset (`[]` validates nothing). The same scope also narrows
+`getValues` (a container is included when any of its ancestors is in scope), and is
+exported to the client as `data-nette-validation-scope` (plus `formnovalidate` on
+the button).
+
+## The `Control` contract is deliberately minimal — and not honored
+
+`Control` declares only **five** methods: `setValue`, `getValue`, `validate`,
+`getErrors`, `isOmitted`. In practice the framework requires far more of every
+control (`getHtmlName`, `getControl`, `getLabel`, `getForm`, `getOption`,
+`isFilled`, …), so it is written against `BaseControl` everywhere. The current state
+papers over the gap with **`instanceof BaseControl` guards** (a handful of sites:
+`Validator` for `%label`, the renderer's `translate`, `Form`, `Blueprint`, the Latte
+runtime) and a **`method.notFound` ignore block in `phpstan.neon`** that enumerates
+the "missing" interface methods. Treat "a control is a `BaseControl`" as the real,
+if unstated, contract.

docs/internals/controls.md

@@ -0,0 +1,68 @@
+# Control value semantics
+
+Per-control quirks that are invisible from the `Control` interface and bite
+during data loading (`setDefaults`) and reading (`getValues`).
+
+## Choice controls: strict on defaults, lenient on submission
+
+`ChoiceControl` / `MultiChoiceControl` enforce membership **asymmetrically**:
+
+- **`setValue()` (and thus `setDefaults()`) throws** for a value outside
+  `$items`, unless `checkDefaultValue(false)` is called first — the classic trap
+  when filling a form from the DB before `setItems()` has the full list.
+  `BackedEnum` values are unwrapped to their backing value first.
+- **`loadHttpData()` does not validate at all.** The submitted key is stored raw;
+  membership is enforced lazily by **`getValue()`, which filters at read time**:
+  an unknown or per-item-disabled key reads as `null` (multi: dropped). Use
+  `getRawValue()` to see what was actually submitted.
+
+Keys pass through PHP array-key coercion (`key([(string) $v => null])`), so
+numeric strings become ints. `setDisabled(array)` disables individual items (the
+control itself stays enabled); since `isFilled()` builds on `getValue()`, a
+selection of a disabled item counts as *not filled*. `MultiChoiceControl`
+appends `[]` to `getHtmlName()`.
+
+`SelectBox` adds prompt machinery (the prompt key is `''`, extended with tabs on
+collision; for a required select it is rendered hidden+disabled) and its
+constructor **auto-adds a closure condition + `Filled` rule** (message
+`SelectBox::Valid`) guarding the "no prompt, nothing chosen" case — being a
+non-exportable *condition*, it is skipped in the client export, per the
+`exportRules` rules. `setItems()` accepts optgroups (nested arrays) and flattens
+them for the underlying membership checks.
+
+## TextBase: two values and a maxlength side-channel
+
+`TextBase` keeps the coerced `$value` **and** a string `$rawValue`; rendering
+uses `$rawValue` / the translated `emptyValue`. `getValue()` maps a value equal
+to the (trimmed, translated) `emptyValue` to `''`, and `setNullable()` further
+maps `''` to `null`. `emptyValue` is exported to the client as
+`data-nette-empty-value`.
+
+`TextBase::addRule()` mirrors the value into the DOM: a `Length`/`MaxLength`
+rule also sets the `maxlength` attribute — but **only while all existing rules
+are still client-exportable**; once a non-exportable non-branch rule (a filter)
+precedes it, the attribute shortcut is disabled, consistent with the export
+`break` (the browser must not hard-enforce a limit the filter may change).
+
+## UploadControl: value comes only from HTTP
+
+`setValue()` is a **no-op** — uploads cannot be defaulted; `getValue()` returns
+the `FileUpload`(s), or a dummy `FileUpload(null)` when nothing was uploaded
+(`setNullable()` switches that to `null`). The constructor auto-adds rules: the
+`isOk()` check wrapped in `addCondition(true)` (a `:static` condition,
+explicitly so the non-exportable callable doesn't `break` the export of the
+sibling `MaxFileSize` rule), `MaxFileSize` from `upload_max_filesize`, and for
+`multiple` a `MaxLength` capped by `max_file_uploads`. A monitor throws unless
+the form method is POST and stamps `enctype="multipart/form-data"` on the form
+prototype. `getHtmlName()` appends `[]` when multiple.
+
+## DateTimeControl: normalization funnel
+
+Every inbound value (`setValue`, rule args) goes through `normalizeValue()`:
+string/timestamp/`DateTimeInterface` → `DateTimeImmutable`, then **truncated by
+type** (date: time zeroed; time: date collapsed to 0001-01-01, seconds dropped
+unless `withSeconds`). `loadHttpData()` swallows parse errors into `null`.
+`getValue()` re-shapes by `setFormat()`: object (default), timestamp, or a
+`format()` string. `getControl()` derives `min`/`max` attributes from `Min`/
+`Max`/`Range` rules — again stopping at the first non-exportable rule. The
+validator-side special-casing lives in `docs/internals/validation.md`.