@oondemand/create-central-oon 0.3.11 → 0.3.14

package/docs/FRONTEND_MANIFEST_REFERENCE.md

@@ -2,7 +2,12 @@
 
 Este documento é a referência operacional para o Codex criar ou alterar manifestos do frontend OonCore.
 
-Use este arquivo junto com `FRONTEND_PATTERNS.md`. O arquivo de padrões explica como pensar a UI; este arquivo lista as opções do contrato atual.
+Use este arquivo junto com `FRONTEND_PATTERNS.md`. O arquivo de padrões explica como pensar a UI; este arquivo lista as opções do contrato atual e das extensões planejadas para UX avançada.
+
+Para modal com abas, grids relacionados editáveis e ações por linha, leia também:
+
+- `ADVANCED_UX_PATTERNS.md`
+- `DETAIL_MODAL_AND_RELATED_GRIDS.md`
 
 ## Arquivos envolvidos
 
@@ -40,8 +45,9 @@ Para Codex, a ordem recomendada é:
 
 1. Começar pelo `central.ui.json`.
 2. Usar `pages` e `blocks` quando precisar de UI v2.
-3. Usar registry/overrides em TypeScript quando precisar de componentes customizados.
-4. Evitar recriar shell, rotas, menu, grid, cards ou formulários manualmente.
+3. Usar `collections[].list`, `collections[].detailModal`, `form.groups`, `relations` e `relatedGrid` para UX operacional avançada.
+4. Usar registry/overrides em TypeScript quando precisar de componentes customizados.
+5. Evitar recriar shell, rotas, menu, grid, cards ou formulários manualmente.
 
 ## CentralUiManifest
 
@@ -57,13 +63,7 @@ interface CentralUiManifest {
   registry?: OonComponentRegistry;
   navigation?: OonNavigationConfig;
   pages?: OonPageDef[];
-  collections?: Array<{
-    model: string;
-    mode?: CollectionMode;
-    path?: string;
-    label?: string;
-    section?: string;
-  }>;
+  collections?: OonCollectionManifestDef[];
   pipelines?: Array<{
     name?: string;
     model?: string;
@@ -85,7 +85,7 @@ interface CentralUiManifest {
 }
 ```
 
-### Opções de raiz
+## Opções de raiz
 
 | Campo | Tipo | Uso |
 | --- | --- | --- |
@@ -96,7 +96,7 @@ interface CentralUiManifest {
 | `layout` | `OonLayoutConfig` | Shell, sidebar, topbar, header, footer e slots. |
 | `navigation` | `OonNavigationConfig` | Modo do menu e itens manuais. |
 | `pages` | `OonPageDef[]` | Páginas por blocos da UI v2. |
-| `collections` | `Array` | Atalho para gerar views de coleção. |
+| `collections` | `Array` | Views de coleção, simples ou avançadas. |
 | `pipelines` | `Array` | Atalho para gerar esteiras. |
 | `documents` | `Array` | Atalho para gerar documentos. |
 
@@ -125,34 +125,6 @@ interface OonLayoutConfig {
 | `content-only` | Experiência focada em conteúdo. |
 | `custom:<key>` | Shell registrado em `registry.layoutSlots`. |
 
-### Slots
-
-| Campo | Valores | Uso |
-| --- | --- | --- |
-| `sidebar` | `core`, `none`, `custom:<key>` | Menu lateral. |
-| `topbar` | `core`, `none`, `custom:<key>` | Barra superior. |
-| `header` | `none`, `custom:<key>` | Header custom acima da página. |
-| `footer` | `core`, `none`, `custom:<key>` | Rodapé. |
-| `assistant` | `core`, `none`, `custom:<key>` | Assistente/copiloto, quando suportado. |
-| `main` | `core` | Área principal do Core. |
-
-### Exemplo
-
-```json
-{
-  "schemaVersion": 2,
-  "name": "Meus Apps",
-  "slug": "meus-apps",
-  "layout": {
-    "shell": "portal",
-    "sidebar": "none",
-    "topbar": "none",
-    "header": "custom:MeusAppsHeader",
-    "footer": "core"
-  }
-}
-```
-
 ## Navigation
 
 ```ts
@@ -164,52 +136,24 @@ interface OonNavigationConfig {
 }
 ```
 
-### Modos
-
-| Valor | Comportamento |
-| --- | --- |
-| `auto` | Core gera menu a partir de coleções, documentos, esteiras, dashboards e páginas. |
-| `manual` | Usa apenas `navigation.items`. |
-| `mixed` | Combina menu automático com itens manuais. |
+## Collections no central.ui.json
 
-## Menu item
+Atalho para coleções simples ou avançadas.
 
 ```ts
-interface OonMenuItem {
-  label: string;
-  href: string;
-  icon?: ReactNode;
+interface OonCollectionManifestDef {
+  model: string;
+  mode?: "full" | "minimal" | "dynamic";
+  path?: string;
+  label?: string;
   section?: string;
-  order?: number;
-  permissions?: string[];
-  children?: OonMenuItem[];
-  badge?: string | number;
-  external?: boolean;
-  hidden?: boolean;
-  action?: string;
-  renderer?: string;
+  list?: OonCollectionListConfig;
+  relations?: Record<string, OonRelationDef>;
+  detailModal?: OonDetailModalConfig;
 }
 ```
 
-### Opções de menu
-
-| Campo | Uso |
-| --- | --- |
-| `label` | Texto do menu. |
-| `href` | Rota interna ou URL. |
-| `section` | Agrupamento visual. |
-| `order` | Ordenação. |
-| `permissions` | Permissões exigidas. |
-| `children` | Subitens. |
-| `badge` | Indicador simples. |
-| `external` | Link externo. |
-| `hidden` | Oculta item sem remover do manifesto. |
-| `action` | Chave de ação. |
-| `renderer` | Renderer customizado em `registry.menuRenderers`. |
-
-## Collections no central.ui.json
-
-Atalho simples para coleções.
+### Exemplo simples
 
 ```json
 {
@@ -225,467 +169,278 @@ Atalho simples para coleções.
 }
 ```
 
-### Campos aceitos no atalho `collections[]`
-
-| Campo | Tipo | Uso |
-| --- | --- | --- |
-| `model` | `string` | Model do backend. |
-| `mode` | `full`, `minimal`, `dynamic` | Modo de renderização. |
-| `path` | `string` | Rota. |
-| `label` | `string` | Nome no menu/tela. |
-| `section` | `string` | Grupo do menu. |
-
-## CollectionViewDef completo
-
-Contrato interno completo quando a coleção já está em `ui.views` ou em blocos.
+### Exemplo avançado
 
-```ts
-interface CollectionViewDef {
-  type: "collection";
-  id?: string;
-  model: string;
-  label?: string;
-  path?: string;
-  icon?: ReactNode;
-  section?: string;
-  mode?: "full" | "minimal" | "dynamic";
-  columns?: OonColumnDef[];
-  form?: OonFormFieldDef[];
-  importExport?: boolean;
-  renderer?: string;
-  cardRenderer?: string;
-  actions?: OonActionDef[];
-  permissions?: string[];
-}
-```
-
-### Column
-
-```ts
-interface OonColumnDef {
-  field: string;
-  label?: string;
-  kind?: FieldKind;
-  sortable?: boolean;
-  width?: number;
-  renderer?: string;
-  permissions?: string[];
+```json
+{
+  "collections": [
+    {
+      "model": "OrcamentoProjeto",
+      "mode": "dynamic",
+      "path": "/orcamentos-projetos",
+      "label": "Orçamentos/Projetos",
+      "section": "Operação",
+      "list": {
+        "filters": [
+          {
+            "field": "tipoRegistro",
+            "label": "Tipo",
+            "type": "select",
+            "options": [
+              { "label": "Todos", "value": "" },
+              { "label": "Orçamento", "value": "Orçamento" },
+              { "label": "Projeto", "value": "Projeto" }
+            ]
+          }
+        ],
+        "rowActions": [
+          { "type": "openDetailModal", "icon": "edit", "label": "Editar", "initialTab": "resumo" }
+        ]
+      },
+      "relations": {
+        "itens": { "model": "OrcamentoItem", "foreignKey": "projetoId", "parentKey": "_id" },
+        "pagamentos": { "model": "Pagamento", "foreignKey": "projetoId", "parentKey": "_id" }
+      },
+      "detailModal": {
+        "enabled": true,
+        "titleField": "nome",
+        "defaultTab": "resumo",
+        "tabs": []
+      }
+    }
+  ]
 }
 ```
 
-### Form field
-
-```ts
-interface OonFormFieldDef {
-  field: string;
-  label?: string;
-  kind?: FieldKind;
-  required?: boolean;
-  options?: string[];
-  ref?: string;
-  renderer?: string;
-  permissions?: string[];
-}
-```
+## list
 
-### Action
+Configura filtros, colunas e ações do grid principal.
 
 ```ts
-interface OonActionDef {
-  id: string;
-  label?: string;
-  renderer?: string;
-  permissions?: string[];
-  action?: string;
+interface OonCollectionListConfig {
+  filters?: OonListFilterDef[];
+  columns?: Array<string | OonColumnDef>;
+  rowActions?: OonRowActionDef[];
 }
 ```
 
-## Documents
+### list.filters
 
 ```json
 {
-  "documents": [
-    {
-      "model": "DocumentoFiscal",
-      "path": "/documentos-fiscais",
-      "label": "Documentos Fiscais",
-      "section": "Fiscal",
-      "approval": true,
-      "attachments": true
-    }
+  "field": "tipoRegistro",
+  "label": "Tipo",
+  "type": "select",
+  "options": [
+    { "label": "Todos", "value": "" },
+    { "label": "Orçamento", "value": "Orçamento" }
   ]
 }
 ```
 
-### Opções
+Tipos previstos:
 
-| Campo | Uso |
-| --- | --- |
-| `model` | Model do documento. |
-| `mode` | Modo futuro/reservado. |
-| `path` | Rota. |
-| `label` | Nome exibido. |
-| `section` | Grupo do menu. |
-| `approval` | Habilita comportamento de aprovação. |
-| `attachments` | Habilita anexos. |
+- `text`
+- `select`
+- `date`
+- `dateRange`
+- `numberRange`
+- `boolean`
+- `ref`
 
-## Pipelines
+### list.rowActions
 
 ```json
 {
-  "pipelines": [
-    {
-      "model": "Pedido",
-      "stageField": "status",
-      "path": "/pedidos/esteira",
-      "label": "Esteira de Pedidos",
-      "section": "Operação"
-    }
-  ]
+  "type": "openDetailModal",
+  "label": "Editar",
+  "icon": "edit",
+  "initialTab": "resumo"
 }
 ```
 
-### Opções
-
-| Campo | Uso |
-| --- | --- |
-| `name` | Nome alternativo usado como model quando `model` não for informado. |
-| `model` | Model dos cards/tickets. |
-| `mode` | Modo futuro/reservado. |
-| `stageField` | Campo que define a coluna/etapa. |
-| `path` | Rota. |
-| `label` | Nome exibido. |
-| `section` | Grupo do menu. |
-
-## PipelineViewDef completo
+## relations
 
-```ts
-interface PipelineViewDef {
-  type: "pipeline";
-  id?: string;
-  model: string;
-  label?: string;
-  path?: string;
-  icon?: ReactNode;
-  section?: string;
-  stageField?: string;
-  stages?: Array<{ id: string; label: string }>;
-  permissions?: string[];
-}
-```
+Relações nomeadas entre model pai e models filhos.
 
-## DocumentViewDef completo
-
-```ts
-interface DocumentViewDef {
-  type: "document";
-  id?: string;
-  model: string;
-  label?: string;
-  path?: string;
-  icon?: ReactNode;
-  section?: string;
-  approval?: boolean;
-  attachments?: boolean;
-  permissions?: string[];
-}
-```
-
-## DashboardViewDef
-
-```ts
-interface DashboardViewDef {
-  type: "dashboard";
-  id?: string;
-  label?: string;
-  path?: string;
-  icon?: ReactNode;
-  section?: string;
-  widgets?: DashboardWidgetDef[];
-}
-
-interface DashboardWidgetDef {
-  id: string;
-  label: string;
-  model?: string;
-  kind?: "count" | "sum" | "custom";
-  field?: string;
-  render?: () => ReactNode;
+```json
+{
+  "relations": {
+    "itens": {
+      "model": "OrcamentoItem",
+      "foreignKey": "projetoId",
+      "parentKey": "_id"
+    }
+  }
 }
 ```
 
-Observação: `render` é função React e não deve estar em JSON. Use somente em configuração TypeScript.
+## detailModal
 
-## Pages UI v2
-
-Páginas permitem compor rotas por blocos.
+Configura modal de detalhe/criação com abas.
 
 ```ts
-interface OonPageDef {
-  id?: string;
-  path: string;
-  label?: string;
-  title?: string;
-  section?: string;
-  icon?: ReactNode;
-  layout?: "default" | "content-only" | "portal";
-  blocks?: OonBlockDef[];
-  component?: string;
-  permissions?: string[];
-  hidden?: boolean;
-  order?: number;
+interface OonDetailModalConfig {
+  enabled?: boolean;
+  titleField?: string;
+  size?: "md" | "lg" | "xl" | "full";
+  defaultTab?: string;
+  tabs: OonDetailTabDef[];
 }
 ```
 
-### Opções de página
+### Abas suportadas
 
-| Campo | Uso |
-| --- | --- |
-| `id` | Identificador opcional. |
-| `path` | Rota. |
-| `label` | Nome no menu. |
-| `title` | Título da página. |
-| `section` | Grupo do menu. |
-| `layout` | Layout da página. |
-| `blocks` | Blocos renderizados. |
-| `component` | Componente custom em `registry.pageComponents`. |
-| `permissions` | Permissões da página. |
-| `hidden` | Oculta do menu. |
-| `order` | Ordenação no menu. |
-
-## Blocks UI v2
-
-Tipos atuais:
-
-```ts
-type OonBlockDef =
-  | OonCustomBlockDef
-  | OonCollectionDataGridBlockDef
-  | OonCollectionCardsBlockDef
-  | OonSectionBlockDef
-  | OonMarkdownBlockDef
-  | OonGenericBlockDef;
-```
-
-### Campos comuns
-
-```ts
-interface OonBaseBlockDef {
-  id?: string;
-  title?: string;
-  permissions?: string[];
-  hidden?: boolean;
-}
-```
+- `summary`
+- `form`
+- `relatedGrid`
+- `readonlyGrid`
+- `customComponent`
 
-### custom
+### Aba summary
 
 ```json
 {
-  "type": "custom",
-  "component": "MeusAppsHero",
-  "props": {
-    "titulo": "Bem-vindo"
-  }
+  "id": "resumo",
+  "label": "Resumo",
+  "type": "summary",
+  "cards": [
+    { "label": "Itens", "source": "relatedCount", "relation": "itens" },
+    { "label": "Total", "field": "total", "format": "currency" }
+  ]
 }
 ```
 
-Renderiza componente de `registry.pageComponents.MeusAppsHero`.
-
-### collection.datagrid
+### Aba form
 
 ```json
 {
-  "type": "collection.datagrid",
-  "model": "App",
-  "mode": "dynamic",
-  "title": "Apps"
+  "id": "dados",
+  "label": "Dados Principais",
+  "type": "form",
+  "groups": [
+    { "label": "Identificação", "fields": ["codigo", "nome", "status"] }
+  ]
 }
 ```
 
-Opções:
+### Aba relatedGrid
 
-```ts
-interface OonCollectionDataGridBlockDef {
-  type: "collection.datagrid";
-  model: string;
-  mode?: CollectionMode;
-  renderer?: string;
-  columns?: OonColumnDef[];
-  form?: OonFormFieldDef[];
+```json
+{
+  "id": "itens",
+  "label": "Itens",
+  "type": "relatedGrid",
+  "relation": "itens",
+  "editable": true,
+  "editMode": "inline",
+  "columns": [
+    { "field": "item", "editable": true },
+    { "field": "status", "editable": true },
+    { "field": "total", "editable": true, "format": "currency" }
+  ],
+  "rowActions": []
 }
 ```
 
-### collection.cards
+### Aba readonlyGrid
 
 ```json
 {
-  "type": "collection.cards",
-  "model": "App",
-  "renderer": "cards.appLauncher"
+  "id": "pagamentos",
+  "label": "Pagamentos",
+  "type": "readonlyGrid",
+  "relation": "pagamentos",
+  "columns": ["codigo", "descricao", "status", "valor"]
 }
 ```
 
-Renderiza cards usando `registry.cardRenderers.appLauncher` quando registrado.
+## rowActions
 
-### section
+Ações reutilizáveis em grid principal ou grids relacionados.
 
-```json
-{
-  "type": "section",
-  "title": "Administração",
-  "description": "Gestão dos apps e permissões",
-  "blocks": [
-    { "type": "collection.datagrid", "model": "Usuario" }
-  ]
+```ts
+interface OonRowActionDef {
+  id?: string;
+  label: string;
+  icon?: string;
+  type: "openDetailModal" | "navigate" | "apiAction" | "customAction";
+  method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+  endpoint?: string;
+  initialTab?: string;
+  confirm?: { title?: string; description?: string };
+  disabledWhen?: OonConditionDef;
+  hiddenWhen?: OonConditionDef;
+  refresh?: string[];
+  roles?: string[];
+  permissions?: string[];
 }
 ```
 
-### markdown
+### apiAction
 
 ```json
 {
-  "type": "markdown",
-  "content": "Texto institucional ou instruções da página."
+  "id": "gerarPagamento",
+  "label": "Gerar pagamento",
+  "type": "apiAction",
+  "method": "POST",
+  "endpoint": "/api/ss-eventos/orcamentos-itens/:id/gerar-pagamento",
+  "disabledWhen": { "field": "pagamentoId", "exists": true },
+  "refresh": ["self", "pagamentos", "resumo", "parent"]
 }
 ```
 
-### Blocos reservados/genéricos
-
-O contrato já reserva:
-
-```txt
-collection.form
-pipeline.board
-document.viewer
-dashboard.kpi
-tabs
-```
-
-Esses blocos podem ser usados como contrato futuro, mas confirme suporte visual antes de depender deles em produção.
+## CollectionViewDef completo
 
-## Registry
+Contrato interno completo quando a coleção já está em `ui.views` ou em blocos.
 
 ```ts
-interface OonComponentRegistry {
-  layoutSlots?: Record<string, OonRendererComponent<any>>;
-  fieldRenderers?: Record<string, OonRendererComponent<any>>;
-  cellRenderers?: Record<string, OonRendererComponent<any>>;
-  cardRenderers?: Record<string, OonRendererComponent<any>>;
-  actionRenderers?: Record<string, OonRendererComponent<any>>;
-  pageComponents?: Record<string, OonRendererComponent<any>>;
-  menuRenderers?: Record<string, OonRendererComponent<any>>;
-}
-```
-
-### Mapeamento de chaves
-
-| Chave no manifesto | Bucket esperado |
-| --- | --- |
-| `custom:MeusAppsHeader` | `layoutSlots` ou `pageComponents`, conforme uso. |
-| `fields.password` | `fieldRenderers` |
-| `cells.statusBadge` | `cellRenderers` |
-| `cards.appLauncher` | `cardRenderers` |
-| `actions.ativarApp` | `actionRenderers` |
-| `menus.portal` | `menuRenderers` |
-
-## Exemplo v1 simples
-
-```json
-{
-  "name": "Central SS Eventos",
-  "slug": "central-ss-eventos",
-  "navigation": { "mode": "auto" },
-  "collections": [
-    { "model": "Orcamento", "label": "Orçamentos", "section": "Operação" },
-    { "model": "Prestador", "label": "Prestadores", "section": "Cadastros" }
-  ],
-  "pipelines": [
-    { "model": "Pagamento", "stageField": "status", "label": "Esteira de Pagamentos" }
-  ],
-  "documents": [
-    { "model": "DocumentoFiscal", "label": "Documentos Fiscais", "approval": true, "attachments": true }
-  ]
+interface CollectionViewDef {
+  type: "collection";
+  id?: string;
+  model: string;
+  label?: string;
+  path?: string;
+  icon?: ReactNode;
+  section?: string;
+  mode?: "full" | "minimal" | "dynamic";
+  columns?: OonColumnDef[];
+  form?: OonFormFieldDef[];
+  importExport?: boolean;
+  renderer?: string;
+  cardRenderer?: string;
+  actions?: OonActionDef[];
+  permissions?: string[];
+  list?: OonCollectionListConfig;
+  relations?: Record<string, OonRelationDef>;
+  detailModal?: OonDetailModalConfig;
 }
 ```
 
-## Exemplo v2 portal / Meus Apps
+## Compatibilidade
 
-```json
-{
-  "schemaVersion": 2,
-  "name": "Meus Apps",
-  "slug": "meus-apps",
-  "layout": {
-    "shell": "portal",
-    "sidebar": "none",
-    "topbar": "none",
-    "header": "custom:MeusAppsHeader",
-    "footer": "core"
-  },
-  "navigation": { "mode": "mixed" },
-  "pages": [
-    {
-      "path": "/",
-      "label": "Meus Apps",
-      "layout": "content-only",
-      "blocks": [
-        { "type": "custom", "component": "MeusAppsHero" },
-        { "type": "collection.cards", "model": "App", "renderer": "cards.appLauncher" }
-      ]
-    },
-    {
-      "path": "/admin/apps",
-      "label": "Apps",
-      "section": "Administração",
-      "blocks": [
-        { "type": "collection.datagrid", "model": "App", "mode": "dynamic" }
-      ]
-    }
-  ]
-}
-```
+- Os campos `list`, `relations` e `detailModal` são opcionais.
+- Manifestos existentes continuam funcionando.
+- Sem `detailModal`, o Core mantém comportamento atual.
+- Sem `form.groups`, o Core mantém formulário padrão.
 
-## Exemplo de registry em TypeScript
-
-```tsx
-import manifest from "../central.ui.json";
-import { manifestToConfig, start } from "@oondemand/oon-core-front";
-import { MeusAppsHeader } from "./overrides/MeusAppsHeader";
-import { AppLauncherCard } from "./overrides/AppLauncherCard";
-
-const config = manifestToConfig(manifest, {
-  apiBaseUrl: import.meta.env.VITE_API_URL,
-});
-
-start({
-  ...config,
-  registry: {
-    layoutSlots: {
-      MeusAppsHeader,
-    },
-    cardRenderers: {
-      "cards.appLauncher": AppLauncherCard,
-      appLauncher: AppLauncherCard,
-    },
-  },
-});
-```
+## UX avançada implementada
 
-## Limitações atuais importantes
+Campos aceitos em `collections[]`:
 
-- O atalho `collections[]` do `central.ui.json` lê apenas `model`, `mode`, `path`, `label` e `section`.
-- Para `columns`, `form`, `actions`, `renderer` e `cardRenderer`, use blocos UI v2, `ui.views` em configuração TypeScript ou evolução futura do conversor.
-- `registry` não deve ser escrito em JSON com componentes React. Use código TypeScript.
-- Blocos `collection.form`, `pipeline.board`, `document.viewer`, `dashboard.kpi` e `tabs` estão reservados no contrato, mas precisam de confirmação visual antes de uso em produção.
+- `list.filters`: filtros acima do grid principal.
+- `list.columns`: colunas declarativas opcionais.
+- `list.rowActions`: ações por linha (`openDetailModal`, `navigate`, `apiAction`, `customAction`).
+- `relations`: mapa de relações `{ model, foreignKey, parentKey }`.
+- `detailModal`: modal genérica com `titleField`, `defaultTab`, `size` e `tabs`.
 
-## Checklist para Codex
+Tipos de aba:
 
-Antes de criar UI customizada, confirme:
+- `summary`: cards com `field`, `relatedCount`, `relatedSum`, `relatedAvg` ou `customMetric`.
+- `form`: campos ou `groups` do registro principal.
+- `relatedGrid`: registros filhos, opcionalmente editáveis inline.
+- `readonlyGrid`: registros filhos sem edição.
+- `customComponent`: chave de componente registrado.
 
-- O requisito cabe em `collections`, `documents` ou `pipelines`?
-- O requisito cabe em `pages` + `blocks`?
-- O requisito cabe em renderer registrado por chave?
-- A permissão está declarada em página, bloco, menu ou backend?
-- Não há componente React serializado no JSON?
-- A Central continua funcionando com atualização do pacote Core?
+`apiAction.endpoint` aceita `:id`, `:parentId`, `:fieldName` e `:parent.fieldName`. `refresh` aceita `self`, `parent`, `all` ou ids de abas.