@praxisui/crud 3.0.0-beta.1 → 3.0.0-beta.3

package/README.md

@@ -114,6 +114,117 @@ Checklist rapido para PR:
 - preferir memoizacao por ciclo de vida/signal
 - manter `trackBy` em listas dinamicas
 
+## Fluxo CRUD
+
+O `@praxisui/crud` nao e apenas um wrapper visual. Ele funciona como shell canonico de CRUD da plataforma:
+
+- compoe `praxis-table` como superficie de listagem
+- sintetiza `crudContext` estavel para a tabela
+- delega abertura de `create/view/edit` ao `CrudLauncherService`
+- resolve `route`, `modal` ou `drawer` por precedencia governada
+- propaga `afterOpen`, `afterClose`, `afterSave` e `afterDelete`
+- faz `refetch()` da tabela quando save/delete concluem com sucesso
+
+### Versao Pedagogica de Alto Nivel
+
+Esta e a leitura adequada para documentacao publica e landing pages.
+
+```mermaid
+sequenceDiagram
+    participant Usuario as Usuario
+    participant Crud as praxis-crud
+    participant Tabela as praxis-table
+    participant Launcher as CrudLauncherService
+    participant Host as Host / Router / Dialog / Drawer
+    participant Form as Praxis Dynamic Form
+
+    Usuario->>Tabela: clica em criar, visualizar ou editar
+    Tabela-->>Crud: emite rowAction ou toolbarAction
+    Crud->>Launcher: resolve a acao e o modo de abertura
+    Launcher->>Host: abre por rota, modal ou gaveta
+    Host->>Form: renderiza o formulario do recurso
+    Form-->>Crud: retorna save, delete ou close
+    Crud->>Tabela: refetch() quando save/delete concluem
+    Crud-->>Usuario: fluxo volta para a lista atualizada
+```
+
+Leitura pedagogica:
+
+1. **A tabela dispara a intencao CRUD**.
+2. **O shell `praxis-crud` governa o fluxo**, nao o app consumidor.
+3. **O launcher decide como abrir o formulario**.
+4. **A lista e atualizada automaticamente apos save/delete**.
+
+### Versao Detalhada e Fiel ao Runtime Atual
+
+Esta versao documenta a implementacao atual da lib.
+
+```mermaid
+sequenceDiagram
+    participant Host as Host / metadata
+    participant Crud as PraxisCrudComponent
+    participant Tabela as PraxisTable
+    participant Launcher as CrudLauncherService
+    participant Storage as AsyncConfigStorage
+    participant Router as Angular Router
+    participant Dialog as DialogService
+    participant Drawer as CRUD_DRAWER_ADAPTER
+    participant FormHost as DynamicFormDialogHost
+    participant Form as PraxisDynamicForm
+
+    Host->>Crud: fornece metadata + crudId
+    Crud->>Crud: assertCrudMetadata(allowDeferredActionBindings=true)
+    Crud->>Crud: buildEffectiveTableConfig()
+    Crud->>Crud: buildTableCrudContext()
+    Crud->>Tabela: renderiza table + crudContext
+
+    alt acao na toolbar
+        Tabela-->>Crud: toolbarAction(action)
+    else acao na linha
+        Tabela-->>Crud: rowAction(action, row)
+    end
+
+    Crud->>Crud: onAction(action, row)
+    Crud->>Launcher: launch(actionMeta, row, metadata, componentKeyId)
+    Launcher->>Storage: load crud-overrides:<componentKeyId>
+    Launcher->>Launcher: mergeCrudOverrides()
+    Launcher->>Launcher: resolveOpenMode()
+
+    alt route
+        Launcher->>Router: navigateByUrl(route + query params)
+    else drawer
+        Launcher->>Drawer: open({ action, metadata, inputs })
+    else modal
+        Launcher->>Dialog: openAsync(DynamicFormDialogHost)
+        Dialog->>FormHost: injeta action + metadata + inputs
+        FormHost->>FormHost: resolve resourcePath, idField, resourceId, mode
+        FormHost->>Form: renderiza PraxisDynamicForm
+        Form-->>FormHost: formSubmit / formCancel
+        FormHost-->>Crud: DialogRef.afterClosed()
+    end
+
+    Crud-->>Host: afterOpen(mode, action)
+
+    alt save
+        Crud-->>Host: afterSave(id, data)
+        Crud->>Tabela: refetch()
+    else delete
+        Crud-->>Host: afterDelete(id)
+        Crud->>Tabela: refetch()
+    else close
+        Crud-->>Host: afterClose()
+    end
+```
+
+### Pontos-Chave do Runtime
+
+1. **`crudContext` precisa ser estavel**: o componente nao usa getter dinamico no template; ele memoiza o contexto quando o metadata muda.
+2. **`PraxisCrudComponent` pode completar a UX da tabela**: ele injeta automaticamente toolbar add e row actions quando o metadata declara acoes e o host nao configurou a tabela explicitamente.
+3. **A validacao estrutural do metadata e estrita, mas aceita bindings diferidos**: `route` e `formId` podem ser completados por overrides persistidos imediatamente antes da abertura.
+4. **O `CrudLauncherService` e a fonte de verdade para `openMode`**: ele mescla overrides persistidos, defaults do metadata e GlobalConfig antes de decidir `route`, `modal` ou `drawer`.
+5. **Modal e drawer nao sao equivalentes internamente**: o ramo modal usa `DynamicFormDialogHostComponent`; o ramo drawer depende do adapter provido pelo host.
+6. **Save e delete geram refetch automatico da lista**: esse side effect faz parte do contrato atual do shell CRUD.
+
 ## Documentacao Tecnica da Lib
 
 - `projects/praxis-crud/docs/host-crud-runtime-and-openmode.md`

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@praxisui/crud",
-  "version": "3.0.0-beta.1",
+  "version": "3.0.0-beta.3",
   "description": "CRUD building blocks for Praxis UI: integrates dynamic forms and tables with unified configuration and services.",
   "peerDependencies": {
     "@angular/common": "^20.1.0",
     "@angular/core": "^20.1.0",
-    "@praxisui/dynamic-form": "^3.0.0-beta.1",
-    "@praxisui/table": "^3.0.0-beta.1",
-    "@praxisui/core": "^3.0.0-beta.1",
-    "@praxisui/dynamic-fields": "^3.0.0-beta.1",
-    "@praxisui/settings-panel": "^3.0.0-beta.1"
+    "@praxisui/dynamic-form": "^3.0.0-beta.3",
+    "@praxisui/table": "^3.0.0-beta.3",
+    "@praxisui/core": "^3.0.0-beta.3",
+    "@praxisui/dynamic-fields": "^3.0.0-beta.3",
+    "@praxisui/settings-panel": "^3.0.0-beta.3"
   },
   "dependencies": {
     "tslib": "^2.3.0"