# Interactivité et scripts

Les pages Sovrium sont rendues côté serveur, puis progressivement enrichies avec une interactivité déclarative. Cette page couvre le bloc `scripts` (scripts externes/inline, indicateurs de fonctionnalités, données de config), le module `interactions` (actions de clic, effets de survol, animations d'entrée), la sauvegarde automatique pour l'édition en ligne, les listes réordonnables et le HTML personnalisé. Aucun câblage d'événements écrit à la main n'est requis pour les motifs intégrés.

```yaml
pages:
  - name: Dashboard
    path: /dashboard
    scripts:
      external:
        - { src: 'https://cdn.example.com/widget.js', async: true, position: body-end }
      features: { betaPanel: true }
    components:
      - type: button
        content: Save
        interactions:
          onClick: { animation: pulse, submitForm: settings-form }
```

## `scripts`

Gestion des scripts côté client au niveau de la page.

| Propriété  | Description                                                                                                     |
| ---------- | --------------------------------------------------------------------------------------------------------------- |
| `external` | Dépendances JavaScript externes — chacune `{ src, async, defer, module, integrity, crossorigin, position }`.    |
| `inline`   | Extraits JavaScript inline — chacun `{ code, async? }`. `async: true` encadre le code dans une IIFE asynchrone. |
| `features` | Bascules de fonctionnalités côté client — un indicateur booléen ou `{ enabled, config }` par fonctionnalité.    |
| `config`   | Données de configuration arbitraires côté client exposées aux scripts.                                          |

### Attributs de script externe

| Attribut      | Description                                                    |
| ------------- | -------------------------------------------------------------- |
| `src`         | URL source du script.                                          |
| `async`       | Charger de façon asynchrone (non bloquant).                    |
| `defer`       | Différer l'exécution jusqu'à ce que le DOM soit analysé.       |
| `module`      | Charger comme module ES (`type="module"`).                     |
| `integrity`   | Hash d'intégrité de sous-ressource pour la sécurité.           |
| `crossorigin` | Paramètre CORS : `anonymous` ou `use-credentials`.             |
| `position`    | Emplacement d'insertion : `head`, `body-start`, ou `body-end`. |

## `interactions`

Le module partagé `interactions` attache un comportement côté client à un composant : actions de clic, effets de survol et animations d'entrée.

### `onClick`

| Propriété    | Description                                                                  |
| ------------ | ---------------------------------------------------------------------------- |
| `animation`  | Animation à jouer au clic (`pulse`, `ripple`, `bounce`, ou `none`).          |
| `navigate`   | Chemin vers lequel naviguer (route interne ou ancre de même page).           |
| `url`        | URL externe à ouvrir (dans le même onglet, ou nouvel onglet avec une cible). |
| `scrollTo`   | Section d'ancre vers laquelle défiler en douceur.                            |
| `toggle`     | Id d'élément à afficher/masquer.                                             |
| `submitForm` | Id de formulaire à soumettre.                                                |
| `modalId`    | Id de section modale à ouvrir.                                               |

Les comportements de clic peuvent se combiner — p. ex. jouer une animation, puis naviguer.

### `onHover`

| Propriété         | Description                                                                         |
| ----------------- | ----------------------------------------------------------------------------------- |
| `transform`       | Transformation CSS au survol (échelle/rotation/translation ; p. ex. `scale: 1.05`). |
| `opacity`         | Valeur d'opacité au survol (0–1).                                                   |
| `backgroundColor` | Couleur d'arrière-plan au survol.                                                   |
| `textColor`       | Couleur du texte au survol.                                                         |
| `borderColor`     | Couleur de bordure au survol.                                                       |
| `boxShadow`       | Ombre portée au survol.                                                             |
| `duration`        | Durée de transition (ms ; `0` applique les effets instantanément).                  |
| `easing`          | Fonction de cadence : `linear`, `ease`, `ease-in`, `ease-out`, `ease-in-out`.       |

Tous les effets de survol s'appliquent simultanément avec une cadence coordonnée.

### `onEntrance`

| Propriété   | Description                                                         |
| ----------- | ------------------------------------------------------------------- |
| `animation` | Type d'animation déclenché lorsque l'élément entre dans la fenêtre. |
| `threshold` | Fraction de l'élément visible avant déclenchement (0–1).            |
| `delay`     | Délai avant le démarrage de l'animation.                            |
| `once`      | Déclencher une seule fois.                                          |

## Actions et gestionnaires de réponse

Les composants interactifs portent une `action` (p. ex. `crud`, `auth`, `navigate`, `automation`) avec des gestionnaires de réponse `onSuccess`/`onError`. Un gestionnaire peut afficher un `toast`, `navigate`, `reset` le formulaire, afficher un `message`, ou rendre un `successPage` avec des `actions` de suivi. `action.type: automation` invoque une [automatisation](/fr/docs/automations-overview) nommée.

```yaml
- type: button
  content: Submit
  action:
    type: crud
    operation: create
    onSuccess: { type: navigate, url: /thanks }
    onError: { type: message, toast: { variant: error, message: 'Save failed' } }
```

## Sauvegarde automatique

Les composants de données prennent en charge la sauvegarde automatique de l'édition en ligne via le module `autoSave` (le plus souvent sur `data-table`).

| Propriété               | Description                                                                                                                       |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `saveMode`              | `auto` (anti-rebond), `onBlur` (sauvegarder quand le champ édité perd le focus), ou `manual` (défaut).                            |
| `autoSaveDebounceMs`    | Délai d'anti-rebond après la dernière frappe (défaut : 500 ; min : 100). Les éditions rapides se regroupent en une seule requête. |
| `showSaveIndicator`     | Afficher le statut : Inactif / Sauvegarde… / Sauvegardé / Erreur (avec nouvelle tentative en cas d'échec).                        |
| `saveIndicatorPosition` | `inline` (près de la cellule éditée), `toast`, ou `toolbar`.                                                                      |

Seule la valeur de cellule modifiée est envoyée dans la charge utile PATCH ; quitter la page vide immédiatement les sauvegardes en attente.

## `reorderable-list`

Une liste dont les éléments peuvent être réordonnés par glisser-déposer ou clavier, déclenchant une action `onReorder`.

| Propriété    | Description                                                                   |
| ------------ | ----------------------------------------------------------------------------- |
| `dataSource` | Liaison de table optionnelle pour les éléments de la liste.                   |
| `children`   | Les éléments de la liste (chacun rendu avec une poignée de glissement).       |
| `onReorder`  | Action invoquée lorsque les éléments sont réordonnés (glissement ou clavier). |

## `custom-html` (`customHTML`)

Intégrer du HTML brut — inline ou depuis un fichier — dans un contexte de bac à sable avec accès aux variables CSS du thème.

| Propriété | Description                                                                                     |
| --------- | ----------------------------------------------------------------------------------------------- |
| `content` | Chaîne HTML inline.                                                                             |
| `htmlSrc` | Chemin vers un fichier HTML externe, relatif à la racine du projet. Prend le pas sur `content`. |

Le HTML est rendu dans un contexte de bac à sable (sans accès au JS de la page parente) et peut référencer les variables du thème (p. ex. `var(--color-primary)`). Un `htmlSrc` invalide rend une erreur claire au lieu de planter.

```yaml
- type: customHTML
  content: '<div style="color: var(--color-primary)">Custom block</div>'
```

## Presse-papiers et motifs

Les motifs interactifs courants sont construits à partir des primitives ci-dessus : boutons de copie vers le presse-papiers (un `button` avec une action), champs de recherche à anti-rebond (`searchInput` avec `debounceMs`), fenêtres modales ouvertes via `onClick.modalId`, et contrôle de visibilité via le module `visibility` (rendu côté serveur mais masqué côté client lorsque les conditions d'authentification ne sont pas remplies — les composants masqués ne laissent jamais fuiter de données sensibles dans le HTML).

## Pages connexes

- [Présentation des pages](/fr/docs/pages-overview) — le modèle de composants, les actions et `scripts`/`vars`.
- [Contrôles de formulaire](/fr/docs/form-controls) — entrées qui se sauvegardent automatiquement ou se soumettent via des actions.
- [Composants de données](/fr/docs/data-components) — sauvegarde automatique de l'édition en ligne de `data-table`.
- [Composants de superposition](/fr/docs/overlay-components) — toasts et dialogues déclenchés par des interactions.
- [Automatisations](/fr/docs/automations-overview) — automatisations invoquées par `action.type: automation`.