# ItemCard

A convenience wrapper around `Item type="card"` that provides a more natural card API by mapping `title` to the card heading and `children` to the card body.

## When to Use

- When displaying notification-style messages (success, error, warning, info)
- For status banners or alert cards
- When you need a card with a heading and body content

## Component

---

### Properties

- **`title`** `ReactNode` — Card heading (mapped to Item's `children`)
- **`children`** `ReactNode` — Card body content (mapped to Item's `description`)
- **`size`** `'xsmall' | 'small' | 'medium' | 'large' | 'xlarge'` (default: `medium`) — Size of the card
- **`icon`** `ReactNode` — Icon displayed before the content
- **`rightIcon`** `ReactNode` — Icon displayed after the content
- **`prefix`** `ReactNode` — Content rendered before the label
- **`suffix`** `ReactNode` — Content rendered after the label
- **`tooltip`** `string | boolean | object` (default: `true`) — Tooltip configuration: string for text, `true` for auto overflow tooltips, or object for advanced config
- **`hotkeys`** `string` — Keyboard shortcut displayed and triggered
- **`isSelected`** `boolean` (default: `false`) — Whether the card shows as selected with a checkbox
- **`isLoading`** `boolean` (default: `false`) — Show loading state, replacing an icon slot with a spinner
- **`actions`** `ReactNode` — Inline action buttons displayed on the right side
- **`autoHideActions`** `boolean` (default: `false`) — When true, actions are hidden by default and shown on hover or focus
- **`preserveActionsSpace`** `boolean` (default: `false`) — Preserve the actions width when hidden (only changes opacity, not layout)
- **`disableActionsFocus`** `boolean` (default: `false`) — Disable focus on action buttons by setting tabIndex to -1
- **`level`** `1 | 2 | 3 | 4 | 5 | 6` (default: `3`) — Heading level for the card title
- **`highlight`** `string` — String to highlight within children text
- **`highlightCaseSensitive`** `boolean` (default: `false`) — Whether highlight matching is case-sensitive

Inherits from [Item](./Item.md) (with `type="card"`).

### Base Properties

Supports [Base properties](../../BaseProperties.md)

### Styling Properties

#### styles

Inherits all styling from `Item`. See [Item documentation](./Item.md) for sub-elements and modifiers.

## Variants

### Sizes

- `medium` — Default size suitable for most use cases
- `large` — Larger size for prominent notifications
- `xlarge` — Extra large size for emphasized alerts

### Themes

Use the `theme` prop to apply a semantic color scheme:

- `default` — Standard card appearance
- `success` — Green theme for positive outcomes
- `danger` — Red theme for errors or destructive states
- `warning` — Amber theme for caution
- `note` — Violet theme for informational context

## Examples

### Basic Usage

```jsx
<ItemCard title="Info" icon={<IconInfoCircle />}>
  This is the card body content.
</ItemCard>
```

### Themed Cards

```jsx
<ItemCard title="Success" icon={<IconCheck />} theme="success">
  Operation completed successfully.
</ItemCard>

<ItemCard title="Error" icon={<IconAlertTriangle />} theme="danger">
  Something went wrong.
</ItemCard>
```

### With Actions

Use `ItemCard.Action` to add inline action buttons such as dismiss or close.

```jsx
<ItemCard
  title="Deployment Complete"
  icon={<IconCheck />}
  theme="success"
  actions={<ItemCard.Action icon={<IconX />} aria-label="Dismiss" />}
>
  Your changes are now live in production.
</ItemCard>
```

### Custom Heading Level

The `level` prop controls the semantic HTML heading tag (h1-h6) for the title. Default is `level={3}` (h3).

```jsx
<ItemCard title="Important Section" icon={<IconInfoCircle />} level={2}>
  This card's title renders as an h2 element.
</ItemCard>
```

## Accessibility

### Keyboard Navigation

- `Tab` - Moves focus to the component when focusable
- `Space/Enter` - Activates the component when used as a button

### Screen Reader Support

- Title renders as a semantic heading (h1-h6) via the `level` prop for proper document structure
- Inherits all accessibility features from `Item`

### ARIA Properties

- `aria-label` - Provides accessible label when no visible label exists

## Best Practices

1. **Do**: Use meaningful titles and body content
   ```jsx
   <ItemCard title="Deployment Complete" icon={<IconCheck />} theme="success">
     Your changes are now live in production.
   </ItemCard>
   ```

2. **Don't**: Use without a title
   ```jsx
   {/* Prefer using Item type="card" directly if you only need a description */}
   <ItemCard>Body only without a title</ItemCard>
   ```

## Related Components

- [Item](./Item.md) - The underlying component with full control over `type`, `children`, and `description`
