import { Meta, Canvas, Controls, Source } from '@storybook/addon-docs/blocks';
import '../../../stories/styles/shared.css';
import * as SyCheckboxStories from "./SyCheckbox.stories";

<Meta of={SyCheckboxStories} />

<div className="header">
  <h1>SyCheckbox</h1>
  <p>Le composant `SyCheckbox` est une case à cocher basée sur `VCheckbox` de Vuetify. Elle peut afficher un état indéterminé, expose des événements de mise à jour contrôlés et respecte les règles d'accessibilité <abbr title="Référentiel Général d'Amélioration de l'Accessibilité">RGAA</abbr>.</p>
</div>

{/* func-version-start */}
<p className="func-version-badge">Dernière mise à jour fonctionnelle : V1.1.3 - 27/07/2026</p>
{/* func-version-end */}
{/* a11y-version-start */}
<p className="a11y-version-badge">Dernière mise à jour accessibilité : V1.1.3 - 22/07/2026</p>
{/* a11y-version-end */}


Il étend les fonctionnalités de base de Vuetify avec :

- Un état indéterminé pour les sélections partielles
- Un système de validation avancé
- Des états visuels (erreur, avertissement, succès)
- Un mode optionnel `cycleIndeterminate` pour faire passer l'utilisateur par l'état indéterminé au clic ou avec la touche Espace

<Canvas of={SyCheckboxStories.Default} />

# API

<Controls of={SyCheckboxStories.Default} />

## États et interaction

Le composant `SyCheckbox` peut avoir trois états :
- **Coché** : La case est cochée (modelValue = true)
- **Non coché** : La case est vide (modelValue = false)
- **Indéterminé** : La case est partiellement cochée (indeterminate = true)

L'état affiché est piloté par les props `modelValue` et `indeterminate`. Quand `indeterminate` vaut `true`, le composant expose `aria-checked="mixed"` aux technologies d'assistance.

Par défaut, `cycleIndeterminate` vaut `false` et SyCheckbox conserve le comportement binaire de Vuetify lors de l'activation utilisateur : la case alterne entre cochée et non cochée. Si la case était indéterminée, l'activation désactive d'abord `indeterminate` puis émet une valeur cochée.

Avec `cycleIndeterminate`, SyCheckbox intercepte le clic et la touche Espace pour inclure l'état indéterminé dans la rotation : non coché, indéterminé, coché, puis non coché. Dans ce mode, passer de non coché à indéterminé émet uniquement `update:indeterminate` avec `true` ; passer d'indéterminé à coché émet `update:indeterminate` avec `false`, puis `update:modelValue` avec `true`.

Le composant ne calcule pas lui-même une sélection partielle et ne mémorise pas l'état des enfants. Si `indeterminate` représente un groupe de cases, l'application doit dériver cette prop depuis les valeurs réelles du groupe.

## Événements

Le composant utilise les événements Vue de mise à jour de modèle :
- `update:modelValue` est émis quand la valeur cochée/non cochée change ; utilisez `@update:model-value` à la place de l'ancien `@change`.
- `update:indeterminate` est émis quand SyCheckbox sort de l'état indéterminé ou quand `cycleIndeterminate` fait entrer la case dans cet état.

```vue
<SyCheckbox
  v-model="checked"
  :indeterminate="indeterminate"
  @update:model-value="handleValueUpdate"
  @update:indeterminate="handleIndeterminateUpdate"
/>
```

## Validation

Le composant supporte trois types de validation :
- Règles d'erreur standard (`customRules`)
- Règles d'avertissement (`customWarningRules`)
- Règles de succès (`customSuccessRules`)

### États visuels :

La case à cocher adapte automatiquement son apparence selon son état :
- Rouge pour les erreurs
- Orange pour les avertissements
- Vert pour les succès

## Relation parent-enfant

SyCheckbox ne connaît pas ses enfants et ne modifie pas directement d'autres cases. Une relation parent-enfant se construit dans l'application, en composant plusieurs SyCheckbox.

Pour rester conforme au modèle WAI-ARIA des cases à cocher mixtes, l'état `indeterminate` du parent doit être dérivé de la sélection réelle des enfants : si tous les enfants sont cochés, le parent doit être coché ; si aucun enfant n'est coché, le parent doit être non coché ; si une partie seulement est cochée, le parent doit être indéterminé.

L'application reste responsable de :
- synchroniser les valeurs des enfants ;
- recalculer `modelValue` et `indeterminate` pour le parent ;
- appliquer `update:modelValue` à tous les enfants quand le parent coche ou décoche le groupe ;
- restaurer une combinaison partielle si elle active `cycleIndeterminate` et reçoit `update:indeterminate=true`.

`controlsIds` n'est plus utilisé par SyCheckbox. Si une relation programmatique spécifique est nécessaire dans un contexte donné, elle doit être portée par le conteneur applicatif qui organise le groupe.

<Canvas of={SyCheckboxStories.WithCycleIndeterminate} />

## Mode Décoratif

La propriété `decorative` permet d'afficher la case à cocher uniquement de manière visuelle, sans rendre l'élément interactif natif (`<input type="checkbox">`) dans le DOM. 
Ce mode est essentiel lorsque la case à cocher est imbriquée à l'intérieur d'un autre élément interactif (comme une ligne d'un tableau cliquable ou une option de liste déroulante). Il permet de respecter les règles d'accessibilité (qui interdisent l'imbrication de contrôles interactifs) tout en offrant le rendu visuel attendu. Le composant parent devient alors responsable de l'annonce de l'état (ex: via `aria-selected`).

<a href="/?path=/docs/guide-du-dev-formulaires-validation-guide-des-formulaires--docs" className="action-link">Pour plus d'informations sur la validation, consultez le guide de validation des formulaires.</a>