@a11ypros/a11y-ui-components 1.0.0 → 1.0.1

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

@@ -0,0 +1,210 @@
+import type { Meta, StoryObj } from '@storybook/react'
+import { useState } from 'react'
+import { Fieldset } from './Fieldset'
+import { Input } from './Input'
+import { Checkbox } from './Checkbox'
+import { Radio } from './Radio'
+
+/**
+ * # Fieldset Component
+ * 
+ * An accessible fieldset component for grouping related form controls. Uses semantic
+ * HTML fieldset/legend structure to provide context for screen readers.
+ * 
+ * ## Usage
+ * 
+ * ```tsx
+ * import { Fieldset, Input } from '@a11ypros/a11y-ui-components'
+ * 
+ * function MyComponent() {
+ *   return (
+ *     <Fieldset legend="Shipping Address">
+ *       <Input label="Street" />
+ *       <Input label="City" />
+ *       <Input label="Zip Code" />
+ *     </Fieldset>
+ *   )
+ * }
+ * ```
+ * 
+ * ## Features
+ * 
+ * - **Semantic grouping**: Uses proper `<fieldset>` and `<legend>` elements
+ * - **Visual legend**: Legend text provides context for the grouped fields
+ * - **Hidden legend**: Option to hide legend visually while keeping it accessible
+ * - **Required indicator**: Shows asterisk when fieldset contains required fields
+ * 
+ * ## Accessibility
+ * 
+ * ### WCAG 2.1/2.2 Compliance
+ * 
+ * - **1.3.1 Info and Relationships**: Proper fieldset/legend structure for grouping related controls
+ * - **4.1.2 Name, Role, Value**: Proper semantic HTML with fieldset role
+ * 
+ * ### Screen Reader Support
+ * 
+ * - Fieldset legend is announced when entering the group
+ * - Provides context for all form controls within the fieldset
+ * - Required state is announced when fieldset contains required fields
+ * - Hidden legend is still announced to screen readers
+ * 
+ * ## Best Practices
+ * 
+ * 1. **Always provide a legend**: Required for accessibility - describes what the group is for
+ * 2. **Group related fields**: Use fieldsets to group logically related form controls
+ * 3. **Use for radio/checkbox groups**: Essential for grouping radio buttons and checkboxes
+ * 4. **Keep legends concise**: Short, descriptive legends work best
+ * 5. **Don't nest fieldsets**: Avoid nesting fieldsets within fieldsets
+ * 
+ * ## Common Pitfalls
+ * 
+ * - Missing legend (screen readers lose context for grouped fields)
+ * - Using div instead of fieldset (loses semantic meaning)
+ * - Nesting fieldsets (can confuse screen readers)
+ * - Too verbose legends (keep them concise)
+ * - Not using for radio/checkbox groups (required for proper grouping)
+ * 
+ * @component
+ * @example
+ * ```tsx
+ * <Fieldset legend="Contact Information">
+ *   <Input label="Email" type="email" required />
+ *   <Input label="Phone" type="tel" />
+ * </Fieldset>
+ * ```
+ */
+const meta: Meta<typeof Fieldset> = {
+  title: 'Components/Form/Fieldset',
+  component: Fieldset,
+  tags: ['autodocs'],
+}
+
+export default meta
+type Story = StoryObj<typeof Fieldset>
+
+/**
+ * Standard fieldset with visible legend. Groups related form controls
+ * and provides context through the legend text.
+ */
+export const Default: Story = {
+  render: () => (
+    <Fieldset legend="Shipping Address">
+      <Input label="Street address"/>
+      <Input label="City" />
+      <Input label="Zip code"/>
+    </Fieldset>
+  ),
+}
+
+/**
+ * Fieldset with required fields. The required indicator (asterisk) appears
+ * next to the legend when the fieldset contains required fields.
+ */
+export const WithRequiredFields: Story = {
+  render: () => (
+    <Fieldset legend="Personal Information" required>
+      <Input label="First name" id="first-name" required />
+      <Input label="Last name" id="last-name" required />
+      <Input label="Email" id="email" type="email" required />
+    </Fieldset>
+  ),
+}
+
+/**
+ * Fieldset with hidden legend. The legend is visually hidden but still
+ * announced to screen readers, useful when visual grouping is clear.
+ */
+export const HiddenLegend: Story = {
+  render: () => (
+    <Fieldset legend="Billing Information" legendHidden>
+      <Input label="Card number" id="card" />
+      <Input label="Expiry date" id="expiry" />
+      <Input label="CVV" id="cvv" />
+    </Fieldset>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Legend is visually hidden but still accessible to screen readers. Use when visual grouping is obvious but you want to maintain semantic structure.',
+      },
+    },
+  },
+}
+
+/**
+ * Fieldset grouping radio buttons. Essential for proper semantic grouping
+ * of radio button groups.
+ */
+export const WithRadioButtons: Story = {
+  render: () => {
+    const [value, setValue] = useState('')
+    return (
+      <Fieldset legend="Choose a size">
+        <Radio
+          name="size"
+          value={value}
+          onChange={(e) => setValue(e.target.value)}
+          options={[
+            { value: 'small', label: 'Small' },
+            { value: 'medium', label: 'Medium' },
+            { value: 'large', label: 'Large' },
+          ]}
+        />
+      </Fieldset>
+    )
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Fieldset is essential for grouping radio buttons. The Radio component uses fieldset internally, but you can wrap multiple radio groups in a fieldset for higher-level grouping.',
+      },
+    },
+  },
+}
+
+/**
+ * Fieldset grouping checkboxes. Groups related checkboxes together
+ * for better semantic structure.
+ */
+export const WithCheckboxes: Story = {
+  render: () => {
+    const [preferences, setPreferences] = useState({
+      email: false,
+      sms: false,
+      push: false,
+    })
+
+    return (
+      <Fieldset legend="Notification Preferences">
+        <div style={{ display: 'flex', flexDirection: 'column', gap: '1rem' }}>
+        <Checkbox
+          id="pref-email"
+          label="Email notifications"
+          checked={preferences.email}
+          onChange={(e) => setPreferences((prev) => ({ ...prev, email: e.target.checked }))}
+        />
+        <Checkbox
+          id="pref-sms"
+          label="SMS notifications"
+          checked={preferences.sms}
+          onChange={(e) => setPreferences((prev) => ({ ...prev, sms: e.target.checked }))}
+        />
+        <Checkbox
+          id="pref-push"
+          label="Push notifications"
+          checked={preferences.push}
+          onChange={(e) => setPreferences((prev) => ({ ...prev, push: e.target.checked }))}
+        />
+        </div>
+      </Fieldset>
+    )
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Fieldset groups related checkboxes together, providing context about what the checkboxes are for.',
+      },
+    },
+  },
+}
+

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

@@ -0,0 +1,71 @@
+import React from 'react'
+import './Fieldset.css'
+
+export interface FieldsetProps extends React.FieldsetHTMLAttributes<HTMLFieldSetElement> {
+  /**
+   * Legend text for the fieldset
+   */
+  legend?: string
+  
+  /**
+   * Whether the legend is visually hidden (but still accessible)
+   */
+  legendHidden?: boolean
+  
+  /**
+   * Whether to show a required field explanation. Use this if the fieldset contains required fields.
+   */
+  required?: boolean
+}
+
+/**
+ * Accessible Fieldset component
+ * 
+ * WCAG Compliance:
+ * - 1.3.1 Info and Relationships: Proper fieldset/legend structure
+ * - 4.1.2 Name, Role, Value: Proper semantic HTML
+ * 
+ * @example
+ * ```tsx
+ * <Fieldset legend="Shipping Address">
+ *   <Input label="Street" />
+ *   <Input label="City" />
+ * </Fieldset>
+ * ```
+ */
+export const Fieldset = React.forwardRef<HTMLFieldSetElement, FieldsetProps>(
+  ({ legend, legendHidden = false, required = false, className = '', children, ...props }, ref) => {
+    const classes = [
+      'form-fieldset',
+      className,
+    ]
+      .filter(Boolean)
+      .join(' ')
+
+    const legendClasses = [
+      'form-legend',
+      legendHidden && 'form-legend--hidden',
+    ]
+      .filter(Boolean)
+      .join(' ')
+
+    return (
+      <fieldset ref={ref} className={classes} {...props}>
+        {legend && (
+          <legend className={legendClasses}>
+            {legend}
+          </legend>
+        )}
+        {required && (
+          <p className="fieldset__required">
+            {' '}<span className='fieldset__required-indicator'>*</span> indicates a required field.
+          </p>
+        )}
+        {children}
+      </fieldset>
+    )
+  }
+)
+
+Fieldset.displayName = 'Fieldset'
+

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

@@ -0,0 +1,164 @@
+import type { Meta, StoryObj } from '@storybook/react'
+import { Input } from './Input'
+
+/**
+ * # Input Component
+ * 
+ * An accessible form input component with proper label association, error handling,
+ * and ARIA attributes. Supports all standard HTML input types.
+ * 
+ * ## Usage
+ * 
+ * ```tsx
+ * import { Input } from '@a11ypros/a11y-ui-components'
+ * 
+ * function MyComponent() {
+ *   return (
+ *     <Input
+ *       label="Email address"
+ *       type="email"
+ *       required
+ *       placeholder="you@example.com"
+ *     />
+ *   )
+ * }
+ * ```
+ * 
+ * ## Features
+ * 
+ * - **Label association**: Labels are properly associated with inputs using \`htmlFor\` and \`id\`
+ * - **Error handling**: Error messages are announced to screen readers via ARIA
+ * - **Helper text**: Optional helper text for additional context
+ * - **Required indicators**: Visual and ARIA indicators for required fields
+ * - **All input types**: Supports text, email, password, number, tel, url, search, etc.
+ * 
+ * ## Accessibility
+ * 
+ * ### WCAG 2.1/2.2 Compliance
+ * 
+ * - **1.3.1 Info and Relationships**: Proper label-input association via \`htmlFor\` and \`id\`
+ * - **2.5.3 Label in Name**: Label text matches accessible name
+ * - **4.1.2 Name, Role, Value**: Proper ARIA attributes including \`aria-required\`, \`aria-invalid\`, \`aria-describedby\`
+ * - **4.1.3 Status Messages**: Error messages announced via ARIA live regions
+ * 
+ * ### Keyboard Interactions
+ * 
+ * | Key | Action |
+ * |-----|--------|
+ * | **Tab** | Moves focus to the input |
+ * | **Shift+Tab** | Moves focus away from the input |
+ * | **Enter** | Submits form (if in a form) |
+ * | **Arrow keys** | Navigate within input value (for text inputs) |
+ * 
+ * ### Screen Reader Support
+ * 
+ * - Label is announced when input receives focus
+ * - Required state is announced ("required")
+ * - Error messages are announced when present
+ * - Helper text is announced via \`aria-describedby\`
+ * - Input type is announced (e.g., "email", "password")
+ * 
+ * ### 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 appropriate input types**: Helps with validation and mobile keyboards
+ * 3. **Provide helpful error messages**: Be specific about what went wrong
+ * 4. **Use helper text for guidance**: Help users understand what to enter
+ * 5. **Mark required fields**: Use \`required\` prop and visual indicator
+ * 
+ * ## Common Pitfalls
+ * 
+ * - Missing label (screen readers can't identify the input)
+ * - Using placeholder as label (placeholders disappear and aren't reliable)
+ * - Vague error messages (be specific about validation failures)
+ * - Not marking required fields (users don't know what's mandatory)
+ * - Using wrong input type (affects mobile keyboards and validation)
+ * 
+ * @component
+ * @example
+ * ```tsx
+ * <Input
+ *   label="Email"
+ *   type="email"
+ *   required
+ *   error={errors.email}
+ *   helperText="We'll never share your email"
+ * />
+ * ```
+ */
+const meta: Meta<typeof Input> = {
+  title: 'Components/Form/Input',
+  component: Input,
+  tags: ['autodocs'],
+}
+
+export default meta
+type Story = StoryObj<typeof Input>
+
+/**
+ * Standard input with label and placeholder. The label is properly associated
+ * with the input for screen readers and clicking the label focuses the input.
+ */
+export const Default: Story = {
+  args: {
+    label: 'Email address',
+    type: 'email',
+    placeholder: 'you@example.com',
+  },
+}
+
+/**
+ * Input with error message. Error messages are announced to screen readers
+ * and displayed visually below the input. The input is marked as invalid
+ * with \`aria-invalid="true"\`.
+ */
+export const WithError: Story = {
+  args: {
+    label: 'Email address',
+    type: 'email',
+    error: 'Please enter a valid email address',
+  },
+}
+
+/**
+ * Input with helper text. Helper text provides additional context or guidance
+ * and is associated with the input via \`aria-describedby\`.
+ */
+export const WithHelperText: Story = {
+  args: {
+    label: 'Password',
+    type: 'password',
+    helperText: 'Must be at least 8 characters',
+  },
+}
+
+/**
+ * Required input field. Required fields are marked with \`aria-required="true"\`
+ * and display a visual indicator (asterisk) next to the label.
+ */
+export const Required: Story = {
+  args: {
+    label: 'Name',
+    required: true,
+  },
+}
+
+/**
+ * Disabled input that cannot be edited. Disabled inputs are announced as
+ * "disabled" by screen readers and appear visually dimmed.
+ */
+export const Disabled: Story = {
+  args: {
+    label: 'Disabled input',
+    disabled: true,
+    defaultValue: 'Cannot edit',
+  },
+}
+

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

@@ -0,0 +1,113 @@
+'use client'
+
+import React from 'react'
+import { generateId, combineAriaDescribedBy } from '../../utils/aria'
+import './Input.css'
+
+export interface InputProps extends React.InputHTMLAttributes<HTMLInputElement> {
+  /**
+   * Error message to display
+   */
+  error?: string
+  
+  /**
+   * Helper text to display below the input
+   */
+  helperText?: string
+  
+  /**
+   * Label for the input (creates associated label)
+   */
+  label?: string
+}
+
+/**
+ * Accessible Input component
+ * 
+ * WCAG Compliance:
+ * - 1.3.1 Info and Relationships: Proper label-input association
+ * - 2.5.3 Label in Name: Label text matches accessible name
+ * - 4.1.2 Name, Role, Value: Proper ARIA attributes
+ * - 4.1.3 Status Messages: Error messages announced
+ * 
+ * @example
+ * ```tsx
+ * <Input
+ *   id="email"
+ *   type="email"
+ *   label="Email address"
+ *   error="Please enter a valid email"
+ * />
+ * ```
+ */
+export const Input = React.forwardRef<HTMLInputElement, InputProps>(
+  (
+    {
+      id,
+      error,
+      helperText,
+      label,
+      className = '',
+      'aria-describedby': ariaDescribedBy,
+      ...props
+    },
+    ref
+  ) => {
+    const inputId = React.useId()
+    const finalId = id || `input-${inputId}`
+    const errorId = error ? `${finalId}-error` : undefined
+    const helperId = helperText ? `${finalId}-helper` : undefined
+
+    const describedBy = combineAriaDescribedBy(
+      ariaDescribedBy,
+      errorId,
+      helperId
+    )
+
+    const classes = [
+      'form-input',
+      error && 'form-input--error',
+      props.disabled && 'form-input--disabled',
+      className,
+    ]
+      .filter(Boolean)
+      .join(' ')
+
+    return (
+      <div className="form-input-wrapper">
+        {label && (
+          <label htmlFor={finalId} className="form-label">
+            {label}
+            {props.required && (
+              <span className="form-label__required" aria-hidden="true">
+                {' '}*
+              </span>
+            )}
+          </label>
+        )}
+        <input
+          ref={ref}
+          id={finalId}
+          className={classes}
+          aria-invalid={error ? true : undefined}
+          aria-describedby={describedBy}
+          required={props.required ? true : undefined}
+          {...props}
+        />
+        {helperText && !error && (
+          <span id={helperId} className="form-helper-text">
+            {helperText}
+          </span>
+        )}
+        {error && (
+          <span id={errorId} className="form-error-text" role="alert">
+            {error}
+          </span>
+        )}
+      </div>
+    )
+  }
+)
+
+Input.displayName = 'Input'
+

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

@@ -0,0 +1,56 @@
+import React from 'react'
+import './Label.css'
+
+export interface LabelProps extends React.LabelHTMLAttributes<HTMLLabelElement> {
+  /**
+   * Whether this label is required (shows asterisk)
+   */
+  required?: boolean
+  
+  /**
+   * ID of the input this label is associated with
+   */
+  htmlFor?: string
+}
+
+/**
+ * Accessible Label component
+ * 
+ * WCAG Compliance:
+ * - 1.3.1 Info and Relationships: Proper label-input association
+ * - 2.5.3 Label in Name: Label text matches accessible name
+ * - 4.1.2 Name, Role, Value: Proper semantic HTML
+ * 
+ * @example
+ * ```tsx
+ * <Label htmlFor="email" required>
+ *   Email address
+ * </Label>
+ * <Input id="email" type="email" />
+ * ```
+ */
+export const Label = React.forwardRef<HTMLLabelElement, LabelProps>(
+  ({ required = false, className = '', children, ...props }, ref) => {
+    const classes = [
+      'form-label',
+      required && 'form-label--required',
+      className,
+    ]
+      .filter(Boolean)
+      .join(' ')
+
+    return (
+      <label ref={ref} className={classes} {...props}>
+        {children}
+        {required && (
+          <span className="form-label__required" aria-hidden="true">
+            {' '}*
+          </span>
+        )}
+      </label>
+    )
+  }
+)
+
+Label.displayName = 'Label'
+