Files
scadaproj/components/ui-theme/validation/theme-1.0.0/field-busy.md
T

6.1 KiB

TH-03 / TH-05 — field associations and busy actions

Implementation checkpoint for the Theme 1.0.0 candidate. Source is in the managed scadaproj worktree on codex/scada-ui-consistency; this checkpoint does not publish the package or migrate consumers.

Additive component contracts

TechField now accepts optional nullable strings:

  • For: renders on the existing label as for; the caller assigns that id to its actual input/select/editor.
  • HintId: renders on the existing hint node when nonempty Hint content exists.
  • ErrorId: renders on the existing error node when nonempty Error content exists.

The wrapper does not inspect or modify arbitrary ChildContent. It does not generate ids, choose a control, synthesize invalid state, manage focus, or announce errors globally. Existing callers without the new parameters still render without for/description ids. Null or empty Hint/Error does not create a description node, even when an id parameter was supplied.

A caller with both help and a conditional validation error should wire its own control explicitly:

<TechField Label="Name" For="secret-name"
           Hint="Use a stable name" HintId="secret-name-hint"
           Error="@nameError" ErrorId="secret-name-error">
    <input id="secret-name" class="form-control" @bind="name"
           aria-describedby="@(string.IsNullOrEmpty(nameError)
               ? "secret-name-hint"
               : "secret-name-hint secret-name-error")"
           aria-invalid="@(string.IsNullOrEmpty(nameError) ? null : "true")" />
</TechField>

Keep ids stable and unique per form instance/row, including concurrently rendered or hidden forms. When the error clears, remove the error id from aria-describedby and clear aria-invalid; never reference absent description nodes. Existing custom control aria-labels and behavior remain caller-owned. The field-name example is synthetic and contains no secret value.

TechButton now accepts optional BusyText and explicitly renders aria-busy="true" or "false" from Busy. While Busy is true, nonempty BusyText replaces ChildContent; null/empty BusyText preserves the existing child content. When Busy becomes false, the original ChildContent returns. The spinner remains decorative (aria-hidden=true).

Busy continues to disable the control, combined with the existing caller-disabled semantics. Completing work does not enable an action that the caller independently disabled. Explicit Busy controls aria-busy even if an unmatched caller attribute contains stale busy text/state; existing Type, variant, size, class composition and click callback behavior remain intact.

An interactive caller can supply operation-specific pending text and its own persistent outcome region:

<TechButton Busy="@saving" BusyText="Saving changes…" @onclick="SaveAsync">
    Save changes
</TechButton>
<p role="status">@saveOutcome</p>

The owning form/operation still prevents duplicate submission, handles failures/cancellation and writes a concise success/failure outcome once. The button adds no global live region, no automatic success text and no retry. Do not put secret values or every polling update in an outcome region. Keep actionable validation/recovery inline; do not depend solely on expiring toasts. Static SSR login POST and antiforgery behavior are unchanged.

Actual verification

Working directory:

/Users/dohertj2/.codex/worktrees/scada-ui-consistency/scadaproj

Command executed before the component parameters existed, then again after implementation:

dotnet test ZB.MOM.WW.Theme/tests/ZB.MOM.WW.Theme.Tests/ZB.MOM.WW.Theme.Tests.csproj \
  -c Release --artifacts-path /tmp/theme-fields-artifacts \
  --filter 'FullyQualifiedName~TechFieldAssociationTests|FullyQualifiedName~TechButtonExtensionsTests|FullyQualifiedName~CommonControlsTests' \
  --logger 'trx;LogFileName=green.trx' \
  --results-directory components/ui-theme/validation/theme-1.0.0/fields-busy

The first run used red.trx and red.log: exit 1, with missing For/HintId/ErrorId/BusyText compile errors as expected. Concurrent TH-04 red tests also produced missing ThemeShell-parameter errors in that same compile; the log is retained honestly rather than attributing all compile errors to this task.

After both assigned components were implemented and TH-04 parameters existed, the focused run passed 28 tests, 0 failed, 0 skipped (exit 0):

  • Six new field cases: associations; null/empty descriptions; independent repeated fields; clearing an error without changing caller control content; backward-compatible callers without associations.
  • Four new busy cases: replacement/restoration plus click behavior; null/empty fallback; caller-disabled remains disabled and stale unmatched aria-busy cannot override component state.
  • Eighteen existing extension/common-control cases, including variants, size/class composition, Type, caller-disabled toggling and existing field/card behavior.

Evidence: red log, green log, green TRX. Output was isolated under /tmp/theme-fields-artifacts to avoid racing another agent's normal-output test run.

Impeccable detector ran once over the two changed Razor components: detector.json, empty findings, exit 0. git diff --check passed for the assigned existing files. No CSS, ThemeShell, README, task ledger or package version file was edited in this task. No commit was created.

Remaining acceptance boundaries

The parent integration pass owns the full Theme suite in its standard output layout. Existing static-asset tests resolve source files relative to standard test output, so this isolated filtered run does not claim full-suite acceptance.

No real consumer browser/session has been exercised for this checkpoint. bUnit proves the emitted relationships, pending-state text and existing component behavior; it does not prove actual label-click focus, screen-reader announcement quality, keyboard focus after slow success/failure, host style contrast or mobile composition. Those checks remain part of the two-host candidate pilots/G1. No package publication, deployment or consumer migration is claimed.