gina 0.6.3 → 0.6.4

package/framework/{v0.6.3 → v0.6.4}/core/plugins/lib/validator/src/main.js

@@ -106,6 +106,7 @@ function ValidatorPlugin(rules, data, formId, culture) {
     var FormValidator   = (isGFFCtx) ? require('lib/form-validator') : require('./form-validator');
     //var Collection      = (isGFFCtx) ? require('lib/collection') : require('../../../../../lib/collection');
     var routing         = (isGFFCtx) ? require('lib/routing') : require('../../../../../lib/routing');
+    var loadingState    = (isGFFCtx) ? require('lib/loading-state') : require('../../../../../lib/loading-state');
 
 
     /** definitions */
@@ -790,9 +791,14 @@ function ValidatorPlugin(rules, data, formId, culture) {
                 if (isErrorMessageHidden) {
                     // hide error messages
                     $children[c].className = $children[c].className +' hidden';
+                    // #A11Y5 — this hide fires when the field regains focus, and it does not
+                    // touch aria-invalid: a committed error stays asserted while its message
+                    // would otherwise leave the a11y tree. Clip it instead.
+                    clipErrorMessage($children[c]);
                 } else {
                     // display error messages
                     $children[c].className = $children[c].className.replace(/(\s+hidden|hidden)/, '');
+                    revealErrorMessage($children[c]);
                 }
                 break
             }
@@ -800,17 +806,38 @@ function ValidatorPlugin(rules, data, formId, culture) {
     }
 
     /**
-     * #A11Y1 (slice 4) — lazily create one visually-hidden aria-live="polite" status region per
-     * form and announce a blur-time committed error through it. A CSS :user-invalid display toggle
-     * is not reliably announced by screen readers, and on blur the field has lost focus so its own
-     * aria-invalid / aria-errormessage are not re-read; the polite region decouples the announcement
-     * from visual display. Submit-time errors use focus (see onValidate), not this region.
+     * #A11Y2 — create (or recover) a form's visually-hidden polite status region WITHOUT
+     * writing to it. Split out of announceA11yError so the region can exist LONG before the
+     * first error: a region that is inserted and populated in the same tick reaches assistive
+     * tech as a single mutation batch, which is commonly never spoken, so the very first
+     * announcement per form — the one that matters most — was the one most likely lost.
+     * bindForm calls this at bind time, which is what makes that first error audible.
+     *
+     * The region is a CHILD OF THE FORM deliberately. A popin renders its form inside a native
+     * `<dialog>` opened with showModal(), which leaves everything outside the top layer inert;
+     * a body-level region would sit in that inert subtree and go unspoken for exactly the forms
+     * that live in popins. Keeping it inside the form keeps it inside the dialog. The price is
+     * that a subtree replacement (a popin re-render's `innerHTML =`, or a nav fragment swap)
+     * destroys it — hence create-OR-RECOVER, and hence the deferred first write in
+     * announceA11yError, which is what stops a recovery from silently repeating the defect.
+     *
+     * The bookkeeping flag lives on the element rather than in a module-scope map so it dies
+     * WITH the region: a destroyed region leaves no stale entry behind, and no form id keeps
+     * an unbounded map alive. Browser-only, like readCsrfCookie — this engine is shared with
+     * the server form-body path, which has no document.
+     *
+     * @inner
      * @param {object} $form - the HTMLFormElement the region belongs to
-     * @param {string} text - the error text to announce
-     * @returns {object|null} the live-region element, or null when nothing was announced
+     * @returns {object|null} the live-region element, or null outside a browser document
+     * @example
+     * // at bind time: the region is in the a11y tree before any error can occur
+     * ensureA11yLiveRegion($form.target);
      */
-    var announceA11yError = function($form, text) {
-        if ( !$form || !text ) return null;
+    var ensureA11yLiveRegion = function($form) {
+        if ( !$form ) return null;
+        if ( typeof(document) === 'undefined' || !document || typeof(document.getElementById) !== 'function' ) {
+            return null;
+        }
         var _fid    = ( typeof($form.id) != 'undefined' && $form.id ) ? $form.id : ( $form.getAttribute('id') || 'form' );
         var _liveId = 'gina-aria-live-' + _fid;
         var _live   = document.getElementById(_liveId);
@@ -822,8 +849,55 @@ function ValidatorPlugin(rules, data, formId, culture) {
             _live.setAttribute('aria-atomic', 'true');
             _live.className = 'gina-visually-hidden';
             _live.style.cssText = 'position:absolute;width:1px;height:1px;margin:-1px;padding:0;overflow:hidden;clip:rect(0 0 0 0);white-space:nowrap;border:0;';
+            _live.ginaA11yFresh = true;
+            $form.appendChild(_live);
+        } else if ( _live.parentNode !== $form ) {
+            // Same id, different form node — a re-render replaced the form, or two forms share
+            // an id. Re-home it so the region always sits inside the form that announces, which
+            // is the property the inert reasoning above depends on; a move is a fresh insertion.
+            _live.ginaA11yFresh = true;
             $form.appendChild(_live);
         }
+        return _live;
+    };
+
+    /**
+     * #A11Y1 (slice 4) — announce a blur-time committed error through the region created at
+     * bind time. A CSS :user-invalid display toggle is not reliably announced by screen
+     * readers, and on blur the field has lost focus so its own aria-invalid /
+     * aria-errormessage are not re-read; the polite region decouples the announcement
+     * from visual display. Submit-time errors use focus (see onValidate), not this region.
+     *
+     * #A11Y2 — when the region had to be created (or re-homed) HERE rather than at bind time,
+     * the insertion and this write would land in the same tick and likely never be spoken, so
+     * that first write is deferred by one macrotask. Only the fresh case defers; an already
+     * bound region writes synchronously, exactly as before. While a deferred write is pending
+     * a later call replaces the pending text, so the LATEST error wins and a stale first
+     * message can never land on top of it. The timer re-enters this function, which then takes
+     * the synchronous branch — keeping exactly ONE textContent write site.
+     *
+     * @param {object} $form - the HTMLFormElement the region belongs to
+     * @param {string} text - the error text to announce
+     * @returns {object|null} the live-region element, or null when nothing was announced
+     * @example
+     * announceA11yError($form, 'This field is required');
+     */
+    var announceA11yError = function($form, text) {
+        if ( !$form || !text ) return null;
+        var _live = ensureA11yLiveRegion($form);
+        if ( !_live ) return null;
+        if ( _live.ginaA11yFresh ) {
+            _live.ginaA11yPending = text;
+            if ( !_live.ginaA11yTimer ) {
+                _live.ginaA11yTimer = setTimeout(function() {
+                    _live.ginaA11yTimer = null;
+                    _live.ginaA11yFresh = false;
+                    announceA11yError($form, _live.ginaA11yPending);
+                }, 0);
+            }
+            return _live;
+        }
+        text = a11yDistinctText(_live, text);
         _live.textContent = text;
         return _live;
     };
@@ -851,6 +925,179 @@ function ValidatorPlugin(rules, data, formId, culture) {
         return parts.join('. ');
     };
 
+    /**
+     * A11Y_LABELS — English defaults for gina's own accessibility status strings.
+     *
+     * Deliberately separate from `setErrorLabels`, which owns per-culture overrides
+     * for *rule* error labels and is keyed by rule name. These are framework-authored
+     * announcements about what gina is doing, so they need a home of their own.
+     *
+     * `%s` in a value is replaced with a runtime detail (currently the file name);
+     * it follows the same placeholder convention the rule error labels already use,
+     * so a translation keeps control of where the detail lands in the sentence.
+     *
+     * @constant {object}
+     * @inner
+     */
+    var A11Y_LABELS = {
+        submitting      : 'Submitting…',
+        // #A11Y7/U2 — staged uploads announce only their TRANSITIONS (start and
+        // success), never per-tick progress: `aria-live="polite"` coalesces but does
+        // not throttle, and one announcement per onprogress event would bury every
+        // other message on the page. There is deliberately NO `uploadError` key —
+        // the error path announces the server's own message instead (#A11Y7/U3), and
+        // a generic second write in the same beat would clobber it (see the rationale
+        // on `releaseSubmitA11y`).
+        uploadStarted   : 'Upload started',
+        uploadComplete  : 'Upload complete',
+        // #A11Y7/U5 — spoken when a staged file's reset/delete control removes it.
+        fileRemoved     : '%s removed'
+    };
+
+    /**
+     * a11yLabel — resolve one accessibility status string.
+     *
+     * Follows the same philosophy `setErrorLabels` documents: an English default
+     * ships inline and fills anything the project does not translate. A project
+     * overrides by assigning `gina.config.a11y`, typically once at boot keyed off
+     * the negotiated culture.
+     *
+     * @param   {string} key - Label key, e.g. `submitting`.
+     * @returns {string} the project's override when it supplies a non-empty string,
+     *                   otherwise the English default (empty string for unknown keys).
+     *
+     * @example
+     * // project side, once at boot:
+     * gina.config.a11y = { submitting: 'Envoi…' };
+     *
+     * @inner
+     */
+    var a11yLabel = function(key) {
+        var _over = ( typeof(gina) != 'undefined' && gina && gina.config && gina.config.a11y )
+            ? gina.config.a11y
+            : null;
+        if ( _over && typeof(_over[key]) == 'string' && _over[key] ) {
+            return _over[key];
+        }
+        return A11Y_LABELS[key] || '';
+    };
+
+    /**
+     * announceA11yStatus — announce a non-error status through the form's region.
+     *
+     * The region #A11Y2 stands up at bind time is `role="status" aria-live="polite"`,
+     * i.e. already a status channel rather than an error-only one — so submit progress
+     * rides that same element instead of a second region competing with it. Kept as a
+     * named delegate purely so call sites read as status, not as errors.
+     *
+     * @param   {object} $form - form target (HTMLFormElement), not the form instance.
+     * @param   {string} text  - resolved, human-readable status text.
+     * @returns {object|null} the live region, or null when it could not be resolved.
+     *
+     * @example
+     * announceA11yStatus($myForm, 'Envoi…');
+     *
+     * @inner
+     */
+    var announceA11yStatus = function($form, text) {
+        return announceA11yError($form, text);
+    };
+
+    /**
+     * a11yDistinctText — make a repeated announcement observably new.
+     *
+     * An `aria-live="polite"` region is announced when its content CHANGES, so re-writing
+     * byte-identical text is commonly not spoken at all. That is the normal case for a
+     * validation message: blurring a field that still fails the same rule produces exactly
+     * the same string, and the user heard nothing the second time. Appending a no-break
+     * space makes the node's content differ while leaving what is read out unchanged, and
+     * it self-cancels — the next identical announcement compares against the suffixed text,
+     * differs, and writes the clean string again.
+     *
+     * Lives outside `announceA11yError` deliberately: that function sits inside a fixed
+     * character window asserted by a source pin, and the rationale above does not fit in it.
+     *
+     * ⚠️ Unverified: that a screen reader actually re-announces as a result. The string
+     * demonstrably changes; no assistive-technology pass has been run to confirm the effect.
+     *
+     * @param   {object} $live - the live region node.
+     * @param   {string} text  - the announcement about to be written.
+     * @returns {string} `text`, suffixed only when it would otherwise be a no-op write.
+     *
+     * @example
+     * var next = a11yDistinctText($region, 'This field is required');
+     *
+     * @inner
+     */
+    var a11yDistinctText = function($live, text) {
+        if ( !$live || typeof(text) != 'string' ) {
+            return text;
+        }
+        return ( $live.textContent === text ) ? text + ' ' : text;
+    };
+
+    /**
+     * ERR_MSG_CLIP — inline declarations that hide an element from VIEW while leaving it
+     * in the accessibility tree.
+     *
+     * `display` carries `!important` because gina's own `.hidden` helper is
+     * `display: none !important`, and an inline `!important` is what outranks it (measured:
+     * a plain inline `display:block` loses to it). The class is deliberately left in place
+     * so consumer CSS keyed on `.hidden` keeps matching.
+     *
+     * @constant {string}
+     * @inner
+     */
+    var ERR_MSG_CLIP = 'display:block !important;position:absolute;width:1px;height:1px;'
+        + 'margin:-1px;padding:0;overflow:hidden;clip:rect(0 0 0 0);white-space:nowrap;border:0;';
+
+    /**
+     * clipErrorMessage — hide a validation message visually, but keep it reachable.
+     *
+     * `.hidden` is `display: none !important`, which removes the node from the
+     * accessibility tree outright. That is the wrong tool wherever `aria-invalid="true"`
+     * stays asserted on the field, because the `aria-errormessage` association then points
+     * assistive tech at a target it cannot resolve — the field is announced invalid with no
+     * retrievable reason. Both hide paths that can coexist with an asserted `aria-invalid`
+     * (the focus-driven hide in `refreshWarning`, and the refresh re-create) clip instead.
+     *
+     * gina creates and owns this element, so replacing `style.cssText` wholesale is safe.
+     *
+     * @param   {object} $err - the `form-item-error-message` element.
+     * @returns {boolean} true when the clip was applied.
+     *
+     * @example
+     * clipErrorMessage($someMessageDiv);
+     *
+     * @inner
+     */
+    var clipErrorMessage = function($err) {
+        if ( !$err || typeof($err.style) == 'undefined' || !$err.style ) {
+            return false;
+        }
+        $err.style.cssText = ERR_MSG_CLIP;
+        return true;
+    };
+
+    /**
+     * revealErrorMessage — undo `clipErrorMessage`, restoring normal visual flow.
+     *
+     * @param   {object} $err - the `form-item-error-message` element.
+     * @returns {boolean} true when the clip was cleared.
+     *
+     * @example
+     * revealErrorMessage($someMessageDiv);
+     *
+     * @inner
+     */
+    var revealErrorMessage = function($err) {
+        if ( !$err || typeof($err.style) == 'undefined' || !$err.style ) {
+            return false;
+        }
+        $err.style.cssText = '';
+        return true;
+    };
+
     /**
      * handleErrorsDisplay
      * Attention: if you are going to handle errors display by hand, set data to `null` to prevent Toolbar refresh with empty data
@@ -1146,6 +1393,14 @@ function ValidatorPlugin(rules, data, formId, culture) {
                         // global pass, so without this focus guard it re-shows the message mid-typing.
                         // On blur (field no longer active) the message is created shown (focusout commits).
                         $err.setAttribute('class', ( document.activeElement && document.activeElement.name == name ) ? 'form-item-error-message hidden' : 'form-item-error-message');
+                        // #A11Y5 — the branch below re-asserts aria-invalid="true" on this same
+                        // field, so when the message is hidden it must stay resolvable: clip it
+                        // out of view rather than out of the accessibility tree. Reads the class
+                        // just written instead of re-deriving the condition, so the ternary above
+                        // stays exactly as pinned.
+                        if ( /hidden/.test($err.className) ) {
+                            clipErrorMessage($err);
+                        }
 
                         // #A11Y1 (slice 2) — preserve the aria-errormessage wire we own across refresh.
                         if ( _ginaOwnsErrMsg && _ariaErrId ) {
@@ -1475,6 +1730,231 @@ function ValidatorPlugin(rules, data, formId, culture) {
     }
 
 
+    /**
+     * armSubmitLoading
+     *
+     * Marks `$trigger` as running (`data-gina-loading="true"`, or whatever
+     * `gina.config.loadingAttribute` names) and remembers it on the form instance so
+     * every terminal path can release it — including the ones that never reach an
+     * XHR and therefore have no `$submitTrigger` of their own in scope.
+     *
+     * The element is stashed rather than re-derived because the two are NOT always
+     * the same: `send()` resolves `$submitTrigger` once from `$form.submitTrigger`
+     * (an id) at its own entry, which a rejected submit never reaches, and which a
+     * second click on a different button would have overwritten by then. The stash
+     * is a single reference per form, replaced on each arm and nulled on disarm, so
+     * it can not retain a detached node past the submit that created it.
+     *
+     * @param {object} $formInstance - the form instance (`instance.$forms[id]`)
+     * @param {object} $trigger - the element the user operated
+     *
+     * @returns {boolean} true when the trigger was marked
+     *
+     * FIRST ARM WINS until the state is released. A form runs one submit at a time — that
+     * is what `withRateLimit` enforces — so a second attempt arriving mid-flight is about
+     * to be refused, and must not take ownership: on a form with several submit buttons it
+     * would move the stash to the refused trigger, leaving the trigger that actually owns
+     * the request armed with nothing left to release it.
+     *
+     * @example
+     * armSubmitLoading(instance.$forms[$form.id], loadingState.resolveTrigger($el, $target));
+     *
+     * @inner
+     */
+    var armSubmitLoading = function($formInstance, $trigger) {
+        if ( !$formInstance || !$trigger ) {
+            return false;
+        }
+        if ($formInstance.loadingTrigger) {
+            return false;
+        }
+        $formInstance.loadingTrigger = $trigger;
+        return loadingState.arm($trigger);
+    };
+
+    /**
+     * disarmSubmitLoading
+     *
+     * Releases whatever `armSubmitLoading` marked for this form
+     * (`data-gina-loading="false"`) and drops the stash. Idempotent and safe to call
+     * on a form that was never armed — every terminal path calls it unconditionally
+     * rather than trying to work out whether arming happened.
+     *
+     * #B247: the validation-rejected path is the one that stranded consumer loading
+     * state, because a rejected submit sends nothing and so never reaches any XHR
+     * settle. `send()`'s rate-limit early return is the same shape and is covered
+     * too; `loadend` covers success, error, timeout and abort alike.
+     *
+     * @param {object} $formInstance - the form instance (`instance.$forms[id]`)
+     *
+     * @returns {boolean} true when a marked trigger was released
+     *
+     * @example
+     * disarmSubmitLoading(instance.$forms[_id]); // on reject, settle, timeout or abort
+     *
+     * @inner
+     */
+    var disarmSubmitLoading = function($formInstance) {
+        if ( !$formInstance || !$formInstance.loadingTrigger ) {
+            return false;
+        }
+        var released = loadingState.disarm($formInstance.loadingTrigger);
+        $formInstance.loadingTrigger = null;
+        return released;
+    };
+
+    /**
+     * holdTriggerFocus — remember the submit trigger gina is about to blur.
+     *
+     * A natively `disabled` control cannot hold focus: the instant gina disables an
+     * in-flight submit trigger the browser moves focus to `<body>`, and re-enabling
+     * does not bring it back (both measured). Every keyboard submit therefore loses
+     * the user's place. Only the native-`disabled` branch is recorded — an `<a>`
+     * receives `aria-disabled`, which does not blur (measured), so it needs no restore.
+     *
+     * @param   {object} $form    - the form instance, which carries the stash.
+     * @param   {object} $trigger - resolved submit trigger; may be null.
+     * @returns {boolean} true when focus was captured for a later restore.
+     *
+     * @example
+     * holdTriggerFocus($myFormInstance, $mySaveButton);
+     *
+     * @inner
+     */
+    var holdTriggerFocus = function($form, $trigger) {
+        if ( !$form || !$trigger ) {
+            return false;
+        }
+        if ( typeof(document) === 'undefined' || !document ) {
+            return false;
+        }
+        if ( document.activeElement !== $trigger ) {
+            return false;
+        }
+        $form.ginaA11yFocusReturn = $trigger;
+        return true;
+    };
+
+    /**
+     * releaseTriggerFocus — put focus back on the trigger gina blurred.
+     *
+     * Deliberately conservative: it restores ONLY when focus is still exactly where
+     * the disable dropped it (`<body>`) and the trigger is still in the document. If
+     * anything else claimed focus while the request was in flight — a popin opened, a
+     * redirect ran, the failed-submit branch moved focus to the first invalid field —
+     * that decision wins and gina undoes nothing. gina restores what gina took, never
+     * more.
+     *
+     * @param   {object} $form - the form instance holding the stash.
+     * @returns {boolean} true when focus was actually restored.
+     *
+     * @example
+     * releaseTriggerFocus($myFormInstance);
+     *
+     * @inner
+     */
+    var releaseTriggerFocus = function($form) {
+        if ( !$form || !$form.ginaA11yFocusReturn ) {
+            return false;
+        }
+        var $trigger = $form.ginaA11yFocusReturn;
+        $form.ginaA11yFocusReturn = null;
+        if ( typeof(document) === 'undefined' || !document ) {
+            return false;
+        }
+        // Nothing else may have claimed focus in the meantime.
+        if ( document.activeElement && document.activeElement !== document.body ) {
+            return false;
+        }
+        var _stillThere = ( typeof($trigger.isConnected) == 'boolean' )
+            ? $trigger.isConnected
+            : ( document.body && document.body.contains($trigger) );
+        if ( !_stillThere || typeof($trigger.focus) != 'function' ) {
+            return false;
+        }
+        $trigger.focus();
+        return true;
+    };
+
+    /**
+     * armSubmitA11y — expose an in-flight submit to assistive technology.
+     *
+     * Three things at once, all scoped to the request window: capture the trigger's
+     * focus before the caller's native disable blurs it, mark the trigger busy, and
+     * announce the start once through the form's polite region.
+     *
+     * Two placement decisions worth keeping:
+     * - `aria-busy` goes on the TRIGGER, never the form. The live region lives inside
+     *   the form, and an ancestor marked busy MAY be treated as "defer announcements in
+     *   this subtree", which would silence the very region used to announce. ARIA 1.2
+     *   defines no normative behaviour here, so this is a cheap hedge, not a spec
+     *   requirement — and it is explicitly NOT a claim about what implementations do:
+     *   measured 2026-08-05 on VoiceOver/Chrome, an announcement from inside an
+     *   `aria-busy="true"` ancestor WAS spoken, so at least that pairing does not defer.
+     *   The placement costs nothing and still guards ATs that might; do not restate it
+     *   as "assistive tech commonly defers" — that wording was wrong and was corrected.
+     * - This window is only ever reached once a request is genuinely in flight, so a
+     *   validation-rejected submit never arms and never announces. That is what keeps
+     *   the arm-before-validate loading state from producing a busy/not-busy flap.
+     *
+     * @param   {object} $form    - the form instance.
+     * @param   {object} $trigger - resolved submit trigger; may be null.
+     * @returns {boolean} true when this call produced the announcement.
+     *
+     * @example
+     * armSubmitA11y($myFormInstance, $mySaveButton);
+     *
+     * @inner
+     */
+    var armSubmitA11y = function($form, $trigger) {
+        if ( !$form ) {
+            return false;
+        }
+        if ($trigger) {
+            if ( !/^A$/i.test($trigger.tagName) ) {
+                holdTriggerFocus($form, $trigger);
+            }
+            $trigger.setAttribute('aria-busy', 'true');
+        }
+        // readyState 1 and 3 both reach here; announce once per request.
+        if ( $form.ginaA11yBusy ) {
+            return false;
+        }
+        $form.ginaA11yBusy = true;
+        if ( $form.target ) {
+            announceA11yStatus($form.target, a11yLabel('submitting'));
+        }
+        return true;
+    };
+
+    /**
+     * releaseSubmitA11y — clear the in-flight submit exposure.
+     *
+     * Idempotent, because both the readyState-4 release and the `loadend` fail-safe
+     * run it. Deliberately announces nothing on completion: an errored response is
+     * already announced field-by-field by `handleErrorsDisplay`, and writing a second
+     * status over a polite region in the same beat can cut that announcement off.
+     *
+     * @param   {object} $form    - the form instance.
+     * @param   {object} $trigger - resolved submit trigger; may be null.
+     * @returns {boolean} true when focus was restored to the trigger.
+     *
+     * @example
+     * releaseSubmitA11y($myFormInstance, $mySaveButton);
+     *
+     * @inner
+     */
+    var releaseSubmitA11y = function($form, $trigger) {
+        if ( !$form ) {
+            return false;
+        }
+        if ($trigger) {
+            $trigger.removeAttribute('aria-busy');
+        }
+        $form.ginaA11yBusy = false;
+        return releaseTriggerFocus($form);
+    };
+
     /**
      * send
      * N.B.: no validation here; if you want to validate against rules, use `.submit()` or `.validateFormById(formId)` before
@@ -1509,6 +1989,11 @@ function ValidatorPlugin(rules, data, formId, culture) {
             && typeof($form.sent) != 'undefined'
             && /^true$/i.test($form.sent)
         ) {
+            // #B247 — deliberately NO loading-state release here. This return means a
+            // request for this form is already in flight, so the trigger that owns it is
+            // still legitimately loading and its own settle will release it. Releasing
+            // here would clear the state mid-request; and because `armSubmitLoading` is
+            // first-wins, the refused attempt never armed anything of its own to clear.
             return;
         }
 
@@ -1664,12 +2149,20 @@ function ValidatorPlugin(rules, data, formId, culture) {
                         }
                     }
                     $form.target.removeAttribute('data-gina-form-loading');
+                    // #B247 — the trigger-scoped release rides the same fail-safe:
+                    // `loadend` is the one hook that covers abort and error too.
+                    disarmSubmitLoading($form);
+                    // #A11Y4 — last, so focus lands on a trigger that is fully settled:
+                    // re-enabled above and no longer flagged loading.
+                    releaseSubmitA11y($form, $submitTrigger);
                 });
             }
             // catching ready state cb
             // Data loading ...
             if ( /^(1|3)$/.test(xhr.readyState) ) {
                 $form.target.setAttribute('data-gina-form-loading', true);
+                // #A11Y4 — must run BEFORE the native disable below, which blurs the trigger.
+                armSubmitA11y($form, $submitTrigger);
                 if ($submitTrigger) {
                     // For A tag: aria-disabled=true
                     if ( /^A$/i.test($submitTrigger.tagName) ) {
@@ -1698,6 +2191,8 @@ function ValidatorPlugin(rules, data, formId, culture) {
                 // Data loading ...
                 if ( /^(1|3)$/.test(xhr.readyState) ) {
                     $form.target.setAttribute('data-gina-form-loading', true);
+                    // #A11Y4 — must run BEFORE the native disable below, which blurs the trigger.
+                    armSubmitA11y($form, $submitTrigger);
                     if ($submitTrigger) {
                         // For A tag: aria-disabled=true
                         if ( /^A$/i.test($submitTrigger.tagName) ) {
@@ -1732,6 +2227,11 @@ function ValidatorPlugin(rules, data, formId, culture) {
                         }
                     }
                     $form.target.removeAttribute('data-gina-form-loading');
+                    // #B247 — idempotent with the `loadend` release above
+                    disarmSubmitLoading($form);
+                    // #A11Y4 — last, so focus lands on a fully settled trigger; idempotent
+                    // with the `loadend` release, which may already have restored it.
+                    releaseSubmitA11y($form, $submitTrigger);
 
                     var $popin          = null;
                     var blob            = null;
@@ -2510,7 +3010,16 @@ function ValidatorPlugin(rules, data, formId, culture) {
      *   computable) so the browser renders its native indeterminate animation;
      *   `error` empties the bar (value 0 — NOT indeterminate, whose animation
      *   would read as still working)
-     * - any other element: `textContent` shows the integer percentage (`42%`)
+     * - any other element: `textContent` shows the integer percentage (`42%`), and
+     *   `role="progressbar"` + `aria-valuemin="0"` / `aria-valuemax="100"` /
+     *   `aria-valuenow="<percent>"` give it the semantics a native `<progress>` gets
+     *   for free (#A11Y7/U2 — without them the indicator is unlabelled text to
+     *   assistive tech). `aria-valuenow` tracks `data-gina-upload-progress` exactly:
+     *   both are ABSENT while indeterminate and on `error`, because an absent
+     *   `aria-valuenow` is how a progressbar signals "unknown" — a stale or zero
+     *   value would read as real, stalled progress. A native `<progress>` is left
+     *   untouched: it already exposes all of this, and a redundant explicit role
+     *   risks overriding the implicit one.
      *
      * Every target also carries two data attributes as styling hooks:
      * `data-gina-upload-progress` (integer percent, absent while indeterminate)
@@ -2546,10 +3055,28 @@ function ValidatorPlugin(rules, data, formId, culture) {
             }
             $indicator.removeAttribute('data-gina-upload-progress');
             $indicator.removeAttribute('data-gina-upload-progress-state');
+            // #A11Y7/U2 — `reset` strips everything this layer ever set, and the ARIA
+            // below is part of "everything": leaving a stale `role="progressbar"` on a
+            // cleared element would expose a permanently 0%-looking bar to assistive tech.
+            if (!isNativeProgress) {
+                $indicator.removeAttribute('role');
+                $indicator.removeAttribute('aria-valuemin');
+                $indicator.removeAttribute('aria-valuemax');
+                $indicator.removeAttribute('aria-valuenow');
+            }
             return;
         }
 
         $indicator.setAttribute('data-gina-upload-progress-state', state);
+        // #A11Y7/U2 — a native <progress> already carries implicit progressbar
+        // semantics (and its own value/max), so it is deliberately left alone; every
+        // other element is text with no role at all until we give it one. The bounds
+        // are constant because `data-gina-upload-progress` is already a percentage.
+        if (!isNativeProgress) {
+            $indicator.setAttribute('role', 'progressbar');
+            $indicator.setAttribute('aria-valuemin', '0');
+            $indicator.setAttribute('aria-valuemax', '100');
+        }
 
         if (state == 'processing') {
             // #R8 — byte-complete, server still post-processing. Advance the STATE only:
@@ -2571,6 +3098,9 @@ function ValidatorPlugin(rules, data, formId, culture) {
                 $indicator.textContent = '100%';
             }
             $indicator.setAttribute('data-gina-upload-progress', 100);
+            if (!isNativeProgress) {
+                $indicator.setAttribute('aria-valuenow', '100');
+            }
             return;
         }
 
@@ -2584,6 +3114,13 @@ function ValidatorPlugin(rules, data, formId, culture) {
                 $indicator.textContent = '';
             }
             $indicator.removeAttribute('data-gina-upload-progress');
+            // #A11Y7/U2 — an errored bar is EMPTY, not indeterminate (the native branch
+            // above says the same about `value`): drop `aria-valuenow` so assistive tech
+            // reports an unknown state rather than a confident 0% that reads as "no
+            // progress yet, still working".
+            if (!isNativeProgress) {
+                $indicator.removeAttribute('aria-valuenow');
+            }
             return;
         }
 
@@ -2592,6 +3129,12 @@ function ValidatorPlugin(rules, data, formId, culture) {
                 $indicator.removeAttribute('value'); // native indeterminate animation
             }
             $indicator.removeAttribute('data-gina-upload-progress');
+            // #A11Y7/U2 — mirrors the `value` removal above: an absent `aria-valuenow`
+            // on a progressbar IS the indeterminate signal, so this must track the
+            // percent attribute exactly rather than reporting a stale last-known value.
+            if (!isNativeProgress) {
+                $indicator.removeAttribute('aria-valuenow');
+            }
             return;
         }
 
@@ -2601,6 +3144,7 @@ function ValidatorPlugin(rules, data, formId, culture) {
             $indicator.value    = result.loaded;
         } else {
             $indicator.textContent = result.progress + '%';
+            $indicator.setAttribute('aria-valuenow', result.progress);
         }
         $indicator.setAttribute('data-gina-upload-progress', result.progress);
     };
@@ -2815,9 +3359,27 @@ function ValidatorPlugin(rules, data, formId, culture) {
 
             $error.innerHTML = '<p>'+ errMsg +'</p>';
             fadeIn($error);
+            // #A11Y7/U3 — the container is `display:none` when the text is written and
+            // only revealed by the fadeIn above, which is exactly the case where a
+            // `role="alert"` on it is unreliable; route through the form's own polite
+            // region instead — the same channel field validation errors already use.
+            // Announce the RENDERED text, not `errMsg`: the message can carry markup
+            // (the url-action checker substitutes `<br>`), and textContent is what a
+            // user would actually read.
+            if ( $uploadTriger && $uploadTriger.form ) {
+                announceA11yError($uploadTriger.form, $error.textContent);
+            }
         } else if(!$error && status != 'success') {
             throw new Error(errMsg)
         } else {
+            // #A11Y7/U2 — success is the other end of the `uploadStarted` transition.
+            // It lives in this branch rather than at the indicator chokepoint above so
+            // it can never fire alongside the error announcement and overwrite it: a
+            // polite region is latest-wins, and a generic "complete" landing on top of
+            // a specific server message would lose the message.
+            if ( $uploadTriger && $uploadTriger.form ) {
+                announceA11yStatus($uploadTriger.form, a11yLabel('uploadComplete'));
+            }
 
             var fieldsObjectList = null
                 , $li   = null
@@ -2831,11 +3393,12 @@ function ValidatorPlugin(rules, data, formId, culture) {
                 let resetLinkNeedToBeAdded = false;
                 let $resetLink = document.getElementById(resetLinkId);
                 let defaultClassNameArr = ['reset','js-upload-reset'];
+                let resetLabel = $uploadTriger.getAttribute('data-gina-form-upload-reset-label') || 'Reset';
                 if (!$resetLink) {
                     resetLinkNeedToBeAdded      = true;
                     $resetLink                  = document.createElement('A');
                     $resetLink.href             = '#';
-                    $resetLink.innerHTML        = $uploadTriger.getAttribute('data-gina-form-upload-reset-label') || 'Reset';
+                    $resetLink.innerHTML        = resetLabel;
                     $resetLink.className        = defaultClassNameArr.join(' ');
                     $resetLink.id               = resetLinkId;
                 } else {
@@ -2843,7 +3406,7 @@ function ValidatorPlugin(rules, data, formId, culture) {
                         $resetLink.href             = '#';
                     }
                     if ( !$resetLink.innerHTML || $resetLink.innerHTML == '' ) {
-                        $resetLink.innerHTML        = $uploadTriger.getAttribute('data-gina-form-upload-reset-label') || 'Reset';
+                        $resetLink.innerHTML        = resetLabel;
                     }
                     if ( typeof($resetLink.className) == 'undefined' ) {
                         $resetLink.className = "";
@@ -2851,6 +3414,27 @@ function ValidatorPlugin(rules, data, formId, culture) {
                     let classNameArr = merge($resetLink.className.split(/\s+/g), defaultClassNameArr);
                     $resetLink.className    = classNameArr.join(' ');
                 }
+                // #A11Y7/U5 — the control gina generates is an anchor, so assistive tech
+                // announces it as a link and Space does not activate it. Give it button
+                // semantics; the matching Space handler lives with the click binding in
+                // `bindUploadResetOrDeleteTrigger`, because a role that PROMISES button
+                // behaviour without delivering the key is worse than no role at all.
+                // Stamped only on an anchor: a consumer supplying their own <button> under
+                // this id already has the right semantics, and overriding an implicit role
+                // is a regression. Strict `/^a$/i` here, unlike the loose `/a/i` guarding
+                // `href` above (that one also matches TEXTAREA, CANVAS, LABEL…).
+                if ( /^a$/i.test($resetLink.tagName) ) {
+                    $resetLink.setAttribute('role', 'button');
+                    // The accessible name names the file it acts on: these controls stack
+                    // one per staged file and are otherwise identical, so a controls list
+                    // reads "Reset, Reset, Reset". The visible label stays the PREFIX so
+                    // the name still contains it (WCAG 2.5.3 Label in Name), and it reuses
+                    // the consumer's own `-reset-label`, so it is translated wherever that
+                    // already is.
+                    if ( files[f].originalFilename ) {
+                        $resetLink.setAttribute('aria-label', resetLabel + ' ' + files[f].originalFilename);
+                    }
+                }
                 $resetLink.style.display    = 'none';
 
                 // image preview
@@ -2861,6 +3445,12 @@ function ValidatorPlugin(rules, data, formId, culture) {
                 ) {
                     let $img    = document.createElement('IMG');
                     $img.src    = files[f].tmpUri;
+                    // #A11Y7/U1 — the preview tells the user WHICH file is staged, so it is
+                    // informative content, not decoration; without a text alternative assistive
+                    // tech falls back to reading the temp URI aloud, once per staged file.
+                    // Empty string when the name is missing: a silently ignored image beats
+                    // announcing a placeholder.
+                    $img.alt    = files[f].originalFilename || '';
                     $img.style.display = 'none';
                     $img.setAttribute('data-upload-original-filename', files[f].originalFilename);
                     $img.setAttribute('data-upload-reset-link-id', $resetLink.id);
@@ -2956,6 +3546,12 @@ function ValidatorPlugin(rules, data, formId, culture) {
                                 // creating IMG tag
                                 let $img = document.createElement('IMG');
                                 $img.src = files[f][key].tmpUri;
+                                // #A11Y7/U1 — name the file the user actually chose, not the
+                                // server-generated preview variant recorded just below: the
+                                // generated name is an internal artefact and means nothing to
+                                // the person listening. Same empty-string fallback as the
+                                // no-preview branch.
+                                $img.alt = files[f].originalFilename || '';
                                 $img.style.display = 'none';
                                 // retrieve img `originalFilename` (not the preview img[key] `originalFilename`)
                                 // these 2 metadatas will be used to remove files from the server
@@ -3196,6 +3792,39 @@ function ValidatorPlugin(rules, data, formId, culture) {
                         // display upload input
                         restoreUploadAffordance($uploadTrigger, uploadHiddenClass);
 
+                        // #A11Y7/U5 — the control about to be removed is the one the user
+                        // just activated, so it holds focus; removing a focused element
+                        // drops focus to <body> and the user loses their place with no
+                        // signal. Move focus first, onto the file input that owns the
+                        // staged files — which `restoreUploadAffordance` just made visible
+                        // again. Guarded on it actually holding focus, so a programmatic
+                        // reset never yanks focus away from wherever the user really is.
+                        if ( document.activeElement === $resetLink || $resetLink.contains(document.activeElement) ) {
+                            if ( typeof($uploadTrigger.focus) == 'function' ) {
+                                $uploadTrigger.focus();
+                            }
+                            // #A11Y5's lesson, applied: `typeof focus == 'function'` is true
+                            // for EVERY HTMLElement, and focus() is a silent no-op on one
+                            // that cannot take focus (hidden, disabled, detached) — so
+                            // confirm the move instead of assuming it. Signal-only: there is
+                            // no better fallback than the document, and failing loudly here
+                            // would break a removal that otherwise succeeded.
+                            if ( document.activeElement !== $uploadTrigger ) {
+                                console.debug('[FormValidator][upload]['+ ($uploadTrigger.id || '?') +'] '+ bindingType +': could not move focus to the file input before removing the '+ bindingType +' control; focus falls back to the document.');
+                            }
+                        }
+                        // Announce the removal. `aria-live="polite"` queues rather than
+                        // interrupts, so this lands after the focus move above has been
+                        // announced instead of racing it. Function replacer, not a string:
+                        // a file name may contain `$`, and a string replacement would expand
+                        // `$&` / `$1` patterns inside it.
+                        if ( $uploadTrigger.form && childNodeFile ) {
+                            announceA11yStatus(
+                                $uploadTrigger.form,
+                                a11yLabel('fileRemoved').replace('%s', function () { return childNodeFile; })
+                            );
+                        }
+
                         // remove link & image - must be done last
                         // (the reset/delete link's own click listener dies with the node)
                         $resetLink.remove();
@@ -5205,6 +5834,19 @@ function ValidatorPlugin(rules, data, formId, culture) {
 
                 onUploadResetOrDelete($uploadTrigger, bindingType);
             });
+            // #A11Y7/U5 — the generated control is an anchor carrying `role="button"`,
+            // and a button MUST activate on Space; an anchor natively answers Enter only,
+            // so without this the role would advertise an interaction that does not work.
+            // Anchors only: a real <button> already fires click on Space, and binding
+            // this there would run the removal twice.
+            if ( /^a$/i.test($uploadResetOrDeleteTrigger.tagName) ) {
+                addListener(gina, $uploadResetOrDeleteTrigger, 'keydown', function onUploadResetOrDeleteTriggerKeydown(e) {
+                    if ( e.key === ' ' || e.keyCode === 32 ) {
+                        e.preventDefault(); // Space would otherwise scroll the page
+                        onUploadResetOrDelete($uploadTrigger, bindingType);
+                    }
+                });
+            }
             $uploadResetOrDeleteTrigger.isBinded = true;
         } else {
             console.warn('[FormValidator::bindForm][upload]['+$uploadTrigger.id+'] : did not find `upload '+bindingType+' trigger`.\nPlease, make sure that your '+bindingType+' element ID is `'+ uploadResetOrDeleteTriggerId +'`, or add to your file input ('+ $uploadTrigger.id +') -> `data-gina-form-upload-'+bindingType+'-trigger="your-custom-id"` definition.');
@@ -5656,6 +6298,13 @@ function ValidatorPlugin(rules, data, formId, culture) {
             throw new Error('Validator::bindForm($target, customRule) could not bind form `'+ $target +'`\n'+err.stack );
         }
 
+        // #A11Y2 — stand the polite live region up HERE, at bind time, rather than lazily on the
+        // first error. Creating and populating it in one tick reaches assistive tech as a single
+        // mutation batch that is commonly never spoken, so the first announcement per form used to
+        // be the one most likely lost. Every registration path funnels through bindForm, so this
+        // one call covers them all. Announcing stays announceA11yError's job; this only creates.
+        ensureA11yLiveRegion($target);
+
         // console.debug('binding for: '+ _id);
         var withRules = false, rule = null, evt = '', proceed = null;
 
@@ -6404,6 +7053,24 @@ function ValidatorPlugin(rules, data, formId, culture) {
                             updateUploadProgressIndicator($uploadForm.uploadProperties.progressContainer, 'preparing');
                         }
 
+                        // #A11Y7/U2 — announce the transition into "uploading". Note this
+                        // is deliberately NOT gated on `progressContainer`: the indicator is
+                        // opt-in by presence, but a user who cannot see it is precisely the
+                        // one who needs to be told the upload began.
+                        // The announcement targets the file input's REAL owning form, not
+                        // `$uploadForm` (the virtual one built just above): the real form is
+                        // where `bindForm` already stood up a live region, so upload status
+                        // and validation errors share one region instead of splitting across
+                        // two. Selection always sends today — the `.send()` below is
+                        // unconditional and `data-gina-file-autosend="false"` is still a TODO
+                        // — so this is a true start; gate it if that ever lands.
+                        if ( $uploadForm.uploadProperties && $uploadForm.uploadProperties.uploadTriggerId ) {
+                            var $a11yUploadInput = document.getElementById($uploadForm.uploadProperties.uploadTriggerId);
+                            if ( $a11yUploadInput && $a11yUploadInput.form ) {
+                                announceA11yStatus($a11yUploadInput.form, a11yLabel('uploadStarted'));
+                            }
+                        }
+
                         // binding form
                         try {
                             var $uploadFormValidator = getFormById(uploadFormId);
@@ -7329,6 +7996,44 @@ function ValidatorPlugin(rules, data, formId, culture) {
                         _evt = 'reset.'+_evt
                     }
 
+                    // #B246 — a disabled submit trigger must not run the submit cycle.
+                    // `updateSubmitTriggerState()` marks an invalid form's trigger with
+                    // `aria-disabled="true"` and never with native `disabled`, precisely so
+                    // the click still reaches us. Nothing READ that marker, so the trigger
+                    // stayed fully operable: a click ran the collect -> validate ->
+                    // `validate.<id>` chain and only the `isValid()` gate stopped the send.
+                    // The trigger was inert in appearance ONLY, and that also contradicted
+                    // the `aria-disabled` contract it advertises to assistive tech (which
+                    // requires the author to suppress the action).
+                    //
+                    // Intercept HERE — before the `submit.<id>` dispatch below — so
+                    // `bindSubmitEl`'s handler never runs, `isSubmitting` is never latched
+                    // and no send path is reachable. The click is still answered with a
+                    // display-only reveal, so the user learns WHY the trigger is disabled
+                    // (which is what the operable-trigger design was bought for).
+                    // Checked on the CLICKED element, not `$formInstance.submitTrigger`:
+                    // a form may carry several submit buttons and only one registers.
+                    if ( /^submit\./i.test(_evt) && isTriggerDisabled($el) ) {
+                        cancelEvent(event);
+                        revealValidationState( instance.$forms[$form.id] || $form );
+                        return false;
+                    }
+
+                    // #B247 — arm the loading state on the element the user actually
+                    // operated. DELIBERATELY after the #B246 gate above: a disabled
+                    // trigger returns without starting anything, so arming it there
+                    // would strand exactly the state this feature exists to release.
+                    // `resolveTrigger` climbs to the owning button/anchor, because a
+                    // click on a wrapped label (`<button><span>Save</span></button>`)
+                    // targets the inner node, and the state belongs on the control the
+                    // user perceives as the trigger.
+                    if ( /^submit\./i.test(_evt) ) {
+                        armSubmitLoading(
+                            instance.$forms[$form.id] || $form,
+                            loadingState.resolveTrigger($el, $target)
+                        );
+                    }
+
                     if (gina.events[_evt]) {
                         cancelEvent(event);
 
@@ -7464,6 +8169,22 @@ function ValidatorPlugin(rules, data, formId, culture) {
                         instance.$forms[_id].isSubmitting = false;
                     }
 
+                    // #B247 — release the trigger-scoped loading state. THIS is the path
+                    // that stranded it: a rejected submit produces no request at all, so
+                    // none of the XHR releases can ever run, and only the framework knows
+                    // the submit was refused before it started. Left armed, the trigger
+                    // stays visually loading until the page or popin is reloaded.
+                    //
+                    // Gated on nothing being in flight: a form can be submitted again
+                    // while an earlier request is still running, and that later attempt
+                    // may well be the one that fails validation. Releasing unconditionally
+                    // would clear the state belonging to the request still in progress —
+                    // whose own settle is what must release it.
+                    var _loadingForm = instance.$forms[_id] || $form;
+                    if ( !/^true$/i.test(_loadingForm.isSending) ) {
+                        disarmSubmitLoading(_loadingForm);
+                    }
+
                     // #A11Y1 (slice 3) — failed submit: move focus to the first invalid field so
                     // assistive tech announces it (accessible name + aria-invalid + the
                     // aria-errormessage text). DOM order; hidden / unfocusable fields are skipped.
@@ -7481,7 +8202,13 @@ function ValidatorPlugin(rules, data, formId, culture) {
                                 && typeof(_aField.focus) == 'function'
                             ) {
                                 _aField.focus();
-                                break;
+                                // #A11Y5 (V8) — kept in step with focusFirstInvalidField:
+                                // only stop once focus actually moved, since focus() is a
+                                // no-op on an unfocusable host that still passes the
+                                // typeof-function gate above.
+                                if ( typeof(document) === 'undefined' || !document || document.activeElement === _aField ) {
+                                    break;
+                                }
                             }
                         }
                     }
@@ -7702,6 +8429,27 @@ function ValidatorPlugin(rules, data, formId, culture) {
                 return false;
             }
 
+            // #B247 — a submit that never went through the click proxy still gets a
+            // loading state: Enter inside a field, `form.submit()`, `$validator.submit()`,
+            // and — less obviously — a click on a wrapped label such as
+            // `<button type="submit"><span>Save</span></button>`, whose event.target is
+            // the span (no `.type`), so the click proxy's submit branch never fires and
+            // the event surfaces here instead. There is no clicked element on this path,
+            // so the registered trigger is the best and only referent. Placed after the
+            // disabled + defaultPrevented guards above, which both return first.
+            // NB. the disabled check at the top of this handler reads a DOMParser copy of
+            // the form's innerHTML, so it sees neither a live `disabled` set by JS nor the
+            // `aria-disabled` marker `updateSubmitTriggerState` uses. Re-check the live
+            // node with #B246's predicate: without it, every Enter-key submit on an
+            // invalid live-check form would flash the trigger armed for the length of the
+            // validation pass before the rejected branch released it.
+            if ($formInstance) {
+                var $loadingTrigger = document.getElementById($formInstance.submitTrigger);
+                if ( !isTriggerDisabled($loadingTrigger) ) {
+                    armSubmitLoading($formInstance, $loadingTrigger);
+                }
+            }
+
             if (withRules || isBinded) {
                 cancelEvent(e);
             }
@@ -7891,13 +8639,17 @@ function ValidatorPlugin(rules, data, formId, culture) {
         } else if ( document.getElementById($formInstance.submitTrigger) ) {
             // Represent the "invalid + live-check-on" state with aria-disabled + a class
             // INSTEAD of the native `disabled` property. A natively-disabled <button>
-            // emits no click event, so the form-level click -> validate -> show-all-errors
-            // -> focus-first guard (the `validate.<id>` listener) never fires: the button
-            // looks dead and gives zero feedback. aria-disabled keeps the trigger operable,
-            // so the click still runs validation (revealing every invalid field + focusing
-            // the first) while `isValid()` (the real gate) still blocks the send. Mirrors
-            // gina's own <a>-tag submit-trigger handling, which already uses aria-disabled
-            // in-flight. The show branch KEEPS clearing native `disabled` so a trigger
+            // emits no click event at all, so the click cannot be observed and the user
+            // gets no feedback about WHY the trigger is dead. aria-disabled keeps the
+            // trigger focusable and perceivable, and clickProxyHandler INTERCEPTS the
+            // click (#B246) to answer it with a display-only reveal: every invalid field
+            // is rendered and the first is focused, while the submit cycle is never
+            // entered. The trigger is therefore genuinely not operable — which is what
+            // the aria-disabled contract promises assistive tech, and what the earlier
+            // "keep it operable so the click can still validate" shape got wrong: it
+            // left the real submit path reachable from a control announced as disabled.
+            // Mirrors gina's own <a>-tag submit-trigger handling, which already uses
+            // aria-disabled in-flight. The show branch KEEPS clearing native `disabled` so a trigger
             // rendered `disabled` in markup still enables on valid / when live-check is off.
             // Tag-agnostic: setAttribute/classList work for both <button> and <a> submit
             // triggers. Consumers must style the [aria-disabled="true"] /
@@ -7918,6 +8670,125 @@ function ValidatorPlugin(rules, data, formId, culture) {
         }
     }
 
+    /**
+     * isTriggerDisabled
+     *
+     * Tells whether a submit trigger is currently marked as disabled.
+     * `updateSubmitTriggerState()` marks an invalid form's trigger with
+     * `aria-disabled="true"` rather than the native `disabled` property, so a
+     * native-only check can never see it. The predicate shape mirrors the popin
+     * plugin's own trigger gate, so both subsystems agree on what "disabled"
+     * means for a trigger.
+     *
+     * @param {object} $el - candidate trigger (DOMObject)
+     *
+     * @returns {boolean} true when the trigger must not be operated
+     *
+     * @example
+     * isTriggerDisabled($button); // true while aria-disabled="true" is set
+     *
+     * @inner
+     */
+    var isTriggerDisabled = function($el) {
+        if ( !$el || typeof($el.getAttribute) != 'function' ) {
+            return false;
+        }
+        return (
+            $el.getAttribute('disabled') != null && $el.getAttribute('disabled') != 'false'
+            ||
+            $el.getAttribute('aria-disabled') == 'true'
+        );
+    };
+
+    /**
+     * focusFirstInvalidField
+     *
+     * Moves focus to the first field carrying an error, in DOM order, skipping
+     * hidden and unfocusable controls (#A11Y1) so assistive tech announces the
+     * accessible name + `aria-invalid` + the `aria-errormessage` text.
+     *
+     * NB. the `validate.<id>` guard keeps its own inline twin of this loop rather
+     * than calling here. That is DELIBERATE: the inline shape is locked by source
+     * pins in `test/core/validator-aria-invalid.test.js` (`_a11yErrs`, `_aField`),
+     * so collapsing the two would break pins unrelated to #B246. Keep the two in
+     * step if the focus rule ever changes.
+     *
+     * @param {object} $form - form target (DOMObject), not the instance
+     * @param {object} errors - error map keyed by field name
+     *
+     * @returns {boolean} true when a field was focused
+     *
+     * @example
+     * focusFirstInvalidField($form, result['fields'] || result['error']);
+     *
+     * @inner
+     */
+    var focusFirstInvalidField = function($form, errors) {
+        if ( !$form || !errors ) {
+            return false;
+        }
+        for (var i = 0, len = $form.length; i < len; ++i) {
+            var $field  = $form[i];
+            var name    = $field.getAttribute('name');
+            if (
+                name
+                && typeof(errors[name]) != 'undefined'
+                && ( typeof(errors[name].count) != 'function' || errors[name].count() > 0 )
+                && $field.type != 'hidden'
+                && typeof($field.focus) == 'function'
+            ) {
+                $field.focus();
+                // #A11Y5 (V8) — `typeof focus == 'function'` is true for EVERY HTMLElement,
+                // a custom element with neither `tabindex` nor `delegatesFocus` included,
+                // whose focus() is a silent no-op (measured). Without confirming the move,
+                // the loop reported success and stopped on a control that never took focus,
+                // so a failed submit announced nothing. Confirming it is also what makes the
+                // "skips unfocusable controls" contract above true rather than aspirational.
+                if ( typeof(document) === 'undefined' || !document || document.activeElement === $field ) {
+                    return true;
+                }
+            }
+        }
+        return false;
+    };
+
+    /**
+     * revealValidationState
+     *
+     * Display-only validation pass, used when a DISABLED submit trigger is
+     * clicked (#B246). It runs the same collect + validate chain the submit path
+     * uses, but routes the result straight to the error renderer instead of
+     * dispatching `validate.<id>` — so `bindSubmitEl`'s handler never runs, the
+     * `isSubmitting` latch is never set and the `isValid()` send gate is never
+     * reached. No request can start from this path by construction.
+     *
+     * The trigger state is re-synced from the fresh result, which also self-heals
+     * a stale disabled marker on a form that has since become valid.
+     *
+     * @param {object} $formInstance - form instance (carries `.target` / `.rules`)
+     *
+     * @returns {void}
+     *
+     * @example
+     * revealValidationState(instance.$forms['myForm']);
+     *
+     * @inner
+     */
+    var revealValidationState = function($formInstance) {
+        if ( !$formInstance || !$formInstance.target ) {
+            return;
+        }
+        var $target         = $formInstance.target;
+        var validationInfo  = getFormValidationInfos($target, $formInstance.rules);
+
+        validate($target, validationInfo.fields, validationInfo.$fields, $formInstance.rules, function onDisabledTriggerReveal(result) {
+            var errors = result['fields'] || result['error'];
+            handleErrorsDisplay($target, errors, result['data']);
+            focusFirstInvalidField($target, errors);
+            updateSubmitTriggerState($formInstance, result.isValid());
+        });
+    };
+
     /**
      * getFormValidationInfos
      *
@@ -9476,5 +10347,5 @@ if ( ( typeof(module) !== 'undefined' ) && module.exports ) {
     module.exports  = ValidatorPlugin
 } else if ( typeof(define) === 'function' && define.amd) {
     // Publish as AMD module
-    define('gina/validator', ['utils/events', 'utils/dom', 'utils/effects', 'utils/data', 'lib/form-validator', 'lib/routing'], function(){ return ValidatorPlugin })
+    define('gina/validator', ['utils/events', 'utils/dom', 'utils/effects', 'utils/data', 'lib/form-validator', 'lib/routing', 'lib/loading-state'], function(){ return ValidatorPlugin })
 }