import { Meta, Story, Primary, Controls, Canvas } from "@storybook/addon-docs/blocks";

import * as stories from "./toggle-group.stories";

<Meta of={stories} />

# Toggle Group

Toggle groups are used for quick filters for a data set. **Example:** the Member’s page of the Admin
Console uses a toggle group to filter members by their organization status: all, invited, needs
confirmation, revoked.

Toggle groups function as radio buttons and a radio group under the hood.

A button in a toggle group can have a badge counter added to show the number of items existing
within that filter.

## Default

<Canvas of={stories.Default} />

<Controls />

## Full width

If a toggle group should span the width of its container, pass the `fullWidth` input to the toggle
group.

```
<bit-toggle-group fullWidth>
...toggle components here...
</bit-toggle-group>
```

<Canvas of={stories.FullWidth} />

## Inline

Use the `inline` input to keep the toggle group inline-grid at all breakpoints and prevent it from
ever expanding to fill the container width. This is useful when placing a toggle group inside a card
or other constrained layout where full-width expansion would look wrong.

```html
<bit-toggle-group inline> ...toggle components here... </bit-toggle-group>
```

<Canvas of={stories.Inline} />

## Responsive overflow

By default, a toggle group adapts to its available space across three modes:

1. **Inline** — the natural state; the group sizes to its content and sits inline.
2. **Full-width** — triggered by the `fullWidth` input; each toggle expands equally to fill the
   container.
3. **Dropdown** — triggered automatically when the container is too narrow to fit the toggles; the
   buttons collapse into a `<select>`-style dropdown so the selection is never lost.

The transition between modes is driven by a `ResizeObserver` that compares the container's current
width against the group's natural (unconstrained) width. When the container shrinks below that
threshold the group switches to dropdown, and when it grows back above it the group returns to its
previous inline or full-width state.

Mode switching is transparent to the consumer: `[(selected)]` (or `[selected]` + `(selectedChange)`)
reports value changes the same way whether the user clicks a toggle pill or picks an option from the
dropdown. There is no separate event to subscribe to for the dropdown mode.

Resize the browser window in the story below to see all three modes in action.

<Canvas of={stories.Overflow} />

# Accessibility

- Since only 1 button can be selected at a time, the toggle group acts similarly to a radio group.
- The user may navigate the options via left/right arrow keys.
- The screen reader will announce the button group: example “[context label], [button content]
  selected, of [# of buttons]”), the number of buttons and the currently selected button.

## Label

Provide an accessible name for the group via the `label` input:

```html
<bit-toggle-group label="People list filter"> ...toggle components here... </bit-toggle-group>
```

In radiogroup mode (`inline`/`fullWidth`) the value is rendered as `aria-label` on the host. When
the responsive variant switches to the dropdown, the same label is rendered as a screen-reader-only
`<label for>` tied to the combobox, so screen reader users keep hearing the group's purpose across
every breakpoint. Consumers do not need to vary their markup between modes.
