ADR 012: Cortex UI Kit¶

Estado¶

Aceptado — 2026-06

Contexto¶

Los plugins declaraban UI como JSON CUS manual (ui/dashboards/*.json) con widgets genéricos (api-table, json-form). Faltaba una API fluida en Python y contratos tipados para forms, tables, actions, resources y calendar.

Decisión¶

Builders Python en framework/cortex_framework/ui/ generan CUS JSON al registrar.
Hook register_resources(registry) orquesta manifest + dashboards + forms.
Widgets CUS tipados: data-table, form, infolist, stat-card, stats-overview, chart, calendar, actions-bar, section.
Frontend @cortex/panel-shadcn implementa widgets; api-table / json-form quedan como alias legacy.

Leyenda: Taxonomía builders Python a widgets CUS y skin React. Actores: plugin, framework/ui, panel-shadcn. Estado: Implementado.

flowchart TB
  subgraph plugin [Plugin bootstrap]
    RR[register_resources]
    RW[register_widgets]
    RS[register_settings shim]
  end
  subgraph builders [framework/ui builders]
    RB[ResourceBuilder]
    FB[FormBuilder]
    TB[TableBuilder]
    IB[InfolistBuilder]
    LB[LayoutBuilder]
  end
  subgraph cus [CUS JSON]
    DT[data-table]
    FM[form]
    IL[infolist]
    WZ[wizard section]
  end
  subgraph react ["@cortex/panel-shadcn"]
    Skin[Widget registry React]
  end
  RR --> RB --> DT
  RR --> FB --> FM
  RR --> TB --> DT
  RB --> IB --> IL
  RB --> LB --> WZ
  RW --> Skin
  DT --> Skin
  FM --> Skin

Conceptos del UI Kit¶

Concepto	Implementación Cortex
Panel / host	`PanelBuilder` + hosts (`cortex.panels`)
Extensión del panel	`register_panel_plugins` + `PanelPluginRegistry`
Render hooks	`register_render_hooks` + slots en `PanelShell`
Schema (fields, layouts, actions)	`SchemaNode` + `SchemaBuilder` + widget `schema`
Resource	`ResourceBuilder` + `register_resources`
Form fields	`FormBuilder` / `FieldBuilder`
Table columns / filters / bulk	`TableBuilder` / `FilterBuilder` / `BulkActionBuilder`
Actions (modales)	`ActionBuilder` → `opensModal` + `ActionModal`
Infolist	`InfolistBuilder` → widget `infolist`
Layouts (tabs, wizard, section)	`LayoutBuilder` + nodos `wizard` / `section`
Widgets (stats, charts)	`StatCardBuilder`, `StatsOverviewBuilder`, `emit_chart_widget` + `register_widgets`
Settings pages	`SettingsBuilder` + `register_settings` + API de plataforma
Reports	`ReportBuilder` + `register_reports`
Relation managers	`RelationBuilder` + widget `relation`
Global search	`SearchRegistry` + `GET /panels/{id}/search`
Calendar	`CalendarBuilder` + `@fullcalendar/react`

Guía de uso: Plugins — Recursos.

Ver también ADR 013, ADR 014, ADR 015.

Consecuencias¶

Plugins migran de JSON manual a register_resources donde aplique.
Validación en panel/validate.py exige config mínimo por tipo de widget.