Sa11y Accessibility Assistant

Sa11y is a customizable, framework-agnostic JavaScript plugin designed for accessibility quality assurance. It functions as an in-page checker that visually highlights common accessibility and usability issues directly on the page.

Key Characteristics:

• Target Audience: Geared towards content authors by providing simple tooltips on how to fix identified errors.
• Scope: It is not a comprehensive code analysis tool; it focuses exclusively on highlighting content issues.
• Automation: Automatically checks content on page load.
• Customization: Uses JSON-like props to fine-tune the experience and allows turning off or hiding irrelevant checks.
• Capabilities: Supports checking items within web components/shadow DOM and headless checks.
• UI: Features a fully encapsulated user interface with dark mode support and multi-language availability.

For advanced UI tasks like generating issue reports or cloning parts of the DOM:

• fnIgnore(element, selectors): Creates a clone of an element while excluding specific tags (defaulting to noscript, script, style, audio, video, form, iframe) or any additional selectors provided.
• generateElementPreview(issueObject, convertBase64): Generates a DOM node preview for an issue. For <img> tags, it can optionally fetch the image and convert it to a Base64 string to ensure the preview is self-contained.

Use these utilities to extract clean text from DOM nodes:

• getText(element): Retrieves the textContent of an element, but uses fnIgnore to skip elements like <script> or <style>, and normalizes whitespace/line breaks. It uses an internal WeakMap to cache results for performance.
• removeWhitespace(string): Collapses multiple whitespace characters into a single space and trims the string.
• normalizeString(string): Removes non-printable ASCII control characters and extra whitespace.

Standard developer utilities included in the package:

• debounce(callback, wait): Returns a debounced version of the provided callback.
• store: A utility object for interacting with localStorage and sessionStorage. store.getItem(key) attempts to fetch from localStorage first, falling back to sessionStorage if not found.
• getCachedStyle(node, pseudoElt): Returns the computed style of a node, using a WeakMap to cache results and avoid redundant getComputedStyle calls.
• supportsAnchorPositioning(): Checks if the browser supports the CSS Anchor Positioning API.

The dismissDigest function generates a lowercase hexadecimal SHA-256 digest from a combination of a pepper (a secret or application-specific salt) and a message (an identifier). This is primarily used to create unique, stable keys for dismissing accessibility messages within localStorage.

import { dismissDigest } from './utils';

const digest = await dismissDigest('my-secret-pepper', 'accessibility-error-id-123');
// returns a lowercase hex string

The Sa11y instance provides two primary getters for inspecting the state of an accessibility audit:

• results: Returns the main array of audit results stored in the internal State.
• elements: Returns the collection of elements identified by the tool (via Found.Found).

The wrapPseudoContent utility extracts text content from an element's :before and :after pseudo-elements and wraps a provided string with them.

Parameters:

• element (Element): The target DOM element.
• string (string): The base string to wrap with pseudo-element content.

Returns:

• string: A string formatted as [before-content][string][after-content].

Note on Content Extraction: It specifically looks for text within quotes in the CSS content property. For example, if a pseudo-element has content: "icon";, it extracts icon.

import { wrapPseudoContent } from './path/to/computeAccessibleName';

// If :before { content: "★"; } and :after { content: " text"; }
const result = wrapPseudoContent(element, 'Hello');
// result would be "★Hello text"

To use Sa11y, instantiate the Sa11y class with an options object. The constructor sets the initial state via setState and runs the initialize() routine. Upon instantiation, the Sa11y instance exposes several utility methods directly on itself, including checkAll, resetAll, find, enabled, and disabled, as well as all methods from the Utils module.

Use the results getter to access the main array of accessibility audit results and the elements getter to access the list of elements found during the audit.

import { Sa11y } from './js/sa11y';

const sa11y = new Sa11y({
  // pass your configuration options here
});

// Access audit results
console.log(sa11y.results);

// Access found elements
console.log(sa11y.elements);

// Use exposed utility methods
sa11y.checkAll();