@praxisui/table 3.0.0-beta.1 → 3.0.0-beta.2

package/README.md

@@ -379,7 +379,7 @@ Quando `resourcePath` é fornecido, a tabela se torna "inteligente":
 Neste exemplo:
 
 - `resourcePath="human-resources/departamentos"` instrui a tabela a se comunicar com o endpoint `/api/human-resources/departamentos`.
-- A tabela fará requisições como `POST /api/human-resources/departamentos/filter` para obter os dados e `GET /api/human-resources/departamentos/schemas` para obter a configuração das colunas.
+- A tabela fará requisições como `POST /api/human-resources/departamentos/filter` para obter os dados e `GET /schemas/filtered?path=/api/human-resources/departamentos/all&operation=get&schemaType=response` para obter o schema estrutural usado no bootstrap das colunas.
 - `enableCustomization` controla explicitamente o gate de edição visual. O default canônico agora é `false`; declare `[enableCustomization]="true"` quando o host quiser expor customização e surfaces editoriais.
 
 ### Empty State + Quick Connect (sem `resourcePath`)
@@ -394,20 +394,22 @@ Ao aplicar/salvar, a `<praxis-table>` é automaticamente configurada para buscar
 
 ### Fluxo de Comunicação do `resourcePath`
 
-O diagrama abaixo ilustra como a propriedade `resourcePath` conecta o componente frontend ao controller do backend. O fluxo de inicialização ocorre em três etapas principais: **Configurar**, **Carregar Schema** e **Buscar Dados**.
+O diagrama abaixo ilustra como a propriedade `resourcePath` conecta o componente frontend ao backend no runtime atual da tabela. Antes de iniciar o fluxo remoto, a lib resolve o modo de dados com precedência **`resourcePath` explícito > `data` local > conexão persistida**. Quando o modo efetivo é `remote`, o bootstrap ocorre em três etapas principais: **Configurar**, **Carregar Schema estrutural** e **Buscar Dados**.
 
 ```mermaid
 sequenceDiagram
     participant FE_Component as Componente Angular<br>(departamentos.html)
     participant Praxis_Table as @praxisui/table<br>(praxis-table.ts)
     participant Crud_Service as @praxisui/core<br>(generic-crud.service.ts)
+    participant Docs_Controller as ApiDocsController<br>(/schemas/filtered)
     participant BE_Controller as Backend Controller<br>(DepartamentoController.java)
-    participant Abstract_Controller as AbstractCrudController
+    participant Abstract_Controller as AbstractCrudController<br>(/filter)
 
     FE_Component->>Praxis_Table: Usa o componente com <br> <praxis-table resourcePath="human-resources/departamentos">
 
     activate Praxis_Table
-    Praxis_Table->>Praxis_Table: ngOnChanges() detecta o @Input() resourcePath
+    Praxis_Table->>Praxis_Table: ngOnInit()/ngOnChanges() resolve dataMode
+    Note over Praxis_Table: remote quando há resourcePath efetivo
     Praxis_Table->>Crud_Service: 1. Chama crudService.configure("human-resources/departamentos")
 
     activate Crud_Service
@@ -418,24 +420,19 @@ sequenceDiagram
     Praxis_Table->>Crud_Service: Chama crudService.getSchema()
 
     activate Crud_Service
-    Crud_Service->>Crud_Service: getEndpointUrl('schema') constrói a URL: <br> "/api/human-resources/departamentos/schemas"
-    Crud_Service->>BE_Controller: Requisição HTTP GET para .../schemas
+    Crud_Service->>Crud_Service: schemaUrl() preserva o base path canônico
+    Crud_Service->>Crud_Service: Deriva path="/api/human-resources/departamentos/all"<br>operation="get", schemaType="response"
+    Crud_Service->>Docs_Controller: GET /schemas/filtered?path=.../all&operation=get&schemaType=response
     deactivate Crud_Service
 
-    activate BE_Controller
-    Note over BE_Controller: @RequestMapping("/human-resources/departamentos")
-    BE_Controller->>Abstract_Controller: Herda o método que lida com @GetMapping("/schemas")
-
-    activate Abstract_Controller
-    Abstract_Controller->>Abstract_Controller: Gera e retorna o Schema da UI
-    Abstract_Controller-->>BE_Controller: Retorna o Schema
-    deactivate Abstract_Controller
-
-    BE_Controller-->>Crud_Service: Resposta HTTP com o JSON do Schema
-    deactivate BE_Controller
+    activate Docs_Controller
+    Docs_Controller->>Docs_Controller: Resolve grupo OpenAPI a partir do path
+    Docs_Controller->>Docs_Controller: Filtra payload estrutural + x-ui
+    Docs_Controller-->>Crud_Service: 200/304 com schema + ETag/X-Schema-Hash
+    deactivate Docs_Controller
 
     activate Crud_Service
-    Crud_Service-->>Praxis_Table: Retorna um Observable com as<br>definições de colunas (FieldDefinition[])
+    Crud_Service-->>Praxis_Table: Normaliza schema e retorna FieldDefinition[]
     deactivate Crud_Service
 
     Praxis_Table->>Praxis_Table: Constrói as colunas da tabela<br>a partir do schema recebido
@@ -460,13 +457,20 @@ sequenceDiagram
     deactivate BE_Controller
 
     activate Crud_Service
-    Crud_Service-->>Praxis_Table: Retorna um Observable com os dados
+    Crud_Service-->>Praxis_Table: Retorna Page<T> com os dados paginados
     deactivate Crud_Service
 
     Praxis_Table->>Praxis_Table: Atualiza o dataSource da tabela com os dados recebidos
     deactivate Praxis_Table
 ```
 
+Notas importantes:
+
+- O host informa `resourcePath` sem o prefixo `/api`; o `GenericCrudService` resolve as URLs reais do backend a partir da configuração de API do host.
+- O bootstrap de schema não depende mais de uma chamada frontend para `GET /{resource}/schemas`; o runtime consome diretamente `/schemas/filtered` com `ETag`/`X-Schema-Hash`.
+- O `praxis-filter` acoplado acompanha o mesmo `resourcePath` em modo remoto e deriva seu schema via `/schemas/filtered?path=.../filter&operation=post&schemaType=request`.
+- Sem `resourcePath` efetivo, a tabela não entra nesse fluxo remoto; ela cai em `local` ou `empty` conforme a precedência canônica.
+
 ## ℹ️ Dicas de UX (Tabela)
 
 - Multi‑sort: habilite em Comportamento → Ordenação. No uso, mantenha Ctrl/Cmd pressionado ao clicar em múltiplas colunas.
@@ -805,12 +809,13 @@ sequenceDiagram
   autonumber
   participant PT as PraxisTable
   participant GS as GenericCrudService
-  participant API as Backend
+  participant Docs as ApiDocsController (/schemas/filtered)
 
   PT->>GS: configure(resourcePath)
   PT->>GS: getSchema()
-  GS->>API: GET {resource}/schemas → 302 → /schemas/filtered
-  API-->>GS: 200/304 schema + x-ui.resource.idField
+  GS->>GS: deriva path=/api/.../all + schemaType=response
+  GS->>Docs: GET /schemas/filtered?path=.../all&operation=get&schemaType=response
+  Docs-->>GS: 200/304 schema + x-ui.resource.idField
   GS->>GS: cache + lastResourceMeta.idField
   GS-->>PT: FieldDefinition[] (normalizado)
   Note over PT: idField = input || context || GS.getResourceIdField() || 'id'
@@ -827,11 +832,12 @@ sequenceDiagram
   participant API as Backend
 
   PT->>PT: key = getIdField() (precedência)
-  PT->>PT: id = row[key] || row['id'] || heurísticas
+  PT->>PT: id = getNestedPropertyValue(row, key)
   PT->>GS: delete(id)
   GS->>API: DELETE {resource}/{id}
   API-->>GS: 204 No Content
-  GS-->>PT: sucesso → refresh
+  GS-->>PT: sucesso
+  PT->>PT: fetchData() em modo remoto
 ```
 
 ### Troubleshooting rápido (idField)
@@ -882,78 +888,113 @@ export class ExampleComponent {
 
 ## ⚙️ Fluxo de Paginação e Filtros (Server-Side)
 
-Quando a `<praxis-table>` é conectada a um `resourcePath`, as operações de paginação, ordenação e filtro são delegadas ao backend. Isso garante alta performance, pois apenas os dados visíveis na tela são trafegados pela rede.
+Quando a `<praxis-table>` opera com `resourcePath`, o runtime resolve o modo remoto e passa a delegar paginação, ordenação e filtros ao backend. Isso reduz tráfego, preserva a semântica do DTO de filtro e mantém o banco como fonte de verdade para `WHERE`, `ORDER BY`, `LIMIT` e `OFFSET`.
 
 Importante: se você não configurar explicitamente as estratégias de paginação/ordenação no `TableConfig`, a tabela resolve automaticamente como `server` quando há `resourcePath`. Se preferir operar no cliente, defina `behavior.pagination.strategy = 'client'` e/ou `behavior.sorting.strategy = 'client'` conscientemente.
 
-O diagrama abaixo detalha a sequência de eventos, desde a interação do usuário na UI até a construção da consulta JPA no servidor.
+### Versão Pedagógica de Alto Nível
+
+Esta é a leitura adequada para documentação pública e landing pages.
 
 ```mermaid
 sequenceDiagram
-    participant UI as @praxisui/table (UI)
-    participant CrudService as @praxisui/core (GenericCrudService)
-    participant Controller as Backend (AbstractCrudController)
-    participant Service as Backend (BaseCrudService)
-    participant SpecBuilder as Backend (GenericSpecificationsBuilder)
-    participant Repository as Spring Data JPA (JpaSpecificationExecutor)
-
-    UI->>UI: Usuário clica na página 2 e<br>digita "Tech" no filtro de nome.
-
-    UI->>UI: onPageChange({pageIndex: 1, pageSize: 10})<br>onFilterChange({nome: 'Tech'})
-
-    UI->>UI: Chama fetchData() com:<br>filterCriteria = {nome: 'Tech'}<br>pageable = {pageNumber: 1, pageSize: 10, sort: 'nome,asc'}
-
-    UI->>CrudService: Chama .filter({nome: 'Tech'}, pageable)
-
-    activate CrudService
-    CrudService->>CrudService: Cria HttpParams:<br>page=1, size=10, sort=nome,asc
-    CrudService->>Controller: Requisição POST para /api/.../filter<br>Body: {nome: 'Tech'}<br>Params: ?page=1&size=10&sort=nome,asc
-    deactivate CrudService
-
-    activate Controller
-    Controller->>Controller: Spring injeta o corpo no FilterDTO<br>e os params no objeto Pageable.
-    Controller->>Service: Chama .filter(filterDTO, pageable)
-    deactivate Controller
-
-    activate Service
-    Service->>SpecBuilder: Chama .buildSpecification(filterDTO)
+    participant Usuario as Usuário
+    participant Tabela as praxis-table
+    participant Frontend as GenericCrudService
+    participant Backend as API Praxis
+    participant Banco as Banco de Dados
+
+    Usuario->>Tabela: muda página, ordena ou aplica filtro
+    Tabela->>Tabela: consolida filterCriteria + paginação + sort
+    Tabela->>Frontend: filter(criteria, pageable)
+    Frontend->>Backend: POST /api/.../filter?page&size&sort
+    Backend->>Banco: executa consulta filtrada e paginada
+    Banco-->>Backend: retorna página de resultados
+    Backend-->>Frontend: responde com página de DTOs
+    Frontend-->>Tabela: entrega Page<T>
+    Tabela->>Tabela: atualiza linhas, paginação e estado visual
+```
 
-    activate SpecBuilder
-    SpecBuilder->>SpecBuilder: Itera nos campos do FilterDTO.<br>Encontra @Filterable no campo 'nome'.
-    SpecBuilder->>SpecBuilder: Cria um Predicate JPA:<br> `criteriaBuilder.like(root.get("nome"), "%tech%")`
-    SpecBuilder->>Service: Retorna a Specification JPA construída.
-    deactivate SpecBuilder
+Leitura pedagógica:
 
-    Service->>Repository: Chama .findAll(specification, pageable)
+1. **A tabela captura a intenção do usuário**: página, ordenação e filtros viram estado de consulta.
+2. **O frontend envia o DTO de filtro para o endpoint canônico**: corpo JSON para filtro, query params para paginação e sort.
+3. **O backend aplica o filtro no conjunto remoto**: não é a UI que filtra localmente em modo remoto.
+4. **O resultado volta já paginado**: a tabela apenas renderiza a página retornada pela API.
 
-    activate Repository
-    Repository->>Repository: Spring Data JPA executa a<br>query SQL com WHERE, LIMIT, OFFSET, ORDER BY.
-    Repository-->>Service: Retorna um objeto Page<Entity> do BD.
-    deactivate Repository
+### Versão Detalhada e Fiel ao Runtime Atual
 
-    Service-->>Controller: Retorna o Page<Entity>
-    deactivate Service
+Esta versão documenta o fluxo real do `praxis-table`, do `praxis-filter`, do `GenericCrudService` e do `praxis-metadata-starter`.
 
-    activate Controller
-    Controller->>Controller: Mapeia Page<Entity> para Page<DTO><br>e encapsula em RestApiResponse.
-    Controller-->>CrudService: Resposta HTTP 200 com<br>JSON do RestApiResponse.
-    deactivate Controller
+```mermaid
+sequenceDiagram
+    participant Host as Host / bindings
+    participant Tabela as PraxisTable
+    participant Filtro as PraxisFilter
+    participant Crud as GenericCrudService
+    participant Controller as AbstractCrudController
+    participant Service as BaseCrudService
+    participant Builder as GenericSpecificationsBuilder
+    participant Repo as JpaSpecificationExecutor
+
+    Host->>Tabela: fornece resourcePath
+    Tabela->>Crud: configure(resourcePath)
+    alt sem colunas prontas
+        Tabela->>Crud: getSchema()
+        Crud-->>Tabela: schema normalizado
+    else com colunas prontas
+        Tabela->>Tabela: verifyServerSchemaVersion()
+    end
 
-    activate CrudService
-    CrudService-->>UI: Retorna Observable<Page<DTO>>
-    deactivate CrudService
+    alt advancedFilters habilitado
+        Tabela->>Filtro: monta praxis-filter
+        Filtro->>Crud: getFilteredSchema(...) ou getSchema()
+        Crud-->>Filtro: metadata de filtro
+    end
 
-    UI->>UI: Atualiza a tabela com os novos dados e o paginador.
+    alt paginação
+        Tabela->>Tabela: onPageChange(pageIndex, pageSize)
+    else ordenação
+        Tabela->>Tabela: onSortChange(active, direction)
+        Tabela->>Tabela: reseta pageIndex = 0
+    else filtro avançado
+        Filtro-->>Tabela: submit/change/clear
+        Tabela->>Tabela: onAdvancedFilterSubmit(criteria)
+    end
 
+    Tabela->>Tabela: fetchData()
+    Tabela->>Tabela: monta PageableRequest com pageIndex, pageSize e sortField efetivo
+    Tabela->>Crud: filter(filterCriteria, pageable)
+
+    Crud->>Crud: normalizeRangeCriteria(...)
+    Crud->>Controller: POST /filter?page&size&sort
+    Note over Crud,Controller: body = filterCriteria JSON
+
+    Controller->>Controller: lê page,size,sort de query params
+    Controller->>Controller: PageableBuilder.from(page,size,sort,...)
+    Controller->>Service: filterMappedWithIncludeIds(filterDTO, pageable, includeIds, toDto)
+
+    Service->>Builder: buildSpecification(filterDTO, pageable)
+    Builder->>Builder: inspeciona campos @Filterable do DTO
+    Builder-->>Service: Specification pronta
+    Service->>Repo: findAll(specification, pageable)
+    Repo-->>Service: Page<Entity>
+    Service-->>Controller: Page<DTO>
+
+    Controller->>Controller: mapeia para EntityModel<DTO> e monta RestApiResponse.success(...)
+    Controller-->>Crud: HTTP 200
+    Crud->>Crud: unwrapPageResponse(...)
+    Crud-->>Tabela: Page<T>
+    Tabela->>Tabela: atualiza dataSubject, totalElements e paginator
 ```
 
-### Pontos-Chave do Fluxo:
+### Pontos-Chave do Fluxo Real
 
-1.  **UI (`@praxisui/table`)**: Captura eventos do usuário e os traduz em objetos `filterCriteria` e `pageable`.
-2.  **Serviço Frontend (`@praxisui/core`)**: O `GenericCrudService` serializa o `pageable` como parâmetros de URL e o `filterCriteria` como corpo de uma requisição POST.
-3.  **Controller Backend**: O `AbstractCrudController` recebe a requisição. O Spring Boot automaticamente popula o DTO de filtro com o corpo da requisição e o objeto `Pageable` com os parâmetros da URL.
-4.  **Serviço Backend (`praxis-metadata-core`)**: O `GenericSpecificationsBuilder` inspeciona as anotações `@Filterable` no DTO de filtro para construir uma `Specification` JPA dinâmica.
-5.  **Repositório (Spring Data JPA)**: O `JpaSpecificationExecutor` (geralmente estendido pelo seu repositório) usa a `Specification` e o `Pageable` para gerar e executar a consulta SQL final, otimizada para o banco de dados.
+1. **`resourcePath` não dispara só fetch**: em modo remoto, a tabela primeiro configura o `GenericCrudService` e pode carregar schema antes da primeira busca.
+2. **O filtro avançado vive em `praxis-filter`**: os eventos reais são `submit`, `change` e `clear`, que a tabela recebe como `onAdvancedFilterSubmit`, `onAdvancedFilterChange` e `onAdvancedFilterClear`.
+3. **O controller não recebe `Pageable` pronto do Spring nesse endpoint**: ele reconstrói o `Pageable` a partir de `page`, `size` e `sort`.
+4. **O backend do starter responde com `RestApiResponse<Page<...>>`**: o `GenericCrudService` faz `unwrapPageResponse(...)` para entregar `Page<T>` ao runtime da tabela.
+5. **A coluna ordenada pode mapear para `sortField`**: o `active` da UI não é necessariamente o campo final enviado ao backend.
 
 ## 🎨 Edição Visual da Tabela: O Poder do Low-Code