@a11ypros/a11y-ui-components 1.0.1 → 1.0.3

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

@@ -1,117 +0,0 @@
-'use client'
-
-import React from 'react'
-import './Link.css'
-
-export interface LinkProps extends React.AnchorHTMLAttributes<HTMLAnchorElement> {
-  /**
-   * Whether this is an external link
-   * Automatically adds rel="noopener noreferrer" for security
-   */
-  external?: boolean
-  
-  /**
-   * Whether this is a skip link (for keyboard navigation)
-   */
-  skip?: boolean
-  
-  /**
-   * ARIA label for the link (required if no visible text)
-   */
-  'aria-label'?: string
-}
-
-/**
- * Accessible Link component
- * 
- * WCAG Compliance:
- * - 2.4.4 Link Purpose: Clear link text or aria-label
- * - 2.4.7 Focus Visible: Clear focus indicators
- * - 4.1.2 Name, Role, Value: Proper semantic HTML
- * 
- * @example
- * ```tsx
- * <Link href="/about" external>
- *   Learn more
- * </Link>
- * ```
- */
-export const Link = React.forwardRef<HTMLAnchorElement, LinkProps>(
-  (
-    {
-      external = false,
-      skip = false,
-      href,
-      rel,
-      target,
-      className = '',
-      children,
-      'aria-label': ariaLabel,
-      ...props
-    },
-    ref
-  ) => {
-    // Determine if link is external based on href or explicit prop
-    const isExternal =
-      external ||
-      (href && (href.startsWith('http') || href.startsWith('//')))
-
-    // Build rel attribute
-    const relAttributes = React.useMemo(() => {
-      const attrs = new Set(rel?.split(' ') || [])
-      if (isExternal) {
-        attrs.add('noopener')
-        attrs.add('noreferrer')
-      }
-      return Array.from(attrs).join(' ')
-    }, [isExternal, rel])
-
-    // Set target for external links
-    const linkTarget = isExternal && !target ? '_blank' : target
-
-    const classes = [
-      'link',
-      skip && 'link--skip',
-      className,
-    ]
-      .filter(Boolean)
-      .join(' ')
-
-    // Skip links should use button semantics if no href
-    if (skip && !href) {
-      return (
-        <button
-          ref={ref as any}
-          className={classes}
-          aria-label={ariaLabel}
-          {...(props as any)}
-        >
-          {children}
-        </button>
-      )
-    }
-
-    return (
-      <a
-        ref={ref}
-        href={href}
-        rel={relAttributes || undefined}
-        target={linkTarget}
-        className={classes}
-        aria-label={ariaLabel}
-        {...props}
-      >
-        {children}
-        {isExternal && (
-          <span className="link__external-icon" aria-hidden="true">
-            {' '}
-            <span aria-label="(opens in new tab)">↗</span>
-          </span>
-        )}
-      </a>
-    )
-  }
-)
-
-Link.displayName = 'Link'
-

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

@@ -1,3 +0,0 @@
-export { Link } from './Link'
-export type { LinkProps } from './Link'
-

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

@@ -1,165 +0,0 @@
-import type { Meta, StoryObj } from '@storybook/react'
-import { useState } from 'react'
-import { Modal } from './Modal'
-import { Button } from '../Button/Button'
-
-/**
- * # Modal Component
- * 
- * An accessible modal dialog component with focus trapping, keyboard support,
- * and proper ARIA attributes following the WAI-ARIA modal pattern.
- * 
- * ## Usage
- * 
- * ```tsx
- * import { Modal } from '@a11ypros/a11y-ui-components'
- * import { useState } from 'react'
- * 
- * function MyComponent() {
- *   const [isOpen, setIsOpen] = useState(false)
- *   
- *   return (
- *     <>
- *       <Button onClick={() => setIsOpen(true)}>Open Modal</Button>
- *       <Modal
- *         isOpen={isOpen}
- *         onClose={() => setIsOpen(false)}
- *         title="Modal Title"
- *       >
- *         <p>Modal content goes here</p>
- *       </Modal>
- *     </>
- *   )
- * }
- * ```
- * 
- * ## Features
- * 
- * - **Focus trapping**: Focus is trapped within the modal when open
- * - **Focus return**: Focus returns to the trigger element when modal closes
- * - **Keyboard support**: ESC key closes the modal
- * - **Backdrop click**: Optional backdrop click to close
- * - **Portal rendering**: Rendered in a portal to avoid z-index issues
- * - **Multiple sizes**: sm, md, lg, and full screen options
- * 
- * ## Accessibility
- * 
- * ### WCAG 2.1/2.2 Compliance
- * 
- * - **2.1.1 Keyboard**: ESC key support, full keyboard navigation
- * - **2.1.2 No Keyboard Trap**: Focus returns to trigger element when modal closes
- * - **2.4.3 Focus Order**: Focus trapped within modal, proper tab order
- * - **2.4.7 Focus Visible**: Clear focus indicators on all interactive elements
- * - **4.1.2 Name, Role, Value**: Proper ARIA modal pattern with role="dialog"
- * - **4.1.3 Status Messages**: Modal title announced when opened
- * 
- * ### Keyboard Interactions
- * 
- * | Key | Action |
- * |-----|--------|
- * | **ESC** | Closes the modal |
- * | **Tab** | Moves focus to next focusable element (trapped within modal) |
- * | **Shift+Tab** | Moves focus to previous focusable element (wraps at boundaries) |
- * | **Enter/Space** | Activates buttons or links within modal |
- * 
- * ### Screen Reader Support
- * 
- * - Modal role and title are announced when opened
- * - Focus moves to modal content automatically
- * - Backdrop is hidden from screen readers (\`aria-hidden="true"\`)
- * - Close button has accessible label
- * - Focus returns to trigger element when closed
- * 
- * ### Focus Management
- * 
- * - Focus is trapped within modal when open (cannot tab to background content)
- * - Focus moves to first focusable element when modal opens
- * - Focus returns to trigger element when modal closes
- * - Backdrop receives focus trap but is not focusable itself
- * 
- * ## Best Practices
- * 
- * 1. **Always provide a title**: Required for accessibility and user understanding
- * 2. **Provide a close mechanism**: Close button, ESC key, or backdrop click
- * 3. **Return focus appropriately**: Focus should return to the element that opened the modal
- * 4. **Keep content focused**: Don't put too much content in modals - use pages for complex flows
- * 5. **Handle mobile**: Ensure modal is usable on mobile devices with proper sizing
- * 
- * ## Common Pitfalls
- * 
- * - Missing title prop (required for accessibility)
- * - Not returning focus to trigger element (breaks keyboard navigation flow)
- * - Allowing focus to escape modal (should be trapped)
- * - Using modals for non-modal content (use regular pages or sections)
- * - Too much content in modal (makes it hard to navigate)
- * - Missing close button or ESC key support
- * 
- * @component
- * @example
- * ```tsx
- * <Modal
- *   isOpen={isOpen}
- *   onClose={() => setIsOpen(false)}
- *   title="Confirm Action"
- * >
- *   <p>Are you sure you want to proceed?</p>
- * </Modal>
- * ```
- */
-const meta: Meta<typeof Modal> = {
-  title: 'Components/Modal',
-  component: Modal,
-  tags: ['autodocs'],
-}
-
-export default meta
-type Story = StoryObj<typeof Modal>
-
-const ModalExample = (args: any) => {
-  const [isOpen, setIsOpen] = useState(false)
-  return (
-    <>
-      <Button onClick={() => setIsOpen(true)}>Open Modal</Button>
-      <Modal {...args} isOpen={isOpen} onClose={() => setIsOpen(false)} />
-    </>
-  )
-}
-
-/**
- * Default modal with standard size. Focus is trapped within the modal
- * and returns to the trigger button when closed.
- */
-export const Default: Story = {
-  render: ModalExample,
-  args: {
-    title: 'Modal Title',
-    children: <p>This is the modal content. Press ESC to close.</p>,
-  },
-}
-
-/**
- * Small modal for simple confirmations or brief messages.
- * Use when you need a compact dialog that doesn't take up much screen space.
- */
-export const Small: Story = {
-  render: ModalExample,
-  args: {
-    title: 'Small Modal',
-    size: 'sm',
-    children: <p>This is a small modal.</p>,
-  },
-}
-
-/**
- * Large modal for more complex content that needs more space.
- * Use when displaying forms, detailed information, or multiple sections.
- */
-export const Large: Story = {
-  render: ModalExample,
-  args: {
-    title: 'Large Modal',
-    size: 'lg',
-    children: <p>This is a large modal with more content.</p>,
-  },
-}
-

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

@@ -1,202 +0,0 @@
-'use client'
-
-import React, { useEffect, useRef } from 'react'
-import { useFocusReturn } from '../../hooks/useFocusReturn'
-import { Button } from '../Button/Button'
-import './Modal.css'
-
-export interface ModalProps {
-  /**
-   * Whether the modal is open
-   */
-  isOpen: boolean
-  
-  /**
-   * Callback when modal should close
-   */
-  onClose: () => void
-  
-  /**
-   * Title of the modal (required for accessibility)
-   */
-  title: string
-  
-  /**
-   * Content of the modal
-   */
-  children: React.ReactNode
-  
-  /**
-   * Whether to close on backdrop click
-   */
-  closeOnBackdropClick?: boolean
-  
-  /**
-   * Whether to close on ESC key press
-   */
-  closeOnEscape?: boolean
-  
-  /**
-   * Size of the modal
-   */
-  size?: 'sm' | 'md' | 'lg' | 'full'
-  
-  /**
-   * Element to return focus to when modal closes
-   */
-  returnFocusTo?: HTMLElement | null
-}
-
-/**
- * Accessible Modal component using HTML5 dialog element
- * 
- * Uses the native `<dialog>` element which provides:
- * - Built-in focus management and focus trapping
- * - Automatic body scroll prevention
- * - Native backdrop overlay
- * - ESC key handling (configurable)
- * 
- * WCAG Compliance:
- * - 2.1.1 Keyboard: ESC key support, built-in focus trap
- * - 2.1.2 No Keyboard Trap: Focus returns to trigger
- * - 2.4.3 Focus Order: Focus trapped within modal (native behavior)
- * - 4.1.2 Name, Role, Value: ARIA modal pattern
- * 
- * @example
- * ```tsx
- * <Modal
- *   isOpen={isOpen}
- *   onClose={() => setIsOpen(false)}
- *   title="Confirm Action"
- * >
- *   <p>Are you sure?</p>
- * </Modal>
- * ```
- */
-export const Modal: React.FC<ModalProps> = ({
-  isOpen,
-  onClose,
-  title,
-  children,
-  closeOnBackdropClick = true,
-  closeOnEscape = true,
-  size = 'md',
-  returnFocusTo,
-}) => {
-  const dialogRef = useRef<HTMLDialogElement>(null)
-  const contentRef = useRef<HTMLDivElement>(null)
-  const titleId = React.useId()
-  const descriptionId = React.useId()
-
-  // Return focus on close
-  useFocusReturn(isOpen, returnFocusTo)
-
-  // Handle dialog open/close
-  useEffect(() => {
-    const dialog = dialogRef.current
-    if (!dialog) return
-
-    if (isOpen) {
-      // Show modal dialog
-      dialog.showModal();
-    } else {
-      // Close dialog
-      dialog.close();
-    }
-
-    return () => {
-      // Cleanup: ensure dialog is closed when component unmounts
-      if (dialog.open) {
-        dialog.close();
-      }
-    }
-  }, [isOpen])
-
-  // Handle backdrop clicks
-  // The ::backdrop pseudo-element doesn't bubble events to the dialog element,
-  // so we need to listen for clicks on the document and check if they're outside
-  // the dialog content area.
-  useEffect(() => {
-    if (!isOpen || !closeOnBackdropClick) return
-
-    const handleDocumentClick = (event: MouseEvent) => {
-      const dialog = dialogRef.current
-      const content = contentRef.current
-      
-      if (!dialog || !content) return
-
-      // Check if click target is outside the dialog content area
-      const target = event.target as Node
-      
-      // If the click is not inside the content wrapper, it's a backdrop click
-      if (!content.contains(target)) {
-        // Verify click coordinates are outside content bounds for extra safety
-        const rect = content.getBoundingClientRect()
-        const clickX = event.clientX
-        const clickY = event.clientY
-        
-        const isOutsideContent = 
-          clickX < rect.left ||
-          clickX > rect.right ||
-          clickY < rect.top ||
-          clickY > rect.bottom
-
-        if (isOutsideContent) {
-          event.preventDefault()
-          event.stopPropagation()
-          onClose()
-        }
-      }
-    }
-
-    // Use capture phase to catch events before they bubble
-    document.addEventListener('mousedown', handleDocumentClick, true)
-
-    return () => {
-      document.removeEventListener('mousedown', handleDocumentClick, true)
-    }
-  }, [isOpen, closeOnBackdropClick, onClose])
-
-  // Handle cancel event (fires when ESC key is pressed)
-  const handleCancel = (event: React.SyntheticEvent<HTMLDialogElement>) => {
-    // Prevent default close behavior
-    event.preventDefault()
-    // Only close if closeOnEscape is enabled
-    if (closeOnEscape) {
-      onClose();
-    }
-  }
-
-  return (
-    <dialog
-      ref={dialogRef}
-      className={`modal modal--${size} ${isOpen ? 'modal--open' : ''}`}
-      aria-labelledby={titleId}
-      aria-describedby={descriptionId}
-      onCancel={handleCancel}
-    >
-      <div ref={contentRef} className="modal-content-wrapper">
-        <div className="modal-header">
-          <h2 id={titleId} className="modal-title">
-            {title}
-          </h2>
-          <Button
-            variant="ghost"
-            size="sm"
-            onClick={onClose}
-            aria-label="Close modal"
-            className="modal-close"
-          >
-            ×
-          </Button>
-        </div>
-        <div id={descriptionId} className="modal-content">
-          {children}
-        </div>
-      </div>
-    </dialog>
-  )
-}
-
-Modal.displayName = 'Modal'
-

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

@@ -1,3 +0,0 @@
-export { Modal } from './Modal'
-export type { ModalProps } from './Modal'
-

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

@@ -1,213 +0,0 @@
-import type { Meta, StoryObj } from '@storybook/react'
-import { useState } from 'react'
-import { Tabs } from './Tabs'
-
-/**
- * # Tabs Component
- * 
- * An accessible tabs component following the WAI-ARIA tabs pattern with full keyboard
- * navigation support and proper focus management.
- * 
- * ## Usage
- * 
- * ```tsx
- * import { Tabs } from '@a11ypros/a11y-ui-components'
- * 
- * function MyComponent() {
- *   return (
- *     <Tabs
- *       aria-label="Settings tabs"
- *       items={[
- *         { id: 'general', label: 'General', content: <div>General content</div> },
- *         { id: 'account', label: 'Account', content: <div>Account content</div> },
- *       ]}
- *     />
- *   )
- * }
- * ```
- * 
- * ## Features
- * 
- * - **Arrow key navigation**: Navigate between tabs using arrow keys
- * - **Activation modes**: Automatic (arrow keys activate immediately) or manual (arrow keys move focus, Enter/Space activates)
- * - **Home/End support**: Jump to first or last tab
- * - **Orientation support**: Horizontal (default) or vertical layouts
- * - **ARIA tabs pattern**: Proper semantic structure and ARIA attributes
- * - **Focus management**: Focus moves to active tab panel content
- * 
- * ## Accessibility
- * 
- * ### WCAG 2.1/2.2 Compliance
- * 
- * - **2.1.1 Keyboard**: Full keyboard navigation with arrow keys, Home, and End
- * - **4.1.2 Name, Role, Value**: Proper ARIA tabs pattern with role="tablist", role="tab", role="tabpanel"
- * - **2.4.3 Focus Order**: Proper focus management between tabs and panels
- * - **2.4.7 Focus Visible**: Clear focus indicators on tab buttons
- * 
- * ### Keyboard Interactions
- * 
- * | Key | Action (Automatic) | Action (Manual) |
- * |-----|---------------------|-----------------|
- * | **Arrow Right/Down** | Move to next tab and activate | Move focus to next tab |
- * | **Arrow Left/Up** | Move to previous tab and activate | Move focus to previous tab |
- * | **Home** | Move to first tab and activate | Move focus to first tab |
- * | **End** | Move to last tab and activate | Move focus to last tab |
- * | **Enter/Space** | N/A | Activate focused tab |
- * | **Tab** | Move focus to tab panel content | Move focus to tab panel content |
- * | **Shift+Tab** | Move focus away from tabs | Move focus away from tabs |
- * 
- * ### Screen Reader Support
- * 
- * - Tab list role and label are announced
- * - Active tab is announced with "selected" state
- * - Tab panel content is associated with its tab
- * - Tab count and position are announced (e.g., "Tab 2 of 3")
- * 
- * ### Focus Management
- * 
- * - Focus moves to active tab when component mounts
- * - Arrow keys move focus between tabs
- * - Tab key moves focus into tab panel content
- * - Focus returns to tab when panel content loses focus
- * 
- * ## Best Practices
- * 
- * 1. **Provide aria-label**: Required for screen readers to understand tab purpose
- * 2. **Keep tab labels concise**: Short, descriptive labels work best
- * 3. **Use appropriate orientation**: Horizontal for most cases, vertical for sidebars
- * 4. **Limit tab count**: Too many tabs can be overwhelming (aim for 5-7 max)
- * 5. **Make content accessible**: Ensure tab panel content is keyboard navigable
- * 
- * ## Common Pitfalls
- * 
- * - Missing aria-label (screen readers can't understand tab purpose)
- * - Too many tabs (becomes hard to navigate)
- * - Non-keyboard accessible content in panels (breaks keyboard navigation)
- * - Not following ARIA tabs pattern (breaks screen reader support)
- * - Changing tab order dynamically (confuses keyboard users)
- * 
- * @component
- * @example
- * ```tsx
- * <Tabs
- *   aria-label="Settings"
- *   items={[
- *     { id: 'general', label: 'General', content: <SettingsForm /> },
- *     { id: 'advanced', label: 'Advanced', content: <AdvancedForm /> },
- *   ]}
- * />
- * ```
- */
-const meta: Meta<typeof Tabs> = {
-  title: 'Components/Tabs',
-  component: Tabs,
-  tags: ['autodocs'],
-}
-
-export default meta
-type Story = StoryObj<typeof Tabs>
-
-/**
- * Horizontal tabs layout (default). Tabs are arranged in a row at the top,
- * with tab panels displayed below. Use for most common tab scenarios.
- */
-export const Default: Story = {
-  render: () => {
-    const [selectedId, setSelectedId] = useState('general')
-    
-    return (
-      <Tabs
-        aria-label="Settings tabs"
-        selectedId={selectedId}
-        onSelectionChange={setSelectedId}
-        items={[
-          {
-            id: 'general',
-            label: 'General',
-            content: <div>General settings content</div>,
-          },
-          {
-            id: 'account',
-            label: 'Account',
-            content: <div>Account settings content</div>,
-          },
-          {
-            id: 'privacy',
-            label: 'Privacy',
-            content: <div>Privacy settings content</div>,
-          },
-        ]}
-      />
-    )
-  },
-}
-
-/**
- * Vertical tabs layout. Tabs are arranged in a column on the left side,
- * with tab panels displayed to the right. Use for sidebar navigation or
- * when you have many tabs that would overflow horizontally.
- */
-export const Vertical: Story = {
-  render: () => {
-    const [selectedId, setSelectedId] = useState('tab1')
-    
-    return (
-      <Tabs
-        aria-label="Vertical tabs"
-        orientation="vertical"
-        selectedId={selectedId}
-        onSelectionChange={setSelectedId}
-        items={[
-          {
-            id: 'tab1',
-            label: 'Tab 1',
-            content: <div>Content 1</div>,
-          },
-          {
-            id: 'tab2',
-            label: 'Tab 2',
-            content: <div>Content 2</div>,
-          },
-        ]}
-      />
-    )
-  },
-}
-
-/**
- * Manual activation mode. Arrow keys move focus between tabs without activating them.
- * Press Enter or Space to activate the focused tab. This is useful when tab content
- * changes are expensive or when you want users to preview tabs before activating.
- */
-export const ManualActivation: Story = {
-  render: () => {
-    const [selectedId, setSelectedId] = useState('general')
-    
-    return (
-      <Tabs
-        aria-label="Settings tabs with manual activation"
-        activationMode="manual"
-        selectedId={selectedId}
-        onSelectionChange={setSelectedId}
-        items={[
-          {
-            id: 'general',
-            label: 'General',
-            content: <div>General settings content</div>,
-          },
-          {
-            id: 'account',
-            label: 'Account',
-            content: <div>Account settings content</div>,
-          },
-          {
-            id: 'privacy',
-            label: 'Privacy',
-            content: <div>Privacy settings content</div>,
-          },
-        ]}
-      />
-    )
-  },
-}
-