Componentes

Eclipse UI tiene 42 fichas en el catálogo y todas hablan el mismo idioma: el peligro se dice igual en un botón que en un aviso, el tamaño chico mide lo mismo en un campo que en un botón, y un control de formulario se conecta al modelo de la misma forma. Si sabes usar una pieza, ya sabes usar las demás. Esta página es ese idioma.

Anatomía de un componente

Un componente son unos cuantos archivos legibles, siempre los mismos y siempre en el mismo lugar. Así se ve el de referencia, Deslizar para reservar:

Ningún componente nuevo nace sin los siete. El JavaScript y el CSS solo existen si hacen falta; la ficha, la demo y la prueba, siempre.

La ficha

La ficha (app/views/ui/catalog/<nombre>.yml) es lo que el catálogo lee para armar la página del componente. catalog_test.rb revisa las claves marcadas como obligatorias en cada ficha, en cada corrida de pruebas.

El vocabulario

Cada eje tiene un nombre y una lista corta de valores. Un componente nuevo usa estos nombres o no entra. La columna «hoy lo aceptan» se lee de los parámetros de cada clase al pintar esta página: si alguien agrega o quita un parámetro, la tabla cambia sola.

Tono: tone:

El significado del color, nunca su peso. Son cinco y no hay más: si algo no encaja en uno, es :neutral.

El token se sigue llamando destructive (viene de shadcn); en las APIs se dice siempre danger. Hoy aceptan tone:: Alert, Badge, Button, SlideToConfirm, StatusPill, Toast, Toaster::Toast. Todos lo normalizan con Ui::Vocabulary.tone, así :destructive, :error o :alert llegan como :danger en cualquiera (también en JavaScript: eui:toast y data-confirm-tone); ver nombres anteriores.

Variante: variant:

Cuánto pesa la superficie, nunca el color. Hay dos escaleras: una para acciones y otra para marcas e indicadores. Tono y variante se combinan: el botón de peligro es variant: :primary, tone: :danger.

Hoy aceptan variant:: ActionButton, Badge, Button, PressButton, SegmentedControl. Las piezas que la usaban para otra cosa ya tienen su nombre (shape: en AnimatedTabs, layout: en Accordion, mode: en Dropzone) y aceptan variant: como nombre anterior.

Tamaño: size:

:xs · :sm · :md · :lg · :xl, con :md por defecto. En los controles, cada tamaño es una altura con nombre que sigue el dial de densidad, así un botón y un campo del mismo tamaño quedan alineados.

En las capas (Modal, Sheet, Popover) size: es el ancho preset y un ancho libre va en width:. Avatares y el medidor del eclipse tienen su propia escala con los mismos nombres. Dos excepciones a propósito: StatusPill va de :xs a :sm y el control segmentado arranca en :sm, porque viven en barras compactas.

Forma, disposición, aire y lo que hay detrás

Celebration usaba on: para otra cosa (el evento que la dispara): ahora es event:, y on: sigue sirviendo.

Estado

Los estados que cambian en el navegador no son parámetros: el controlador los escribe en data-state (open, closing, loading, success, error, confirmed…) y el CSS los lee de ahí, junto con data-tone (solo para el tono) y data-side (el lado de una capa).

Slots

Lo que una pieza no puede saber (la acción real, el botón que abre una capa, el pie de un modal) entra por slot. Leídos de los renders_one y renders_many de cada clase:

Si hay un String y un slot para lo mismo (title: y with_title), gana el slot. Las colecciones se llaman como un elemento, en singular: with_item, with_tab, with_option, with_column.

Formularios

Un control se conecta igual en todas partes: name: a mano, o form: + attribute: con el builder, de donde salen el nombre, el id, el valor y el error del modelo. La ayuda se llama hint:. La tabla se lee de cada clase; un nombre en gris es el que esa pieza usa en lugar del canónico.

• Valores: value: para lo libre, selected: para elegir entre opciones, checked: (con unchecked_value:) para un booleano.
• Atributos extra: en un control de una sola pieza nativa (Input, Select, Textarea, Checkbox) **attrs llega al elemento nativo (autocomplete:, inputmode:); en los compuestos llega a la raíz y el control nativo recibe input: {}.
• Enviar solo: lo que manda su formulario al completarse usa requestSubmit, así Turbo lo maneja y se pide con auto_submit: (fechas y código; submit_on_change: y submit: siguen sirviendo).

Eventos

Un componente avisa lo que pasó con <componente>:<verbo> (Stimulus pone el prefijo), con el verbo en presente y detail.value cuando hay un valor. Las órdenes de afuera hacia adentro van con eui:: eui:open y eui:close en un dialog, eui:toast en window. Leídos de los controladores:

Clases y atributos

Todo componente acepta **attrs en su raíz: class: se suma (nunca reemplaza), data: y aria: se mezclan sin pisar el data-controller propio e id: se respeta. Si el look sirve fuera del componente, la clase expone .classes(**) con los mismos parámetros (Ui::ButtonComponent.classes(variant: :secondary) para un button_to). Todavía sin **attrs: Toast.

Los atributos públicos que se pueden poner en cualquier elemento:

Nombres anteriores

Cuando un nombre cambia, el anterior sigue sirviendo: el componente lo acepta en la entrada y pinta exactamente lo mismo, así ninguna vista se rompe. Esta tabla sale de Ui::Vocabulary y su prueba comprueba que cada clase acepte los dos. En código nuevo, usa siempre el de la derecha.

Reglas de API

• Un componente no consulta. Lee lo que ya viene cargado (includes en el controlador) o lo que llega por parámetro (price:, items:); nunca un where ni un count adentro. Los de un pack pueden recibir el modelo completo con un constructor .for(modelo), con la misma regla.
• Las acciones reales van por slot. El componente no sabe si reservar es un button_to, un enlace o un deslizador; la vista sí. El atajo href: + cta_label: existe para el caso simple.
• Los controles mandan su valor. Con name: o form: + attribute:, siempre con un input real (visible u oculto). Sin JavaScript el formulario se envía igual.
• Turbo de fábrica. Lo que envía usa requestSubmit; lo que espera al servidor escucha turbo:submit-start y turbo:submit-end; lo que flota se cierra en turbo:before-cache; los ids que apunta un Turbo Stream son estables.
• Nada se traga un error. Un valor que no existe (tone: :rojo) falla en desarrollo y pruebas con la lista de valores válidos (Ui::Vocabulary.pick); en producción deja un aviso en el log y usa el valor por defecto.
• Textos con valor por defecto en español y un parámetro <parte>_label: para cambiarlos (close_label:, loading_label:).

<%# Los datos entran ya cargados; la acción real, por slot. %>
<%= render Ui::PricingCardComponent.new(name: @plan.name, price: @plan.price, period: "mes", featured: true) do |card| %>
  <% card.with_action do %>
    <%= form_with url: checkout_path(@plan) do %>
      <%= render Ui::SlideToConfirmComponent.new(label: "Desliza para pagar") %>
    <% end %>
  <% end %>
<% end %>

<%# Un control conectado al modelo: nombre, valor y error salen de f. %>
<%= render Ui::InputComponent.new(form: f, attribute: :capacity, label: "Capacidad", trailing: "lugares") %>

Estados de las fichas

Cada ficha dice qué tan lista está la pieza. El estado sale en la tarjeta del índice y arriba de cada ficha, y la app que usa la gema lo vigila con Ui::Catalog.app_usages: una ficha estable debe usarse en alguna de sus vistas, y una pieza que ya se usa debe decir estable.

• De beta a estable: el día que una vista de una app en producción la use, cambia status: estable en su ficha (si no, la prueba de esa app te lo pide). Desde ahí, su API solo cambia con alias.
• De experimental a beta: cuando tiene prueba propia, su ficha completa y pasó la revisión en las personalidades y a 375px.
• Nada baja de estable sin un plan de migración para las vistas que la usan.

Agregar un componente, paso a paso

1. Busca primero en el catálogo y en app/components/ui/. Extender una pieza (un parámetro, un slot) casi siempre gana a crear otra.
2. Nombra con el vocabulario. Antes de escribir código, decide los parámetros con las tablas de arriba: tono, variante, tamaño, slots, formulario, eventos. Normaliza cada valor con Ui::Vocabulary.tone o Ui::Vocabulary.pick: así los alias funcionan y un typo falla en desarrollo.
3. Crea los archivos de la anatomía. Copia la forma de slide_to_confirm_*: cabecera con qué es, cuándo usarlo y un ejemplo.
4. Solo tokens y la escala. Colores, tamaños de texto, radios, sombras y duraciones con nombre (ver Color, Tipografía y Movimiento); íconos del set.
5. Elige el patrón ARIA en la tabla de accesibilidad y completa el teclado.
6. Conéctalo a Rails: name: / form: + attribute:, Turbo y eventos componente:verbo.
7. Escribe la ficha con status: beta, pattern: y keyboard:, y una demo con contenido real que luzca en la tarjeta de 330px y en el escenario.
8. Prueba y corre los guardianes (ver Calidad): tu prueba, la del catálogo, la de las páginas y RuboCop.
9. Míralo en carbón claro y oscuro, eclipse y umbra, y a 375px de ancho, con la consola limpia.
10. Documenta en docs/GUI.md si agregaste un componente, un token o un parámetro del vocabulario.