diff --git a/docs/_sidebar.md b/docs/_sidebar.md index e0f2f129..42f07668 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -69,6 +69,7 @@ - [Relative Time](/components/relative-time) - [Resize Observer](/components/resize-observer) - [Responsive Media](/components/responsive-media) + - [Visually Hidden](/components/visually-hidden) - Design Tokens - [Typography](/tokens/typography) diff --git a/docs/components/visually-hidden.md b/docs/components/visually-hidden.md new file mode 100644 index 00000000..caf2185c --- /dev/null +++ b/docs/components/visually-hidden.md @@ -0,0 +1,47 @@ +# Visually Hidden + +[component-header:sl-visually-hidden] + +The visually hidden utility makes content accessible to assistive devices without displaying it on the screen. + +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 keyboards user won't be able to determine where the focus indicator is without it. + +```html preview +
+ + Skip to main content + +
+``` + +## 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 preview + + Visit External Page + + opens in a new window + +``` + +### Content Conveyed By Context + +Adding a title or 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. + +```html preview + +
+ Personal Info +
+ + + +``` + +[component-metadata:sl-visually-hidden] diff --git a/docs/resources/changelog.md b/docs/resources/changelog.md index 11e63493..99a8156e 100644 --- a/docs/resources/changelog.md +++ b/docs/resources/changelog.md @@ -8,10 +8,12 @@ _During the beta period, these restrictions may be relaxed in the event of a mis ## Next +- Added experimental `` component - Improved a11y of `` by representing it as an image with an `alt` [#579](https://github.com/shoelace-style/shoelace/issues/579) - Improved a11y of the scroll buttons in `` - Improved a11y of the close button in `` - Improved a11y of `` by removing an invalid `aria-selected` attribute [#579](https://github.com/shoelace-style/shoelace/issues/579) +- Improved a11y of `` by not using a variation of the `name` attribute for labels (use the `label` prop instead) - Moved `role` from the shadow root to the host element in `` - Removed redundant `role="menu"` in `` - Slightly faster animations for showing and hiding `` @@ -78,7 +80,7 @@ Shoelace doesn't have a lot of dependencies, but this release unbundles most of ## 2.0.0-beta.53 - 🚨 BREAKING: removed `` (use `` instead) -- 🚨 BREAKING: removed `percentage` attribute from `` and `` (use `value`) instead +- 🚨 BREAKING: removed `percentage` attribute from `` and `` (use `value` instead) - 🚨 BREAKING: switched the default `type` of `` from `primary` to `neutral` - Added the experimental `` component - Added the `` component diff --git a/src/components/visually-hidden/visually-hidden.styles.ts b/src/components/visually-hidden/visually-hidden.styles.ts new file mode 100644 index 00000000..fda6bce7 --- /dev/null +++ b/src/components/visually-hidden/visually-hidden.styles.ts @@ -0,0 +1,18 @@ +import { css } from 'lit'; +import componentStyles from '../../styles/component.styles'; + +export default css` + ${componentStyles} + + :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 new file mode 100644 index 00000000..29a6032d --- /dev/null +++ b/src/components/visually-hidden/visually-hidden.test.ts @@ -0,0 +1,13 @@ +import { expect, fixture, html, waitUntil } from '@open-wc/testing'; +// import sinon from 'sinon'; + +import '../../../dist/shoelace.js'; +import type SlVisuallyHidden from './visually-hidden'; + +describe('', () => { + it('should render a component', async () => { + const el = await fixture(html` `); + + expect(el).to.exist; + }); +}); diff --git a/src/components/visually-hidden/visually-hidden.ts b/src/components/visually-hidden/visually-hidden.ts new file mode 100644 index 00000000..92f1f879 --- /dev/null +++ b/src/components/visually-hidden/visually-hidden.ts @@ -0,0 +1,24 @@ +import { LitElement, html } from 'lit'; +import { customElement } from 'lit/decorators.js'; +import styles from './visually-hidden.styles'; + +/** + * @since 2.0 + * @status experimental + * + * @slot - The content you'd like to be visually hidden. + */ +@customElement('sl-visually-hidden') +export default class SlVisuallyHidden extends LitElement { + static styles = styles; + + render() { + return html` `; + } +} + +declare global { + interface HTMLElementTagNameMap { + 'sl-visually-hidden': SlVisuallyHidden; + } +} diff --git a/src/shoelace.ts b/src/shoelace.ts index ade7c5ae..9d644a9f 100644 --- a/src/shoelace.ts +++ b/src/shoelace.ts @@ -49,6 +49,7 @@ export { default as SlTabPanel } from './components/tab-panel/tab-panel'; export { default as SlTag } from './components/tag/tag'; export { default as SlTextarea } from './components/textarea/textarea'; export { default as SlTooltip } from './components/tooltip/tooltip'; +export { default as SlVisuallyHidden } from './components/visually-hidden/visually-hidden'; /* plop:component */ // Utilities