# Toggle Button Group

## Usage

`ToggleButtonGroup` keeps the pressed state of its `ToggleButton` children. Each child needs a `value`. The group's `v-model:value` replaces that button's own pressed state.

`type="single"` keeps one button pressed. Pressing it again clears the selection, and the value is `null`. `type="multiple"` presses buttons independently, and the value is a list. `orientation` is `horizontal` or `vertical`. `label` is the group's accessible name.

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

const view = ref<string | null>('grid')
</script>

<template>
  <ToggleButtonGroup v-model:value="view" label="View mode">
    <ToggleButton label="List" value="list" />
    <ToggleButton label="Grid" value="grid" />
    <ToggleButton label="Board" value="board" />
  </ToggleButtonGroup>
</template>
```

## Examples

### Group

Toggle button groups in single-select and multi-select modes. Single selection acts as a view mode switcher; multiple selection forms a formatting toolbar.

```vue
<script setup lang="ts">
import { Icon } from '@astryx-vue/core/Icon'
import { Stack } from '@astryx-vue/core/Stack'
import { Text } from '@astryx-vue/core/Text'
import { ToggleButton, ToggleButtonGroup } from '@astryx-vue/core/ToggleButton'
import { ref } from 'vue'

const view = ref<string | null>('list')
const formats = ref<string[]>(['bold'])
</script>

<template>
  <Stack direction="vertical" :gap="4">
    <Stack direction="vertical" :gap="1">
      <Text type="supporting" color="secondary">
        Single selection
      </Text>
      <ToggleButtonGroup v-model:value="view" label="View mode">
        <ToggleButton value="list" label="List view" is-icon-only>
          <template #icon>
            <Icon icon="i-heroicons-list-bullet" />
          </template>
        </ToggleButton>
        <ToggleButton value="grid" label="Grid view" is-icon-only>
          <template #icon>
            <Icon icon="i-heroicons-squares-2x2" />
          </template>
        </ToggleButton>
        <ToggleButton value="table" label="Table view" is-icon-only>
          <template #icon>
            <Icon icon="i-heroicons-table-cells" />
          </template>
        </ToggleButton>
      </ToggleButtonGroup>
    </Stack>
    <Stack direction="vertical" :gap="1">
      <Text type="supporting" color="secondary">
        Multiple selections
      </Text>
      <ToggleButtonGroup v-model:value="formats" type="multiple" label="Text formatting">
        <ToggleButton value="bold" label="Bold" is-icon-only>
          <template #icon>
            <Icon icon="i-heroicons-bold" />
          </template>
        </ToggleButton>
        <ToggleButton value="italic" label="Italic" is-icon-only>
          <template #icon>
            <Icon icon="i-heroicons-italic" />
          </template>
        </ToggleButton>
        <ToggleButton value="underline" label="Underline" is-icon-only>
          <template #icon>
            <Icon icon="i-heroicons-underline" />
          </template>
        </ToggleButton>
        <ToggleButton value="strikethrough" label="Strikethrough" is-icon-only>
          <template #icon>
            <Icon icon="i-heroicons-strikethrough" />
          </template>
        </ToggleButton>
      </ToggleButtonGroup>
    </Stack>
  </Stack>
</template>
```

### Vertical

A vertically stacked ToggleButtonGroup using the vertical orientation, shown with both single-select and multi-select behavior.

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

const view = ref<string | null>('grid')
const filters = ref<string[]>(['active'])
</script>

<template>
  <VStack :gap="4">
    <VStack :gap="1">
      <Text type="label" color="secondary">
        Single select
      </Text>
      <ToggleButtonGroup v-model:value="view" orientation="vertical" label="View mode">
        <ToggleButton value="list" label="List" />
        <ToggleButton value="grid" label="Grid" />
        <ToggleButton value="board" label="Board" />
      </ToggleButtonGroup>
    </VStack>
    <VStack :gap="1">
      <Text type="label" color="secondary">
        Multi select
      </Text>
      <ToggleButtonGroup v-model:value="filters" orientation="vertical" type="multiple" label="Status filters">
        <ToggleButton value="active" label="Active" />
        <ToggleButton value="pending" label="Pending" />
        <ToggleButton value="closed" label="Closed" />
      </ToggleButtonGroup>
    </VStack>
  </VStack>
</template>
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | - | Accessible name, rendered as `aria-label`. |
| `type` | `'single' \| 'multiple'` | `'single'` | `single` keeps one member pressed. `multiple` presses members independently. |
| `value` | `string \| null \| string[]` | `null` | The pressed member, or the list of them. Bind with `v-model:value`. |
| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Layout direction. |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Size the members inherit. A member's own `size` wins. |
| `isDisabled` | `boolean` | `false` | Disables every member. A member can still disable itself. |

## Events

| Name | Payload | Description |
| --- | --- | --- |
| `update:value` | `string \| null \| string[]` | The next selection. |
| `change` | `string \| null \| string[]` | Emitted with `update:value`. |

## Slots

The default slot is the `ToggleButton` members. Each member that participates needs a `value`.