@oondemand/create-central-oon 0.3.9 → 0.3.10

package/README.md

@@ -40,6 +40,12 @@ Aliases: o binário também responde por `scaffold-central-oon`.
 
 O pacote inclui documentação canônica em `docs/`. Ela é publicada no npm junto com o gerador.
 
+A referência completa das opções do manifesto front fica em:
+
+```txt
+packages/create-central-oon/docs/FRONTEND_MANIFEST_REFERENCE.md
+```
+
 Ao criar uma Central, o CLI gera uma pasta `.ooncore/` com um cache local da documentação da versão instalada:
 
 ```txt

package/docs/FRONTEND_MANIFEST_REFERENCE.md

@@ -0,0 +1,691 @@
+# Referência do Manifesto Frontend OonCore
+
+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.
+
+## Arquivos envolvidos
+
+```txt
+frontend/central.ui.json               # manifesto declarativo da Central
+frontend/src/main.tsx                   # bootstrap do frontend
+packages/oonCore-front/src/manifest.ts # conversão central.ui.json -> OonCoreFrontConfig
+packages/oonCore-front/src/types.ts    # tipos oficiais do contrato
+```
+
+## Regra principal
+
+O manifesto JSON não deve carregar componentes React. Ele só pode declarar dados e chaves de renderer, como:
+
+```txt
+custom:MeusAppsHeader
+fields.password
+cells.statusBadge
+cards.appLauncher
+actions.ativarApp
+menus.portal
+```
+
+Os componentes reais devem ser registrados em código TypeScript/React pelo `registry`.
+
+## Níveis de contrato
+
+Existem três níveis importantes:
+
+1. `central.ui.json`: entrada declarativa usada pelas Centrais geradas.
+2. `CentralUiManifest`: contrato lido por `startFromManifest`.
+3. `OonUiManifest` / `OonCoreFrontConfig`: contrato interno mais completo do Core Front.
+
+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.
+
+## CentralUiManifest
+
+Contrato aceito por `startFromManifest(manifest, runtime)`.
+
+```ts
+interface CentralUiManifest {
+  name: string;
+  slug: string;
+  backend?: { metadataUrl?: string };
+  schemaVersion?: 1 | 2;
+  layout?: OonLayoutConfig;
+  registry?: OonComponentRegistry;
+  navigation?: OonNavigationConfig;
+  pages?: OonPageDef[];
+  collections?: Array<{
+    model: string;
+    mode?: CollectionMode;
+    path?: string;
+    label?: string;
+    section?: string;
+  }>;
+  pipelines?: Array<{
+    name?: string;
+    model?: string;
+    mode?: string;
+    stageField?: string;
+    path?: string;
+    label?: string;
+    section?: string;
+  }>;
+  documents?: Array<{
+    model: string;
+    mode?: string;
+    path?: string;
+    label?: string;
+    section?: string;
+    approval?: boolean;
+    attachments?: boolean;
+  }>;
+}
+```
+
+### Opções de raiz
+
+| Campo | Tipo | Uso |
+| --- | --- | --- |
+| `name` | `string` | Nome exibido da Central. |
+| `slug` | `string` | Identificador da Central/app. |
+| `backend.metadataUrl` | `string` | URL explícita de metadata, quando aplicável. |
+| `schemaVersion` | `1 \| 2` | Sem valor = compatibilidade v1. Use `2` para UI v2. |
+| `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. |
+| `pipelines` | `Array` | Atalho para gerar esteiras. |
+| `documents` | `Array` | Atalho para gerar documentos. |
+
+## Layout
+
+```ts
+type OonSlotConfig = "core" | "none" | `custom:${string}`;
+
+interface OonLayoutConfig {
+  shell?: "default" | "portal" | "content-only" | `custom:${string}`;
+  sidebar?: OonSlotConfig;
+  topbar?: OonSlotConfig;
+  header?: "none" | `custom:${string}`;
+  footer?: "core" | "none" | `custom:${string}`;
+  assistant?: "core" | "none" | `custom:${string}`;
+  main?: "core";
+}
+```
+
+### Valores de `layout.shell`
+
+| Valor | Comportamento |
+| --- | --- |
+| `default` | Shell operacional padrão com sidebar/topbar. |
+| `portal` | Shell para portal, útil para Meus Apps ou home de cards. |
+| `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
+type OonNavigationMode = "auto" | "manual" | "mixed";
+
+interface OonNavigationConfig {
+  mode?: OonNavigationMode;
+  items?: OonMenuItem[];
+}
+```
+
+### 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. |
+
+## Menu item
+
+```ts
+interface OonMenuItem {
+  label: string;
+  href: string;
+  icon?: ReactNode;
+  section?: string;
+  order?: number;
+  permissions?: string[];
+  children?: OonMenuItem[];
+  badge?: string | number;
+  external?: boolean;
+  hidden?: boolean;
+  action?: string;
+  renderer?: string;
+}
+```
+
+### 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.
+
+```json
+{
+  "collections": [
+    {
+      "model": "Cliente",
+      "mode": "dynamic",
+      "path": "/clientes",
+      "label": "Clientes",
+      "section": "Cadastros"
+    }
+  ]
+}
+```
+
+### 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.
+
+```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[];
+}
+```
+
+### Form field
+
+```ts
+interface OonFormFieldDef {
+  field: string;
+  label?: string;
+  kind?: FieldKind;
+  required?: boolean;
+  options?: string[];
+  ref?: string;
+  renderer?: string;
+  permissions?: string[];
+}
+```
+
+### Action
+
+```ts
+interface OonActionDef {
+  id: string;
+  label?: string;
+  renderer?: string;
+  permissions?: string[];
+  action?: string;
+}
+```
+
+## Documents
+
+```json
+{
+  "documents": [
+    {
+      "model": "DocumentoFiscal",
+      "path": "/documentos-fiscais",
+      "label": "Documentos Fiscais",
+      "section": "Fiscal",
+      "approval": true,
+      "attachments": true
+    }
+  ]
+}
+```
+
+### Opções
+
+| 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. |
+
+## Pipelines
+
+```json
+{
+  "pipelines": [
+    {
+      "model": "Pedido",
+      "stageField": "status",
+      "path": "/pedidos/esteira",
+      "label": "Esteira de Pedidos",
+      "section": "Operação"
+    }
+  ]
+}
+```
+
+### 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
+
+```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[];
+}
+```
+
+## 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;
+}
+```
+
+Observação: `render` é função React e não deve estar em JSON. Use somente em configuração TypeScript.
+
+## Pages UI v2
+
+Páginas permitem compor rotas por blocos.
+
+```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;
+}
+```
+
+### Opções de página
+
+| 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;
+}
+```
+
+### custom
+
+```json
+{
+  "type": "custom",
+  "component": "MeusAppsHero",
+  "props": {
+    "titulo": "Bem-vindo"
+  }
+}
+```
+
+Renderiza componente de `registry.pageComponents.MeusAppsHero`.
+
+### collection.datagrid
+
+```json
+{
+  "type": "collection.datagrid",
+  "model": "App",
+  "mode": "dynamic",
+  "title": "Apps"
+}
+```
+
+Opções:
+
+```ts
+interface OonCollectionDataGridBlockDef {
+  type: "collection.datagrid";
+  model: string;
+  mode?: CollectionMode;
+  renderer?: string;
+  columns?: OonColumnDef[];
+  form?: OonFormFieldDef[];
+}
+```
+
+### collection.cards
+
+```json
+{
+  "type": "collection.cards",
+  "model": "App",
+  "renderer": "cards.appLauncher"
+}
+```
+
+Renderiza cards usando `registry.cardRenderers.appLauncher` quando registrado.
+
+### section
+
+```json
+{
+  "type": "section",
+  "title": "Administração",
+  "description": "Gestão dos apps e permissões",
+  "blocks": [
+    { "type": "collection.datagrid", "model": "Usuario" }
+  ]
+}
+```
+
+### markdown
+
+```json
+{
+  "type": "markdown",
+  "content": "Texto institucional ou instruções da página."
+}
+```
+
+### 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.
+
+## Registry
+
+```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 }
+  ]
+}
+```
+
+## Exemplo v2 portal / Meus Apps
+
+```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" }
+      ]
+    }
+  ]
+}
+```
+
+## 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,
+    },
+  },
+});
+```
+
+## Limitações atuais importantes
+
+- 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.
+
+## Checklist para Codex
+
+Antes de criar UI customizada, confirme:
+
+- 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?

package/docs/FRONTEND_PATTERNS.md

@@ -2,6 +2,8 @@
 
 O frontend da Central deve ser declarativo. Shell, providers, rotas, menu, datagrid, formulários, documentos e esteiras pertencem ao `@oondemand/oon-core-front`.
 
+Para a lista completa de opções do manifesto, use `FRONTEND_MANIFEST_REFERENCE.md`.
+
 ## Estrutura esperada
 
 ```txt
@@ -29,7 +31,16 @@ Use `central.ui.json` como entrada principal para declarar:
 - documentos;
 - esteiras;
 - dashboards;
-- agrupamentos.
+- agrupamentos;
+- layout v2;
+- páginas por blocos;
+- renderers por chave.
+
+## Manifesto v1 e v2
+
+- Manifesto sem `schemaVersion` mantém compatibilidade v1.
+- Manifesto com `schemaVersion: 2` habilita composição por `layout`, `navigation`, `pages` e `blocks`.
+- Componentes React não devem ser serializados no JSON; use chaves e registre os componentes no `registry` em TypeScript.
 
 ## Regras
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oondemand/create-central-oon",
-  "version": "0.3.9",
+  "version": "0.3.10",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/oondemand/oon-platform.git",

package/templates/_base/backend/package.json

@@ -12,6 +12,6 @@
     "deploy": "oonCore-back deploy"
   },
   "dependencies": {
-    "@oondemand/oon-core-back": "^0.3.9"
+    "@oondemand/oon-core-back": "^0.3.10"
   }
 }

package/templates/_base/frontend/package.json

@@ -10,7 +10,7 @@
     "sync:metadata": "oonCore-front sync:metadata"
   },
   "dependencies": {
-    "@oondemand/oon-core-front": "^0.3.9",
+    "@oondemand/oon-core-front": "^0.3.10",
     "@chakra-ui/react": "^3.13.0",
     "@emotion/react": "^11.14.0",
     "@tanstack/react-query": "^5.65.0",