@a11ypros/a11y-ui-components 1.0.1 → 1.0.2

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

@@ -1,248 +0,0 @@
-'use client'
-
-import React, { useState, useCallback, useRef } from 'react'
-import { createArrowKeyHandler, isNavigationKey, isArrowKey } from '../../utils/keyboard'
-import { getExpandedAttributes, getSelectedAttributes, getCurrentAttributes } from '../../utils/aria'
-import './Tabs.css'
-
-export interface TabItem {
-  id: string
-  label: string
-  content: React.ReactNode
-  disabled?: boolean
-}
-
-export interface TabsProps {
-  /**
-   * Tab items
-   */
-  items: TabItem[]
-  
-  /**
-   * Default selected tab ID
-   */
-  defaultSelectedId?: string
-  
-  /**
-   * Controlled selected tab ID
-   */
-  selectedId?: string
-  
-  /**
-   * Callback when tab selection changes
-   */
-  onSelectionChange?: (id: string) => void
-  
-  /**
-   * Orientation of tabs
-   */
-  orientation?: 'horizontal' | 'vertical'
-  
-  /**
-   * Activation mode for tabs
-   * - 'automatic': Arrow keys both move focus and activate tabs immediately
-   * - 'manual': Arrow keys move focus only, Enter/Space activates the focused tab
-   * @default 'automatic'
-   */
-  activationMode?: 'automatic' | 'manual'
-  
-  /**
-   * Label for the tab list (required for accessibility)
-   */
-  'aria-label'?: string
-  'aria-labelledby'?: string
-}
-
-/**
- * Accessible Tabs component
- * 
- * WCAG Compliance:
- * - 2.1.1 Keyboard: Arrow key navigation, Home/End support
- * - 4.1.2 Name, Role, Value: ARIA tabs pattern
- * - 2.4.3 Focus Order: Proper focus management
- * 
- * @example
- * ```tsx
- * <Tabs
- *   items={[
- *     { id: 'tab1', label: 'Tab 1', content: <div>Content 1</div> },
- *     { id: 'tab2', label: 'Tab 2', content: <div>Content 2</div> },
- *   ]}
- *   aria-label="Settings tabs"
- * />
- * ```
- */
-export const Tabs: React.FC<TabsProps> = ({
-  items,
-  defaultSelectedId,
-  selectedId: controlledSelectedId,
-  onSelectionChange,
-  orientation = 'horizontal',
-  activationMode = 'automatic',
-  'aria-label': ariaLabel,
-  'aria-labelledby': ariaLabelledBy,
-}) => {
-  const initialSelectedId = defaultSelectedId || items[0]?.id
-  const [internalSelectedId, setInternalSelectedId] = useState(initialSelectedId)
-  const [focusedId, setFocusedId] = useState<string | null>(initialSelectedId)
-  const tabRefs = useRef<Map<string, HTMLButtonElement>>(new Map())
-
-  const selectedId = controlledSelectedId ?? internalSelectedId
-  const selectedIndex = items.findIndex((item) => item.id === selectedId)
-  
-  // In automatic mode, focused tab is always the selected tab
-  // In manual mode, focused tab can be different from selected tab
-  const effectiveFocusedId = activationMode === 'automatic' ? selectedId : (focusedId || selectedId)
-
-  const handleSelect = useCallback(
-    (id: string) => {
-      if (onSelectionChange) {
-        onSelectionChange(id)
-      } else {
-        setInternalSelectedId(id)
-      }
-      // In manual mode, update focused tab when selecting
-      if (activationMode === 'manual') {
-        setFocusedId(id)
-      }
-    },
-    [onSelectionChange, activationMode]
-  )
-
-  const handleKeyDown = useCallback(
-    (event: React.KeyboardEvent<HTMLButtonElement>, currentIndex: number) => {
-      const isHorizontal = orientation === 'horizontal'
-      let newIndex = currentIndex
-
-      // Handle Enter/Space for manual activation
-      if (activationMode === 'manual' && (event.key === 'Enter' || event.key === ' ')) {
-        event.preventDefault()
-        const currentTab = items[currentIndex]
-        if (currentTab && !currentTab.disabled) {
-          handleSelect(currentTab.id)
-        }
-        return
-      }
-
-      // Handle arrow keys and Home/End
-      if (isNavigationKey(event.key) || isArrowKey(event.key)) {
-        event.preventDefault()
-
-        switch (event.key) {
-          case 'Home':
-            newIndex = 0
-            break
-          case 'End':
-            newIndex = items.length - 1
-            break
-          case 'ArrowRight':
-            if (isHorizontal) {
-              newIndex = (currentIndex + 1) % items.length
-            }
-            break
-          case 'ArrowLeft':
-            if (isHorizontal) {
-              newIndex = (currentIndex - 1 + items.length) % items.length
-            }
-            break
-          case 'ArrowDown':
-            if (!isHorizontal) {
-              newIndex = (currentIndex + 1) % items.length
-            }
-            break
-          case 'ArrowUp':
-            if (!isHorizontal) {
-              newIndex = (currentIndex - 1 + items.length) % items.length
-            }
-            break
-        }
-
-        // Skip disabled tabs
-        while (items[newIndex]?.disabled && newIndex !== currentIndex) {
-          if (event.key === 'Home' || event.key === 'ArrowRight' || event.key === 'ArrowDown') {
-            newIndex = (newIndex + 1) % items.length
-          } else {
-            newIndex = (newIndex - 1 + items.length) % items.length
-          }
-        }
-
-        const newTab = items[newIndex]
-        if (newTab && !newTab.disabled) {
-          if (activationMode === 'automatic') {
-            // Automatic: move focus and activate
-            handleSelect(newTab.id)
-            tabRefs.current.get(newTab.id)?.focus()
-          } else {
-            // Manual: move focus only
-            setFocusedId(newTab.id)
-            tabRefs.current.get(newTab.id)?.focus()
-          }
-        }
-      }
-    },
-    [items, orientation, activationMode, handleSelect]
-  )
-
-  const selectedTab = items.find((item) => item.id === selectedId)
-
-  return (
-    <div className={`tabs tabs--${orientation}`}>
-      <div
-        className="tabs-list"
-        role="tablist"
-        aria-orientation={orientation}
-        aria-label={ariaLabel}
-        aria-labelledby={ariaLabelledBy}
-      >
-        {items.map((item, index) => {
-          const isSelected = item.id === selectedId
-          const isFocused = item.id === effectiveFocusedId
-          // In manual mode, focused tab should be focusable even if not selected
-          // In automatic mode, only selected tab is focusable
-          const tabIndex = activationMode === 'manual' 
-            ? (isFocused ? 0 : -1)
-            : (isSelected ? 0 : -1)
-
-          return (
-            <button
-              key={item.id}
-              ref={(el) => {
-                if (el) {
-                  tabRefs.current.set(item.id, el)
-                } else {
-                  tabRefs.current.delete(item.id)
-                }
-              }}
-              id={`tab-${item.id}`}
-              role="tab"
-              aria-controls={`tabpanel-${item.id}`}
-              aria-selected={isSelected}
-              tabIndex={tabIndex}
-              disabled={item.disabled}
-              className={`tabs-tab ${isSelected ? 'tabs-tab--selected' : ''} ${item.disabled ? 'tabs-tab--disabled' : ''}`}
-              onClick={() => !item.disabled && handleSelect(item.id)}
-              onKeyDown={(e) => handleKeyDown(e, index)}
-              onFocus={() => setFocusedId(item.id)}
-              {...getCurrentAttributes(isSelected ? 'page' : undefined)}
-            >
-              {item.label}
-            </button>
-          )
-        })}
-      </div>
-      {selectedTab && (
-        <div
-          id={`tabpanel-${selectedTab.id}`}
-          role="tabpanel"
-          aria-labelledby={`tab-${selectedTab.id}`}
-          className="tabs-panel"
-        >
-          {selectedTab.content}
-        </div>
-      )}
-    </div>
-  )
-}
-
-Tabs.displayName = 'Tabs'
-

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

@@ -1,3 +0,0 @@
-export { Tabs } from './Tabs'
-export type { TabsProps, TabItem } from './Tabs'
-

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

@@ -1,153 +0,0 @@
-import type { Meta, StoryObj } from '@storybook/react'
-import { ToastProvider, useToast } from './ToastProvider'
-import { Button } from '../Button/Button'
-
-/**
- * # Toast Component
- * 
- * An accessible toast notification system with ARIA live regions for screen reader
- * announcements. Provides non-intrusive feedback for user actions.
- * 
- * ## Usage
- * 
- * ```tsx
- * import { ToastProvider, useToast } from '@a11ypros/a11y-ui-components'
- * 
- * function MyComponent() {
- *   const { addToast } = useToast()
- *   
- *   const handleSave = async () => {
- *     await saveData()
- *     addToast({
- *       message: 'Data saved successfully',
- *       type: 'success'
- *     })
- *   }
- *   
- *   return <Button onClick={handleSave}>Save</Button>
- * }
- * 
- * // Wrap your app with ToastProvider
- * function App() {
- *   return (
- *     <ToastProvider>
- *       <MyComponent />
- *     </ToastProvider>
- *   )
- * }
- * ```
- * 
- * ## Toast Types
- * 
- * - **info**: Informational messages (blue)
- * - **success**: Success confirmations (green)
- * - **warning**: Warning messages (yellow/orange)
- * - **error**: Error messages (red)
- * 
- * ## Features
- * 
- * - **ARIA live regions**: Automatically announces to screen readers
- * - **Auto-dismiss**: Toasts automatically disappear after a timeout
- * - **Keyboard dismissible**: ESC key closes all toasts
- * - **Multiple toasts**: Can display multiple toasts simultaneously
- * - **Accessible close button**: Each toast has a close button with proper ARIA labels
- * 
- * ## Accessibility
- * 
- * ### WCAG 2.1/2.2 Compliance
- * 
- * - **4.1.3 Status Messages**: ARIA live region announcements for screen readers
- * - **2.1.1 Keyboard**: ESC key support to dismiss toasts
- * - **4.1.2 Name, Role, Value**: Proper ARIA attributes and semantic HTML
- * - **2.4.7 Focus Visible**: Clear focus indicators on close buttons
- * 
- * ### Keyboard Interactions
- * 
- * | Key | Action |
- * |-----|--------|
- * | **ESC** | Closes all visible toasts |
- * | **Tab** | Moves focus to toast close button |
- * | **Enter/Space** | Activates close button |
- * 
- * ### Screen Reader Support
- * 
- * - Toast messages are announced via ARIA live regions
- * - Live region politeness: "polite" for info/success, "assertive" for warnings/errors
- * - Close button has accessible label ("Close notification")
- * - Toast type is included in announcement when relevant
- * 
- * ### Focus Management
- * 
- * - Focus moves to close button when toast appears (optional, can be configured)
- * - Focus returns to previous element when toast closes
- * - Toasts don't trap focus (unlike modals)
- * 
- * ## Best Practices
- * 
- * 1. **Use appropriate types**: Match toast type to message severity
- * 2. **Keep messages concise**: Short, clear messages are more effective
- * 3. **Don't overuse**: Too many toasts can be overwhelming
- * 4. **Provide context**: Include enough information for users to understand the message
- * 5. **Handle errors gracefully**: Use error toasts for user-facing errors, not technical details
- * 
- * ## Common Pitfalls
- * 
- * - Using toasts for critical information (use modals for important confirmations)
- * - Too many toasts at once (can overwhelm users)
- * - Vague messages (be specific about what happened)
- * - Missing ToastProvider wrapper (toasts won't work without it)
- * - Using wrong toast type (confuses users about message severity)
- * 
- * @component
- * @example
- * ```tsx
- * const { addToast } = useToast()
- * 
- * addToast({
- *   message: 'Settings saved',
- *   type: 'success'
- * })
- * ```
- */
-const meta: Meta<typeof ToastProvider> = {
-  title: 'Components/Toast',
-  component: ToastProvider,
-  tags: ['autodocs'],
-}
-
-export default meta
-type Story = StoryObj<typeof ToastProvider>
-
-const ToastDemo = () => {
-  const { addToast } = useToast()
-
-  return (
-    <div style={{ display: 'flex', gap: '1rem', flexWrap: 'wrap' }}>
-      <Button onClick={() => addToast({ message: 'Info message', type: 'info' })}>
-        Show Info
-      </Button>
-      <Button onClick={() => addToast({ message: 'Success!', type: 'success' })}>
-        Show Success
-      </Button>
-      <Button onClick={() => addToast({ message: 'Warning message', type: 'warning' })}>
-        Show Warning
-      </Button>
-      <Button onClick={() => addToast({ message: 'Error occurred', type: 'error' })}>
-        Show Error
-      </Button>
-    </div>
-  )
-}
-
-/**
- * Toast notification system with all four types: info, success, warning, and error.
- * Each toast type has distinct styling and appropriate ARIA live region politeness.
- */
-export const Default: Story = {
-  render: () => (
-    <ToastProvider>
-      <ToastDemo />
-    </ToastProvider>
-  ),
-}
-

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

@@ -1,175 +0,0 @@
-'use client'
-
-import React, { useEffect, useState } from 'react'
-import { useAriaLive } from '../../hooks/useAriaLive'
-import { isEscapeKey } from '../../utils/keyboard'
-import { Button } from '../Button/Button'
-import './Toast.css'
-
-export interface ToastProps {
-  /**
-   * Unique ID for the toast
-   */
-  id: string
-  
-  /**
-   * Toast message
-   */
-  message: string
-  
-  /**
-   * Toast type
-   */
-  type?: 'info' | 'success' | 'warning' | 'error'
-  
-  /**
-   * Whether toast can be dismissed
-   */
-  dismissible?: boolean
-  
-  /**
-   * Auto-dismiss duration in milliseconds (0 = no auto-dismiss). For WCAG compliance, this should be 6 seconds.
-   */
-  duration?: number
-  
-  /**
-   * Callback when toast is dismissed
-   */
-  onDismiss: (id: string) => void
-  
-  /**
-   * Pause auto-dismiss on hover
-   */
-  pauseOnHover?: boolean
-}
-
-/**
- * Accessible Toast component
- * 
- * WCAG Compliance:
- * - 4.1.3 Status Messages: ARIA live region announcements
- * - 2.1.1 Keyboard: ESC key support, Tab navigation support
- * - 2.4.3 Focus Order: Consistent focus order - toasts always appear in same position
- * - 4.1.2 Name, Role, Value: Proper ARIA attributes
- * 
- * Focus Order:
- * - Toasts are focusable with tabIndex={0} (not positive tabindex)
- * - Toast container is always rendered in the same DOM position (via portal to body)
- * - Toasts appear in consistent order (order added) for predictable tab navigation
- * - Container itself is not focusable, only individual toasts are focusable
- * 
- * @example
- * ```tsx
- * <Toast
- *   id="toast-1"
- *   message="Successfully saved!"
- *   type="success"
- *   onDismiss={handleDismiss}
- * />
- * ```
- */
-export const Toast: React.FC<ToastProps> = ({
-  id,
-  message,
-  type = 'info',
-  dismissible = true,
-  duration = 6000,
-  onDismiss,
-  pauseOnHover = true,
-}) => {
-  const [isPaused, setIsPaused] = useState(false)
-  const timeoutRef = React.useRef<NodeJS.Timeout | null>(null)
-
-  // Announce toast via ARIA live region
-  useAriaLive(message, type === 'error' ? 'assertive' : 'polite')
-
-  // Auto-dismiss
-  useEffect(() => {
-    if (duration === 0 || isPaused) {
-      if (timeoutRef.current) {
-        clearTimeout(timeoutRef.current)
-        timeoutRef.current = null
-      }
-      return
-    }
-
-    timeoutRef.current = setTimeout(() => {
-      onDismiss(id)
-    }, duration)
-
-    return () => {
-      if (timeoutRef.current) {
-        clearTimeout(timeoutRef.current)
-      }
-    }
-  }, [duration, id, onDismiss, isPaused])
-
-  // Handle ESC key
-  useEffect(() => {
-    if (!dismissible) return
-
-    const handleKeyDown = (event: KeyboardEvent) => {
-      if (isEscapeKey(event.key)) {
-        onDismiss(id)
-      }
-    }
-
-    document.addEventListener('keydown', handleKeyDown)
-    return () => {
-      document.removeEventListener('keydown', handleKeyDown)
-    }
-  }, [dismissible, id, onDismiss])
-
-  const handleMouseEnter = () => {
-    if (pauseOnHover) {
-      setIsPaused(true)
-    }
-  }
-
-  const handleMouseLeave = () => {
-    if (pauseOnHover) {
-      setIsPaused(false)
-    }
-  }
-
-  const handleDismiss = () => {
-    onDismiss(id)
-  }
-
-  const classes = [
-    'toast',
-    `toast--${type}`,
-  ]
-    .filter(Boolean)
-    .join(' ')
-
-  return (
-    <div
-      className={classes}
-      role="alert"
-      aria-live={type === 'error' ? 'assertive' : 'polite'}
-      aria-atomic="true"
-      tabIndex={0}
-      onMouseEnter={handleMouseEnter}
-      onMouseLeave={handleMouseLeave}
-    >
-      <div className="toast-content">
-        <span className="toast-message">{message}</span>
-      </div>
-      {dismissible && (
-        <Button
-          variant="ghost"
-          size="sm"
-          onClick={handleDismiss}
-          aria-label="Dismiss notification"
-          className="toast-dismiss"
-        >
-          ×
-        </Button>
-      )}
-    </div>
-  )
-}
-
-Toast.displayName = 'Toast'
-

package/packages/design-system/src/components/Toast/ToastProvider.tsx

@@ -1,73 +0,0 @@
-'use client'
-
-import React, { createContext, useContext, useState, useCallback } from 'react'
-import { createPortal } from 'react-dom'
-import { Toast, ToastProps } from './Toast'
-import './ToastProvider.css'
-
-export interface ToastItem extends Omit<ToastProps, 'onDismiss'> {
-  id: string
-}
-
-interface ToastContextValue {
-  addToast: (toast: Omit<ToastItem, 'id'>) => void
-  removeToast: (id: string) => void
-}
-
-const ToastContext = createContext<ToastContextValue | undefined>(undefined)
-
-export const useToast = () => {
-  const context = useContext(ToastContext)
-  if (!context) {
-    throw new Error('useToast must be used within ToastProvider')
-  }
-  return context
-}
-
-export interface ToastProviderProps {
-  children: React.ReactNode
-  position?: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' | 'top-center' | 'bottom-center'
-}
-
-/**
- * Toast Provider component
- * Manages toast stack and positioning
- */
-export const ToastProvider: React.FC<ToastProviderProps> = ({
-  children,
-  position = 'top-right',
-}) => {
-  const [toasts, setToasts] = useState<ToastItem[]>([])
-
-  const addToast = useCallback((toast: Omit<ToastItem, 'id'>) => {
-    const id = `toast-${Date.now()}-${Math.random()}`
-    setToasts((prev) => [...prev, { ...toast, id }])
-  }, [])
-
-  const removeToast = useCallback((id: string) => {
-    setToasts((prev) => prev.filter((toast) => toast.id !== id))
-  }, [])
-
-  // Always render container to maintain consistent DOM position for focus order
-  // Toasts appear in order they were added (newest last), maintaining consistent tab order
-  const toastContainer = (
-    <div 
-      className={`toast-container toast-container--${position}`} 
-      role="region" 
-      aria-label="Notifications"
-    >
-      {toasts.map((toast) => (
-        <Toast key={toast.id} {...toast} onDismiss={removeToast} />
-      ))}
-    </div>
-  )
-
-  return (
-    <ToastContext.Provider value={{ addToast, removeToast }}>
-      {children}
-      {typeof document !== 'undefined' &&
-        createPortal(toastContainer, document.body)}
-    </ToastContext.Provider>
-  )
-}
-

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

@@ -1,5 +0,0 @@
-export { Toast } from './Toast'
-export { ToastProvider, useToast } from './ToastProvider'
-export type { ToastProps } from './Toast'
-export type { ToastItem, ToastProviderProps } from './ToastProvider'
-

package/packages/design-system/src/hooks/useAriaLive.ts

@@ -1,51 +0,0 @@
-'use client'
-
-import { useEffect, useRef } from 'react'
-
-/**
- * Hook to manage ARIA live regions for screen reader announcements
- * 
- * @param message - Message to announce
- * @param priority - 'polite' (default) or 'assertive'
- * @param clearOnUnmount - Whether to clear the message on unmount
- */
-export function useAriaLive(
-  message: string | undefined,
-  priority: 'polite' | 'assertive' = 'polite',
-  clearOnUnmount: boolean = true
-): void {
-  const liveRegionRef = useRef<HTMLDivElement | null>(null)
-
-  useEffect(() => {
-    // Create or get the live region element
-    let liveRegion = document.getElementById(`aria-live-${priority}`) as HTMLDivElement
-
-    if (!liveRegion) {
-      liveRegion = document.createElement('div')
-      liveRegion.id = `aria-live-${priority}`
-      liveRegion.setAttribute('role', 'status')
-      liveRegion.setAttribute('aria-live', priority)
-      liveRegion.setAttribute('aria-atomic', 'true')
-      liveRegion.style.position = 'absolute'
-      liveRegion.style.left = '-10000px'
-      liveRegion.style.width = '1px'
-      liveRegion.style.height = '1px'
-      liveRegion.style.overflow = 'hidden'
-      document.body.appendChild(liveRegion)
-    }
-
-    liveRegionRef.current = liveRegion
-
-    // Update the message
-    if (message) {
-      liveRegion.textContent = message
-    }
-
-    return () => {
-      if (clearOnUnmount && liveRegionRef.current) {
-        liveRegionRef.current.textContent = ''
-      }
-    }
-  }, [message, priority, clearOnUnmount])
-}
-