@a13y/devtools 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 Diego Aneli and contributors
+
+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,278 @@
+<div align="center">
+  <img src="https://raw.githubusercontent.com/DiegoAneli/a13y/main/assets/logo.svg" alt="A13Y Logo" width="150" />
+
+  <h1>@a13y/devtools</h1>
+
+  <p><strong>Development-time validators and runtime checks for @a13y</strong></p>
+  <p>Helpful warnings and error messages during development, automatically stripped in production.</p>
+
+  [![npm version](https://img.shields.io/npm/v/@a13y/devtools.svg)](https://www.npmjs.com/package/@a13y/devtools)
+  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+</div>
+
+<br />
+
+## Features
+
+- **Development-only** - Zero overhead in production (tree-shakeable)
+- **WCAG references** - Every warning includes WCAG 2.2 criterion
+- **Fix suggestions** - Actionable fixes with code examples
+- **Runtime validation** - Catches accessibility issues during development
+- **Type-safe** - Full TypeScript support
+
+## Installation
+
+```bash
+npm install -D @a13y/devtools
+```
+
+## Usage
+
+Devtools are automatically integrated when you use `@a13y/react` or `@a13y/core`. Simply install the package and warnings will appear in development.
+
+### Automatic Integration
+
+```typescript
+import { useAccessibleButton } from '@a13y/react';
+
+function Button() {
+  const { buttonProps } = useAccessibleButton({ onPress: () => {} });
+
+  // ⚠️ Warning in console if devtools installed:
+  // "Element is missing accessible label (WCAG 4.1.2)"
+  return <button {...buttonProps}></button>;
+}
+```
+
+### Manual Validation
+
+You can also use validators directly:
+
+```typescript
+import { validateFocus, validateAria } from '@a13y/devtools/runtime/validators';
+
+const button = document.querySelector('button');
+
+// Validate focus management
+validateFocus(button, {
+  hasFocusableElements: true,
+  isVisible: true,
+});
+
+// Validate ARIA attributes
+validateAria(button, {
+  role: 'button',
+  requiredAttrs: ['aria-label'],
+});
+```
+
+## Validators
+
+### Focus Validator
+
+```typescript
+import { validateFocus } from '@a13y/devtools/runtime/validators';
+
+validateFocus(element, {
+  hasFocusableElements: true,
+  isVisible: true,
+  isInert: false,
+});
+```
+
+Checks:
+- Element has focusable children
+- Focus trap contains interactive elements
+- Elements are visible
+- No inert ancestors
+
+### ARIA Validator
+
+```typescript
+import { validateAria } from '@a13y/devtools/runtime/validators';
+
+validateAria(element, {
+  role: 'dialog',
+  requiredAttrs: ['aria-labelledby', 'aria-describedby'],
+  allowedRoles: ['dialog', 'alertdialog'],
+});
+```
+
+Checks:
+- Valid ARIA roles
+- Required ARIA attributes present
+- Attribute values are valid
+- No conflicting attributes
+
+### Keyboard Validator
+
+```typescript
+import { validateKeyboard } from '@a13y/devtools/runtime/validators';
+
+validateKeyboard(element, {
+  supportsKeys: ['Enter', ' ', 'Escape'],
+  hasKeyboardHandler: true,
+});
+```
+
+Checks:
+- Keyboard event handlers present
+- Required keys supported
+- Focus visible on keyboard navigation
+
+## Warning System
+
+### Warning Levels
+
+```typescript
+import { warn, error } from '@a13y/devtools/runtime/warnings';
+
+// Polite warning (logged to console)
+warn('accessibility-issue', {
+  message: 'Missing accessible label',
+  wcagCriterion: '4.1.2',
+  fixes: [
+    'Add aria-label attribute',
+    'Add aria-labelledby reference',
+    'Add visible text content',
+  ],
+});
+
+// Error (thrown in dev, silent in prod)
+error('critical-accessibility-issue', {
+  message: 'Dialog missing required title',
+  wcagCriterion: '2.4.6',
+});
+```
+
+### Warning Categories
+
+- `focus` - Focus management issues
+- `keyboard` - Keyboard navigation problems
+- `aria` - ARIA attribute errors
+- `structure` - DOM structure issues
+- `semantics` - Semantic HTML problems
+
+## Invariants
+
+Runtime checks that throw errors in development:
+
+```typescript
+import { invariant } from '@a13y/devtools/runtime/invariants';
+
+invariant(
+  element.hasAttribute('aria-label'),
+  'Button must have accessible label',
+  'WCAG 4.1.2'
+);
+```
+
+## Production Builds
+
+All devtools code is automatically removed in production:
+
+```typescript
+// Development build
+if (process.env.NODE_ENV !== 'production') {
+  validateFocus(element);
+}
+
+// Production build - entire block removed by bundler
+// No runtime overhead!
+```
+
+## Configuration
+
+Configure warning behavior:
+
+```typescript
+import { configureWarnings } from '@a13y/devtools';
+
+configureWarnings({
+  // Disable specific warnings
+  ignore: ['focus-trap-no-elements'],
+
+  // Throw errors instead of warnings
+  strict: true,
+
+  // Custom warning handler
+  onWarn: (warning) => {
+    console.log(`[A13Y] ${warning.message}`);
+    // Send to error tracking service
+  },
+});
+```
+
+## TypeScript Support
+
+Full TypeScript support with type definitions:
+
+```typescript
+import type {
+  WarningType,
+  ValidationOptions,
+  WCAGCriterion,
+} from '@a13y/devtools';
+```
+
+## Example Warnings
+
+### Missing Label
+
+```
+⚠️ A13Y Warning: Missing accessible label
+Element: <button>Save</button>
+WCAG: 4.1.2 Name, Role, Value
+
+Suggested fixes:
+1. Add aria-label: <button aria-label="Save document">
+2. Add aria-labelledby: <button aria-labelledby="save-label">
+3. Ensure visible text is descriptive
+```
+
+### Invalid ARIA
+
+```
+⚠️ A13Y Warning: Invalid ARIA attribute value
+Element: <div role="dialog" aria-expanded="yes">
+WCAG: 4.1.2 Name, Role, Value
+
+Issue: aria-expanded must be "true" or "false", not "yes"
+
+Fix: <div role="dialog" aria-expanded="true">
+```
+
+### Focus Trap
+
+```
+⚠️ A13Y Warning: Focus trap has no focusable elements
+Element: <div role="dialog">...</div>
+WCAG: 2.1.1 Keyboard
+
+Issue: Focus trap activated but contains no focusable elements
+
+Suggested fixes:
+1. Add focusable elements (button, input, a, etc.)
+2. Add tabindex="0" to make element focusable
+3. Check if elements are hidden or disabled
+```
+
+## Tree Shaking
+
+Import validators individually for optimal bundle size:
+
+```typescript
+// ✅ Good - imports only focus validator
+import { validateFocus } from '@a13y/devtools/runtime/validators';
+
+// ❌ Avoid - imports all validators
+import { validateFocus } from '@a13y/devtools';
+```
+
+## Author
+
+Created and maintained by **Diego Aneli** ([@DiegoAneli](https://github.com/DiegoAneli))
+
+## License
+
+MIT © Diego Aneli and contributors

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+import { WarningSystemConfig } from './runtime/warnings/index.js';
+export { AccessibilityWarning, FixSuggestion, WCAGLevel, WCAGUrls, WarningCategory, WarningCodes, WarningSeverity, WarningSystem, createWarning } from './runtime/warnings/index.js';
+export { assertFocusVisible, assertHasAccessibleName, assertKeyboardAccessible, assertValidAriaAttributes, assertValidTabindex, invariant } from './runtime/invariants/index.js';
+export { AriaValidator, FocusValidator, KeyboardValidator, ariaValidator, focusValidator, keyboardValidator } from './runtime/validators/index.js';
+
+/**
+ * @a13y/devtools - Development Tools
+ * Runtime validation and warnings for accessibility
+ * @packageDocumentation
+ */
+declare const VERSION: "0.0.0";
+
+/**
+ * Initialize devtools
+ * Starts all validators and warning system
+ */
+declare const initDevtools: (config?: WarningSystemConfig) => void;
+/**
+ * Destroy devtools
+ * Stops all validators
+ */
+declare const destroyDevtools: () => void;
+
+export { VERSION, WarningSystemConfig, destroyDevtools, initDevtools };