@a11ypros/a11y-ui-components 1.0.1 → 1.0.2

package/packages/design-system/src/components/Button/Button.stories.tsx

@@ -1,228 +0,0 @@
-import type { Meta, StoryObj } from '@storybook/react'
-import { Button } from './Button'
-
-/**
- * # Button Component
- * 
- * An accessible, WCAG 2.1/2.2 compliant button component with full keyboard support,
- * focus management, and ARIA attributes.
- * 
- * ## Usage
- * 
- * ```tsx
- * import { Button } from '@a11ypros/a11y-ui-components'
- * 
- * function MyComponent() {
- *   return (
- *     <Button variant="primary" onClick={handleClick}>
- *       Submit Form
- *     </Button>
- *   )
- * }
- * ```
- * 
- * ## Variants
- * 
- * - **primary**: Main call-to-action buttons (default)
- * - **secondary**: Secondary actions that are important but not the primary action
- * - **ghost**: Subtle actions with no background, minimal styling
- * - **danger**: Destructive actions like delete, remove, or cancel operations
- * 
- * ## Sizes
- * 
- * - **sm**: Small buttons for compact UIs (height: 32px)
- * - **md**: Medium buttons for standard use (height: 40px) - default
- * - **lg**: Large buttons for prominent actions (height: 48px)
- * 
- * ## States
- * 
- * - **loading**: Shows a loading indicator and disables interaction. Automatically sets `aria-busy="true"`
- * - **disabled**: Prevents all interaction. Button appears visually dimmed and is announced as "disabled button" by screen readers
- * 
- * ## Accessibility
- * 
- * ### WCAG 2.1/2.2 Compliance
- * 
- * - **1.3.1 Info and Relationships**: Uses semantic `<button>` element
- * - **2.1.1 Keyboard**: Full keyboard support (Enter/Space activation)
- * - **2.4.7 Focus Visible**: Clear 2px outline on focus (meets 3:1 contrast ratio)
- * - **4.1.2 Name, Role, Value**: Proper ARIA attributes and semantic HTML
- * - **4.1.3 Status Messages**: Loading state announced via `aria-busy="true"`
- * 
- * ### Keyboard Interactions
- * 
- * | Key | Action |
- * |-----|--------|
- * | Enter | Activates the button |
- * | Space | Activates the button |
- * | Tab | Moves focus to the button |
- * | Shift+Tab | Moves focus away from the button |
- * 
- * ### Screen Reader Support
- * 
- * - Button role and name are announced automatically
- * - Loading state: "Busy" announced via `aria-busy="true"`
- * - Disabled state: "Disabled button" announced via `aria-disabled="true"`
- * - Custom labels via `aria-label` prop for icon-only buttons
- * - Loading spinner hidden from screen readers (`aria-hidden="true"`)
- * 
- * ### Focus Management
- * 
- * - Focus indicators use 2px solid outline with 2px offset
- * - Focus styles respect `prefers-reduced-motion` media query
- * - High contrast mode supported via `prefers-contrast` media query
- * - Focus visible only on keyboard navigation (not mouse clicks) using `:focus-visible`
- * 
- * ## Best Practices
- * 
- * 1. Always provide accessible text: Use `children` for visible text or `aria-label` for icon-only buttons
- * 2. Use appropriate variants: Primary for main actions (one per page/section), danger for destructive actions
- * 3. Handle loading states: Use `loading` prop instead of manually disabling during async operations
- * 4. Don't use buttons for navigation: Use the Link component for navigation instead
- * 5. Provide feedback: Don't disable buttons without explaining why or providing alternative actions
- * 
- * ## Common Pitfalls
- * 
- * - Using `<div onClick={...}>` instead of Button (loses keyboard support and semantic meaning)
- * - Missing `aria-label` on icon-only buttons (screen readers can't understand the action)
- * - Using `disabled` without providing feedback or alternative actions
- * - Not handling loading states during async operations (users don't know if action is processing)
- * - Using buttons for navigation (use Link component instead for proper semantics)
- * - Removing focus styles (breaks keyboard navigation visibility)
- * 
- * @component
- * @example
- * ```tsx
- * <Button variant="primary" onClick={handleClick}>
- *   Click me
- * </Button>
- * ```
- */
-const meta: Meta<typeof Button> = {
-  title: 'Components/Button',
-  component: Button,
-  tags: ['autodocs'],
-  argTypes: {
-    variant: {
-      control: 'select',
-      options: ['primary', 'secondary', 'ghost', 'danger'],
-    },
-    size: {
-      control: 'select',
-      options: ['sm', 'md', 'lg'],
-    },
-    loading: {
-      control: 'boolean',
-    },
-    disabled: {
-      control: 'boolean',
-    },
-  },
-}
-
-export default meta
-type Story = StoryObj<typeof Button>
-
-/**
- * Primary buttons are used for the main call-to-action on a page or in a section.
- * They should be used sparingly - typically one per page or section.
- */
-export const Primary: Story = {
-  args: {
-    variant: 'primary',
-    children: 'Primary Button',
-  },
-}
-
-/**
- * Secondary buttons are used for secondary actions that are important but not
- * the primary action. They provide visual hierarchy.
- */
-export const Secondary: Story = {
-  args: {
-    variant: 'secondary',
-    children: 'Secondary Button',
-  },
-}
-
-/**
- * Ghost buttons have no background and minimal styling. Use for tertiary actions
- * or when you want a more subtle appearance.
- */
-export const Ghost: Story = {
-  args: {
-    variant: 'ghost',
-    children: 'Ghost Button',
-  },
-}
-
-/**
- * Danger buttons are used for destructive actions like delete, remove, or cancel
- * operations. They use red coloring to indicate the potentially harmful nature
- * of the action.
- */
-export const Danger: Story = {
-  args: {
-    variant: 'danger',
-    children: 'Delete',
-  },
-}
-
-/**
- * Buttons come in three sizes. Choose the size that fits your layout and
- * maintains visual hierarchy. Medium is the default size.
- */
-export const Sizes: Story = {
-  render: () => (
-    <div style={{ display: 'flex', gap: '1rem', alignItems: 'center', flexWrap: 'wrap' }}>
-      <Button size="sm">Small</Button>
-      <Button size="md">Medium</Button>
-      <Button size="lg">Large</Button>
-    </div>
-  ),
-}
-
-/**
- * Loading state shows a spinner and disables the button. Use this during
- * async operations to provide feedback and prevent duplicate submissions.
- * The button automatically sets `aria-busy="true"` to announce the loading state.
- */
-export const Loading: Story = {
-  args: {
-    loading: true,
-    children: 'Save',
-  },
-}
-
-/**
- * Disabled buttons cannot be interacted with. They appear visually dimmed
- * and are announced as "disabled button" by screen readers.
- */
-export const Disabled: Story = {
-  args: {
-    disabled: true,
-    children: 'Disabled Button',
-  },
-}
-
-/**
- * Icon-only buttons require an aria-label for accessibility. Without visible
- * text, screen readers need the aria-label to understand what the button does.
- */
-export const WithAriaLabel: Story = {
-  args: {
-    'aria-label': 'Close dialog',
-    children: '×',
-  },
-}
-
-export const AllVariants: Story = {
-  render: () => (
-    <div style={{ display: 'flex', gap: '1rem', flexWrap: 'wrap' }}>
-      <Button variant="primary">Primary</Button>
-      <Button variant="secondary">Secondary</Button>
-      <Button variant="ghost">Ghost</Button>
-      <Button variant="danger">Danger</Button>
-    </div>
-  ),
-}

package/packages/design-system/src/components/Button/Button.tsx

@@ -1,137 +0,0 @@
-import React from 'react'
-import { createActivationHandler } from '../../utils/keyboard'
-import { getAriaLabel, getBusyAttributes } from '../../utils/aria'
-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 const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
-  (
-    {
-      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: React.KeyboardEvent<HTMLButtonElement>) => {
-        // Handle activation keys
-        const activationHandler = createActivationHandler((e) => {
-          if (!isDisabled && onClick) {
-            onClick(e as any)
-          }
-        })
-        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 (
-      <button
-        ref={ref}
-        type="button"
-        className={classes}
-        disabled={isDisabled}
-        onClick={onClick}
-        onKeyDown={handleKeyDown}
-        aria-disabled={isDisabled}
-        {...ariaProps}
-      >
-        {loading && (
-          <span className="btn__spinner" aria-hidden="true">
-            <svg
-              className="btn__spinner-icon"
-              width="16"
-              height="16"
-              viewBox="0 0 16 16"
-              fill="none"
-              xmlns="http://www.w3.org/2000/svg"
-            >
-              <circle
-                className="btn__spinner-circle"
-                cx="8"
-                cy="8"
-                r="6"
-                stroke="currentColor"
-                strokeWidth="2"
-                strokeLinecap="round"
-                strokeDasharray="31.416"
-                strokeDashoffset="31.416"
-              />
-            </svg>
-          </span>
-        )}
-        <span className="btn__content">{children}</span>
-      </button>
-    )
-  }
-)
-
-Button.displayName = 'Button'
-

package/packages/design-system/src/components/Button/index.ts

@@ -1,3 +0,0 @@
-export { Button } from './Button'
-export type { ButtonProps } from './Button'
-

package/packages/design-system/src/components/DataTable/DataTable.stories.tsx

@@ -1,211 +0,0 @@
-import type { Meta, StoryObj } from '@storybook/react'
-import { useState, useMemo } from 'react'
-import { DataTable } from './DataTable'
-
-/**
- * # DataTable Component
- * 
- * An accessible data table component with keyboard navigation, sorting, and selection
- * capabilities. Uses semantic HTML table structure with enhanced accessibility features.
- * 
- * ## Usage
- * 
- * ```tsx
- * import { DataTable } from '@a11ypros/a11y-ui-components'
- * 
- * const data = [
- *   { id: '1', name: 'John Doe', email: 'john@example.com' },
- *   { id: '2', name: 'Jane Smith', email: 'jane@example.com' },
- * ]
- * 
- * const columns = [
- *   { key: 'name', header: 'Name', sortable: true },
- *   { key: 'email', header: 'Email', sortable: true },
- * ]
- * 
- * function MyComponent() {
- *   return (
- *     <DataTable
- *       data={data}
- *       columns={columns}
- *       getRowId={(row) => row.id}
- *       caption="User list"
- *     />
- *   )
- * }
- * ```
- * 
- * ## Features
- * 
- * - **Keyboard navigation**: Arrow keys to navigate rows, Home/End for first/last
- * - **Sorting**: Click column headers to sort (optional)
- * - **Selection**: Select rows with Space key or checkbox (optional)
- * - **Semantic HTML**: Uses proper `<table>`, `<thead>`, `<tbody>` structure
- * - **ARIA support**: Proper ARIA attributes for sortable columns and selected rows
- * 
- * ## Accessibility
- * 
- * ### WCAG 2.1/2.2 Compliance
- * 
- * - **1.3.1 Info and Relationships**: Semantic table structure with proper headers
- * - **2.1.1 Keyboard**: Full keyboard navigation with arrow keys, Home, End, Space
- * - **4.1.2 Name, Role, Value**: Proper ARIA attributes for table, rows, and cells
- * - **4.1.3 Status Messages**: Sort state and selection state announced to screen readers
- * 
- * ### Keyboard Interactions
- * 
- * | Key | Action |
- * |-----|--------|
- * | **Arrow Up** | Move to previous row |
- * | **Arrow Down** | Move to next row |
- * | **Home** | Move to first row |
- * | **End** | Move to last row |
- * | **Space** | Select/deselect row (if selectable) |
- * | **Tab** | Move focus to sortable column headers or other controls |
- * | **Enter** | Activate sort on column header |
- * 
- * ### Screen Reader Support
- * 
- * - Table caption is announced
- * - Column headers are associated with cells
- * - Sort state is announced (e.g., "Name column, sorted ascending")
- * - Row selection state is announced (e.g., "Row 2, selected")
- * - Cell content is read with column header context
- * 
- * ### Focus Management
- * 
- * - Focus moves between rows using arrow keys
- * - Focus moves to sortable column headers with Tab
- * - Selected rows maintain focus state
- * - Focus indicators visible on all interactive elements
- * 
- * ## Best Practices
- * 
- * 1. **Always provide a caption**: Required for screen readers to understand table purpose
- * 2. **Use proper column headers**: Headers should clearly describe column content
- * 3. **Keep tables focused**: Don't nest tables or use tables for layout
- * 4. **Limit row count**: Very large tables should use pagination
- * 5. **Make sortable columns clear**: Use visual indicators for sortable columns
- * 
- * ## Common Pitfalls
- * 
- * - Missing caption (screen readers can't understand table purpose)
- * - Using tables for layout (use CSS Grid or Flexbox instead)
- * - Missing column headers (breaks screen reader navigation)
- * - Too many columns (becomes hard to navigate)
- * - Not announcing sort/selection state (users don't know current state)
- * 
- * @component
- * @example
- * ```tsx
- * <DataTable
- *   data={users}
- *   columns={columns}
- *   getRowId={(row) => row.id}
- *   caption="User directory"
- *   sortable
- * />
- * ```
- */
-const meta: Meta<typeof DataTable> = {
-  title: 'Components/DataTable',
-  component: DataTable,
-  tags: ['autodocs'],
-}
-
-export default meta
-type Story = StoryObj<typeof DataTable>
-
-const sampleData = [
-  { id: '1', name: 'John Doe', email: 'john@example.com', role: 'Admin' },
-  { id: '2', name: 'Jane Smith', email: 'jane@example.com', role: 'User' },
-  { id: '3', name: 'Bob Johnson', email: 'bob@example.com', role: 'User' },
-]
-
-const columns = [
-  { key: 'name', header: 'Name', sortable: true },
-  { key: 'email', header: 'Email', sortable: true },
-  { key: 'role', header: 'Role', sortable: true },
-]
-
-// Helper function to sort data
-function sortData<T extends Record<string, any>>(
-  data: T[],
-  sortConfig: { column: string; direction: 'asc' | 'desc' } | undefined
-): T[] {
-  if (!sortConfig) return data
-
-  return [...data].sort((a, b) => {
-    const aValue = a[sortConfig.column]
-    const bValue = b[sortConfig.column]
-
-    if (aValue === bValue) return 0
-
-    const comparison = aValue < bValue ? -1 : 1
-    return sortConfig.direction === 'asc' ? comparison : -comparison
-  })
-}
-
-/**
- * Basic data table without sorting. Simple table display with keyboard navigation.
- */
-export const Default: Story = {
-  args: {
-    data: sampleData,
-    columns: [
-      { key: 'name', header: 'Name' },
-      { key: 'email', header: 'Email' },
-      { key: 'role', header: 'Role' },
-    ],
-    getRowId: (row) => row.id,
-    caption: 'User list',
-  },
-}
-
-/**
- * Selectable table allows users to select rows using Space key or checkboxes.
- * Selection state is announced to screen readers and can be used for bulk actions.
- */
-export const Selectable: Story = {
-  render: () => {
-    const [selectedRows, setSelectedRows] = useState<string[]>([])
-    return (
-      <DataTable
-        data={sampleData}
-        columns={[
-          { key: 'name', header: 'Name' },
-          { key: 'email', header: 'Email' },
-          { key: 'role', header: 'Role' },
-        ]}
-        getRowId={(row) => row.id}
-        selectable
-        selectedRows={selectedRows}
-        onSelectionChange={setSelectedRows}
-        caption="Selectable user list"
-      />
-    )
-  },
-}
-
-/**
- * Sortable table with controlled sorting. Sort configuration is managed externally,
- * allowing for server-side sorting or custom sort logic.
- */
-export const Sortable: Story = {
-  render: () => {
-    const [sortConfig, setSortConfig] = useState<{ column: string; direction: 'asc' | 'desc' } | undefined>()
-    const sortedData = useMemo(() => sortData(sampleData, sortConfig), [sortConfig])
-
-    return (
-      <DataTable
-        data={sortedData}
-        columns={columns}
-        getRowId={(row) => row.id}
-        sortConfig={sortConfig}
-        onSortChange={(column, direction) => setSortConfig({ column, direction })}
-        caption="Sortable user list"
-      />
-    )
-  },
-}
-