# Item

Displays a flexible content row with optional media, title, description, actions, header, and footer.

Use Item when you need to present content such as profile summaries, settings rows, list links, media rows, or menu-like entries without introducing form-field semantics.

## Import

```ts
import {
  ItemActionsComponent,
  ItemComponent,
  ItemContentComponent,
  ItemDescriptionComponent,
  ItemFooterComponent,
  ItemGroupComponent,
  ItemHeaderComponent,
  ItemMediaComponent,
  ItemSeparatorComponent,
  ItemTitleComponent,
} from '@edsis/component/item';
```

## Usage

Use `<Item>` for the default host element. When the row should behave like a native link or button, apply `[Item]` directly to the semantic host instead of relying on React-style `asChild` composition.

```html
<Item variant="outline">
  <ItemMedia variant="icon">
    <svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
      <path d="M12 5v14" />
      <path d="M5 12h14" />
    </svg>
  </ItemMedia>

  <ItemContent>
    <ItemTitle>Security alert</ItemTitle>
    <ItemDescription>New login detected from an unknown device.</ItemDescription>
  </ItemContent>

  <ItemActions>
    <button Button variant="outline" size="sm" type="button">Review</button>
  </ItemActions>
</Item>
```

## Composition

The Angular structure follows the shadcn Item information architecture while translating React-specific patterns to Angular selectors and semantic hosts.

```text
ItemGroup
└── Item
    ├── ItemHeader
    ├── ItemMedia
    ├── ItemContent
    │   ├── ItemTitle
    │   └── ItemDescription
    ├── ItemActions
    └── ItemFooter
```

## Common patterns

### Variants

Use `variant="outline"` for bordered rows, `variant="muted"` for low-emphasis containers, and the default variant when the item should blend into the surrounding surface.

```html
<div class="flex max-w-md flex-col gap-4">
  <Item class="px-4 py-3">
    <ItemContent>
      <ItemTitle>Default item</ItemTitle>
      <ItemDescription>Transparent background with no border.</ItemDescription>
    </ItemContent>
  </Item>

  <Item variant="outline">
    <ItemContent>
      <ItemTitle>Outline item</ItemTitle>
      <ItemDescription>Bordered treatment for cards and settings rows.</ItemDescription>
    </ItemContent>
  </Item>

  <Item variant="muted">
    <ItemContent>
      <ItemTitle>Muted item</ItemTitle>
      <ItemDescription>Soft background for secondary content.</ItemDescription>
    </ItemContent>
  </Item>
</div>
```

### Media modes

`ItemMedia` supports three common shadcn-style treatments.

- Default media for avatars or custom projected content.
- `variant="icon"` for compact icon chips.
- `variant="image"` for fixed-size artwork or thumbnails.

```html
<Item variant="outline">
  <ItemMedia>
    <Avatar>
      <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
      <AvatarFallback>CN</AvatarFallback>
    </Avatar>
  </ItemMedia>

  <ItemContent>
    <ItemTitle>shadcn</ItemTitle>
    <ItemDescription>Example avatar content</ItemDescription>
  </ItemContent>
</Item>
```

### Size

Set `size` on the root item to scale title and description typography plus the icon and image media wrappers.

```html
<Item variant="outline" size="default">...</Item>
<Item variant="outline" size="sm">...</Item>
<Item variant="outline" size="xs">...</Item>
```

### Group with separators

Use `ItemGroup` with `ItemSeparator` when you need a vertically stacked list of related rows.

```html
<ItemGroup class="max-w-sm gap-0 rounded-xl border border-border">
  <Item class="px-4 py-3">
    <ItemContent>
      <ItemTitle>shadcn</ItemTitle>
      <ItemDescription>shadcn@vercel.com</ItemDescription>
    </ItemContent>
  </Item>
  <ItemSeparator />
  <Item class="px-4 py-3">
    <ItemContent>
      <ItemTitle>evilrabbit</ItemTitle>
      <ItemDescription>evilrabbit@vercel.com</ItemDescription>
    </ItemContent>
  </Item>
</ItemGroup>
```

### Link host

shadcn React uses `asChild` for anchors. In Angular, put `[Item]` on the anchor directly.

```html
<a Item href="/dashboard" variant="outline">
  <ItemContent>
    <ItemTitle>Dashboard</ItemTitle>
    <ItemDescription>Overview of your account and activity.</ItemDescription>
  </ItemContent>
  <ItemActions>
    <svg
      aria-hidden="true"
      viewBox="0 0 24 24"
      fill="none"
      stroke="currentColor"
      stroke-width="2"
      class="size-4"
    >
      <path d="m9 18 6-6-6-6" />
    </svg>
  </ItemActions>
</a>
```

### Dropdown composition

The shadcn Item dropdown example maps cleanly to the local menu primitives. Render `Item` inside a `MenuItem` when you want denser menu rows.

```html
<button Button variant="outline" [MenuTrigger]="peopleMenu">Select person</button>

<ng-template MenuContent #peopleMenu="MenuContent">
  <MenuSurface class="w-64">
    <MenuLabel>People</MenuLabel>
    <MenuSeparator />

    <button MenuItem class="p-0">
      <Item size="xs" class="w-full p-2">
        <ItemContent>
          <ItemTitle>shadcn</ItemTitle>
          <ItemDescription>shadcn@vercel.com</ItemDescription>
        </ItemContent>
      </Item>
    </button>
  </MenuSurface>
</ng-template>
```

## API reference

### `ItemComponent`

| Input     | Type                                | Default     |
| --------- | ----------------------------------- | ----------- |
| `variant` | `'default' \| 'outline' \| 'muted'` | `'default'` |
| `size`    | `'default' \| 'sm' \| 'xs'`         | `'default'` |
| `class`   | `string`                            | `''`        |

### `ItemMediaComponent`

| Input     | Type                             | Default     |
| --------- | -------------------------------- | ----------- |
| `variant` | `'default' \| 'icon' \| 'image'` | `'default'` |
| `class`   | `string`                         | `''`        |

### Parts

- `ItemGroup` arranges related items in a vertical stack.
- `ItemSeparator` renders a full-width divider line between grouped rows.
- `ItemHeader` and `ItemFooter` span the full width of the item.
- `ItemActions` stays aligned to the trailing edge with logical spacing, so RTL layouts remain correct.

## Styling and theming

The outline variant uses `border-border` instead of inheriting border color from text, which keeps dividers and item shells consistent with the rest of the library theme.

Pass `class` to the root or individual parts to tune spacing, borders, width, image treatment, or flex behavior. `ItemContent` can be reused for secondary metadata by overriding it with classes such as `flex-none basis-auto items-end text-right`.

Powered by `class-variance-authority`. Re-exports: `itemVariants`, `itemMediaVariants`, `ItemVariant`, `ItemSize`, `ItemMediaVariant`.

## Accessibility

- Use a semantic anchor or button host when the row is interactive.
- Keep decorative icons and artwork `aria-hidden` or use empty `alt` text when nearby text already names the content.
- Do not place nested interactive controls inside an interactive anchor host. When the row contains independent actions, keep the host non-interactive and place buttons inside `ItemActions`.

## Keyboard interactions

- Non-interactive items are not focusable.
- Anchor and button hosts keep native Tab, Enter, and Space behavior.
- Embedded controls inside `ItemActions` follow the natural DOM tab order.
- When composed inside `MenuItem`, keyboard behavior comes from the menu primitives.

## Angular notes

- There is no `asChild` input in Angular. Use semantic hosts such as `<a Item>` or `<button Item>` directly.
- `size` and `variant` are Angular `input()` values on the root item.
- `ItemMedia` reads the parent item size automatically so icon and image wrappers stay in sync.
- Use `Field` or the local form primitives when the row contains an actual form control such as a checkbox, radio, input, or select.

## Source parity

This Angular implementation follows the shadcn Item information architecture and examples while translating React `asChild` composition to semantic hosts and mapping the dropdown example to the existing Angular menu primitives.