Visualization

Cuándo usar text

Una nota text es la capa explicativa de un dashboard — títulos de sección, narrativa, instrucciones, advertencias, leyendas: las palabras que hacen que una pared de gráficos tenga sentido. La nota común es prosa pura sin query. Opcionalmente, cuando ayuda a una oración, una nota puede tejer un valor en vivo desde una query dentro del texto — pero eso es una función secundaria, no el objetivo.

No es un kpi: un kpi es una tarjeta de métrica con ranuras fijas de titular/delta y chrome de tarjeta; una nota text es prosa libre. Si la respuesta es un solo número, usá kpi; si necesitás un número por categoría, usá bar; para una tabla, usá grid. Usá text cuando el contenido es lenguaje.

Estática vs dinámica

Una nota estática tiene solo un body — prosa Markdown, sin query, sin lectura de datos. Una nota dinámica agrega una query de una sola fila y un mapping, e interpola valores en la prosa.

format — formato del body. v1 trae markdown (el único valor; plain / html están reservados).
body — requerido. El fuente Markdown. Subset soportado: títulos, párrafos, listas ordenadas / sin orden, negrita, itálica, code en línea, bloques de código, y [enlaces](url).

Tokens y mapping

Una nota dinámica interpola valores escalares desde la única fila de resultado de su query. Cada token en el body se enlaza a una columna a través de mapping:

Sintaxis del token: {{ field }}, o con un formato numérico {{ field | "$#,##0" }}.
mapping — un objeto de nombre de token → columna del resultado. El nombre de cada token debe ser una clave de mapping, y cada clave de mapping debe usarse en un token; de lo contrario la nota se rechaza en validación.
Los tokens son solo escalares. Las llaves que no coinciden con la gramática del token se tratan como texto literal.

mapping:
  total_revenue: revenue_total   # token "total_revenue" -> columna "revenue_total"
  growth_pct:    mom_growth
body: |
  La facturación de este mes es **{{ total_revenue | "$#,##0" }}**, un
  **{{ growth_pct | "+0.0%" }}** más que el anterior.

Los patrones de formato numérico usan la misma gramática que cualquier otra viz — ver el resumen de viz-types.

query es opcional

text es el único tipo de visualization donde query es opcional. Una nota sin query es una nota estática: renderiza su prosa de inmediato, sin ejecución. Agregá una query de una sola fila solo cuando la nota interpola un valor. Todos los demás tipos de viz requieren query.

Seguridad

La nota es segura por construcción:

Los valores interpolados se escapan como HTML — un valor que contiene markup se renderiza como texto literal, nunca como elementos.
El Markdown renderizado se sanitiza — solo sobrevive el subset soportado; los scripts y etiquetas desconocidas se eliminan.
Los href de enlaces se limitan a http, https y URLs relativas; cualquier otro esquema (p. ej. javascript:, data:) se renderiza como texto inerte.

Comportamiento de cross-filter

Una nota text participa solo como consumidor, igual que kpi:

No emite. Una nota no tiene dimensión que clicar — no agrega pills.
Sí reacciona. La query de una nota dinámica se re-ejecuta con los filtros y pills activos del dashboard, y sus valores interpolados se recalculan. Una nota estática no tiene nada que re-ejecutar.

Ejemplos

Una nota estática — prosa pura, sin query (el caso común):

id: ops_intro
title: Resumen de operaciones
type: text
format: markdown
body: |
  ## Resumen de operaciones

  Estos paneles siguen la salud de fulfilment. Las celdas en **ámbar**
  marcan SLAs en riesgo. Las cifras excluyen pedidos cancelados.
published: true

Una nota dinámica — un valor en vivo tejido en una oración:

id: revenue_note
title: Resumen de facturación
type: text
format: markdown
query: "models/sales.malloy::headline"   # una fila, muchas columnas
mapping:
  total_revenue: revenue_total
  growth_pct:    mom_growth
body: |
  ## Resumen de facturación

  El total de este mes es **{{ total_revenue | "$#,##0" }}**, un
  **{{ growth_pct | "+0.0%" }}** más que el mes anterior.
published: true

Errores comunes

Un token se renderiza como placeholder. La columna mapeada falta o es null en la fila de resultado, o la query falló — el resto de la prosa igual se renderiza. Revisá el nombre de la columna en mapping.
La validación rechaza la nota. Un token cuyo nombre no está en mapping, o una clave de mapping que ningún token usa, se rechaza. Mantené tokens y mapping sincronizados.
mapping sin query. Los tokens necesitan una fuente — un mapping sin query es inválido.
Esperar una tabla. Los tokens son escalares; solo se leen las columnas nombradas de la primera fila. Una query de muchas filas no se renderiza como lista.
Un enlace no hace nada. Solo los href http / https / relativos se vuelven enlaces; otros esquemas se renderizan como texto plano por diseño.

Visualization — text