autumn_web/

nested_form.rs

//! Nested (`has_many`) form binding — a parent struct plus one child
//! collection, decoded and validated in a single extractor.
//!
//! # Overview
//!
//! [`NestedChangesetForm<P, C>`] is the nested-form counterpart of
//! [`ChangesetForm<T>`](crate::form::ChangesetForm): it decodes a form body
//! carrying a parent struct `P` **and** a repeated child collection `C`
//! (rendered with input names like `items[0][sku]`, `items[1][sku]`, …),
//! runs [`validator::Validate`] on the parent and on every non-destroyed
//! child row, and captures per-field errors so the whole form can be
//! re-rendered inline after a failed submission.
//!
//! The child collection is identified by the [`NestedChild::COLLECTION`]
//! constant, which names the field group in input names
//! (`items[i][field]`) and in combined error keys (`items[1].quantity`).
//!
//! # Wire format
//!
//! ```text
//! name=Order+1                 // parent field
//! items[0][sku]=A-1            // child row 0, subfield `sku`
//! items[0][quantity]=2         // child row 0, subfield `quantity`
//! items[1][sku]=B-2            // child row 1
//! items[1][quantity]=3
//! items[1][_destroy]=1         // optional: mark row 1 for removal
//! ```
//!
//! Row indices need not be contiguous — client-side removal can leave gaps
//! (`items[0]`, `items[2]`) which are compacted in ascending order to
//! preserve row order. The compacted 0-based position is what appears in
//! combined error keys and is what a renderer iterates.
//!
//! # Binding and validating
//!
//! ```rust
//! use autumn_web::nested_form::{decode_nested_urlencoded, NestedChild};
//!
//! #[derive(serde::Deserialize, validator::Validate)]
//! struct NewOrder {
//!     #[validate(length(min = 1))]
//!     name: String,
//! }
//!
//! #[derive(serde::Deserialize, validator::Validate)]
//! struct NewLineItem {
//!     #[validate(length(min = 1))]
//!     sku: String,
//!     #[validate(range(min = 1))]
//!     quantity: i32,
//! }
//!
//! impl NestedChild for NewLineItem {
//!     const COLLECTION: &'static str = "items";
//! }
//!
//! let pairs = vec![
//!     ("name".to_string(), "Order 1".to_string()),
//!     ("items[0][sku]".to_string(), "A-1".to_string()),
//!     ("items[0][quantity]".to_string(), "2".to_string()),
//!     // second row is invalid: quantity is below the range minimum
//!     ("items[1][sku]".to_string(), "B-2".to_string()),
//!     ("items[1][quantity]".to_string(), "0".to_string()),
//! ];
//!
//! let changeset = decode_nested_urlencoded::<NewOrder, NewLineItem>(&pairs)
//!     .expect("parent decodes");
//!
//! // The invalid child surfaces under its per-row combined key, and the whole
//! // changeset refuses to yield a valid `(parent, children)` pair.
//! assert!(!changeset.errors_for("items[1].quantity").is_empty());
//! assert!(changeset.errors_for("items[0].quantity").is_empty());
//! assert!(!changeset.is_valid());
//! assert!(changeset.into_valid().is_err());
//! ```
//!
//! # Per-row error keys
//!
//! Errors are addressable with `#[validate(nested)]`-style combined keys of
//! the shape `"{COLLECTION}[{i}].{sub}"`. A child whose `quantity` fails
//! validation on the (compacted) second row surfaces under
//! [`errors_for("items[1].quantity")`](NestedChangeset::errors_for); a bare
//! `"items[1]"` returns that row's row-level (parse) error. Parent field
//! errors keep their plain field-name keys and are delegated to
//! [`Changeset::errors_for`]. This is exactly the key shape a Maud renderer
//! reads back per row via [`RowScope::errors_for`], so a failed submission
//! re-renders each field's message inline next to the offending input.
//!
//! # `_destroy` marker
//!
//! A child subfield named `_destroy` with a truthy value (`"1"`, `"true"`,
//! `"on"`) marks its row for removal. Destroyed rows are **retained** for
//! re-rendering (so the checkbox state survives a round-trip) but never
//! contribute to `valid_children`, so [`into_valid`](NestedChangeset::into_valid)
//! drops them from the returned child vector. [`RowScope::destroy_checkbox`]
//! renders the durable no-JS control that drives this.
//!
//! # Rendering: `inputs_for` + htmx / no-JS
//!
//! With the `maud` feature, [`inputs_for`] renders the repeating child block:
//! it re-emits every submitted row (values + inline errors) and then appends
//! at least one blank template row so a user can add a child **without any
//! JavaScript** — the pre-rendered blank row's `items[n][…]` inputs post like
//! any other. Because the browser submits that blank row's empty inputs, the
//! decoder applies Rails-style `reject_if: :all_blank`: a child row whose every
//! non-`_destroy` subfield is blank (empty or whitespace-only) is **ignored**
//! entirely — never decoded, validated, or persisted — so the auto-rendered
//! blank template row is safe with no JS and never becomes a phantom child that
//! blocks submission (on a required-field child) or saves an empty row (on an
//! all-optional child). Supplying [`InputsForOptions::add_row_url`] additionally emits an
//! htmx "Add row" button (`hx-get` + `hx-swap="beforeend"`, with
//! `hx-params="index"` so only the `hx-vals` `index` is sent — no form fields
//! and no CSRF/submit token — are serialized into the fragment request);
//! [`nested_row_fragment`] renders the server response
//! for that endpoint. htmx is a progressive enhancement layered over the no-JS
//! path — it is never required.
//!
//! # Handler + atomic save
//!
//! ```rust,ignore
//! #[post("/orders")]
//! async fn create(
//!     mut db: Db,
//!     form: NestedChangesetForm<NewOrder, NewLineItem>,
//! ) -> impl IntoResponse {
//!     match form.into_valid() {
//!         Ok((order, items)) => save_order_with_items(&mut db, order, items).await,
//!         Err(form) => (StatusCode::UNPROCESSABLE_ENTITY, render(&form)).into_response(),
//!     }
//! }
//! ```
//!
//! A parent and its children must be persisted **atomically** — a half-saved
//! order with only some of its line items is never acceptable. Do it inside a
//! **single** [`Db::tx`](crate::db::Db::tx): insert the parent, read back its
//! generated `id`, stamp each child's foreign key with that `id`, and insert
//! the children — all on the one `conn` the closure is handed. Returning `Err`
//! from anywhere in the closure (a failing child, a DB constraint violation)
//! rolls the **whole** transaction back, so neither the parent nor any child
//! row is left behind.
//!
//! ```rust,ignore
//! use scoped_futures::ScopedFutureExt;
//!
//! db.tx(|conn| async move {
//!     let order = diesel::insert_into(orders::table)
//!         .values(&new_order)
//!         .returning(Order::as_returning())
//!         .get_result(conn)
//!         .await?;
//!     for mut item in new_items {
//!         item.order_id = order.id; // stamp the FK from the freshly-read parent id
//!         diesel::insert_into(line_items::table)
//!             .values(&item)
//!             .execute(conn)
//!             .await?; // any Err here rolls back the parent insert too
//!     }
//!     Ok::<_, diesel::result::Error>(order.id)
//! }.scope_boxed())
//! .await
//! ```
//!
//! Use **raw diesel inserts on `conn`**, not a generated
//! [`Repository`](macro@crate::repository) `create`: that `create` opens its *own*
//! `Db::tx`, and `Db::tx` cannot be re-entered on the same connection — the
//! nested call trips the nested-transaction guard and returns a `400`. Keep the
//! whole parent-plus-children unit of work in the one outer `tx`.
//!
//! See `tests/integration/nested_form_atomic_save.rs` for the rollback
//! correctness gate (a failing child leaves **zero** rows in either table) and
//! `tests/integration/nested_form_order_example.rs` for the full create flow.

// autumn-panic-gate: request-path module — production code path must be panic-free.
// See CONTRIBUTING.md "Request-path panic gate". Justify exceptions with
// #[allow(clippy::<lint>, reason = "…")] at the narrowest scope.
#![cfg_attr(
    not(test),
    deny(
        clippy::unwrap_used,
        clippy::expect_used,
        clippy::panic,
        clippy::unreachable,
        clippy::todo,
        clippy::unimplemented,
        clippy::indexing_slicing,
        clippy::string_slice,
        clippy::arithmetic_side_effects,
    )
)]

use std::collections::{BTreeMap, BTreeSet, HashMap};

use axum::extract::{FromRequest, Request};
use axum::response::IntoResponse;

use crate::form::{
    Changeset, IntoChangeset, decode_urlencoded_dropping_blank_optional_fields,
    validation_errors_to_map,
};
#[cfg(feature = "maud")]
use crate::form::{FieldKind, FieldOptions, FieldSpec, render_field};

// ── NestedChild ────────────────────────────────────────────────────

/// A child row type bound as part of a nested (`has_many`) form.
///
/// The [`COLLECTION`](NestedChild::COLLECTION) constant names the field
/// group used in input names (`items[i][field]`) and in combined error
/// keys (`items[1].quantity`).
pub trait NestedChild: serde::de::DeserializeOwned + validator::Validate + Send {
    /// Field-group name used in input names (`items[i][field]`) and error
    /// keys (`items[1].quantity`). e.g. `"items"`.
    const COLLECTION: &'static str;
}

// ── NestedRow ──────────────────────────────────────────────────────

/// One submitted child row, retained for re-rendering regardless of whether
/// it parsed or validated.
#[derive(Debug, Clone)]
pub struct NestedRow {
    /// Raw submitted subfield values (`sku` → `["A-1"]`), used to pre-fill
    /// inputs when re-rendering after a failed submission. A repeated subfield
    /// (`items[0][tags]=a&items[0][tags]=b`) keeps every value in order
    /// (issue #3394).
    values: HashMap<String, Vec<String>>,
    /// Per-subfield validation (or parse) errors. A row that failed to parse
    /// records its error under the offending subfield's name (via
    /// `serde_path_to_error`), falling back to the empty-string (row-level) key
    /// only when no field can be identified.
    errors: HashMap<String, Vec<String>>,
    /// `true` when the row carried a truthy `_destroy` marker.
    destroyed: bool,
}

impl NestedRow {
    /// The raw submitted value for subfield `sub`, if present. For a repeated
    /// subfield this is the last value; [`values`](Self::values) returns all
    /// of them.
    #[must_use]
    pub fn value(&self, sub: &str) -> Option<&str> {
        self.values
            .get(sub)
            .and_then(|v| v.last())
            .map(String::as_str)
    }

    /// Every raw submitted value for subfield `sub`, in submission order, or an
    /// empty slice. Use it to re-render a `Vec` subfield (a checkbox group or a
    /// `<select multiple>`) after a failed submission (issue #3394).
    #[must_use]
    pub fn values(&self, sub: &str) -> &[String] {
        self.values.get(sub).map_or(&[], Vec::as_slice)
    }

    /// Validation messages for subfield `sub`, or an empty slice.
    ///
    /// A row-level parse failure is stored under the empty-string key, so
    /// `row.errors_for("")` returns any whole-row decode error.
    #[must_use]
    pub fn errors_for(&self, sub: &str) -> &[String] {
        self.errors.get(sub).map_or(&[], Vec::as_slice)
    }

    /// `true` when the row was marked for removal via a truthy `_destroy`.
    #[must_use]
    pub const fn is_destroyed(&self) -> bool {
        self.destroyed
    }

    /// Every error keyed by subfield name (empty key = row-level parse error).
    #[must_use]
    pub const fn all_errors(&self) -> &HashMap<String, Vec<String>> {
        &self.errors
    }
}

// ── NestedChangeset ────────────────────────────────────────────────

/// A parent [`Changeset<P>`] plus its bound child collection.
///
/// Obtain one from [`decode_nested_urlencoded`] or (preferred) the
/// [`NestedChangesetForm`] axum extractor.
#[derive(Debug)]
pub struct NestedChangeset<P, C> {
    /// The parent changeset (values + per-field errors), reusing the existing
    /// [`Changeset`] pipeline.
    pub parent: Changeset<P>,
    /// The submitted child rows in compacted order, retained for re-render.
    rows: Vec<NestedRow>,
    /// `Some(children)` iff the parent is valid **and** every non-destroyed
    /// row both parsed and validated; `None` otherwise.
    valid_children: Option<Vec<C>>,
}

impl<P, C: NestedChild> NestedChangeset<P, C> {
    /// Build a blank, **non-validating** nested changeset for the initial
    /// `new` (create) render, before the user has submitted anything.
    ///
    /// Mirrors [`ChangesetForm::blank`](crate::form::ChangesetForm::blank): it
    /// wraps `parent` in a valid [`Changeset`] (via [`Changeset::new`], which
    /// records **no** errors — it does **not** run [`validator::Validate`])
    /// with **zero** child rows. So `is_valid()` returns `true`,
    /// `errors_for(..)` is empty, `rows()` is empty, and `into_valid()` returns
    /// `Ok((parent, vec![]))` even when a required parent field is still empty.
    ///
    /// Use this for the initial GET render of an **empty** (create) form so the
    /// blank page does not show a premature "field is required" error or
    /// `aria-invalid="true"` before the user has typed. For an **edit** render
    /// that must display existing child rows (with their persisted ids), use
    /// [`seeded`](NestedChangeset::seeded) instead — `blank` produces zero child
    /// rows and cannot pre-fill or preserve existing line items. Use
    /// [`decode_nested_urlencoded`] (or the [`NestedChangesetForm`] extractor)
    /// for the POST decode that validates a real submission and re-renders with
    /// inline errors.
    #[must_use]
    pub fn blank(parent: P) -> Self {
        Self {
            parent: Changeset::new(parent),
            rows: Vec::new(),
            valid_children: Some(Vec::new()),
        }
    }

    /// `true` when the parent is valid, every non-destroyed row has no
    /// errors, and the children all parsed and validated.
    #[must_use]
    pub fn is_valid(&self) -> bool {
        self.parent.is_valid()
            && self.valid_children.is_some()
            && self.rows.iter().all(|r| r.destroyed || r.errors.is_empty())
    }

    /// Consume the changeset, returning `Ok((parent, children))` when valid or
    /// `Err(self)` (with all rows retained for re-render) when not.
    ///
    /// The returned child vector contains only non-destroyed rows, in order.
    ///
    /// # Errors
    ///
    /// Returns `Err(self)` when the parent or any non-destroyed child row has
    /// validation errors, or any child failed to parse.
    #[allow(
        clippy::result_large_err,
        reason = "the Err variant intentionally returns the whole changeset (rows + raw \
                  values) so the handler can re-render the form inline with errors"
    )]
    pub fn into_valid(self) -> Result<(P, Vec<C>), Self> {
        if !self.is_valid() {
            return Err(self);
        }
        let Self {
            parent,
            rows,
            valid_children,
        } = self;
        // `is_valid()` guarantees both arms below take the happy path; the
        // reconstruction branches keep the code panic-free without relying on
        // that invariant.
        match valid_children {
            Some(children) => match parent.into_valid() {
                Ok(p) => Ok((p, children)),
                Err(parent) => Err(Self {
                    parent,
                    rows,
                    valid_children: None,
                }),
            },
            None => Err(Self {
                parent,
                rows,
                valid_children: None,
            }),
        }
    }

    /// Validation messages for `key`, or an empty slice.
    ///
    /// Supports both parent field keys (delegated to
    /// [`Changeset::errors_for`]) and combined child keys of the form
    /// `"{COLLECTION}[{i}].{sub}"` (e.g. `"items[1].quantity"`). A bare
    /// `"{COLLECTION}[{i}]"` returns that row's row-level (parse) errors.
    #[must_use]
    pub fn errors_for(&self, key: &str) -> &[String] {
        if let Some((idx, sub)) = parse_combined_child_key(key, C::COLLECTION) {
            return self.rows.get(idx).map_or(&[], |r| r.errors_for(sub));
        }
        self.parent.errors_for(key)
    }

    /// The submitted child rows in compacted (ascending-index) order.
    #[must_use]
    pub fn rows(&self) -> &[NestedRow] {
        &self.rows
    }

    /// The child collection name, i.e. [`NestedChild::COLLECTION`].
    #[must_use]
    pub const fn collection_name(&self) -> &'static str {
        C::COLLECTION
    }
}

/// Edit-render seeding — pre-populate a non-validating changeset with existing
/// persisted children.
///
/// The extra [`serde::Serialize`] bound lives on this `impl` block alone, so the
/// core [`NestedChild`] trait stays serialize-free; only callers that seed an
/// edit form need their child type to be serializable.
impl<P, C: NestedChild + serde::Serialize> NestedChangeset<P, C> {
    /// Build a **non-validating**, valid nested changeset that pre-renders one
    /// row per existing `child`, for the initial `edit` render of a form that
    /// already has persisted children.
    ///
    /// Where [`blank`](NestedChangeset::blank) produces **zero** child rows (for
    /// the create/new page), `seeded` produces exactly one [`NestedRow`] per
    /// element of `children`, so an edit form can display and preserve existing
    /// line items — including each child's `id` as a hidden input (via
    /// [`RowScope::hidden_input`]) — before the first submit. That hidden `id`
    /// also makes the in-scope `_destroy`-on-existing-children flow usable: the
    /// row round-trips its identity so ticking Remove on a persisted child
    /// submits a real, identifiable row for the handler to delete.
    ///
    /// Each row's raw `values` are produced by serializing the child with
    /// [`serde_html_form::to_string`] (a `Vec` field becomes repeated keys) and
    /// parsing the result back into the
    /// per-subfield map — the **same** string representation
    /// [`decode_nested_urlencoded`] populates from a real submission, so
    /// [`RowScope::value`] pre-fills a seeded row's inputs identically to a
    /// re-rendered submitted row.
    ///
    /// Like `blank`, this does **not** run [`validator::Validate`]: it wraps
    /// `parent` in a valid [`Changeset`] (via [`Changeset::new`]) and keeps
    /// `valid_children = Some(children)`, so `is_valid()` returns `true`,
    /// `errors_for(..)` is empty, every seeded row reports no errors and is not
    /// destroyed, and `into_valid()` returns `Ok((parent, children))`. Use the
    /// POST decode path ([`decode_nested_urlencoded`] / the
    /// [`NestedChangesetForm`] extractor) to validate the actual edit
    /// submission.
    ///
    /// Deeper reconciliation of persisted children — reordering, or deep-diffing
    /// submitted rows against the seeded set to compute per-row inserts /
    /// updates / deletes — is intentionally **out of scope** here (see issue
    /// #1346's out-of-scope list) and remains a follow-up; `seeded` only
    /// pre-renders the existing rows so the no-JS edit + `_destroy` flow works.
    #[must_use]
    pub fn seeded(parent: P, children: Vec<C>) -> Self {
        let rows = children
            .iter()
            .map(|child| {
                let mut values: HashMap<String, Vec<String>> = HashMap::new();
                // Serialize the child to the same `field=value` wire form the
                // decoder reads, then parse it back so `RowScope::value` pre-fills
                // seeded rows identically to a re-rendered submitted row. A
                // serialization failure (never expected for a plain struct) simply
                // yields an empty value map rather than panicking on the request path.
                if let Ok(encoded) = serde_html_form::to_string(child) {
                    for (k, v) in url::form_urlencoded::parse(encoded.as_bytes()) {
                        values
                            .entry(k.into_owned())
                            .or_default()
                            .push(v.into_owned());
                    }
                }
                NestedRow {
                    values,
                    errors: HashMap::new(),
                    destroyed: false,
                }
            })
            .collect();
        Self {
            parent: Changeset::new(parent),
            rows,
            valid_children: Some(children),
        }
    }
}

// ── Decoder ────────────────────────────────────────────────────────

/// Decode URL-encoded `pairs` into a [`NestedChangeset<P, C>`].
///
/// Pairs whose key matches `^{COLLECTION}\[(\d+)\]\[([^\]]+)\]$` are child
/// subfields (captured index + subfield name); everything else is a parent
/// pair. Child pairs are grouped by numeric index into ascending order and
/// **compacted** so non-contiguous indices (gaps from client-side removal)
/// still yield sequential rows preserving submission order. Subfield order
/// within a row is preserved.
///
/// A `_destroy` subfield with a truthy value (`"1"`, `"true"`, `"on"`) marks
/// its row destroyed; destroyed rows are retained (for re-render) but never
/// contribute to `valid_children`.
///
/// Following Rails' `reject_if: :all_blank`, a child row whose every
/// non-`_destroy` subfield value is blank (empty or whitespace-only after
/// trimming) is **ignored**: it is not decoded, not validated, not retained in
/// `rows`, and never counts toward `valid_children` — exactly as if that index
/// had never been submitted. This is what makes the blank template row
/// [`inputs_for`] auto-renders safe with no JavaScript. A row with at least one
/// non-blank non-`_destroy` value is kept and validated as usual, so a
/// partially filled row that omits a required field still surfaces per-field
/// errors.
///
/// Both the parent and each non-destroyed child are decoded through the same
/// blank-optional-dropping path
/// [`ChangesetForm`](crate::form::ChangesetForm) uses, so string→typed
/// coercion (`quantity=5` → `i32`) comes for free. A repeated key fills a
/// `Vec<T>` field. On a single-value field it is an error (issue #3394): for
/// the parent, the decode fails; for a row, the error is on that subfield.
///
/// # Unstorable bytes
///
/// Submitted text values are swept for NUL (`U+0000`) before anything decodes
/// them (issue #2423), and a parent field or child subfield that carried one
/// gets [`NUL_CHARACTER_FIELD_ERROR`](crate::form::NUL_CHARACTER_FIELD_ERROR)
/// alongside whatever the validators said. `_destroy` is excluded from the
/// sweep — cleaning a marker read only for truthiness would change it — and so
/// are the *default* names of the framework's plumbing fields, since this
/// function takes raw pairs and never sees the request extensions that carry
/// their configured names. [`NestedChangesetForm`] additionally exempts those.
///
/// # Errors
///
/// Returns `Err(message)` when the **parent** fails to decode (a malformed,
/// non-blank typed value) — mirroring the hard-400 contract of
/// [`ChangesetForm`](crate::form::ChangesetForm). A **child** row that fails
/// to parse is not a hard error: it is retained with a row-level error and
/// marks the changeset invalid.
pub fn decode_nested_urlencoded<P, C>(
    pairs: &[(String, String)],
) -> Result<NestedChangeset<P, C>, String>
where
    P: serde::de::DeserializeOwned + validator::Validate,
    C: NestedChild,
{
    decode_nested_with_nul_message(pairs, crate::form::NUL_CHARACTER_FIELD_ERROR)
        .map_err(|e| e.to_string())
}

/// Like [`decode_nested_urlencoded`], but the caller sets the message for a NUL
/// byte.
/// The error keeps its status, so the extractor answers 422 for a repeated
/// parent field and 400 for the rest.
fn decode_nested_with_nul_message<P, C>(
    pairs: &[(String, String)],
    nul_message: &str,
) -> Result<NestedChangeset<P, C>, crate::form::FormDecodeError>
where
    P: serde::de::DeserializeOwned + validator::Validate,
    C: NestedChild,
{
    let collection = C::COLLECTION;

    // Split parent pairs from grouped child subfields. `BTreeMap` keeps the
    // rows in ascending index order; enumerating it later compacts gaps.
    let mut parent_pairs: Vec<(String, String)> = Vec::new();
    let mut child_groups: BTreeMap<usize, Vec<(String, String)>> = BTreeMap::new();
    for (key, value) in pairs {
        if let Some((idx, sub)) = parse_child_key(key, collection) {
            child_groups
                .entry(idx)
                .or_default()
                .push((sub.to_string(), value.clone()));
        } else {
            parent_pairs.push((key.clone(), value.clone()));
        }
    }

    // #2423: sweep NUL bytes out of the submitted values before anything
    // decodes them, remembering which names carried one so the byte lands as
    // an ordinary error on the field or subfield that held it. Postgres cannot
    // store `0x00` in a TEXT column, so without this the row parses, validates,
    // and fails only at the database with an unhandled 500. Parent fields and
    // each row's subfields are swept separately because they are keyed
    // separately in the rendered form.
    // `_destroy` is excluded from the sweep, not merely from the reporting.
    // Cleaning it would rewrite the marker itself: `is_truthy` trims only
    // whitespace, so `"1\u{0}"` reads as false today and would read as *true*
    // after stripping — silently destroying a row the author submitted to keep.
    // It is never written to a column, so leaving the byte in it costs nothing.
    let parent_nul_fields: Vec<String> = crate::form::strip_nul_from_pairs(&mut parent_pairs)
        .into_iter()
        // A direct caller of this public function passes the raw pairs, tokens
        // and all, and never sees the request extensions that carry the
        // configurable field names — so exempt the defaults here. The
        // extractor additionally exempts the configured names.
        .filter(|field| !crate::form::is_plumbing_field(field))
        .collect();
    let child_nul_fields: BTreeMap<usize, Vec<String>> = child_groups
        .iter_mut()
        .map(|(idx, subfields)| {
            // Deduplicated for the same reason `strip_nul_from_pairs` is: a
            // subfield may be submitted any number of times, and one message
            // per *pair* would let a crafted body inflate a single row's error
            // list without bound. One message per offending subfield.
            let mut swept: BTreeSet<String> = BTreeSet::new();
            for (sub, value) in subfields.iter_mut() {
                if sub != DESTROY_SUBFIELD && value.as_bytes().contains(&0) {
                    *value = crate::normalize::strip_nul(value);
                    if !swept.contains(sub.as_str()) {
                        swept.insert(sub.clone());
                    }
                }
            }
            (*idx, swept.into_iter().collect::<Vec<String>>())
        })
        .collect();

    // Decode the parent through the shared blank-optional-dropping path.
    let parent_encoded = encode_pairs(&parent_pairs);
    let parent_data: P =
        decode_urlencoded_dropping_blank_optional_fields::<P>(parent_encoded.as_bytes())?;
    let mut parent = parent_data.into_changeset();
    for field in parent_nul_fields {
        parent.add_error(field, nul_message);
    }

    let mut rows: Vec<NestedRow> = Vec::new();
    let mut children: Vec<C> = Vec::new();
    let mut all_children_ok = true;

    for (idx, subfields) in child_groups {
        match decode_child_row::<C>(
            &subfields,
            child_nul_fields.get(&idx).map_or(&[], Vec::as_slice),
            nul_message,
        ) {
            ChildRow::Dropped => {}
            ChildRow::Bound { row, child } => {
                if let Some(child) = child {
                    children.push(child);
                }
                rows.push(row);
            }
            ChildRow::Rejected(row) => {
                all_children_ok = false;
                rows.push(row);
            }
        }
    }

    let valid_children = if parent.is_valid() && all_children_ok {
        Some(children)
    } else {
        None
    };

    Ok(NestedChangeset {
        parent,
        rows,
        valid_children,
    })
}

/// The outcome of decoding one submitted child row.
enum ChildRow<C> {
    /// A blank template row (Rails `reject_if: :all_blank`) — dropped
    /// entirely, exactly as if that index had never been submitted.
    Dropped,
    /// Retained for re-render and contributing `child` to the bound children:
    /// `Some` when the row parsed and validated, `None` when it is marked
    /// destroyed and so has nothing to write. Neither blocks `into_valid`.
    Bound {
        /// The row as re-rendered.
        row: NestedRow,
        /// The bound child, absent for a destroyed row.
        child: Option<C>,
    },
    /// Retained for re-render carrying per-subfield errors; blocks
    /// `into_valid`.
    Rejected(NestedRow),
}

/// Decode one submitted child row from its grouped subfields.
///
/// `nul_fields` names the subfields of this row whose submitted value carried
/// a NUL byte (#2423); the values in `subfields` have already been cleaned, so
/// this function only sets the message for them, from `nul_message`.
fn decode_child_row<C: NestedChild>(
    subfields: &[(String, String)],
    nul_fields: &[String],
    nul_message: &str,
) -> ChildRow<C> {
    let mut values: HashMap<String, Vec<String>> = HashMap::new();
    let mut destroyed = false;
    // Subfields decoded into `C`, excluding the `_destroy` marker (not a
    // field of `C`).
    let mut decode_pairs: Vec<(String, String)> = Vec::new();
    for (sub, val) in subfields {
        values.entry(sub.clone()).or_default().push(val.clone());
        if sub == DESTROY_SUBFIELD {
            if is_truthy(val) {
                destroyed = true;
            }
        } else {
            decode_pairs.push((sub.clone(), val.clone()));
        }
    }

    // Rails `reject_if: :all_blank`: when every non-`_destroy` subfield value is blank —
    // empty or whitespace-only after trimming — drop the row entirely. This is the
    // auto-rendered blank template row `inputs_for` emits for the no-JS "add a child"
    // path, not a real submitted child, so treat it as if the index was never submitted:
    // do not decode, validate, retain, or count it toward the children. A row with at
    // least one non-blank, non-`_destroy` value is kept and validated as usual, so a
    // partially filled row still surfaces its per-field errors. `decode_pairs` already
    // excludes `_destroy`, so an all-blank row that also carries `_destroy` is dropped
    // here too, the same outcome as the destroy path.
    let all_blank = decode_pairs.iter().all(|(_, val)| val.trim().is_empty());

    // A genuinely blank template row drops, destroyed or not — unchanged.
    if all_blank && nul_fields.is_empty() {
        return ChildRow::Dropped;
    }

    // #2423: a destroyed row is never written, so there is nothing to reject
    // there — the cleaned values are retained only so the row re-renders. This
    // has to be decided *before* the NUL rejection below: a row whose only
    // remaining content was an unstorable byte is still a row the author asked
    // to delete, and rejecting it would block `into_valid` and leave them
    // unable to remove it.
    if destroyed {
        return ChildRow::Bound {
            row: NestedRow {
                values,
                errors: HashMap::new(),
                destroyed,
            },
            child: None,
        };
    }

    // #2423: values were cleaned before the blank check, so a subfield whose
    // only content was a NUL now reads as blank. That must not make the row
    // *vanish* — the author did submit something, it just could not be stored
    // — so a row that carried a NUL is reported even when nothing legible is
    // left of it.
    if all_blank {
        let mut errors: HashMap<String, Vec<String>> = HashMap::new();
        for field in nul_fields {
            errors
                .entry(field.clone())
                .or_default()
                .push(nul_message.to_owned());
        }
        return ChildRow::Rejected(NestedRow {
            values,
            errors,
            destroyed,
        });
    }

    let mut errors: HashMap<String, Vec<String>> = HashMap::new();
    let mut child: Option<C> = None;

    let encoded = encode_pairs(&decode_pairs);
    match decode_urlencoded_dropping_blank_optional_fields::<C>(encoded.as_bytes()) {
        Ok(decoded) => match validator::Validate::validate(&decoded) {
            Ok(()) => child = Some(decoded),
            Err(ve) => errors = validation_errors_to_map(&ve),
        },
        Err(e) => {
            // Row parse failure — deserialization failed before validation,
            // as when `sku` is filled but the required numeric `quantity` is
            // malformed or present-but-blank. Key the message under the
            // offending subfield so it surfaces as `items[i].{field}`,
            // rendered by `errors_for("{field}")` next to the offending input
            // rather than only under the row-level "" key.
            //
            // The blank-optional retry inside
            // `decode_urlencoded_dropping_blank_optional_fields` can drop a
            // present-but-blank typed field (`quantity=`) before serde sees it,
            // so the primary error is then a `missing field` report at the row
            // root with an empty path, losing the field name the row helpers
            // need. `recover_child_error_field` recovers it by preferring the
            // primary error's `missing field` message, with a raw non-dropping
            // re-decode only as a last resort. Only if every layer fails does it
            // fall back to the row-level "" key, so the error is never silently
            // dropped.
            let field = recover_child_error_field::<C>(&e, &decode_pairs);
            errors.entry(field).or_default().push(e.to_string());
        }
    }

    // #2423: a NUL byte in this row's text is a rejection in its own right,
    // recorded alongside whatever the validators said.
    for field in nul_fields {
        errors
            .entry(field.clone())
            .or_default()
            .push(nul_message.to_owned());
        child = None;
    }

    let row = NestedRow {
        values,
        errors,
        destroyed,
    };
    match child {
        Some(child) => ChildRow::Bound {
            row,
            child: Some(child),
        },
        None => ChildRow::Rejected(row),
    }
}

/// Parse `key` as a child subfield reference `COLLECTION[<idx>][<sub>]`,
/// returning `(idx, sub)`. Hand-parses the bracket pattern (no `regex`
/// dependency), matching `^{COLLECTION}\[(\d+)\]\[([^\]]+)\]$` with
/// `COLLECTION` treated literally.
fn parse_child_key<'a>(key: &'a str, collection: &str) -> Option<(usize, &'a str)> {
    let rest = key.strip_prefix(collection)?;
    let rest = rest.strip_prefix('[')?;
    let close = rest.find(']')?;
    let (idx_str, after) = rest.split_at(close);
    let idx: usize = idx_str.parse().ok()?;
    // `after` begins with the `]` that `close` pointed at.
    let after = after.strip_prefix(']')?;
    let after = after.strip_prefix('[')?;
    let close2 = after.find(']')?;
    let (sub, tail) = after.split_at(close2);
    // The subfield must be the final segment: exactly a trailing `]`.
    if tail != "]" || sub.is_empty() {
        return None;
    }
    Some((idx, sub))
}

/// Parse a combined error key `COLLECTION[<idx>]` optionally followed by
/// `.<sub>`, returning `(idx, sub)` where `sub` is `""` for the bare form.
/// Returns `None` when the key is not a child key (so it falls through to the
/// parent).
fn parse_combined_child_key<'a>(key: &'a str, collection: &str) -> Option<(usize, &'a str)> {
    let rest = key.strip_prefix(collection)?;
    let rest = rest.strip_prefix('[')?;
    let close = rest.find(']')?;
    let (idx_str, after) = rest.split_at(close);
    let idx: usize = idx_str.parse().ok()?;
    let after = after.strip_prefix(']')?;
    if after.is_empty() {
        return Some((idx, ""));
    }
    let sub = after.strip_prefix('.')?;
    if sub.is_empty() {
        return None;
    }
    Some((idx, sub))
}

/// Re-encode `pairs` as an `application/x-www-form-urlencoded` string so the
/// shared form decode path can re-parse them.
fn encode_pairs(pairs: &[(String, String)]) -> String {
    url::form_urlencoded::Serializer::new(String::new())
        .extend_pairs(pairs.iter().map(|(k, v)| (k.as_str(), v.as_str())))
        .finish()
}

/// Last `Map`/`Enum` key in a `serde_path_to_error` path, if any is non-empty.
///
/// This is the subfield the decode failure is attributed to (e.g. `quantity`
/// for `items[i][quantity]`). `Seq`/`Unknown` segments carry no field name.
fn last_path_field(path: &serde_path_to_error::Path) -> Option<String> {
    path.iter()
        .filter_map(|seg| match seg {
            serde_path_to_error::Segment::Map { key }
            | serde_path_to_error::Segment::Enum { variant: key } => Some(key.clone()),
            serde_path_to_error::Segment::Seq { .. } | serde_path_to_error::Segment::Unknown => {
                None
            }
        })
        .next_back()
        .filter(|f| !f.is_empty())
}

/// Extract the field name from serde's stable "missing field" message — the
/// backtick-quoted identifier in [`serde::de::Error::missing_field`]'s
/// `Display` format — if present.
fn missing_field_name(msg: &str) -> Option<String> {
    let after = msg.split_once("missing field `")?.1;
    let name = after.split_once('`')?.0;
    (!name.is_empty()).then(|| name.to_owned())
}

/// Recover the offending subfield name for a child-row parse failure so the
/// error can be keyed to `items[i].{field}` (rendered next to the input) rather
/// than only under the row-level "" key.
///
/// Layered because the blank-optional retry inside
/// [`decode_urlencoded_dropping_blank_optional_fields`] can DROP a
/// present-but-blank typed field (`quantity=`) before serde ever sees it, so
/// the primary decode reports a root-level missing-field error for `quantity`
/// with an empty path — losing the field name the row helpers need:
///
/// 1. The primary decode's `serde_path_to_error` path (last `Map`/`Enum` key).
///    For a malformed non-blank value (`quantity=abc`) this already yields the
///    field, since that pair is never dropped.
/// 2. If empty, the backtick-quoted identifier parsed from the PRIMARY error's
///    missing-field message. The blank-dropping decode stops on the first typed
///    field it can't satisfy, so this names the truly-required field even when
///    an earlier OPTIONAL blank precedes it — e.g. a child with an optional
///    `weight` before a required `quantity`, both submitted blank, reports the
///    required `quantity` as missing, not `weight`. It also covers the
///    present-but-blank required field (dropped → missing) and the field truly
///    never submitted. This is preferred over the raw re-decode below precisely
///    so the error lands on the required field, not a harmless optional blank a
///    non-dropping pass would trip on first.
/// 3. Only if BOTH are empty (a rare root-level error carrying neither a path
///    nor a missing-field message), a raw re-decode over the ORIGINAL row pairs
///    with blanks RETAINED (no dropping), mirroring the shared helper's
///    deserializer minus the drop loop, and its last `Map`/`Enum` key.
/// 4. Otherwise `""` (row-level key) so the error is never silently dropped.
///
/// This runs ONLY on the already-failed path to LOCATE the field; it does not
/// affect the success path. Legitimately-blank optional fields still decode to
/// `None` via the primary blank-dropping decode, which succeeds for them and
/// never reaches here.
fn recover_child_error_field<C: serde::de::DeserializeOwned>(
    primary: &crate::form::FormDecodeError,
    decode_pairs: &[(String, String)],
) -> String {
    // 0. A repeated single-value subfield (issue #3394) names itself.
    let Some(primary) = primary.invalid_error() else {
        return primary.field().unwrap_or_default().to_owned();
    };

    // 1. Primary decode path (present-but-malformed value at a real path).
    if let Some(field) = last_path_field(primary.path()) {
        return field;
    }

    // 2. The `missing field \`X\`` identifier from the PRIMARY error — names
    //    the required field the blank-dropping pass actually stopped on.
    if let Some(field) = missing_field_name(&primary.inner().to_string()) {
        return field;
    }

    // 3. Fallback: raw (non-dropping) re-decode over the original row pairs,
    //    for the rare root-level error with neither a path nor a missing-field
    //    message.
    let encoded = encode_pairs(decode_pairs);
    let deserializer = serde_html_form::Deserializer::from_bytes(encoded.as_bytes());
    if let Err(raw_err) = serde_path_to_error::deserialize::<_, C>(deserializer)
        && let Some(field) = last_path_field(raw_err.path())
    {
        return field;
    }

    // 4. Row-level key.
    String::new()
}

/// Whether a `_destroy` marker value counts as "destroy this row".
/// The subfield name that marks a submitted child row for destruction.
///
/// Not a column: its value is only ever read for truthiness, so it is left out
/// of the #2423 NUL sweep entirely (see `decode_nested_urlencoded`).
const DESTROY_SUBFIELD: &str = "_destroy";

fn is_truthy(value: &str) -> bool {
    let trimmed = value.trim();
    trimmed == "1" || trimmed.eq_ignore_ascii_case("true") || trimmed.eq_ignore_ascii_case("on")
}

// ── NestedChangesetForm extractor ──────────────────────────────────

/// Axum extractor that decodes a nested (`has_many`) form body, validates the
/// parent and every non-destroyed child row, and captures the CSRF and
/// submit-token context for re-rendering.
///
/// Mirrors [`ChangesetForm`](crate::form::ChangesetForm): errors live in the
/// [`NestedChangeset`] rather than rejecting with 422; the handler decides how
/// to respond. Only `application/x-www-form-urlencoded` bodies are accepted
/// (multipart is a follow-up).
pub struct NestedChangesetForm<P, C> {
    /// The validated (or invalid) nested changeset.
    pub changeset: NestedChangeset<P, C>,
    csrf_token: Option<String>,
    csrf_field: String,
    submit_token: Option<String>,
    submit_field: String,
}

impl<P, C: NestedChild> NestedChangesetForm<P, C> {
    /// Build a blank nested-form context for the initial `new` (create) GET
    /// render, before any submission.
    ///
    /// Mirrors [`ChangesetForm::blank`](crate::form::ChangesetForm::blank): it
    /// wraps `parent` in a **non-validating** [`NestedChangeset::blank`] (no
    /// child rows, no errors) so the initial page renders clean — no premature
    /// "field is required" message or `aria-invalid="true"` before the user has
    /// typed. For an **edit** render that must show existing children, use
    /// [`seeded`](Self::seeded) instead (`blank` renders zero child rows).
    /// Contrast the POST path (the [`NestedChangesetForm`] extractor /
    /// [`decode_nested_urlencoded`]), which validates the submission and
    /// re-renders inline errors.
    ///
    /// `csrf_token` is the token from a `CsrfToken` extractor, or `None` when
    /// CSRF middleware is not active. The CSRF and submit-token field names
    /// default to `_csrf` / `_submit_token` (exactly what the extractor falls
    /// back to when the corresponding config extensions are absent); when the
    /// app customizes `security.csrf.form_field`, set it with
    /// [`with_csrf_field`](Self::with_csrf_field) so
    /// [`form_tag`](Self::form_tag) emits the right hidden field name.
    ///
    /// The submit token starts `None`, so a bare `blank(..).form_tag(..)` emits
    /// **no** submit-token hidden input and the first submission is not protected
    /// against double-submit ([`SubmitTokenLayer`](crate::security::SubmitTokenLayer)
    /// passes tokenless mutating requests through). Supply the minted token on the
    /// initial GET with [`with_submit_token`](Self::with_submit_token) (and
    /// [`with_submit_field`](Self::with_submit_field) if the field name is
    /// customized) so the **first** submit carries a token too:
    ///
    /// ```rust,ignore
    /// #[get("/orders/new")]
    /// async fn new_order(csrf: CsrfToken, submit: SubmitToken) -> Markup {
    ///     let form = NestedChangesetForm::<NewOrder, NewLineItem>::blank(
    ///         NewOrder::default(),
    ///         Some(csrf.token().to_owned()),
    ///     )
    ///     .with_submit_token(Some(submit.token().to_owned()));
    ///     form.form_tag("/orders", "post", /* … */)
    /// }
    /// ```
    #[must_use]
    pub fn blank(parent: P, csrf_token: Option<String>) -> Self {
        Self {
            changeset: NestedChangeset::blank(parent),
            csrf_token,
            csrf_field: "_csrf".to_owned(),
            submit_token: None,
            submit_field: "_submit_token".to_owned(),
        }
    }

    /// Wrap a pre-built [`NestedChangeset`] (which may already carry validation
    /// errors) in a form for rendering, with no CSRF/submit token.
    ///
    /// Mirrors [`ChangesetForm::from_changeset`](crate::form::ChangesetForm::from_changeset):
    /// useful in tests and cases where a `NestedChangeset` was produced
    /// externally (e.g. via [`decode_nested_urlencoded`]) before constructing a
    /// form for re-render. The CSRF/submit-token field names default to
    /// `_csrf` / `_submit_token`; add a token with
    /// [`with_csrf_field`](Self::with_csrf_field) as needed.
    #[must_use]
    pub fn from_changeset(changeset: NestedChangeset<P, C>) -> Self {
        Self {
            changeset,
            csrf_token: None,
            csrf_field: "_csrf".to_owned(),
            submit_token: None,
            submit_field: "_submit_token".to_owned(),
        }
    }

    /// Override the CSRF form-field name used by [`form_tag`](Self::form_tag).
    ///
    /// Mirrors
    /// [`ChangesetForm::with_csrf_field`](crate::form::ChangesetForm::with_csrf_field):
    /// call this on a [`blank`](Self::blank) GET-handler form when
    /// `security.csrf.form_field` is customized (e.g. `"authenticity_token"`).
    /// The extractor captures the configured name automatically on the POST
    /// path.
    #[must_use]
    pub fn with_csrf_field(mut self, field: impl Into<String>) -> Self {
        self.csrf_field = field.into();
        self
    }

    /// Supply the one-time submit token to a [`blank`](Self::blank) (or
    /// [`from_changeset`](Self::from_changeset)) GET-handler form so
    /// [`form_tag`](Self::form_tag) emits the hidden submit-token input on the
    /// **initial** render — protecting the very first submission against
    /// double-submit, not just later 422 re-renders.
    ///
    /// [`blank`](Self::blank) leaves this `None` (the initial page renders no
    /// submit-token field otherwise), and [`SubmitTokenLayer`](crate::security::SubmitTokenLayer)
    /// passes tokenless mutating requests through unchanged — so without calling
    /// this the first create-form submit is unprotected. Source the token from a
    /// [`SubmitToken`](crate::security::SubmitToken) extractor on the GET handler.
    /// The extractor captures it automatically on the POST re-render path.
    ///
    /// When the app customizes `security.submit_token.field_name`, pair this with
    /// [`with_submit_field`](Self::with_submit_field) so the hidden input carries
    /// the right name.
    #[must_use]
    pub fn with_submit_token(mut self, token: Option<String>) -> Self {
        self.submit_token = token;
        self
    }

    /// Override the submit-token form-field name used by
    /// [`form_tag`](Self::form_tag).
    ///
    /// Mirrors [`with_csrf_field`](Self::with_csrf_field): call this on a
    /// [`blank`](Self::blank) GET-handler form when
    /// `security.submit_token.field_name` is customized (the default is
    /// `_submit_token`). The extractor captures the configured name automatically
    /// on the POST path.
    #[must_use]
    pub fn with_submit_field(mut self, field: impl Into<String>) -> Self {
        self.submit_field = field.into();
        self
    }

    /// The CSRF token captured from the request, if the CSRF middleware is active.
    #[must_use]
    pub fn csrf_token(&self) -> Option<&str> {
        self.csrf_token.as_deref()
    }

    /// The CSRF form-field name (honours `security.csrf.form_field`).
    #[must_use]
    pub fn csrf_field(&self) -> &str {
        &self.csrf_field
    }

    /// The one-time submit token captured from the request, if the
    /// submit-token middleware is active.
    #[must_use]
    pub fn submit_token(&self) -> Option<&str> {
        self.submit_token.as_deref()
    }

    /// The submit-token form-field name (honours
    /// `security.submit_token.field_name`).
    #[must_use]
    pub fn submit_field(&self) -> &str {
        &self.submit_field
    }

    /// Consume and return only the inner [`NestedChangeset`].
    pub fn into_changeset(self) -> NestedChangeset<P, C> {
        self.changeset
    }

    /// Return `Ok((parent, children))` when valid, `Err(self)` when not.
    ///
    /// The `Err` branch retains the CSRF/submit context so the handler can
    /// immediately re-render the form with inline errors.
    ///
    /// # Errors
    ///
    /// Returns `Err(self)` when the inner changeset has validation errors.
    #[allow(
        clippy::result_large_err,
        reason = "the Err variant intentionally returns the whole form (changeset + CSRF/submit \
                  context) so the handler can re-render inline with errors"
    )]
    pub fn into_valid(self) -> Result<(P, Vec<C>), Self> {
        let Self {
            changeset,
            csrf_token,
            csrf_field,
            submit_token,
            submit_field,
        } = self;
        match changeset.into_valid() {
            Ok(pair) => Ok(pair),
            Err(changeset) => Err(Self {
                changeset,
                csrf_token,
                csrf_field,
                submit_token,
                submit_field,
            }),
        }
    }
}

/// Edit-render seeding for the form context — mirrors
/// [`NestedChangeset::seeded`], carrying the extra [`serde::Serialize`] bound on
/// this `impl` block alone.
impl<P, C: NestedChild + serde::Serialize> NestedChangesetForm<P, C> {
    /// Build a nested-form context for the initial `edit` GET render,
    /// pre-populated with the existing persisted `children`.
    ///
    /// Mirrors [`blank`](Self::blank)'s CSRF handling (the CSRF/submit-token
    /// field names default to `_csrf` / `_submit_token`, and the submit token
    /// starts `None`), but wraps [`NestedChangeset::seeded`] instead of
    /// [`NestedChangeset::blank`]: the changeset pre-renders one row per existing
    /// child so the edit page shows and preserves current line items — with their
    /// `id`s carried as hidden inputs (via [`RowScope::hidden_input`]) — and the
    /// no-JS `_destroy` removal of an existing child works before the first
    /// submit.
    ///
    /// The same builder methods used with [`blank`](Self::blank) apply here:
    /// [`with_csrf_field`](Self::with_csrf_field) for a customized
    /// `security.csrf.form_field`, and [`with_submit_token`](Self::with_submit_token)
    /// / [`with_submit_field`](Self::with_submit_field) to emit the one-time
    /// submit-token hidden input on the initial edit render. `csrf_token` is the
    /// token from a `CsrfToken` extractor, or `None` when CSRF middleware is not
    /// active.
    #[must_use]
    pub fn seeded(parent: P, children: Vec<C>, csrf_token: Option<String>) -> Self {
        Self {
            changeset: NestedChangeset::seeded(parent, children),
            csrf_token,
            csrf_field: "_csrf".to_owned(),
            submit_token: None,
            submit_field: "_submit_token".to_owned(),
        }
    }
}

/// Maud rendering — emit the `<form>` open tag with the **captured** CSRF (and
/// submit-token) hidden fields injected.
#[cfg(feature = "maud")]
impl<P, C: NestedChild> NestedChangesetForm<P, C> {
    /// Render a `<form>` element wrapping `content`, injecting the CSRF hidden
    /// input under the **captured** field name (honouring
    /// `security.csrf.form_field`) and — when present — the one-time
    /// submit-token hidden input under its captured field name.
    ///
    /// Mirrors [`ChangesetForm::form_tag`](crate::form::ChangesetForm::form_tag),
    /// including the `PUT`/`PATCH`/`DELETE` → hidden `_method` override. **Prefer
    /// this over the standalone [`crate::form::form_tag`]** for a nested-form
    /// re-render: the standalone helper hardcodes the default `_csrf` field name
    /// and would emit the wrong hidden field for an app that customized
    /// `security.csrf.form_field`, so the next submit's CSRF check would reject
    /// the form. This method uses the field name the extractor captured (or the
    /// one set via [`with_csrf_field`](Self::with_csrf_field) on a
    /// [`blank`](Self::blank) form), keeping CSRF parity across the re-render.
    ///
    /// The submit-token hidden input is emitted only when a submit token is
    /// present. The POST re-render path captures it automatically; on the initial
    /// GET render from [`blank`](Self::blank), supply it with
    /// [`with_submit_token`](Self::with_submit_token) so the **first** submit is
    /// protected against double-submit too — otherwise a bare
    /// `blank(..).form_tag(..)` create form carries no submit token and its first
    /// submission passes through [`SubmitTokenLayer`](crate::security::SubmitTokenLayer)
    /// unprotected.
    #[must_use]
    #[allow(clippy::needless_pass_by_value)]
    pub fn form_tag(&self, action: &str, method: &str, content: maud::Markup) -> maud::Markup {
        crate::form::form_tag_inner(
            action,
            method,
            &self.csrf_field,
            self.csrf_token.as_deref(),
            None,
            maud::html! {
                @if let Some(token) = self.submit_token.as_deref() {
                    input type="hidden" name=(self.submit_field) value=(token);
                }
                (content)
            },
        )
    }
}

/// Dereferences to [`NestedChangeset<P, C>`] so all changeset methods are
/// available directly on the form (`form.is_valid()`, `form.errors_for(…)`,
/// `form.rows()`, …).
impl<P, C> std::ops::Deref for NestedChangesetForm<P, C> {
    type Target = NestedChangeset<P, C>;
    fn deref(&self) -> &Self::Target {
        &self.changeset
    }
}

impl<S, P, C> FromRequest<S> for NestedChangesetForm<P, C>
where
    S: Send + Sync,
    P: serde::de::DeserializeOwned + validator::Validate + Send,
    C: NestedChild,
{
    type Rejection = axum::response::Response;

    async fn from_request(req: Request, state: &S) -> Result<Self, Self::Rejection> {
        // Capture CSRF + submit-token context from request extensions exactly
        // as `ChangesetForm` does, before the body is consumed.
        let csrf_token = req
            .extensions()
            .get::<crate::security::CsrfToken>()
            .map(|t| t.token().to_string());
        let csrf_field = req
            .extensions()
            .get::<crate::security::csrf::CsrfFormField>()
            .map_or_else(|| "_csrf".to_owned(), |f| f.0.clone());
        let submit_token = req
            .extensions()
            .get::<crate::security::SubmitToken>()
            .map(|t| t.token().to_string());
        let submit_field = req
            .extensions()
            .get::<crate::security::SubmitFormField>()
            .map_or_else(|| "_submit_token".to_owned(), |f| f.0.clone());

        // Same content-type gate axum's own form extractors apply. Multipart
        // is out of scope for now (follow-up).
        let (req, nul_message) = crate::form::nul_field_message(req, state).await;
        let content_type = req
            .headers()
            .get(http::header::CONTENT_TYPE)
            .and_then(|v| v.to_str().ok())
            .unwrap_or_default()
            .to_string();
        if !crate::media_type::is_media_type(&content_type, "application/x-www-form-urlencoded") {
            return Err((
                axum::http::StatusCode::UNSUPPORTED_MEDIA_TYPE,
                "Nested form requests must have `Content-Type: application/x-www-form-urlencoded`",
            )
                .into_response());
        }

        // Buffer through axum's `Bytes` extractor so `DefaultBodyLimit` is
        // enforced (a bare `to_bytes(.., usize::MAX)` would defeat it).
        let (parts, body) = req.into_parts();
        let bytes_req = Request::from_parts(parts, body);
        let bytes = axum::body::Bytes::from_request(bytes_req, state)
            .await
            .map_err(IntoResponse::into_response)?;

        let mut pairs: Vec<(String, String)> = url::form_urlencoded::parse(&bytes)
            .map(|(k, v)| (k.into_owned(), v.into_owned()))
            .collect();

        // #2423: the CSRF token, the submit token and the method override are
        // transport plumbing, not form fields — no template renders them, so an
        // error keyed under one would make the form permanently invalid with
        // nothing on screen to explain why. Clean them here so
        // `decode_nested_urlencoded`'s sweep, which knows nothing about the two
        // configurable names, never sees a NUL in one. Each is still rejected on
        // its own terms when malformed.
        for (key, value) in &mut pairs {
            if *key == csrf_field || *key == submit_field || crate::form::is_plumbing_field(key) {
                *value = crate::normalize::strip_nul(value);
            }
        }

        let changeset = decode_nested_with_nul_message::<P, C>(&pairs, &nul_message)
            .map_err(|e| (e.status(), e.to_string()).into_response())?;

        Ok(Self {
            changeset,
            csrf_token,
            csrf_field,
            submit_token,
            submit_field,
        })
    }
}

// ── Maud view helpers ──────────────────────────────────────────────

/// A single row's rendering scope inside [`inputs_for`].
///
/// Each scope binds the child collection name, the row's 0-based `index`, and
/// (for existing/submitted rows) the underlying [`NestedRow`] so its raw values
/// pre-fill inputs and its per-subfield errors render inline on re-render after
/// a failed submission. A blank template row carries `row: None` — its inputs
/// render empty with no error blocks.
///
/// The row-scoped input builders mirror the standalone field helpers in
/// [`crate::form`] (`text_input`, `number_input`, …) but emit **nested** input
/// names (`items[{index}][{sub}]`) and per-row-unique element ids
/// (`items-{index}-{sub}`) so ids and `aria-describedby` links stay unique
/// across repeated rows.
#[cfg(feature = "maud")]
pub struct RowScope<'a> {
    collection: &'a str,
    index: usize,
    row: Option<&'a NestedRow>,
}

#[cfg(feature = "maud")]
impl RowScope<'_> {
    /// This row's 0-based position in the collection.
    #[must_use]
    pub const fn index(&self) -> usize {
        self.index
    }

    /// The nested input `name` for subfield `sub`, i.e.
    /// `"{collection}[{index}][{sub}]"`.
    #[must_use]
    pub fn field_name(&self, sub: &str) -> String {
        format!("{}[{}][{}]", self.collection, self.index, sub)
    }

    /// The raw submitted value for subfield `sub`, or `None` for a blank row.
    #[must_use]
    pub fn value(&self, sub: &str) -> Option<&str> {
        self.row.and_then(|r| r.value(sub))
    }

    /// Every raw submitted value for subfield `sub`, or an empty slice (always
    /// empty for a blank row). See [`NestedRow::values`].
    #[must_use]
    pub fn values(&self, sub: &str) -> &[String] {
        self.row.map_or(&[], |r| r.values(sub))
    }

    /// Validation messages for subfield `sub`, or an empty slice (always empty
    /// for a blank row).
    #[must_use]
    pub fn errors_for(&self, sub: &str) -> &[String] {
        self.row.map_or(&[], |r| r.errors_for(sub))
    }

    /// `true` when this (existing) row carried a truthy `_destroy` marker.
    #[must_use]
    pub fn is_destroyed(&self) -> bool {
        self.row.is_some_and(NestedRow::is_destroyed)
    }

    /// Per-row-unique element id base for subfield `sub`
    /// (`"{collection}-{index}-{sub}"`), used for `id` / `aria-describedby`
    /// linkage so repeated rows never collide.
    fn element_id(&self, sub: &str) -> String {
        format!("{}-{}-{}", self.collection, self.index, sub)
    }

    /// Render a labeled row-scoped `<input type="text">` for subfield `sub`.
    ///
    /// Mirrors [`crate::form::text_input`]: `autumn-field` wrapper, per-row
    /// pre-fill, `aria-invalid` / `aria-describedby`, and a `role="alert"`
    /// error block — but with the nested `name` and a per-row-unique `id`.
    #[must_use]
    pub fn text_input(&self, sub: &str, label: &str) -> maud::Markup {
        self.text_input_with(sub, label, &FieldOptions::new())
    }

    /// Like [`RowScope::text_input`] but adds `required` + `aria-required="true"`
    /// — **only for real/submitted rows that are not marked for destruction**
    /// (`self.row.is_some() && !self.is_destroyed()`).
    ///
    /// A blank template row (`row: None`, the one [`inputs_for`] auto-appends
    /// for the no-JS "add a child" path) deliberately renders the *same* input
    /// **without** the client-side `required`/`aria-required` attributes so it
    /// stays leaveable-empty. Otherwise the browser's native constraint
    /// validation would block form submit on the empty trailing template row
    /// *before* the server's all-blank rejection can run — a user who filled one
    /// child row could not submit while a blank row sat beneath it. A submitted
    /// row the user ticked `_destroy` on is skipped for the same reason: the
    /// decoder drops destroyed rows before validation (and from `into_valid()`),
    /// so re-emitting client-side `required` on an empty destroyed field would
    /// let the browser block the next submit before the server can honor the
    /// removal. Required-ness is still enforced server-side for any row the user
    /// actually engages: a partially-filled, non-destroyed row is retained as a
    /// `Some` row on re-render and re-acquires `required`, and the decoder's
    /// all-blank rejection drops the untouched template row. This composes with
    /// that all-blank rejection so
    /// neither the client nor the server treats the template row as a real child.
    #[must_use]
    pub fn required_text_input(&self, sub: &str, label: &str) -> maud::Markup {
        self.text_input_with(sub, label, &FieldOptions::new().required())
    }

    /// [`RowScope::text_input`] with a hint and typed attributes. See
    /// [`FieldOptions`]. A required option follows the template-row rule of
    /// [`RowScope::required_text_input`].
    #[must_use]
    pub fn text_input_with(
        &self,
        sub: &str,
        label: &str,
        options: &FieldOptions<'_>,
    ) -> maud::Markup {
        self.row_field(FieldKind::Text, sub, label, options)
    }

    /// Render a labeled row-scoped `<input type="number">` for subfield `sub`.
    ///
    /// Mirrors [`crate::form::number_input`] (leaving the browser-default
    /// `step`), with the nested `name` and a per-row-unique `id`.
    #[must_use]
    pub fn number_input(&self, sub: &str, label: &str) -> maud::Markup {
        self.number_input_with(sub, label, &FieldOptions::new())
    }

    /// [`RowScope::number_input`] for a required subfield. See
    /// [`RowScope::required_text_input`] for the template-row rule.
    #[must_use]
    pub fn required_number_input(&self, sub: &str, label: &str) -> maud::Markup {
        self.number_input_with(sub, label, &FieldOptions::new().required())
    }

    /// [`RowScope::number_input`] with a hint and typed attributes. See
    /// [`FieldOptions`].
    #[must_use]
    pub fn number_input_with(
        &self,
        sub: &str,
        label: &str,
        options: &FieldOptions<'_>,
    ) -> maud::Markup {
        self.row_field(FieldKind::Number, sub, label, options)
    }

    /// Render a labeled row-scoped `<textarea>` for subfield `sub`.
    ///
    /// Mirrors [`crate::form::textarea_input`]: the value is emitted as the
    /// element body, with the nested `name` and a per-row-unique `id`.
    #[must_use]
    pub fn textarea_input(&self, sub: &str, label: &str) -> maud::Markup {
        self.textarea_input_with(sub, label, &FieldOptions::new())
    }

    /// [`RowScope::textarea_input`] for a required subfield. See
    /// [`RowScope::required_text_input`] for the template-row rule.
    #[must_use]
    pub fn required_textarea_input(&self, sub: &str, label: &str) -> maud::Markup {
        self.textarea_input_with(sub, label, &FieldOptions::new().required())
    }

    /// [`RowScope::textarea_input`] with a hint and typed attributes. See
    /// [`FieldOptions`].
    #[must_use]
    pub fn textarea_input_with(
        &self,
        sub: &str,
        label: &str,
        options: &FieldOptions<'_>,
    ) -> maud::Markup {
        self.row_field(FieldKind::Textarea, sub, label, options)
    }

    /// Shared body of the row-scoped field helpers.
    fn row_field(
        &self,
        kind: FieldKind,
        sub: &str,
        label: &str,
        options: &FieldOptions<'_>,
    ) -> maud::Markup {
        // Emit the client-side `required`/`aria-required` constraint only for a
        // real/submitted row that is *not* marked for destruction. A blank
        // template row (`row: None`) must stay leaveable-empty so the browser
        // does not block submit on the trailing auto-appended blank row before
        // the server's all-blank rejection runs; server-side validation still
        // enforces required-ness for any row the user actually fills (it is
        // retained as a `Some` row on re-render). A submitted row the user
        // ticked `_destroy` on is likewise skipped: the decoder drops destroyed
        // rows before validation, so re-emitting client-side `required` on an
        // empty destroyed field would let the browser's constraint validation
        // block the next submit before the server can honor `_destroy`.
        let unmasked = self.row.is_some() && !self.is_destroyed();
        let masked;
        let options = if options.is_required() && !unmasked {
            masked = options.clone().optional();
            &masked
        } else {
            options
        };
        let name = self.field_name(sub);
        let id = self.element_id(sub);
        let spec = FieldSpec {
            name: Some(&name),
            value: Some(self.value(sub).unwrap_or_default()),
            ..FieldSpec::new(kind, &id, label)
        };
        render_field(&spec, self.errors_for(sub), options)
    }

    /// Render a row-scoped `<input type="hidden">` for subfield `sub`.
    ///
    /// Use this to carry an existing child's primary key (e.g. `id`) on an edit
    /// form so the decoder can match the submitted row back to a persisted record.
    #[must_use]
    pub fn hidden_input(&self, sub: &str, value: &str) -> maud::Markup {
        let name = self.field_name(sub);
        maud::html! {
            input type="hidden" name=(name) value=(value);
        }
    }

    /// Render the durable no-JS removal control: a `_destroy` checkbox whose
    /// checked state is preserved on re-render (`checked` iff
    /// [`RowScope::is_destroyed`]).
    ///
    /// The decoder honours a truthy `_destroy` marker
    /// ([`decode_nested_urlencoded`]), so ticking this box and submitting the
    /// surrounding form removes the row with no JavaScript. htmx/JS row removal
    /// (swapping the `.nested-fields__row` node's `outerHTML`) is an optional
    /// progressive enhancement layered on top; this checkbox is the required
    /// mechanism.
    #[must_use]
    pub fn destroy_checkbox(&self, label: &str) -> maud::Markup {
        let checked = self.is_destroyed();
        let name = self.field_name("_destroy");
        let id = self.element_id("_destroy");
        maud::html! {
            div class="autumn-field autumn-field--destroy" {
                input
                    type="checkbox"
                    id=(id)
                    name=(name)
                    value="1"
                    checked[checked]
                    class="autumn-field__checkbox";
                label for=(id) class="autumn-field__label" { (label) }
            }
        }
    }
}

/// Options for [`inputs_for`].
#[cfg(feature = "maud")]
pub struct InputsForOptions {
    /// Number of extra blank rows to pre-render after the existing rows. The
    /// no-JS fallback lets users fill and submit these without any JavaScript.
    /// Defaults to `1`; [`inputs_for`] always emits **at least one** blank
    /// template row even when this is `0`.
    pub blank_rows: usize,
    /// Optional htmx URL for the server "Add row" fragment endpoint (see
    /// [`nested_row_fragment`]). When `None`, no Add button is rendered and the
    /// no-JS path still works via the pre-rendered blank rows.
    pub add_row_url: Option<String>,
    /// Container element id. Defaults to `"{collection}-rows"`.
    ///
    /// This id is load-bearing when [`add_row_url`](Self::add_row_url) is set:
    /// the Add-row button's `hx-target` and its `hx-vals` index scan both select
    /// `#{container_id}`. HTML ids must be unique in a document, so **when two or
    /// more nested forms for the same child collection appear on one page, each
    /// MUST pass a distinct `container_id`.** The `{collection}-rows` default is
    /// correct for a single such form per page; leaving two same-collection forms
    /// on the default id produces duplicate ids (invalid HTML) and makes each
    /// Add-row button resolve against — and append rows / compute indices from —
    /// whichever container the shared id happens to match first, i.e. the wrong
    /// form. Distinct ids are the only requirement; any stable, unique string
    /// (e.g. `"shipping-items-rows"` vs `"billing-items-rows"`) works.
    pub container_id: Option<String>,
}

#[cfg(feature = "maud")]
impl Default for InputsForOptions {
    fn default() -> Self {
        Self {
            blank_rows: 1,
            add_row_url: None,
            container_id: None,
        }
    }
}

/// Render the repeating child field-group block for a nested (`has_many`) form.
///
/// Wraps the rows in `<div id="{container_id}" class="nested-fields">`. For each
/// existing/submitted row (from [`NestedChangeset::rows`], in order — **including**
/// rows re-submitted after a validation failure) it invokes `render_row` with a
/// [`RowScope`] carrying that row, so values and per-field errors pre-fill on
/// re-render. It then appends [`InputsForOptions::blank_rows`] blank rows (always
/// at least one) whose scopes carry `row: None`. Every row is wrapped in
/// `<div class="nested-fields__row" data-index="{i}">` so htmx/JS removal can
/// target the node's `outerHTML`.
///
/// The appended blank template row makes adding a child work with **no
/// JavaScript**, and it is safe even though the browser submits its empty
/// inputs: [`decode_nested_urlencoded`] applies Rails-style
/// `reject_if: :all_blank`, so a child row whose every non-`_destroy` subfield
/// is blank is ignored rather than decoded as a phantom child. An untouched
/// blank row therefore never blocks submission or persists an empty child.
///
/// So the no-JS path stays submittable, the appended blank template row's inputs
/// omit the client-side `required`/`aria-required` constraint by design (see
/// [`RowScope::required_text_input`]): a required-variant input renders empty and
/// *leaveable* on a `row: None` template row, so the browser's native validation
/// does not block submitting a form that still carries a trailing blank row.
/// This composes with the decoder's all-blank rejection — the untouched template
/// row is dropped server-side — while server-side validation still enforces
/// required-ness for any row the user actually fills.
///
/// When [`InputsForOptions::add_row_url`] is `Some`, an "Add row"
/// `<button type="button">` is emitted with `hx-get`, `hx-target="#{container_id}"`,
/// `hx-swap="beforeend"`, and — critically — `hx-params="index"` so **only**
/// the `index` param (supplied by the `hx-vals` below) is serialized into the
/// Add-row GET; every parent + line-item field, and `_csrf`/submit token, is
/// dropped, avoiding leaks into the request query string / proxy logs. `"none"`
/// can NOT be used: the vendored htmx 2.0.4 merges `hx-vals` into the request
/// `FormData` *before* the `hx-params` filter runs, so `"none"` (an empty
/// `FormData`) would strip the computed `index` too — naming `index` keeps it.
///
/// The button also carries an `hx-vals` (`js:` form) that computes a fresh
/// `index` for each request — `max(existing data-index) + 1` scanning only
/// `#{container_id} .nested-fields__row[data-index]` (scoped by the container
/// id so a form reads its own rows). The endpoint should read that `index`
/// param and pass it to [`nested_row_fragment`] so every appended row gets a
/// name unique within the form; a static request would reuse the same index and
/// emit duplicate control names. This is the JS-present enhancement path only —
/// the no-JS fallback (pre-rendered blank rows) needs no such counter and is
/// unaffected.
///
/// # Multiple same-collection forms on one page
///
/// Both the Add-row `hx-target` and its `hx-vals` index scan address the
/// container by its `#{container_id}`. That scoping is only distinct if the ids
/// are distinct, so **every same-collection nested form that also sets
/// `add_row_url` must be given its own [`InputsForOptions::container_id`]** when
/// more than one appears on a page. The default `{collection}-rows` id is right
/// for a single such form; two forms sharing it emit duplicate HTML ids and each
/// Add-row button then targets / scans whichever container the shared id resolves
/// to first (the wrong form). A relative, id-free `hx-vals` scan was evaluated
/// and rejected: the vendored htmx 2.0.4 evaluates a `js:` `hx-vals` expression
/// with `Function("return (" + expr + ")")()` — no receiver — so `this` is the
/// global object, not the triggering button, leaving no reliable handle to walk
/// to the button's own container. The unique-id contract above is therefore the
/// supported way to keep several same-collection forms independent.
///
/// # CSRF
///
/// This renders only the child block. The surrounding `<form>` — via
/// [`crate::form::form_tag`] / `ChangesetForm` — carries the CSRF and submit-token
/// fields exactly as today; do **not** duplicate them here.
///
/// # Example
///
/// ```rust,ignore
/// use autumn_web::form::{required_text_input, submit_button};
/// use autumn_web::nested_form::{inputs_for, InputsForOptions};
///
/// // `form` is a `NestedChangesetForm<NewOrder, NewLineItem>` re-rendered after
/// // a failed submit; it derefs to its inner `NestedChangeset`.
/// let opts = InputsForOptions {
///     add_row_url: Some("/orders/line-item-row".into()),
///     ..InputsForOptions::default()
/// };
/// // Prefer `form.form_tag` over the standalone `form_tag`: it emits the CSRF
/// // hidden field under the app-configured field name (and the submit token),
/// // so a customized `security.csrf.form_field` survives the re-render.
/// form.form_tag("/orders", "POST", maud::html! {
///     // Parent fields (CSRF + submit token are emitted by `form.form_tag`).
///     (required_text_input(&form.parent, "name", "Order name"))
///     // Repeating child rows.
///     (inputs_for(&form, &opts, |row| maud::html! {
///         (row.required_text_input("sku", "SKU"))
///         (row.number_input("quantity", "Quantity"))
///         (row.destroy_checkbox("Remove"))
///     }))
///     (submit_button("Create order"))
/// });
/// ```
#[cfg(feature = "maud")]
#[must_use]
pub fn inputs_for<P, C: NestedChild>(
    nested: &NestedChangeset<P, C>,
    opts: &InputsForOptions,
    render_row: impl Fn(&RowScope) -> maud::Markup,
) -> maud::Markup {
    let collection = C::COLLECTION;
    let container_id = opts
        .container_id
        .clone()
        .unwrap_or_else(|| format!("{collection}-rows"));
    let rows = nested.rows();
    // Always emit at least one blank template row so the no-JS path can add a
    // child even when the caller asked for zero.
    let blank_count = opts.blank_rows.max(1);

    maud::html! {
        div id=(container_id) class="nested-fields" {
            @for (i, row) in rows.iter().enumerate() {
                @let scope = RowScope { collection, index: i, row: Some(row) };
                div class="nested-fields__row" data-index=(i) {
                    (render_row(&scope))
                }
            }
            @for k in 0..blank_count {
                @let index = rows.len().saturating_add(k);
                @let scope = RowScope { collection, index, row: None };
                div class="nested-fields__row" data-index=(index) {
                    (render_row(&scope))
                }
            }
            @if let Some(url) = &opts.add_row_url {
                // Send a *fresh* unique row index with every Add-row request.
                // `nested_row_fragment` requires the returned row's index to be
                // unique within this form; a static request would keep reusing
                // the same index and produce duplicate control names. Compute
                // `max(existing data-index) + 1` from this container's rows,
                // scoped by `#{container_id}`. That scoping is only distinct when
                // the id is distinct: callers rendering more than one
                // same-collection nested form on a page MUST give each a unique
                // `container_id` (see `InputsForOptions::container_id`), because
                // the vendored htmx 2.0.4 evaluates this `js:` `hx-vals` with no
                // `this`/`event` bound to the button, so an id-free relative walk
                // to the button's own container is not available. The decoder
                // tolerates gaps, so this stays collision-free even after
                // client-side row removals.
                //
                // `hx-params="index"` serializes ONLY the `index` param with
                // the Add-row GET: per htmx semantics a bare comma-list keeps
                // just the named params, so every parent + line-item field
                // (and `_csrf`/submit token) is dropped from the request query
                // string / proxy logs, avoiding leaks and URL-length limits.
                // We can NOT use `"none"`: in the vendored htmx 2.0.4 the
                // `hx-vals` values are merged into the request FormData BEFORE
                // the `hx-params` filter runs (see `htmx.min.js`: the request
                // builder does `const v=ln(j,V);let w=hn(v,r)` where `V` is the
                // resolved `hx-vals` and `hn` is `filterValues`), so `"none"`
                // (which returns an empty FormData) would strip the `index` we
                // compute here too. Naming `index` keeps exactly that one value.
                @let hx_vals = format!(
                    "js:{{\"index\": Math.max(-1, ...Array.from(document.querySelectorAll(\"#{container_id} .nested-fields__row[data-index]\")).map(function(e){{return parseInt(e.dataset.index,10);}})) + 1}}"
                );
                button
                    type="button"
                    class="nested-fields__add"
                    hx-get=(url)
                    hx-target=(format!("#{container_id}"))
                    hx-swap="beforeend"
                    hx-params="index"
                    hx-vals=(hx_vals)
                { "Add row" }
            }
        }
    }
}

/// Render a single blank child row for the htmx "Add row" fragment endpoint.
///
/// Returns one `<div class="nested-fields__row" data-index="{index}">` produced
/// by `render_row` with a blank [`RowScope`]. Because the decoder tolerates
/// non-contiguous indices, `index` only needs to be **unique** within the form
/// (e.g. a monotonically increasing counter the client tracks), not contiguous.
///
/// The [`inputs_for`] Add-row button sends this unique value as an `index`
/// param (via `hx-vals`, computed as `max(existing data-index) + 1`). Because
/// the button sets `hx-params="index"`, the Add-row request carries ONLY the
/// `hx-vals` `index` — no parent/line-item form fields and no CSRF/submit
/// token are serialized — and `index` is the only value this endpoint needs.
/// The endpoint should read that param from the query/form and pass it straight
/// to `nested_row_fragment(index, ..)`. Uniqueness — not contiguity — is the
/// contract: the decoder tolerates gaps, so indices left behind by client-side
/// row removals never cause collisions.
#[cfg(feature = "maud")]
#[must_use]
pub fn nested_row_fragment<C: NestedChild>(
    index: usize,
    render_row: impl Fn(&RowScope) -> maud::Markup,
) -> maud::Markup {
    let scope = RowScope {
        collection: C::COLLECTION,
        index,
        row: None,
    };
    maud::html! {
        div class="nested-fields__row" data-index=(index) {
            (render_row(&scope))
        }
    }
}

// ── Tests ──────────────────────────────────────────────────────────

#[cfg(test)]
mod tests {
    use super::*;
    use crate::form::NUL_CHARACTER_FIELD_ERROR;

    #[derive(serde::Serialize, serde::Deserialize, validator::Validate)]
    struct Order {
        #[validate(length(min = 1, message = "name required"))]
        name: String,
    }

    #[derive(serde::Serialize, serde::Deserialize, validator::Validate)]
    struct LineItem {
        #[validate(length(min = 1, message = "sku required"))]
        sku: String,
        #[validate(range(min = 1, message = "quantity must be >= 1"))]
        quantity: i32,
    }

    impl NestedChild for LineItem {
        const COLLECTION: &'static str = "items";
    }

    /// A child with one **required** field (`name`) and one **optional** field
    /// (`nickname`), used to exercise the reject-all-blank rules.
    #[derive(serde::Deserialize, validator::Validate)]
    struct Contact {
        #[validate(length(min = 1, message = "name required"))]
        name: String,
        #[validate(length(min = 1, message = "nickname too short"))]
        nickname: Option<String>,
    }

    impl NestedChild for Contact {
        const COLLECTION: &'static str = "contacts";
    }

    async fn nested_ok(_f: NestedChangesetForm<Order, LineItem>) -> &'static str {
        "ok"
    }

    #[tokio::test]
    async fn mixed_case_urlencoded_content_type_is_accepted() {
        use tower::ServiceExt;
        let req = Request::builder()
            .method("POST")
            .uri("/t")
            .header("Content-Type", "Application/X-WWW-Form-Urlencoded")
            .body(axum::body::Body::from("name=Order"))
            .unwrap();
        let resp = axum::Router::new()
            .route("/t", axum::routing::post(nested_ok))
            .oneshot(req)
            .await
            .unwrap();
        assert_eq!(resp.status(), axum::http::StatusCode::OK);
    }

    #[tokio::test]
    async fn wrong_content_type_is_rejected_with_415() {
        use tower::ServiceExt;
        let req = Request::builder()
            .method("POST")
            .uri("/t")
            .header("Content-Type", "text/plain")
            .body(axum::body::Body::from("name=Order"))
            .unwrap();
        let resp = axum::Router::new()
            .route("/t", axum::routing::post(nested_ok))
            .oneshot(req)
            .await
            .unwrap();
        assert_eq!(
            resp.status(),
            axum::http::StatusCode::UNSUPPORTED_MEDIA_TYPE
        );
    }

    fn p(k: &str, v: &str) -> (String, String) {
        (k.to_owned(), v.to_owned())
    }

    // ── #3394: repeated keys on the nested path ───────────────────────

    #[derive(serde::Deserialize, validator::Validate)]
    struct TaggedOrder {
        #[serde(default)]
        tags: Vec<String>,
    }

    #[test]
    fn repeated_parent_key_decodes_into_a_vec_field() {
        let pairs = vec![
            p("tags", "a"),
            p("tags", "b"),
            p("items[0][sku]", "A-1"),
            p("items[0][quantity]", "2"),
        ];
        let cs = decode_nested_urlencoded::<TaggedOrder, LineItem>(&pairs).expect("parent decodes");
        assert_eq!(cs.parent.data().tags, ["a", "b"]);
        assert!(cs.is_valid());
    }

    #[test]
    fn repeated_child_scalar_is_a_row_error_on_that_subfield() {
        let pairs = vec![
            p("name", "Order 1"),
            p("items[0][sku]", "A-1"),
            p("items[0][sku]", "B-2"),
            p("items[0][quantity]", "2"),
        ];
        let cs = decode_nested_urlencoded::<Order, LineItem>(&pairs).expect("parent decodes");
        assert!(!cs.is_valid());
        let errors = cs.rows()[0].errors_for("sku");
        assert_eq!(errors.len(), 1, "{errors:?}");
        assert!(errors[0].contains("`sku`"), "{errors:?}");
    }

    #[tokio::test]
    async fn repeated_parent_scalar_is_a_422_through_the_extractor() {
        use tower::ServiceExt;
        let req = Request::builder()
            .method("POST")
            .uri("/t")
            .header("Content-Type", "application/x-www-form-urlencoded")
            .body(axum::body::Body::from("name=a&name=b"))
            .unwrap();
        let resp = axum::Router::new()
            .route("/t", axum::routing::post(nested_ok))
            .oneshot(req)
            .await
            .unwrap();
        assert_eq!(resp.status(), axum::http::StatusCode::UNPROCESSABLE_ENTITY);
    }

    #[test]
    fn repeated_parent_scalar_fails_the_decode() {
        let pairs = vec![p("name", "a"), p("name", "b")];
        let err = decode_nested_urlencoded::<Order, LineItem>(&pairs)
            .err()
            .expect("a repeated parent scalar must not decode");
        assert!(err.contains("`name`"), "{err}");
    }

    #[derive(serde::Serialize, serde::Deserialize, validator::Validate)]
    struct TaggedItem {
        #[validate(length(min = 1, message = "sku required"))]
        sku: String,
        #[serde(default)]
        tags: Vec<String>,
    }

    impl NestedChild for TaggedItem {
        const COLLECTION: &'static str = "items";
    }

    #[test]
    fn repeated_child_values_survive_a_validation_error_re_render() {
        // `sku` fails validation; the re-render must keep both tags, not only
        // the last one.
        let pairs = vec![
            p("name", "Order 1"),
            p("items[0][sku]", ""),
            p("items[0][tags]", "a"),
            p("items[0][tags]", "b"),
        ];
        let cs = decode_nested_urlencoded::<Order, TaggedItem>(&pairs).expect("parent decodes");
        assert!(!cs.is_valid());
        let row = &cs.rows()[0];
        assert!(!row.errors_for("sku").is_empty());
        assert_eq!(row.values("tags"), ["a", "b"]);
        assert_eq!(row.value("tags"), Some("b"));
        assert_eq!(row.values("sku"), [""]);
        assert!(row.values("missing").is_empty());
    }

    #[test]
    fn seeded_child_vec_field_pre_fills_every_element() {
        let cs = NestedChangeset::seeded(
            Order {
                name: "Existing order".to_owned(),
            },
            vec![TaggedItem {
                sku: "A-1".to_owned(),
                tags: vec!["a".to_owned(), "b".to_owned()],
            }],
        );
        let row = &cs.rows()[0];
        assert_eq!(row.value("sku"), Some("A-1"));
        assert_eq!(row.values("tags"), ["a", "b"]);
    }

    // ── #2423: NUL bytes on the nested path ───────────────────────────

    /// The parent behaves exactly like a flat [`ChangesetForm`] field: the
    /// byte is stripped from the retained value and recorded as one error on
    /// the field that carried it.
    #[test]
    fn nul_byte_in_a_parent_field_is_a_parent_error() {
        let pairs = vec![
            p("name", "Order\u{0}1"),
            p("items[0][sku]", "A-1"),
            p("items[0][quantity]", "2"),
        ];
        let cs = decode_nested_urlencoded::<Order, LineItem>(&pairs).expect("parent decodes");
        assert!(!cs.is_valid());
        assert_eq!(cs.errors_for("name"), [NUL_CHARACTER_FIELD_ERROR]);
        assert_eq!(cs.parent.data().name, "Order1");
    }

    /// A child subfield is keyed under that subfield on that row, so it
    /// renders next to the offending input rather than at the row root.
    #[test]
    fn nul_byte_in_a_child_subfield_is_a_row_error() {
        let pairs = vec![
            p("name", "Order 1"),
            p("items[0][sku]", "A\u{0}-1"),
            p("items[0][quantity]", "2"),
        ];
        let cs = decode_nested_urlencoded::<Order, LineItem>(&pairs).expect("parent decodes");
        assert!(!cs.is_valid());
        assert_eq!(cs.rows().len(), 1);
        assert_eq!(cs.rows()[0].errors_for("sku"), [NUL_CHARACTER_FIELD_ERROR]);
        // The retained value the row re-renders is the cleaned text.
        assert_eq!(cs.rows()[0].value("sku"), Some("A-1"));
        assert!(
            cs.rows()[0].errors_for("quantity").is_empty(),
            "only the offending subfield is flagged"
        );
    }

    /// A NUL anywhere in the submission blocks the whole write, so
    /// `into_valid` cannot hand back children built from unstorable text.
    #[test]
    fn nul_byte_in_a_child_subfield_blocks_into_valid() {
        let pairs = vec![
            p("name", "Order 1"),
            p("items[0][sku]", "A\u{0}-1"),
            p("items[0][quantity]", "2"),
        ];
        let cs = decode_nested_urlencoded::<Order, LineItem>(&pairs).expect("parent decodes");
        assert!(cs.into_valid().is_err());
    }

    /// `_destroy` is a marker read only for truthiness, never a stored column,
    /// and `is_truthy` trims whitespace but not NUL. Cleaning it would rewrite
    /// the marker: `"1\u{0}"` reads as *false* today and would read as true
    /// after stripping, silently destroying a row the author submitted to keep.
    /// So the sweep leaves it alone entirely.
    #[test]
    fn a_nul_in_the_destroy_marker_does_not_flip_it_truthy() {
        let pairs = vec![
            p("name", "Order 1"),
            p("items[0][sku]", "A-1"),
            p("items[0][quantity]", "2"),
            p("items[0][_destroy]", "1\u{0}"),
        ];
        let cs = decode_nested_urlencoded::<Order, LineItem>(&pairs).expect("parent decodes");
        assert_eq!(cs.rows().len(), 1);
        assert!(
            !cs.rows()[0].is_destroyed(),
            "a NUL-mangled marker must stay falsy, not become a destroy"
        );
        assert!(cs.is_valid(), "and it is not an error either");
    }

    /// A row whose every legible subfield was nothing but NUL bytes must not
    /// silently vanish the way a genuinely blank template row does — the author
    /// submitted something, it just could not be stored.
    #[test]
    fn a_row_of_only_nul_bytes_is_reported_rather_than_dropped() {
        let pairs = vec![
            p("name", "Order 1"),
            p("items[0][sku]", "\u{0}"),
            p("items[0][quantity]", ""),
        ];
        let cs = decode_nested_urlencoded::<Order, LineItem>(&pairs).expect("parent decodes");
        assert_eq!(cs.rows().len(), 1, "the row must survive for re-render");
        assert_eq!(cs.rows()[0].errors_for("sku"), [NUL_CHARACTER_FIELD_ERROR]);
        assert!(!cs.is_valid());
    }

    /// A genuinely blank template row still drops, unchanged.
    #[test]
    fn a_blank_template_row_still_drops() {
        let pairs = vec![
            p("name", "Order 1"),
            p("items[0][sku]", ""),
            p("items[0][quantity]", ""),
        ];
        let cs = decode_nested_urlencoded::<Order, LineItem>(&pairs).expect("parent decodes");
        assert!(cs.rows().is_empty());
        assert!(cs.is_valid());
    }

    /// `decode_nested_urlencoded` is public and takes the raw pairs — tokens
    /// and all — so it applies the default plumbing exemption itself. A direct
    /// caller must not get a parent error keyed `_csrf`, which no template
    /// renders.
    #[test]
    fn default_plumbing_fields_are_exempt_for_direct_callers() {
        for field in ["_csrf", "_submit_token", "_method"] {
            let pairs = vec![
                p("name", "Order 1"),
                p(field, "to%00ken".replace("%00", "\u{0}").as_str()),
                p("items[0][sku]", "A-1"),
                p("items[0][quantity]", "2"),
            ];
            let cs = decode_nested_urlencoded::<Order, LineItem>(&pairs).expect("parent decodes");
            assert!(
                cs.is_valid(),
                "`{field}` must not produce an unrenderable error: {:?}",
                cs.errors_for(field)
            );
        }
    }

    /// The extractor is where the *configured* token field names are known, so
    /// that is where they have to be exempted. `decode_nested_urlencoded`
    /// covers only the defaults.
    #[tokio::test]
    async fn nested_extractor_exempts_the_configured_token_field_names() {
        use axum::body::Body;
        use axum::extract::FromRequest as _;

        let mut req = axum::http::Request::builder()
            .method("POST")
            .uri("/orders")
            .header("Content-Type", "application/x-www-form-urlencoded")
            .body(Body::from(
                "authenticity=to%00ken&stamp=st%00amp&name=Order+1\
                 &items%5B0%5D%5Bsku%5D=A-1&items%5B0%5D%5Bquantity%5D=2",
            ))
            .expect("build request");
        req.extensions_mut()
            .insert(crate::security::csrf::CsrfFormField(
                "authenticity".to_owned(),
            ));
        req.extensions_mut()
            .insert(crate::security::SubmitFormField("stamp".to_owned()));

        let form = NestedChangesetForm::<Order, LineItem>::from_request(req, &())
            .await
            .expect("body decodes");

        assert!(
            form.changeset.is_valid(),
            "renamed token fields must not produce unrenderable errors: {:?}",
            form.changeset.parent.errors()
        );
    }

    /// A destroyed row is never written, so it must never be *rejected* —
    /// otherwise the author cannot delete a row whose only remaining content
    /// was an unstorable byte. The blank-and-NUL rejection must not run ahead
    /// of the destroy check.
    #[test]
    fn a_destroyed_row_of_only_nul_bytes_is_not_rejected() {
        let pairs = vec![
            p("name", "Order 1"),
            p("items[0][sku]", "\u{0}"),
            p("items[0][quantity]", ""),
            p("items[0][_destroy]", "1"),
        ];
        let cs = decode_nested_urlencoded::<Order, LineItem>(&pairs).expect("parent decodes");
        assert!(
            cs.is_valid(),
            "a row the author asked to destroy must not block the submission"
        );
        assert!(
            cs.into_valid().is_ok(),
            "the parent must still be bindable so the destroy can be applied"
        );
    }

    /// A repeated subfield carrying NULs contributes one message, not one per
    /// occurrence — the same guarantee the flat sweep already makes. Without
    /// it a crafted body inflates a single row's error list without bound.
    #[test]
    fn a_repeated_nul_subfield_in_a_row_reports_once() {
        let pairs = vec![
            p("name", "Order 1"),
            p("items[0][sku]", "A-1"),
            p("items[0][quantity]", "2"),
            p("items[0][unknown]", "a\u{0}a"),
            p("items[0][unknown]", "b\u{0}b"),
            p("items[0][unknown]", "c\u{0}c"),
        ];
        let cs = decode_nested_urlencoded::<Order, LineItem>(&pairs).expect("parent decodes");
        assert_eq!(cs.rows().len(), 1);
        assert_eq!(
            cs.rows()[0].errors_for("unknown").len(),
            1,
            "one message per offending subfield, not one per submitted pair"
        );
    }

    /// No false positives on the nested path either.
    #[test]
    fn clean_nested_submission_is_unaffected() {
        let pairs = vec![
            p("name", "Order 1"),
            p("items[0][sku]", "A-1"),
            p("items[0][quantity]", "2"),
        ];
        let cs = decode_nested_urlencoded::<Order, LineItem>(&pairs).expect("parent decodes");
        assert!(cs.is_valid());
    }

    #[test]
    fn binds_parent_and_two_children_in_order() {
        let pairs = vec![
            p("name", "Order 1"),
            p("items[0][sku]", "A-1"),
            p("items[0][quantity]", "2"),
            p("items[1][sku]", "B-2"),
            p("items[1][quantity]", "3"),
        ];
        let cs = decode_nested_urlencoded::<Order, LineItem>(&pairs).expect("parent decodes");
        assert!(cs.is_valid());
        assert_eq!(cs.rows().len(), 2);
        assert_eq!(cs.rows()[0].value("sku"), Some("A-1"));
        assert_eq!(cs.rows()[1].value("sku"), Some("B-2"));
        assert_eq!(cs.collection_name(), "items");

        let (order, items) = cs.into_valid().unwrap_or_else(|_| panic!("valid"));
        assert_eq!(order.name, "Order 1");
        assert_eq!(items.len(), 2);
        assert_eq!(items[0].sku, "A-1");
        assert_eq!(items[0].quantity, 2);
        assert_eq!(items[1].quantity, 3);
    }

    #[test]
    fn non_contiguous_indices_compact_preserving_order() {
        let pairs = vec![
            p("name", "Order"),
            p("items[0][sku]", "A"),
            p("items[0][quantity]", "1"),
            p("items[2][sku]", "C"),
            p("items[2][quantity]", "5"),
        ];
        let cs = decode_nested_urlencoded::<Order, LineItem>(&pairs).expect("parent decodes");
        // Gap at index 1 compacts: two rows in ascending order.
        assert_eq!(cs.rows().len(), 2);
        assert_eq!(cs.rows()[0].value("sku"), Some("A"));
        assert_eq!(cs.rows()[1].value("sku"), Some("C"));
        assert!(cs.is_valid());

        let (_order, items) = cs.into_valid().unwrap_or_else(|_| panic!("valid"));
        assert_eq!(items.len(), 2);
        assert_eq!(items[0].sku, "A");
        assert_eq!(items[1].sku, "C");
    }

    #[test]
    fn destroy_marker_drops_row_from_children_but_retains_it() {
        let pairs = vec![
            p("name", "Order"),
            p("items[0][sku]", "A"),
            p("items[0][quantity]", "1"),
            p("items[1][sku]", "X"),
            p("items[1][quantity]", "9"),
            p("items[1][_destroy]", "1"),
        ];
        let cs = decode_nested_urlencoded::<Order, LineItem>(&pairs).expect("parent decodes");
        assert_eq!(cs.rows().len(), 2);
        assert!(!cs.rows()[0].is_destroyed());
        assert!(cs.rows()[1].is_destroyed());
        // Destroyed row is still retained with its raw values for re-render.
        assert_eq!(cs.rows()[1].value("sku"), Some("X"));
        assert!(cs.is_valid());

        let (_order, items) = cs.into_valid().unwrap_or_else(|_| panic!("valid"));
        // Only the non-destroyed row contributes.
        assert_eq!(items.len(), 1);
        assert_eq!(items[0].sku, "A");
    }

    #[test]
    fn child_validation_failure_surfaces_combined_key_and_blocks_valid() {
        let pairs = vec![
            p("name", "Order"),
            p("items[0][sku]", "A"),
            p("items[0][quantity]", "2"),
            // quantity = 0 violates range(min = 1)
            p("items[1][sku]", "B"),
            p("items[1][quantity]", "0"),
        ];
        let cs = decode_nested_urlencoded::<Order, LineItem>(&pairs).expect("parent decodes");
        assert!(!cs.is_valid());
        assert!(!cs.errors_for("items[1].quantity").is_empty());
        // The valid sibling row has no error for that key.
        assert!(cs.errors_for("items[0].quantity").is_empty());
        assert!(cs.into_valid().is_err());
    }

    #[test]
    fn all_valid_yields_ok_with_coerced_numeric_fields() {
        let pairs = vec![
            p("name", "Order"),
            p("items[0][sku]", "A"),
            p("items[0][quantity]", "5"),
        ];
        let cs = decode_nested_urlencoded::<Order, LineItem>(&pairs).expect("parent decodes");
        assert!(cs.is_valid());
        let (order, items) = cs.into_valid().unwrap_or_else(|_| panic!("valid"));
        assert_eq!(order.name, "Order");
        assert_eq!(items.len(), 1);
        // "5" coerced to i32.
        let q: i32 = items[0].quantity;
        assert_eq!(q, 5);
    }

    #[test]
    fn parent_invalid_blocks_valid_children() {
        let pairs = vec![
            // Empty parent name violates length(min = 1).
            p("name", ""),
            p("items[0][sku]", "A"),
            p("items[0][quantity]", "1"),
        ];
        let cs = decode_nested_urlencoded::<Order, LineItem>(&pairs).expect("parent decodes");
        assert!(!cs.is_valid());
        assert!(!cs.errors_for("name").is_empty());
        assert!(cs.into_valid().is_err());
    }

    #[test]
    fn child_parse_failure_keys_error_to_offending_field() {
        let pairs = vec![
            p("name", "Order"),
            // `sku` is filled, so the row is NOT all-blank (it is kept, not
            // dropped) — contrast `all_blank_template_row_is_ignored`, where an
            // empty row is dropped entirely with no error.
            p("items[0][sku]", "A"),
            // Non-numeric quantity: hard parse failure for i32, before
            // validation. `serde_path_to_error` attributes it to `quantity`.
            p("items[0][quantity]", "not-a-number"),
        ];
        let cs = decode_nested_urlencoded::<Order, LineItem>(&pairs).expect("parent decodes");
        assert!(!cs.is_valid());
        assert_eq!(cs.rows().len(), 1);
        // Raw values retained for re-render.
        assert_eq!(cs.rows()[0].value("sku"), Some("A"));
        assert_eq!(cs.rows()[0].value("quantity"), Some("not-a-number"));
        // The parse error is keyed to the offending subfield, so it renders next
        // to the bad input via `errors_for("quantity")` on that row.
        assert!(!cs.errors_for("items[0].quantity").is_empty());
        assert!(!cs.rows()[0].errors_for("quantity").is_empty());
        // It is NOT stored under the row-level "" key anymore.
        assert!(cs.rows()[0].errors_for("").is_empty());
        assert!(cs.errors_for("items[0]").is_empty());
        assert!(cs.into_valid().is_err());
    }

    #[test]
    fn child_parse_failure_on_blank_typed_field_keys_error_to_field() {
        // The Codex case: a row with `sku` filled but the required TYPED
        // `quantity` present-but-blank. The blank-optional retry inside
        // `decode_urlencoded_dropping_blank_optional_fields` DROPS the blank
        // `quantity=` pair, so serde reports `missing field \`quantity\`` at the
        // ROW ROOT (empty path). The field-recovery re-decode over the original
        // (blank-retained) pairs must still key the error to `quantity` so it
        // renders next to the blank input rather than the row-level "" key.
        let pairs = vec![
            p("name", "Order"),
            p("items[0][sku]", "A"),
            p("items[0][quantity]", ""),
        ];
        let cs = decode_nested_urlencoded::<Order, LineItem>(&pairs).expect("parent decodes");
        assert!(!cs.is_valid());
        assert_eq!(cs.rows().len(), 1);
        // Keyed to the offending subfield, so it renders next to the blank input.
        assert!(!cs.errors_for("items[0].quantity").is_empty());
        assert!(!cs.rows()[0].errors_for("quantity").is_empty());
        // NOT stored under the row-level "" / `items[0]` key.
        assert!(cs.rows()[0].errors_for("").is_empty());
        assert!(cs.errors_for("items[0]").is_empty());
        assert!(cs.into_valid().is_err());
    }

    #[test]
    fn child_row_with_blank_optional_typed_field_still_decodes_valid() {
        // Regression guard for the fix: a row with the required field filled and
        // an OPTIONAL TYPED field present-but-blank (`weight=`) must still decode
        // to a VALID row. The primary blank-dropping decode drops the blank
        // `weight=` pair so it resolves to `None` and the decode SUCCEEDS — the
        // field-recovery re-decode (which runs only on the failed path) is never
        // reached, and the row must stay valid.
        #[derive(serde::Deserialize, validator::Validate)]
        struct Widget {
            #[validate(length(min = 1, message = "label required"))]
            label: String,
            // Typed optional: a blank submission is dropped to `None` by the
            // blank-optional decode (an empty string is not a valid `i32`).
            weight: Option<i32>,
        }
        impl NestedChild for Widget {
            const COLLECTION: &'static str = "widgets";
        }

        let pairs = vec![
            p("name", "Order"),
            p("widgets[0][label]", "Bolt"),
            p("widgets[0][weight]", ""),
        ];
        let cs = decode_nested_urlencoded::<Order, Widget>(&pairs).expect("parent decodes");
        assert!(cs.is_valid());
        assert_eq!(cs.rows().len(), 1);
        assert!(cs.errors_for("widgets[0].weight").is_empty());
        assert!(cs.rows()[0].errors_for("weight").is_empty());
        let (_order, widgets) = cs.into_valid().unwrap_or_else(|_| panic!("valid"));
        assert_eq!(widgets.len(), 1);
        assert_eq!(widgets[0].label, "Bolt");
        assert_eq!(widgets[0].weight, None);
    }

    #[test]
    fn child_optional_blank_before_required_blank_keys_error_to_required_field() {
        // Codex P2 follow-on: a child whose OPTIONAL typed field (`weight:
        // Option<i32>`) is declared BEFORE a REQUIRED typed field (`quantity:
        // i32`), with BOTH submitted blank. The blank-dropping decode drops both
        // blank pairs and ends at `missing field \`quantity\`` — the required
        // one. A raw non-dropping re-decode, by contrast, trips FIRST on the
        // harmless optional `weight=` (parsing `""` as an `i32` at `.weight`), so
        // it would mis-key the error to `weight`. The field-recovery therefore
        // prefers the PRIMARY error's missing-field message over the raw
        // re-decode, so the inline error lands on `quantity`, not `weight`.
        #[derive(serde::Deserialize, validator::Validate)]
        struct Part {
            #[validate(length(min = 1, message = "sku required"))]
            sku: String,
            // Optional, declared FIRST — a blank submission is harmless (→ None).
            // Never read on this invalid-row path (the row fails to fully decode),
            // so silence the dead-field lint.
            #[allow(dead_code)]
            weight: Option<i32>,
            // Required, declared AFTER — a blank submission is the real error.
            #[validate(range(min = 1, message = "quantity must be >= 1"))]
            quantity: i32,
        }
        impl NestedChild for Part {
            const COLLECTION: &'static str = "items";
        }

        let pairs = vec![
            p("name", "Order"),
            // `sku` filled so the row is retained (not all-blank).
            p("items[0][sku]", "Widget"),
            p("items[0][weight]", ""),
            p("items[0][quantity]", ""),
        ];
        let cs = decode_nested_urlencoded::<Order, Part>(&pairs).expect("parent decodes");
        assert!(!cs.is_valid());
        assert_eq!(cs.rows().len(), 1);
        // The error is keyed to the truly-missing REQUIRED field…
        assert!(!cs.errors_for("items[0].quantity").is_empty());
        assert!(!cs.rows()[0].errors_for("quantity").is_empty());
        // …and NOT to the harmless OPTIONAL blank the raw re-decode trips on.
        assert!(cs.errors_for("items[0].weight").is_empty());
        assert!(cs.rows()[0].errors_for("weight").is_empty());
        // Not stored under the row-level "" / `items[0]` key either.
        assert!(cs.rows()[0].errors_for("").is_empty());
        assert!(cs.errors_for("items[0]").is_empty());
        assert!(cs.into_valid().is_err());
    }

    #[test]
    fn parent_hard_parse_failure_is_err() {
        #[derive(serde::Deserialize, validator::Validate)]
        struct NumericParent {
            #[validate(range(min = 0))]
            count: i32,
        }
        #[derive(serde::Deserialize, validator::Validate)]
        struct Child {
            #[validate(length(min = 1))]
            name: String,
        }
        impl NestedChild for Child {
            const COLLECTION: &'static str = "kids";
        }

        let pairs = vec![p("count", "not-a-number")];
        let result = decode_nested_urlencoded::<NumericParent, Child>(&pairs);
        assert!(result.is_err());
    }

    // ── reject_if: :all_blank ──────────────────────────────────────

    /// The core regression test for the phantom-blank-row P1: `inputs_for`
    /// always emits a trailing all-blank template row, and with no JS the
    /// browser submits its empty inputs. That row must be ignored, not decoded
    /// as a real (empty) child.
    #[test]
    fn all_blank_template_row_is_ignored() {
        let pairs = vec![
            p("name", "Order"),
            // One filled, valid child row.
            p("contacts[0][name]", "Alice"),
            p("contacts[0][nickname]", "Al"),
            // The auto-rendered blank template row: every subfield empty.
            p("contacts[1][name]", ""),
            p("contacts[1][nickname]", ""),
        ];
        let cs = decode_nested_urlencoded::<Order, Contact>(&pairs).expect("parent decodes");
        assert!(cs.is_valid());
        // The blank template row was dropped entirely — only the real row remains.
        assert_eq!(cs.rows().len(), 1);
        assert_eq!(cs.rows()[0].value("name"), Some("Alice"));

        let (_order, contacts) = cs.into_valid().unwrap_or_else(|_| panic!("valid"));
        assert_eq!(contacts.len(), 1);
        assert_eq!(contacts[0].name, "Alice");
    }

    /// Blank detection trims: a row whose fields are whitespace-only (or empty)
    /// is treated as blank and dropped.
    #[test]
    fn whitespace_only_row_is_ignored() {
        let pairs = vec![
            p("name", "Order"),
            p("contacts[0][name]", "Bob"),
            // Whitespace-only + empty: still all-blank after trimming.
            p("contacts[1][name]", "   "),
            p("contacts[1][nickname]", ""),
        ];
        let cs = decode_nested_urlencoded::<Order, Contact>(&pairs).expect("parent decodes");
        assert!(cs.is_valid());
        assert_eq!(cs.rows().len(), 1);
        assert_eq!(cs.rows()[0].value("name"), Some("Bob"));

        let (_order, contacts) = cs.into_valid().unwrap_or_else(|_| panic!("valid"));
        assert_eq!(contacts.len(), 1);
    }

    /// A row with at least one non-blank value is a real child the user is
    /// adding: it is kept and validated, so a missing **required** field still
    /// surfaces a per-row error. We must not over-aggressively drop it.
    #[test]
    fn partially_filled_row_with_missing_required_still_errors() {
        let pairs = vec![
            p("name", "Order"),
            // Required `name` left blank, but the optional `nickname` is filled,
            // so the row is NOT all-blank: it is kept and must error.
            p("contacts[0][name]", ""),
            p("contacts[0][nickname]", "Ally"),
        ];
        let cs = decode_nested_urlencoded::<Order, Contact>(&pairs).expect("parent decodes");
        assert!(!cs.is_valid());
        assert_eq!(cs.rows().len(), 1);
        // The kept row surfaces the required-field error under its combined key.
        assert!(!cs.errors_for("contacts[0].name").is_empty());
        // Raw values retained for re-render.
        assert_eq!(cs.rows()[0].value("nickname"), Some("Ally"));
        assert!(cs.into_valid().is_err());
    }

    /// A fully filled row is still bound — reject-all-blank does not regress the
    /// happy path when every submitted row carries real values.
    #[test]
    fn fully_filled_row_is_still_bound() {
        let pairs = vec![
            p("name", "Order"),
            p("contacts[0][name]", "Carol"),
            p("contacts[0][nickname]", "Caz"),
        ];
        let cs = decode_nested_urlencoded::<Order, Contact>(&pairs).expect("parent decodes");
        assert!(cs.is_valid());
        assert_eq!(cs.rows().len(), 1);

        let (_order, contacts) = cs.into_valid().unwrap_or_else(|_| panic!("valid"));
        assert_eq!(contacts.len(), 1);
        assert_eq!(contacts[0].name, "Carol");
        assert_eq!(contacts[0].nickname.as_deref(), Some("Caz"));
    }

    #[test]
    fn parse_child_key_matches_and_rejects() {
        assert_eq!(parse_child_key("items[0][sku]", "items"), Some((0, "sku")));
        assert_eq!(
            parse_child_key("items[12][quantity]", "items"),
            Some((12, "quantity"))
        );
        // Wrong collection.
        assert_eq!(parse_child_key("other[0][sku]", "items"), None);
        // Not a child subfield (parent key).
        assert_eq!(parse_child_key("name", "items"), None);
        // Trailing junk after the closing bracket.
        assert_eq!(parse_child_key("items[0][sku]x", "items"), None);
        // Non-numeric index.
        assert_eq!(parse_child_key("items[a][sku]", "items"), None);
    }

    // ── blank (non-validating) constructor ─────────────────────────

    #[test]
    fn blank_changeset_is_valid_with_no_rows_or_errors() {
        // The initial `new`-page path: the required parent `name` is still
        // empty, but `blank` does NOT validate, so nothing errors before the
        // user types (unlike `decode_nested_urlencoded`).
        let cs = NestedChangeset::<Order, LineItem>::blank(Order {
            name: String::new(),
        });
        assert!(cs.is_valid());
        assert!(cs.errors_for("name").is_empty());
        assert!(cs.rows().is_empty());

        let (order, items) = cs
            .into_valid()
            .unwrap_or_else(|_| panic!("blank changeset is valid"));
        assert_eq!(order.name, "");
        assert!(items.is_empty());
    }

    #[test]
    fn decoded_empty_parent_errors_unlike_blank() {
        // Contrast the POST decode path: it DOES validate, so the same empty
        // required parent surfaces an error — exactly what `blank` avoids on the
        // initial GET render.
        let cs =
            decode_nested_urlencoded::<Order, LineItem>(&[p("name", "")]).expect("parent decodes");
        assert!(!cs.is_valid());
        assert!(!cs.errors_for("name").is_empty());
    }

    // ── seeded (edit-render) constructor ───────────────────────────

    #[test]
    fn seeded_changeset_pre_populates_one_row_per_child() {
        // The initial `edit`-page path: seed the changeset with the two existing
        // children so an edit form can display/preserve them before first submit.
        let cs = NestedChangeset::seeded(
            Order {
                name: "Existing order".to_owned(),
            },
            vec![
                LineItem {
                    sku: "A-1".to_owned(),
                    quantity: 2,
                },
                LineItem {
                    sku: "B-2".to_owned(),
                    quantity: 3,
                },
            ],
        );

        // One row per seeded child, each pre-filled with its serialized values —
        // the same string representation the decoder populates.
        assert_eq!(cs.rows().len(), 2);
        assert_eq!(cs.rows()[0].value("sku"), Some("A-1"));
        assert_eq!(cs.rows()[0].value("quantity"), Some("2"));
        assert_eq!(cs.rows()[1].value("sku"), Some("B-2"));
        assert_eq!(cs.rows()[1].value("quantity"), Some("3"));

        // Non-validating and clean: no errors, no destroyed rows.
        assert!(cs.is_valid());
        assert!(cs.errors_for("name").is_empty());
        assert!(cs.errors_for("items[0].sku").is_empty());
        assert!(cs.errors_for("items[1].quantity").is_empty());
        assert!(!cs.rows()[0].is_destroyed());
        assert!(!cs.rows()[1].is_destroyed());

        // `into_valid` returns the seeded parent + children unchanged.
        let (order, items) = cs
            .into_valid()
            .unwrap_or_else(|_| panic!("seeded changeset is valid"));
        assert_eq!(order.name, "Existing order");
        assert_eq!(items.len(), 2);
        assert_eq!(items[0].sku, "A-1");
        assert_eq!(items[0].quantity, 2);
        assert_eq!(items[1].sku, "B-2");
        assert_eq!(items[1].quantity, 3);
    }

    #[test]
    fn seeded_changeset_with_no_children_is_valid_and_empty() {
        // Seeding zero children behaves like `blank` — a valid changeset with no
        // rows — so an edit form for a parent that currently has no children is
        // handled uniformly.
        let cs = NestedChangeset::<Order, LineItem>::seeded(
            Order {
                name: "Empty".to_owned(),
            },
            Vec::new(),
        );
        assert!(cs.is_valid());
        assert!(cs.rows().is_empty());
        let (_order, items) = cs
            .into_valid()
            .unwrap_or_else(|_| panic!("seeded changeset is valid"));
        assert!(items.is_empty());
    }
}

#[cfg(all(test, feature = "maud"))]
mod maud_tests {
    use super::*;

    #[derive(serde::Serialize, serde::Deserialize, validator::Validate)]
    struct Order {
        #[validate(length(min = 1, message = "name required"))]
        name: String,
    }

    #[derive(serde::Serialize, serde::Deserialize, validator::Validate)]
    struct LineItem {
        #[validate(length(min = 1, message = "sku required"))]
        sku: String,
        #[validate(range(min = 1, message = "quantity must be >= 1"))]
        quantity: i32,
    }

    impl NestedChild for LineItem {
        const COLLECTION: &'static str = "items";
    }

    fn p(k: &str, v: &str) -> (String, String) {
        (k.to_owned(), v.to_owned())
    }

    /// A changeset with two submitted rows, the second failing child validation
    /// (`quantity = 0`), so both rows are retained for re-render.
    fn two_row_changeset() -> NestedChangeset<Order, LineItem> {
        let pairs = vec![
            p("name", "Order 1"),
            p("items[0][sku]", "A-1"),
            p("items[0][quantity]", "2"),
            p("items[1][sku]", "B-2"),
            // quantity = 0 violates range(min = 1): row 1 is retained with an error.
            p("items[1][quantity]", "0"),
        ];
        decode_nested_urlencoded::<Order, LineItem>(&pairs).expect("parent decodes")
    }

    fn render_row(row: &RowScope) -> maud::Markup {
        maud::html! {
            (row.required_text_input("sku", "SKU"))
            (row.number_input("quantity", "Quantity"))
            (row.destroy_checkbox("Remove"))
        }
    }

    #[test]
    fn existing_rows_render_indexed_names_and_prefilled_values() {
        let cs = two_row_changeset();
        let opts = InputsForOptions::default();
        let html = inputs_for(&cs, &opts, render_row).into_string();

        assert!(html.contains(r#"name="items[0][sku]""#), "{html}");
        assert!(html.contains(r#"name="items[1][sku]""#), "{html}");
        // Pre-filled values from the re-rendered changeset.
        assert!(html.contains(r#"value="A-1""#), "{html}");
        assert!(html.contains(r#"value="B-2""#), "{html}");
        // Container defaults to "{collection}-rows".
        assert!(html.contains(r#"id="items-rows""#), "{html}");
    }

    #[test]
    fn per_row_error_renders_scoped_alert_block() {
        let cs = two_row_changeset();
        let opts = InputsForOptions::default();
        let html = inputs_for(&cs, &opts, render_row).into_string();

        // The failing row's quantity error is scoped to that row's unique id.
        assert!(html.contains(r#"id="items-1-quantity-error""#), "{html}");
        assert!(html.contains(r#"role="alert""#), "{html}");
        assert!(html.contains("quantity must be &gt;= 1"), "{html}");
        // The valid sibling row's quantity has no error block.
        assert!(!html.contains(r#"id="items-0-quantity-error""#), "{html}");
    }

    #[test]
    fn appends_blank_template_row_with_next_index() {
        let cs = two_row_changeset();
        let opts = InputsForOptions::default();
        let html = inputs_for(&cs, &opts, render_row).into_string();

        // Two existing rows (indices 0,1) plus one blank row at index 2.
        assert!(html.contains(r#"data-index="0""#), "{html}");
        assert!(html.contains(r#"data-index="1""#), "{html}");
        assert!(html.contains(r#"data-index="2""#), "{html}");
        assert!(html.contains(r#"name="items[2][sku]""#), "{html}");
    }

    /// Extract the full `<...>` tag containing the given `name="…"` attribute,
    /// so a per-input attribute assertion isn't fooled by a sibling row's tag.
    fn tag_with_name(html: &str, name: &str) -> String {
        let needle = format!(r#"name="{name}""#);
        let at = html
            .find(&needle)
            .unwrap_or_else(|| panic!("missing {name} in {html}"));
        let open = html[..at].rfind('<').expect("tag has an opening '<'");
        let close = html[at..].find('>').expect("tag has a closing '>'") + at;
        html[open..=close].to_string()
    }

    /// Fix 1: a required-variant input on a submitted row carries the client-side
    /// `required`/`aria-required` constraint, but the auto-appended blank template
    /// row (`row: None`) omits it so the form stays submittable with a trailing
    /// blank row present (server-side validation still enforces required-ness).
    #[test]
    fn blank_template_row_omits_client_required_but_submitted_row_keeps_it() {
        let cs = two_row_changeset();
        let opts = InputsForOptions::default();
        let html = inputs_for(&cs, &opts, render_row).into_string();

        // Submitted rows (indices 0, 1) keep the client-side constraint.
        let submitted = tag_with_name(&html, "items[0][sku]");
        assert!(submitted.contains(" required"), "{submitted}");
        assert!(submitted.contains(r#"aria-required="true""#), "{submitted}");

        // The appended blank template row (index 2) omits both, so it is
        // leaveable-empty and does not block submitting the form.
        let blank = tag_with_name(&html, "items[2][sku]");
        assert!(!blank.contains("required"), "{blank}");
        assert!(!blank.contains("aria-required"), "{blank}");
    }

    /// Fix (Codex P2, near the `required` gate): a submitted row the user ticked
    /// `_destroy` on must ALSO omit the client-side `required`/`aria-required`,
    /// exactly like a blank template row. Otherwise, in a 422 re-render where the
    /// user checked Remove on a row with an empty required field, the browser's
    /// constraint validation would block the next submit before the server can
    /// honor `_destroy`. A non-destroyed submitted row in the same render keeps
    /// the constraint.
    #[test]
    fn destroyed_row_omits_client_required_while_submitted_row_keeps_it() {
        // Row 0: an ordinary submitted row. Row 1: the user ticked Remove on a
        // row whose required `sku` is empty (it is retained because `quantity`
        // is non-blank, so the all-blank rejection does not drop it).
        let pairs = vec![
            p("name", "Order 1"),
            p("items[0][sku]", "A-1"),
            p("items[0][quantity]", "2"),
            p("items[1][sku]", ""),
            p("items[1][quantity]", "9"),
            p("items[1][_destroy]", "1"),
        ];
        let cs = decode_nested_urlencoded::<Order, LineItem>(&pairs).expect("parent decodes");
        assert!(cs.rows()[1].is_destroyed());
        let html = inputs_for(&cs, &InputsForOptions::default(), render_row).into_string();

        // The non-destroyed submitted row keeps the client-side constraint.
        let kept = tag_with_name(&html, "items[0][sku]");
        assert!(kept.contains(" required"), "{kept}");
        assert!(kept.contains(r#"aria-required="true""#), "{kept}");

        // The destroyed row omits both, exactly like a blank template row, so a
        // form carrying an empty required field on a to-be-removed row still
        // submits and the server can honor `_destroy`.
        let destroyed = tag_with_name(&html, "items[1][sku]");
        assert!(!destroyed.contains("required"), "{destroyed}");
        assert!(!destroyed.contains("aria-required"), "{destroyed}");
    }

    #[test]
    fn always_emits_a_blank_row_even_when_blank_rows_zero() {
        let cs = two_row_changeset();
        let opts = InputsForOptions {
            blank_rows: 0,
            ..InputsForOptions::default()
        };
        let html = inputs_for(&cs, &opts, render_row).into_string();
        // Still emits the blank template row at index 2.
        assert!(html.contains(r#"data-index="2""#), "{html}");
    }

    #[test]
    fn destroy_checkbox_emits_indexed_marker() {
        let cs = two_row_changeset();
        let opts = InputsForOptions::default();
        let html = inputs_for(&cs, &opts, render_row).into_string();

        assert!(html.contains(r#"name="items[0][_destroy]""#), "{html}");
        assert!(html.contains(r#"name="items[1][_destroy]""#), "{html}");
        assert!(html.contains(r#"type="checkbox""#), "{html}");
    }

    #[test]
    fn add_button_renders_only_with_url_and_carries_htmx_attrs() {
        let cs = two_row_changeset();

        // No URL: no Add button.
        let none = inputs_for(&cs, &InputsForOptions::default(), render_row).into_string();
        assert!(!none.contains("Add row"), "{none}");

        // With URL: button serializes only the `index` param (`hx-params="index"`)
        // and uses a beforeend swap.
        let opts = InputsForOptions {
            add_row_url: Some("/orders/line-item-row".into()),
            ..InputsForOptions::default()
        };
        let html = inputs_for(&cs, &opts, render_row).into_string();
        assert!(html.contains("Add row"), "{html}");
        assert!(html.contains(r#"hx-params="index""#), "{html}");
        assert!(html.contains(r#"hx-swap="beforeend""#), "{html}");
        assert!(html.contains(r#"hx-get="/orders/line-item-row""#), "{html}");
        assert!(html.contains(r##"hx-target="#items-rows""##), "{html}");
    }

    /// Fix (Codex P2, near the Add-row button): the Add-row button sends a fresh
    /// unique `index` with each htmx request via `hx-vals` (`js:` form) computed
    /// from THIS container's rows (`max(existing data-index) + 1`), so repeated
    /// clicks never reuse an index and emit duplicate control names. The selector
    /// is scoped to the form's own container id; keeping several same-collection
    /// forms independent requires each to pass a distinct `container_id` (see
    /// `add_button_targets_and_scans_custom_container_id`). The pre-existing htmx
    /// attrs stay intact.
    #[test]
    fn add_button_hx_vals_sends_fresh_container_scoped_index() {
        let cs = two_row_changeset();
        let opts = InputsForOptions {
            add_row_url: Some("/orders/line-item-row".into()),
            ..InputsForOptions::default()
        };
        let html = inputs_for(&cs, &opts, render_row).into_string();

        // Pre-existing htmx wiring is preserved.
        assert!(html.contains(r#"hx-get="/orders/line-item-row""#), "{html}");
        assert!(html.contains(r#"hx-swap="beforeend""#), "{html}");
        assert!(html.contains(r#"hx-params="index""#), "{html}");

        // A JS-computed `hx-vals` that sends a fresh `index`…
        assert!(html.contains("hx-vals="), "{html}");
        assert!(html.contains("Math.max(-1"), "{html}");
        // …referencing the `index` param and reading each row's `data-index`…
        assert!(html.contains("parseInt(e.dataset.index,10)"), "{html}");
        // …via a selector scoped to THIS form's container id.
        assert!(
            html.contains("#items-rows .nested-fields__row[data-index]"),
            "{html}"
        );
    }

    /// Fix (Codex P2, container-id collisions): a caller rendering two nested
    /// forms for the same child collection on one page must give each a distinct
    /// `container_id` so their Add-row buttons stay independent. Assert that an
    /// explicit `container_id` flows through to BOTH the container `id` and the
    /// Add-row button's `hx-target` + `hx-vals` index scan — proving per-form
    /// scoping works once ids are distinct — and that the default id is absent.
    #[test]
    fn add_button_targets_and_scans_custom_container_id() {
        let cs = two_row_changeset();
        let opts = InputsForOptions {
            add_row_url: Some("/orders/line-item-row".into()),
            // A second same-collection form on the page would pass its own id;
            // this one deliberately avoids containing the `items-rows` default so
            // the negative assertions below are exact substring checks.
            container_id: Some("shipping-lines".into()),
            ..InputsForOptions::default()
        };
        let html = inputs_for(&cs, &opts, render_row).into_string();

        // The container carries the custom id, not the `{collection}-rows` default.
        assert!(
            html.contains(r#"<div id="shipping-lines" class="nested-fields">"#),
            "{html}"
        );
        // The Add-row button targets the custom container…
        assert!(html.contains(r##"hx-target="#shipping-lines""##), "{html}");
        // …and its index scan reads that same custom container's rows…
        assert!(
            html.contains("#shipping-lines .nested-fields__row[data-index]"),
            "{html}"
        );
        // …with no leftover reference to the default id.
        assert!(!html.contains("items-rows .nested-fields__row"), "{html}");
        assert!(!html.contains(r##"hx-target="#items-rows""##), "{html}");
    }

    #[test]
    fn destroy_checkbox_checked_reflects_destroyed_row() {
        let pairs = vec![
            p("name", "Order"),
            p("items[0][sku]", "A"),
            p("items[0][quantity]", "1"),
            p("items[0][_destroy]", "1"),
        ];
        let cs = decode_nested_urlencoded::<Order, LineItem>(&pairs).expect("parent decodes");
        let html = inputs_for(&cs, &InputsForOptions::default(), render_row).into_string();
        // The destroyed row's checkbox is checked.
        assert!(
            html.contains(r#"name="items[0][_destroy]" value="1" checked"#),
            "{html}"
        );
    }

    #[test]
    fn nested_row_fragment_renders_single_row_at_index() {
        let html = nested_row_fragment::<LineItem>(7, render_row).into_string();
        assert!(html.contains(r#"data-index="7""#), "{html}");
        assert!(html.contains(r#"name="items[7][sku]""#), "{html}");
        // Exactly one row wrapper.
        assert_eq!(html.matches("nested-fields__row").count(), 1, "{html}");
    }

    // ── Fix 1: form_tag preserves the captured CSRF/submit-token fields ─

    /// `NestedChangesetForm::form_tag` must emit the CSRF hidden input under the
    /// **captured/configured** field name — NOT the standalone `form_tag`'s
    /// hardcoded `_csrf` — so an app with a custom `security.csrf.form_field`
    /// keeps CSRF parity across a nested re-render.
    #[test]
    fn form_tag_emits_custom_csrf_field_name_not_default() {
        let form = NestedChangesetForm::<Order, LineItem>::blank(
            Order {
                name: String::new(),
            },
            Some("tok-123".to_owned()),
        )
        .with_csrf_field("authenticity_token");

        let html = form
            .form_tag("/orders", "post", maud::html! {})
            .into_string();

        // The captured custom field name carries the token…
        assert!(
            html.contains(r#"name="authenticity_token" value="tok-123""#),
            "{html}"
        );
        // …and the hardcoded default the standalone `form_tag` would emit does not.
        assert!(!html.contains(r#"name="_csrf""#), "{html}");
        assert!(html.contains(r#"action="/orders""#), "{html}");
        assert!(html.contains(r#"method="post""#), "{html}");
    }

    /// When a submit token is captured, `form_tag` also emits it under its
    /// captured field name (alongside the custom CSRF field).
    #[test]
    fn form_tag_emits_captured_submit_token_field() {
        let form = NestedChangesetForm::<Order, LineItem> {
            changeset: NestedChangeset::blank(Order {
                name: String::new(),
            }),
            csrf_token: Some("tok".to_owned()),
            csrf_field: "authenticity_token".to_owned(),
            submit_token: Some("stok-9".to_owned()),
            submit_field: "_submit_token".to_owned(),
        };

        let html = form
            .form_tag("/orders", "post", maud::html! {})
            .into_string();

        assert!(
            html.contains(r#"name="authenticity_token" value="tok""#),
            "{html}"
        );
        assert!(
            html.contains(r#"name="_submit_token" value="stok-9""#),
            "{html}"
        );
        assert!(!html.contains(r#"name="_csrf""#), "{html}");
    }

    // ── Fix 2: blank render shows no premature parent errors ────────────

    /// The initial `new`-page render from `blank`: the required parent field is
    /// empty but un-validated, so no error message or `aria-invalid="true"`
    /// appears before the user types.
    #[test]
    fn blank_form_render_shows_no_parent_validation_error() {
        let form = NestedChangesetForm::<Order, LineItem>::blank(
            Order {
                name: String::new(),
            },
            Some("tok".to_owned()),
        );

        let html = form
            .form_tag(
                "/orders",
                "post",
                maud::html! {
                    (crate::form::required_text_input(&form.parent, "name", "Order name"))
                    (inputs_for(&*form, &InputsForOptions::default(), render_row))
                },
            )
            .into_string();

        assert!(!html.contains(r#"aria-invalid="true""#), "{html}");
        assert!(!html.contains("name required"), "{html}");
    }

    /// Contrast: a re-render from a failed decode DOES surface the parent error
    /// and marks the field invalid — the exact behaviour `blank` suppresses on
    /// the initial GET render.
    #[test]
    fn decoded_invalid_parent_render_shows_error_unlike_blank() {
        let cs =
            decode_nested_urlencoded::<Order, LineItem>(&[p("name", "")]).expect("parent decodes");
        let form = NestedChangesetForm::from_changeset(cs);

        let html = form
            .form_tag(
                "/orders",
                "post",
                maud::html! {
                    (crate::form::required_text_input(&form.parent, "name", "Order name"))
                },
            )
            .into_string();

        assert!(html.contains(r#"aria-invalid="true""#), "{html}");
        assert!(html.contains("name required"), "{html}");
    }

    // ── Fix 3: blank forms can carry the current submit token ───────────

    /// A `blank` form given a submit token (and a custom submit field name) emits
    /// the hidden submit-token input on the initial GET render, so the FIRST
    /// submission is protected against double-submit — not just later 422
    /// re-renders.
    #[test]
    fn blank_form_with_submit_token_emits_hidden_submit_field() {
        let form = NestedChangesetForm::<Order, LineItem>::blank(
            Order {
                name: String::new(),
            },
            Some("csrf".to_owned()),
        )
        .with_submit_field("authenticity_submit")
        .with_submit_token(Some("tok".to_owned()));

        let html = form
            .form_tag("/orders", "post", maud::html! {})
            .into_string();

        assert!(
            html.contains(r#"name="authenticity_submit" value="tok""#),
            "{html}"
        );
    }

    /// Without supplying a submit token, a `blank` form emits NO submit-token
    /// hidden input — documenting the default and that the caller must supply the
    /// minted token on the initial GET to protect the first submit.
    #[test]
    fn blank_form_without_submit_token_omits_submit_field() {
        let form = NestedChangesetForm::<Order, LineItem>::blank(
            Order {
                name: String::new(),
            },
            Some("csrf".to_owned()),
        );

        let html = form
            .form_tag("/orders", "post", maud::html! {})
            .into_string();

        assert!(!html.contains("_submit_token"), "{html}");
        assert!(!html.contains(r#"name="_submit_token""#), "{html}");
    }

    // ── seeded (edit-render) rendering ──────────────────────────────

    /// A `seeded` changeset pre-renders its existing children through
    /// `inputs_for`: each seeded row's inputs carry the child's serialized values
    /// so an edit form shows the current line items, and a trailing blank template
    /// row is still appended for adding another child with no JS.
    #[test]
    fn seeded_rows_render_with_prefilled_values() {
        let cs = NestedChangeset::seeded(
            Order {
                name: "Existing order".to_owned(),
            },
            vec![
                LineItem {
                    sku: "A-1".to_owned(),
                    quantity: 2,
                },
                LineItem {
                    sku: "B-2".to_owned(),
                    quantity: 3,
                },
            ],
        );
        let html = inputs_for(&cs, &InputsForOptions::default(), render_row).into_string();

        // Both seeded rows render their indexed inputs with pre-filled values.
        assert!(html.contains(r#"name="items[0][sku]""#), "{html}");
        assert!(html.contains(r#"value="A-1""#), "{html}");
        assert!(html.contains(r#"name="items[1][sku]""#), "{html}");
        assert!(html.contains(r#"value="B-2""#), "{html}");
        // The trailing blank template row is still appended (index 2).
        assert!(html.contains(r#"data-index="2""#), "{html}");
        assert!(html.contains(r#"name="items[2][sku]""#), "{html}");
    }
}