import { Meta, Source, Canvas } from '@storybook/addon-docs/blocks';
import * as CriticalBannerStories from './CriticalBanner.story';

<Meta title="Prompts/CriticalBanner/Accessibility" tags={['new']} />

# Accessibility

Under the hood, `CriticalBanner` is marked as `role="region"` for a section of content that users might want to navigate to directly.

By default, it's labelled by the `title` and described by the `description`.

## Announcement Behavior

`CriticalBanner` is designed for critical messages that require immediate attention. It always uses **`aria-live="assertive"`** to immediately interrupt and announce changes to screen readers.

Unlike `InfoPrompt` which offers configurable politeness levels, `CriticalBanner` is always assertive because it communicates critical, time-sensitive information that users must be aware of immediately.

### What Gets Announced

The component intelligently announces only **visible content**, respecting the collapsed/expanded state:

- **Collapsed with title**: Announces title only (description is hidden)
- **Collapsed without title**: Announces description only (visible up to 2 lines)
- **Expanded**: Announces title, description, and action button labels (all visible)

<Source
  dark
  code={`
// Collapsed with title - announces: "Your account requires verification"
<CriticalBanner
  title="Your account requires verification"
  description="Please verify your identity to continue"
  action={{ label: "Verify now", onClick: handleVerify }}
  expanded={false}
  onToggle={handleToggle}
/>

// Expanded - announces: "Your account requires verification | Please verify your identity to continue | Verify now | Learn more"

<CriticalBanner
  title="Your account requires verification"
  description="Please verify your identity to continue"
  action={{ label: 'Verify now', onClick: handleVerify }}
  actionSecondary={{ label: 'Learn more', onClick: handleLearnMore }}
  expanded={true}
  onToggle={handleToggle}
/>

// Collapsed without title - announces: "Your verification is pending..."

<CriticalBanner
  description="Your verification is pending. We'll notify you once complete."
  expanded={false}
  onToggle={handleToggle}
/>
`}
/>

### When Announcements Trigger

Screen readers announce the banner content whenever:

- The banner first appears in the DOM
- The user toggles between collapsed and expanded states
- The content (title, description, or action labels) changes

## Reduced Motion

`CriticalBanner` respects the user's reduced motion preference. When reduced motion is on, the component does not show:

- the entry animation that reveals the banner from above when it first appears
- the collapse and expand animation used when the user toggles the banner content

The same content is still rendered and announced. Reduced motion only removes the visual movement.

## Media

Custom media icons should include their own accessibility attributes. Use the `title` prop on icons to provide accessible names for screen readers:

<Source
  dark
  code={`
import { Bank, AlertCircle } from '@transferwise/icons';

<CriticalBanner
  title="Bank connection required"
  description="Connect your bank account to continue"
  media={{ avatar: { asset: <Bank title="Bank account" /> } }}
  action={{ label: 'Connect now', onClick: handleConnect }}
  expanded={false}
  onToggle={handleToggle}
/>

<CriticalBanner
  title="Verification required"
  description="We need to verify your identity"
  media={{ avatar: { asset: <AlertCircle title="Alert" /> } }}
  action={{ label: "Start verification", onClick: handleVerify }}
  expanded={false}
  onToggle={handleToggle}
/>
`}
/>

Alternatively, you can use `media['aria-label']` to provide a label for custom images:

<Source
  dark
  code={`
<CriticalBanner
  title="Card blocked"
  description="Your card has been blocked for security reasons"
  media={{
    imgSrc: '/wise-card.svg',
    'aria-label': 'Wise debit card'
  }}
  action={{ label: "Unblock card", onClick: handleUnblock }}
  expanded={false}
  onToggle={handleToggle}
/>
`}
/>
