Block Kit

Le Block Kit d’EmDash permet aux plugins en bac à sable de décrire leur interface d’administration sous forme de JSON. L’hôte rend les blocs — aucun JavaScript fourni par le plugin ne s’exécute jamais dans le navigateur.

Note

Les plugins de confiance (déclarés dans astro.config.ts) peuvent toujours fournir des composants React personnalisés. Le Block Kit est destiné aux plugins en bac à sable installés à l’exécution auxquels on ne peut pas faire confiance pour l’accès au DOM.

Astuce

Les éléments du Block Kit sont également utilisés pour les champs d’édition de bloc de texte portable. Lorsqu’un plugin déclare des fields sur un type de bloc, l’éditeur affiche un formulaire Block Kit pour modifier les données du bloc (URL, titre, paramètres, etc.).

Fonctionnement

1. L’utilisateur navigue vers la page d’administration d’un plugin
2. L’administration envoie une interaction page_load à la route d’administration du plugin
3. Le plugin retourne une BlockResponse contenant un tableau de blocs
4. L’administration rend les blocs en utilisant le composant BlockRenderer
5. Lorsque l’utilisateur interagit (clique sur un bouton, soumet un formulaire), l’administration renvoie l’interaction au plugin
6. Le plugin retourne de nouveaux blocs, et le cycle se répète

// Plugin admin route handler
routes: {
  admin: {
    handler: async (ctx, { request }) => {
      const interaction = await request.json();

      if (interaction.type === "page_load") {
        return {
          blocks: [
            { type: "header", text: "My Plugin Settings" },
            {
              type: "form",
              block_id: "settings",
              fields: [
                { type: "text_input", action_id: "api_url", label: "API URL" },
                { type: "toggle", action_id: "enabled", label: "Enabled", initial_value: true },
              ],
              submit: { label: "Save", action_id: "save" },
            },
          ],
        };
      }

      if (interaction.type === "form_submit" && interaction.action_id === "save") {
        await ctx.kv.set("settings", interaction.values);
        return {
          blocks: [/* ... blocs mis à jour ... */],
          toast: { message: "Settings saved", type: "success" },
        };
      }
    },
  },
}

Types de blocs

Type	Description
header	Titre principal en gras
section	Texte avec élément accessoire optionnel
divider	Règle horizontale
fields	Grille label/valeur à deux colonnes
table	Tableau de données avec formatage, tri, pagination
actions	Ligne horizontale de boutons et contrôles
stats	Cartes de métriques de tableau de bord avec indicateurs de tendance
form	Champs de saisie avec visibilité conditionnelle et soumission
image	Image au niveau du bloc avec légende
context	Petit texte d’aide en grisé
columns	Mise en page à 2-3 colonnes avec blocs imbriqués

Types d’éléments

Type	Description
button	Bouton d’action avec boîte de dialogue de confirmation optionnelle
text_input	Saisie de texte sur une ou plusieurs lignes
number_input	Saisie numérique avec min/max
select	Sélection déroulante
toggle	Interrupteur marche/arrêt
secret_input	Saisie masquée pour clés API et jetons

Aides à la construction

Le package @emdash-cms/blocks exporte des aides à la construction pour un code plus propre :

import { blocks, elements } from "@emdash-cms/blocks";

const { header, form, section, stats } = blocks;
const { textInput, toggle, select, button } = elements;

return {
  blocks: [
    header("Paramètres SEO"),
    form({
      blockId: "settings",
      fields: [
        textInput("site_title", "Titre du site", { initialValue: "Mon site" }),
        toggle("generate_sitemap", "Générer un plan de site", { initialValue: true }),
        select("robots", "Robots par défaut", [
          { label: "Index, Follow", value: "index,follow" },
          { label: "No Index", value: "noindex,follow" },
        ]),
      ],
      submit: { label: "Save", actionId: "save" },
    }),
  ],
};

Champs conditionnels

Les champs de formulaire peuvent être affichés conditionnellement en fonction des valeurs d’autres champs :

{
  "type": "toggle",
  "action_id": "auth_enabled",
  "label": "Enable Authentication"
}

{
  "type": "secret_input",
  "action_id": "api_key",
  "label": "API Key",
  "condition": { "field": "auth_enabled", "eq": true }
}

Le champ api_key n’apparaît que lorsque auth_enabled est activé. Les conditions sont évaluées côté client sans aller-retour.

Essayez-le

Utilisez le Block Playground pour construire et tester interactivement des mises en page de blocs.