fix: dimmer AT firefox/macos quirks (#438)

* fix(dimmer): re-apply inert via rAF in firstUpdated to fix Firefox/VoiceOver first-load reachability

On Mac/Firefox/VoiceOver, background card headings were reachable via AT
navigation on first page load when `active` was set declaratively. After
toggling off then on, the bug disappeared — confirming a timing issue.

Root cause: `_updateBackgroundInert()` applied `inert` during `slotchange`,
but child custom elements (it-card) were still upgrading their shadow DOM at
that point. Firefox's AT registered the heading links before the `inert`
constraint propagated through the fully-rendered tree.

Fix: override `firstUpdated()` to re-apply `_updateBackgroundInert()` after
one rAF, matching the AT-settlement pattern in focus-trap-controller.

Also documents BSI#1165 (upstream bootstrap-italia a11y issue) in dimmer.scss
since it cannot be addressed from this layer.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* fix(dimmer): add aria-hidden to background elements to fix Firefox/VoiceOver

The rAF firstUpdated workaround did not fix the issue. Root cause:
Firefox's inert implementation does not propagate through shadow DOM slot
boundaries when building its accessibility tree on first page load. inert IS
set in the DOM but Firefox VoiceOver still finds slotted <a> links inside
custom elements (e.g. it-card) because it does not walk the light DOM
ancestor chain when creating AT nodes for shadow DOM content.

aria-hidden="true" operates on the DOM tree (not the flat tree) and Firefox
has mature, correct support for it: when set on a container, it explicitly
excludes the element and all DOM-tree descendants from the accessibility tree,
including light DOM children that happen to be slotted into child custom
elements.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* changeset

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: Piero Nicolli <piero.nicolli@redturtle.it>

Author: 3 people

.changeset/lazy-mammals-smile.md

@@ -0,0 +1,5 @@
+---
+'@italia/dimmer': patch
+---
+
+Fixed browser-specific quirks with the accessibility trees

packages/dimmer/src/dimmer.scss

@@ -10,6 +10,8 @@
 @use 'bootstrap-italia/src/scss/base/maps' as *;
 
 // Import dimmer component styles from Bootstrap Italia
+// TODO: track BSI#1165 (https://github.com/italia/bootstrap-italia/issues/1165) —
+// upstream dimmer a11y issue; apply override here once BSI ships a fix.
 @use 'bootstrap-italia/src/scss/components/dimmer' as *;
 
 // .dimmer.dimmer-{color} — same element, so the @each must live OUTSIDE .dimmer,

packages/dimmer/src/it-dimmer.ts

@@ -163,18 +163,24 @@ export class ItDimmer extends BaseComponent {
   }
 
   /**
-   * Applica/rimuove `inert` sugli elementi slottati nel background slot.
-   * Necessario per Safari, che non rispetta `aria-hidden` sull'overlay
-   * e lascia interagibili gli elementi sotto il dimmer.
+   * Applica/rimuove `inert` e `aria-hidden` sugli elementi slottati nel background slot.
+   *
+   * - `inert`: blocca interazione da tastiera/mouse (necessario per Safari, che non rispetta
+   *   `aria-hidden` sull'overlay).
+   * - `aria-hidden`: nasconde l'elemento dall'albero di accessibilità via DOM tree (non flat
+   *   tree). Necessario per Firefox: `inert` da solo non propaga correttamente attraverso
+   *   le slot boundary nelle custom elements al primo caricamento della pagina.
    */
   private _updateBackgroundInert(): void {
     const slot = this.shadowRoot?.querySelector<HTMLSlotElement>('slot:not([name])');
     if (!slot) return;
     for (const el of slot.assignedElements({ flatten: true })) {
       if (this.active) {
         el.setAttribute('inert', '');
+        el.setAttribute('aria-hidden', 'true');
       } else {
         el.removeAttribute('inert');
+        el.removeAttribute('aria-hidden');
       }
     }
   }

packages/dimmer/test/it-dimmer.test.ts

@@ -440,22 +440,24 @@ describe('it-dimmer', () => {
       expect(dimmer?.getAttribute('aria-hidden')).to.be.null;
     });
 
-    it('sets inert on background slot elements when active', async () => {
+    it('sets inert and aria-hidden on background slot elements when active', async () => {
       const el = await fixture<ItDimmer>(html`
         <it-dimmer>
           <div id="bg">Sfondo</div>
         </it-dimmer>
       `);
       const bg = el.querySelector('#bg')!;
       expect(bg.hasAttribute('inert')).to.be.false;
+      expect(bg.getAttribute('aria-hidden')).to.be.null;
 
       el.active = true;
       await el.updateComplete;
 
       expect(bg.hasAttribute('inert')).to.be.true;
+      expect(bg.getAttribute('aria-hidden')).to.equal('true');
     });
 
-    it('removes inert from background slot elements when hidden', async () => {
+    it('removes inert and aria-hidden from background slot elements when hidden', async () => {
       const el = await fixture<ItDimmer>(html`
         <it-dimmer active>
           <div id="bg">Sfondo</div>
@@ -464,11 +466,13 @@ describe('it-dimmer', () => {
       await el.updateComplete;
       const bg = el.querySelector('#bg')!;
       expect(bg.hasAttribute('inert')).to.be.true;
+      expect(bg.getAttribute('aria-hidden')).to.equal('true');
 
       el.active = false;
       await el.updateComplete;
 
       expect(bg.hasAttribute('inert')).to.be.false;
+      expect(bg.getAttribute('aria-hidden')).to.be.null;
     });
 
     it('has part="dimmable" on wrapper', async () => {