# PurchaseSummaryBar

> Slug: `purchase-summary-bar` · Category: Display

## When to use
- A persistent purchase / cart summary bar on a checkout, plan-builder, or configurator flow — shows monthly amount, today's amount, taxes treatment, and a "View summary" action.
- Mobile sticky-footer summaries that surface running totals before the user opens a full breakdown sheet.

## When NOT to use
- The primary monthly bill on a dashboard -> `BillCard`.
- A read-only line-item table -> `Table`.
- A small inline label or chip -> `StatusLabel` / `Tidbit`.

## Variants & decision tree
- Taxes already rolled into prices -> `taxesLabel="Including"`.
- Taxes shown separately or pre-tax prices -> `taxesLabel="Before"`.
- Inverse dark surface (e.g., on a hero) -> `inverse`.

## States
- `focused` — force-focus visual on the action button (design-review only).
- `inverse` — dark-background styling.

## Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| **`dueMonthlyAmount`** | `number` | — | Monthly amount due. |
| **`dueTodayAmount`** | `number` | — | Amount due today. |
| **`taxesLabel`** | `'Including' \| 'Before'` | — | How taxes are presented. |
| **`a11yLabel`** | `string` | — | Required region label. If empty the component renders nothing. |
| `icon` | `ReactNode` | — | Trigger icon (typically a plus-outlined SVG). |
| `onButtonClick` | `() => void` | — | Click handler for "View summary". |
| `inverse` | `boolean` | inherits | Dark-background styling. |
| `focused` | `boolean` | `false` | Force-focus state for design review. |

## Usage examples
```tsx
import { PurchaseSummaryBar } from 'arrow-react-bootstrap';

<PurchaseSummaryBar
  a11yLabel="Cart summary"
  dueMonthlyAmount={129.99}
  dueTodayAmount={0}
  taxesLabel="Including"
  icon={<svg viewBox="0 0 24 24"><path d="M12 5v14M5 12h14" /></svg>}
  onButtonClick={openCartDrawer}
/>
```

## Composition
- Pair with a full breakdown surface (`Modal`, drawer, or detail page) opened by `onButtonClick`.
- Place at the bottom of the viewport (sticky) on mobile checkout flows.

## Accessibility
- The bar is a labelled `<div>` region — pass a meaningful `a11yLabel`.
- The action renders a real `<button>`; do not wrap it in an anchor.

## Do / Don't
- Do: keep the bar visible across the entire purchase flow until checkout completes.
- Do: format amounts to your locale before passing them in (the component receives raw numbers).
- Don't: hide the taxes treatment — the `taxesLabel` is regulatory-friendly copy.
- Don't: render two `PurchaseSummaryBar`s on the same page.
