Cortex Panel — runtime frontend¶

Cómo el shell React consume manifests y dashboards CUS por HTTP. Para declarar UI desde Python, usa la guía Plugins.

Ver ADR 003, ADR 018 y contexto del proyecto.

Arquitectura npm¶

flowchart TB
  subgraph demo [Demo Vite]
    SH[framework/web-shadcn]
  end
  subgraph web ["@cortex/web"]
    W["createPanelShellApp"]
  end
  subgraph skin ["@cortex/panel-shadcn"]
    SK[widgets + PanelShell]
  end
  subgraph core ["@cortex/panel-core"]
    C["PanelProvider navUtils PanelApiClient"]
  end
  SH --> W --> SK --> C

Arranque local¶

npm install              # raíz — workspaces
npm run dev:web-shadcn   # http://localhost:5175
npm run build:web-shadcn

Vite hace proxy de /api → http://localhost:8000. La API debe estar en marcha (uv run cortex-api).

Flujo runtime¶

1. En bootstrap, el plugin registra UI (register_resources o register_dashboards).
2. El shell carga rutas con GET /api/v1/panels/routes.
3. ModuleScreen resuelve pantalla → GET /api/v1/ui/dashboards/{dashboardId}.
4. WidgetRenderer instancia el componente según widget.type.

sequenceDiagram
  participant API as FastAPI
  participant Shell as PanelProvider
  participant M as ModuleScreen
  participant W as Widgets

  Shell->>API: GET /api/v1/panels/{panelId}
  M->>API: GET manifest + dashboard
  M->>W: layout + configs
  W->>API: fetchPath datos y forms

Componentes clave¶

Jerarquía de títulos¶

El shell shadcn aplica un contrato de un título visible por pantalla (ver ADR 018):

Flags en PanelConfiguration.theme:

En Python, emit_dashboard(..., hide_title=True) suprime el título del dashboard; el título vive en screens[].title. ResourceBuilder lo aplica por defecto en list/create/edit/view.

flowchart TB
  subgraph titles [Jerarquía de títulos]
    Shell["PanelShell h1 screen.title"]
    Module["ModuleScreen h2 opcional"]
    Dash["DashboardRenderer h3 si no hideTitle"]
    Widget["Widget CardTitle si config.title"]
  end
  Shell --> Module --> Dash --> Widget

Resolución de pantallas¶

ModuleScreen y PanelShell usan matchModuleScreen de @cortex/panel-core:

1. Calculan la ruta relativa con relativeModulePath(pathname, moduleUrl).
2. Evalúan todas las entradas de manifest.screens con dashboardId.
3. Eligen la pantalla con mayor especificidad (scoreScreenPath): segmentos literales antes que parámetros (:id).

Ejemplo: la ruta relativa create coincide con path: "create" y con path: ":id", pero gana la literal.

import { matchModuleScreen, relativeModulePath } from '@cortex/panel-core';

const relative = relativeModulePath('/operations/clients/create', '/operations/clients');
const { screen, params } = matchModuleScreen(manifest, relative);
// screen.path === 'create'

Si una acción CREATE navega a create, el manifest debe declarar una pantalla con path: "create" (o usar ResourceBuilder, que la genera automáticamente).

PanelApiClient¶

Rutas habituales (packages/cortex-panel-core/src/panelApiClient.ts):

Widget registry¶

import { createDefaultRegistry } from '@cortex/panel-shadcn';

const registry = createDefaultRegistry();
registry.register('mi-widget', MiWidget);

Catálogo de tipos: Widgets (plugins).

Shell mínimo¶

import { createPanelShellApp } from '@cortex/web';
import { PanelShell, createDefaultRegistry } from '@cortex/panel-shadcn';

export const { AppPanelProvider, AppPanelRoutes } = createPanelShellApp({
  PanelShell,
  createDefaultRegistry,
});

Multi-módulo en un panel¶

GET /api/v1/panels/operations devuelve modules[], navGroups[] y navigation[] — sidebar agrupado con orden por navSort. Varios plugins contribuyen módulos sin compartir código React.

flowchart TB
  subgraph panelOperativo [Panel panel]
    Shell[PanelShell sidebar único]
    B[cortex_plugin_booking]
    C[cortex_plugin_clients]
    P[cortex_plugin_pricing]
  end
  Shell --> B
  Shell --> C
  Shell --> P
  B --> API_B["/api/v1/booking/"]
  C --> API_C["/api/v1/clients/"]
  P --> API_P["/api/v1/pricing/"]

Panel Control¶

Módulo embebido cortex_framework.control — rutas /control/, API /api/v1/control/plugins. No es plugin pip.

Validación CUS¶

cortex_framework.panel.validate — schemas en framework/cortex_framework/panel/schemas/.

Siguiente lectura¶

• Plugins — introducción
• Primer plugin

Arquitectura 4 capas (Magento → HIVE)¶

El panel separa controller (headless), template (view por skin), styles y statics para intercambiar presentación sin recompilar el bundle npm. Ver ADR 026 y ADR 027.

Carga de templates en runtime¶

1. PanelShell lee panel.configuration.theme.skin.
2. loadSkinTemplates(registry, skin) importa el entry ESM del skin y llama registerSkinTemplates(registry).
3. WidgetRegistry.resolve(type, skin) elige la view (data-table@operations, etc.).
4. Build de skins: npm run build:skins (assets + registry.js por skin).

sequenceDiagram
  participant Shell as PanelShell
  participant Loader as SkinTemplateLoader
  participant Registry as WidgetRegistry
  participant API as API CUS

  Shell->>API: GET /panels/operations
  API-->>Shell: theme.skin=operations
  Shell->>Loader: loadSkinTemplates(operations)
  Loader->>Registry: registerSkinTemplates
  Shell->>API: GET dashboard JSON
  Shell->>Registry: resolve type + skin

Layouts composables¶

Los plugins aportan fragmentos con register_layouts. El loader fusiona con merge_layouts y expone:

ModuleScreen pasa screen.layoutHandle al cargar el dashboard (p. ej. panel-home en operations).

Shell declarativo¶

PanelConfiguration.shellLayout define slots del chrome (shell.sidebar.footer, toolbar móvil). GET /api/v1/info devuelve shell.defaultRoute y rutas de auth; RootRedirect en el demo usa esa respuesta (sin hardcode /operations).

Catálogo de widget types¶

GET /api/v1/ui/widget-types lista tipos core (__framework__) y de dominio (plugin owner). En desarrollo, DashboardRenderer advierte tipos desconocidos vía warnUnknownDashboardWidgetTypes.

Publicación¶

scripts/publish-cloudsmith.sh publica wheels Python (core, framework y cada cortex-plugin-*), paquetes npm (@cortex/panel-core, @cortex/panel-shadcn, @cortex/web, skins) y deja los bundles de template en framework/web-shadcn/public/skins/.

Código fuente de plugins: repos GitHub cortex-ia-com-co/cortex-plugin-* integrados en el monorepo vía submódulos. Ver Repositorios y submódulos.