# Card

## Overview

_[Design to fill]_

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

## Anatomy

_[Design to fill]_

## Variants

Padding and the header divider are separate props, so they compose freely:

| Prop                         | Owns                       | Default |
| ---------------------------- | -------------------------- | ------- |
| `hasPadding` on `Card`       | Content padding            | `true`  |
| `hasBorder` on `Card.Header` | The header's bottom border | `false` |

A card can therefore have edge-to-edge content and still show the divider. When the content
is padded, it clears the divider automatically.

`isParent` cards draw the header border from their own styles, so `hasBorder` has no effect
on them.

The heading level and styling adapt to `isSecondary`:

| `isSecondary` | Title element | Use                                                     |
| ------------- | ------------- | ------------------------------------------------------- |
| `false`       | `<h3>`        | A top-level card (default).                             |
| `true`        | `<h4>`        | A card nested within another card or a lower-rank card. |

`isParent` adjusts a card that wraps other cards:

| `isParent` | Use                                                                   |
| ---------- | --------------------------------------------------------------------- |
| `false`    | A standalone card (default).                                          |
| `true`     | A container card that wraps nested child cards, styled to frame them. |

## Props / API

### `Card`

| Prop          | Type        | Default | Description                                                        |
| ------------- | ----------- | ------- | ------------------------------------------------------------------ |
| `hasPadding`  | `boolean`   | `true`  | Applies the default content padding. See Variants.                 |
| `isParent`    | `boolean`   | `false` | Renders the card in its parent style to frame nested child cards.  |
| `isSecondary` | `boolean`   | `false` | Renders the card in its secondary style and drops the title to h4. |
| `children`    | `ReactNode` | -       | The `Card.Header`, `Card.Content`, and `Card.Footer` slots.        |

Standard `<div>` attributes are forwarded via `...rest`.

### `Card.Header`

| Prop        | Type        | Default | Description                                                                                       |
| ----------- | ----------- | ------- | ------------------------------------------------------------------------------------------------- |
| `hasBorder` | `boolean`   | `false` | Draws the header's bottom border, and clears padded content of it. No effect on `isParent` cards. |
| `children`  | `ReactNode` | -       | Typically `Card.Header.Title` and `Card.Header.After`.                                            |

Renders a `<header>`. Standard `<header>` attributes are forwarded via `...rest`.

### `Card.Header.Title`

| Prop       | Type        | Default | Description                       |
| ---------- | ----------- | ------- | --------------------------------- |
| `disabled` | `boolean`   | `false` | Applies the disabled title style. |
| `children` | `ReactNode` | -       | The heading text.                 |

Renders an `<h3>`, or `<h4>` depending on if the parent card is `isSecondary`.

### `Card.Header.After`

| Prop       | Type        | Default | Description                                        |
| ---------- | ----------- | ------- | -------------------------------------------------- |
| `children` | `ReactNode` | -       | Trailing header content, e.g. actions or a status. |

Renders a `<div>`. Standard `<div>` attributes are forwarded via `...rest`.

### `Card.Content`

| Prop       | Type        | Default | Description    |
| ---------- | ----------- | ------- | -------------- |
| `children` | `ReactNode` | -       | The card body. |

Renders a `<div>`. Standard `<div>` attributes are forwarded via `...rest`.

### `Card.Footer`

| Prop       | Type        | Default | Description                     |
| ---------- | ----------- | ------- | ------------------------------- |
| `children` | `ReactNode` | -       | Supporting actions or metadata. |

Renders a `<footer>`. Standard `<footer>` attributes are forwarded via `...rest`.

The header, title, content, and footer slots must be rendered inside a `Card`. Using them outside throws.

## States

- Default (idle)
- Disabled title

## Code examples

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

export default function CardExample(): React.JSX.Element {
  return (
    <Card>
      <Card.Header hasBorder>
        <Card.Header.Title>Monthly report</Card.Header.Title>
        <Card.Header.After>Updated 2 hours ago</Card.Header.After>
      </Card.Header>
      <Card.Content>Your team resolved 42 issues this month.</Card.Content>
      <Card.Footer>View details</Card.Footer>
    </Card>
  );
}
```

A divider under the header while the content stays edge to edge:

```tsx
import { Card, Table } from "@mylighthouse/prism-react";

export default function FullBleedCardExample(): React.JSX.Element {
  return (
    <Card hasPadding={false}>
      <Card.Header hasBorder>
        <Card.Header.Title>Partners</Card.Header.Title>
      </Card.Header>
      <Card.Content>
        <Table bordered={false}>{/* rows */}</Table>
      </Card.Content>
    </Card>
  );
}
```

## A11y intent

_[Design to fill]_

- The card renders as an `<article>`, a self-contained region that assistive tech can navigate to and announce.
- `Card.Header`, `Card.Content`, and `Card.Footer` map to native `<header>`, body, and `<footer>` elements.
- `Card.Header.Title` renders a real heading (`<h3>`, or `<h4>` when secondary) so the card participates in the document outline. Keep heading levels sequential: use `isSecondary` for nested cards rather than skipping levels.
- The disabled title style is visual only; convey any genuinely unavailable state through the interactive controls it applies to, not by color alone (WCAG 1.4.1).