# Section

## Usage

`Section` groups a region of a page: a settings group, a form section, or a highlighted block. It paints a background, applies padding from the spacing scale, and can draw a divider on any side.

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

<template>
  <Section :padding="4">
    <p>Account</p>
  </Section>
</template>
```

`variant` is `section` (surface), `muted`, or `transparent`. `padding` defaults to step 4. A single edge overrides the axis, and an axis overrides `padding`. `dividers` accepts `top`, `bottom`, `start`, and `end`; `start` and `end` follow writing direction.

The outer box uses a negative margin so a section can escape the padding of a parent container such as `Card` or `LayoutContent`.

### Anatomy

- **Section container**: Painted container that groups a page region.
- **Consumer content**: Caller-provided content rendered inside the section container.

## Best practices

| Guidance | Practices |
| --- | --- |
| Do | Use Section for a region of a page. Use Card for one discrete item, such as a profile or a notification. |
| Do | Start with the default variant. Use muted when one region should stand out. |
| Do | Add a divider between adjacent sections that share a background. |
| Don't | Restate the theme padding with an extra margin on the children. Set `padding` on the section. |

## Examples

### Default with wash

A default section stacked with a full-width muted section, so one region such as an upgrade prompt stands out.

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

const features = [
  '10 team members',
  'Unlimited projects',
  'Priority support',
  'Advanced analytics',
]
</script>

<template>
  <VStack :gap="2">
    <Section :padding="4" variant="section">
      <VStack :gap="3" h-align="center">
        <VStack :gap="1" h-align="center">
          <Text type="display-3">
            Pro Plan
          </Text>
          <Text color="secondary" type="body">
            Everything you need to scale your team.
          </Text>
        </VStack>
        <VStack :gap="2">
          <HStack v-for="feature in features" :key="feature" :gap="2" align="center">
            <span class="i-carbon-checkmark nav-mark" />
            <Text type="body">
              {{ feature }}
            </Text>
          </HStack>
        </VStack>
      </VStack>
    </Section>
    <Section :padding="6" variant="muted">
      <VStack :gap="2" h-align="center">
        <HStack :gap="2" align="center">
          <Text type="display-3">
            $49
          </Text>
          <Text color="secondary" type="supporting">
            / month
          </Text>
        </HStack>
        <Button label="Upgrade" variant="primary" />
      </VStack>
    </Section>
  </VStack>
</template>
```

### With dividers

Adjacent sections of the same variant, separated by a bottom divider, as on a settings page.

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

<template>
  <VStack :gap="0">
    <Section :dividers="['bottom']" :padding="5" variant="section">
      <VStack :gap="1">
        <Heading :level="4">
          Account
        </Heading>
        <Text color="secondary" type="body">
          Manage your profile, email, and password.
        </Text>
      </VStack>
    </Section>
    <Section :dividers="['bottom']" :padding="5" variant="section">
      <VStack :gap="1">
        <Heading :level="4">
          Notifications
        </Heading>
        <Text color="secondary" type="body">
          Choose what updates you receive and how.
        </Text>
      </VStack>
    </Section>
    <Section :padding="5" variant="section">
      <VStack :gap="1">
        <Heading :level="4">
          Privacy
        </Heading>
        <Text color="secondary" type="body">
          Control who can see your activity and data.
        </Text>
      </VStack>
    </Section>
  </VStack>
</template>
```

## Section Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `variant` | `'section' \| 'transparent' \| 'muted'` | `'section'` | Background. `section` uses the surface, `muted` uses the wash, and `transparent` paints nothing. |
| `padding` | `SpacingStep` | `4` | Padding on every edge. `0` is edge-to-edge content. |
| `paddingInline` | `SpacingStep` | - | Inline-axis padding. Overrides `padding` on that axis. |
| `paddingInlineStart` | `SpacingStep` | - | Inline-start padding. Overrides the broader values on that edge. The physical edge follows writing direction. |
| `paddingInlineEnd` | `SpacingStep` | - | Inline-end padding. Overrides the broader values on that edge. |
| `paddingBlock` | `SpacingStep` | - | Block-axis padding. Overrides `padding` on that axis. |
| `paddingBlockStart` | `SpacingStep` | - | Block-start padding. Overrides the broader values on that edge. |
| `paddingBlockEnd` | `SpacingStep` | - | Block-end padding. Overrides the broader values on that edge. |
| `dividers` | `Array<'top' \| 'bottom' \| 'start' \| 'end'>` | - | Edges that draw a 1px border. `start` and `end` follow writing direction. |
| `width` | `number \| string` | - | Width. Numbers are pixels, strings are used as they are. |
| `height` | `number \| string` | - | Height. Numbers are pixels, strings are used as they are. |
| `maxWidth` | `number \| string` | - | Maximum width. Numbers are pixels, strings are used as they are. |
| `minHeight` | `number \| string` | - | Minimum height. Numbers are pixels, strings are used as they are. |

`SpacingStep` accepts `0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10`.

## Slots

| Name | Description |
| --- | --- |
| `default` | Content inside the section. |

## Native attributes

`Section` renders a `<div>`.

The following go to that element:

- HTML attributes.
- `aria-*` attributes.
- `data-*` attributes.
- `class`.
- `style`.

`class` is merged. The inner element sets `data-variant` and `data-divider-*` for each requested edge.