# Web Component QuadraCatalogue V1

## Artefact et prérequis

La phase 2 produit `dist/quadratik-product-picker.js`, module ES autonome incluant Lit et les validateurs du contrat. Le build mesuré le 15 novembre 2026 pèse **133,25 kB non compressé et 33,37 kB gzip**, hors source map. La version 0.3.0 du 16 novembre (attribut `host-context`) pèse 134 004 octets, bundle `78296af7658cc78fb46c3a00f9750e7d1a928030f2ada0520412ddd09eb41ae5`. La version **0.4.0** du 17 novembre (contexte `calc`, attributs `action-label` et `categories`) pèse **135 759 octets** une fois assemblée (135,81 kB / 34,06 kB gzip au build), bundle `a8ee3cb4b36168167369b2c11128ab0aff58eb98011d70c502cdb55866013b7d`. Cette mesure constitue la référence initiale, pas un seuil de performance approuvé. Aucune bibliothèque de visualisation lourde n’est chargée.

Le composant est connecté uniquement. Il appelle une API V1 compatible sous l’URL donnée par `api-base-url`, sans cookie ni token (`credentials: "omit"`), revalide les réponses HTTP et ne crée aucun stockage persistant. Une liste, une fiche ou une erreur non conforme au contrat fermé est refusée.

```html
<quadratik-product-picker
  api-base-url="https://strapi.example.test/api/catalogue/v1"
></quadratik-product-picker>
<script type="module" src="/releases/v1/assets/quadratik-product-picker.HASH_SHA256.js"></script>
```

La phase 3 produit ce chemin à partir du SHA-256 complet et le publie dans `/releases/v1/manifest.json`. Le démonstrateur distribué revalide ce manifeste puis importe son `bundle.url`. L’intégration locale de développement peut toujours importer le package `@quadratik/catalogue`. Voir la [procédure de distribution locale](DISTRIBUTION_LOCALE_V1.md).

## Propriétés et personnalisation

| Attribut HTML | Propriété JavaScript | Défaut | Rôle |
|---|---|---:|---|
| `api-base-url` | `apiBaseUrl` | `/api/catalogue/v1` | Racine de l’API V1 |
| `page-size` | `pageSize` | `24` | Taille demandée, bornée de 1 à 100 |
| `request-timeout-ms` | `requestTimeoutMs` | `10000` | Délai maximal de chaque requête |
| `host-context` | `hostContext` | `room` | Contexte d'affichage depuis 0.3.0 : `room` (« Ajouter à la pièce », filtre d'ajoutabilité visible), `quote` (« Ajouter au devis »), `doc` (« Voir le manuel d’assemblage ») et, depuis 0.4.0, `calc` (« Utiliser dans le calcul »). Hors `room`, le filtre d'ajoutabilité est masqué. Valeur inconnue → `room`. N'affecte ni le contrat ni l'événement |
| `action-label` | `actionLabel` | vide | Depuis 0.4.0 : libellé du bouton d'action imposé par l'hôte (ex. « Charger dans A », « Ajouter en B »), retenu s'il fait 1 à 60 caractères après trim ; sinon libellé du contexte. Présentation uniquement |
| `categories` | `categories` | vide | Depuis 0.4.0 : périmètre de gammes imposé par l'hôte, slugs séparés par virgules ou espaces (normalisés, dédoublonnés, invalides ignorés). Le sélecteur ne propose que les gammes du périmètre publiées dans `/meta`, **sans** « Toutes les catégories » ; la première est présélectionnée et chaque requête de liste porte `category` (l'API n'accepte qu'une catégorie par requête). Aucune gamme du périmètre publiée → liste vide, jamais le catalogue entier. Vide : comportement historique |

La méthode `refresh(): Promise<void>` recharge les métadonnées et la première page. Modifier `apiBaseUrl`, `pageSize`, `requestTimeoutMs` ou `categories` relance aussi le chargement. Avec un périmètre, la liste attend les métadonnées pour connaître la gamme à demander. Les nouvelles recherches, filtres et ouvertures de fiche annulent les requêtes devenues obsolètes.

Variables CSS exposées avec valeurs Quadratik par défaut :

- `--quadratik-catalogue-color`, `--quadratik-catalogue-muted` ;
- `--quadratik-catalogue-surface`, `--quadratik-catalogue-surface-muted`, `--quadratik-catalogue-border` ;
- `--quadratik-catalogue-accent`, `--quadratik-catalogue-accent-contrast`, `--quadratik-catalogue-danger` ;
- `--quadratik-catalogue-radius`, `--quadratik-catalogue-font`.

Les parts stables de présentation sont `shell`, `header`, `toolbar`, `content`, `product-list`, `product-card`, `detail`, `acoustic-panel`, `actions`, `add-button` et `cancel-button`. Elles permettent un raccord visuel limité sans exposer le DOM interne comme contrat métier.

## Événements

`quadratik-product-selected` n’est émis qu’après un nouveau GET de détail, validation du schéma et des invariants, et contrôle de l’ajoutabilité. Son `detail` suit `selected-event.schema.json`. `quadratik-product-cancelled` porte `{ contractVersion: "1" }`. Les deux événements utilisent `bubbles: true` et `composed: true`.

```js
const picker = document.querySelector('quadratik-product-picker');
picker.addEventListener('quadratik-product-selected', event => {
  // Revalider event.detail à la frontière de l'hôte avant persistance.
  const { documentId, ref, variant, revision } = event.detail.product;
});
picker.addEventListener('quadratik-product-cancelled', () => closeHostModal());
```

Un produit sans placement reste consultable mais le bouton « Ajouter à la pièce » est désactivé. Les profils acoustiques génériques ou indéterminés restent ajoutables avec leur avertissement non certifié visible.

## États et accessibilité

Les états distincts couvrent chargement, liste vide, réseau indisponible, délai dépassé, HTTP 401/403, réponse invalide, fiche disparue et requête remplacée. Une erreur de connexion retire la possibilité d’émettre une nouvelle sélection. L’événement navigateur `offline` annule les lectures en cours ; `online` déclenche un rechargement.

Le Shadow DOM contient des labels explicites, régions de statut/alerte, tableau acoustique avec en-têtes, contrôles natifs utilisables au clavier et styles de focus visibles. Après ouverture d’une fiche, le focus va sur son titre ; le bouton de retour ramène au catalogue. Il n’existe pas de seconde modale interne : l’intégration QuadraRoom conservera l’enveloppe de sa modale en phase 4.

Les tests Chromium exécutent un audit d’accessibilité automatisé sur la liste et la fiche, vérifient le contrôle clavier natif du panneau `<details>`, l’ordre 125/250/500/1 000/2 000/4 000 Hz et les valeurs de diffusion absentes.

## Enregistrement et versions concurrentes

L’import enregistre l’élément s’il n’existe pas. `registerQuadratikProductPicker()` retourne `registered`, `already-registered`, `version-conflict` ou `unavailable`. Si une autre version a déjà défini le même nom dans le registre, le module ne tente jamais de la remplacer et consigne le conflit. Une page hôte doit charger une seule version majeure du composant.

L’import reste sûr dans un rendu serveur : aucun accès non protégé à `document`, `window` ou `customElements` n’a lieu au niveau du module. L’élément ne s’enregistre qu’en présence d’un registre navigateur.

## Exemples d’hôtes

- [HTML sans framework](../examples/integration.html) ;
- [adaptateur React avec nettoyage du listener](../examples/react/QuadratikProductPicker.tsx) ;
- [chargement navigateur Astro](../examples/astro/Catalogue.astro).

Ces exemples documentent le raccord technique. Ils ne remplacent pas l’adaptateur, la persistance de l’instantané et les contrôles propres à QuadraRoom prévus en phase 4.

## Développement et vérification

```sh
npm run dev          # démonstrateur local à fixtures synthétiques
npm run build        # types + bundle reproductible
npm run test:browser # comportements réels dans Chromium
npm run check        # contrat, navigateur et schémas versionnés
```

Les tests couvrent les quatre contextes d'hôte, le libellé imposé (valeur invalide ignorée), le périmètre de gammes (options limitées, requêtes bornées, périmètre inconnu vide, changement à chaud), plusieurs instances, nettoyage/annulation au démontage, recherche/filtres/pagination API, remplacement d’une requête, liste et détail, sélection/annulation, perte de réseau, timeout, 401/403, réponse invalide ou fiche disparue, produit sans placement et conflit de versions. Le démonstrateur permet également de simuler les états hors ligne, lent et invalide.
