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,69 @@
+# 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, and rendering each carry sharp traps
+(the `:valid` re-validation loop, accumulating filters, message-override keying).
+Read `docs/internals/` before touching them. Note the internals describe the
+current **v3.x** line; a v4 redesign is planned but not in this code.
+
+## 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)
+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/README.md

@@ -0,0 +1,20 @@
+# Forms internals
+
+How `nette/forms` works underneath, for agents editing it. Split by the natural
+seams; each file is self-contained.
+
+- **[container-and-data.md](container-and-data.md)** — the Form/Container/Control
+  tree, how submitted HTTP data is read (the flat pull model), submission
+  detection, `fireEvents`, `getValues`, validation scope, and the deliberately
+  minimal `Control` contract.
+- **[validation.md](validation.md)** — the `Rules`/`Rule` tree, evaluation order,
+  and the sharp traps (`:valid`, filter re-application, message override keying).
+- **[rendering.md](rendering.md)** — `DefaultFormRenderer` wrappers and the Latte
+  runtime, including the `{form detached}`/`{form scope}` machinery.
+
+> **Version scope.** This describes the current **v3.x** release line (server-side
+> flat data model, string-op validation rules, a 5-method `Control` interface). A
+> v4 redesign of the data flow (layered pull, submission sources) and the
+> validation core (validator objects, message identifiers) is planned and will
+> change several of the mechanisms below; treat this as the v3.x source of truth
+> until then.

docs/internals/container-and-data.md

@@ -0,0 +1,96 @@
+# Container tree & HTTP data flow (v3.x)
+
+`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 the 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))`).
+- `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.
+
+`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)`, and **stops the chain the moment a handler invalidates
+the form**.
+
+`Form::validate()` (override) pulls the validation scope from the clicked
+`SubmitterControl` before delegating 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)` stores only `Container`/`Control`
+targets. `Form::validate()` passes them down; `Container::validate($controls)`
+validates only that subset (`[]` validates nothing). The same scope also narrows
+`getValues`, and is exported to the client as `data-nette-validation-scope`.
+
+## 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 when editing v3.x.

docs/internals/rendering.md

@@ -0,0 +1,49 @@
+# Rendering (v3.x)
+
+Two rendering paths: the programmatic `DefaultFormRenderer` and the Latte runtime.
+Both draw HTML from the same control **prototypes** (`getControl()`/`getLabel()`),
+so custom markup ultimately flows through those `Html` elements.
+
+## DefaultFormRenderer: the `$wrappers` map
+
+`DefaultFormRenderer` is table-oriented and driven by a nested `$wrappers` map:
+`section => key => Html|string|null` (e.g. `controls.container = 'table'`,
+`pair.container = 'tr'`, `label.container = 'th'`, `control.container = 'td'`, plus
+per-state keys like `pair.required`/`.error`/`.odd` and per-input-type control
+classes). `render()` fans out to `renderBegin`/`renderErrors`/`renderBody`/`renderEnd`;
+`renderBody` walks groups → `renderControls` → `renderPair` (label + control), with
+buttons aggregated into `renderPairMulti`. Wrapper elements are **cloned** per use
+(`getWrapper` clones an `Html`, else builds one from a tag string) so mutating one
+rendered element never leaks into the template. This renderer is stable/legacy —
+new rendering work goes through Latte.
+
+## Latte runtime: the `$stack` / `$detachedIds` machinery
+
+`Bridges/FormsLatte/Runtime` keeps two **parallel** stacks: `$stack` (the current
+form/container scope) and `$detachedIds` (the detached form id per stack level,
+`null` when not detached). `begin()` pushes and, for a `Form`, fires the render
+events; `end()` pops both. `get()` resolves an element from the current scope and —
+**this is the detached-form wiring** — if a detached id is active and the element is
+a `BaseControl`, sets `setHtmlAttribute('form', $id)` on it. `isNested()` is just
+`(bool) $stack`.
+
+`FormNode` compiles the `{form}` family in three modes:
+
+- **normal** — wraps the body in `renderBegin … body … renderEnd`.
+- **`{form scope name}`** (and the deprecated `{formContext}`) — renders the body
+  **only**, no `<form>` tag; used to (re-)enter a form/container without emitting
+  markup (e.g. an AJAX snippet). It takes **no arguments** (a compile error
+  otherwise). `isNested()` decides whether it enters a container or an existing UI
+  form.
+- **`{form detached name}`** — emits `renderBegin . renderEnd` **before** the body,
+  i.e. an empty `<form id=…></form>` (carrying hidden fields incl. the tracker),
+  and the body is rendered **after** it. The body's controls are not physically
+  nested in that form; each is linked back to it by the `form="<id>"` attribute that
+  `get()` stamps on. This exploits HTML5's out-of-tree `form=` association so a page
+  form can legitimately contain an independent inner `<form>`. A detached form
+  **must** have a non-empty id (else `InvalidStateException`), and nested containers
+  inherit the id while a nested `Form` starts fresh.
+
+The invariant a theme/renderer must respect: **the `{form}` machinery owns the
+`<form>` begin/end** across all three modes — nothing else may emit the `<form>` tag,
+or detached and nested forms break.

docs/internals/validation.md

@@ -0,0 +1,72 @@
+# Validation (v3.x)
+
+The densest part of the package, and the one with the sharpest traps.
+
+## The rule tree
+
+`Rules` holds an ordered `$rules[]`, a **separate** `$required` slot, and a
+`$parent` pointer. A `Rule` is a **mutable** value object: `control`, `validator`
+(**either a string op like `':email'` or a callable**), `arg`, `isNegative`,
+`message`, and an optional `branch` (a nested `Rules` for conditions). There is no
+`op` field — the op string *is* the validator, mapped to a built-in via
+`getCallback()` (`':email'` → `[Validator::class, 'validateEmail']`).
+
+- `addRule`: a `Filled` rule goes to `$required`, everything else to `$rules[]`;
+  `Valid` may not be a rule.
+- `addCondition` turns a bool argument into `:static`; `addConditionOn` creates a
+  `Rule` with a `branch` and **returns the branch**, which is why `addRule` chains
+  into the condition.
+- `elseCondition` clones the last rule and flips it — `Filled`↔`Blank` via a lookup,
+  otherwise `isNegative = !isNegative`.
+
+## Evaluation order and `$emptyOptional`
+
+`Rules::validate()`:
+
+- **`$emptyOptional`** = "not required and not filled". When set, every **non-branch**
+  rule except `Filled` is skipped — an empty optional field validates clean. It
+  propagates into branches, but a `Blank` branch resets it to `false`.
+- **Order is Blank → required → the rest**, imposed by `getIterator()` (priorities
+  0/1/2), not by insertion order.
+- **Filters are ordinary rules.** `addFilter` appends a rule whose closure does
+  `setValue(filter(getValue())); return true;`, at priority 2 — so a filter runs
+  **after** Blank and Required, interleaved with other rules, not in a dedicated
+  phase.
+
+## Trap: filters re-apply on every validation pass
+
+A filter mutates the control's value in place and **nothing ever restores the raw
+value**. Every call to `validate()` — direct, via `:valid`, or via toggle
+computation — re-runs the filter on the **already-filtered** value. A
+`addFilter(fn($v) => $v.'x')` appends another `x` each pass. In particular,
+computing toggle states calls the same `validateRule()` with full side effects, so
+**every render that reads toggles mutates values and can add phantom errors**
+(there is no dry-run mode in v3.x; `validateRule` always executes the callback).
+
+## Trap: `:valid` runs full validation and has no recursion guard
+
+The `:valid` op routes to `Validator::validateValid()`, which calls
+`$control->getRules()->validate()` — the **full** pipeline, applying filters and
+calling `addError`. Because toggle computation (`getToggleStates`) goes through the
+same `validateRule` path, a condition on `:valid` writes errors and mutates values
+on every toggle read. Worse, there is **no visited-set**: `A` conditioned on
+`B :valid` and `B` conditioned on `A :valid` recurse until the stack overflows.
+
+## Trap: `Validator::$messages` is keyed by op, so it misses callable validators
+
+`Validator::formatMessage()` resolves the message template from `$rule->validator`
+**only when it is a string** (`is_string($rule->validator) && isset($messages[...])`).
+So `Validator::$messages[Form::Email]` (and the NEON `forms: messages:`) overrides
+`addRule(Form::Email)` but **never** a custom callable/object rule — those fall back
+to the rule's explicit message or a "Missing validation message" error. There is no
+stable message id in v3.x; the op string is the only key.
+
+## Client export
+
+`Helpers::exportRules()` serializes rules into `data-nette-rules`. A rule exports
+only if `canExport()` — `is_string($validator) || Callback::isStatic($validator)`.
+A non-exportable **non-branch** rule (typically a mutating filter closure) **`break`s**
+and stops export of everything after it; inside a branch it merely `continue`s.
+`Form::Enum` has no JS counterpart and is exported as `Form::Equal` against the
+enum's case values. This "a mutating filter halts client validation of later rules"
+behavior is intentional: the client cannot reproduce an opaque server-side mutation.