@a11ypros/a11y-ui-components 1.0.1 → 1.0.2

package/README.md

@@ -1,227 +1,252 @@
-# Accessible Design System + AI Audit Assistant
+# @a11ypros/a11y-ui-components
 
-An opinionated, accessibility-first design system built with React, TypeScript, and Next.js, featuring an AI-powered accessibility audit assistant powered by Anthropic's Claude API.
+An accessibility-first React UI component library built with WCAG 2.1/2.2 Level AA compliance. Every component has been carefully crafted by a certified WAS (Web Accessibility Specialist) to ensure your applications are usable by everyone, regardless of their abilities or the assistive technologies they use.
 
 ## Features
 
-- **WCAG 2.1/2.2 Compliant Components**: All components follow accessibility best practices
-- **Design Token System**: Consistent spacing, colors, typography, and motion tokens
-- **Keyboard Navigation**: Full keyboard support for all interactive elements
-- **Focus Management**: Proper focus trapping and return focus patterns
-- **ARIA Support**: Semantic HTML with ARIA enhancements where needed
-- **Reduced Motion**: Respects `prefers-reduced-motion` media query
-- **High Contrast**: Supports `prefers-contrast` for better visibility
-- **AI Audit Assistant**: Paste JSX code and get WCAG compliance reviews with code suggestions
+- ✅ **WCAG 2.1/2.2 Level AA Compliant** - Built with accessibility as a core requirement
+- ✅ **TypeScript** - Full TypeScript support with type definitions included
+- ✅ **Tree-shakeable** - ES modules with side-effect-free exports for optimal bundle sizes
+- ✅ **Keyboard Navigation** - Full keyboard support for all interactive components
+- ✅ **Screen Reader Friendly** - Proper ARIA labels and semantic HTML
+- ✅ **Focus Management** - Built-in focus trap and focus return utilities
+- ✅ **Modern React** - Built for React 18+ with hooks and modern patterns
 
-## Project Structure
+## Installation
 
-```
-├── packages/
-│   └── design-system/     # Component library
-│       ├── src/
-│       │   ├── components/ # React components
-│       │   ├── tokens/     # Design tokens
-│       │   ├── hooks/      # Custom hooks
-│       │   ├── utils/      # Utility functions
-│       │   └── styles/     # Global styles
-│       └── package.json
-├── apps/
-│   └── web/               # Next.js app
-│       ├── app/
-│       │   ├── (docs)/    # Documentation pages
-│       │   └── api/       # API routes
-│       └── package.json
-├── .storybook/            # Storybook configuration
-└── package.json           # Root workspace config
+```bash
+npm install @a11ypros/a11y-ui-components
 ```
 
-## Getting Started
+or
 
-### Prerequisites
+```bash
+yarn add @a11ypros/a11y-ui-components
+```
 
-- Node.js 18+ 
-- npm or pnpm
+## Peer Dependencies
 
-### Installation
+This package requires React 18+ and React DOM 18+:
 
-1. Clone the repository:
 ```bash
-git clone <repository-url>
-cd PORTFOLIO
+npm install react react-dom
 ```
 
-2. Install dependencies:
-```bash
-npm install
-```
+## Quick Start
 
-3. Set up environment variables:
-Create a `.env.local` file in `apps/web/`:
-```bash
-ANTHROPIC_API_KEY=your_api_key_here
+### 1. Import CSS
+
+Import the global styles in your application entry point:
+
+```tsx
+// In your main CSS file or entry point
+import '@a11ypros/a11y-ui-components/styles';
 ```
 
-### Development
+Or import component-specific styles:
 
-1. Start the Next.js development server:
-```bash
-npm run dev
+```tsx
+import '@a11ypros/a11y-ui-components/styles/components';
 ```
 
-2. Start Storybook (in a separate terminal):
-```bash
-npm run storybook
+### 2. Import and Use Components
+
+```tsx
+import { Button, Input, Modal } from '@a11ypros/a11y-ui-components';
+
+function App() {
+  return (
+    <div>
+      <Button>Click me</Button>
+      <Input label="Email" type="email" />
+      <Modal isOpen={true} onClose={() => {}}>
+        <p>Modal content</p>
+      </Modal>
+    </div>
+  );
+}
 ```
 
-The Next.js app will be available at `http://localhost:3000` and Storybook at `http://localhost:6006`.
+## Available Components
+
+### Form Components
+- **Input** - Accessible text input with label and error handling
+- **Textarea** - Multi-line text input
+- **Select** - Dropdown select with keyboard navigation
+- **Checkbox** - Accessible checkbox with proper labeling
+- **Radio** - Radio button group with fieldset support
+- **Label** - Accessible form label component
+- **Fieldset** - Form fieldset for grouping related inputs
+
+### UI Components
+- **Button** - Accessible button with multiple variants
+- **Link** - Accessible link component
+- **Modal** - Accessible modal dialog with focus trap
+- **Tabs** - Keyboard-navigable tab component
+- **DataTable** - Accessible data table with sorting
+- **Toast** - Accessible toast notification system
+- **ToastProvider** - Context provider for toast notifications
+
+### Hooks
+- **useFocusTrap** - Trap focus within a container
+- **useFocusReturn** - Return focus to previous element
+- **useAriaLive** - Manage ARIA live regions for announcements
 
-## Component Library
+### Utilities
+- **aria** - ARIA attribute utilities
+- **keyboard** - Keyboard event utilities
+- **focus** - Focus management utilities
 
-### Available Components
+### Design Tokens
+- **colors** - Color palette and theme tokens
+- **typography** - Typography scale and font tokens
+- **spacing** - Spacing scale tokens
+- **breakpoints** - Responsive breakpoint tokens
+- **motion** - Animation and transition tokens
 
-- **Button**: Accessible button with variants, sizes, and loading states
-- **Link**: Semantic link component with external link detection
-- **Modal**: Focus-trapped modal dialog with ARIA support
-- **DataTable**: Accessible table with keyboard navigation and sorting
-- **Toast**: Notification system with ARIA live regions
-- **Tabs**: Tab component with arrow key navigation
-- **Form Components**: Input, Textarea, Select, Checkbox, Radio, Fieldset, Label
+## Documentation
 
-### Usage Example
+📚 **[View Full Documentation & Storybook](https://ui.a11ypros.com/storybook)**
+
+Browse all components, see live examples, and explore accessibility features in our interactive Storybook documentation.
+
+## Usage Examples
+
+### Form with Validation
 
 ```tsx
-import { Button, Input, Modal } from '@a11ypros/a11y-ui-components'
+import { Input, Button, Label } from '@a11ypros/a11y-ui-components';
+
+function LoginForm() {
+  const [email, setEmail] = useState('');
+  const [error, setError] = useState('');
+
+  return (
+    <form>
+      <Input
+        label="Email"
+        type="email"
+        value={email}
+        onChange={(e) => setEmail(e.target.value)}
+        error={error}
+        required
+      />
+      <Button type="submit">Sign In</Button>
+    </form>
+  );
+}
+```
+
+### Modal Dialog
+
+```tsx
+import { Modal, Button } from '@a11ypros/a11y-ui-components';
+import { useState } from 'react';
+
+function App() {
+  const [isOpen, setIsOpen] = useState(false);
 
-function MyComponent() {
-  const [isOpen, setIsOpen] = useState(false)
-  
   return (
     <>
-      <Button variant="primary" onClick={() => setIsOpen(true)}>
-        Open Modal
-      </Button>
-      
+      <Button onClick={() => setIsOpen(true)}>Open Modal</Button>
       <Modal
         isOpen={isOpen}
         onClose={() => setIsOpen(false)}
-        title="Example Modal"
+        title="Confirm Action"
       >
-        <Input label="Email" type="email" required />
+        <p>Are you sure you want to proceed?</p>
+        <Button onClick={() => setIsOpen(false)}>Confirm</Button>
       </Modal>
     </>
-  )
+  );
 }
 ```
 
-## WCAG Compliance
-
-Each component documents its WCAG 2.1/2.2 compliance:
-
-- **1.3.1** Info and Relationships (semantic HTML)
-- **1.4.3** Contrast (Minimum) - via design tokens
-- **2.1.1** Keyboard (all interactive elements)
-- **2.4.7** Focus Visible
-- **2.5.3** Label in Name
-- **4.1.2** Name, Role, Value (ARIA)
-- **4.1.3** Status Messages (for Toast)
+### Toast Notifications
 
-## AI Audit Assistant
-
-The AI Audit Assistant analyzes JSX code snippets for accessibility issues:
+```tsx
+import { ToastProvider, useToast, Button } from '@a11ypros/a11y-ui-components';
 
-1. Navigate to `/audit` in the Next.js app
-2. Paste your JSX code
-3. Click "Run Accessibility Audit"
-4. Review issues grouped by WCAG Success Criteria
-5. See code suggestions for each issue
+function App() {
+  return (
+    <ToastProvider>
+      <MyComponent />
+    </ToastProvider>
+  );
+}
 
-### API Setup
+function MyComponent() {
+  const { addToast } = useToast();
 
-The audit assistant requires an Anthropic API key:
+  return (
+    <Button
+      onClick={() =>
+        addToast({
+          message: 'Action completed successfully!',
+          type: 'success',
+        })
+      }
+    >
+      Show Toast
+    </Button>
+  );
+}
+```
 
-1. Get your API key from [Anthropic](https://console.anthropic.com/)
-2. Add it to `apps/web/.env.local`:
-   ```
-   ANTHROPIC_API_KEY=your_key_here
-   ```
+## Important Note on Accessibility
 
-## Design Tokens
+> **Note**: While these components are built with accessibility in mind and meet WCAG 2.1/2.2 Level AA standards, **simply using these components does not guarantee an accessible application**. These components are foundational building blocks that must be used properly within the larger consuming application with accessibility in mind.
 
-The design system uses CSS custom properties for theming:
+To ensure your application is truly accessible, consider:
 
-```css
-/* Colors */
---color-primary-500: #0ea5e9;
---color-text-primary: #171717;
+- **Proper Implementation**: Use components according to their documented patterns and accessibility guidelines
+- **Application-Level Considerations**: Ensure proper page structure, heading hierarchy, and landmark regions
+- **Content Accessibility**: Write clear, descriptive text and provide alternative text for images
+- **Testing**: Regularly test your application with keyboard navigation and screen readers
+- **User Experience**: Consider the full user journey and how components work together
 
-/* Spacing */
---spacing-4: 1rem;
+## Internationalization (i18n)
 
-/* Typography */
---font-size-base: 1rem;
---font-weight-semibold: 600;
+Currently, all screen reader text and ARIA labels are provided in English. Full i18n support is a high-priority feature coming soon to ensure global accessibility.
 
-/* Motion */
---motion-duration-normal: 200ms;
-```
+## Tree Shaking
 
-## Storybook
+This package is fully tree-shakeable. Import only what you need:
 
-View all components and their documentation in Storybook:
+```tsx
+// ✅ Good - tree-shakeable
+import { Button } from '@a11ypros/a11y-ui-components';
 
-```bash
-npm run storybook
+// ✅ Also good - import specific utilities
+import { useFocusTrap } from '@a11ypros/a11y-ui-components';
 ```
 
-Each component story includes:
-- Usage examples
-- Accessibility notes
-- Keyboard interaction tables
-- WCAG compliance information
+## TypeScript Support
 
-## Building
+Full TypeScript definitions are included. No need to install `@types` packages.
 
-Build the Next.js app:
-```bash
-npm run build
-```
+```tsx
+import { Button, ButtonProps } from '@a11ypros/a11y-ui-components';
 
-Build Storybook:
-```bash
-npm run build-storybook
+const props: ButtonProps = {
+  variant: 'primary',
+  size: 'medium',
+  children: 'Click me',
+};
 ```
 
-## Testing Accessibility
-
-### Automated Testing
-
-Storybook includes the `@storybook/addon-a11y` addon for automated accessibility checks.
-
-### Manual Testing
-
-1. **Keyboard Navigation**: Test all components with keyboard only (Tab, Arrow keys, Enter/Space)
-2. **Screen Reader**: Test with NVDA (Windows), VoiceOver (macOS), or JAWS
-3. **Focus Indicators**: Ensure all interactive elements have visible focus styles
-4. **Color Contrast**: Verify text meets WCAG AA contrast ratios (4.5:1)
-
 ## Contributing
 
-When adding new components:
-
-1. Follow the existing component structure
-2. Include proper ARIA attributes
-3. Add keyboard navigation support
-4. Include focus management
-5. Add Storybook stories with accessibility documentation
-6. Test with keyboard and screen readers
+Contributions are welcome! Please see our [GitHub repository](https://github.com/ryan0122/a11ypros-components) for contribution guidelines.
 
 ## License
 
-MIT
+MIT © [A11y Pros](https://a11ypros.com)
 
-## Resources
+## Links
 
-- [WCAG 2.1 Guidelines](https://www.w3.org/WAI/WCAG21/quickref/)
-- [WAI-ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/)
-- [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/)
+- 📦 [npm package](https://www.npmjs.com/package/@a11ypros/a11y-ui-components)
+- 📚 [Documentation & Storybook](https://ui.a11ypros.com/storybook)
+- 🐛 [Issue Tracker](https://github.com/ryan0122/a11ypros-components/issues)
+- 💻 [Source Code](https://github.com/ryan0122/a11ypros-components)
 

package/dist/components/Button/Button.d.ts

@@ -0,0 +1,37 @@
+import React from 'react';
+import './Button.css';
+export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+    /**
+     * Visual variant of the button
+     */
+    variant?: 'primary' | 'secondary' | 'ghost' | 'danger';
+    /**
+     * Size of the button
+     */
+    size?: 'sm' | 'md' | 'lg';
+    /**
+     * Whether the button is in a loading state
+     */
+    loading?: boolean;
+    /**
+     * ARIA label for the button (required if no visible text)
+     */
+    'aria-label'?: string;
+}
+/**
+ * Accessible Button component
+ *
+ * WCAG Compliance:
+ * - 2.1.1 Keyboard: Full keyboard support (Enter/Space)
+ * - 2.4.7 Focus Visible: Clear focus indicators
+ * - 4.1.2 Name, Role, Value: Proper ARIA attributes
+ *
+ * @example
+ * ```tsx
+ * <Button variant="primary" onClick={handleClick}>
+ *   Click me
+ * </Button>
+ * ```
+ */
+export declare const Button: React.ForwardRefExoticComponent<ButtonProps & React.RefAttributes<HTMLButtonElement>>;
+//# sourceMappingURL=Button.d.ts.map

package/dist/components/Button/Button.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Button.d.ts","sourceRoot":"","sources":["../../../src/components/Button/Button.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAA;AAGzB,OAAO,cAAc,CAAA;AAErB,MAAM,WAAW,WAAY,SAAQ,KAAK,CAAC,oBAAoB,CAAC,iBAAiB,CAAC;IAChF;;OAEG;IACH,OAAO,CAAC,EAAE,SAAS,GAAG,WAAW,GAAG,OAAO,GAAG,QAAQ,CAAA;IAEtD;;OAEG;IACH,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAA;IAEzB;;OAEG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;IAEjB;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,MAAM,uFA2FlB,CAAA"}

package/dist/components/Button/Button.js

@@ -0,0 +1,52 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import React from 'react';
+import { createActivationHandler } from '../../utils/keyboard';
+import { getAriaLabel, getBusyAttributes } from '../../utils/aria';
+import './Button.css';
+/**
+ * Accessible Button component
+ *
+ * WCAG Compliance:
+ * - 2.1.1 Keyboard: Full keyboard support (Enter/Space)
+ * - 2.4.7 Focus Visible: Clear focus indicators
+ * - 4.1.2 Name, Role, Value: Proper ARIA attributes
+ *
+ * @example
+ * ```tsx
+ * <Button variant="primary" onClick={handleClick}>
+ *   Click me
+ * </Button>
+ * ```
+ */
+export const Button = React.forwardRef(({ variant = 'primary', size = 'md', loading = false, disabled, children, className = '', onClick, onKeyDown, 'aria-label': ariaLabel, ...props }, ref) => {
+    const isDisabled = disabled || loading;
+    const handleKeyDown = React.useCallback((event) => {
+        // Handle activation keys
+        const activationHandler = createActivationHandler((e) => {
+            if (!isDisabled && onClick) {
+                onClick(e);
+            }
+        });
+        activationHandler(event);
+        // Call user's onKeyDown if provided
+        if (onKeyDown) {
+            onKeyDown(event);
+        }
+    }, [isDisabled, onClick, onKeyDown]);
+    const ariaProps = {
+        ...getAriaLabel(ariaLabel),
+        ...getBusyAttributes(loading),
+        ...props,
+    };
+    const classes = [
+        'btn',
+        `btn--${variant}`,
+        `btn--${size}`,
+        loading && 'btn--loading',
+        className,
+    ]
+        .filter(Boolean)
+        .join(' ');
+    return (_jsxs("button", { ref: ref, type: "button", className: classes, disabled: isDisabled, onClick: onClick, onKeyDown: handleKeyDown, "aria-disabled": isDisabled, ...ariaProps, children: [loading && (_jsx("span", { className: "btn__spinner", "aria-hidden": "true", children: _jsx("svg", { className: "btn__spinner-icon", width: "16", height: "16", viewBox: "0 0 16 16", fill: "none", xmlns: "http://www.w3.org/2000/svg", children: _jsx("circle", { className: "btn__spinner-circle", cx: "8", cy: "8", r: "6", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", strokeDasharray: "31.416", strokeDashoffset: "31.416" }) }) })), _jsx("span", { className: "btn__content", children: children })] }));
+});
+Button.displayName = 'Button';

package/dist/components/Button/index.d.ts

@@ -0,0 +1,3 @@
+export { Button } from './Button';
+export type { ButtonProps } from './Button';
+//# sourceMappingURL=index.d.ts.map

package/dist/components/Button/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/Button/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAA;AACjC,YAAY,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA"}

package/dist/components/Button/index.js

@@ -0,0 +1 @@
+export { Button } from './Button';

package/dist/components/DataTable/DataTable.d.ts

@@ -0,0 +1,71 @@
+import React from 'react';
+import './DataTable.css';
+export interface DataTableColumn<T> {
+    key: string;
+    header: string;
+    render?: (row: T, index: number) => React.ReactNode;
+    sortable?: boolean;
+    width?: string;
+}
+export interface DataTableProps<T> {
+    /**
+     * Data rows
+     */
+    data: T[];
+    /**
+     * Column definitions
+     */
+    columns: DataTableColumn<T>[];
+    /**
+     * Key function to get unique ID for each row
+     */
+    getRowId: (row: T) => string;
+    /**
+     * Whether rows are selectable
+     */
+    selectable?: boolean;
+    /**
+     * Selected row IDs
+     */
+    selectedRows?: string[];
+    /**
+     * Callback when selection changes
+     */
+    onSelectionChange?: (selectedIds: string[]) => void;
+    /**
+     * Sort configuration
+     */
+    sortConfig?: {
+        column: string;
+        direction: 'asc' | 'desc';
+    };
+    /**
+     * Callback when sort changes
+     */
+    onSortChange?: (column: string, direction: 'asc' | 'desc') => void;
+    /**
+     * Caption for the table (required for accessibility)
+     */
+    caption?: string;
+}
+/**
+ * Accessible DataTable component
+ *
+ * WCAG Compliance:
+ * - 1.3.1 Info and Relationships: Semantic table structure
+ * - 2.1.1 Keyboard: Arrow keys, Home/End navigation
+ * - 4.1.2 Name, Role, Value: Proper ARIA attributes
+ * - 4.1.3 Status Messages: Sort announcements
+ *
+ * @example
+ * ```tsx
+ * <DataTable
+ *   data={users}
+ *   columns={columns}
+ *   getRowId={(user) => user.id}
+ *   caption="User list"
+ * />
+ * ```
+ */
+export declare function DataTable<T extends Record<string, any>>({ data, columns, getRowId, selectable, selectedRows, onSelectionChange, sortConfig, onSortChange, caption, }: DataTableProps<T>): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=DataTable.d.ts.map

package/dist/components/DataTable/DataTable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DataTable.d.ts","sourceRoot":"","sources":["../../../src/components/DataTable/DataTable.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAwC,MAAM,OAAO,CAAA;AAI5D,OAAO,iBAAiB,CAAA;AAExB,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,GAAG,EAAE,MAAM,CAAA;IACX,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,KAAK,CAAC,SAAS,CAAA;IACnD,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,cAAc,CAAC,CAAC;IAC/B;;OAEG;IACH,IAAI,EAAE,CAAC,EAAE,CAAA;IAET;;OAEG;IACH,OAAO,EAAE,eAAe,CAAC,CAAC,CAAC,EAAE,CAAA;IAE7B;;OAEG;IACH,QAAQ,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,MAAM,CAAA;IAE5B;;OAEG;IACH,UAAU,CAAC,EAAE,OAAO,CAAA;IAEpB;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAA;IAEvB;;OAEG;IACH,iBAAiB,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,IAAI,CAAA;IAEnD;;OAEG;IACH,UAAU,CAAC,EAAE;QACX,MAAM,EAAE,MAAM,CAAA;QACd,SAAS,EAAE,KAAK,GAAG,MAAM,CAAA;KAC1B,CAAA;IAED;;OAEG;IACH,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,GAAG,MAAM,KAAK,IAAI,CAAA;IAElE;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,EACvD,IAAI,EACJ,OAAO,EACP,QAAQ,EACR,UAAkB,EAClB,YAAiB,EACjB,iBAAiB,EACjB,UAAU,EACV,YAAY,EACZ,OAAO,GACR,EAAE,cAAc,CAAC,CAAC,CAAC,2CAoMnB"}