Saltar a contenido

Referencia de pantallas: datos, estilo y recetas

Disponible con Kino 0.9.74

Disponible desde Kino 0.9.74. Una versión anterior de Kino rechaza estos plugins con «Este plugin necesita una versión más nueva de Kino»; para seguir llegando a quien tiene una versión anterior usa enhancements (ver Pantallas sin subir tu apiVersion).

Esta es la tercera parte del catálogo de componentes de las pantallas de un plugin:

  • Disposición, contenido y acciones: Column, Row, Card, Text, Image, botones, ListTile, las tarjetas de títulos de Kino y las operaciones locales ui.
  • Formularios, superpuestos y navegación: Form, las entradas, bind y config, ventanas emergentes, avisos y go.
  • Esta página: cómo fluyen los datos y los eventos (estado, entradas, eventos, respuestas, temporizadores), los valores por tamaño, los nombres al estilo Flutter, cada propiedad de estilo y cada token, los límites y recetas para copiar.

La guía, Pantallas, explica el bloque screen del manifiesto, las exportaciones screen() y screenEvent(), el foco en la TV y cómo probar con el kit. El ejemplo de la galería pone en marcha todos los componentes.

Datos y comportamiento

Estado

El estado vive en Kino. Tu entorno de ejecución se cierra tras un rato sin actividad, así que nada de lo que guardes en una variable sobrevive: Kino guarda el estado de la pantalla, lo entrega en cada llamada y vuelve a llamar a screen() después de cada respuesta que trae un parche de state. Un parche se fusiona clave por clave (null borra una clave). Como máximo 64 KB; vive solo mientras la pantalla está abierta esta vez (lo que deba sobrevivir, guárdalo en kino.storage). screen() es una vista pura: nada de red ahí.

{ "state": { "count": 3, "selected": null } }

Entradas (state.inputs)

state.inputs guarda cada entrada de la pantalla por su clave: lo que fijó la persona o tu código, o si no, el valor que muestra el árbol. Para fijar lo que muestra un campo, responde { state: { inputs: { <key>: value } } }: se ve al instante y no dispara ningún evento.

Entrada Valor en state.inputs Reglas del formulario bind guarda
TextField texto required, minLength, maxLength, pattern, errorText text
TextField (varias líneas) texto required, minLength, maxLength, pattern, errorText text
DropdownButton el valor de la opción o null required, errorText select o text
Switch booleano required, errorText toggle
Checkbox booleano required, errorText toggle
RadioGroup el valor de la opción o null required, errorText select o text
Slider número ninguna text
Chips un valor o null (una lista con multiple) required, minLength, maxLength, errorText select o text
NumberStepper su valor como texto ("2.50") required, errorText sin bind

Eventos

  • Un evento a la vez por pantalla; el siguiente espera (como máximo 8 en espera), separados 100 ms, y nunca se descarta por llegar rápido. Un onChanged más nuevo del mismo campo reemplaza a uno anterior que siga esperando.
  • La primera llamada después de abrir la pantalla es el evento reservado open: carga ahí tus datos y responde un parche de state.
  • Una llamada tiene 20 s. Una llamada que se pasa del tiempo muestra el estado de error de la pantalla; tres fallos seguidos también. El tiempo agotado de una pantalla nunca cuenta para el «No responde» del plugin.

Respuestas

Lo que puede responder screenEvent (y un temporizador, el onClose de una ventana emergente, el panelAction de un panel). Todos los campos son opcionales; null significa que no hay nada que hacer. Algunas respuestas no son de la persona, así que conservan menos: la respuesta al evento reservado open descarta su go (salvo go.screen), y la de un «cargar más» nunca cambia la ruta.

Campo Qué hace En la respuesta de un temporizador En una respuesta de onClose En un panel en modo pantalla
state un parche fusionado clave por clave (null borra una clave); luego screen() corre de nuevo se conserva se conserva se conserva
dialog un diálogo emergente: title, body (texto o nodos), como máximo 3 buttons se descarta se descarta se descarta
sheet una hoja inferior en el teléfono, un cajón lateral en la TV: title, body se descarta se descarta se descarta
menu una lista de 1 a 8 acciones: items de { label, icon?, onTap } se descarta se descarta se descarta
toast un mensaje corto: un texto o { text, textEn?, role?, action?, ms? } (ms de 2.000 a 8.000, por defecto 3.500) se conserva se conserva se conserva
toastEn el gemelo en inglés de un toast de texto se conserva se conserva se conserva
go algún lugar de Kino (Navegación) se descarta se descarta se conserva
route { push: name, params? } o { pop: true }: una pantalla tuya más adentro del lienzo se descarta se descarta se descarta
close true cierra la pantalla se conserva se conserva se conserva
focus la clave del nodo que toma el foco se descarta se descarta se conserva
config tus ajustes a escribir, como máximo 32 claves (bind y config) se conserva se conserva se conserva
ui operaciones locales (como máximo 8); un open espera al árbol que pide la respuesta se descarta se conserva, sin open ni focus se conserva
share { key }, apiVersion 17: ese nodo como imagen en la hoja de compartir del sistema (Compartir una imagen); solo la respuesta al toque o envío de la persona se descarta se descarta se descarta
enableJob un id de tarea, apiVersion 17: enciende la fila propia de Kino de esa tarea (Las filas de Kino en Ajustes), solo después del toque de la persona; ninguna respuesta la apaga se descarta se descarta se descarta

Compartir una imagen (share)

share: { key } en una respuesta dibuja un nodo de la pantalla como imagen y abre la hoja de compartir del sistema: una tarjeta para enviar, no una captura de pantalla. Pide apiVersion 17; un plugin con una versión menor se rechaza y queda en el registro.

screenEvent(event) {
  if (event.name === "share") return { share: { key: "card" } };
}
  • Solo después del toque o envío de la propia persona. La respuesta al open reservado, a un temporizador, a un «cargar más», a un cambio o a un onClose lo descarta, y también un panel; igual una respuesta o un árbol nuevo que llega más de 5 s después del toque, y Atrás, un reinicio, un fallo, una ventana emergente más nueva o un dibujo que no pinta nada entre medias. Cada caso queda en el registro.
  • El nodo tiene que ser uno que la persona ve ahora: en el árbol actual o en el cuerpo de una ventana emergente abierta; con state o route en la misma respuesta, en el árbol que esa respuesta pide. Un nodo hidden, uno en una ventana emergente o un elemento de acordeón cerrados, uno en otra página de pages, una clave que nombra una ventana emergente y una clave desconocida se descartan, con registro.
  • Un pageView nunca se comparte entero. Kino no sabe a qué página deslizó la persona, así que un nodo que contiene un pageView, su propia clave o la de un ancestro, se rechaza, con registro. Dentro de uno, solo se puede compartir su primera página, y solo cuando initialPage es 0.
  • Los títulos +18 nunca van en una imagen, ni con el código desbloqueado: TitleCard, TitleRail y TitleGrid los pierden. Un nodo que se queda sin nada se descarta, con registro.
  • La imagen es un PNG de 1080×1350 píxeles, siempre dibujado a 360 dp de ancho y con escala de fuente 1, así que tu diseño no cambia con el teléfono ni el tamaño de fuente de la persona. Tu nodo recibe el área sobre la línea propia de Kino, recortado a ella, con el tema de tu pantalla. La línea de Kino nombra a tu plugin (máximo 24 caracteres), así que una tarjeta nunca pasa por una de Kino; nada tuyo puede taparla.
  • Las imágenes esperan 3 s como máximo; después, el marcador de Kino (o tu fallback). Las animaciones saltan a su final. Los botones y los campos se dibujan, pero no hacen nada; un nodo settings no se dibuja.
  • De una en una: un segundo toque mientras se hace una se descarta. Si falla, Kino lo dice en su propio aviso.
  • El título de la hoja de compartir nombra a tu plugin; no se añade nada a lo que escribe la persona. El archivo queda en la caché privada de Kino, de solo lectura para la app que elija la persona, y se borra en el siguiente compartir. Sin capacidad ni línea de permiso: la persona toca y elige la app.
  • Una TV no tiene hoja de compartir: rechaza share, con registro y sin aviso. Oculta el botón ahí (kino.device, device: "tv").

Temporizadores (every)

La raíz de un árbol (o el screen.every del manifiesto) puede llevar { ms, event } o una lista de ellos: Kino envía ese evento cada ms mientras la pantalla está abierta, visible y Kino en primer plano. Un tic no es la pulsación de nadie: su respuesta conserva solo state, toast, close y config; 3 fallos seguidos apagan ese temporizador; los tics nunca cuentan para «No responde» y nunca corren mientras espera un evento de la persona.

{ "type": "Column", "every": { "ms": 30000, "event": "refresh" }, "children": [{ "type": "Text", "text": "Se actualiza cada 30 s", "textEn": "Refreshes every 30 s" }] }

Valores por tamaño

Cualquier propiedad de estilo o de disposición puede ser un mapa por tamaño { compact?, medium?, expanded? } (las clases de ventana de Material: compact por debajo de 600 dp, medium de 600 a 839, expanded de 840 en adelante; una TV es expanded). Una clase que falta en el mapa toma la siguiente más pequeña presente, o si no, el valor por defecto de Kino. Un nodo cuyo valor no es válido en una sola clase se descarta entero, y un mapa que mezcla clases con otras claves se descarta. devices y sizes dibujan un nodo solo en algunos sitios; ctx.device y ctx.size le permiten a screen() devolver otro árbol.

{ "type": "GridView", "columns": { "compact": 1, "medium": 2, "expanded": 3 }, "gap": { "compact": 8, "expanded": 16 }, "padding": { "compact": 16, "expanded": 32 }, "children": [
  { "type": "Text", "text": "Solo en la TV", "textEn": "TV only", "devices": ["tv"] },
  { "type": "Text", "text": "Solo en ventanas anchas", "textEn": "Wide windows only", "sizes": ["expanded"] }
] }

Nombres al estilo Flutter

Quien conoce Flutter encuentra los mismos nombres. Son la forma documentada; los nombres anteriores en minúsculas se siguen aceptando y los dos dan el mismo árbol. Usa una sola forma: si un nodo trae las dos, gana la de Flutter y el choque queda en el registro. Solo se renombran los nodos: los campos del dialog, sheet y menu de una respuesta, los buttons de un diálogo, los items de un menú, la action de un aviso y las entradas de options y tabs conservan label y onTap. Los componentes propios de Kino (titleCard, titleRail, titleGrid, heroCard, emptyState, errorState, popup, settings) conservan sus nombres.

Nombre al estilo Flutter Nombre anterior Implica
Column col
Row row
Stack box
Card card
Spacer spacer
SizedBox spacer
Divider divider
SingleChildScrollView scroll
GridView grid
Text text
Image image
Icon icon
Badge badge
LinearProgressIndicator progress
CircularProgressIndicator loading
ListView list
Button button
ElevatedButton button variant: "primary"
TextButton button variant: "text"
IconButton button variant: "icon"
TextField textInput
DropdownButton dropdown
Switch toggle
Checkbox checkbox
RadioGroup radioGroup
Slider slider
Chips chips
TabBar tabs
AlertDialog popup kind: "dialog"
BottomSheet popup kind: "sheet"
PopupMenuButton popup kind: "menu"
Form form
MaterialBanner banner
ExpansionTile accordion
Skeleton skeleton
QrImage qr
NumberStepper stepper
DataTable table
TableRow tr
TableCell td
FloatingActionButton fab
ListTile listTile
CircleAvatar avatar
PageView pageView
Scaffold scaffold
AppBar appBar
NavigationBar navigationBar
TextField con multiline: true o maxLines > 1 textArea
Propiedad al estilo Flutter Nombre anterior Dónde
width w cualquier nodo
height h cualquier nodo
minHeight minH cualquier nodo
mainAxisAlignment justify cualquier nodo
crossAxisAlignment align cualquier nodo
flex weight cualquier nodo
borderRadius radius cualquier nodo
onChanged onChange cualquier nodo
onSubmitted onSubmit cualquier nodo
hintText hint cualquier nodo
hintTextEn hintEn cualquier nodo
labelText label cualquier nodo
labelTextEn labelEn cualquier nodo
obscureText secret cualquier nodo
onPressed onTap solo un botón (en otro lado se ignora y queda en el registro)
flex weight una columna de DataTable

Estilo

El estilo sale de escalas fijas, nunca de valores libres; un valor fuera de su escala se descarta y queda en el registro. Todos los nodos aceptan estas propiedades.

Propiedad Nombre anterior Valores Por tamaño
padding 0, 4, 8, 12, 16, 24, 32, 48, o por lado { x, y, top, end, bottom, start } sí
margin 0, 4, 8, 12, 16, 24, 32, 48, o por lado sí
gap 0, 4, 8, 12, 16, 24, 32, 48 sí
borderRadius radius none, small, medium, large, full, o por esquina { topStart, topEnd, bottomStart, bottomEnd } (la que se omite, medium) sí
width w 16, 24, 32, 40, 48, 64, 80, 96, 120, 160, 200, 240, 320, 400, 480, 560, 640 sí
height h 16, 24, 32, 40, 48, 64, 80, 96, 120, 160, 200, 240, 320, 400, 480, 560, 640 sí
minHeight minH 16, 24, 32, 40, 48, 64, 80, 96, 120, 160, 200, 240, 320, 400, 480, 560, 640 sí
fill true: todo el ancho del padre sí
flex weight de 1 a 12: su parte de un Row o un Column sí
crossAxisAlignment align start, center, end, stretch: a lo ancho del eje principal (en un Text, el párrafo) sí
mainAxisAlignment justify start, center, end, spaceBetween, spaceAround: a lo largo del eje principal sí
color primary, secondary, surface, muted, warning, error, onPrimary, primaryContainer, surfaceVariant sí
span de 1 a 12 o "auto" (por defecto), solo en un Row con wrap: true sí
offset de 0 a 11, solo en un Row con wrap: true sí
maxWidthFraction de 0.25 a 1 en pasos de 0.05: como máximo esa parte del ancho del padre (exactamente, con fill) sí
alignSelf start, center, end, stretch: este hijo a lo ancho de su Row o Column, por encima del crossAxisAlignment del padre (propiedades de caja y texto) sí
textAlign start, center, end, justify: el párrafo de un nodo que dibuja texto (Text, Button, Chips, TextField, TextField, ListTile) sí
border { width?, color? } en una caja: ancho de 0 a 8 dp (por defecto 1), un rol de color (por defecto el contorno de Kino) sí
elevation de 0 a 24 en un Card o un Stack: la sombra de Kino (también la elevación tonal de una tarjeta) sí
background un rol de color: el relleno de una caja (su contenido se lee en el color «sobre» de ese rol) sí
minWidth 16, 24, 32, 40, 48, 64, 80, 96, 120, 160, 200, 240, 320, 400, 480, 560, 640 sí
maxWidth 16, 24, 32, 40, 48, 64, 80, 96, 120, 160, 200, 240, 320, 400, 480, 560, 640 sí
maxHeight 16, 24, 32, 40, 48, 64, 80, 96, 120, 160, 200, 240, 320, 400, 480, 560, 640 sí
positioned { top?, left?, right?, bottom?, width?, height? } en un hijo de Stack: dp o "25%" del Stack (Stack posicionado) sí
opacity de 0 a 1; por debajo de 0.38 el nodo no acepta pulsaciones ni foco (animaciones) sí
animate { duration?, curve? } en una caja o un hijo posicionado: los cambios se deslizan (animaciones) sí

Propiedades comunes

Todos los nodos aceptan estas, además de las suyas y las de estilo.

Propiedad Tipo Por defecto Por tamaño Notas
key texto auto-<n> no única en la pantalla; obligatoria en entradas, ventanas emergentes, un ExpansionTile y un aviso que se puede descartar; el prefijo auto- es de Kino
onTap acción ninguna no una pulsación (la de un botón es onPressed)
onLongPress acción ninguna no una pulsación larga; úsala para extras a los que se llega de otra forma
onSwipeLeft, onSwipeRight acción ninguna no aditivo, sin apiVersion nuevo: un deslizamiento lateral (a la izquierda = la página siguiente); en la TV, Derecha / Izquierda cuando el foco ya no tiene a dónde ir (Deslizar)
arg texto ninguno no el arg del evento cuando la acción es solo el nombre de un evento (como máximo 4.096 caracteres)
enabled booleano true no false lo dibuja desactivado; ui enable/disable lo cambian
hidden booleano false no true lo empieza oculto; ui show/hide/toggle lo cambian
devices phone, tv, desktop (una lista) en todas partes no se dibuja solo ahí; un nombre desconocido descarta el nodo
sizes compact, medium, expanded (una lista) todos los tamaños no se dibuja solo en esas clases de ancho
testKey texto ninguno no de 1 a 64 caracteres, para pruebas, nunca se dibuja
autofocus booleano false no un nodo que toma foco: adonde va el foco cuando un dibujado lo dejó en ninguna parte (propiedades compartidas)
selected booleano ninguno no un botón o una tarjeta con onTap: el aspecto de seleccionado de Kino; ui set y toggle (prop: "selected") lo cambian
badge "dot" o { text, textEn?, color? } ninguno no un botón, una tarjeta con onTap, una pestaña: un número (como máximo 12 caracteres) o un punto en su esquina superior final
visible booleano true no false lo oculta igual que hidden: true (animaciones)
tooltip texto ninguno no un nodo que hace algo: la pista de Kino (tooltipEn), como máximo 80 caracteres; nunca información esencial (tooltip)
enabledAt epoch ms ninguno no un botón, un FloatingActionButton, una tarjeta o un ListTile con onTap: desactivado hasta esa hora en el reloj del aparato, luego se activa solo, sin llamarte (texto con una hora)
canRequestFocus booleano false no cualquier nodo: en la TV, una parada del D-pad donde el control se detiene para leerlo (el aspecto de fila de Kino, sin pulsación); se ignora donde el nodo ya toma foco y en el teléfono (propiedades compartidas)
loading booleano false no un botón, un FloatingActionButton, una tarjeta o un ListTile con onTap: el aspecto de ocupado de Kino (un indicador giratorio, sin pulsación, se lee como ocupado); Kino también lo dibuja en el nodo pulsado mientras su llamada tarda (pulsaciones ocupadas y lentas)

Propiedades compartidas

Kino nunca agrega un componente por cada necesidad: una familia de nodos comparte una propiedad con un mismo significado en todas partes.

  • autofocus: true en un nodo que toma foco (un botón, una entrada, un TabBar, un titleCard, o cualquier nodo con onTap u onLongPress): en un dibujado (un tic o una respuesta) que dejó el foco en ninguna parte, o en un nodo que ya no está, el foco va al primer nodo con autofocus en el orden del árbol. El focus propio de una respuesta gana, y un nodo que todavía tiene el foco lo conserva. Esto es sobre todo para la TV: una pantalla que cambia con un temporizador (una descarga terminada, un evento en vivo que acabó) pone el control en su único camino para seguir. En un teléfono un campo de texto nunca recibe autofoco (ningún teclado se abre solo). En otro lado se ignora y queda en el registro.
  • canRequestFocus: true (el nombre de Flutter) en cualquier nodo que no toma foco por sí mismo (un Card de estado, un Text, un Row, un Column, un DataTable, un MaterialBanner sin acción): en la TV se vuelve una parada del D-pad donde el control se detiene para leerlo, con el aspecto de fila de Kino (un tinte tonal y un subrayado de acento, nunca el anillo blanco), sin pulsación (OK no hace nada). Participa en Arriba, Abajo, Izquierda, Derecha y las reglas del Scaffold como cualquier parada, y un lector de pantalla lee su contenido. Se ignora en un nodo que ya toma foco y en el teléfono; nunca por tamaño. Receta, una tarjeta de estado como parada de lectura en la TV: { "type": "Card", "key": "status", "canRequestFocus": true, "children": [ ... ] }. Sin ella la TV igual muestra la tarjeta: un cuerpo con desplazamiento avanza por páginas (80 % de su alto) antes de que el foco pase de largo un bloque que todavía no se ha mostrado.
  • selected: true | false en un botón (cualquier variante) o una tarjeta con onTap: el aspecto de seleccionado de Kino (tonal relleno; una tarjeta recibe un contorno en el color primario), que un lector de pantalla lee como seleccionado. Es estado, no una acción; ui set y toggle con prop: "selected" lo cambian sin llamarte (Operaciones ui locales). Chips y TabBar dicen cuál está seleccionado con su value. En la TV el foco no cambia.
  • badge: el valor del nodo Badge, "dot" o { text, textEn?, color? } (un número o una palabra corta, como máximo 12 caracteres; color un rol de color, por defecto el primario de Kino), en un botón, una tarjeta con onTap, una pestaña de TabBar (en su entrada de tabs) y una pestaña del cajón de un panel (en los tabs del resultado del panel). Se pone en la esquina superior final del nodo (junto a la etiqueta de una pestaña) y un lector de pantalla lo lee después del nombre del nodo («Chat, 3»; un punto se lee «nuevo»). Ponlo en cada dibujado.
{ "type": "Column", "children": [
  { "type": "TabBar", "key": "tabs", "value": "chat", "onChanged": "tab", "tabs": [
    { "value": "room", "label": "Sala", "labelEn": "Room" },
    { "value": "chat", "label": "Chat", "badge": { "text": "3" } }] },
  { "type": "Row", "gap": 8, "children": [
    { "type": "IconButton", "key": "mute", "icon": "close", "labelText": "Silencio", "labelTextEn": "Mute", "selected": true,
      "onPressed": { "ui": [{ "toggle": "mute", "prop": "selected" }], "event": "mute" } },
    { "type": "IconButton", "key": "downloads", "icon": "download", "labelText": "Descargas", "labelTextEn": "Downloads", "badge": "dot", "onPressed": "downloads" },
    { "type": "ElevatedButton", "key": "retry", "labelText": "Reintentar", "labelTextEn": "Try again", "autofocus": true, "onPressed": "retry" }] }
] }

maxWidthFraction (de 0.25 a 1 en pasos de 0.05) y borderRadius por esquina son de estilo: todos los nodos aceptan el primero, y todo nodo que dibuja una caja el segundo; el anillo de foco de la TV sigue las esquinas.

Propiedades de caja y texto

Propiedades de estilo, todas por tamaño, cada una un token o un rol de color, nunca un valor libre:

Propiedad La aceptan Qué hace
alignSelf un hijo de un Row, Column, Card, Form o desplazamiento start, center, end, stretch a lo ancho de su padre, por encima del crossAxisAlignment del padre; en una fila stretch se dibuja como start (Kino no mide alturas intrínsecas); en otro lado, también la celda de una fila que se ajusta, se ignora y queda en el registro
textAlign Text, la etiqueta de un botón, Chips, TextField, ListTile start, center, end, justify; en un Text gana sobre la lectura anterior de crossAxisAlignment como párrafo. La TV dibuja sus propias entradas de campos y acciones, ajustadas a su texto: ahí se nota en un Text
border una caja: Column, Row, Stack, Card, desplazamiento, GridView, Form, ListTile, PageView { width?, color? }: de 0 a 8 dp (por defecto 1; fuera de rango se ajusta al límite), un rol de color (por defecto el contorno de Kino); sigue borderRadius; una tarjeta seleccionada conserva el contorno primario de Kino
elevation Card, Stack de 0 a 24 (ajustado al límite): la sombra de Kino, que sigue la forma; una tarjeta simple además se eleva tonalmente. Sin sombras libres
background una caja un rol de color: el relleno (por encima de color, que una caja sigue leyendo como su relleno); el texto y los iconos de adentro se leen en el color «sobre» de ese rol, y un Text o Icon coloreado con un rol que no se leería sobre ese relleno se dibuja en el color legible del relleno
minWidth, maxWidth, maxHeight cualquier nodo la escala de tamaños, junto a minHeight; un mínimo mayor que su máximo descarta el máximo y queda en el registro
{ "type": "Column", "crossAxisAlignment": "start", "children": [
  { "type": "Card", "border": { "width": 2, "color": "primary" }, "elevation": 3, "maxWidth": 320, "alignSelf": "center",
    "children": [{ "type": "Text", "text": "Centrado", "textEn": "Centred", "textAlign": "center", "fill": true }] },
  { "type": "Stack", "background": "primaryContainer", "padding": 12, "children": [{ "type": "Text", "text": "Destacado", "textEn": "Highlighted" }] }
] }

Animaciones (animate, opacity, visible)

AnimatedContainer, AnimatedOpacity y AnimatedSwitcher de Flutter reunidos en una sola propiedad de estilo: animate: { duration?, curve? } en una caja (o un hijo positioned): los cambios de su tamaño, su opacity, su relleno, su lugar en un Stack y su visibilidad entre dos dibujados se deslizan durante duration ms (de 100 a 600, por defecto 250, ajustado al límite) siguiendo curve (standard, ease, decelerate). opacity (de 0 a 1, cualquier nodo) lo desvanece; por debajo de 0.38 el nodo no acepta pulsaciones ni foco. visible: false oculta un nodo igual que hidden: true (ui show y hide siguen funcionando); con animate aparece y desaparece desvaneciéndose y plegándose, y mientras se va no acepta nada. La opción «quitar animaciones» del aparato (escala de duración de animación 0) vuelve cada una un salto; una animación nunca retrasa una pulsación ni el foco; como máximo 24 nodos animándose por pantalla (el resto descarta animate y queda en el registro).

{ "type": "Card", "key": "details", "animate": { "duration": 300, "curve": "decelerate" }, "visible": true,
  "background": "surfaceVariant", "children": [{ "type": "Text", "text": "Más información", "textEn": "More details" }] }

Tokens

Token Valores
Espaciado (padding, margin, gap) 0, 4, 8, 12, 16, 24, 32, 48
Tamaños (width, height, minHeight) 16, 24, 32, 40, 48, 64, 80, 96, 120, 160, 200, 240, 320, 400, 480, 560, 640
Esquinas (borderRadius) none, small, medium, large, full (uno para todas las esquinas, o un mapa por esquina)
Roles de color (color) primary, secondary, surface, muted, warning, error, onPrimary, primaryContainer, surfaceVariant
Roles (MaterialBanner, un toast) info, warning, error, success
Estilos de texto (Text.style) hero, h1, h2, h3, h4, h5, p, caption, label
Tamaños de tarjeta (titleCard, titleRail, QrImage) small, medium, large
Clases de ancho (mapas por tamaño, sizes) compact, medium, expanded
Aparatos (devices, ctx.device) phone, tv, desktop
Iconos (Icon.name, el icon de un botón) info, tune, settings, star, bolt, language, subtitles, list, magic, heart, movie, tv, sports, music, bookmark, help, refresh, sync, add, remove, delete, edit, search, close, check, share, play, pause, download, upload, link, open_in_new, home, person, lock, notifications, warning, error, visibility, copy, arrow_back, arrow_forward, expand_more, expand_less, more_vert, filter_list, calendar, schedule, send, mood

No están en esta versión: deslizar para actualizar, botones segmentados, autocompletado y cuadros combinados, selectores de fecha y hora, un control deslizante de rango, una calificación, elementos de lista que se descartan o se reordenan, texto enriquecido, gráficos, tarjetas de «seguir viendo» y de canales, y entradas de archivo. Detecta un componente que agregue un Kino más nuevo con kino.screen.names.includes("DataTable").

Límites

Límite Valor Qué
maxConfigKeys 32 ajustes que escribe un config
maxDepth 10 profundidad de un árbol
maxNodes 600 nodos en un árbol
maxListItems 500 elementos de una lista, fila, cuadrícula, acordeón o de las opciones de una elección
maxStateBytes 65.536 (64 KB) bytes del estado, como JSON
maxTextChars 2.000 caracteres de un texto
minEventIntervalMs 100 ms entre dos eventos
callTimeoutMs 20.000 ms por llamada a screen o screenEvent
maxPopups 1 ventana emergente abierta a la vez
maxRefChars 4.096 caracteres de un ref o un arg
maxSearchQueryChars 200 caracteres del q de un go.search
eventQueue 8 eventos en espera
maxUiOps 8 operaciones ui por acción o respuesta
maxDialogButtons 3 botones en un diálogo
maxWeight 12 el mayor flex
maxGridColumns 8 el mayor columns
maxTestKeyChars 64 caracteres de un testKey
maxTrailingLabelChars 40 caracteres del trailingLabel de un campo de texto
maxHeroButtons 2 botones en un heroCard
maxMenuItems 8 elementos de un menú
maxTitles 1.000 títulos en todo un árbol
maxFlatTitles 60 títulos en una fila o cuadrícula dibujada de una vez
maxPatternChars 200 caracteres de un pattern
maxPatternRepeat 1.000 la mayor repetición en un patrón
maxPatternStates 500 pasos de un patrón con las repeticiones expandidas
maxPatternFields 16 patrones que corre un envío
maxPatternCompileWork 20.000 unidades de trabajo para leer un patrón
maxPatternMatchWork 4.000.000 pasos del comparador que corre un envío
minTimerMs 1.000 temporizador más corto, ms
maxTimerMs 86.400.000 temporizador más largo, ms
maxTimers 3 temporizadores por pantalla
timerMaxFailures 3 fallos seguidos que apagan un temporizador
toastMinMs 2.000 toast más corto, ms
toastMaxMs 8.000 toast más largo, ms
toastDefaultMs 3.500 duración por defecto de un toast, ms
timerConfigWriteIntervalMs 60.000 ms entre dos escrituras de un mismo ajuste desde un temporizador
maxQrChars 1.000 caracteres del valor de un QrImage
maxStepperDecimals 6 decimales de un NumberStepper
maxStepperAbs 1.000.000.000.000.000 el mayor número de un NumberStepper, en positivo o negativo
maxSkeletonLines 6 líneas de un Skeleton
maxTableColumns 20 columnas de un DataTable
maxTableRows 200 filas de un DataTable
maxColSpan 8 el mayor colSpan
gridColumns 12 columnas de la fila de doce columnas
maxGoRouteChars 64 caracteres del route de un go.screen
maxGoArgsBytes 4.096 (4 KB) bytes de los args de un go.screen, como JSON

Panel del reproductor

El panel del reproductor se puede armar con los mismos nodos: panel(context) puede devolver { format: "screen", root, ... }, un árbol de pantalla dentro del cajón de Kino. Todo lo que hace falta está en El panel del reproductor:

  • el panel en modo pantalla: el resultado, el texto más pequeño en la TV, qué campos de la respuesta conserva;
  • pestañas aportadas (playerPanelTab): tu pestaña en el panel del título de cualquier plugin;
  • el panel fijado: acoplado junto al video;
  • layout: "fill" y un ListView con stickToBottom: una pestaña de chat cuya fila de escritura se queda abajo del panel.

Recetas

Copia, pega, adapta. Cada una es un screen completo (y su screenEvent cuando tiene eventos); el ejemplo de la galería pone en marcha la mayoría.

Cuadrícula de tarjetas de noticias

Una tarjeta por línea en un teléfono, dos en una ventana mediana, tres en una TV; tarjetas sin margen interno con una imagen y un respaldo; un toque lee la noticia en una ventana emergente declarada que abre la respuesta.

const STORIES = [
  { id: "a", title: "Un estreno", source: "Kino", image: "https://peach.blender.org/wp-content/uploads/title_anouncement.jpg" },
  { id: "b", title: "Otra noticia", source: "Guía", image: "" },
];

export async function screen({ state }) {
  const reading = STORIES.find((s) => s.id === state.reading);
  const card = (s) => ({
    type: "Card", key: "story-" + s.id, flush: true, span: { compact: 12, medium: 6, expanded: 4 }, onTap: { event: "read", arg: s.id },
    children: [
      { type: "Image", ...(s.image ? { url: s.image } : {}), aspect: "16:9", alt: s.title, fallback: { type: "Stack", color: "surface", children: [{ type: "Text", text: s.source, style: "h3", padding: 12 }] } },
      { type: "Column", padding: 12, gap: 4, children: [{ type: "Text", text: s.title, style: "h4", maxLines: 3 }, { type: "Text", text: s.source, style: "caption", color: "muted" }] },
    ],
  });
  return { type: "Column", children: [
    { type: "SingleChildScrollView", flex: 1, children: [{ type: "Row", wrap: true, gap: 12, padding: 16, children: STORIES.map(card) }] },
    { type: "AlertDialog", key: "story", title: reading ? reading.title : "", onClose: "closed", children: [{ type: "Text", text: reading ? reading.source : "…" }] },
  ] };
}

export async function screenEvent({ name, arg }) {
  if (name === "read") return { state: { reading: arg }, ui: [{ open: "story" }] };
  if (name === "closed") return { state: { reading: null } };
  return null;
}

Formulario de ajustes con validación

Un formulario cuyo envío Kino revisa primero; la respuesta escribe tus ajustes con config (el manifiesto declara greeting como un ajuste text y density como un select).

export async function screen() {
  return { type: "SingleChildScrollView", children: [{ type: "Form", key: "prefs", onSubmitted: "save", gap: 12, padding: 16, children: [
    { type: "TextField", key: "greeting", labelText: "Saludo", labelTextEn: "Greeting", required: true, maxLength: 40, pattern: "^[A-Za-z ]+$", errorText: "Solo letras", errorTextEn: "Letters only" },
    { type: "RadioGroup", key: "density", labelText: "Densidad", value: "normal", options: [{ value: "compact", label: "Compacta" }, { value: "normal", label: "Normal" }, { value: "roomy", label: "Amplia" }] },
    { type: "ElevatedButton", labelText: "Guardar", labelTextEn: "Save", submit: true },
  ] }] };
}

export async function screenEvent({ name, value }) {
  if (name !== "save") return null;
  return { config: { greeting: value.greeting, density: value.density }, toast: "Guardado", toastEn: "Saved" };
}

Ventana de confirmación

La forma rápida es el confirm de un botón (Kino pregunta y luego corre la acción); la forma a tu medida es un diálogo desde la respuesta.

export async function screen({ state }) {
  return { type: "Column", gap: 12, padding: 16, children: [
    { type: "Text", text: state.deleted ? "Lista borrada" : "Tu lista" },
    { type: "TextButton", labelText: "Borrar (rápido)", confirm: "¿Borrar la lista?", confirmEn: "Delete the list?", onPressed: "delete" },
    { type: "Button", variant: "secondary", labelText: "Borrar (diálogo)", onPressed: "ask" },
  ] };
}

export async function screenEvent({ name }) {
  if (name === "ask") return { dialog: { title: "¿Borrar la lista?", body: "No se puede deshacer.", buttons: [{ label: "Borrar", event: "delete", variant: "primary" }, { label: "Cancelar", variant: "text" }] } };
  if (name === "delete") return { state: { deleted: true }, toast: { text: "Borrada", role: "success" } };
  return null;
}

Pestañas con chips

Un TabBar cuyo valor guardas en tu estado, y Chips que filtran la lista de la pestaña.

const ALL = [{ t: "Big Buck Bunny", k: "movies" }, { t: "Sintel", k: "movies" }, { t: "Una serie", k: "series" }];

export async function screen({ state }) {
  const tab = state.tab === "saved" ? "saved" : "all";
  const filter = typeof state.inputs?.kind === "string" ? state.inputs.kind : "any";
  const list = ALL.filter((x) => filter === "any" || x.k === filter);
  return { type: "Column", children: [
    { type: "TabBar", key: "tabs", value: tab, onChanged: "tab", tabs: [{ value: "all", label: "Todo", labelEn: "All" }, { value: "saved", label: "Guardado", labelEn: "Saved" }] },
    { type: "Chips", key: "kind", value: filter, padding: 8, options: [{ value: "any", label: "Todo" }, { value: "movies", label: "Películas" }, { value: "series", label: "Series" }], onChanged: "filter" },
    { type: "ListView", key: "list", flex: 1, items: list.map((x, i) => ({ type: "Text", key: "x" + i, text: x.t, padding: 12 })), empty: { type: "emptyState", title: "Nada", titleEn: "Nothing" } },
  ] };
}

export async function screenEvent({ name, value }) {
  if (name === "tab") return { state: { tab: value } };
  if (name === "filter") return { state: {} }; // the chip's value is already in state.inputs: just draw again
  return null;
}

Matriz de botones (estilo calculadora)

Botones en una fila de doce columnas, tres columnas cada uno (cuatro por línea), cada uno con su propia key y con tamaño por clase: en una TV el D-pad la recorre como una matriz. Un plugin de calculadora completo se arma de la misma forma.

const KEYS = ["7", "8", "9", "÷", "4", "5", "6", "×", "1", "2", "3", "−", "C", "0", ".", "+"];

export async function screen({ state }) {
  const shown = typeof state.shown === "string" ? state.shown : "0";
  return { type: "Column", gap: 12, padding: 16, children: [
    { type: "Card", variant: "filled", children: [{ type: "Text", text: shown, style: "h1", crossAxisAlignment: "end" }] },
    { type: "Row", wrap: true, gap: 8, children: KEYS.map((k, i) => ({
      type: "Button", key: "k" + i, variant: /\d|\./.test(k) ? "secondary" : "primary", labelText: k,
      onPressed: "key", arg: k, span: 3, fill: true, height: { compact: 80, medium: 64, expanded: 48 },
    })) },
  ] };
}

export async function screenEvent({ name, arg, state }) {
  if (name !== "key") return null;
  const now = typeof state.shown === "string" ? state.shown : "0";
  return { state: { shown: arg === "C" ? "0" : (now === "0" ? "" : now) + arg } };
}

Una pantalla con barra superior, pestañas y botón flotante

Una raíz Scaffold: la barra con un botón para volver, una acción de búsqueda y dos pestañas; una lista perezosa en el cuerpo; un botón «Nueva» encima de una barra inferior de tres secciones. Tu estado guarda la pestaña y la sección (ninguna está en state.inputs).

export async function screen({ state }) {
  const tab = state.tab === "saved" ? "saved" : "all";
  const section = ["home", "lists", "me"].includes(state.section) ? state.section : "home";
  const rows = (tab === "saved" ? ["Guardado 1"] : ["Uno", "Dos", "Tres"]).map((t, i) => ({ type: "ListTile", key: "r" + i, title: t, onTap: "show", arg: String(i) }));
  return {
    type: "Scaffold",
    appBar: {
      type: "AppBar", title: "Mis listas", titleEn: "My lists",
      leading: { type: "IconButton", icon: "arrow_back", labelText: "Atrás", labelTextEn: "Back", onPressed: { close: true } },
      actions: [{ type: "IconButton", icon: "search", labelText: "Buscar", labelTextEn: "Search", onPressed: "search" }],
      bottom: { type: "TabBar", key: "tabs", value: tab, onChanged: "tab", tabs: [{ value: "all", label: "Todo", labelEn: "All" }, { value: "saved", label: "Guardado", labelEn: "Saved" }] },
    },
    body: { type: "ListView", key: "rows", items: rows },
    floatingActionButton: { type: "FloatingActionButton", icon: "add", labelText: "Nueva", labelTextEn: "New", onPressed: "newList" },
    bottomNavigationBar: { type: "NavigationBar", value: section, onChanged: "section", items: [
      { key: "home", icon: "home", label: "Inicio", labelEn: "Home" },
      { key: "lists", icon: "list", label: "Listas", labelEn: "Lists" },
      { key: "me", icon: "person", label: "Yo", labelEn: "Me" },
    ] },
  };
}

export async function screenEvent(e) {
  if (e.name === "tab") return { state: { tab: e.value } };
  if (e.name === "section") return { state: { section: e.value } };
  return null;
}

Pestañas en la barra superior

La barra de título propia de Kino ya nombra la pantalla, así que la barra superior puede llevar las pestañas mismas: un TabBar como title, junto a las acciones, de una fila de alto.

export async function screen({ state }) {
  const tab = ["account", "connection", "help"].includes(state.tab) ? state.tab : "account";
  return {
    type: "Scaffold",
    appBar: {
      type: "AppBar",
      title: { type: "TabBar", key: "tabs", value: tab, onChanged: "tab", tabs: [
        { value: "account", label: "Cuenta", labelEn: "Account" },
        { value: "connection", label: "Conexión", labelEn: "Connection" },
        { value: "help", label: "Inicio y ayuda", labelEn: "Start and help" },
      ] },
      actions: [
        { type: "IconButton", icon: "refresh", labelText: "Actualizar", labelTextEn: "Refresh", onPressed: "refresh" },
        { type: "IconButton", icon: "help", labelText: "Ayuda", labelTextEn: "Help", onPressed: "help" },
      ],
    },
    body: { type: "SingleChildScrollView", children: [{ type: "Column", padding: 16, gap: 12, children: [{ type: "Text", text: "Pestaña: " + tab }] }] },
  };
}

export async function screenEvent(e) {
  return e.name === "tab" ? { state: { tab: e.value } } : null;
}

Una vista de búsqueda que Atrás cierra primero

Una sola barra (mergeWithKinoBar: tu leading donde estaba Cerrar, tu título en lugar del nombre del plugin) y un Atrás que primero sale de la búsqueda y luego de la pantalla: mientras state.searching es verdadero el árbol declara onBack, y su respuesta apaga la marca, así el siguiente Atrás cierra la pantalla.

export async function screen({ state }) {
  const searching = state.searching === true;
  return {
    type: "Scaffold",
    // Declared only while there is something for Back to undo.
    onBack: searching ? "close_search" : undefined,
    appBar: {
      type: "AppBar", mergeWithKinoBar: true,
      title: searching ? "Buscar" : "Mis listas", titleEn: searching ? "Search" : "My lists",
      leading: searching
        ? { type: "IconButton", icon: "arrow_back", labelText: "Cerrar la búsqueda", labelTextEn: "Close search", onPressed: "close_search" }
        : { type: "IconButton", icon: "close", labelText: "Cerrar", labelTextEn: "Close", onPressed: { close: true } },
      actions: searching ? [] : [{ type: "IconButton", icon: "search", labelText: "Buscar", labelTextEn: "Search", onPressed: "open_search" }],
    },
    body: { type: "Column", padding: 16, gap: 12, children: [
      searching
        ? { type: "TextField", key: "q", labelText: "Buscar", labelTextEn: "Search", autofocus: true }
        : { type: "Text", text: "Tus listas", textEn: "Your lists" },
    ] },
  };
}

export async function screenEvent(e) {
  if (e.name === "open_search") return { state: { searching: true } };
  if (e.name === "close_search") return { state: { searching: false } };
  return null;
}

Un lector: páginas que se ajustan al ancho, zoom y un punto que se guarda

Para manga, webtoons, cómics y documentos largos. Cuatro piezas pequeñas, cada una útil por sí sola:

  • Image con fit: "width": la imagen toma el ancho de su caja y su alto propio, así una página nunca se corta (sin medir bytes, sin tabla de tamaños). El aspect (cualquier "w:h", como "1.4:1") solo guarda el lugar hasta que carga.
  • zoom: true en el desplazamiento vertical: pellizcar, doble toque y arrastrar; el contenido se dibuja más ancho, así la imagen se ve nítida.
  • onScroll: dónde se detuvo la persona, de 0 (arriba) a 1 (final), 0,3 s después de que se detiene. Guárdalo en kino.storage.
  • pages con reverse: true y progress: "bar": una página a la vez, deslizada de izquierda a derecha, o de derecha a izquierda para manga, hasta 250 páginas, con una barra fina en vez de un segmento por página. Una página que contiene un desplazamiento con zoom lo amplía; un dedo sobre una página sin ampliar sigue deslizando.
export async function screen({ state }) {
  const pages = state.pages ?? []; // [{ url }]
  if (state.mode === "paged") {
    return { type: "pages", key: "pgs", flex: 1, reverse: state.rtl === true, progress: "bar", onPageChanged: "page",
      children: pages.map((p, i) => ({ type: "SingleChildScrollView", key: "z" + i, zoom: true, children: [
        { type: "Image", url: p.url, fit: "width", aspect: "2:3", alt: "Página " + (i + 1), altEn: "Page " + (i + 1) } ] })) };
  }
  return { type: "SingleChildScrollView", key: "strip", flex: 1, zoom: true, onScroll: "scrolled",
    children: [{ type: "Column", crossAxisAlignment: "center",
      children: pages.map((p, i) => ({ type: "Image", key: "p" + i, url: p.url, fit: "width", aspect: "2:3" })) }] };
}

export async function screenEvent({ name, value }) {
  if (name === "scrolled" || name === "page") { kino.storage.set("at", String(value)); return null; } // the place to resume
  return null;
}
  • Un nodo pages necesita una key propia y 2 o más hijos; con progress: "segments" (el valor por defecto), 8 como máximo.
  • onScroll es para un desplazamiento vertical que se desplaza solo (la tira); dentro de pages, la página a la que llegó la persona viene de onPageChanged.
  • Retoma una página con un set de ui sobre la key del pages en la respuesta que abre el capítulo: ui: [{ set: { key: "pgs", value: 4 } }].
  • A la tira vertical no se le puede ordenar que se desplace a una posición guardada: guarda el punto, muéstralo y deja que la persona se desplace.

PageView con viewportFraction menor que 1: la página siguiente asoma por el lado, pasa sola y Kino dibuja los puntos.

const page = (it, i) => ({ type: "Card", key: "car-" + i, variant: "filled", radius: "large", margin: 8,
  onTap: { event: "series", arg: it.url },
  children: [{ type: "Row", gap: 16, padding: 16, crossAxisAlignment: "center", children: [
    { type: "Card", flush: true, radius: "medium", elevation: 6, children: [
      { type: "Image", url: it.poster, width: 120, aspect: "2:3", alt: it.title } ] },
    { type: "Column", gap: 8, flex: 1, crossAxisAlignment: "start", children: [
      { type: "Badge", text: "#" + (i + 1), color: "primary" },
      { type: "Text", text: it.title, style: "h3", maxLines: 3 },
      { type: "ElevatedButton", icon: "play", radius: "full", labelText: "Ver", labelTextEn: "See", onPressed: { event: "series", arg: it.url } },
    ] } ] }] });

// placeholders until your data loads: a PageView with no pages draws nothing
const DEMO = [{ url: "/a", title: "Uno", poster: "https://example.com/a.jpg" }, { url: "/b", title: "Dos", poster: "https://example.com/b.jpg" }];

export async function screen({ state }) {
  return { type: "SingleChildScrollView", children: [
    { type: "Text", text: "Tendencias", textEn: "Trending", style: "h3", padding: 16 },
    { type: "PageView", key: "carousel", viewportFraction: { compact: 0.9, medium: 0.6, expanded: 0.42 }, padEnds: false,
      autoPlayMs: 5000, children: (state.trending ?? DEMO).slice(0, 6).map(page) } ] };
}

Cada página cuenta para los 600 nodos de una pantalla: una página como esta son unos 9 nodos, así que seis páginas cuestan 54. Deja el carrusel en 6 a 8 páginas y recorta los rieles que van debajo.

Una tarjeta del Home de Kino que abre tu pantalla, con una portada a la que volver

Un elemento de una fila de home() lleva open: { screen }: al tocarlo abre tu pantalla en vez de la página del título, desde las filas del Home de Kino y desde sus estantes de categorías. Dale args, no una ruta, para que la pantalla se abra en tu portada (ruta main) y apiles el detalle encima: así Atrás cae en tu portada en vez de no hacer nada.

export async function home() {
  return [{ id: "trending", title: "Mangas populares", items: titles.map((t) => ({
    id: t.slug, ref: t.url, title: t.title, kind: "movie", poster: t.poster,
    open: { screen: { args: { open: t.url } } },          // no route: the screen opens as "main"
  })) }];
}

export async function screenEvent({ name, route }) {
  if (name === "open" && typeof route?.args?.open === "string") {
    const detail = await loadSeries(route.args.open);       // your own loader
    return { state: { detail }, route: { push: "detail", params: { url: route.args.open } } }; // front page below, detail on top
  }
  return null;
}
  • Un plugin que no reproduce nada declara "catalogOnly": true; dale a sus elementos kind: "movie" (un elemento series necesita episodes).
  • Comprueba tú route.args.open (una ruta que reconozcas): viene de una fila guardada que escribió una versión anterior del plugin.
  • Kino guarda las filas de home() 6 horas y las descarta cuando cambia la versión del plugin.

Buscar dentro del campo, con esqueletos mientras carga

Un TextField puede llevar su propio icono de búsqueda (trailingIcon, trailingLabel, onTrailingTap), así que no hace falta un botón aparte ni un Form. Muestra al instante una cuadrícula de esqueletos oculta con una operación ui local, y ocúltala en la respuesta: la pantalla nunca se queda congelada mientras tu screenEvent consulta.

const SEARCH = { ui: [{ show: "loading" }, { hide: "results" }], event: "search" };
const card = (r) => ({ type: "Card", key: "r-" + r.id, onTap: { event: "series", arg: r.id }, children: [{ type: "Text", text: r.title, padding: 8 }] });

export async function screen({ state }) {
  return { type: "SingleChildScrollView", children: [{ type: "Column", children: [
    { type: "TextField", key: "q", kind: "search", padding: 16, labelText: "Buscar", labelTextEn: "Search",
      trailingIcon: "search", trailingLabel: "Buscar", trailingLabelEn: "Search", onSubmitted: SEARCH, onTrailingTap: SEARCH },
    { type: "Column", key: "loading", hidden: true, padding: 12, children: [{ type: "GridView", columns: 3, gap: 12,
      children: [0, 1, 2, 3, 4, 5].map((i) => ({ type: "Column", key: "sk" + i, gap: 8, children: [
        { type: "Skeleton", shape: "block", height: 200 }, { type: "Skeleton", shape: "line", lines: 2 } ] })) }] },
    { type: "Column", key: "results", children: (state.results ?? []).map(card) },
  ] }] };
}

export async function screenEvent({ name, value }) {
  if (name !== "search") return null;
  const results = await find(String(value ?? "").trim());   // the field's text arrives as `value`
  return { state: { results }, ui: [{ hide: "loading" }, { show: "results" }] }; // also in the answer to a failure
}

Aquí los esqueletos le ganan al spinner: conservan la forma de la cuadrícula, así nada salta cuando llegan los resultados.

Filtros en una hoja inferior, con un campo de búsqueda

Tres o cuatro filtros como botones (Género: Todos ▾) que abren una BottomSheet; una lista larga (géneros) lleva un campo de búsqueda. Elegir una fila cierra la hoja y muestra esqueletos mientras carga la página nueva, todo con operaciones ui locales en el toque.

const BUSY = [{ show: "skeleton" }, { hide: "grid" }];

const sheet = (key, title, options, current, event, q) => ({ type: "BottomSheet", key, title, children: [
  options.length > 8 ? { type: "TextField", key: "gq", kind: "search", value: q, padding: 8, labelText: "Buscar", onChanged: "gq" } : null,
  { type: "ListView", key: key + "-list", items: options.filter((o) => !q || o[1].toLowerCase().includes(q.toLowerCase())).map((o) => ({
    type: "ListTile", key: key + "-" + o[0], dense: true, title: o[1],
    trailing: o[0] === current ? { type: "Icon", name: "check" } : undefined,
    onTap: { ui: [{ close: key }].concat(BUSY), event, arg: o[0] } })) },
].filter(Boolean) });

// the button that opens it
const button = (sheetKey, label, value) => ({ type: value ? "ElevatedButton" : "TextButton", radius: "full", icon: "expand_more",
  labelText: label + ": " + (value || "Todos"), onPressed: { ui: [{ open: sheetKey }] } });
  • gq es tu propio estado: screenEvent responde { state: { gq: value } } y el siguiente dibujo filtra la lista; la hoja sigue abierta.
  • Una fila de Chips sirve para 3 a 5 opciones cortas; con más, desplazarse de lado oculta casi todas. Usa una hoja.
  • Una opción con valor vacío no puede ser el value de un chip: usa una palabra como "all" y léela de vuelta como vacía.