From cd172ede8c284acdb1419337b93b0cbc4679bd73 Mon Sep 17 00:00:00 2001
From: Lea Verou <lea@verou.me>
Date: Thu, 19 Dec 2024 21:15:25 -0500
Subject: [PATCH] Docs for visually hidden util, remove visually hidden
 component per #232

---
 docs/docs/components/button-group.md          |  2 +-
 docs/docs/components/visually-hidden.md       | 46 ---------
 docs/docs/experimental/themer.md              | 26 +++--
 docs/docs/resources/changelog.md              |  4 +-
 docs/docs/utilities/visually-hidden.md        | 96 +++++++++++++++++++
 src/components/color-picker/color-picker.ts   |  4 +-
 src/components/copy-button/copy-button.ts     |  6 +-
 src/components/page/page.css                  | 13 ---
 src/components/page/page.ts                   |  5 +-
 .../visually-hidden/visually-hidden.css       | 11 ---
 .../visually-hidden/visually-hidden.test.ts   | 43 ---------
 .../visually-hidden/visually-hidden.ts        | 27 ------
 12 files changed, 119 insertions(+), 164 deletions(-)
 delete mode 100644 docs/docs/components/visually-hidden.md
 create mode 100644 docs/docs/utilities/visually-hidden.md
 delete mode 100644 src/components/visually-hidden/visually-hidden.css
 delete mode 100644 src/components/visually-hidden/visually-hidden.test.ts
 delete mode 100644 src/components/visually-hidden/visually-hidden.ts

diff --git a/docs/docs/components/button-group.md b/docs/docs/components/button-group.md
index f45f06691..73043ea6f 100644
--- a/docs/docs/components/button-group.md
+++ b/docs/docs/components/button-group.md
@@ -167,7 +167,7 @@ Create a split button using a button and a dropdown. Use a [visually hidden](/do
   <wa-button variant="brand">Save</wa-button>
   <wa-dropdown placement="bottom-end">
     <wa-button slot="trigger" variant="brand" caret>
-      <wa-visually-hidden>More options</wa-visually-hidden>
+      <span class="wa-visually-hidden">More options</span>
     </wa-button>
     <wa-menu>
       <wa-menu-item>Save</wa-menu-item>
diff --git a/docs/docs/components/visually-hidden.md b/docs/docs/components/visually-hidden.md
deleted file mode 100644
index 4542c6b89..000000000
--- a/docs/docs/components/visually-hidden.md
+++ /dev/null
@@ -1,46 +0,0 @@
----
-title: Visually Hidden
-description: The visually hidden utility makes content accessible to assistive devices without displaying it on the screen.
-tags: component
-noAlpha: true
----
-
-According to [The A11Y Project](https://www.a11yproject.com/posts/2013-01-11-how-to-hide-content/), "there are real world situations where visually hiding content may be appropriate, while the content should remain available to assistive technologies, such as screen readers. For instance, hiding a search field's label as a common magnifying glass icon is used in its stead."
-
-Since visually hidden content can receive focus when tabbing, the element will become visible when something inside receives focus. This behavior is intentional, as sighted keyboard user won't be able to determine where the focus indicator is without it.
-
-```html {.example}
-<div style="min-height: 1.875rem;">
-  <wa-visually-hidden>
-    <a href="#">Skip to main content</a>
-  </wa-visually-hidden>
-</div>
-```
-
-## Examples
-
-### Links That Open in New Windows
-
-In this example, the link will open a new window. Screen readers will announce "opens in a new window" even though the text content isn't visible to sighted users.
-
-```html {.example}
-<a href="https://example.com/" target="_blank">
-  Visit External Page
-  <wa-icon name="arrow-up-right-from-square" variant="regular"></wa-icon>
-  <wa-visually-hidden>opens in a new window</wa-visually-hidden>
-</a>
-```
-
-### Content Conveyed By Context
-
-Adding a label may seem redundant at times, but they're very helpful for unsighted users. Rather than omit them, you can provide context to unsighted users with visually hidden content that will be announced by assistive devices such as screen readers.
-
-```html {.example}
-<wa-card style="width: 100%; max-width: 360px;">
-  <header>
-    <wa-visually-hidden>Personal Info</wa-visually-hidden>
-  </header>
-  <wa-input label="Name" style="margin-bottom: .5rem;"></wa-input>
-  <wa-input label="Email" type="email"></wa-input>
-</wa-card>
-```
diff --git a/docs/docs/experimental/themer.md b/docs/docs/experimental/themer.md
index e1b415ebe..a334d7068 100644
--- a/docs/docs/experimental/themer.md
+++ b/docs/docs/experimental/themer.md
@@ -379,12 +379,8 @@ hasOutline: false
     background-color: var(--wa-color-neutral-fill-quiet);
   }
 
-  /**
-  <wa-visually-hidden>, but without the :not(:focus-within),
-  the reason is that it shows the default browser file uploader.
-*/
-  .hidden-label::part(form-control-label),
-  .file-uploader input {
+  /** Visually hidden */
+  .hidden-label::part(form-control-label) {
     position: absolute !important;
     width: 1px !important;
     height: 1px !important;
@@ -522,7 +518,7 @@ hasOutline: false
     <wa-icon name="minus" library="fa-classic-regular" slot="collapse-icon"></wa-icon>
     <wa-input name="project-name" value="" placeholder="Project name" label="What are you working on?"></wa-input>
     <div>
-      <label class="file-uploader" style="display: block;" aria-describedby="file-uploader-description">
+      <label class="file-uploader wa-visually-hidden-force" style="display: block;" aria-describedby="file-uploader-description">
         <input name="project-logo" type="file" accept="image/*">
         Add logo
       </label>
@@ -537,7 +533,7 @@ hasOutline: false
           <wa-button value="[choose]" appearance="plain" id="icon-chooser-trigger" class="logo-chooser">
             <wa-tooltip for="icon-chooser-trigger" distance="-3" hoist>Browse Icons</wa-tooltip>
             <wa-icon name="ellipsis" library="fa-classic-regular"></wa-icon>
-            <wa-visually-hidden>Browse icons</wa-visually-hidden>
+            <span class="wa-visually-hidden">Browse icons</span>
           </wa-button>
           <small slot="hint" style="display: inline-block; line-height: var(--wa-line-height-condensed);">It's dangerous to go alone. Take these!</small>
       </wa-radio-group>
@@ -2270,17 +2266,17 @@ hasOutline: false
       <table style="margin-bottom: 0;">
         <thead>
           <tr>
-            <th><wa-checkbox size="large" style="padding-left: var(--wa-space-s)"><wa-visually-hidden>Check all</wa-visually-hidden></wa-checkbox></th>
+            <th><wa-checkbox size="large" style="padding-left: var(--wa-space-s)"><span class="wa-visually-hidden">Check all</span></wa-checkbox></th>
             <th>Customer</th>
             <th>Conversation</th>
             <th>Assigned To</th>
             <th style="text-align: center;">Status</th>
-            <th><wa-visually-hidden>Actions</wa-visually-hidden></th>
+            <th><span class="wa-visually-hidden">Actions</span></th>
           </tr>
         </thead>
         <tbody>
           <tr>
-            <td><wa-checkbox size="large" style="padding-left: var(--wa-space-s)"><wa-visually-hidden>Completed</wa-visually-hidden></wa-checkbox></td>
+            <td><wa-checkbox size="large" style="padding-left: var(--wa-space-s)"><span class="wa-visually-hidden">Completed</span></wa-checkbox></td>
             <td>Keanu Reeves</td>
             <td class="desc"><span style="font-weight: bold">Am I dead?</span><br><span class="excerpt">Okey dokey... free my mind. Right, no problem, free my mind, free my mind, no problem, right...</span></td>
             <td><wa-avatar  image="/assets/images/themer/avatar-chad.jpg"  label="Chad" style="margin-right: var(--wa-space-xs)"></wa-avatar>  Chad Stahelski</td>
@@ -2310,7 +2306,7 @@ hasOutline: false
             </td>
           </tr>
           <tr>
-            <td><wa-checkbox size="large" style="padding-left: var(--wa-space-s)"><wa-visually-hidden>Completed</wa-visually-hidden></wa-checkbox></td>
+            <td><wa-checkbox size="large" style="padding-left: var(--wa-space-s)"><span class="wa-visually-hidden">Completed</span></wa-checkbox></td>
             <td>Lawrence Fishburne</td>
             <td class="desc"><span style="font-weight: bold">We have a rule</span><br><span class="excerpt">We never free a mind once it's reached a certain age. It's dangerous, the mind has trouble letting go.</span></td>
             <td><wa-avatar image="/assets/images/themer/avatar-char.jpg"  label="Char" style="margin-right: var(--wa-space-xs)"></wa-avatar>  Char McCoy</td>
@@ -2340,7 +2336,7 @@ hasOutline: false
             </td>
           </tr>
           <tr>
-            <td><wa-checkbox size="large" style="padding-left: var(--wa-space-s)" checked><wa-visually-hidden>Completed</wa-visually-hidden></wa-checkbox></td>
+            <td><wa-checkbox size="large" style="padding-left: var(--wa-space-s)" checked><span class="wa-visually-hidden">Completed</span></wa-checkbox></td>
             <td>Carrie-Ann Moss</td>
             <td class="desc"><span style="font-weight: bold">Was it the same cat?</span><br><span class="excerpt">A déjà vu is usually a glitch in the Matrix. It happens when they change something.</span></td>
             <td><wa-avatar initials="DE" label="Avatar with initials: DE" style="margin-right: var(--wa-space-xs)"></wa-avatar>  Debbie Evans</td>
@@ -2370,7 +2366,7 @@ hasOutline: false
             </td>
           </tr>
           <tr>
-            <td><wa-checkbox size="large" style="padding-left: var(--wa-space-s)"><wa-visually-hidden>Completed</wa-visually-hidden></wa-checkbox></td>
+            <td><wa-checkbox size="large" style="padding-left: var(--wa-space-s)"><span class="wa-visually-hidden">Completed</span></wa-checkbox></td>
             <td>Joe Pantoliano</td>
             <td class="desc"><span style="font-weight: bold">Ignorance is bliss</span><br><span class="excerpt">Why oh why didn't I take the blue pill?</span></td>
             <td></td>
@@ -2400,7 +2396,7 @@ hasOutline: false
             </td>
           </tr>
           <tr>
-            <td><wa-checkbox size="large" style="padding-left: var(--wa-space-s)"><wa-visually-hidden>Completed</wa-visually-hidden></wa-checkbox></td>
+            <td><wa-checkbox size="large" style="padding-left: var(--wa-space-s)"><span class="wa-visually-hidden">Completed</span></wa-checkbox></td>
             <td>Hugo Weaving</td>
             <td class="desc"><span style="font-weight: bold">I'd like to share a revelation</span><br><span class="excerpt">I need the codes, I have to get inside Zion and you have to tell me how.</span></td>
             <td><wa-avatar  image="/assets/images/themer/avatar-dara.jpg"  label="Dara" style="margin-right: var(--wa-space-xs)"></wa-avatar> Dara Prescott</td>
diff --git a/docs/docs/resources/changelog.md b/docs/docs/resources/changelog.md
index 7c6e6244f..5610f1e00 100644
--- a/docs/docs/resources/changelog.md
+++ b/docs/docs/resources/changelog.md
@@ -31,10 +31,12 @@ During the alpha period, things might break! We take breaking changes very serio
 - Added [appearance utilities](/docs/utilities/appearance/)
 - Added [size utilities](/docs/utilities/size/)
 - Added [layout utilities](/docs/layout/#utilities)
-- Added [visually hidden](/docs/utilities/a11y/#visually-hidden) utility
+- Added [`.wa-visually hidden`](/docs/utilities/a11y/#visually-hidden) utility
 - Added [`<wa-page>`](/docs/components/page/#styles) native styles and utilities
 
 ### Components
+
+- Removed `<wa-visually-hidden>` in favor of the utility class
 - `<wa-page>`: `mobile-breakpoint` now takes any CSS length, not just pixels
 - Added `checked` and `disabled` custom states to `<wa-checkbox>` and `<wa-radio>`
 - Added `disabled`, `expanded`, `indeterminate`, and `selected` custom states to `<wa-tree-item>`
diff --git a/docs/docs/utilities/visually-hidden.md b/docs/docs/utilities/visually-hidden.md
new file mode 100644
index 000000000..f2f5533e9
--- /dev/null
+++ b/docs/docs/utilities/visually-hidden.md
@@ -0,0 +1,96 @@
+---
+title: Visually Hidden
+description: The visually hidden utility makes content accessible to assistive devices without displaying it on the screen.
+noAlpha: true
+---
+
+`.wa-visually-hidden` `.wa-visually-hidden-force`
+
+> "there are real world situations where visually hiding content may be appropriate, while the content should remain available to assistive technologies, such as screen readers. For instance, hiding a search field's label as a common magnifying glass icon is used in its stead."
+> — [The A11Y Project](https://www.a11yproject.com/posts/2013-01-11-how-to-hide-content/)
+
+Since visually hidden content can receive focus when tabbing, the element will become visible when something inside receives focus.
+This behavior is intentional, as otherwise sighted keyboard users wouldn't be able to determine where the focus indicator is.
+
+```html {.example}
+<div style="min-height: 1.875rem;">
+  <a href="#" class="wa-visually-hidden">Skip to main content</a>
+</div>
+```
+
+## Examples
+
+### Links That Open in New Windows
+
+In this example, the link will open a new window. Screen readers will announce "opens in a new window" even though the text content isn't visible to sighted users.
+
+```html {.example}
+<a href="https://example.com/" target="_blank">
+  Visit External Page
+  <wa-icon name="arrow-up-right-from-square" variant="regular"></wa-icon>
+  <span class="wa-visually-hidden">opens in a new window</span>
+</a>
+```
+
+### Content Conveyed By Context
+
+Adding a label may seem redundant at times, but they're very helpful for unsighted users. Rather than omit them, you can provide context to unsighted users with visually hidden content that will be announced by assistive devices such as screen readers.
+
+```html {.example}
+<wa-card style="width: 100%; max-width: 360px;">
+  <header class="wa-visually-hidden">
+    Personal Info
+  </header>
+  <wa-input label="Name" style="margin-bottom: .5rem;"></wa-input>
+  <wa-input label="Email" type="email"></wa-input>
+</wa-card>
+```
+
+### Force visually hidden
+
+There are cases where you want to _always_ visually hide certain content, even when it's focused.
+For example when hiding a checkbox to render a custom one:
+
+```html {.example}
+<label>
+  <span class="checkbox">
+    <input type="checkbox" class="wa-visually-hidden-force" />
+  </span>
+  I have read the terms and conditions
+</label>
+
+<style>
+.checkbox {
+  display: inline-flex;
+  vertical-align: middle;
+  width: var(--wa-font-size-l);
+  height: var(--wa-font-size-l);
+  background: var(--wa-color-neutral-fill-quiet);
+  color: var(--wa-color-neutral-on-quiet);
+  border-radius: var(--wa-border-radius-xs);
+  margin-inline-end: var(--wa-space-xs);
+
+  &::after {
+    content: "✓" / "";
+    margin: auto;
+    transition: opacity var(--wa-transition-slow) var(--wa-transition-easing);
+  }
+
+  &:has(:checked) {
+    background: var(--wa-color-brand-fill-loud);
+    color: var(--wa-color-brand-on-loud);
+  }
+
+  &:not(:has(:checked)) {
+    &::after {
+      opacity: 0;
+    }
+  }
+
+  &:focus-within {
+    outline: var(--wa-focus-ring);
+    outline-offset: var(--wa-focus-ring-offset);
+  }
+}
+</style>
+```
diff --git a/src/components/color-picker/color-picker.ts b/src/components/color-picker/color-picker.ts
index fe149b4df..4dfb99d7e 100644
--- a/src/components/color-picker/color-picker.ts
+++ b/src/components/color-picker/color-picker.ts
@@ -18,6 +18,7 @@ import { watch } from '../../internal/watch.js';
 import { WebAwesomeFormAssociatedElement } from '../../internal/webawesome-element.js';
 import formControlStyles from '../../styles/shadow/form-control.css';
 import sizeStyles from '../../styles/utilities/size.css';
+import visuallyHidden from '../../styles/utilities/visually-hidden.css';
 import { LocalizeController } from '../../utilities/localize.js';
 import '../button-group/button-group.js';
 import '../button/button.js';
@@ -26,7 +27,6 @@ import type WaDropdown from '../dropdown/dropdown.js';
 import '../icon/icon.js';
 import '../input/input.js';
 import type WaInput from '../input/input.js';
-import '../visually-hidden/visually-hidden.js';
 import styles from './color-picker.css';
 
 interface EyeDropperConstructor {
@@ -106,7 +106,7 @@ declare const EyeDropper: EyeDropperConstructor;
  */
 @customElement('wa-color-picker')
 export default class WaColorPicker extends WebAwesomeFormAssociatedElement {
-  static shadowStyle = [sizeStyles, formControlStyles, styles];
+  static shadowStyle = [visuallyHidden, sizeStyles, formControlStyles, styles];
 
   static shadowRootOptions = { ...WebAwesomeFormAssociatedElement.shadowRootOptions, delegatesFocus: true };
 
diff --git a/src/components/copy-button/copy-button.ts b/src/components/copy-button/copy-button.ts
index c2bb8f60b..324295dae 100644
--- a/src/components/copy-button/copy-button.ts
+++ b/src/components/copy-button/copy-button.ts
@@ -5,11 +5,11 @@ import { WaCopyEvent } from '../../events/copy.js';
 import { WaErrorEvent } from '../../events/error.js';
 import { animateWithClass } from '../../internal/animate.js';
 import WebAwesomeElement from '../../internal/webawesome-element.js';
+import visuallyHidden from '../../styles/utilities/visually-hidden.css';
 import { LocalizeController } from '../../utilities/localize.js';
 import '../icon/icon.js';
 import '../tooltip/tooltip.js';
 import type WaTooltip from '../tooltip/tooltip.js';
-import '../visually-hidden/visually-hidden.js';
 import styles from './copy-button.css';
 
 /**
@@ -44,7 +44,7 @@ import styles from './copy-button.css';
  */
 @customElement('wa-copy-button')
 export default class WaCopyButton extends WebAwesomeElement {
-  static shadowStyle = styles;
+  static shadowStyle = [visuallyHidden, styles];
 
   private readonly localize = new LocalizeController(this);
 
@@ -201,7 +201,7 @@ export default class WaCopyButton extends WebAwesomeElement {
         @click=${this.handleCopy}
       >
         <!-- Render a visually hidden label to appease the accessibility checking gods -->
-        <wa-visually-hidden>${this.currentLabel}</wa-visually-hidden>
+        <span class="wa-visually-hidden">${this.currentLabel}</span>
         <slot part="copy-icon" name="copy-icon">
           <wa-icon library="system" name="copy" variant="regular" fixed-width></wa-icon>
         </slot>
diff --git a/src/components/page/page.css b/src/components/page/page.css
index f3455e7de..928501763 100644
--- a/src/components/page/page.css
+++ b/src/components/page/page.css
@@ -195,19 +195,6 @@ slot:not([name]) {
   grid-area: main-footer;
 }
 
-/* Visually hidden */
-.skip-to-content:not(:focus-within) {
-  position: absolute !important;
-  width: 1px !important;
-  height: 1px !important;
-  clip: rect(0 0 0 0) !important;
-  clip-path: inset(50%) !important;
-  border: none !important;
-  overflow: hidden !important;
-  white-space: nowrap !important;
-  padding: 0 !important;
-}
-
 .skip-to-content {
   position: absolute;
   top: var(--wa-space-m);
diff --git a/src/components/page/page.ts b/src/components/page/page.ts
index 7dbaf6915..43e3795bc 100644
--- a/src/components/page/page.ts
+++ b/src/components/page/page.ts
@@ -4,6 +4,7 @@ import { live } from 'lit/directives/live.js';
 import { unsafeHTML } from 'lit/directives/unsafe-html.js';
 import { toLength, toPx } from '../../internal/css-values.js';
 import WebAwesomeElement from '../../internal/webawesome-element.js';
+import visuallyHidden from '../../styles/utilities/visually-hidden.css';
 import styles from './page.css';
 import mobileStyles from './page.mobile.styles.js';
 
@@ -78,7 +79,7 @@ if (typeof ResizeObserver === 'undefined') {
  */
 @customElement('wa-page')
 export default class WaPage extends WebAwesomeElement {
-  static shadowStyle = styles;
+  static shadowStyle = [visuallyHidden, styles];
 
   private headerResizeObserver = this.slotResizeObserver('header');
   private subheaderResizeObserver = this.slotResizeObserver('subheader');
@@ -262,7 +263,7 @@ export default class WaPage extends WebAwesomeElement {
 
   render() {
     return html`
-      <a href="#main-content" part="skip-to-content" class="skip-to-content">
+      <a href="#main-content" part="skip-to-content" class="wa-visually-hidden">
         <slot name="skip-to-content">Skip to content</slot>
       </a>
 
diff --git a/src/components/visually-hidden/visually-hidden.css b/src/components/visually-hidden/visually-hidden.css
deleted file mode 100644
index 82b5a99b7..000000000
--- a/src/components/visually-hidden/visually-hidden.css
+++ /dev/null
@@ -1,11 +0,0 @@
-:host(:not(:focus-within)) {
-  position: absolute !important;
-  width: 1px !important;
-  height: 1px !important;
-  clip: rect(0 0 0 0) !important;
-  clip-path: inset(50%) !important;
-  border: none !important;
-  overflow: hidden !important;
-  white-space: nowrap !important;
-  padding: 0 !important;
-}
diff --git a/src/components/visually-hidden/visually-hidden.test.ts b/src/components/visually-hidden/visually-hidden.test.ts
deleted file mode 100644
index 27cfda2eb..000000000
--- a/src/components/visually-hidden/visually-hidden.test.ts
+++ /dev/null
@@ -1,43 +0,0 @@
-import { expect } from '@open-wc/testing';
-import { html } from 'lit';
-import { fixtures } from '../../internal/test/fixture.js';
-
-describe('<wa-visually-hidden>', () => {
-  for (const fixture of fixtures) {
-    describe(`with "${fixture.type}" rendering`, () => {
-      it('should render but not display visually hidden content', async () => {
-        const el = await fixture(html`
-          <wa-visually-hidden>
-            <a href="#">Skip to main content</a>
-          </wa-visually-hidden>
-        `);
-
-        const { width, height, overflow, clipPath } = getComputedStyle(el);
-
-        expect(width).to.equal('1px');
-        expect(height).to.equal('1px');
-        expect(overflow).to.equal('hidden');
-        expect(clipPath).to.equal('inset(50%)');
-      });
-
-      // should show visually hidden content when focused
-      it('should show visually hidden content when focused', async () => {
-        const el = await fixture(html`
-          <wa-visually-hidden>
-            <a href="#">Skip to main content</a>
-          </wa-visually-hidden>
-        `);
-
-        const a = el.querySelector('a')!;
-        a.focus();
-
-        const { width, height, overflow, clipPath } = getComputedStyle(el);
-
-        expect(width).not.to.equal('1px');
-        expect(height).not.to.equal('1px');
-        expect(overflow).not.to.equal('hidden');
-        expect(clipPath).not.to.equal('inset(50%)');
-      });
-    });
-  }
-});
diff --git a/src/components/visually-hidden/visually-hidden.ts b/src/components/visually-hidden/visually-hidden.ts
deleted file mode 100644
index a0adb9ce7..000000000
--- a/src/components/visually-hidden/visually-hidden.ts
+++ /dev/null
@@ -1,27 +0,0 @@
-import { html } from 'lit';
-import { customElement } from 'lit/decorators.js';
-import WebAwesomeElement from '../../internal/webawesome-element.js';
-import styles from './visually-hidden.css';
-
-/**
- * @summary The visually hidden utility makes content accessible to assistive devices without displaying it on the screen.
- * @documentation https://backers.webawesome.com/docs/components/visually-hidden
- * @status stable
- * @since 2.0
- *
- * @slot - The content to be visually hidden.
- */
-@customElement('wa-visually-hidden')
-export default class WaVisuallyHidden extends WebAwesomeElement {
-  static shadowStyle = styles;
-
-  render() {
-    return html` <slot></slot> `;
-  }
-}
-
-declare global {
-  interface HTMLElementTagNameMap {
-    'wa-visually-hidden': WaVisuallyHidden;
-  }
-}