@compa11y/core 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,241 @@
+import { D as DevWarningHandler, a as DevWarning } from './types-DDSPmE8m.cjs';
+export { A as AnnouncerOptions, b as AriaLivePoliteness, c as AriaRole, F as FocusTrapOptions, d as FocusableElement, K as KeyboardNavigationOptions } from './types-DDSPmE8m.cjs';
+export { FocusScope, FocusScopeOptions, RovingTabindex, RovingTabindexOptions, createFocusScope, createFocusTrap, createRovingTabindex, focusWithVisibleRing, getActiveFocusTrap, getLastFocusSource, hasFocusTrap, hasVisibleFocus, initFocusVisible, isFocusVisible, setFocusVisible } from './focus/index.cjs';
+export { KeyboardHandler, KeyboardHandlers, KeyboardManager, KeyboardManagerOptions, KeyboardPatterns, TypeAhead, createKeyboardManager, createTypeAhead, getKeyCombo, normalizeKey } from './keyboard/index.cjs';
+export { announce, announceAssertive, announceError, announcePolite, announceProgress, announceStatus, clearAnnouncements, createAnnouncer, initAnnouncer, queueAnnouncement } from './announcer/index.cjs';
+export { aria, buildAriaProps, hasAccessibleName, mergeAriaIds } from './aria/index.cjs';
+
+/**
+ * ID generation utilities for accessible components
+ *
+ * Generates unique, predictable IDs for ARIA relationships
+ */
+/**
+ * Generate a unique ID with optional prefix
+ */
+declare function generateId(prefix?: string): string;
+/**
+ * Generate a set of related IDs for a component
+ * Useful for complex components with multiple ARIA relationships
+ */
+declare function generateIds<T extends readonly string[]>(parts: T, prefix?: string): Record<T[number], string>;
+/**
+ * Reset the ID counter (useful for testing)
+ */
+declare function resetIdCounter(): void;
+/**
+ * Create a scoped ID generator for a component instance
+ */
+declare function createIdScope(componentName: string): {
+    id: string;
+    generate: (suffix: string) => string;
+    generateMultiple: <T extends readonly string[]>(parts: T) => Record<T[number], string>;
+};
+
+/**
+ * DOM utilities for accessibility
+ */
+/**
+ * Focusable element selectors
+ * Based on WHATWG focus management spec
+ */
+declare const FOCUSABLE_SELECTORS: string;
+/**
+ * Tabbable element selectors (subset of focusable that can be tabbed to)
+ */
+declare const TABBABLE_SELECTORS: string;
+/**
+ * Check if an element is visible (not hidden by CSS)
+ */
+declare function isVisible(element: Element): boolean;
+/**
+ * Check if an element is focusable
+ */
+declare function isFocusable(element: Element): boolean;
+/**
+ * Check if an element is tabbable (can receive focus via Tab key)
+ */
+declare function isTabbable(element: Element): boolean;
+/**
+ * Get all focusable elements within a container
+ */
+declare function getFocusableElements(container: HTMLElement): HTMLElement[];
+/**
+ * Get all tabbable elements within a container (sorted by tabIndex)
+ */
+declare function getTabbableElements(container: HTMLElement): HTMLElement[];
+/**
+ * Get the first focusable element in a container
+ */
+declare function getFirstFocusable(container: HTMLElement): HTMLElement | null;
+/**
+ * Get the last focusable element in a container
+ */
+declare function getLastFocusable(container: HTMLElement): HTMLElement | null;
+/**
+ * Check if an element contains the currently focused element
+ */
+declare function containsFocus(container: HTMLElement): boolean;
+/**
+ * Get the next focusable element
+ */
+declare function getNextFocusable(container: HTMLElement, current: HTMLElement, wrap?: boolean): HTMLElement | null;
+/**
+ * Get the previous focusable element
+ */
+declare function getPreviousFocusable(container: HTMLElement, current: HTMLElement, wrap?: boolean): HTMLElement | null;
+/**
+ * Check if element is within a specific container
+ */
+declare function isWithinContainer(element: Element, container: Element): boolean;
+/**
+ * Query for an element, supporting various input types
+ */
+declare function resolveElement<T extends HTMLElement = HTMLElement>(target: T | string | (() => T | null) | null | undefined, container?: HTMLElement): T | null;
+
+/**
+ * Platform detection utilities
+ *
+ * Used for platform-specific accessibility behavior
+ */
+/**
+ * Check if we're in a browser environment
+ */
+declare function isBrowser(): boolean;
+/**
+ * Detect if running on macOS
+ */
+declare function isMac(): boolean;
+/**
+ * Detect if running on iOS
+ */
+declare function isIOS(): boolean;
+/**
+ * Detect if running on Android
+ */
+declare function isAndroid(): boolean;
+/**
+ * Detect if running on Windows
+ */
+declare function isWindows(): boolean;
+/**
+ * Detect if using a touch device
+ */
+declare function isTouchDevice(): boolean;
+/**
+ * Detect if user prefers reduced motion
+ */
+declare function prefersReducedMotion(): boolean;
+/**
+ * Detect if user prefers high contrast
+ */
+declare function prefersHighContrast(): boolean;
+/**
+ * Detect if user prefers dark color scheme
+ */
+declare function prefersDarkMode(): boolean;
+/**
+ * Get the current screen reader mode (if detectable)
+ * Note: This is not 100% reliable and should not be depended upon
+ */
+declare function getScreenReaderHints(): {
+    possibleScreenReader: boolean;
+    forcedColors: boolean;
+};
+/**
+ * Create a media query listener with cleanup
+ */
+declare function createMediaQueryListener(query: string, callback: (matches: boolean) => void): () => void;
+
+/**
+ * Developer Warnings System
+ *
+ * Provides development-time feedback for accessibility issues
+ */
+
+/**
+ * Set a custom warning handler
+ */
+declare function setWarningHandler(handler: DevWarningHandler | null): void;
+/**
+ * Issue a development warning
+ */
+declare function warn(warning: DevWarning): void;
+/**
+ * Clear issued warnings (useful for testing)
+ */
+declare function clearWarnings(): void;
+/**
+ * Pre-built warning checks
+ */
+declare const checks: {
+    /**
+     * Check for missing accessible label
+     */
+    accessibleLabel(element: HTMLElement | null, component: string, propName?: string): void;
+    /**
+     * Check for missing required prop
+     */
+    requiredProp(value: unknown, propName: string, component: string): void;
+    /**
+     * Check for invalid ARIA role
+     */
+    validRole(role: string | undefined, component: string, element?: HTMLElement): void;
+    /**
+     * Check for interactive element without keyboard support
+     */
+    keyboardAccessible(element: HTMLElement | null, component: string, handlers: {
+        onClick?: unknown;
+        onKeyDown?: unknown;
+    }): void;
+    /**
+     * Check tabIndex usage
+     */
+    tabIndex(tabIndex: number | undefined, component: string, element?: HTMLElement): void;
+    /**
+     * Check for autofocus in dialogs
+     */
+    dialogAutoFocus(hasAutoFocus: boolean, component: string): void;
+    /**
+     * Check for missing form labels
+     */
+    formLabel(inputElement: HTMLElement | null, labelId: string | undefined, component: string): void;
+    /**
+     * Check for missing alt text on images
+     */
+    imageAlt(element: HTMLElement | null, component: string): void;
+};
+/**
+ * Create a component-scoped warning function
+ */
+declare function createComponentWarnings(componentName: string): {
+    error: (message: string, suggestion?: string, element?: Element) => void;
+    warning: (message: string, suggestion?: string, element?: Element) => void;
+    info: (message: string, suggestion?: string, element?: Element) => void;
+    checks: {
+        accessibleLabel: (element: HTMLElement | null, propName?: string) => void;
+        requiredProp: (value: unknown, propName: string) => void;
+        keyboardAccessible: (element: HTMLElement | null, handlers: {
+            onClick?: unknown;
+            onKeyDown?: unknown;
+        }) => void;
+        tabIndex: (tabIndex: number | undefined, element?: HTMLElement) => void;
+    };
+};
+
+/**
+ * @compa11y/core
+ *
+ * Framework-agnostic accessibility primitives
+ *
+ * This package provides the foundational utilities used by all
+ * compa11y packages (React, Web Components, etc.)
+ */
+
+/**
+ * Initialize all compa11y systems
+ * Call this once at app startup for optimal behavior
+ */
+declare function initA11yKit(): () => void;
+
+export { DevWarning, DevWarningHandler, FOCUSABLE_SELECTORS, TABBABLE_SELECTORS, checks, clearWarnings, containsFocus, createComponentWarnings, createIdScope, createMediaQueryListener, generateId, generateIds, getFirstFocusable, getFocusableElements, getLastFocusable, getNextFocusable, getPreviousFocusable, getScreenReaderHints, getTabbableElements, initA11yKit, isAndroid, isBrowser, isFocusable, isIOS, isMac, isTabbable, isTouchDevice, isVisible, isWindows, isWithinContainer, prefersDarkMode, prefersHighContrast, prefersReducedMotion, resetIdCounter, resolveElement, setWarningHandler, warn };

package/dist/index.d.ts

@@ -0,0 +1,241 @@
+import { D as DevWarningHandler, a as DevWarning } from './types-DDSPmE8m.js';
+export { A as AnnouncerOptions, b as AriaLivePoliteness, c as AriaRole, F as FocusTrapOptions, d as FocusableElement, K as KeyboardNavigationOptions } from './types-DDSPmE8m.js';
+export { FocusScope, FocusScopeOptions, RovingTabindex, RovingTabindexOptions, createFocusScope, createFocusTrap, createRovingTabindex, focusWithVisibleRing, getActiveFocusTrap, getLastFocusSource, hasFocusTrap, hasVisibleFocus, initFocusVisible, isFocusVisible, setFocusVisible } from './focus/index.js';
+export { KeyboardHandler, KeyboardHandlers, KeyboardManager, KeyboardManagerOptions, KeyboardPatterns, TypeAhead, createKeyboardManager, createTypeAhead, getKeyCombo, normalizeKey } from './keyboard/index.js';
+export { announce, announceAssertive, announceError, announcePolite, announceProgress, announceStatus, clearAnnouncements, createAnnouncer, initAnnouncer, queueAnnouncement } from './announcer/index.js';
+export { aria, buildAriaProps, hasAccessibleName, mergeAriaIds } from './aria/index.js';
+
+/**
+ * ID generation utilities for accessible components
+ *
+ * Generates unique, predictable IDs for ARIA relationships
+ */
+/**
+ * Generate a unique ID with optional prefix
+ */
+declare function generateId(prefix?: string): string;
+/**
+ * Generate a set of related IDs for a component
+ * Useful for complex components with multiple ARIA relationships
+ */
+declare function generateIds<T extends readonly string[]>(parts: T, prefix?: string): Record<T[number], string>;
+/**
+ * Reset the ID counter (useful for testing)
+ */
+declare function resetIdCounter(): void;
+/**
+ * Create a scoped ID generator for a component instance
+ */
+declare function createIdScope(componentName: string): {
+    id: string;
+    generate: (suffix: string) => string;
+    generateMultiple: <T extends readonly string[]>(parts: T) => Record<T[number], string>;
+};
+
+/**
+ * DOM utilities for accessibility
+ */
+/**
+ * Focusable element selectors
+ * Based on WHATWG focus management spec
+ */
+declare const FOCUSABLE_SELECTORS: string;
+/**
+ * Tabbable element selectors (subset of focusable that can be tabbed to)
+ */
+declare const TABBABLE_SELECTORS: string;
+/**
+ * Check if an element is visible (not hidden by CSS)
+ */
+declare function isVisible(element: Element): boolean;
+/**
+ * Check if an element is focusable
+ */
+declare function isFocusable(element: Element): boolean;
+/**
+ * Check if an element is tabbable (can receive focus via Tab key)
+ */
+declare function isTabbable(element: Element): boolean;
+/**
+ * Get all focusable elements within a container
+ */
+declare function getFocusableElements(container: HTMLElement): HTMLElement[];
+/**
+ * Get all tabbable elements within a container (sorted by tabIndex)
+ */
+declare function getTabbableElements(container: HTMLElement): HTMLElement[];
+/**
+ * Get the first focusable element in a container
+ */
+declare function getFirstFocusable(container: HTMLElement): HTMLElement | null;
+/**
+ * Get the last focusable element in a container
+ */
+declare function getLastFocusable(container: HTMLElement): HTMLElement | null;
+/**
+ * Check if an element contains the currently focused element
+ */
+declare function containsFocus(container: HTMLElement): boolean;
+/**
+ * Get the next focusable element
+ */
+declare function getNextFocusable(container: HTMLElement, current: HTMLElement, wrap?: boolean): HTMLElement | null;
+/**
+ * Get the previous focusable element
+ */
+declare function getPreviousFocusable(container: HTMLElement, current: HTMLElement, wrap?: boolean): HTMLElement | null;
+/**
+ * Check if element is within a specific container
+ */
+declare function isWithinContainer(element: Element, container: Element): boolean;
+/**
+ * Query for an element, supporting various input types
+ */
+declare function resolveElement<T extends HTMLElement = HTMLElement>(target: T | string | (() => T | null) | null | undefined, container?: HTMLElement): T | null;
+
+/**
+ * Platform detection utilities
+ *
+ * Used for platform-specific accessibility behavior
+ */
+/**
+ * Check if we're in a browser environment
+ */
+declare function isBrowser(): boolean;
+/**
+ * Detect if running on macOS
+ */
+declare function isMac(): boolean;
+/**
+ * Detect if running on iOS
+ */
+declare function isIOS(): boolean;
+/**
+ * Detect if running on Android
+ */
+declare function isAndroid(): boolean;
+/**
+ * Detect if running on Windows
+ */
+declare function isWindows(): boolean;
+/**
+ * Detect if using a touch device
+ */
+declare function isTouchDevice(): boolean;
+/**
+ * Detect if user prefers reduced motion
+ */
+declare function prefersReducedMotion(): boolean;
+/**
+ * Detect if user prefers high contrast
+ */
+declare function prefersHighContrast(): boolean;
+/**
+ * Detect if user prefers dark color scheme
+ */
+declare function prefersDarkMode(): boolean;
+/**
+ * Get the current screen reader mode (if detectable)
+ * Note: This is not 100% reliable and should not be depended upon
+ */
+declare function getScreenReaderHints(): {
+    possibleScreenReader: boolean;
+    forcedColors: boolean;
+};
+/**
+ * Create a media query listener with cleanup
+ */
+declare function createMediaQueryListener(query: string, callback: (matches: boolean) => void): () => void;
+
+/**
+ * Developer Warnings System
+ *
+ * Provides development-time feedback for accessibility issues
+ */
+
+/**
+ * Set a custom warning handler
+ */
+declare function setWarningHandler(handler: DevWarningHandler | null): void;
+/**
+ * Issue a development warning
+ */
+declare function warn(warning: DevWarning): void;
+/**
+ * Clear issued warnings (useful for testing)
+ */
+declare function clearWarnings(): void;
+/**
+ * Pre-built warning checks
+ */
+declare const checks: {
+    /**
+     * Check for missing accessible label
+     */
+    accessibleLabel(element: HTMLElement | null, component: string, propName?: string): void;
+    /**
+     * Check for missing required prop
+     */
+    requiredProp(value: unknown, propName: string, component: string): void;
+    /**
+     * Check for invalid ARIA role
+     */
+    validRole(role: string | undefined, component: string, element?: HTMLElement): void;
+    /**
+     * Check for interactive element without keyboard support
+     */
+    keyboardAccessible(element: HTMLElement | null, component: string, handlers: {
+        onClick?: unknown;
+        onKeyDown?: unknown;
+    }): void;
+    /**
+     * Check tabIndex usage
+     */
+    tabIndex(tabIndex: number | undefined, component: string, element?: HTMLElement): void;
+    /**
+     * Check for autofocus in dialogs
+     */
+    dialogAutoFocus(hasAutoFocus: boolean, component: string): void;
+    /**
+     * Check for missing form labels
+     */
+    formLabel(inputElement: HTMLElement | null, labelId: string | undefined, component: string): void;
+    /**
+     * Check for missing alt text on images
+     */
+    imageAlt(element: HTMLElement | null, component: string): void;
+};
+/**
+ * Create a component-scoped warning function
+ */
+declare function createComponentWarnings(componentName: string): {
+    error: (message: string, suggestion?: string, element?: Element) => void;
+    warning: (message: string, suggestion?: string, element?: Element) => void;
+    info: (message: string, suggestion?: string, element?: Element) => void;
+    checks: {
+        accessibleLabel: (element: HTMLElement | null, propName?: string) => void;
+        requiredProp: (value: unknown, propName: string) => void;
+        keyboardAccessible: (element: HTMLElement | null, handlers: {
+            onClick?: unknown;
+            onKeyDown?: unknown;
+        }) => void;
+        tabIndex: (tabIndex: number | undefined, element?: HTMLElement) => void;
+    };
+};
+
+/**
+ * @compa11y/core
+ *
+ * Framework-agnostic accessibility primitives
+ *
+ * This package provides the foundational utilities used by all
+ * compa11y packages (React, Web Components, etc.)
+ */
+
+/**
+ * Initialize all compa11y systems
+ * Call this once at app startup for optimal behavior
+ */
+declare function initA11yKit(): () => void;
+
+export { DevWarning, DevWarningHandler, FOCUSABLE_SELECTORS, TABBABLE_SELECTORS, checks, clearWarnings, containsFocus, createComponentWarnings, createIdScope, createMediaQueryListener, generateId, generateIds, getFirstFocusable, getFocusableElements, getLastFocusable, getNextFocusable, getPreviousFocusable, getScreenReaderHints, getTabbableElements, initA11yKit, isAndroid, isBrowser, isFocusable, isIOS, isMac, isTabbable, isTouchDevice, isVisible, isWindows, isWithinContainer, prefersDarkMode, prefersHighContrast, prefersReducedMotion, resetIdCounter, resolveElement, setWarningHandler, warn };