@a11ypros/a11y-ui-components 1.0.1 → 1.0.3

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

@@ -1,160 +0,0 @@
-'use client'
-
-import React from 'react'
-import { combineAriaDescribedBy } from '../../utils/aria'
-import { createArrowKeyHandler, isActivationKey } from '../../utils/keyboard'
-import './Select.css'
-
-export interface SelectOption {
-  value: string
-  label: string
-  disabled?: boolean
-}
-
-export interface SelectProps extends Omit<React.SelectHTMLAttributes<HTMLSelectElement>, 'children'> {
-  /**
-   * Options for the select
-   */
-  options: SelectOption[]
-  
-  /**
-   * Error message to display
-   */
-  error?: string
-  
-  /**
-   * Helper text to display below the select
-   */
-  helperText?: string
-  
-  /**
-   * Label for the select
-   */
-  label?: string
-  
-  /**
-   * Placeholder option text
-   */
-  placeholder?: string
-}
-
-/**
- * Accessible Select component
- * 
- * WCAG Compliance:
- * - 1.3.1 Info and Relationships: Proper label-select association
- * - 2.1.1 Keyboard: Full keyboard navigation
- * - 4.1.2 Name, Role, Value: Proper ARIA attributes
- * 
- * @example
- * ```tsx
- * <Select
- *   id="country"
- *   label="Country"
- *   options={[
- *     { value: 'us', label: 'United States' },
- *     { value: 'ca', label: 'Canada' },
- *   ]}
- * />
- * ```
- */
-export const Select = React.forwardRef<HTMLSelectElement, SelectProps>(
-  (
-    {
-      id,
-      options,
-      error,
-      helperText,
-      label,
-      placeholder,
-      className = '',
-      'aria-describedby': ariaDescribedBy,
-      ...props
-    },
-    ref
-  ) => {
-    const selectId = React.useId()
-    const finalId = id || `select-${selectId}`
-    const errorId = error ? `${finalId}-error` : undefined
-    const helperId = helperText ? `${finalId}-helper` : undefined
-
-    const describedBy = combineAriaDescribedBy(
-      ariaDescribedBy,
-      errorId,
-      helperId
-    )
-
-    const handleKeyDown = React.useCallback(
-      (event: React.KeyboardEvent<HTMLSelectElement>) => {
-        // Arrow keys are handled natively by select
-        // But we can add custom handling if needed
-        if (props.onKeyDown) {
-          props.onKeyDown(event)
-        }
-      },
-      [props.onKeyDown]
-    )
-
-    const classes = [
-      'form-select',
-      error && 'form-select--error',
-      props.disabled && 'form-select--disabled',
-      className,
-    ]
-      .filter(Boolean)
-      .join(' ')
-
-    return (
-      <div className="form-select-wrapper">
-        {label && (
-          <label htmlFor={finalId} className="form-label">
-            {label}
-            {props.required && (
-              <span className="form-label__required" aria-hidden="true">
-                {' '}*
-              </span>
-            )}
-          </label>
-        )}
-        <select
-          ref={ref}
-          id={finalId}
-          className={classes}
-          aria-invalid={error ? true : undefined}
-          aria-describedby={describedBy}
-          onKeyDown={handleKeyDown}
-          required={props.required ? true : undefined}
-          {...props}
-        >
-          {placeholder && (
-            <option value="" disabled>
-              {placeholder}
-            </option>
-          )}
-          {options.map((option) => (
-            <option
-              key={option.value}
-              value={option.value}
-              disabled={option.disabled}
-            >
-              {option.label}
-            </option>
-          ))}
-        </select>
-        {helperText && !error && (
-          <span id={helperId} className="form-helper-text">
-            {helperText}
-          </span>
-        )}
-        {error && (
-          <span id={errorId} className="form-error-text" role="alert">
-            {error}
-          </span>
-        )}
-      </div>
-    )
-  }
-)
-
-Select.displayName = 'Select'
-

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

@@ -1,253 +0,0 @@
-import type { Meta, StoryObj } from '@storybook/react'
-import { useState } from 'react'
-import { Textarea } from './Textarea'
-
-/**
- * # Textarea Component
- * 
- * An accessible textarea component with proper label association, error handling,
- * character counting, and ARIA attributes. Ideal for multi-line text input.
- * 
- * ## Usage
- * 
- * ```tsx
- * import { Textarea } from '@a11ypros/a11y-ui-components'
- * 
- * function MyComponent() {
- *   return (
- *     <Textarea
- *       label="Message"
- *       placeholder="Enter your message"
- *       maxLength={500}
- *       showCount
- *     />
- *   )
- * }
- * ```
- * 
- * ## Features
- * 
- * - **Label association**: Labels are properly associated with textareas using \`htmlFor\` and \`id\`
- * - **Error handling**: Error messages are announced to screen readers via ARIA
- * - **Helper text**: Optional helper text for additional context
- * - **Character counting**: Optional character count display with \`maxLength\` support
- * - **Auto-resize**: Can be configured to grow with content
- * 
- * ## Accessibility
- * 
- * ### WCAG 2.1/2.2 Compliance
- * 
- * - **1.3.1 Info and Relationships**: Proper label-textarea association via \`htmlFor\` and \`id\`
- * - **4.1.2 Name, Role, Value**: Proper ARIA attributes including \`aria-required\`, \`aria-invalid\`, \`aria-describedby\`
- * - **4.1.3 Status Messages**: Error messages and character count announced to screen readers
- * 
- * ### Keyboard Interactions
- * 
- * | Key | Action |
- * |-----|--------|
- * | **Tab** | Moves focus to the textarea |
- * | **Shift+Tab** | Moves focus away from the textarea |
- * | **Enter** | Creates new line (does not submit form) |
- * | **Arrow keys** | Navigate within text content |
- * 
- * ### Screen Reader Support
- * 
- * - Textarea role and label are announced when focused
- * - Character count is announced when \`showCount\` is enabled
- * - Required state is announced ("required")
- * - Error messages are announced when present
- * - Helper text is announced via \`aria-describedby\`
- * - Max length is announced when \`maxLength\` is set
- * 
- * ### 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 multi-line input**: Textarea is for longer, multi-line text (use Input for single-line)
- * 3. **Set appropriate maxLength**: Helps users understand constraints
- * 4. **Provide helpful error messages**: Be specific about validation failures
- * 5. **Use helper text for guidance**: Help users understand what to enter
- * 
- * ## Common Pitfalls
- * 
- * - Missing label (screen readers can't identify the textarea)
- * - Using textarea for single-line input (use Input component instead)
- * - Not setting maxLength when needed (users don't know limits)
- * - Vague error messages (be specific about validation failures)
- * - Too small initial size (hard to see what you're typing)
- * 
- * @component
- * @example
- * ```tsx
- * <Textarea
- *   label="Feedback"
- *   maxLength={500}
- *   showCount
- *   required
- *   error={errors.feedback}
- *   helperText="Please provide detailed feedback"
- * />
- * ```
- */
-const meta: Meta<typeof Textarea> = {
-  title: 'Components/Form/Textarea',
-  component: Textarea,
-  tags: ['autodocs'],
-}
-
-export default meta
-type Story = StoryObj<typeof Textarea>
-
-/**
- * Standard textarea with label and placeholder. The label is properly associated
- * with the textarea for screen readers and clicking the label focuses the textarea.
- */
-export const Default: Story = {
-  render: () => {
-    const [value, setValue] = useState('')
-    return (
-      <Textarea
-        id="textarea-default"
-        label="Message"
-        value={value}
-        onChange={(e) => setValue(e.target.value)}
-        placeholder="Enter your message here..."
-      />
-    )
-  },
-}
-
-/**
- * Textarea with character count. Shows remaining characters when \`maxLength\`
- * and \`showCount\` are set. The count is announced to screen readers.
- */
-export const WithCharacterCount: Story = {
-  render: () => {
-    const [value, setValue] = useState('')
-    return (
-      <Textarea
-        id="textarea-count"
-        label="Description"
-        value={value}
-        onChange={(e) => setValue(e.target.value)}
-        maxLength={200}
-        showCount
-        placeholder="Enter a description (max 200 characters)"
-      />
-    )
-  },
-}
-
-/**
- * Textarea with error message. Error messages are announced to screen readers
- * and displayed visually below the textarea. The textarea is marked as invalid
- * with \`aria-invalid="true"\`.
- */
-export const WithError: Story = {
-  render: () => {
-    const [value, setValue] = useState('')
-    return (
-      <Textarea
-        id="textarea-error"
-        label="Comments"
-        value={value}
-        onChange={(e) => setValue(e.target.value)}
-        error="Please enter at least 10 characters"
-        maxLength={500}
-        showCount
-      />
-    )
-  },
-}
-
-/**
- * Textarea with helper text. Helper text provides additional context or guidance
- * and is associated with the textarea via \`aria-describedby\`.
- */
-export const WithHelperText: Story = {
-  render: () => {
-    const [value, setValue] = useState('')
-    return (
-      <Textarea
-        id="textarea-helper"
-        label="Additional notes"
-        value={value}
-        onChange={(e) => setValue(e.target.value)}
-        helperText="Include any additional information that might be helpful"
-        maxLength={1000}
-        showCount
-      />
-    )
-  },
-}
-
-/**
- * Required textarea field. Required textareas are marked with \`aria-required="true"\`
- * and display a visual indicator (asterisk) next to the label.
- */
-export const Required: Story = {
-  render: () => {
-    const [value, setValue] = useState('')
-    return (
-      <Textarea
-        id="textarea-required"
-        label="Bio"
-        value={value}
-        onChange={(e) => setValue(e.target.value)}
-        required
-        maxLength={500}
-        showCount
-        placeholder="Tell us about yourself"
-      />
-    )
-  },
-}
-
-/**
- * Disabled textarea that cannot be edited. Disabled textareas are announced as
- * "disabled" by screen readers and appear visually dimmed.
- */
-export const Disabled: Story = {
-  args: {
-    id: 'textarea-disabled',
-    label: 'Disabled textarea',
-    disabled: true,
-    defaultValue: 'This textarea cannot be edited',
-  },
-}
-
-/**
- * Large textarea for longer content. Use appropriate rows and cols attributes
- * to provide a good initial size for the content type.
- */
-export const Large: Story = {
-  render: () => {
-    const [value, setValue] = useState('')
-    return (
-      <Textarea
-        id="textarea-large"
-        label="Full article"
-        value={value}
-        onChange={(e) => setValue(e.target.value)}
-        rows={10}
-        maxLength={5000}
-        showCount
-        placeholder="Write your article here..."
-      />
-    )
-  },
-  parameters: {
-    docs: {
-      description: {
-        story: 'Large textarea with more rows for longer content. Adjust rows and cols to fit your use case.',
-      },
-    },
-  },
-}
-

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

@@ -1,145 +0,0 @@
-'use client'
-
-import React from 'react'
-import { combineAriaDescribedBy } from '../../utils/aria'
-import './Textarea.css'
-
-export interface TextareaProps extends React.TextareaHTMLAttributes<HTMLTextAreaElement> {
-  /**
-   * Error message to display
-   */
-  error?: string
-  
-  /**
-   * Helper text to display below the textarea
-   */
-  helperText?: string
-  
-  /**
-   * Label for the textarea
-   */
-  label?: string
-  
-  /**
-   * Maximum character count (shows counter)
-   */
-  maxLength?: number
-  
-  /**
-   * Whether to show character count
-   */
-  showCount?: boolean
-}
-
-/**
- * Accessible Textarea component
- * 
- * WCAG Compliance:
- * - 1.3.1 Info and Relationships: Proper label-textarea association
- * - 4.1.2 Name, Role, Value: Proper ARIA attributes
- * - 4.1.3 Status Messages: Error messages announced
- * 
- * @example
- * ```tsx
- * <Textarea
- *   id="message"
- *   label="Message"
- *   maxLength={500}
- *   showCount
- * />
- * ```
- */
-export const Textarea = React.forwardRef<HTMLTextAreaElement, TextareaProps>(
-  (
-    {
-      id,
-      error,
-      helperText,
-      label,
-      maxLength,
-      showCount = false,
-      className = '',
-      value,
-      'aria-describedby': ariaDescribedBy,
-      ...props
-    },
-    ref
-  ) => {
-    const textareaId = React.useId()
-    const finalId = id || `textarea-${textareaId}`
-    const errorId = error ? `${finalId}-error` : undefined
-    const helperId = helperText ? `${finalId}-helper` : undefined
-    const countId = showCount ? `${finalId}-count` : undefined
-
-    const describedBy = combineAriaDescribedBy(
-      ariaDescribedBy,
-      errorId,
-      helperId,
-      countId
-    )
-
-    const currentLength = typeof value === 'string' ? value.length : 0
-    const remainingChars = maxLength ? maxLength - currentLength : undefined
-
-    const classes = [
-      'form-textarea',
-      error && 'form-textarea--error',
-      props.disabled && 'form-textarea--disabled',
-      className,
-    ]
-      .filter(Boolean)
-      .join(' ')
-
-    return (
-      <div className="form-textarea-wrapper">
-        {label && (
-          <label htmlFor={finalId} className="form-label">
-            {label}
-            {props.required && (
-              <span className="form-label__required" aria-hidden="true">
-                {' '}*
-              </span>
-            )}
-          </label>
-        )}
-        <textarea
-          ref={ref}
-          id={finalId}
-          className={classes}
-          maxLength={maxLength}
-          value={value}
-          aria-invalid={error ? true : undefined}
-          aria-describedby={describedBy}
-          required={props.required ? true : undefined}
-          {...props}
-        />
-        {(showCount || helperText) && (
-          <div className="form-textarea-footer">
-            {helperText && !error && (
-              <span id={helperId} className="form-helper-text">
-                {helperText}
-              </span>
-            )}
-            {error && (
-              <span id={errorId} className="form-error-text" role="alert">
-                {error}
-              </span>
-            )}
-            {showCount && maxLength && (
-              <span
-                id={countId}
-                className="form-character-count"
-                aria-live="polite"
-              >
-                {currentLength} / {maxLength}
-              </span>
-            )}
-          </div>
-        )}
-      </div>
-    )
-  }
-)
-
-Textarea.displayName = 'Textarea'
-

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

@@ -1,8 +0,0 @@
-export * from './Input'
-export * from './Textarea'
-export * from './Select'
-export * from './Checkbox'
-export * from './Radio'
-export * from './Fieldset'
-export * from './Label'
-

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

@@ -1,128 +0,0 @@
-import type { Meta, StoryObj } from '@storybook/react'
-import { Link } from './Link'
-
-/**
- * # Link Component
- * 
- * An accessible link component with automatic external link detection, skip link support,
- * and proper focus management. Uses semantic `<a>` element with enhanced accessibility features.
- * 
- * ## Usage
- * 
- * ```tsx
- * import { Link } from '@a11ypros/a11y-ui-components'
- * 
- * function MyComponent() {
- *   return (
- *     <Link href="/about">
- *       Learn more about us
- *     </Link>
- *   )
- * }
- * ```
- * 
- * ## Features
- * 
- * - **External link detection**: Automatically adds \`rel="noopener noreferrer"\` for security
- * - **Skip links**: Special styling and behavior for keyboard navigation skip links
- * - **Focus management**: Clear focus indicators that meet WCAG contrast requirements
- * - **ARIA support**: Proper aria-label support for icon-only or context-dependent links
- * 
- * ## Accessibility
- * 
- * ### WCAG 2.1/2.2 Compliance
- * 
- * - **2.4.4 Link Purpose (In Context)**: Clear link text or aria-label that describes the link purpose
- * - **2.4.7 Focus Visible**: Clear 2px outline on focus (meets 3:1 contrast ratio)
- * - **4.1.2 Name, Role, Value**: Proper semantic HTML with accessible name
- * 
- * ### Keyboard Interactions
- * 
- * | Key | Action |
- * |-----|--------|
- * | **Enter** | Activates the link |
- * | **Tab** | Moves focus to the link |
- * | **Shift+Tab** | Moves focus away from the link |
- * 
- * ### Screen Reader Support
- * 
- * - Link role and name are announced automatically
- * - External links: "Link, external" announced (when \`external\` prop is true)
- * - Skip links: Properly announced for keyboard navigation
- * - Custom labels via \`aria-label\` prop for context-dependent links
- * 
- * ### 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. **Use descriptive link text**: Avoid "click here" or "read more" - describe what the link does
- * 2. **Use external prop for external links**: Automatically adds security attributes
- * 3. **Provide aria-label for icon-only links**: Screen readers need context
- * 4. **Use skip links for main content**: Helps keyboard users navigate large pages
- * 5. **Don't use links for buttons**: Use Button component for actions, Link for navigation
- * 
- * ## Common Pitfalls
- * 
- * - Using generic link text like "click here" (screen readers lose context)
- * - Missing \`external\` prop on external links (security risk)
- * - Using links for actions instead of navigation (use Button component)
- * - Missing \`aria-label\` on icon-only links (screen readers can't understand purpose)
- * - Removing focus styles (breaks keyboard navigation visibility)
- * 
- * @component
- * @example
- * ```tsx
- * <Link href="/about" external>
- *   Learn more
- * </Link>
- * ```
- */
-const meta: Meta<typeof Link> = {
-  title: 'Components/Link',
-  component: Link,
-  tags: ['autodocs'],
-}
-
-export default meta
-type Story = StoryObj<typeof Link>
-
-/**
- * Standard internal link for navigation within the application.
- */
-export const Default: Story = {
-  args: {
-    href: '#',
-    children: 'Link text',
-  },
-}
-
-/**
- * External link that automatically adds security attributes (\`rel="noopener noreferrer"\`)
- * to prevent security vulnerabilities when opening links in new tabs.
- */
-export const External: Story = {
-  args: {
-    href: 'https://example.com',
-    external: true,
-    children: 'External link',
-  },
-}
-
-/**
- * Skip link for keyboard navigation. These links allow keyboard users to skip
- * repetitive navigation and jump directly to main content. Typically placed
- * at the top of the page and styled to be visible on focus.
- */
-export const SkipLink: Story = {
-  args: {
-    href: '#main-content',
-    skip: true,
-    children: 'Skip to main content',
-  },
-}
-