@a13y/react 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,241 @@
+<div align="center">
+  <img src="https://raw.githubusercontent.com/DiegoAneli/a13y/main/assets/logo.svg" alt="A13Y Logo" width="150" />
+
+  <h1>@a13y/react</h1>
+
+  <p><strong>Type-safe React hooks for accessibility with compile-time guarantees</strong></p>
+</div>
+
+<br />
+
+## Features
+
+- **Type-Safe**: Restrictive TypeScript signatures prevent misuse
+- **Props Enforcement**: Required props enforced at compile-time
+- **Automatic ARIA**: Correct ARIA attributes applied automatically
+- **Keyboard Support**: Enter, Space, Arrow keys handled correctly
+- **Focus Management**: Focus trap, restoration, roving tabindex
+- **Dev Validation**: Runtime warnings in development (via @a13y/devtools)
+- **Zero Overhead**: All dev code stripped in production
+
+## Installation
+
+```bash
+npm install @a13y/react @a13y/core
+```
+
+Optional devtools for development warnings:
+
+```bash
+npm install -D @a13y/devtools
+```
+
+## Hooks
+
+### useAccessibleButton
+
+Creates accessible buttons with keyboard support.
+
+```tsx
+import { useAccessibleButton } from '@a13y/react';
+
+function DeleteButton() {
+  const { buttonProps } = useAccessibleButton({
+    label: 'Delete item', // Required for icon-only buttons
+    onPress: (event) => {
+      console.log(event.type); // 'mouse' | 'keyboard'
+      console.log(event.key); // 'Enter' | ' ' | undefined
+    },
+  });
+
+  return <button {...buttonProps}>🗑️</button>;
+}
+```
+
+**Props:**
+- `label?: string` - Accessible label (required for icon-only buttons)
+- `onPress: (event: PressEvent) => void` - Called on click or Enter/Space
+- `isDisabled?: boolean` - Whether button is disabled
+- `role?: 'button' | 'link'` - ARIA role (default: 'button')
+- `elementType?: 'button' | 'a'` - HTML element type (default: 'button')
+
+### useAccessibleDialog
+
+Creates accessible modals/dialogs with focus trap.
+
+```tsx
+import { useAccessibleDialog } from '@a13y/react';
+
+function ConfirmDialog({ isOpen, onClose }) {
+  const { dialogProps, titleProps, descriptionProps, backdropProps } =
+    useAccessibleDialog({
+      isOpen,
+      onClose,
+      title: 'Confirm Action', // ✅ Required
+      description: 'This action cannot be undone',
+    });
+
+  if (!isOpen) return null;
+
+  return (
+    <>
+      {backdropProps && <div className="backdrop" {...backdropProps} />}
+      <div className="dialog" {...dialogProps}>
+        <h2 {...titleProps}>Confirm Action</h2>
+        <p {...descriptionProps}>This action cannot be undone</p>
+        <button onClick={onClose}>Cancel</button>
+      </div>
+    </>
+  );
+}
+```
+
+**Props:**
+- `isOpen: boolean` - Whether dialog is open
+- `onClose: () => void` - Called when dialog should close
+- `title: string` - Dialog title (REQUIRED for accessibility)
+- `description?: string` - Dialog description
+- `role?: 'dialog' | 'alertdialog'` - ARIA role (default: 'dialog')
+- `isModal?: boolean` - Whether dialog is modal/blocking (default: true)
+- `closeOnBackdropClick?: boolean` - Close on backdrop click (default: true)
+
+### useFocusTrap
+
+Creates a focus trap for modals and popups.
+
+```tsx
+import { useFocusTrap } from '@a13y/react';
+
+function Modal({ isOpen, onClose }) {
+  const { trapRef } = useFocusTrap({
+    isActive: isOpen,
+    onEscape: onClose,
+    restoreFocus: true, // Restore focus on close
+    autoFocus: true, // Auto-focus first element
+  });
+
+  if (!isOpen) return null;
+
+  return (
+    <div ref={trapRef} className="modal">
+      <h2>Modal Title</h2>
+      <button onClick={onClose}>Close</button>
+    </div>
+  );
+}
+```
+
+**Props:**
+- `isActive: boolean` - Whether focus trap is active
+- `onEscape?: () => void` - Called when Escape key is pressed
+- `restoreFocus?: boolean` - Restore focus on deactivation (default: true)
+- `autoFocus?: boolean` - Auto-focus first element (default: true)
+
+### useKeyboardNavigation
+
+Implements roving tabindex keyboard navigation.
+
+```tsx
+import { useKeyboardNavigation } from '@a13y/react';
+
+function Toolbar() {
+  const { containerProps, getItemProps, currentIndex } =
+    useKeyboardNavigation({
+      orientation: 'horizontal', // Arrow Left/Right
+      loop: true, // Wrap around at edges
+    });
+
+  const tools = ['Cut', 'Copy', 'Paste', 'Undo', 'Redo'];
+
+  return (
+    <div className="toolbar" {...containerProps}>
+      {tools.map((tool, index) => (
+        <button
+          key={tool}
+          {...getItemProps(index)}
+          className={index === currentIndex ? 'focused' : ''}
+        >
+          {tool}
+        </button>
+      ))}
+    </div>
+  );
+}
+```
+
+**Props:**
+- `orientation: 'horizontal' | 'vertical' | 'both'` - Navigation direction
+- `loop?: boolean` - Whether to loop at boundaries (default: false)
+- `onNavigate?: (index: number) => void` - Called when navigation occurs
+- `defaultIndex?: number` - Initial focused index (default: 0)
+- `currentIndex?: number` - Controlled current index
+
+## Type Safety
+
+### Forbidden Props
+
+The hooks prevent misuse by forbidding certain props:
+
+```tsx
+const { buttonProps } = useAccessibleButton({ onPress: () => {} });
+
+// ❌ TypeScript Error: These props are managed by the hook
+<button {...buttonProps} onClick={() => {}} />
+<button {...buttonProps} onKeyDown={() => {}} />
+```
+
+### Required Props
+
+Required props are enforced at compile-time:
+
+```tsx
+// ❌ TypeScript Error: 'title' is required
+useAccessibleDialog({
+  isOpen: true,
+  onClose: () => {},
+  // title: missing!
+});
+```
+
+## Development Warnings
+
+When `@a13y/devtools` is installed, you get runtime warnings in development:
+
+```tsx
+// ⚠️ Console warning: Element is missing an accessible name
+<button {...buttonProps}></button>
+
+// ⚠️ Console warning: Focus trap has no focusable elements
+<div ref={trapRef}></div>
+```
+
+All warnings include:
+- Clear description of the issue
+- WCAG 2.2 criterion reference
+- Multiple fix suggestions with code examples
+
+## Production Build
+
+Zero overhead in production:
+
+```tsx
+// Development build
+useAccessibleButton({ onPress: () => {} });
+// ✅ Includes validation code from @a13y/devtools
+
+// Production build (NODE_ENV=production)
+useAccessibleButton({ onPress: () => {} });
+// ✅ All validation code removed via dead code elimination
+```
+
+## Examples
+
+See [EXAMPLES.md](./EXAMPLES.md) for complete usage examples.
+
+## Author
+
+Created and maintained by **Diego Aneli** ([@DiegoAneli](https://github.com/DiegoAneli))
+
+## License
+
+MIT © Diego Aneli and contributors

package/dist/components/index.d.ts

@@ -0,0 +1,374 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { P as PressEvent } from '../use-accessible-button-B0syf-Az.js';
+import { ReactNode } from 'react';
+
+/**
+ * Button variants
+ */
+type ButtonVariant = 'primary' | 'secondary' | 'danger' | 'ghost';
+/**
+ * Props for AccessibleButton
+ */
+interface AccessibleButtonProps {
+    /**
+     * Button content
+     * If content is not text (e.g., icon only), label is REQUIRED
+     */
+    children: ReactNode;
+    /**
+     * Accessible label
+     * REQUIRED if children is not text (e.g., icon-only button)
+     */
+    label?: string;
+    /**
+     * Click handler
+     */
+    onPress: (event: PressEvent) => void;
+    /**
+     * Whether button is disabled
+     */
+    disabled?: boolean;
+    /**
+     * Visual variant (does not affect accessibility)
+     */
+    variant?: ButtonVariant;
+    /**
+     * Custom className
+     */
+    className?: string;
+    /**
+     * Button type
+     */
+    type?: 'button' | 'submit' | 'reset';
+}
+/**
+ * Accessible Button Component
+ *
+ * Features:
+ * - Automatic keyboard support (Enter, Space)
+ * - Required accessible name (compile-time + runtime)
+ * - Disabled state handling
+ * - Development-time validation
+ *
+ * @example
+ * ```tsx
+ * // Text button (label optional)
+ * <AccessibleButton onPress={() => console.log('Clicked')}>
+ *   Save
+ * </AccessibleButton>
+ *
+ * // Icon button (label REQUIRED)
+ * <AccessibleButton
+ *   label="Delete item"
+ *   onPress={() => console.log('Deleted')}
+ * >
+ *   🗑️
+ * </AccessibleButton>
+ * ```
+ */
+declare const AccessibleButton: (props: AccessibleButtonProps) => react_jsx_runtime.JSX.Element;
+
+/**
+ * Props for AccessibleDialog
+ */
+interface AccessibleDialogProps {
+    /**
+     * Whether dialog is open
+     */
+    isOpen: boolean;
+    /**
+     * Called when dialog should close
+     */
+    onClose: () => void;
+    /**
+     * Dialog title - REQUIRED for accessibility
+     * This will be announced to screen readers
+     */
+    title: string;
+    /**
+     * Dialog content
+     */
+    children: ReactNode;
+    /**
+     * Optional description
+     * Provides additional context to screen readers
+     */
+    description?: string;
+    /**
+     * ARIA role
+     */
+    role?: 'dialog' | 'alertdialog';
+    /**
+     * Whether to show close button
+     */
+    showCloseButton?: boolean;
+    /**
+     * Custom className for dialog container
+     */
+    className?: string;
+    /**
+     * Custom className for backdrop
+     */
+    backdropClassName?: string;
+}
+/**
+ * Accessible Dialog Component
+ *
+ * Features:
+ * - Focus trap with Tab/Shift+Tab cycling
+ * - Escape key to close
+ * - Focus restoration on close
+ * - Click outside to close
+ * - Required title for screen readers
+ * - Body scroll lock when open
+ *
+ * @example
+ * ```tsx
+ * <AccessibleDialog
+ *   isOpen={isOpen}
+ *   onClose={() => setIsOpen(false)}
+ *   title="Confirm Action"
+ *   description="This action cannot be undone"
+ * >
+ *   <p>Are you sure you want to delete this item?</p>
+ *   <button onClick={handleConfirm}>Confirm</button>
+ *   <button onClick={() => setIsOpen(false)}>Cancel</button>
+ * </AccessibleDialog>
+ * ```
+ */
+declare const AccessibleDialog: (props: AccessibleDialogProps) => react_jsx_runtime.JSX.Element | null;
+
+/**
+ * Menu item definition
+ */
+interface MenuItem {
+    /**
+     * Unique identifier
+     */
+    id: string;
+    /**
+     * Item label
+     */
+    label: string;
+    /**
+     * Click handler
+     */
+    onPress: () => void;
+    /**
+     * Whether item is disabled
+     */
+    disabled?: boolean;
+    /**
+     * Optional icon
+     */
+    icon?: ReactNode;
+}
+/**
+ * Props for AccessibleMenu
+ */
+interface AccessibleMenuProps {
+    /**
+     * Menu trigger button label
+     */
+    label: string;
+    /**
+     * Trigger button content
+     */
+    trigger: ReactNode;
+    /**
+     * Menu items
+     */
+    items: MenuItem[];
+    /**
+     * Custom className for trigger button
+     */
+    className?: string;
+    /**
+     * Custom className for menu container
+     */
+    menuClassName?: string;
+}
+/**
+ * Accessible Menu Component
+ *
+ * Dropdown menu with full keyboard navigation:
+ * - Arrow Up/Down to navigate items
+ * - Enter/Space to select
+ * - Escape to close
+ * - Focus trap when open
+ *
+ * @example
+ * ```tsx
+ * <AccessibleMenu
+ *   label="Open actions menu"
+ *   trigger="Actions ▼"
+ *   items={[
+ *     { id: 'edit', label: 'Edit', onPress: () => console.log('Edit') },
+ *     { id: 'delete', label: 'Delete', onPress: () => console.log('Delete'), disabled: true },
+ *     { id: 'share', label: 'Share', onPress: () => console.log('Share') },
+ *   ]}
+ * />
+ * ```
+ */
+declare const AccessibleMenu: (props: AccessibleMenuProps) => react_jsx_runtime.JSX.Element;
+
+/**
+ * Props for AccessibleModal
+ */
+interface AccessibleModalProps {
+    /**
+     * Whether modal is open
+     */
+    isOpen: boolean;
+    /**
+     * Called when modal should close
+     */
+    onClose: () => void;
+    /**
+     * Modal title - REQUIRED
+     */
+    title: string;
+    /**
+     * Modal body content
+     */
+    children: ReactNode;
+    /**
+     * Footer content (typically action buttons)
+     */
+    footer?: ReactNode;
+    /**
+     * Modal size
+     */
+    size?: 'sm' | 'md' | 'lg' | 'xl' | 'full';
+    /**
+     * Whether modal can be closed by clicking outside
+     */
+    closeOnBackdropClick?: boolean;
+    /**
+     * Custom className for modal container
+     */
+    className?: string;
+}
+/**
+ * Accessible Modal Component
+ *
+ * Full-featured modal with header, body, and footer sections.
+ *
+ * @example
+ * ```tsx
+ * <AccessibleModal
+ *   isOpen={isOpen}
+ *   onClose={() => setIsOpen(false)}
+ *   title="Edit Profile"
+ *   size="md"
+ *   footer={
+ *     <>
+ *       <AccessibleButton onPress={() => setIsOpen(false)}>
+ *         Cancel
+ *       </AccessibleButton>
+ *       <AccessibleButton onPress={handleSave} variant="primary">
+ *         Save Changes
+ *       </AccessibleButton>
+ *     </>
+ *   }
+ * >
+ *   <form>
+ *     <input type="text" placeholder="Name" />
+ *     <input type="email" placeholder="Email" />
+ *   </form>
+ * </AccessibleModal>
+ * ```
+ */
+declare const AccessibleModal: (props: AccessibleModalProps) => react_jsx_runtime.JSX.Element | null;
+
+/**
+ * Tab definition
+ */
+interface Tab {
+    /**
+     * Unique identifier
+     */
+    id: string;
+    /**
+     * Tab label - REQUIRED for accessibility
+     */
+    label: string;
+    /**
+     * Tab panel content
+     */
+    content: ReactNode;
+    /**
+     * Whether tab is disabled
+     */
+    disabled?: boolean;
+    /**
+     * Optional icon
+     */
+    icon?: ReactNode;
+}
+/**
+ * Props for AccessibleTabs
+ */
+interface AccessibleTabsProps {
+    /**
+     * Tabs configuration - REQUIRED
+     * Must have at least one tab
+     */
+    tabs: [Tab, ...Tab[]];
+    /**
+     * Initially selected tab index
+     */
+    defaultTab?: number;
+    /**
+     * Controlled selected tab index
+     */
+    selectedTab?: number;
+    /**
+     * Called when tab changes
+     */
+    onTabChange?: (index: number) => void;
+    /**
+     * Custom className for tabs container
+     */
+    className?: string;
+    /**
+     * Custom className for panel
+     */
+    panelClassName?: string;
+}
+/**
+ * Accessible Tabs Component
+ *
+ * Tab interface following WAI-ARIA Tabs pattern:
+ * - Arrow Left/Right to navigate tabs
+ * - Home/End to jump to first/last
+ * - Automatic panel switching
+ * - Proper ARIA attributes
+ *
+ * @example
+ * ```tsx
+ * <AccessibleTabs
+ *   tabs={[
+ *     {
+ *       id: 'account',
+ *       label: 'Account',
+ *       content: <div>Account settings...</div>,
+ *     },
+ *     {
+ *       id: 'security',
+ *       label: 'Security',
+ *       content: <div>Security settings...</div>,
+ *     },
+ *     {
+ *       id: 'billing',
+ *       label: 'Billing',
+ *       content: <div>Billing information...</div>,
+ *       disabled: true,
+ *     },
+ *   ]}
+ * />
+ * ```
+ */
+declare const AccessibleTabs: (props: AccessibleTabsProps) => react_jsx_runtime.JSX.Element;
+
+export { AccessibleButton, AccessibleDialog, AccessibleMenu, AccessibleModal, AccessibleTabs, type AccessibleButtonProps as ButtonComponentProps, type ButtonVariant, type AccessibleDialogProps as DialogComponentProps, type AccessibleMenuProps as MenuComponentProps, type MenuItem, type AccessibleModalProps as ModalComponentProps, type Tab, type AccessibleTabsProps as TabsComponentProps };