fix(switch): add static accessible label (#3094)

* fix(switch): add static accessible label

Rename `label` property to `accessibleLabel` (attribute:
`accessible-label`) for consistency. Wire it to set `ariaLabel`
on element internals for a proper static accessible name.

Closes #2754

Assisted-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs: changeset

* fix(switch): keep label as deprecated, add accessible-label

Keep the existing `label` property as deprecated and fall back
to it when `accessible-label` is not set. JSDoc advises updating
the accessible label based on checked state.

Assisted-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: bennypowers

.changeset/fix-switch-a11y.md

@@ -0,0 +1,6 @@
+---
+"@patternfly/elements": patch
+---
+
+`<pf-switch>`: the switch now has a proper static accessible label
+independent of its on/off state text.

elements/pf-switch/demo/without-label.html

@@ -2,7 +2,7 @@
   <form>
     <fieldset>
       <legend>Without label</legend>
-      <pf-switch checked></pf-switch>
+      <pf-switch accessible-label="Toggle option" checked></pf-switch>
     </fieldset>
   </form>
 </section>

elements/pf-switch/pf-switch.ts

@@ -24,9 +24,16 @@ export class PfSwitch extends LitElement {
 
   #internals = InternalsController.of(this, { role: 'switch' });
 
-  /** Accessible label text for the switch */
+  /** @deprecated use `accessible-label` instead */
   @property({ reflect: true }) label?: string;
 
+  /**
+   * Accessible label for the switch when there is no associated `<label>` element.
+   * Update this value based on the checked state to communicate the meaning of
+   * each state to assistive technology users, e.g. "Wi-Fi on" / "Wi-Fi off".
+   */
+  @property({ reflect: true, attribute: 'accessible-label' }) accessibleLabel?: string;
+
   /** Flag to show if the switch has a check icon. */
   @property({ reflect: true, type: Boolean, attribute: 'show-check-icon' }) showCheckIcon = false;
 
@@ -57,6 +64,7 @@ export class PfSwitch extends LitElement {
   override willUpdate(): void {
     this.#internals.ariaChecked = String(!!this.checked);
     this.#internals.ariaDisabled = String(!!this.disabled);
+    this.#internals.ariaLabel = this.accessibleLabel || this.label || null;
   }
 
   override render(): TemplateResult<1> {

elements/pf-switch/test/pf-switch.spec.ts

@@ -43,6 +43,27 @@ describe('<pf-switch>', function() {
     });
   });
 
+  describe('with accessible-label attribute', function() {
+    let element: PfSwitch;
+    let snapshot: A11yTreeSnapshot;
+    beforeEach(async function() {
+      element = await createFixture<PfSwitch>(html`
+        <pf-switch accessible-label="Dark Mode"></pf-switch>
+      `);
+      snapshot = await a11ySnapshot({ selector: 'pf-switch' });
+    });
+    it('has an accessible name from accessible-label', function() {
+      expect(snapshot.name).to.equal('Dark Mode');
+    });
+    it('keeps the same accessible name regardless of checked state', async function() {
+      element.click();
+      await element.updateComplete;
+      await nextFrame();
+      snapshot = await a11ySnapshot({ selector: 'pf-switch' });
+      expect(snapshot.name).to.equal('Dark Mode');
+    });
+  });
+
   describe('with labels for on and off state', function() {
     let element: PfSwitch;
     let snapshot: A11yTreeSnapshot;