@a11ypros/a11y-ui-components 1.0.0 → 1.0.1

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

@@ -0,0 +1,160 @@
+'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

@@ -0,0 +1,253 @@
+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

@@ -0,0 +1,145 @@
+'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

@@ -0,0 +1,8 @@
+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

@@ -0,0 +1,128 @@
+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',
+  },
+}
+