@a11ypros/a11y-ui-components 1.0.0 → 1.0.1

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

@@ -0,0 +1,293 @@
+'use client'
+
+import React, { useState, useRef, useCallback } from 'react'
+import { useAriaLive } from '../../hooks/useAriaLive'
+import { createArrowKeyHandler, isNavigationKey } from '../../utils/keyboard'
+import { Checkbox } from '../Form/Checkbox'
+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 function DataTable<T extends Record<string, any>>({
+  data,
+  columns,
+  getRowId,
+  selectable = false,
+  selectedRows = [],
+  onSelectionChange,
+  sortConfig,
+  onSortChange,
+  caption,
+}: DataTableProps<T>) {
+  const [focusedRow, setFocusedRow] = useState<string | null>(null)
+  const tableRef = useRef<HTMLTableElement>(null)
+  const rowRefs = useRef<Map<string, HTMLTableRowElement>>(new Map())
+
+  // Announce sort changes
+  const sortAnnouncement = sortConfig
+    ? `Sorted by ${columns.find((c) => c.key === sortConfig.column)?.header || sortConfig.column}, ${sortConfig.direction === 'asc' ? 'ascending' : 'descending'}`
+    : undefined
+  useAriaLive(sortAnnouncement, 'polite')
+
+  const handleSelectAll = useCallback(() => {
+    if (!onSelectionChange) return
+
+    const allSelected = selectedRows.length === data.length
+    if (allSelected) {
+      onSelectionChange([])
+    } else {
+      onSelectionChange(data.map(getRowId))
+    }
+  }, [data, selectedRows, onSelectionChange, getRowId])
+
+  const handleSelectRow = useCallback(
+    (rowId: string) => {
+      if (!onSelectionChange) return
+
+      const isSelected = selectedRows.includes(rowId)
+      if (isSelected) {
+        onSelectionChange(selectedRows.filter((id) => id !== rowId))
+      } else {
+        onSelectionChange([...selectedRows, rowId])
+      }
+    },
+    [selectedRows, onSelectionChange]
+  )
+
+  const handleSort = useCallback(
+    (columnKey: string) => {
+      if (!onSortChange || !columns.find((c) => c.key === columnKey)?.sortable) {
+        return
+      }
+
+      const newDirection =
+        sortConfig?.column === columnKey && sortConfig.direction === 'asc'
+          ? 'desc'
+          : 'asc'
+      onSortChange(columnKey, newDirection)
+    },
+    [onSortChange, sortConfig, columns]
+  )
+
+  const handleKeyDown = useCallback(
+    (event: React.KeyboardEvent<HTMLTableRowElement>, rowId: string, index: number) => {
+      const row = rowRefs.current.get(rowId)
+      if (!row) return
+
+      if (isNavigationKey(event.key)) {
+        event.preventDefault()
+
+        let newIndex = index
+        switch (event.key) {
+          case 'ArrowDown':
+            newIndex = Math.min(index + 1, data.length - 1)
+            break
+          case 'ArrowUp':
+            newIndex = Math.max(index - 1, 0)
+            break
+          case 'Home':
+            newIndex = 0
+            break
+          case 'End':
+            newIndex = data.length - 1
+            break
+        }
+
+        const newRowId = getRowId(data[newIndex])
+        setFocusedRow(newRowId)
+        rowRefs.current.get(newRowId)?.focus()
+      } else if (event.key === ' ' && selectable) {
+        event.preventDefault()
+        handleSelectRow(rowId)
+      }
+    },
+    [data, selectable, handleSelectRow, getRowId]
+  )
+
+  const allSelected = data.length > 0 && selectedRows.length === data.length
+  const someSelected = selectedRows.length > 0 && selectedRows.length < data.length
+
+  return (
+    <div className="data-table-wrapper">
+      <table
+        ref={tableRef}
+        className="data-table"
+        aria-label={caption}
+      >
+        {caption && <caption className="data-table-caption">{caption}</caption>}
+        <thead>
+          <tr>
+            {selectable && (
+              <th scope="col" className="data-table-header data-table-header--checkbox">
+                <Checkbox
+                  checked={allSelected}
+                  aria-label="Select all rows"
+                  onChange={handleSelectAll}
+                  aria-checked={allSelected ? 'true' : someSelected ? 'mixed' : 'false'}
+                />
+              </th>
+            )}
+            {columns.map((column) => (
+              <th
+                key={column.key}
+                scope="col"
+                className={`data-table-header ${column.sortable ? 'data-table-header--sortable' : ''}`}
+                style={column.width ? { width: column.width } : undefined}
+                aria-sort={
+                  sortConfig?.column === column.key
+                    ? sortConfig.direction === 'asc'
+                      ? 'ascending'
+                      : 'descending'
+                    : 'none'
+                }
+              >
+                {column.sortable ? (
+                  <button
+                    type="button"
+                    className="data-table-sort-button"
+                    aria-label={
+                      sortConfig?.column === column.key
+                        ? `${column.header}, sorted ${sortConfig.direction === 'asc' ? 'ascending' : 'descending'}, activate to sort ${sortConfig.direction === 'asc' ? 'descending' : 'ascending'}`
+                        : `Sort by ${column.header}`
+                    }
+                    onClick={() => handleSort(column.key)}
+                  >
+                    {column.header}
+                    {sortConfig?.column === column.key && (
+                      <span className="data-table-sort-indicator" aria-hidden="true">
+                        {sortConfig.direction === 'asc' ? ' ↑' : ' ↓'}
+                      </span>
+                    )}
+                  </button>
+                ) : (
+                  column.header
+                )}
+              </th>
+            ))}
+          </tr>
+        </thead>
+        <tbody>
+          {data.map((row, index) => {
+            const rowId = getRowId(row)
+            const isSelected = selectedRows.includes(rowId)
+            const isFocused = focusedRow === rowId
+
+            return (
+              <tr
+                key={rowId}
+                ref={(el) => {
+                  if (el) {
+                    rowRefs.current.set(rowId, el)
+                  } else {
+                    rowRefs.current.delete(rowId)
+                  }
+                }}
+                className={`data-table-row ${isSelected ? 'data-table-row--selected' : ''} ${isFocused ? 'data-table-row--focused' : ''}`}
+                tabIndex={0}
+                aria-selected={selectable ? isSelected : undefined}
+                onKeyDown={(e) => handleKeyDown(e, rowId, index)}
+                onClick={() => {
+                  if (selectable) {
+                    handleSelectRow(rowId)
+                  }
+                }}
+              >
+                {selectable && (
+                  <td className="data-table-cell data-table-cell--checkbox">
+                    <Checkbox
+                      checked={isSelected}
+                      aria-label={`Select row ${index + 1}`}
+                      onChange={() => handleSelectRow(rowId)}
+                      onClick={(e) => e.stopPropagation()}
+                    />
+                  </td>
+                )}
+                {columns.map((column) => (
+                  <td key={column.key} className="data-table-cell">
+                    {column.render ? column.render(row, index) : row[column.key]}
+                  </td>
+                ))}
+              </tr>
+            )
+          })}
+        </tbody>
+      </table>
+    </div>
+  )
+}
+

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

@@ -0,0 +1,3 @@
+export { DataTable } from './DataTable'
+export type { DataTableProps, DataTableColumn } from './DataTable'
+

package/packages/design-system/src/components/Form/Checkbox.stories.tsx

@@ -0,0 +1,252 @@
+import type { Meta, StoryObj } from '@storybook/react'
+import { useState } from 'react'
+import { Checkbox } from './Checkbox'
+
+/**
+ * # Checkbox Component
+ * 
+ * An accessible checkbox component with proper label association, error handling,
+ * and ARIA attributes. Supports both controlled and uncontrolled usage.
+ * 
+ * ## Usage
+ * 
+ * ```tsx
+ * import { Checkbox } from '@a11ypros/a11y-ui-components'
+ * 
+ * function MyComponent() {
+ *   const [checked, setChecked] = useState(false)
+ *   
+ *   return (
+ *     <Checkbox
+ *       id="agree"
+ *       label="I agree to the terms and conditions"
+ *       checked={checked}
+ *       onChange={(e) => setChecked(e.target.checked)}
+ *     />
+ *   )
+ * }
+ * ```
+ * 
+ * ## Features
+ * 
+ * - **Label association**: Labels are properly associated with checkboxes using \`htmlFor\` and \`id\`
+ * - **Error handling**: Error messages are announced to screen readers via ARIA
+ * - **Helper text**: Optional helper text for additional context
+ * - **Keyboard accessible**: Full keyboard support with Space key for toggling
+ * 
+ * ## Accessibility
+ * 
+ * ### WCAG 2.1/2.2 Compliance
+ * 
+ * - **1.3.1 Info and Relationships**: Proper label-checkbox association via \`htmlFor\` and \`id\`
+ * - **2.5.3 Label in Name**: Label text matches accessible name
+ * - **4.1.2 Name, Role, Value**: Proper ARIA attributes including \`aria-required\`, \`aria-invalid\`, \`aria-describedby\`
+ * 
+ * ### Keyboard Interactions
+ * 
+ * | Key | Action |
+ * |-----|--------|
+ * | **Tab** | Moves focus to the checkbox |
+ * | **Shift+Tab** | Moves focus away from the checkbox |
+ * | **Space** | Toggles checkbox state |
+ * | **Enter** | Toggles checkbox state (in some contexts) |
+ * 
+ * ### Screen Reader Support
+ * 
+ * - Checkbox role and label are announced when focused
+ * - Checked state is announced ("checked" or "not checked")
+ * - Required state is announced ("required")
+ * - Error messages are announced when present
+ * - Helper text is announced via \`aria-describedby\`
+ * 
+ * ### Focus Management
+ * 
+ * - Focus indicators use 2px solid outline with 2px offset
+ * - Focus styles respect \`prefers-reduced-motion\` media query
+ * - Error state has distinct focus styling
+ * - Focus visible only on keyboard navigation using \`:focus-visible\`
+ * 
+ * ## Best Practices
+ * 
+ * 1. **Always provide a label**: Required for accessibility and usability
+ * 2. **Use for binary choices**: Checkboxes are for independent yes/no choices
+ * 3. **Group related checkboxes**: Use Fieldset component to group related options
+ * 4. **Provide helpful error messages**: Be specific about what needs to be checked
+ * 5. **Use helper text for guidance**: Help users understand the implications of checking
+ * 
+ * ## Common Pitfalls
+ * 
+ * - Missing label (screen readers can't identify the checkbox)
+ * - Using checkbox for single choice (use Radio for mutually exclusive options)
+ * - Vague error messages (be specific about validation failures)
+ * - Not grouping related checkboxes (use Fieldset for logical grouping)
+ * - Using wrong element (use Radio for single choice from multiple options)
+ * 
+ * @component
+ * @example
+ * ```tsx
+ * <Checkbox
+ *   id="terms"
+ *   label="I agree to the terms"
+ *   required
+ *   error={errors.terms}
+ * />
+ * ```
+ */
+const meta: Meta<typeof Checkbox> = {
+  title: 'Components/Form/Checkbox',
+  component: Checkbox,
+  tags: ['autodocs'],
+}
+
+export default meta
+type Story = StoryObj<typeof Checkbox>
+
+/**
+ * Standard checkbox with label. The label is properly associated
+ * with the checkbox for screen readers and clicking the label toggles the checkbox.
+ */
+export const Default: Story = {
+  render: () => {
+    const [checked, setChecked] = useState(false)
+    return (
+      <Checkbox
+        id="checkbox-default"
+        label="I agree to the terms and conditions"
+        checked={checked}
+        onChange={(e) => setChecked(e.target.checked)}
+      />
+    )
+  },
+}
+
+/**
+ * Checkbox with error message. Error messages are announced to screen readers
+ * and displayed visually below the checkbox. The checkbox is marked as invalid
+ * with \`aria-invalid="true"\`.
+ */
+export const WithError: Story = {
+  render: () => {
+    const [checked, setChecked] = useState(false)
+    return (
+      <Checkbox
+        id="checkbox-error"
+        label="I agree to the terms"
+        checked={checked}
+        onChange={(e) => setChecked(e.target.checked)}
+        error="You must agree to the terms to continue"
+      />
+    )
+  },
+}
+
+/**
+ * Checkbox with helper text. Helper text provides additional context or guidance
+ * and is associated with the checkbox via \`aria-describedby\`.
+ */
+export const WithHelperText: Story = {
+  render: () => {
+    const [checked, setChecked] = useState(false)
+    return (
+      <Checkbox
+        id="checkbox-helper"
+        label="Subscribe to newsletter"
+        checked={checked}
+        onChange={(e) => setChecked(e.target.checked)}
+        helperText="Receive weekly updates about new features"
+      />
+    )
+  },
+}
+
+/**
+ * Required checkbox field. Required checkboxes are marked with \`aria-required="true"\`
+ * and display a visual indicator (asterisk) next to the label.
+ */
+export const Required: Story = {
+  render: () => {
+    const [checked, setChecked] = useState(false)
+    return (
+      <Checkbox
+        id="checkbox-required"
+        label="I accept the privacy policy"
+        checked={checked}
+        onChange={(e) => setChecked(e.target.checked)}
+        required
+      />
+    )
+  },
+}
+
+/**
+ * Disabled checkbox that cannot be toggled. Disabled checkboxes are announced as
+ * "disabled" by screen readers and appear visually dimmed.
+ */
+export const Disabled: Story = {
+  args: {
+    id: 'checkbox-disabled',
+    label: 'This option is disabled',
+    disabled: true,
+    checked: false,
+  },
+}
+
+/**
+ * Checked checkbox state. Shows the checkbox in its checked state.
+ */
+export const Checked: Story = {
+  args: {
+    id: 'checkbox-checked',
+    label: 'This option is selected',
+    checked: true,
+  },
+}
+
+/**
+ * Multiple checkboxes grouped together. Use Fieldset component to group
+ * related checkboxes for better semantic structure and accessibility.
+ */
+export const Grouped: Story = {
+  render: () => {
+    const [preferences, setPreferences] = useState({
+      email: false,
+      sms: false,
+      push: false,
+    })
+
+    const handleChange = (key: keyof typeof preferences) => (e: React.ChangeEvent<HTMLInputElement>) => {
+      setPreferences((prev) => ({ ...prev, [key]: e.target.checked }))
+    }
+
+    return (
+      <div style={{ display: 'flex', flexDirection: 'column', gap: '1rem' }}>
+        <Checkbox
+          id="pref-email"
+          label="Email notifications"
+          checked={preferences.email}
+          onChange={handleChange('email')}
+        />
+        <Checkbox
+          id="pref-sms"
+          label="SMS notifications"
+          checked={preferences.sms}
+          onChange={handleChange('sms')}
+        />
+        <Checkbox
+          id="pref-push"
+          label="Push notifications"
+          checked={preferences.push}
+          onChange={handleChange('push')}
+        />
+      </div>
+    )
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Multiple checkboxes that can be selected independently. For better accessibility, wrap related checkboxes in a Fieldset component.',
+      },
+    },
+  },
+}
+

package/packages/design-system/src/components/Form/Checkbox.tsx

@@ -0,0 +1,114 @@
+'use client'
+
+import React from 'react'
+import { combineAriaDescribedBy } from '../../utils/aria'
+import './Checkbox.css'
+
+export interface CheckboxProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'type'> {
+  /**
+   * Label for the checkbox
+   */
+  label?: string
+  
+  /**
+   * Error message to display
+   */
+  error?: string
+  
+  /**
+   * Helper text to display
+   */
+  helperText?: string
+}
+
+/**
+ * Accessible Checkbox component
+ * 
+ * WCAG Compliance:
+ * - 1.3.1 Info and Relationships: Proper label-input association
+ * - 2.5.3 Label in Name: Label text matches accessible name
+ * - 4.1.2 Name, Role, Value: Proper ARIA attributes
+ * 
+ * @example
+ * ```tsx
+ * <Checkbox
+ *   id="agree"
+ *   label="I agree to the terms"
+ *   checked={checked}
+ *   onChange={handleChange}
+ * />
+ * ```
+ */
+export const Checkbox = React.forwardRef<HTMLInputElement, CheckboxProps>(
+  (
+    {
+      id,
+      label,
+      error,
+      helperText,
+      className = '',
+      'aria-describedby': ariaDescribedBy,
+      ...props
+    },
+    ref
+  ) => {
+    const checkboxId = React.useId()
+    const finalId = id || `checkbox-${checkboxId}`
+    const errorId = error ? `${finalId}-error` : undefined
+    const helperId = helperText ? `${finalId}-helper` : undefined
+
+    const describedBy = combineAriaDescribedBy(
+      ariaDescribedBy,
+      errorId,
+      helperId
+    )
+
+    const classes = [
+      'form-checkbox',
+      error && 'form-checkbox--error',
+      className,
+    ]
+      .filter(Boolean)
+      .join(' ')
+
+    return (
+      <div className="form-checkbox-wrapper">
+        <div className="form-checkbox-input-wrapper">
+          <input
+            ref={ref}
+            id={finalId}
+            type="checkbox"
+            className={classes}
+            aria-invalid={error ? true : undefined}
+            aria-describedby={describedBy}
+            required={props.required ? true : undefined}
+            {...props}
+          />
+          {label && (
+            <label htmlFor={finalId} className="form-checkbox-label">
+              {label}
+              {props.required && (
+                <span className="form-label__required" aria-hidden="true">
+                  {' '}*
+                </span>
+              )}
+            </label>
+          )}
+        </div>
+        {helperText && !error && (
+          <span id={helperId} className="form-helper-text">
+            {helperText}
+          </span>
+        )}
+        {error && (
+          <span id={errorId} className="form-error-text" role="alert">
+            {error}
+          </span>
+        )}
+      </div>
+    )
+  }
+)
+
+Checkbox.displayName = 'Checkbox'
+