# ButtonTray

> Slug: `button-tray` · Category: Actions

## When to use
- Render a page- or section-level action bar with primary/secondary `Button`s and an optional helper link or supplementary content.
- Get a sensible responsive default: column+fill on small, row+hug on medium and up.
- Anchor a transactional flow (checkout, settings, modal footer).

## When NOT to use
- A simple action pair without supplementary content — use `ButtonGroup`.
- Inline action affordances within text — use `ButtonStyledAsLink`.
- Single button — render `Button` directly.

## Variants & decision tree
- Need a "Need help? Contact us" link beside the buttons -> pass `supplementaryAction` (`leadingText`, `linkLabel`, optional `linkUrl`).
- Need rich content (e.g., legal copy, policy text) -> pass `supplementaryContent`.
- Visual divider above the tray -> `hasDivider`.
- Custom inline styles on the wrapper -> `inlineStyles` (rare; prefer composition).

## States
- Inverse-aware (`inverse` prop or `ArrowThemeProvider`).
- Sets `data-has-divider` and `data-has-supplementary` on the root for CSS targeting.
- `supplementaryAction` renders an anchor when `linkUrl` is set, otherwise falls back to `ButtonStyledAsLink` (inline + monochrome).

## Props
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| **`children`** | `ReactNode` | — | One or more `Button`s — wrapped in a built-in `ButtonGroup`. |
| `supplementaryAction` | `{ leadingText?, linkLabel, linkUrl? }` | — | Help-link affordance. Renders `<a>` if `linkUrl` is set. |
| `supplementaryContent` | `ReactNode` | — | Free-form supplementary content block. |
| `hasDivider` | `boolean` | `false` | Show a top divider. |
| `inlineStyles` | `CSSProperties` | — | Inline styles on the root. |
| `inverse` | `boolean` | inherits | Dark-background styling. |
| `className` | `string` | — | Extra class names. |

## Usage examples
```tsx
import { Button, ButtonTray } from 'arrow-react-bootstrap';

// Checkout action tray with help link
<ButtonTray
  supplementaryAction={{
    leadingText: 'Need help?',
    linkLabel: 'Contact support',
    linkUrl: '/support',
  }}
>
  <Button variant="primary">Place order</Button>
  <Button variant="secondary">Back</Button>
</ButtonTray>

// Tray with supplementary policy block + divider
<ButtonTray
  hasDivider
  supplementaryContent={<small>By continuing, you accept our terms.</small>}
>
  <Button variant="primary">Continue</Button>
  <Button variant="secondary">Cancel</Button>
</ButtonTray>
```

## Composition
- Use inside `Modal` body footer, transactional page foot, or `FullPageInterruption`.
- Children may be `Button`, `ButtonStyledAsLink`, or `LinkStyledAsButton`.

## Accessibility
- Root `<div role="group">` groups the actions semantically.
- The internal `ButtonGroup` renders an accessible `<ul role="list">`.
- Keyboard order follows DOM order: supplementary content/action first, then buttons.

## Do / Don't
- Do: use for full-width primary action zones with optional support copy.
- Do: prefer `linkUrl` for actual navigation; omit it for actions handled in JS.
- Don't: stack multiple `ButtonTray`s; consolidate into one set.
- Don't: pass non-button children — keep `children` to action elements.
