Drop the HTML5 required attribute once MudBlazor honours caller-supplied aria-required #263

Problem / motivation

#199 asked for aria-required="true" without the HTML5 required attribute — the accessibility
annotation without the browser-validation attribute the project's convention forbids. That turned out to
be unreachable on MudBlazor 9.8.0, so #199 shipped the compromise (option A): drive Required from
IsRequired and accept the HTML5 attribute.

Why it was unreachable. Decompiled from MudBlazor.dll 9.8.0 — MudInput<T>.BuildRenderTree:

// <input> branch                                    // <textarea> branch
AddMultipleAttributes(38, UserAttributes);           AddMultipleAttributes(15, UserAttributes);
...                                                  ...
AddAttribute(54, "required",      Required);         AddAttribute(30, "required",      Required);
AddAttribute(55, "aria-required", Required…);        AddAttribute(31, "aria-required", Required…);

The caller's UserAttributes splat lands before MudBlazor's own writes, and the Blazor render tree
resolves duplicate attributes last-write-wins. So a caller can never override aria-required, and one
bool drives both attributes together. Confirmed identical on 9.5.0, 9.7.0 and 9.8.0.

Why this is fixable rather than a fact of life. MudBlazor 9.7/9.8 added a helper that does exactly
what is needed — but wired it only to the hidden-input presenter <div>, not to the real input:

/// Caller-provided UserAttributes take precedence over the computed accessibility fallbacks.
private Dictionary<string, object?>? GetDisplayUserAttributes()
{
    var dictionary = new Dictionary<string, object>(UserAttributes, StringComparer.OrdinalIgnoreCase);
    dictionary.TryAdd("aria-required", Required.ToString().ToLowerInvariant());   // TryAdd → caller wins
    ...
}

And MudBlazor's own AGENTS.md:213 states the rule the ordinary render path violates:

When generating HTML or ARIA attributes in component code, prefer fallback values so caller-provided
attributes can override them whenever feasible; do not hard-force generated attributes unless the
behavior truly requires it.

Proposed solution

Upstream first, then revert the compromise here.

A verified patch already exists at /Users/philippe/repo/phmatray/public/mudblazor-aria-required.patch
(76 insertions, 10 deletions). It extends MudBlazor's own pattern to the real <input>/<textarea>:
aria-required, aria-invalid and aria-describedby move into a caller-wins dictionary
(GetInputUserAttributes()), while required deliberately stays bound to the parameter — which is
precisely what makes the pair separable.

Verified locally before filing:

Once a MudBlazor release carries it, FormCraft flips to Required="false" plus
aria-required="true" through UserAttributes, dropping the HTML5 attribute — which resolves the
CLAUDE.md convention tension #199 had to amend rather than satisfy.

Alternatives considered

• Stay on option A forever. Works today and is not broken — the HTML5 attribute is inert under the
  form's novalidate (novalidate is applied by script to the first form on the page, so the documented guarantee can miss #206). Rejected as the end state only because it required amending a documented
  convention to accommodate an upstream limitation, and because required still matches :required /
  :invalid in consumer CSS.
• Fork MudBlazor / ship a patched build. Rejected: enormous maintenance cost for two attributes.
• Post-render JS interop to strip required. Rejected: a JS dependency, invisible to bUnit, and
  fragile across re-renders — it would make the "no HTML5 attribute" claim untestable.
• Keep the annotation in the accessible name (append "(required)" to aria-label). This was option
  B during Required fields are not identified to assistive technology on either render path #199's triage. Rejected then and now: a text convention rather than the standard programmatic
  flag.

Area

FormCraft.ForMudBlazor — field rendering (both render paths), accessibility, upstream dependency

Follow-up from #199 (landed as #254). Related: #190, #204, #206, #203

⛔ Blocked on the upstream MudBlazor PR being opened, merged and released. The FormCraft-side work
in the plan below is small; the wait is not. Do not start it before a MudBlazor release carries the fix
— the tests would be red for reasons no code change here can address.

flowchart TD
    A["field.Required(\"…\")"] --> B{MudBlazor release<br/>honours caller ARIA?}
    B -->|"no — today"| C["Required=true<br/>aria-required=true + HTML5 required"]
    B -->|"yes — after upstream"| D["Required=false<br/>aria-required=true via UserAttributes"]
    D --> E["announced ✅<br/>no HTML5 attribute ✅<br/>no asterisk unless .WithNativeRequired()"]

🛠️ Implementation plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: land the upstream fix, then drop FormCraft's HTML5-attribute compromise.

Architecture: all FormCraft changes in FormCraft.ForMudBlazor; core untouched. Both render paths
change together or RenderPipelineParityTests fails — that is intended.

Tech stack: .NET 8 / 10 multi-target, Blazor, MudBlazor 9, xUnit + bUnit + Shouldly.

Global constraints:

• Base branch dev; commit as Philippe Matray <phmatray@gmail.com>; conventional commits.
• TreatWarningsAsErrors=true; dotnet test --filter is inert (MTP0001) — run the whole suite.
• ⛔ Task 1 is a hard gate. Tasks 2-4 cannot go green until a MudBlazor release carries the fix.
• Resolve the required flag through the single NativeRequired.Resolve(...) implementation (Required fields are not identified to assistive technology on either render path #199).
• .WithNativeRequired() must keep meaning "MudBlazor's native decoration", asterisk included.

Task 1: Open the upstream MudBlazor PR

Files: none in this repo. The patch is at /Users/philippe/repo/phmatray/public/mudblazor-aria-required.patch.

Interfaces: MudInput.GetInputUserAttributes() — caller-wins fallbacks for aria-required, aria-invalid, aria-describedby.

• Step 1: Fork MudBlazor/MudBlazor, branch from dev, apply the patch with git apply.
• Step 2: Run their build and the affected suites → confirm 0 warnings and the ~681 component tests green, and that the two new tests fail with the production hunk reverted.
• Step 3: Open the PR, citing AGENTS.md:213 and the existing GetDisplayUserAttributes() precedent, and stating the consumer case (server-side validation with novalidate).
• Step 4: Record the upstream PR URL in a comment on this issue.
• Step 5: Wait for merge + release. Stop here until then — nothing below can pass.

Task 2: Raise the MudBlazor pin

Files: modify Directory.Packages.props.

Interfaces: none.

• Step 1: Bump MudBlazor to the first release carrying the fix.
• Step 2: Run dotnet build -c Release and dotnet test -c Release → both green on the existing behaviour, proving the bump alone changes nothing.
• Step 3: Commit: build(deps): raise MudBlazor to <version> for caller-overridable ARIA.

Task 3: Flip both render paths to the ARIA-only mechanism

Files: modify FormCraft.ForMudBlazor/Fields/MudBlazorFieldComponentBase.cs; modify FormCraft.ForMudBlazor/Features/CollectionField/CollectionFieldComponent.razor.cs; modify AriaRequiredTests.cs and CollectionRequiredTests.cs.

Interfaces: the inference contributes aria-required via UserAttributes; MudBlazor's Required parameter is reserved for the explicit .WithNativeRequired() opt-in.

• Step 1: Write the failing tests: a .Required(...) field renders aria-required="true" and no required attribute, on both paths, for text, numeric, date and select.
• Step 2: Run the suite → FAIL (the HTML5 attribute is still present).
• Step 3: Split the resolution — keep NativeRequired.Resolve(...) for the explicit opt-in driving Required, and route the IsRequired inference into an aria-required user attribute on both paths.
• Step 4: Decide the asterisk question from the spec explicitly — either render a FormCraft-owned marker or accept its loss for plain .Required(...) fields — and pin the decision with a test.
• Step 5: Invert the CollectionRequiredTests cases that assert the HTML5 attribute's presence (they were inverted the other way by Required fields are not identified to assistive technology on either render path #199).
• Step 6: Run the suite → PASS, whole suite green.
• Step 7: Commit: feat(mudblazor): announce required fields without the HTML5 required attribute.

Task 4: Restore the convention wording and document

Files: modify CLAUDE.md; modify README.md; modify FormCraft.ForMudBlazor/Extensions/FieldBuilderExtensions.cs (WithNativeRequired XML doc).

Interfaces: none new.

• Step 1: Restore CLAUDE.md's validation convention to its literal form — Required() adds validation but not the HTML5 attribute — noting that ARIA annotation is separate and now independently achievable.
• Step 2: Add a README ## 🎉 Unreleased bullet explaining that the HTML5 attribute is gone again, what it means for the asterisk, and that .WithNativeRequired() restores native semantics.
• Step 3: Update WithNativeRequired's XML doc — the Level A warning on false still applies, but the "why the HTML5 attribute comes back" paragraph becomes historical.
• Step 4: Run dotnet build -c Release and dotnet test -c Release → both green.
• Step 5: Commit: docs: restore the validation convention now ARIA is independent.