import { Meta } from "@storybook/addon-docs/blocks";

<Meta title="FP.REACT Components/Alert/Readme" />

# Alert Component

## Summary

The `Alert` component is a highly customizable and accessible component for displaying status messages with different severity levels. It supports multiple severity types (default, info, success, warning, error), visual variants, auto-dismiss functionality, exit animations, and optional action buttons. **Fully WCAG 2.1 Level AA compliant** with comprehensive accessibility features.

## Features

- **Multiple Severity Levels** - Info, success, warning, error, and default states with matching visual indicators
- **Visual Variants** - Choose from outlined (default), filled, or soft styles
- **Flexible Content** - Simple text mode or complex layouts with the `contentType` prop
- **Exit Animations** - Smooth fade-out and slide-up transitions using CSS
- **Auto-Dismiss with Pause** - Automatic dismissal that pauses on hover/focus (WCAG 2.2.1)
- **Keyboard Support** - ESC key dismisses dismissible alerts
- **Custom Actions** - Add custom action buttons alongside the message
- **Icon Customization** - Adjust icon size or hide icons completely
- **Configurable Headings** - Maintain proper document hierarchy with `titleLevel` prop
- **Auto-Focus** - Automatically focus critical alerts for accessibility
- **Screen Reader Support** - Severity announcements and proper ARIA attributes
- **WCAG 2.1 Level AA Compliant** - Meets all accessibility standards including color contrast, touch targets, and focus indicators

## Props

```tsx
export type AlertProps = {
  /**
   * Whether the alert is open.
   */
  open: boolean;

  /**
   * The severity level of the alert.
   * @default "default"
   */
  severity?: "default" | "info" | "success" | "warning" | "error";

  /**
   * The main message content.
   */
  children: React.ReactNode;

  /**
   * Optional title for the alert.
   */
  title?: string;

  /**
   * Whether the alert can be dismissed.
   * @default false
   */
  dismissible?: boolean;

  /**
   * Callback when alert is dismissed.
   */
  onDismiss?: () => void;

  /**
   * Size of the icon in pixels.
   * @default 24
   */
  iconSize?: number;

  /**
   * Whether to hide the icon.
   */
  hideIcon?: boolean;

  /**
   * Additional props to pass to the Icon component.
   */
  iconProps?: IconProps;

  /**
   * Duration in milliseconds before the alert automatically dismisses.
   * Set to 0 or undefined to disable auto-dismiss.
   * @default undefined
   */
  autoHideDuration?: number;

  /**
   * Whether to pause auto-dismiss when hovered or focused.
   * Complies with WCAG 2.2.1 (Timing Adjustable).
   * @default true
   */
  pauseOnHover?: boolean;

  /**
   * Semantic heading level for the title (2-6).
   * When undefined, uses default heading level.
   * Use this to maintain proper document hierarchy.
   * @default 3
   */
  titleLevel?: 2 | 3 | 4 | 5 | 6;

  /**
   * Custom action buttons to display in the alert.
   */
  actions?: React.ReactNode;

  /**
   * Whether to automatically focus the alert when it becomes visible.
   * Useful for critical alerts that require immediate attention.
   * @default false
   */
  autoFocus?: boolean;

  /**
   * Visual variant of the alert.
   * - outlined: Border with lighter background (default)
   * - filled: Solid colored background
   * - soft: No border, subtle background
   * @default "outlined"
   */
  variant?: "outlined" | "filled" | "soft";

  /**
   * Content rendering mode for alert children.
   * - "text": Wraps children in paragraph tag (default, for simple text)
   * - "node": Renders children directly (for complex layouts, lists, or custom components)
   * @default "text"
   */
  contentType?: "text" | "node";
} & React.ComponentProps<typeof UI>;
```

## Technical Details

### Component Architecture

The `Alert` component uses the `UI` component for rendering and includes:

- **Animation State Management** - Separate `isVisible` and `shouldRender` states for smooth exit animations
- **Auto-Dismiss Timer** - Automatic cleanup of setTimeout when component unmounts or alert is dismissed
- **Keyboard Event Handler** - ESC key support with proper cleanup
- **Memoized Icons** - Performance-optimized icon rendering using `useMemo`
- **ARIA Attributes** - Proper `role="alert"`, `aria-live`, and `aria-atomic` for screen readers

### Accessibility Features (WCAG 2.1 Level AA Compliant)

- **ARIA Roles** - Uses `role="alert"` for proper screen reader announcements
- **Live Regions** - `aria-live="polite"` for info/success/warning, `aria-live="assertive"` for errors
- **Screen Reader Announcements** - Visually hidden severity text ("Error:", "Warning:", etc.) for context
- **Keyboard Navigation** - ESC key dismisses alerts when `dismissible` is true
- **Focus Management** - Optional auto-focus for critical alerts via `autoFocus` prop with visible focus indicators
- **Semantic HTML** - Configurable heading levels (h2-h6) via `titleLevel` prop for proper document hierarchy
- **Flexible Content Structure** - `contentType` prop enables semantic HTML for complex content (lists, multiple paragraphs)
- **Touch Target Compliance** - Dismiss button meets 44×44px minimum size (WCAG 2.5.5)
- **Pause on Interaction** - Auto-dismiss pauses when alert is hovered or focused (WCAG 2.2.1)
- **Color Contrast** - All text meets 4.5:1 minimum contrast ratio (WCAG 1.4.3)
- **Focus Indicators** - 2px visible outline for keyboard navigation (WCAG 2.4.7)
- **Reduced Motion Support** - Respects `prefers-reduced-motion` user preference

### Animation Behavior

Exit animations use CSS transitions (300ms duration) for smooth fade-out and slide-up effects. The component:

1. Sets `isVisible` to `false` when dismissed
2. Waits for CSS transition to complete (300ms)
3. Removes component from DOM by setting `shouldRender` to `false`
4. Calls `onDismiss` callback after animation completes

## Usage Examples

### Basic Usage

```tsx
import Alert from "#components/alert";

<Alert open={true} severity="info">
  This is an info alert.
</Alert>;
```

### With Title and Dismissal

```tsx
import Alert from "#components/alert";

<Alert
  open={true}
  severity="error"
  title="Error"
  dismissible={true}
  onDismiss={() => console.log("Alert dismissed")}
>
  This is an error alert with a title and dismiss button.
</Alert>;
```

### Auto-Dismiss Alert

Automatically dismiss the alert after 5 seconds:

```tsx
import Alert from "#components/alert";

<Alert
  open={true}
  severity="success"
  title="Success"
  autoHideDuration={5000}
  onDismiss={() => console.log("Auto-dismissed after 5 seconds")}
>
  Your changes have been saved successfully!
</Alert>;
```

### Alert with Custom Actions

Add custom action buttons for user interactions:

```tsx
import Alert from "#components/alert";
import Button from "#components/buttons/button";

<Alert
  open={true}
  severity="warning"
  title="Unsaved Changes"
  actions={
    <>
      <Button size="sm" onClick={handleSave}>
        Save
      </Button>
      <Button size="sm" onClick={handleDiscard}>
        Discard
      </Button>
    </>
  }
>
  You have unsaved changes that will be lost.
</Alert>;
```

### Visual Variants

Use different visual styles for the alert:

```tsx
import Alert from "#components/alert";

// Outlined (default) - border with lighter background
<Alert open={true} variant="outlined" severity="info">
  Outlined variant with border
</Alert>;

// Filled - solid colored background
<Alert open={true} variant="filled" severity="success">
  Filled variant with solid background
</Alert>;

// Soft - no border, subtle background
<Alert open={true} variant="soft" severity="warning">
  Soft variant with subtle styling
</Alert>;
```

### Hidden Icon

Hide the severity icon when needed:

```tsx
import Alert from "#components/alert";

<Alert open={true} hideIcon severity="info">
  This alert has no icon.
</Alert>;
```

### Custom Icon Size

Adjust the icon size:

```tsx
import Alert from "#components/alert";

<Alert open={true} iconSize={48} severity="error">
  This alert has a larger icon (48px).
</Alert>;
```

### Critical Alert with Auto-Focus

Automatically focus critical alerts for accessibility:

```tsx
import Alert from "#components/alert";

<Alert
  open={true}
  severity="error"
  title="Critical Error"
  autoFocus={true}
  dismissible={true}
>
  A critical error occurred. Please contact support.
</Alert>;
```

### Complex Content with Lists

Use `contentType="node"` for complex layouts with lists:

```tsx
import Alert from "#components/alert";

<Alert
  open={true}
  severity="warning"
  title="Action Required"
  contentType="node"
  dismissible={true}
>
  <p>Please complete the following security steps:</p>
  <ul>
    <li>Review your recent login activity</li>
    <li>Update your password</li>
    <li>Enable two-factor authentication</li>
  </ul>
</Alert>;
```

### Multiple Paragraphs

Render multiple paragraphs for detailed messages:

```tsx
import Alert from "#components/alert";

<Alert
  open={true}
  severity="info"
  title="Privacy Policy Update"
  contentType="node"
  dismissible={true}
>
  <p>
    We've made significant improvements to our privacy policy to better
    protect your data and give you more control.
  </p>
  <p>
    Please review the changes. The new policy takes effect January 1, 2026.
  </p>
</Alert>;
```

### Custom Layout with contentType

Create custom layouts for rich alert content:

```tsx
import Alert from "#components/alert";

<Alert
  open={true}
  severity="success"
  title="Deployment Complete"
  contentType="node"
  dismissible={true}
>
  <p>Your application has been deployed successfully!</p>
  <div style={{ display: 'flex', gap: '1rem', marginTop: '0.5rem' }}>
    <div><strong>Build #:</strong> 1234</div>
    <div><strong>Duration:</strong> 2m 34s</div>
    <div><strong>Status:</strong> Live</div>
  </div>
</Alert>;
```

### Configurable Heading Hierarchy

Maintain proper document structure with `titleLevel`:

```tsx
import Alert from "#components/alert";

// In a section with h2 heading
<section>
  <h2>Account Settings</h2>
  <Alert
    open={true}
    severity="info"
    title="Email Verification Required"
    titleLevel={3}
    dismissible={true}
  >
    Please verify your email address to continue.
  </Alert>
</section>;
```

### Advanced Example

Combine multiple features:

```tsx
import Alert from "#components/alert";
import Button from "#components/buttons/button";

<Alert
  open={true}
  severity="warning"
  title="Session Expiring Soon"
  variant="filled"
  autoFocus={true}
  dismissible={true}
  autoHideDuration={30000}
  onDismiss={() => console.log("Alert dismissed")}
  iconSize={40}
  actions={
    <Button size="sm" onClick={handleExtendSession}>
      Extend Session
    </Button>
  }
>
  Your session will expire in 5 minutes. Save your work or extend your session.
</Alert>;
```

## Keyboard Interactions

| Key   | Action                                         |
| ----- | ---------------------------------------------- |
| `ESC` | Dismisses the alert (when `dismissible=true`)  |
| `Tab` | Moves focus to dismiss button or action buttons|

## Visual Variants

### Outlined (Default)
- Border with background color
- Icon in severity color
- Default variant for most use cases

### Filled
- Solid background in severity color
- White text and icon
- High visual emphasis
- Best for critical alerts

### Soft
- No border
- Subtle background color
- Low visual weight
- Best for informational messages

## Best Practices

### When to Use Each Severity

- **Default** - Generic notifications without specific status
- **Info** - Informational messages that don't require action
- **Success** - Confirmation of successful actions
- **Warning** - Alerts requiring attention but not critical
- **Error** - Critical errors requiring immediate attention

### Auto-Dismiss Guidelines

- Use for **success** and **info** alerts (non-critical)
- Avoid for **error** and **warning** alerts (user should explicitly dismiss)
- Recommended duration: 5000-7000ms for readable messages
- Always provide `onDismiss` callback for cleanup

### Accessibility Guidelines

- Use `autoFocus` only for critical errors that require immediate attention
- Always provide meaningful titles for better screen reader experience
- Ensure action buttons have descriptive labels
- Test with keyboard-only navigation

### Action Buttons

- Limit to 2-3 action buttons for clarity
- Use small button sizes (`size="sm"`)
- Primary action first, secondary actions after
- Always include dismiss option for dismissible alerts

### Content Type Selection

Choose the appropriate `contentType` based on your content:

**Use `contentType="text"` (default) when:**
- Displaying simple, single-line or single-paragraph text
- Content is purely text without HTML structure
- You want automatic semantic paragraph wrapping

**Use `contentType="node"` when:**
- Including lists (ul, ol) in your alert
- Rendering multiple paragraphs with different styling
- Using custom components or complex layouts
- Need fine-grained control over HTML structure
- Content includes interactive elements

### Heading Hierarchy

Maintain proper document structure with `titleLevel`:

- Always consider the parent heading level
- Use `titleLevel={2}` for alerts in main content areas
- Use `titleLevel={3}` for alerts within sections
- Use `titleLevel={4}` or higher for nested subsections
- Screen readers use heading levels for navigation

**Example:**
```tsx
<h1>Dashboard</h1>
  <h2>Notifications</h2>
    <Alert titleLevel={3} title="New Message">...</Alert>
  <h2>Settings</h2>
    <Alert titleLevel={3} title="Update Available">...</Alert>
```

## Additional Notes

- **WCAG 2.1 Level AA Compliant** - Meets all accessibility standards including color contrast, touch targets, focus indicators, and screen reader support
- **Flexible Content Rendering** - `contentType` prop supports both simple text and complex HTML structures while maintaining semantic correctness
- **Screen Reader Optimized** - Visually hidden severity text provides context ("Error:", "Warning:", etc.) for screen reader users
- **Pause on Interaction** - Auto-dismiss automatically pauses when users hover or focus the alert (WCAG 2.2.1)
- **Semantic Heading Levels** - `titleLevel` prop enables proper document hierarchy for accessibility and SEO
- **Exit Animations** - GPU-accelerated CSS transitions with automatic cleanup and reduced-motion support
- **Performance Optimized** - Severity icons are memoized, timers auto-cleanup on unmount
- **Keyboard Accessible** - ESC key dismissal with proper event listener cleanup
- **Touch-Friendly** - Dismiss button meets 44×44px minimum touch target size
- **Focus Management** - Visible 2px focus indicators for keyboard navigation
- **Custom Icons** - Fine-grained icon control through `iconProps` for advanced use cases
- **Backward Compatible** - All new features have sensible defaults and zero breaking changes