houser-js-utils
Version:
A comprehensive collection of TypeScript utility functions for common development tasks including array manipulation, string processing, date handling, random number generation, validation, and much more.
178 lines (177 loc) • 6 kB
TypeScript
/**
* @module AccessibilityUtils
* @description A collection of utility functions for improving web accessibility, ARIA management, and inclusive design.
* Provides methods for handling ARIA attributes, focus management, and keyboard navigation.
*
* @example
* ```typescript
* import { AccessibilityUtils } from 'houser-js-utils';
*
* // Set ARIA attributes
* AccessibilityUtils.setAriaLabel(element, 'Close dialog');
*
* // Manage focus
* AccessibilityUtils.trapFocus(modalElement);
*
* // Check accessibility
* const isAccessible = AccessibilityUtils.hasValidAriaLabels(form);
* ```
*/
export declare const AccessibilityUtils: {
/**
* Gets the ARIA described by attribute of an element
* @param element - The DOM element to check
* @returns The value of aria-describedby attribute or null if not set
* @example
* ```typescript
* const element = document.querySelector('.input');
* const describedBy = AccessibilityUtils.getAriaDescribedBy(element);
* ```
*/
getAriaDescribedBy(element: Element): string | null;
/**
* Sets the ARIA described by attribute of an element
* @param element - The DOM element to modify
* @param describedBy - The ID(s) of the element(s) that describe this element
* @example
* ```typescript
* const input = document.querySelector('.input');
* const helpText = document.querySelector('.help-text');
* AccessibilityUtils.setAriaDescribedBy(input, helpText.id);
* ```
*/
setAriaDescribedBy(element: Element, describedBy: string): void;
/**
* Gets the ARIA expanded state of an element
* @param element - Element to check
* @returns ARIA expanded state
*/
getAriaExpanded(element: Element): boolean | null;
/**
* Sets the ARIA expanded state of an element
* @param element - Element to modify
* @param expanded - ARIA expanded state to set
*/
setAriaExpanded(element: Element, expanded: boolean): void;
/**
* Gets the ARIA hidden state of an element
* @param element - Element to check
* @returns ARIA hidden state
*/
getAriaHidden(element: Element): boolean | null;
/**
* Sets the ARIA hidden state of an element
* @param element - Element to modify
* @param hidden - ARIA hidden state to set
*/
setAriaHidden(element: Element, hidden: boolean): void;
/**
* Gets the ARIA invalid state of an element
* @param element - Element to check
* @returns ARIA invalid state
*/
getAriaInvalid(element: Element): boolean | null;
/**
* Sets the ARIA invalid state of an element
* @param element - Element to modify
* @param invalid - ARIA invalid state to set
*/
setAriaInvalid(element: Element, invalid: boolean): void;
/**
* Gets the ARIA label of an element
* @param element - Element to check
* @returns ARIA label
*/
getAriaLabel(element: Element): string | null;
/**
* Sets the ARIA label of an element
* @param element - Element to modify
* @param label - ARIA label to set
*/
setAriaLabel(element: Element, label: string): void;
/**
* Gets the ARIA required state of an element
* @param element - Element to check
* @returns ARIA required state
*/
getAriaRequired(element: Element): boolean | null;
/**
* Sets the ARIA required state of an element
* @param element - Element to modify
* @param required - ARIA required state to set
*/
setAriaRequired(element: Element, required: boolean): void;
/**
* Gets the ARIA role of an element
* @param element - Element to check
* @returns ARIA role
*/
getAriaRole(element: Element): string | null;
/**
* Sets the ARIA role of an element
* @param element - Element to modify
* @param role - ARIA role to set
*/
setAriaRole(element: Element, role: string): void;
/**
* Removes focus from an element
* @param element - Element to blur
*/
blurElement(element: Element): void;
/**
* Sets focus to an element
* @param element - Element to focus
*/
focusElement(element: Element): void;
/**
* Sets focus to the first focusable element in a container
* @param container - Container element
*/
focusFirstElement(container: Element): void;
/**
* Sets focus to the last focusable element in a container
* @param container - Container element
*/
focusLastElement(container: Element): void;
/**
* Sets focus to the next focusable element
* @param currentElement - Current element
*/
focusNextElement(currentElement: Element): void;
/**
* Sets focus to the previous focusable element
* @param currentElement - Current element
*/
focusPreviousElement(currentElement: Element): void;
/**
* Gets all focusable elements within a container
* @param container - Container element
* @returns Array of focusable elements
*/
getFocusableElements(container: Element): Element[];
/**
* Gets the current focus element
* @returns Currently focused element
*/
getFocusedElement(): Element | null;
/**
* Checks if an element is focusable
* @param element - Element to check
* @returns True if element is focusable
*/
isFocusable(element: Element): boolean;
/**
* Traps focus within a container element, typically used for modals or dialogs
* @param container - The container element to trap focus within
* @returns A function that removes the focus trap when called
* @example
* ```typescript
* const modal = document.querySelector('.modal');
* const removeTrap = AccessibilityUtils.trapFocus(modal);
*
* // Later, when the modal is closed:
* removeTrap();
* ```
*/
trapFocus(container: Element): () => void;
};