fix(badge): improve language around screen reader text usage

Author: zeroedin

elements/pf-v6-badge/README.md

@@ -28,7 +28,7 @@ A badge is used to annotate other information like a label or an object name.
 
 | React prop | Notes |
 | --- | --- |
-| `screenReaderText` | No built-in screen reader text span. Authors should provide their own visually-hidden text adjacent to the badge. |
+| `screenReaderText` | Authors slot visually-hidden text alongside the badge content for screen reader context, e.g. `<pf-v6-badge>3 <span class="pf-v6-screen-reader">unread messages</span></pf-v6-badge>`. |
 
 ### Changed API
 

elements/pf-v6-badge/pf-v6-badge.ts

@@ -9,6 +9,8 @@ export type BadgeState = 'unread' | 'read';
 /**
  * A **badge** is used to annotate other information like a label or an object name.
  * @summary Displays a numeric value as an annotation
+ * @slot - Badge content, typically a number or short text. Include a visually-hidden
+ *         `<span>` for screen reader context when the number alone is not descriptive.
  */
 @customElement('pf-v6-badge')
 export class PfV6Badge extends LitElement {
@@ -42,7 +44,7 @@ export class PfV6Badge extends LitElement {
         (threshold && number && (threshold <= number)) ? `${threshold.toString()}+`
       : (number != null) ? number.toString()
       : '';
-    return html`${!displayText ? html`<!-- Badge content, typically a number or short text --><slot></slot>` : displayText}`;
+    return html`${!displayText ? html`<!-- Badge content, typically a number or short text with visually-hidden screen reader support text --><slot></slot>` : displayText}`;
   }
 }
 

elements/pf-v6-badge/test/pf-v6-badge.spec.ts

@@ -33,7 +33,6 @@ describe('<pf-v6-badge>', function() {
 
     it('should be visible in the accessibility tree', async function() {
       const snapshot = await a11ySnapshot();
-      expect(snapshot.children?.length).to.be.greaterThan(0);
       const badgeNode = snapshot.children?.find(
         (child: { name?: string }) => child.name?.includes('100')
       );
@@ -155,12 +154,22 @@ describe('<pf-v6-badge>', function() {
   });
 
   describe('accessibility', function() {
+    it('should be accessible', async function() {
+      const element = await createFixture<PfV6Badge>(html`
+        <pf-v6-badge state="read" number="10">10</pf-v6-badge>
+      `);
+      await expect(element).to.be.accessible();
+    });
+
     it('should contain text in the accessibility tree', async function() {
       await createFixture<PfV6Badge>(html`
         <pf-v6-badge state="read" number="10">10</pf-v6-badge>
       `);
       const snapshot = await a11ySnapshot();
-      expect(snapshot.children?.length).to.be.greaterThan(0);
+      const badgeNode = snapshot.children?.find(
+        (child: { name?: string }) => child.name?.includes('10')
+      );
+      expect(badgeNode).to.exist;
     });
   });