@a11ypros/a11y-ui-components 1.0.1 → 1.0.2

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

@@ -1,40 +0,0 @@
-'use client'
-
-import { useEffect, useRef } from 'react'
-
-/**
- * Hook to return focus to a previously focused element when component unmounts
- * Useful for modals, dropdowns, and other temporary UI elements
- * 
- * @param returnOnUnmount - Whether to return focus on unmount
- * @param returnElement - Optional specific element to return focus to
- */
-export function useFocusReturn(
-  returnOnUnmount: boolean = true,
-  returnElement?: HTMLElement | null
-): void {
-  const savedElementRef = useRef<HTMLElement | null>(null)
-
-  useEffect(() => {
-    if (!returnOnUnmount) return
-
-    // Save the currently focused element
-    if (document.activeElement instanceof HTMLElement) {
-      savedElementRef.current = document.activeElement
-    }
-
-    return () => {
-      // Restore focus on unmount
-      const elementToFocus = returnElement || savedElementRef.current
-      if (elementToFocus && typeof elementToFocus.focus === 'function') {
-        try {
-          elementToFocus.focus()
-        } catch (error) {
-          // Silently fail if focus fails
-          console.warn('Failed to return focus:', error)
-        }
-      }
-    }
-  }, [returnOnUnmount, returnElement])
-}
-

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

@@ -1,82 +0,0 @@
-'use client'
-
-import { useEffect, useRef } from 'react'
-import { getFirstFocusable, getLastFocusable } from '../utils/focus'
-
-/**
- * Hook to trap focus within a container element
- * Implements WCAG 2.1.2 Keyboard (No Keyboard Trap)
- * 
- * @param enabled - Whether the focus trap is active
- * @param containerRef - Ref to the container element
- */
-export function useFocusTrap(
-  enabled: boolean,
-  containerRef: React.RefObject<HTMLElement>
-): void {
-  const previousActiveElement = useRef<HTMLElement | null>(null)
-
-  useEffect(() => {
-    if (!enabled || !containerRef.current) return
-
-    const container = containerRef.current
-
-    // Save the previously focused element
-    if (document.activeElement instanceof HTMLElement) {
-      previousActiveElement.current = document.activeElement
-    }
-
-    // Focus the first focusable element in the container
-    const firstFocusable = getFirstFocusable(container)
-    if (firstFocusable) {
-      firstFocusable.focus()
-    } else {
-      // If no focusable elements, focus the container itself
-      container.focus()
-    }
-
-    // Handle Tab key to trap focus
-    const handleKeyDown = (event: KeyboardEvent) => {
-      if (event.key !== 'Tab') return
-
-      const focusableElements = [
-        getFirstFocusable(container),
-        getLastFocusable(container),
-      ].filter(Boolean) as HTMLElement[]
-
-      if (focusableElements.length === 0) {
-        event.preventDefault()
-        return
-      }
-
-      const firstElement = focusableElements[0]
-      const lastElement = focusableElements[focusableElements.length - 1]
-
-      if (event.shiftKey) {
-        // Shift + Tab
-        if (document.activeElement === firstElement) {
-          event.preventDefault()
-          lastElement.focus()
-        }
-      } else {
-        // Tab
-        if (document.activeElement === lastElement) {
-          event.preventDefault()
-          firstElement.focus()
-        }
-      }
-    }
-
-    container.addEventListener('keydown', handleKeyDown)
-
-    return () => {
-      container.removeEventListener('keydown', handleKeyDown)
-      
-      // Restore focus to the previously focused element
-      if (previousActiveElement.current) {
-        previousActiveElement.current.focus()
-      }
-    }
-  }, [enabled, containerRef])
-}
-

package/packages/design-system/src/styles/index.ts

@@ -1,3 +0,0 @@
-export { theme } from '../tokens/theme'
-export type { Theme } from '../tokens/theme'
-

package/packages/design-system/src/tokens/breakpoints.ts

@@ -1,28 +0,0 @@
-/**
- * Responsive breakpoints
- * Mobile-first approach
- */
-
-export const breakpoints = {
-  sm: '640px',   // Small devices (landscape phones)
-  md: '768px',   // Medium devices (tablets)
-  lg: '1024px',  // Large devices (desktops)
-  xl: '1280px',  // Extra large devices
-  '2xl': '1536px', // 2X Extra large devices
-} as const
-
-export type BreakpointToken = typeof breakpoints
-
-/**
- * Media query helpers
- */
-export const mediaQuery = {
-  sm: `@media (min-width: ${breakpoints.sm})`,
-  md: `@media (min-width: ${breakpoints.md})`,
-  lg: `@media (min-width: ${breakpoints.lg})`,
-  xl: `@media (min-width: ${breakpoints.xl})`,
-  '2xl': `@media (min-width: ${breakpoints['2xl']})`,
-  reducedMotion: '@media (prefers-reduced-motion: reduce)',
-  highContrast: '@media (prefers-contrast: high)',
-} as const
-

package/packages/design-system/src/tokens/colors.ts

@@ -1,98 +0,0 @@
-/**
- * Color tokens with WCAG AA contrast ratios (4.5:1 for normal text, 3:1 for large text)
- * All colors meet WCAG 2.1 Level AA standards
- */
-
-export const colors = {
-  // Primary palette
-  primary: {
-    50: '#f0f9ff',
-    100: '#e0f2fe',
-    200: '#bae6fd',
-    300: '#7dd3fc',
-    400: '#38bdf8',
-    500: '#0ea5e9', // Main primary - meets 4.5:1 on white
-    600: '#0284c7',
-    700: '#0369a1',
-    800: '#075985',
-    900: '#0c4a6e',
-  },
-  
-  // Neutral grays
-  neutral: {
-    50: '#fafafa',
-    100: '#f5f5f5',
-    200: '#bbbbbb',
-    300: '#d4d4d4',
-    400: '#a3a3a3',
-    500: '#737373',
-    600: '#525252', // Meets 4.5:1 on white
-    700: '#404040', // Meets 4.5:1 on white
-    800: '#262626', // Meets 4.5:1 on white
-    900: '#171717', // Meets 4.5:1 on white
-  },
-  
-  // Semantic colors
-  success: {
-    50: '#f0fdf4',
-    100: '#dcfce7',
-    200: '#bbf7d0',
-    300: '#86efac',
-    400: '#4ade80',
-    500: '#22c55e', // Meets 4.5:1 on white
-    600: '#16a34a',
-    700: '#15803d',
-  },
-  
-  warning: {
-    50: '#fffbeb',
-    100: '#fef3c7',
-    200: '#fde68a',
-    300: '#fcd34d',
-    400: '#fbbf24',
-    500: '#f59e0b', // Meets 4.5:1 on white
-    600: '#d97706',
-    700: '#b45309',
-  },
-  
-  error: {
-    50: '#fef2f2',
-    100: '#fee2e2',
-    200: '#fecaca',
-    300: '#fca5a5',
-    400: '#f87171',
-    500: '#ef4444', // Meets 4.5:1 on white
-    600: '#dc2626', // Meets 4.5:1 on white
-    700: '#b91c1c',
-  },
-  
-  // Base colors
-  white: '#ffffff',
-  black: '#000000',
-  
-  // Background colors
-  background: {
-    default: '#ffffff',
-    secondary: '#fafafa',
-    tertiary: '#f5f5f5',
-  },
-  
-  // Text colors (meet contrast requirements)
-  text: {
-    primary: '#171717', // neutral.900 - 4.5:1 on white
-    secondary: '#525252', // neutral.600 - 4.5:1 on white
-    tertiary: '#737373', // neutral.500 - 4.5:1 on white (large text)
-    inverse: '#ffffff', // white - 4.5:1 on dark backgrounds
-    disabled: '#a3a3a3', // neutral.400
-  },
-  
-  // Border colors
-  border: {
-    default: '#bbbbbb', // neutral.200
-    focus: '#0ea5e9', // primary.500
-    error: '#ef4444', // error.500
-  },
-} as const
-
-export type ColorToken = typeof colors
-

package/packages/design-system/src/tokens/index.ts

@@ -1,6 +0,0 @@
-export * from './colors'
-export * from './spacing'
-export * from './typography'
-export * from './motion'
-export * from './breakpoints'
-

package/packages/design-system/src/tokens/motion.ts

@@ -1,41 +0,0 @@
-/**
- * Motion tokens that respect prefers-reduced-motion
- * All animations should check for reduced motion preference
- */
-
-export const motion = {
-  duration: {
-    fast: '150ms',
-    normal: '200ms',
-    slow: '300ms',
-    slower: '400ms',
-  },
-  
-  easing: {
-    easeIn: 'cubic-bezier(0.4, 0, 1, 1)',
-    easeOut: 'cubic-bezier(0, 0, 0.2, 1)',
-    easeInOut: 'cubic-bezier(0.4, 0, 0.2, 1)',
-    linear: 'linear',
-  },
-  
-  // Reduced motion overrides (set to 0 or instant)
-  reduced: {
-    duration: '0ms',
-    easing: 'linear',
-  },
-} as const
-
-export type MotionToken = typeof motion
-
-/**
- * Helper to get motion duration respecting prefers-reduced-motion
- * Usage: const duration = getMotionDuration('normal')
- * In CSS: use @media (prefers-reduced-motion: reduce) { animation-duration: 0ms; }
- */
-export function getMotionDuration(key: keyof typeof motion.duration): string {
-  if (typeof window !== 'undefined' && window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
-    return motion.reduced.duration
-  }
-  return motion.duration[key]
-}
-

package/packages/design-system/src/tokens/spacing.ts

@@ -1,24 +0,0 @@
-/**
- * Spacing scale using 4px base unit
- * Follows consistent 8px grid system
- */
-
-export const spacing = {
-  0: '0',
-  1: '0.25rem', // 4px
-  2: '0.5rem',  // 8px
-  3: '0.75rem', // 12px
-  4: '1rem',    // 16px
-  5: '1.25rem', // 20px
-  6: '1.5rem',  // 24px
-  8: '2rem',    // 32px
-  10: '2.5rem', // 40px
-  12: '3rem',   // 48px
-  16: '4rem',   // 64px
-  20: '5rem',   // 80px
-  24: '6rem',   // 96px
-  32: '8rem',   // 128px
-} as const
-
-export type SpacingToken = typeof spacing
-

package/packages/design-system/src/tokens/theme.ts

@@ -1,19 +0,0 @@
-/**
- * Central theme export combining all design tokens
- */
-import { colors } from './colors'
-import { spacing } from './spacing'
-import { typography } from './typography'
-import { motion } from './motion'
-import { breakpoints } from './breakpoints'
-
-export const theme = {
-  colors,
-  spacing,
-  typography,
-  motion,
-  breakpoints,
-} as const
-
-export type Theme = typeof theme
-

package/packages/design-system/src/tokens/typography.ts

@@ -1,64 +0,0 @@
-/**
- * Typography scale with accessible line heights and font sizes
- * Line heights ensure readability (minimum 1.5 for body text)
- */
-
-export const typography = {
-  fontFamily: {
-    sans: [
-      '-apple-system',
-      'BlinkMacSystemFont',
-      '"Segoe UI"',
-      'Roboto',
-      '"Helvetica Neue"',
-      'Arial',
-      'sans-serif',
-    ].join(', '),
-    mono: [
-      'Menlo',
-      'Monaco',
-      '"Courier New"',
-      'monospace',
-    ].join(', '),
-  },
-  
-  fontSize: {
-    xs: '0.75rem',   // 12px
-    sm: '0.875rem',  // 14px
-    base: '1rem',    // 16px
-    lg: '1.125rem',  // 18px
-    xl: '1.25rem',   // 20px
-    '2xl': '1.5rem', // 24px
-    '3xl': '1.875rem', // 30px
-    '4xl': '2.25rem',  // 36px
-    '5xl': '3rem',     // 48px
-  },
-  
-  lineHeight: {
-    none: '1',
-    tight: '1.25',
-    snug: '1.375',
-    normal: '1.5',   // Minimum for accessibility
-    relaxed: '1.625',
-    loose: '2',
-  },
-  
-  fontWeight: {
-    normal: '400',
-    medium: '500',
-    semibold: '600',
-    bold: '700',
-  },
-  
-  letterSpacing: {
-    tighter: '-0.05em',
-    tight: '-0.025em',
-    normal: '0',
-    wide: '0.025em',
-    wider: '0.05em',
-    widest: '0.1em',
-  },
-} as const
-
-export type TypographyToken = typeof typography
-

package/packages/design-system/src/utils/aria.ts

@@ -1,108 +0,0 @@
-/**
- * ARIA utility functions
- * Helpers for managing ARIA attributes and roles
- */
-
-/**
- * Generate a unique ID for ARIA attributes
- */
-let idCounter = 0
-export function generateId(prefix = 'id'): string {
-  return `${prefix}-${++idCounter}`
-}
-
-/**
- * Get ARIA label from props, preferring aria-label over aria-labelledby
- */
-export function getAriaLabel(
-  ariaLabel?: string,
-  ariaLabelledBy?: string
-): { 'aria-label'?: string; 'aria-labelledby'?: string } {
-  if (ariaLabel) {
-    return { 'aria-label': ariaLabel }
-  }
-  if (ariaLabelledBy) {
-    return { 'aria-labelledby': ariaLabelledBy }
-  }
-  return {}
-}
-
-/**
- * Get ARIA describedby attributes
- */
-export function getAriaDescribedBy(
-  describedBy?: string
-): { 'aria-describedby'?: string } {
-  if (describedBy) {
-    return { 'aria-describedby': describedBy }
-  }
-  return {}
-}
-
-/**
- * Combine multiple ARIA describedby IDs
- */
-export function combineAriaDescribedBy(...ids: (string | undefined)[]): string | undefined {
-  const validIds = ids.filter((id): id is string => Boolean(id))
-  return validIds.length > 0 ? validIds.join(' ') : undefined
-}
-
-/**
- * Get live region attributes
- */
-export function getLiveRegionAttributes(
-  live: 'polite' | 'assertive' | 'off' = 'polite'
-): { 'aria-live': 'polite' | 'assertive' | 'off'; 'aria-atomic'?: boolean } {
-  return {
-    'aria-live': live,
-    'aria-atomic': live !== 'off',
-  }
-}
-
-/**
- * Get busy state attributes
- */
-export function getBusyAttributes(busy: boolean): { 'aria-busy': boolean } {
-  return { 'aria-busy': busy }
-}
-
-/**
- * Get expanded state attributes
- */
-export function getExpandedAttributes(
-  expanded: boolean | undefined
-): { 'aria-expanded'?: boolean } {
-  if (expanded === undefined) return {}
-  return { 'aria-expanded': expanded }
-}
-
-/**
- * Get pressed state attributes (for toggle buttons)
- */
-export function getPressedAttributes(
-  pressed: boolean | undefined
-): { 'aria-pressed'?: boolean } {
-  if (pressed === undefined) return {}
-  return { 'aria-pressed': pressed }
-}
-
-/**
- * Get selected state attributes
- */
-export function getSelectedAttributes(
-  selected: boolean | undefined
-): { 'aria-selected'?: boolean } {
-  if (selected === undefined) return {}
-  return { 'aria-selected': selected }
-}
-
-/**
- * Get current state attributes (for navigation)
- */
-export function getCurrentAttributes(
-  current: boolean | 'page' | 'step' | 'location' | 'date' | 'time' | undefined
-): { 'aria-current'?: boolean | 'page' | 'step' | 'location' | 'date' | 'time' } {
-  if (current === undefined) return {}
-  return { 'aria-current': current }
-}
-

package/packages/design-system/src/utils/focus.ts

@@ -1,87 +0,0 @@
-/**
- * Focus management utilities
- * Helpers for programmatic focus control
- */
-
-/**
- * Get all focusable elements within a container
- */
-export function getFocusableElements(
-  container: HTMLElement
-): HTMLElement[] {
-  const focusableSelectors = [
-    'a[href]',
-    'button:not([disabled])',
-    'textarea:not([disabled])',
-    'input:not([disabled])',
-    'select:not([disabled])',
-    '[tabindex]:not([tabindex="-1"])',
-  ].join(', ')
-
-  return Array.from(container.querySelectorAll<HTMLElement>(focusableSelectors))
-}
-
-/**
- * Get the first focusable element in a container
- */
-export function getFirstFocusable(container: HTMLElement): HTMLElement | null {
-  const focusable = getFocusableElements(container)
-  return focusable[0] || null
-}
-
-/**
- * Get the last focusable element in a container
- */
-export function getLastFocusable(container: HTMLElement): HTMLElement | null {
-  const focusable = getFocusableElements(container)
-  return focusable[focusable.length - 1] || null
-}
-
-/**
- * Check if an element is focusable
- */
-export function isFocusable(element: HTMLElement): boolean {
-  if (element.tabIndex < 0) return false
-  if (element.hasAttribute('disabled')) return false
-  if (element.hasAttribute('hidden')) return false
-  if (element.style.display === 'none') return false
-  if (element.style.visibility === 'hidden') return false
-  
-  return true
-}
-
-/**
- * Save the currently focused element
- */
-let savedFocusElement: HTMLElement | null = null
-
-export function saveFocus(): void {
-  if (document.activeElement instanceof HTMLElement) {
-    savedFocusElement = document.activeElement
-  }
-}
-
-/**
- * Restore focus to the previously saved element
- */
-export function restoreFocus(): void {
-  if (savedFocusElement) {
-    savedFocusElement.focus()
-    savedFocusElement = null
-  }
-}
-
-/**
- * Focus an element safely (with error handling)
- */
-export function safeFocus(element: HTMLElement | null): void {
-  if (element && typeof element.focus === 'function') {
-    try {
-      element.focus()
-    } catch (error) {
-      // Silently fail if focus fails
-      console.warn('Failed to focus element:', error)
-    }
-  }
-}
-

package/packages/design-system/src/utils/index.ts

@@ -1,4 +0,0 @@
-export * from './aria'
-export * from './keyboard'
-export * from './focus'
-

package/packages/design-system/src/utils/keyboard.ts

@@ -1,77 +0,0 @@
-/**
- * Keyboard event utilities
- * Helpers for handling keyboard interactions
- */
-
-export type KeyboardHandler = (event: React.KeyboardEvent) => void
-
-/**
- * Check if a key is an activation key (Enter or Space)
- */
-export function isActivationKey(key: string): boolean {
-  return key === 'Enter' || key === ' '
-}
-
-/**
- * Check if a key is an arrow key
- */
-export function isArrowKey(key: string): boolean {
-  return ['ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight'].includes(key)
-}
-
-/**
- * Check if a key is a navigation key (Home, End, PageUp, PageDown)
- */
-export function isNavigationKey(key: string): boolean {
-  return ['Home', 'End', 'PageUp', 'PageDown'].includes(key)
-}
-
-/**
- * Check if a key is an escape key
- */
-export function isEscapeKey(key: string): boolean {
-  return key === 'Escape'
-}
-
-/**
- * Check if modifier keys are pressed
- */
-export function hasModifierKey(event: React.KeyboardEvent): boolean {
-  return event.ctrlKey || event.metaKey || event.altKey || event.shiftKey
-}
-
-/**
- * Create a keyboard handler that only fires on specific keys
- */
-export function createKeyHandler(
-  keys: string[],
-  handler: KeyboardHandler
-): KeyboardHandler {
-  return (event: React.KeyboardEvent) => {
-    if (keys.includes(event.key)) {
-      handler(event)
-    }
-  }
-}
-
-/**
- * Create a keyboard handler for activation keys (Enter/Space)
- */
-export function createActivationHandler(
-  handler: KeyboardHandler
-): KeyboardHandler {
-  return createKeyHandler(['Enter', ' '], (event) => {
-    event.preventDefault()
-    handler(event)
-  })
-}
-
-/**
- * Create a keyboard handler for arrow keys
- */
-export function createArrowKeyHandler(
-  handler: KeyboardHandler
-): KeyboardHandler {
-  return createKeyHandler(['ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight'], handler)
-}
-