# Stack Item

## Usage

Stack arranges items in a row or column with consistent spacing. Use the gap prop to control the space between items.

```ts
import { StackItem } from '@astryx-vue/core/Stack'
```

`StackItem` wraps one child of a `Stack` when that child needs its own sizing rule. `size` is `static` by default, which keeps the intrinsic size; `fill` lets the item take the space the other items leave over. `crossAlignSelf` overrides the stack's cross-axis alignment for this one item, and `isScrollable` turns the item into a scroll region of its own.

The wrapper also applies the flex reset — `min-width` and `min-height` of zero — so a long value inside cannot widen the row it sits in.

```vue
<script setup lang="ts">
import { HStack, StackItem } from '@astryx-vue/core/Stack'
</script>

<template>
  <HStack :gap="3">
    <StackItem size="static">
      Static
    </StackItem>
    <StackItem size="fill">
      Fills remaining space
    </StackItem>
  </HStack>
</template>
```

### Anatomy

- **Stack container**: Layout container that arranges content along one flex axis.
- **Item**: Optional StackItem wrapper that controls one item in the stack.
- **Content**: Caller-supplied content rendered by a Stack or StackItem.

## Best practices

| Guidance | Practices |
| --- | --- |
| Do | Use the gap prop for spacing between items; don't add margins manually. |
| Do | Use StackItem with `size="fill"` to make one item stretch and fill the leftover space. |
| Don't | Nest stacks inside stacks; try `wrap="wrap"` first to let items flow to the next line. |

## Examples

Common configurations, variations, and states.

### Fill

A static-width item next to one that fills the remaining space. Wrap stack children in StackItem when an item needs explicit sizing control.

```vue
<script setup lang="ts">
import { Card } from '@astryx-vue/core/Card'
import { HStack, StackItem } from '@astryx-vue/core/Stack'
import { Text } from '@astryx-vue/core/Text'
</script>

<template>
  <HStack :gap="3">
    <StackItem size="static">
      <Card>
        <Text type="supporting" color="secondary">
          Static
        </Text>
      </Card>
    </StackItem>
    <StackItem size="fill">
      <Card>
        <Text type="supporting" color="secondary">
          Fills remaining space
        </Text>
      </Card>
    </StackItem>
  </HStack>
</template>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `as` | `string \| Component` | `'div'` | Element or component rendered at the root. |
| `crossAlignSelf` | `StackCrossAlignment` | — | Overrides the parent stack's cross-axis alignment for this item: `start`, `center`, `end`, or `stretch`. |
| `isScrollable` | `boolean` | `false` | Enables scrollable overflow. The wrapper already resets the flex minimum size, so `size="fill"` together with `isScrollable` is a complete scroll region. |
| `size` | `'static' \| 'fill'` | `'static'` | `static` keeps the natural size; `fill` expands to consume the space the other items leave over. |

`StackCrossAlignment` accepts these values:

```ts
type StackCrossAlignment = 'start' | 'center' | 'end' | 'stretch'
```

## Slots

- `default`: the content of the item.

## Native attributes

The root element receives HTML attributes, `aria-*` attributes, `data-*` attributes, `class`, and `style`. `class` is merged with the component's own classes.