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

import * as stories from "./checkbox.stories";

<Meta of={stories} />

```ts
import { CheckboxModule } from "@bitwarden/components";
```

<Title />
<Description />

<Primary />
<Controls />

## Stories

### Default

<Canvas of={stories.Default} />

### Hint

<Canvas of={stories.Hint} />

### Custom

<Canvas of={stories.Custom} />

### Indeterminate

<Canvas of={stories.Indeterminate} />

## Using in a group

Use `bit-form-control-group` when you have multiple related checkboxes that should be validated
together as a single form field. The group binds to an array form control — each checkbox input's
`[value]` is added to or removed from the array when checked.

Choose checkboxes in a group when:

- The user selects from a set of options that are saved via a form submit action
- At least one selection should be required (`Validators.required` on the group control enforces
  this)
- The options are independent of each other (any combination is valid)

NOTE: Use switches instead when each option should take effect immediately without a save action.

```html
<bit-form-control-group formControlName="features">
  <bit-form-control-card>
    <input type="checkbox" bitCheckbox [value]="'featureA'" />
    <bit-label>Feature A</bit-label>
  </bit-form-control-card>
  <bit-form-control-card>
    <input type="checkbox" bitCheckbox [value]="'featureB'" />
    <bit-label>Feature B</bit-label>
  </bit-form-control-card>
</bit-form-control-group>
```

### Opting out of group selection (not recommended)

Omitting `[value]` while nested inside a group renders the card as a standalone control — it manages
its own checked state via `formControlName` and does not interact with the group's selection. In
most cases, if a card doesn't need group selection, it should be placed outside the group entirely.

### Group

<Canvas of={stories.FormControlCardGroup} />

### Group with validation

<Canvas of={stories.FormControlCardGroupWithValidation} />

### Leading element

A form control card can render a leading element before the label. Use the `icon` input for the
common case — it renders a `bit-icon-tile` and automatically switches to the `subtle` variant when
the control is disabled:

```html
<bit-form-control-card icon="bwi-clock">
  <input type="checkbox" bitCheckbox formControlName="checkbox" />
  <bit-label>Enable feature</bit-label>
</bit-form-control-card>
```

To render any other element instead, project it into the `start` slot. This is mutually exclusive
with `icon` — if both are provided, the `icon` wins. The card wraps the slot to keep the element
top-aligned when the label wraps, so you only need to size and color your element:

```html
<bit-form-control-card>
  <bit-svg
    slot="start"
    [content]="lockIcon"
    aria-hidden="true"
    class="tw-w-9 tw-text-fg-brand"
  ></bit-svg>
  <input type="checkbox" bitCheckbox formControlName="checkbox" />
  <bit-label>Enable feature</bit-label>
</bit-form-control-card>
```

<Canvas of={stories.FormControlCardCustomSlot} />
