Kit de componentes y UI

Las extensiones describen su interfaz como JSON ({ "type", "props", "children" }). BloomX lo dibuja con un kit de componentes propio que hereda, sin que la extensión haga nada, la paleta, el radio, la tipografía y el modo claro/oscuro de la empresa. Esta página es la referencia de componentes, tematización, estado, expresiones y acciones; las herramientas para escribirlos y probarlos están en Herramientas de extensiones.

Un componente, una página#

Cada componente del kit tiene su página propia (/docs/extension-ui/<componente>, por ejemplo BUTTON, FORM o TABLE) con la tabla de props generada del esquema, vista previa en vivo con el renderer real, un simulador (editor de props, validación, estado, contexto, backend simulado y registro de eventos) y un ejemplo tomado de un manifest real. El índice de abajo agrupa todos por categoría.

Componentes de página completa#

Pensados para un mount PAGE (una página completa en /extensions/<path>). Cada uno tiene su página con vista previa y simulador con datos simulados (sin backend real). Exigen la capacidad `ui.pages.v1` en requires.capabilities; los clientes antiguos no reciben esas versiones.

La TABLE también ganó, con la misma capacidad: searchable, filtros por columna (columns[].filter), celdas link y status (toneMap, hrefKey), bulkActions, defaultSort y los estados error + onRetry.

Para construir una página completa y enlazarla desde la navegación, sigue Página completa y navegación.

Reglas de tematización#

Regla clave: una extensión no elige colores ni estilos. Solo usa propiedades semánticas y el renderer las traduce a los tokens del tema activo (bg-primary, text-success, border-destructive...), con el contraste exigido por el contrato de temas (Temas empresariales).

• Contraste garantizado: cada par texto/fondo que pinta el kit está declarado y un test lo comprueba en los 8 temas genéricos y en las paletas de empresa de prueba (claro y oscuro). Las superficies "suaves" usan la pareja card/card-foreground con borde de la intención, no tintes translucidos que podrían bajar de 4.5:1.
• Valores inválidos no rompen: un tone desconocido, un gap fuera de escala o un texto donde se espera un número se corrigen al valor por defecto en ejecución y se avisan en el validador.
• Accesible por defecto: roles ARIA, nombres accesibles, foco visible, teclado (flechas, Enter, Espacio, Escape) y foco atrapado en diálogos.

Un ejemplo completo#

{
  "type": "STACK",
  "props": { "gap": 3 },
  "children": [
    { "type": "HEADING", "props": { "level": 3, "content": "Nueva nota" } },
    { "type": "FORM", "props": {
        "submitLabel": "Guardar",
        "successMessage": "Guardado",
        "fields": [
          { "name": "title", "label": "Título", "required": true, "rules": { "maxLength": 80 } },
          { "name": "tags", "label": "Etiquetas", "type": "tags" }
        ],
        "onSubmit": { "action": "CALL_BACKEND", "function": "saveNote",
                      "retry": { "attempts": 3, "delayMs": 400 } } } },
    { "type": "ALERT", "props": { "tone": "danger", "message": "${state.$error.saveNote}", "hidden": "${!state.$error.saveNote}" } }
  ]
}

Catálogo de componentes#

Generado desde ui-schema.ts. Todas las props admiten expresiones ${...} salvo las de tipo nodo o acción. Cada componente admite además hidden (expresión booleana), onLoad, onLoadWhen y ariaLabel. La galería de componentes los muestra en vivo con ejemplos copiables y en todos los temas.

Estructura#

Texto#

Acciones#

Entradas y formularios#

Datos#

Navegación#

Estado y avisos#

Superpuestos#

Gráficos#

Lógica#

Estado y binding#

• state del manifest define el valor inicial; cada mount y cada overlay tiene su propio estado. Lee con ${state.a.b} y escribe con SET_STATE (key admite rutas "a.b").
• Binding bidireccional: bind: "form.email" en cualquier entrada lee y escribe state.form.email; defaultValue se aplica una vez si aún no hay valor; onChange recibe value.
• Dentro de un FORM, las entradas con name se registran solas: validan al enviar y sus valores viajan en formData.
• Carga y error automáticos: CALL_BACKEND/CALL_API mantienen state.$loading.<clave> y state.$error.<clave> (la clave es key o el nombre de la función). Un BUTTON cuyo onClick llama al backend muestra solo su carga, se bloquea y evita el doble envío; un FORM muestra cargando, el error del backend y successMessage.

{
  "state": { "query": "", "rows": [] },
  "mounts": [{ "point": "PAGE", "path": "notas", "component": {
    "type": "STACK", "children": [
      { "type": "INPUT", "props": { "label": "Buscar", "type": "search", "bind": "query" } },
      { "type": "BUTTON", "props": { "label": "Buscar",
          "onClick": { "action": "CALL_BACKEND", "function": "search", "args": { "q": "${state.query}" },
                       "resultKey": "rows" } } },
      { "type": "TABLE", "props": { "rows": "${state.rows}", "columns": [ { "key": "title", "label": "Título", "sortable": true } ],
                                     "loading": "${state.$loading.search}", "pageSize": 10 } }
    ] } }]
}

Expresiones#

Las cadenas ${...} se evalúan sin `eval` con un lenguaje pequeño (los argumentos de filtro son expresiones: los textos van entre comillas, como pluck:'id'; un identificador suelto es una variable): literales, context.x, state.x, variables del evento (value, result, formData, row, error, item), acceso a.b, a?.b, a[0], operadores + - * / % == != < > <= >= && || ! ?: y filtros con |. No se pueden llamar funciones ni salir del alcance dado.

|| devuelve el primer valor no vacío (el valor indefinido, null y la cadena vacía son vacíos; 0 y false no). Una expresión inválida produce vacío en ejecución y un error con ruta y posición en el validador (checkExpression).

Acciones#

Una acción es { "action": "NOMBRE", ... }, un arreglo o { "actions": [...] }; se ejecutan en orden y cada paso ve el estado de los anteriores. onSuccess recibe result; onError recibe error. Sin onError, un fallo muestra un aviso con el motivo (toastOnError: false lo silencia) y se registra para el autor.

CALL_BACKEND: reintento y resultado#

• retry: { attempts: 1-5, delayMs: 0-10000, backoff: "none"|"linear"|"exponential" } reintenta ante error de red o success:false.
• resultKey guarda el resultado en state[resultKey]; args gana sobre los campos del formulario que disparó la acción.
• NAVIGATE solo admite rutas internas (/...), OPEN_URL solo https/http/mailto/tel, CALL_API solo rutas del propio origen. El resto se bloquea con un aviso claro.
• CONFIRM abre un diálogo accesible y encadena onConfirm / onCancel.

Validación y errores#

• Antes de pintar, ExtensionLoader valida el manifest y el UI. Un mount con errores se sustituye por un estado de error amable (el resto de la extensión y de la aplicación siguen funcionando) y el problema se registra para el autor: lo ves en /extensions (errores de ejecución por extensión) y en la consola.
• Los errores llevan la ruta exacta: mounts[0].component.children[2].props.tone: Valor no permitido "sucsess"; permitidos: neutral, primary, ... (¿quisiste decir success?).
• Límites duros por UI: maxNodes 600 · maxDepth 24 · maxString 20000 · maxArray 500 · maxBytes 262144.
• Formularios: rules admite required, minLength, maxLength, min, max, minItems, maxItems, pattern, email, url y message (sustituye al texto genérico). validateOn: submit, blur (por defecto) o change. Los patrones con cuantificadores anidados se rechazan.

Formato antiguo y migración#

Los manifests existentes siguen funcionando: migrateLegacyUi los adapta al cargar y avisa de lo obsoleto (sin tocar el manifest). Conviene migrarlos con el botón Migrar del playground o con el validador.

Iconos de extensiones#

El campo icon (en el manifest y en cualquier prop icon o name de un icono) admite tres formas: `brand:<slug>` (logotipo de una app integrada), `lucide:<Nombre>` (icono funcional) e `initials:<XY>` (1 a 3 letras). El nombre Lucide sin esquema ("Mail") sigue funcionando. No hay URLs de imagen arbitrarias: los logotipos se cargan de forma asíncrona desde el backend de BloomX (/api/extensions/icons/…, con un marcador de letra instantáneo y sin saltos de maquetación), así que cambiar un logo no exige desplegar ni recargar. El icon también puede ser un data URL data:image/png|webp|svg+xml;base64,… (máx. 64 KB, validado).

{
  "id": "acme-zoom",
  "name": "Acme Zoom",
  "icon": "brand:zoom",
  "i18n": {
    "es": { "name": "Zoom", "description": "Crea reuniones de Zoom" },
    "en": { "name": "Zoom", "description": "Create Zoom meetings" }
  },
  "mounts": [{ "point": "COMPOSER_TOOLBAR", "component": { "type": "BUTTON", "props": {
    "label": "Zoom", "icon": "brand:zoom",
    "toolbar": {
      "label": { "es": "Reunión de Zoom", "en": "Zoom meeting" },
      "description": { "es": "Crea una reunión de Zoom", "en": "Create a Zoom meeting" }
    },
    "onClick": { "action": "OPEN_OVERLAY", "targetId": "zoom-modal" } } } }]
}

Los logotipos se pintan con su color oficial sobre una ficha neutra. Si ese color no contrasta al menos 3:1 con el tema activo (Notion negro en un tema oscuro, por ejemplo) se usa una variante más clara u oscura del mismo tono; en menús densos y botones deshabilitados se usa el modo monocromo. El icono es decorativo: el nombre accesible lo da el botón. name y description son el respaldo; i18n.<idioma> los localiza, y el tooltip de una acción usa toolbar.label y toolbar.description por idioma (aparece a los 400 ms, máximo 280 px, el texto envuelve y Esc lo cierra).

Logotipos de marca disponibles#

brand:googlemeet (Google Meet), brand:googlecalendar (Google Calendar), brand:googledrive (Google Drive), brand:googlesheets (Google Sheets), brand:googledocs (Google Docs), brand:googlegemini (Google Gemini), brand:gmail (Gmail), brand:google (Google), brand:zoom (Zoom), brand:notion (Notion), brand:trello (Trello), brand:hubspot (HubSpot), brand:giphy (GIPHY), brand:zoho (Zoho), brand:github (GitHub), brand:gitlab (GitLab), brand:jira (Jira), brand:linear (Linear), brand:asana (Asana), brand:clickup (ClickUp), brand:airtable (Airtable), brand:stripe (Stripe), brand:dropbox (Dropbox), brand:todoist (Todoist), brand:calendly (Calendly), brand:discord (Discord), brand:whatsapp (WhatsApp), brand:telegram (Telegram), brand:anthropic (Anthropic), brand:microsoft (Microsoft), brand:microsoftteams (Microsoft Teams), brand:slack (Slack)

Marcas que no están en el conjunto de logotipos libres (retiradas a petición del titular): se muestran como una ficha neutra con su inicial y nunca se dibujan a mano. brand:microsoftoutlook (Microsoft Outlook), brand:salesforce (Salesforce), brand:openai (OpenAI).

Iconos funcionales recomendados#