@compa11y/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ivan Trajkovski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,160 @@
+# @compa11y/core
+
+Framework-agnostic accessibility primitives for building accessible UI components.
+
+## Installation
+
+```bash
+npm install @compa11y/core
+```
+
+## Features
+
+- **Focus Management** — Focus traps, focus scope, roving tabindex
+- **Keyboard Navigation** — Pre-built patterns for menus, tabs, grids
+- **Screen Reader Support** — Live region announcements
+- **ARIA Utilities** — Helpers for managing ARIA attributes
+- **Dev Warnings** — Catch accessibility issues during development
+
+## Usage
+
+### Focus Trap
+
+```ts
+import { createFocusTrap } from '@compa11y/core';
+
+const dialog = document.getElementById('dialog');
+const trap = createFocusTrap(dialog, {
+  escapeDeactivates: true,
+  returnFocus: true,
+});
+
+// Activate when dialog opens
+trap.activate();
+
+// Deactivate when dialog closes
+trap.deactivate();
+```
+
+### Announcements
+
+```ts
+import { announce, announcePolite, announceAssertive } from '@compa11y/core';
+
+// Polite announcement (doesn't interrupt)
+announcePolite('Item added to cart');
+
+// Assertive announcement (interrupts current speech)
+announceAssertive('Error: Form submission failed');
+```
+
+### Keyboard Navigation
+
+```ts
+import { createKeyboardManager, KeyboardPatterns } from '@compa11y/core';
+
+const manager = createKeyboardManager(
+  KeyboardPatterns.menu({
+    onUp: () => focusPreviousItem(),
+    onDown: () => focusNextItem(),
+    onEnter: () => selectItem(),
+    onEscape: () => closeMenu(),
+  })
+);
+
+manager.attach(menuElement);
+```
+
+### ARIA Utilities
+
+```ts
+import { aria, buildAriaProps, hasAccessibleName } from '@compa11y/core';
+
+// Set individual ARIA attributes
+aria.setExpanded(button, true);
+aria.setControls(button, 'menu-id');
+
+// Build props object for React/frameworks
+const props = buildAriaProps({
+  expanded: true,
+  controls: 'menu-id',
+  hasPopup: 'menu',
+});
+
+// Check accessibility
+if (!hasAccessibleName(element)) {
+  console.warn('Element needs an accessible name');
+}
+```
+
+### Dev Warnings
+
+```ts
+import { checks, createComponentWarnings } from '@compa11y/core';
+
+// Use pre-built checks
+checks.accessibleLabel(element, 'MyComponent');
+
+// Create component-scoped warnings
+const warnings = createComponentWarnings('MyComponent');
+warnings.error('Missing required prop', 'Add the "label" prop');
+```
+
+## API Reference
+
+### Focus
+
+- `createFocusTrap(container, options)` — Create a focus trap
+- `createFocusScope(container, options)` — Manage focus within a scope
+- `createRovingTabindex(container, selector, options)` — Roving tabindex pattern
+- `initFocusVisible()` — Initialize focus-visible detection
+
+### Announcer
+
+- `initAnnouncer()` — Initialize live regions
+- `announce(message, options)` — General announcement
+- `announcePolite(message)` — Non-interrupting announcement
+- `announceAssertive(message)` — Interrupting announcement
+- `createAnnouncer(defaults)` — Create scoped announcer
+
+### Keyboard
+
+- `createKeyboardManager(handlers, options)` — Keyboard event handling
+- `KeyboardPatterns.menu(handlers)` — Menu navigation pattern
+- `KeyboardPatterns.tabs(handlers)` — Tabs navigation pattern
+- `KeyboardPatterns.grid(handlers)` — Grid navigation pattern
+- `createTypeAhead(items, options)` — Type-ahead search
+
+### ARIA
+
+- `aria.*` — ARIA attribute setters
+- `buildAriaProps(props)` — Build props object
+- `hasAccessibleName(element)` — Check for accessible name
+- `mergeAriaIds(...ids)` — Merge ARIA ID lists
+
+### Dev
+
+- `warn(warning)` — Issue a warning
+- `checks.*` — Pre-built accessibility checks
+- `createComponentWarnings(name)` — Create scoped warnings
+
+### DOM Utilities
+
+- `isFocusable(element)` — Check if focusable
+- `isTabbable(element)` — Check if tabbable
+- `getFocusableElements(container)` — Get all focusable elements
+- `getTabbableElements(container)` — Get all tabbable elements
+- `getFirstFocusable(container)` — Get first focusable
+- `getLastFocusable(container)` — Get last focusable
+
+### Platform
+
+- `isBrowser()` — Check if in browser
+- `isMac()` — Check if macOS
+- `prefersReducedMotion()` — Check motion preference
+- `prefersHighContrast()` — Check contrast preference
+- `prefersDarkMode()` — Check color scheme preference
+
+## License
+
+MIT

package/dist/announcer/index.cjs

@@ -0,0 +1,49 @@
+'use strict';
+
+var chunkV6TZIZZ4_cjs = require('../chunk-V6TZIZZ4.cjs');
+require('../chunk-XEGB27QF.cjs');
+
+
+
+Object.defineProperty(exports, "announce", {
+  enumerable: true,
+  get: function () { return chunkV6TZIZZ4_cjs.announce; }
+});
+Object.defineProperty(exports, "announceAssertive", {
+  enumerable: true,
+  get: function () { return chunkV6TZIZZ4_cjs.announceAssertive; }
+});
+Object.defineProperty(exports, "announceError", {
+  enumerable: true,
+  get: function () { return chunkV6TZIZZ4_cjs.announceError; }
+});
+Object.defineProperty(exports, "announcePolite", {
+  enumerable: true,
+  get: function () { return chunkV6TZIZZ4_cjs.announcePolite; }
+});
+Object.defineProperty(exports, "announceProgress", {
+  enumerable: true,
+  get: function () { return chunkV6TZIZZ4_cjs.announceProgress; }
+});
+Object.defineProperty(exports, "announceStatus", {
+  enumerable: true,
+  get: function () { return chunkV6TZIZZ4_cjs.announceStatus; }
+});
+Object.defineProperty(exports, "clearAnnouncements", {
+  enumerable: true,
+  get: function () { return chunkV6TZIZZ4_cjs.clearAnnouncements; }
+});
+Object.defineProperty(exports, "createAnnouncer", {
+  enumerable: true,
+  get: function () { return chunkV6TZIZZ4_cjs.createAnnouncer; }
+});
+Object.defineProperty(exports, "initAnnouncer", {
+  enumerable: true,
+  get: function () { return chunkV6TZIZZ4_cjs.initAnnouncer; }
+});
+Object.defineProperty(exports, "queueAnnouncement", {
+  enumerable: true,
+  get: function () { return chunkV6TZIZZ4_cjs.queueAnnouncement; }
+});
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/announcer/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.cjs"}

package/dist/announcer/index.d.cts

@@ -0,0 +1,61 @@
+import { A as AnnouncerOptions } from '../types-DDSPmE8m.cjs';
+
+/**
+ * Live Announcer
+ *
+ * Provides screen reader announcements via ARIA live regions
+ */
+
+/**
+ * Initialize the live announcer
+ * Call this once at app startup
+ */
+declare function initAnnouncer(): () => void;
+/**
+ * Announce a message to screen readers
+ */
+declare function announce(message: string, options?: AnnouncerOptions): void;
+/**
+ * Announce a polite message (non-interruptive)
+ */
+declare function announcePolite(message: string, options?: Omit<AnnouncerOptions, 'politeness'>): void;
+/**
+ * Announce an assertive message (interruptive)
+ */
+declare function announceAssertive(message: string, options?: Omit<AnnouncerOptions, 'politeness'>): void;
+/**
+ * Clear all announcements
+ */
+declare function clearAnnouncements(): void;
+/**
+ * Queue multiple announcements (debounced)
+ */
+declare function queueAnnouncement(message: string, options?: AnnouncerOptions & {
+    debounce?: number;
+}): void;
+/**
+ * Create an announcer instance for a specific context
+ */
+declare function createAnnouncer(defaultOptions?: AnnouncerOptions): {
+    announce: (message: string, options?: AnnouncerOptions) => void;
+    polite: (message: string, options?: Omit<AnnouncerOptions, "politeness">) => void;
+    assertive: (message: string, options?: Omit<AnnouncerOptions, "politeness">) => void;
+    queue: (message: string, options?: AnnouncerOptions & {
+        debounce?: number;
+    }) => void;
+    clear: typeof clearAnnouncements;
+};
+/**
+ * Status announcer - for status updates like "Saved", "Loading complete"
+ */
+declare function announceStatus(message: string): void;
+/**
+ * Error announcer - for error messages
+ */
+declare function announceError(message: string): void;
+/**
+ * Progress announcer - for progress updates
+ */
+declare function announceProgress(current: number, total: number, template?: string): void;
+
+export { announce, announceAssertive, announceError, announcePolite, announceProgress, announceStatus, clearAnnouncements, createAnnouncer, initAnnouncer, queueAnnouncement };

package/dist/announcer/index.d.ts

@@ -0,0 +1,61 @@
+import { A as AnnouncerOptions } from '../types-DDSPmE8m.js';
+
+/**
+ * Live Announcer
+ *
+ * Provides screen reader announcements via ARIA live regions
+ */
+
+/**
+ * Initialize the live announcer
+ * Call this once at app startup
+ */
+declare function initAnnouncer(): () => void;
+/**
+ * Announce a message to screen readers
+ */
+declare function announce(message: string, options?: AnnouncerOptions): void;
+/**
+ * Announce a polite message (non-interruptive)
+ */
+declare function announcePolite(message: string, options?: Omit<AnnouncerOptions, 'politeness'>): void;
+/**
+ * Announce an assertive message (interruptive)
+ */
+declare function announceAssertive(message: string, options?: Omit<AnnouncerOptions, 'politeness'>): void;
+/**
+ * Clear all announcements
+ */
+declare function clearAnnouncements(): void;
+/**
+ * Queue multiple announcements (debounced)
+ */
+declare function queueAnnouncement(message: string, options?: AnnouncerOptions & {
+    debounce?: number;
+}): void;
+/**
+ * Create an announcer instance for a specific context
+ */
+declare function createAnnouncer(defaultOptions?: AnnouncerOptions): {
+    announce: (message: string, options?: AnnouncerOptions) => void;
+    polite: (message: string, options?: Omit<AnnouncerOptions, "politeness">) => void;
+    assertive: (message: string, options?: Omit<AnnouncerOptions, "politeness">) => void;
+    queue: (message: string, options?: AnnouncerOptions & {
+        debounce?: number;
+    }) => void;
+    clear: typeof clearAnnouncements;
+};
+/**
+ * Status announcer - for status updates like "Saved", "Loading complete"
+ */
+declare function announceStatus(message: string): void;
+/**
+ * Error announcer - for error messages
+ */
+declare function announceError(message: string): void;
+/**
+ * Progress announcer - for progress updates
+ */
+declare function announceProgress(current: number, total: number, template?: string): void;
+
+export { announce, announceAssertive, announceError, announcePolite, announceProgress, announceStatus, clearAnnouncements, createAnnouncer, initAnnouncer, queueAnnouncement };

package/dist/announcer/index.js

@@ -0,0 +1,4 @@
+export { announce, announceAssertive, announceError, announcePolite, announceProgress, announceStatus, clearAnnouncements, createAnnouncer, initAnnouncer, queueAnnouncement } from '../chunk-2CQOLVQH.js';
+import '../chunk-Z7K2G6FX.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/announcer/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/aria/index.cjs

@@ -0,0 +1,24 @@
+'use strict';
+
+var chunkNBGFFCIJ_cjs = require('../chunk-NBGFFCIJ.cjs');
+
+
+
+Object.defineProperty(exports, "aria", {
+  enumerable: true,
+  get: function () { return chunkNBGFFCIJ_cjs.aria; }
+});
+Object.defineProperty(exports, "buildAriaProps", {
+  enumerable: true,
+  get: function () { return chunkNBGFFCIJ_cjs.buildAriaProps; }
+});
+Object.defineProperty(exports, "hasAccessibleName", {
+  enumerable: true,
+  get: function () { return chunkNBGFFCIJ_cjs.hasAccessibleName; }
+});
+Object.defineProperty(exports, "mergeAriaIds", {
+  enumerable: true,
+  get: function () { return chunkNBGFFCIJ_cjs.mergeAriaIds; }
+});
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/aria/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.cjs"}

package/dist/aria/index.d.cts

@@ -0,0 +1,176 @@
+import { c as AriaRole } from '../types-DDSPmE8m.cjs';
+
+/**
+ * ARIA Utilities
+ *
+ * Helpers for managing ARIA attributes and relationships
+ */
+
+/**
+ * ARIA attribute helpers
+ */
+declare const aria: {
+    /**
+     * Set aria-hidden on an element
+     */
+    hide(element: HTMLElement): void;
+    /**
+     * Remove aria-hidden from an element
+     */
+    show(element: HTMLElement): void;
+    /**
+     * Set aria-expanded state
+     */
+    setExpanded(element: HTMLElement, expanded: boolean): void;
+    /**
+     * Set aria-selected state
+     */
+    setSelected(element: HTMLElement, selected: boolean): void;
+    /**
+     * Set aria-checked state
+     */
+    setChecked(element: HTMLElement, checked: boolean | "mixed"): void;
+    /**
+     * Set aria-pressed state
+     */
+    setPressed(element: HTMLElement, pressed: boolean | "mixed"): void;
+    /**
+     * Set aria-disabled state
+     */
+    setDisabled(element: HTMLElement, disabled: boolean): void;
+    /**
+     * Set aria-busy state
+     */
+    setBusy(element: HTMLElement, busy: boolean): void;
+    /**
+     * Set aria-current
+     */
+    setCurrent(element: HTMLElement, value: "page" | "step" | "location" | "date" | "time" | "true" | "false"): void;
+    /**
+     * Set aria-invalid state
+     */
+    setInvalid(element: HTMLElement, invalid: boolean | "grammar" | "spelling"): void;
+    /**
+     * Set aria-label
+     */
+    setLabel(element: HTMLElement, label: string): void;
+    /**
+     * Set aria-labelledby
+     */
+    setLabelledBy(element: HTMLElement, ...ids: string[]): void;
+    /**
+     * Set aria-describedby
+     */
+    setDescribedBy(element: HTMLElement, ...ids: string[]): void;
+    /**
+     * Set aria-controls
+     */
+    setControls(element: HTMLElement, ...ids: string[]): void;
+    /**
+     * Set aria-owns
+     */
+    setOwns(element: HTMLElement, ...ids: string[]): void;
+    /**
+     * Set aria-activedescendant
+     */
+    setActiveDescendant(element: HTMLElement, id: string | null): void;
+    /**
+     * Set aria-haspopup
+     */
+    setHasPopup(element: HTMLElement, popup: "menu" | "listbox" | "tree" | "grid" | "dialog" | boolean): void;
+    /**
+     * Set aria-level
+     */
+    setLevel(element: HTMLElement, level: number): void;
+    /**
+     * Set aria-posinset and aria-setsize
+     */
+    setPosition(element: HTMLElement, position: number, setSize: number): void;
+    /**
+     * Set aria-valuemin, aria-valuemax, aria-valuenow
+     */
+    setValue(element: HTMLElement, options: {
+        min?: number;
+        max?: number;
+        now?: number;
+        text?: string;
+    }): void;
+    /**
+     * Set role attribute
+     */
+    setRole(element: HTMLElement, role: AriaRole | null): void;
+    /**
+     * Set aria-modal
+     */
+    setModal(element: HTMLElement, modal: boolean): void;
+    /**
+     * Set aria-orientation
+     */
+    setOrientation(element: HTMLElement, orientation: "horizontal" | "vertical"): void;
+    /**
+     * Set aria-required
+     */
+    setRequired(element: HTMLElement, required: boolean): void;
+    /**
+     * Set aria-readonly
+     */
+    setReadOnly(element: HTMLElement, readOnly: boolean): void;
+    /**
+     * Set aria-autocomplete
+     */
+    setAutocomplete(element: HTMLElement, value: "none" | "inline" | "list" | "both"): void;
+    /**
+     * Set aria-multiselectable
+     */
+    setMultiSelectable(element: HTMLElement, multiselectable: boolean): void;
+    /**
+     * Set aria-sort
+     */
+    setSort(element: HTMLElement, sort: "none" | "ascending" | "descending" | "other"): void;
+};
+/**
+ * Build ARIA props object for React/JS usage
+ */
+declare function buildAriaProps(props: {
+    label?: string;
+    labelledBy?: string | string[];
+    describedBy?: string | string[];
+    controls?: string | string[];
+    owns?: string | string[];
+    expanded?: boolean;
+    selected?: boolean;
+    checked?: boolean | 'mixed';
+    pressed?: boolean | 'mixed';
+    disabled?: boolean;
+    hidden?: boolean;
+    modal?: boolean;
+    busy?: boolean;
+    current?: 'page' | 'step' | 'location' | 'date' | 'time' | 'true' | 'false';
+    invalid?: boolean | 'grammar' | 'spelling';
+    hasPopup?: 'menu' | 'listbox' | 'tree' | 'grid' | 'dialog' | boolean;
+    activeDescendant?: string;
+    level?: number;
+    posInSet?: number;
+    setSize?: number;
+    valueMin?: number;
+    valueMax?: number;
+    valueNow?: number;
+    valueText?: string;
+    orientation?: 'horizontal' | 'vertical';
+    required?: boolean;
+    readOnly?: boolean;
+    autocomplete?: 'none' | 'inline' | 'list' | 'both';
+    multiSelectable?: boolean;
+    sort?: 'none' | 'ascending' | 'descending' | 'other';
+    role?: AriaRole;
+}): Record<string, string | undefined>;
+/**
+ * Merge multiple aria-labelledby or aria-describedby values
+ */
+declare function mergeAriaIds(...ids: (string | undefined | null)[]): string | undefined;
+/**
+ * Check if an element has an accessible name
+ */
+declare function hasAccessibleName(element: HTMLElement): boolean;
+
+export { aria, buildAriaProps, hasAccessibleName, mergeAriaIds };