fn_registry/cpp/functions/viz/kpi_card.md

name, kind, lang, domain, version, purity, signature, description, tags, uses_functions, uses_types, returns, returns_optional, error_type, imports, tested, tests, test_file_path, file_path, framework, params, output

name	kind	lang	domain	version	purity	signature	description	tags	uses_functions	uses_types	returns	returns_optional	error_type	imports	tested	tests	test_file_path	file_path	framework	params	output
kpi_card	component	cpp	viz	1.4.0	pure	void kpi_card(const char* label, float value, float delta_percent, const float* history = nullptr, int history_count = 0, const char* format = "%.1f", const char* icon = nullptr)	Card de KPI con icono opcional + label, valor grande, delta porcentual con TI_TRENDING_UP/DOWN y sparkline historico. Contenedor con surface bg, borde y radius via tokens (Mantine Paper equivalente).	imgui kpi card dashboard metrics sparkline tokens tabler cpp-dashboard-viz	sparkline_cpp_viz tokens_cpp_core			false		imgui	true	classify_delta positive -> Up classify_delta negative -> Down classify_delta near zero -> Flat pct_change basic deltas pct_change with zero previous returns 0 pct_change handles negative values	cpp/tests/test_kpi_card_math.cpp	cpp/functions/viz/kpi_card.cpp	imgui	name desc label Nombre del KPI mostrado como header muted (ej: "Revenue", "Users") name desc value Valor numerico actual del KPI name desc delta_percent Cambio porcentual respecto al periodo anterior (positivo = mejora, negativo = deterioro) name desc history Array de valores historicos para el sparkline. Nullable — si es nullptr no se renderiza sparkline name desc history_count Numero de valores en el array history name desc format Formato printf para el valor principal (ej: "$%.0f", "%.1f%%", "%.2f") name desc icon Glyph Tabler opcional (TI_* de core/icons_tabler.h) renderizado antes del label. Nullable — si es nullptr solo muestra label	Renderiza la card KPI completa en el frame ImGui actual: top row con icono opcional + label muted, valor grande, badge delta verde/rojo con TI_TRENDING_UP/DOWN, y sparkline de 120x24px

kpi_card

Card compacta para dashboards ImGui que muestra un KPI con contexto de tendencia. Combina label, valor escalado, badge de delta colorizado y sparkline historico en un grupo coherente de ~150px de ancho.

Usa sparkline del registry para el historico, con el mismo color que el badge (verde si delta >= 0, rojo si delta < 0).

Debe llamarse dentro del render callback de fn::run_app (o cualquier contexto con un frame ImGui activo).

Ejemplo

float history[] = {10.0f, 12.0f, 11.0f, 15.0f, 18.0f, 17.0f, 20.0f};
kpi_card("Revenue", 20000.0f, 12.5f, history, 7, "$%.0f");

// Sin sparkline
kpi_card("Error Rate", 0.3f, -15.2f, nullptr, 0, "%.2f%%");

// Grid de KPIs
ImGui::Columns(3, "kpis", false);
kpi_card("MAU",     1250000.0f,  3.4f, mau_history, 30);
ImGui::NextColumn();
kpi_card("Revenue", 89400.0f,   -1.2f, rev_history, 30, "$%.0f");
ImGui::NextColumn();
kpi_card("Churn",   2.1f,       -0.3f, churn_history, 30, "%.1f%%");
ImGui::Columns(1);

Notas

• v1.1: la card se renderiza dentro de un BeginChild con surface bg, border y radius::md de fn_tokens — replica el <Paper withBorder radius="md" p="sm"> del frontend.
• v1.2: altura fija 78px (antes 108px) + font scale 1.4x (antes 1.8x) + padding spacing::sm (antes md). Mas compacta para densidades altas de KPIs. NoScrollbar|NoScrollWithMouse ademas de altura fija para evitar lag al redimensionar.
• v1.3 (sesion 2026-04-25): nuevo parametro opcional icon (Tabler TI_* glyph) renderizado antes del label en la top row. Triangulos de delta migrados a TI_TRENDING_UP / TI_TRENDING_DOWN (los UTF-8 hex anteriores no estan en el atlas Karla/DroidSans → cuadritos). Em dash placeholder migrado a TI_MINUS. Altura subida 78→86 px para acomodar el row icono+label sin apretar. uses_functions ahora incluye implicitamente icons_tabler (header puro, no funcion).
• El ancho se adapta al contenedor padre via GetContentRegionAvail().x. Para que ocupe exactamente una celda usar ImGui::BeginTable — BeginGroup / dashboard_grid no propagan ancho constrained y la card desbordaria la celda.
• La linea de trend siempre se reserva (delta, sparkline o em dash placeholder en text_dim) para que un grid de KPIs quede alineado vertical.
• Los caracteres UTF-8 del triangulo (▲ U+25B2 y ▼ U+25BC) y del em dash (— U+2014) requieren que la fuente ImGui tenga el rango de simbolos geometricos / puntuacion general cargado. → Obsoleto en v1.3: ahora se usan glyphs Tabler que estan en el atlas mergeado por icon_font_cpp_core.
• Colores: delta usa fn_tokens::colors::{success, error}, placeholder TI_MINUS usa text_dim, label + icono usan text_muted.

Capability growth log

• v1.4.0 (2026-05-18) — Overload con y_min, y_max que se propaga al sparkline interno. Cards de un grid con dominio fijo (CPU%/RAM% -> 0,100) ahora son visualmente comparables — outliers no aplastan la escala. Default sigue siendo auto-scale.