
# Canvas

Le canevas offre une vue d’ensemble dézoomée, semblable à Figma, de toutes les pages gérées par Blockstudio. Chaque page s’affiche sous forme de plan de travail en iframe dynamique, sur une seule ligne horizontale. Déplacez-vous avec le trackpad et zoomez en pinçant ou avec Ctrl+défilement.

## Activation

Le canevas est accessible depuis une page d’administration masquée. Accédez à :

```
/wp-admin/admin.php?page=blockstudio-canvas
```

La page est accessible uniquement lorsque `dev.canvas.enabled` est `true` et que l’utilisateur actuel possède la capacité `edit_posts`.

## Paramètres

Activez le canevas et configurez son comportement dans le `blockstudio.json` de votre thème :

```json title="blockstudio.json"
{
  "dev": {
    "canvas": {
      "enabled": true,
      "adminBar": false
    }
  }
}
```

| Propriété | Type | Valeur par défaut | Description |
|----------|------|---------|-------------|
| `enabled` | `boolean` | `false` | Active la fonctionnalité de canevas. |
| `adminBar` | `boolean` | `true` | Affiche la barre d’administration WordPress dans les iframes des plans de travail. Définissez cette option sur `false` pour obtenir un aperçu plus épuré. |

Les deux réglages sont également disponibles sous forme de filtres :

```php
add_filter('blockstudio/settings/dev/canvas/enabled', '__return_true');
add_filter('blockstudio/settings/dev/canvas/admin_bar', '__return_false');
```

## Vues

Passez d’une vue à l’autre à l’aide du menu déroulant en haut à droite.

- **Pages** : toutes les pages gérées par Blockstudio s’affichent en plans de travail pleine largeur sur une seule ligne.
- **Blocs** : tous les blocs Blockstudio enregistrés s’affichent dans une grille, chacun rendu avec ses valeurs d’attribut par défaut.

## Inventaire public et API des documents

`Canvas` expose un contrat PHP versionné et neutre vis-à-vis des consommateurs, pour les outils qui ont besoin du même contenu enregistré sans reconstruire la logique de découverte ou de rendu de Blockstudio :

```php
use Blockstudio\Canvas;

$all = Canvas::inventory();

$changed = Canvas::inventory([
  'blocks' => ['theme/hero'],
  'pages' => ['about'],
]);

$documents = Canvas::documents([
  'patterns' => ['theme/featured'],
  'templates' => ['front-page'],
]);
```

La version actuelle est disponible sous forme de `Canvas::SCHEMA_VERSION`. Les résultats de l’inventaire contiennent :

- `inventory` : `pages`, `blocks`, `patterns`, `templates`, `parts` normalisés et exemples publics de la famille `ui`
- `order` : l’ordre d’affichage stable entre les types
- `sources` : les chemins source exacts sélectionnés, avec leur provenance sur chaque enregistrement ; pour une page, `source` est son identité source stable, tandis que `path` est le chemin physique du modèle de rendu
- `warnings` et `errors` : des problèmes structurés plutôt qu’une sortie générée
- `deleted` : les identifiants demandés qui n’existent plus
- `selection` : la sélection normalisée et l’indication de son ciblage

`Canvas::documents()` ajoute un document de rendu complet pour chaque enregistrement sélectionné.
Chaque document contient son corps, HTML assemblé, les noms des blocs et leurs dépendances, ainsi que CSS, JavaScript, les modules, l’initialisation de l’interactivité, les variables globales UI intégrées et la sortie Tailwind. Les documents de page utilisent un conteneur de contenu sémantique `<main>` ; les appelants peuvent le remplacer ou le désactiver avec les options partagées des documents de rendu.
Chaque page sélectionnée est rendue dans son propre contexte WordPress restauré, de sorte que les conditions de requête, les filtres de classe du corps, les codes courts, les mises en page, les redirections et les rappels `wp_enqueue_scripts` s’appliquent à cette page, et non à la requête d’administration ou REST à l’origine de la demande du résultat Canvas. Les classes du corps fournies par l’appelant sont fusionnées avec celles du contexte de la page, et les registres de mise en file d’attente du frontend sont isolés entre les documents. Canvas résout ces rappels de cycle de vie par leurs noms de fonction publics WordPress, afin de préserver le même contexte lorsque Blockstudio est chargé via Composer ou un espace de noms d’application déplacé.

### Sémantique de sélection exacte

La sélection est stricte :

- Aucune clé de type reconnue ne charge tous les types.
- `true`, `null` ou `"*"` charge tous les enregistrements de ce type.
- Une chaîne ou une liste ne charge que les ID, noms, slugs, chemins ou chemins source exacts.
- Une chaîne ou liste vide, ou `false`, ne charge aucun enregistrement de ce type.
- Dès qu’une clé de type est présente, les types omis ne sont ni découverts, ni synchronisés, ni rendus, ni compilés.

Cela rend sûres les requêtes limitées aux éléments modifiés dans les grands projets. Les blocs et pages existants sont résolus via leurs registres canoniques. Lorsqu’une requête frontend ne charge que la projection persistée de la page, Canvas effectue une découverte source en lecture seule et fusionne les ID d’articles et les permaliens correspondants sans synchroniser le contenu. La même fusion d’identités s’applique lorsqu’une source de découverte logique alimente d’abord le registre adossé aux sources ; le rendu contextuel de la page utilise ainsi l’article géré par WordPress correspondant. La nouvelle topologie de session active est découverte uniquement autour du répertoire modifié, tandis que les sources de motifs sélectionnées et de modèles de l’éditeur de site sont compilées uniquement après la sélection.

Le point de terminaison d’actualisation REST applique la même règle à ses paramètres de requête existants `blocks` et `pages`. Par exemple, `?blocks=theme/hero` renvoie ce bloc sans aucune page ; utilisez les deux paramètres pour une réponse mixte. Appelé sans l’un ou l’autre paramètre, le point de terminaison conserve la réponse complète historique.

## Mode direct

Le mode direct utilise les Server-Sent Events (SSE) pour détecter les changements de fichiers et actualiser le canevas en temps réel. Lorsque vous modifiez un modèle de bloc, un modèle de page ou une feuille de style, les plans de travail concernés s’actualisent automatiquement en une seconde environ.

Activez ou désactivez le mode direct depuis le menu déroulant. Un indicateur vert clignotant apparaît lorsqu’il est actif. Le réglage est conservé entre les sessions via localStorage.

Le mode direct suit les modifications apportées aux fichiers `.php`, `.json`, `.css`, `.scss`, `.js`, `.twig` et `.html` dans les répertoires des blocs et des pages. Les modifications connues actualisent uniquement leur bloc ou page enregistré. Un bloc ou une page véritablement nouveau déclenche un seul parcours topologique limité à son répertoire ; la création de contenu reste ainsi possible pendant une session directe ouverte, sans rescanner les sources sans rapport.

## Mode focus

Cliquez sur le libellé d’un plan de travail pour passer en mode focus. Le plan sélectionné occupe toute la largeur de la fenêtre, avec un défilement vertical. Appuyez sur Échap ou cliquez sur le bouton de fermeture pour revenir à la vue d’ensemble.

## Commandes

| Action | Entrée |
|--------|-------|
| Déplacer la vue | Défilement / glisser à deux doigts sur le pavé tactile |
| Zoomer | Ctrl+défilement ou pincement |
| Ajuster à la vue | Menu déroulant |
| Zoomer à 100% | Menu déroulant |
| Mettre le plan de travail en focus | Cliquer sur le libellé du plan de travail |
| Quitter le focus | Échap / bouton de fermeture |

## Sécurité

Le script du canevas et les données de la page ne sont chargés que si toutes les conditions sont remplies :

- Le réglage `dev.canvas.enabled` est `true`.
- L’utilisateur actuel dispose de la capacité `edit_posts`.

Les visiteurs publics ne voient jamais le script du canevas ni les métadonnées de la page.
