# V Stack

## Usage

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

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

`VStack` is `Stack` with the direction fixed to a column, so the same props work without repeating `direction`. `gap` takes a step from the spacing scale and is the only spacing the column needs: do not add margins to the children.

`vAlign` places the items along the column — `start`, `center`, `end`, `between`, `around`, or `evenly`. `hAlign` sets how the items sit against each other horizontally, and `justify` is a shorter alias for it.

```vue
<script setup lang="ts">
import { Heading } from '@astryx-vue/core/Heading'
import { VStack } from '@astryx-vue/core/Stack'
import { Text } from '@astryx-vue/core/Text'
</script>

<template>
  <VStack :gap="3">
    <Heading :level="5">
      Weekly Report
    </Heading>
    <Text type="body" color="secondary">
      VStack arranges its children in a vertical column.
    </Text>
  </VStack>
</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.

### Basic

A heading and paragraphs stacked vertically with a consistent gap. Use VStack whenever siblings should flow top to bottom with even spacing.

```vue
<script setup lang="ts">
import { Heading } from '@astryx-vue/core/Heading'
import { VStack } from '@astryx-vue/core/Stack'
import { Text } from '@astryx-vue/core/Text'
</script>

<template>
  <VStack :gap="3">
    <Heading :level="5">
      Weekly Report
    </Heading>
    <Text type="body" color="secondary">
      VStack arranges its children in a vertical column.
    </Text>
    <Text type="body" color="secondary">
      The gap prop controls the spacing between each item.
    </Text>
  </VStack>
</template>
```

## Props

`VStack` takes every `Stack` prop except `direction`, which is fixed to `vertical`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `align` | `StackCrossAlignment` | — | Horizontal alignment alias, so the prop reads the same as on `Stack`. Same as `hAlign`. |
| `as` | `string \| Component` | `'div'` | Element or component rendered at the root. |
| `gap` | `SpacingStep` | — | Space between adjacent items, using the spacing scale. |
| `height` | `number \| string` | — | Height of the column. Numbers are pixels, strings are used as they are. |
| `hAlign` | `StackCrossAlignment` | — | Horizontal cross-axis alignment of the items: `start`, `center`, `end`, or `stretch`. |
| `isScrollable` | `boolean` | `false` | Enables scrollable overflow. |
| `justify` | `StackMainAlignment` | — | Main-axis alignment alias. Mirrors CSS `justify-content`. |
| `maxWidth` | `number \| string` | — | Maximum width of the column. |
| `minHeight` | `number \| string` | — | Minimum height of the column. |
| `padding` | `SpacingStep` | — | Padding on both axes, using the spacing scale. |
| `paddingBlock` | `SpacingStep` | — | Block-axis padding. Overrides `padding` on this axis. |
| `paddingBlockEnd` | `SpacingStep` | — | Bottom padding. Overrides `paddingBlock` and `padding` on that edge only. |
| `paddingBlockStart` | `SpacingStep` | — | Top padding. Overrides `paddingBlock` and `padding` on that edge only. |
| `paddingInline` | `SpacingStep` | — | Inline-axis padding. Overrides `padding` on this axis. |
| `paddingInlineEnd` | `SpacingStep` | — | Inline-end padding (right in LTR). Overrides `paddingInline` and `padding` on that edge only. |
| `paddingInlineStart` | `SpacingStep` | — | Inline-start padding (left in LTR). Overrides `paddingInline` and `padding` on that edge only. |
| `vAlign` | `StackMainAlignment` | — | Vertical main-axis alignment of the items: `start`, `center`, `end`, `between`, `around`, or `evenly`. |
| `width` | `number \| string` | — | Width of the column. Numbers are pixels, strings are used as they are. |
| `wrap` | `StackWrap` | `'nowrap'` | Whether the items wrap onto another column: `nowrap`, `wrap`, or `wrap-reverse`. |

The helper types are shared with `Stack`:

```ts
type SpacingStep = 0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10
type StackMainAlignment = 'start' | 'center' | 'end' | 'between' | 'around' | 'evenly'
type StackCrossAlignment = 'start' | 'center' | 'end' | 'stretch'
type StackWrap = 'nowrap' | 'wrap' | 'wrap-reverse'
type StackSizeValue = number | string
type StackElement = Component | string
```

## Slots

- `default`: the items in the column.

## Native attributes

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