@oondemand/create-central-oon 0.5.6 → 0.6.0

package/templates/_base/frontend/src/app/app.tsx

@@ -0,0 +1,25 @@
+import { defineOonApp, type OonAppKind, type OonTenancyModel } from "@oondemand/oon-core-front";
+import manifest from "../../../central.app.json";
+import { navigation } from "./navigation";
+import { routes } from "./routes";
+import { theme } from "./theme";
+
+export const app = defineOonApp({
+  app: {
+    id: manifest.id,
+    name: manifest.name,
+    title: manifest.name,
+    kind: manifest.appKind as OonAppKind,
+    tenancyModel: manifest.tenancyModel as OonTenancyModel,
+    capabilities: manifest.capabilities,
+  },
+  api: {
+    baseUrl: import.meta.env.VITE_API_URL ?? "/api",
+    meusAppsUrl: import.meta.env.DEV ? undefined : import.meta.env.VITE_MEUS_APPS_URL,
+  },
+  runtimeMode: import.meta.env.DEV ? "local" : "platform",
+  routes,
+  navigation,
+  theme,
+  shell: { shell: "default" },
+});

package/templates/_base/frontend/src/app/navigation.ts

@@ -0,0 +1,5 @@
+import { defineOonNavigation } from "@oondemand/oon-core-front/routing";
+
+export const navigation = defineOonNavigation([
+  { label: "Início", href: "/", order: 10 },
+]);

package/templates/_base/frontend/src/app/routes.tsx

@@ -0,0 +1,6 @@
+import { defineOonRoutes } from "@oondemand/oon-core-front/routing";
+import { HomePage } from "../pages/HomePage";
+
+export const routes = defineOonRoutes([
+  { path: "/", component: HomePage },
+]);

package/templates/_base/frontend/src/app/theme.ts

@@ -0,0 +1,8 @@
+import { createOonTheme, oonDefaultTheme } from "@oondemand/oon-core-front/theme";
+
+export const theme = createOonTheme({
+  id: "__SLUG__",
+  label: "__NAME__",
+  extends: oonDefaultTheme,
+  density: "comfortable",
+});

package/templates/_base/frontend/src/components/gitkeep

@@ -0,0 +1 @@
+

package/templates/_base/frontend/src/features/gitkeep

@@ -0,0 +1 @@
+

package/templates/_base/frontend/src/layouts/gitkeep

@@ -0,0 +1 @@
+

package/templates/_base/frontend/src/main.tsx

@@ -1,9 +1,4 @@
-import { startCentralFromManifest } from "@oondemand/oon-core-front";
-import app from "../../central.app.json";
-import ui from "../central.ui.json";
+import { startOonApp } from "@oondemand/oon-core-front";
+import { app } from "./app/app";
 
-startCentralFromManifest({ app, ui }, {
-  apiBaseUrl: import.meta.env.VITE_API_URL ?? "/api",
-  runtimeMode: import.meta.env.DEV ? "local" : "platform",
-  meusAppsUrl: import.meta.env.DEV ? undefined : import.meta.env.VITE_MEUS_APPS_URL,
-});
+startOonApp(app);

package/templates/_base/frontend/src/pages/HomePage.tsx

@@ -0,0 +1,25 @@
+import { Stack, Text } from "@chakra-ui/react";
+import { CorePage, CorePageHeader, CoreStatusPanel, CoreSummaryCards } from "@oondemand/oon-core-front/ui";
+
+export function HomePage() {
+  return (
+    <CorePage>
+      <CorePageHeader
+        title="Boas-vindas ao __NAME__"
+        description="A fundação técnica está pronta para receber a experiência e o domínio do app."
+      />
+      <Stack gap={6}>
+        <CoreSummaryCards items={[
+          { id: "core", label: "OonCore", value: "Pronto", description: "Shell, autenticação, sessão, tenant e RBAC." },
+          { id: "platform", label: "Plataforma Oon", value: "Governada", description: "Publicação, ambientes, acesso e proveniência." },
+        ]} />
+        <CoreStatusPanel
+          title="Próximos passos"
+          status="Code-first"
+          description="Crie páginas em src/pages, componentes em src/components e organize o domínio em src/features."
+        />
+        <Text color="text.muted">Menus, rotas, layouts e temas ficam em src/app e podem combinar componentes locais com blocos públicos do OonCore.</Text>
+      </Stack>
+    </CorePage>
+  );
+}

package/templates/_base/frontend/tsconfig.json

@@ -13,5 +13,5 @@
     "isolatedModules": true,
     "types": ["vite/client"]
   },
-  "include": ["src", "central.ui.json", "vite.config.ts"]
+  "include": ["src", "vite.config.ts"]
 }

package/templates/_base/package.json

@@ -13,6 +13,6 @@
     "dev:frontend": "npm run dev --prefix frontend"
   },
   "devDependencies": {
-    "@oondemand/create-central-oon": "0.5.6"
+    "@oondemand/create-central-oon": "0.6.0"
   }
 }

package/docs/CONNECTORS_AND_INTEGRATIONS.md

@@ -1,66 +0,0 @@
-# Conectores e Integrações
-
-Toda integração deve ser modelada como um processo rastreável, não como chamada solta dentro de controller.
-
-## Objetivo
-
-Transformar cada integração em:
-
-```txt
-configuração + mapping + execução + status + rastreabilidade
-```
-
-## Estrutura recomendada
-
-```txt
-backend/src/integrations/
-├── <sistema>/
-│   ├── client.js
-│   ├── mappings/
-│   ├── services/
-│   └── README.md
-```
-
-## Client
-
-O client deve concentrar:
-
-- URL base;
-- autenticação;
-- headers;
-- timeout;
-- retry técnico;
-- normalização de erro.
-
-Não coloque regra de negócio no client.
-
-## Mapping
-
-Mappings devem transformar dados entre a Central e o sistema externo.
-
-Regras:
-
-- mapping deve ser explícito;
-- campos obrigatórios devem ser validados antes do envio;
-- resposta externa deve ser normalizada;
-- erros devem ser compreensíveis para operação.
-
-## Esteira de integração
-
-Toda integração relevante deve gerar registro operacional com:
-
-- origem;
-- destino;
-- payload resumido ou referência;
-- status;
-- tentativas;
-- erro normalizado;
-- data/hora;
-- usuário ou processo responsável.
-
-## Segurança
-
-- Nunca versionar app key, secret, token ou credencial.
-- Não logar payloads sensíveis sem necessidade.
-- Não expor credenciais no frontend.
-- Usar `.env` e configuração de ambiente.

package/docs/FRONTEND_MANIFEST_REFERENCE.md

@@ -1,487 +0,0 @@
-# Referência do Manifesto Frontend OonCore
-
-Este documento é a referência operacional para qualquer Agent 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 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
-
-```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 Agents, a ordem recomendada é:
-
-1. Começar pelo `central.ui.json`.
-2. Usar `pages` e `blocks` quando precisar de UI v2.
-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
-
-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?: OonCollectionManifestDef[];
-  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` | Views de coleção, simples ou avançadas. |
-| `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`. |
-
-## Navigation
-
-```ts
-type OonNavigationMode = "auto" | "manual" | "mixed";
-
-interface OonNavigationConfig {
-  mode?: OonNavigationMode;
-  items?: OonMenuItem[];
-}
-```
-
-## Collections no central.ui.json
-
-Atalho para coleções simples ou avançadas.
-
-```ts
-interface OonCollectionManifestDef {
-  model: string;
-  mode?: "full" | "minimal" | "dynamic";
-  path?: string;
-  label?: string;
-  section?: string;
-  list?: OonCollectionListConfig;
-  relations?: Record<string, OonRelationDef>;
-  detailModal?: OonDetailModalConfig;
-}
-```
-
-### Exemplo simples
-
-```json
-{
-  "collections": [
-    {
-      "model": "Cliente",
-      "mode": "dynamic",
-      "path": "/clientes",
-      "label": "Clientes",
-      "section": "Cadastros"
-    }
-  ]
-}
-```
-
-### Exemplo avançado
-
-```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": []
-      }
-    }
-  ]
-}
-```
-
-## list
-
-Configura filtros, colunas e ações do grid principal.
-
-```ts
-interface OonCollectionListConfig {
-  filters?: OonListFilterDef[];
-  columns?: Array<string | OonColumnDef>;
-  rowActions?: OonRowActionDef[];
-}
-```
-
-### list.filters
-
-```json
-{
-  "field": "tipoRegistro",
-  "label": "Tipo",
-  "type": "select",
-  "options": [
-    { "label": "Todos", "value": "" },
-    { "label": "Orçamento", "value": "Orçamento" }
-  ]
-}
-```
-
-Tipos previstos:
-
-- `text`
-- `select`
-- `date`
-- `dateRange`
-- `numberRange`
-- `boolean`
-- `ref`
-
-### list.rowActions
-
-```json
-{
-  "type": "openDetailModal",
-  "label": "Editar",
-  "icon": "edit",
-  "initialTab": "resumo"
-}
-```
-
-## relations
-
-Relações nomeadas entre model pai e models filhos.
-
-```json
-{
-  "relations": {
-    "itens": {
-      "model": "OrcamentoItem",
-      "foreignKey": "projetoId",
-      "parentKey": "_id"
-    }
-  }
-}
-```
-
-## detailModal
-
-Configura modal de detalhe/criação com abas.
-
-```ts
-interface OonDetailModalConfig {
-  enabled?: boolean;
-  titleField?: string;
-  size?: "md" | "lg" | "xl" | "full";
-  defaultTab?: string;
-  tabs: OonDetailTabDef[];
-}
-```
-
-### Abas suportadas
-
-- `summary`
-- `form`
-- `relatedGrid`
-- `readonlyGrid`
-- `customComponent`
-
-### Aba summary
-
-```json
-{
-  "id": "resumo",
-  "label": "Resumo",
-  "type": "summary",
-  "cards": [
-    { "label": "Itens", "source": "relatedCount", "relation": "itens" },
-    { "label": "Total", "field": "total", "format": "currency" }
-  ]
-}
-```
-
-### Aba form
-
-```json
-{
-  "id": "dados",
-  "label": "Dados Principais",
-  "type": "form",
-  "groups": [
-    { "label": "Identificação", "fields": ["codigo", "nome", "status"] }
-  ]
-}
-```
-
-### Aba relatedGrid
-
-```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": []
-}
-```
-
-### Aba readonlyGrid
-
-```json
-{
-  "id": "pagamentos",
-  "label": "Pagamentos",
-  "type": "readonlyGrid",
-  "relation": "pagamentos",
-  "columns": ["codigo", "descricao", "status", "valor"]
-}
-```
-
-## rowActions
-
-Ações reutilizáveis em grid principal ou grids relacionados.
-
-```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[];
-}
-```
-
-### apiAction
-
-```json
-{
-  "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"]
-}
-```
-
-## 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[];
-  list?: OonCollectionListConfig;
-  relations?: Record<string, OonRelationDef>;
-  detailModal?: OonDetailModalConfig;
-}
-```
-
-## Compatibilidade
-
-- 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.
-
-## UX avançada implementada
-
-Campos aceitos em `collections[]`:
-
-- `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`.
-
-Tipos de aba:
-
-- `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.
-
-`apiAction.endpoint` aceita `:id`, `:parentId`, `:fieldName` e `:parent.fieldName`. `refresh` aceita `self`, `parent`, `all` ou ids de abas.
-
-
-## Opções remotas em campos de formulário
-
-Campos `enum` podem carregar opções de um endpoint dependente do formulário atual ou do registro pai. O contrato funciona em formulários principais e em criação/edição de `relatedGrid`.
-
-```ts
-{
-  field: "roleCode",
-  label: "Perfil",
-  kind: "enum",
-  optionsEndpoint: "/control-plane/app-role-catalogs/:appId?tenantId=:parentId",
-  optionsResponsePath: "options",
-  optionsValueField: "value",
-  optionsLabelField: "label",
-  optionsDescriptionField: "description",
-  optionsEditablePath: "editable",
-  optionsDependsOn: ["appId", "tenantId"],
-  fallbackOptions: [{ value: "admin", label: "Administrador" }],
-  readonlyOnFallback: true,
-  optionsUnavailableMessage: "Catálogo indisponível; perfil admin aplicado."
-}
-```
-
-| Campo | Uso |
-| --- | --- |
-| `optionsEndpoint` | Endpoint relativo. Aceita `:field`, `:parentId` e `:parent.field`; valores são codificados para URL. |
-| `optionsResponsePath` | Caminho da lista na resposta. Sem valor, a própria resposta deve ser um array. |
-| `optionsValueField` | Campo usado como valor da opção; padrão `value`. |
-| `optionsLabelField` | Campo usado como rótulo; padrão `label`. |
-| `optionsDescriptionField` | Campo opcional de descrição. |
-| `optionsEditablePath` | Booleano remoto que permite ou bloqueia a edição. |
-| `optionsDependsOn` | Campos que precisam estar preenchidos e cuja mudança invalida a seleção atual. |
-| `fallbackOptions` | Opções seguras usadas quando o endpoint falha ou retorna lista vazia. |
-| `readonlyOnFallback` | Bloqueia a seleção durante o fallback; padrão `true`. |
-| `optionsUnavailableMessage` | Mensagem explicando o fallback ao usuário. |
-| `readonly` | Bloqueia o campo em qualquer estado. |
-
-Durante a edição, a interpolação também considera os valores iniciais completos do registro, inclusive campos somente leitura que não são renderizados no formulário. Valores alterados pelo usuário prevalecem sobre os valores iniciais.
-
-O backend continua responsável por validar o valor selecionado. Opções remotas melhoram a experiência, mas não substituem autorização nem validação de domínio.