# Banner

## Overview

_[Design to fill]_

- **When to use**: _[Design to fill]_
- **When not to use**: _[Design to fill]_

## Anatomy

_[Design to fill]_

## Variants

| Prop          | Effect                                                                                      |
| ------------- | ------------------------------------------------------------------------------------------- |
| `bannerStyle` | Sets the semantic style: `info`, `success`, `warning`, `critical`, `intelligence`, `brand`. |
| `position`    | Sets the layout treatment: `top`, `bottom`, `island`.                                       |
| `isOneLine`   | Renders a condensed single-line layout instead of the default full-width layout.            |
| `isLoading`   | Swaps `Banner.Icon` for a loading spinner and puts `Banner.Button` into its loading state.  |

## Props / API

Banner is a compound component. The root `Banner` provides context (`bannerStyle`, `fullWidth`, `isLoading`) consumed by its sub-components.

### `Banner`

| Prop          | Type                                                                          | Default  | Description                                                     |
| ------------- | ----------------------------------------------------------------------------- | -------- | --------------------------------------------------------------- |
| `bannerStyle` | `"info" \| "success" \| "warning" \| "critical" \| "intelligence" \| "brand"` | `"info"` | Semantic/visual style of the banner.                            |
| `position`    | `"top" \| "bottom" \| "island"`                                               | `"top"`  | Layout treatment.                                               |
| `isOneLine`   | `boolean`                                                                     | -        | Condensed single-line layout.                                   |
| `isLoading`   | `boolean`                                                                     | -        | Shows a spinner in place of the icon and loads `Banner.Button`. |

Extends `HTMLAttributes<HTMLDivElement>`. Standard attributes are forwarded to the underlying `<section>` via `...rest`.

The `BANNER_STYLE` and `BANNER_POSITION` constants are exported for referencing values by name.

### `Banner.Icon`

| Prop   | Type       | Default | Description                                            |
| ------ | ---------- | ------- | ------------------------------------------------------ |
| `icon` | `IconName` | -       | Icon to render, colored by the banner's `bannerStyle`. |

When the root banner's `isLoading` is set, a `LoadingSpinner` is rendered instead of the icon. Both the icon and spinner are `aria-hidden="true"`.

### `Banner.Content`

Layout wrapper for the banner body. Accepts `children`.

### `Banner.ContentText`

Groups the title and message. Accepts `children`.

### `Banner.Title`

Renders `children` as an `<h2>`.

### `Banner.Message`

Renders `children` as a `<p>`.

### `Banner.Footer`

Renders a `<footer>` for actions (buttons, checkbox). Extends `HTMLAttributes<HTMLDivElement>`.

### `Banner.Button`

| Prop         | Type                                                   | Default            | Description               |
| ------------ | ------------------------------------------------------ | ------------------ | ------------------------- |
| `buttonType` | `ButtonType`                                           | Derived from style | Button style.             |
| `onClick`    | `(event: React.MouseEvent<HTMLButtonElement>) => void` | -                  | Click handler (required). |
| `iconBefore` | `IconName`                                             | -                  | Icon before the label.    |
| `iconAfter`  | `IconName`                                             | -                  | Icon after the label.     |
| `disabled`   | `boolean`                                              | -                  | Disables the button.      |
| `children`   | `React.ReactNode`                                      | -                  | Button label.             |

Wraps the [Button](./button.md) component. Inherits `isLoading` from the banner context.

### `Banner.CloseButton`

| Prop      | Type                                         | Default | Description               |
| --------- | -------------------------------------------- | ------- | ------------------------- |
| `onClick` | `React.MouseEventHandler<HTMLButtonElement>` | -       | Click handler (required). |

Renders a ghost, small [Button](./button.md) with a `cross` icon and a built-in `aria-label="Close"`.

### `Banner.Checkbox`

| Prop       | Type                                   | Default | Description               |
| ---------- | -------------------------------------- | ------- | ------------------------- |
| `checked`  | `boolean`                              | -       | Controlled checked state. |
| `onChange` | `ChangeEventHandler<HTMLInputElement>` | -       | Change handler.           |
| `disabled` | `boolean`                              | -       | Disables the checkbox.    |
| `children` | `React.ReactNode`                      | -       | Label content.            |

Wraps the [Checkbox](./checkbox.md) in a `<label>` alongside label text.

### `Banner.Link`

| Prop   | Type      | Default | Description                               |
| ------ | --------- | ------- | ----------------------------------------- |
| `href` | `string`  | -       | Destination URL (required).               |
| `icon` | `boolean` | -       | Appends an `aria-hidden` `link-out` icon. |

Extends `AnchorHTMLAttributes<HTMLAnchorElement>`. Renders a real `<a>`.

### `Banner.LinkButton`

| Prop       | Type                                                                                         | Default | Description         |
| ---------- | -------------------------------------------------------------------------------------------- | ------- | ------------------- |
| `onClick`  | `(e: React.MouseEvent<HTMLButtonElement> \| React.KeyboardEvent<HTMLButtonElement>) => void` | -       | Handler (required). |
| `icon`     | `boolean`                                                                                    | -       | Appends an icon.    |
| `children` | `React.ReactNode`                                                                            | -       | Label content.      |

Extends `ButtonHTMLAttributes<HTMLButtonElement>`. Renders a real `<button>` styled like a link.

## States

- Default (idle)
- Loading

## Code examples

```tsx
import { Banner } from "@mylighthouse/prism-react";

export default function BannerExample(): React.JSX.Element {
  return (
    <Banner bannerStyle="info" position="island">
      <Banner.Icon icon="circle-information-filled" />
      <Banner.Content>
        <Banner.ContentText>
          <Banner.Title>Heads up</Banner.Title>
          <Banner.Message>
            This is an example banner message with actions.{" "}
            <Banner.Link href="https://mylighthouse.com" icon>
              Learn more
            </Banner.Link>
          </Banner.Message>
        </Banner.ContentText>
        <Banner.Footer>
          <Banner.Button onClick={() => console.log("Primary action")}>
            Primary action
          </Banner.Button>
          <Banner.Button
            buttonType="secondary"
            onClick={() => console.log("Secondary action")}
          >
            Secondary action
          </Banner.Button>
        </Banner.Footer>
      </Banner.Content>
      <Banner.CloseButton onClick={() => console.log("Closed")} />
    </Banner>
  );
}
```

## A11y intent

_[Design to fill]_

- The banner renders a semantic `<section>`, `Banner.Title` renders an `<h2>` and `Banner.Message` renders a `<p>` for proper document structure.
- `Banner.Icon` and its loading spinner are `aria-hidden="true"`, so meaning must not rely on the icon alone: pair `bannerStyle` with a clear title/message.
- `Banner.CloseButton` ships a built-in `aria-label="Close"` so the icon-only control has an accessible name.
- `Banner.Link` renders a real `<a>` and `Banner.LinkButton` a real `<button>`, keeping keyboard and AT semantics correct.
- `Banner.Checkbox` wraps a native checkbox in a `<label>`, so its state and purpose are announced.

## Cross-references

- **[Button](./button.md)**: used by `Banner.Button` and `Banner.CloseButton` for actions.
- **[Checkbox](./checkbox.md)**: used by `Banner.Checkbox` for actions.