Widgets déclaratifs

Le principe

Un widget déclaratif est la façon la plus légère d’apparaître sur
l’accueil d’un tenant : vous ne livrez ni page, ni code. Vous décrivez le
widget dans le manifeste — un template fourni par Capibara, d’éventuels
champs config que l’utilisateur du tenant remplit (ex. une adresse), une
source de données — et la plateforme fait tout le reste :

1. elle collecte la donnée côté serveur (fetch borné, HTTPS, host
   allowlisté par vos capabilities http.fetch:<host>) ;
2. elle rend le widget avec ses propres composants, à la charte graphique
   Capibara — jamais d’iframe, jamais de site externe ;
3. elle stocke la configuration saisie par l’utilisateur sur son
   installation. Votre code n’y touche jamais (et n’existe d’ailleurs pas,
   pour un widget purement déclaratif).

C’est le même esprit qu’un bot Discord : vous déclarez, la plateforme exécute.

Déclaration dans le manifeste

{
  "capabilities": [
    "ui.widget",
    "http.fetch:geocoding-api.open-meteo.com",
    "http.fetch:api.open-meteo.com"
  ],
  "contributes": {
    "widgets": [
      {
        "key": "meteo",
        "title": "Météo",
        "kind": "declarative",
        "template": "weather",
        "config": [
          { "key": "address", "label": "Votre ville ou adresse", "type": "text", "placeholder": "Paris", "required": true }
        ],
        "minHeight": 220
      }
    ]
  }
}

Champ	Type	Règle
kind	"declarative"	obligatoire — distingue le widget déclaratif d’un widget embedUrl.
template	string	weather, kpi ou list (catalogue plateforme, il s’étoffera).
config	tableau	optionnel, max 6 champs — { key, label (≤ 60), type: "text"|"number", placeholder?, required? }. Saisis par l’utilisateur SUR le widget, stockés par la plateforme.
source	objet	optionnel — { url, map? } : URL HTTPS templatée avec les champs de config (…?q={address}) + mapping champ de sortie → chemin dans la réponse JSON ("value": "data.count").
minHeight	number	optionnel, 120-1200 px.

Règle d’allowlist (bloquante à la validation) : tout host appelé — celui
de source.url, ou les hosts intégrés du template — doit être déclaré en
capability http.fetch:<host>. Le validateur du manifeste vous liste les
capabilities manquantes.

Les templates

weather — météo (source intégrée)

Aucune source à fournir : le template embarque Open-Meteo (géocodage de
l’adresse saisie puis conditions actuelles — température, ressenti, vent,
humidité, ciel, heure locale). Déclarez les deux hosts :
http.fetch:geocoding-api.open-meteo.com et http.fetch:api.open-meteo.com.
Champ de config attendu : address (requis).

kpi — un chiffre clé

Sans source : rend les valeurs de config value et label telles quelles
(mode statique). Avec source : la réponse JSON est mappée via map
(ex. { "value": "stats.total" }) — chemins pointés, index de tableau
autorisés (results.0.name).

list — une liste d’éléments

La source doit produire un champ items (via map, ex.
{ "items": "data.entries" }) : tableau d’objets { title | name | label, subtitle? | description? } — 6 éléments affichés au maximum.

Ce que voit l’utilisateur

• Il ajoute votre widget depuis « Personnaliser » › « Ajouter un widget » sur
  son accueil (rubrique Apps du sélecteur — le widget porte le nom de votre
  app).
• Si un champ required n’est pas rempli, le widget affiche directement le
  petit formulaire de configuration ; ensuite, un bouton « Modifier » discret
  permet de changer la saisie (ex. changer de ville).
• La donnée est rafraîchie à l’affichage (avec un cache client de quelques
  minutes) — prévoyez une source qui supporte des lectures régulières.

Bornes d’exécution

Le fetch plateforme applique les mêmes bornes que la sandbox : HTTPS
obligatoire, host allowlisté, redirections refusées, timeout 10 s,
réponse ≤ 512 Ko, JSON uniquement. Une source injoignable produit un message
d’erreur sobre dans le widget — jamais de widget cassé.

Exemple complet

Le tutoriel Démarrer construit pas à pas un widget
météo déclaratif (manifeste seul, sans code), l’installe en test puis le
publie. L’app « Météo (exemple) », téléchargeable depuis l’index de la
documentation, montre ensuite la version avec code hébergé (page
et widget rendus par le Kit).