# BillCard

> Slug: `bill-card` · Category: Display

## When to use
- The primary billing summary on an account dashboard or "My T-Mobile" home — total due, due-date copy, AutoPay status, and primary actions.
- You need a structured card with eyebrow, total amount, billing copy, button group, and an optional embedded list.

## When NOT to use
- A non-billing summary tile -> `Tile` or `DisclosureCard`.
- A sticky checkout / cart summary -> `PurchaseSummaryBar`.
- The FCC broadband nutrition label -> `BroadbandFacts`.
- A simple key/value list -> `Lists` or `List`.

## Variants & decision tree
- AutoPay status drives the trailing status pill: `'on' | 'off' | 'paused' | 'none'`. Override pill copy via `autoPayStatusLabels`.
- Add a `tidbit` for short descriptive context above the header.
- Add a `sectionHeader` for an explicit titled card.
- Inverse / dark surface -> `inverse`.

## States
- `inverse` — dark-background.
- `autoPayType` — drives the status pill variant; "none" hides the pill.

## Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` | `'bill-card'` | Unique identifier. |
| `sectionHeader` | `SectionHeaderProps` | — | Optional header rendered above the card body. |
| **`eyebrow`** | `ReactNode` | — | Eyebrow above the bill total. |
| `tidbit` | `Omit<TidbitProps, 'elevated' \| 'inverse'>` | — | Tidbit above the header row. |
| **`billTotal`** | `{ amount: ReactNode }` | — | Main billing amount. |
| `billCopy` | `{ header?: string; body?: string; headerPrefix?: string }` | — | Bill copy block. |
| `buttons` | `ReactNode` | — | Slot for a `ButtonGroup`. |
| `lists` | `ReactNode` | — | Slot for an embedded `List` / `Lists`. |
| `autoPayType` | `'on' \| 'off' \| 'paused' \| 'none'` | `'on'` | AutoPay status variant. |
| `autoPayStatusLabels` | `Partial<{on,off,paused,none}>` | — | Custom status pill copy. |
| `inverse` | `boolean` | inherits | Dark-background styling. |

## Usage examples
```tsx
import { BillCard, ButtonGroup, Button, Lists, ListItemType } from 'arrow-react-bootstrap';

<BillCard
  eyebrow="Current bill"
  billTotal={{ amount: '$132.45' }}
  billCopy={{ header: 'Due Sept 18', body: 'On AutoPay — your card will be charged automatically.' }}
  autoPayType="on"
  buttons={
    <ButtonGroup>
      <Button variant="primary">View bill</Button>
      <Button variant="secondary">Manage AutoPay</Button>
    </ButtonGroup>
  }
  lists={
    <Lists
      listItems={[{ label: 'Payment history', type: ListItemType.NAV, href: '/history' }]}
    />
  }
/>
```

## Composition
- Place a `SectionHeader` via the prop, not as a sibling.
- Use `ButtonGroup` (column on mobile) or `ButtonGroupHorizontal` for the `buttons` slot.

## Accessibility
- The card is semantic: heading levels come from `sectionHeader`; the pill announces AutoPay state.
- Provide visible `billCopy.body` (not relying on color alone) for important context.

## Do / Don't
- Do: use this exclusively for the primary bill summary, one per page.
- Do: keep the amount in `billTotal.amount` — formatting is up to you.
- Don't: replicate AutoPay status with a separate `StatusLabel` — `autoPayType` already renders one.
- Don't: nest another `BillCard` inside.
