@praxisui/table 8.0.0-beta.0 → 8.0.0-beta.100

package/README.md

@@ -1,4 +1,4 @@
----
+---
 title: "Table"
 slug: "table-overview"
 description: "Visao geral do @praxisui/table com TableConfig unificada, filtros, renderers, performance e integracao enterprise."
@@ -163,6 +163,27 @@ Filtro runtime:
 - The default is `false`; hosts opt in when they want settings, authoring affordances and schema-drift UX.
 - Customization mode does not change the table data mode. It only gates configuration/editorial surfaces.
 
+## Praxis Semantic Assistant
+
+- The table assistant is part of the global Praxis semantic copilot experience, not a standalone table patch bot.
+- In customization mode, opening the assistant registers a `PraxisAssistantContextSnapshot` through `PraxisAssistantSessionRegistryService`.
+- The table session identity follows `table:{routeKey}:{componentInstanceId || tableId}` so multiple tables on the same page can preserve separate assistant sessions.
+- Minimizing the table shell keeps the governed session in `PraxisAssistantSessionRegistryService` with `presence: 'origin-anchor'`; the visual affordance returns to the table assistant trigger, which changes to the minimized state and reopens the preserved session. The App Shell does not interpret or execute table semantics.
+- The table snapshot stores only safe context: table identity, target, context chips, manifest reference, resource path, schema field names, data/runtime digests, capability refs and governance hints.
+- When rows are selected, the assistant context includes a governed `table-row-selection` digest with selected count, id field, selected ids and a small sanitized row sample. The runtime never uses selected row text to decide primary intent; the LLM/backend receives the digest only as grounding after the assistant turn has the table component scope.
+- Prompts that indicate shared business decisions, such as rules, policies, compliance, LGPD, approval, eligibility or access control, must be routed to governed `domain-rules` handoff instead of local table config patches.
+
+### Consultative answers vs governed edits
+
+`@praxisui/table` declares two component-level response modes through its authoring context:
+
+- `consult/answer`: use when the user asks a factual or how-to question about the current table. Examples: "qual endpoint esta servindo esta tabela?", "quais campos existem nesta tabela?", "quais recursos de estilização a tabela suporta?" and "como criar uma coluna que soma duas colunas?".
+- `edit/componentEditPlan`: use when the user asks to apply or materialize a change. Examples: "mostre ativo como badge verde", "crie uma coluna bonus com 10% do salario", "deixe o avatar vermelho quando salario for maior que 30000" and "anime as linhas com salario acima de 30000".
+
+Consultative answers are selected by the backend/LLM from the component `responseModes` contract and return `type: "info"`. The table runtime must not classify user intent through local keywords; it only sends grounded context such as `resourcePath`, schema fields and the table authoring manifest, then renders the orchestrator response without an apply action. For how-to or documentation-style turns, the orchestrator should explain the governed operation shape and give a safe example instead of collecting missing edit parameters.
+
+Governed edits must be selected by the same backend/LLM response-mode decision and produce a validated `componentEditPlan`; the table compiles that plan into a patch and only then exposes the review/apply step.
+
 ## Migration Note
 
 - This release treats `enableCustomization=false` as the canonical default.
@@ -187,6 +208,8 @@ Para garantir que a tabela, filtros e editores reflitam o tema do app host:
 Observação: tokens `--md-sys-*` e `--mdc-theme-*` continuam aceitos quando presentes.
 Nota: a classe de tema é decisão do host (`.dark-theme` ou `.theme-dark`/`.theme-light`); mantenha tokens e componentes no mesmo escopo.
 
+Surface stacking is owned by `@praxisui/table`: when toolbar, grid and paginator are rendered as one table surface, the runtime flattens the internal join corners and keeps only the outer corners rounded. Host apps should theme the table through Material/Praxis tokens instead of targeting internal descendants such as `.mat-mdc-table`, `.mat-mdc-paginator` or `.praxis-toolbar` to repair border radius joins.
+
 ## ✨ Características Principais
 
 ### 🏗️ Arquitetura Unificada
@@ -256,6 +279,82 @@ O novo editor é "column-first" e usa uma tipagem compartilhada com o Editor d
 - Preview: execute “Testar” para ver quantas linhas seriam afetadas pelas regras ativas.
 - Import/Export: exporta JSON sem o campo `enabled`; importa com validação estrutural de JSON Logic e sanitização de estilos (allowlist).
 
+#### Estados de linha vs estilos de célula
+
+Use `rowConditionalStyles` quando a condição descreve o estado semântico da linha inteira, como prioridade, SLA vencido, item sem responsável, bloqueio ou estagnação. Para temas e faixas visuais, prefira `cssClass` em `rowConditionalStyles` e resolva a aparência no CSS do host. Isso preserva o ownership de tema do host e evita que gradientes ou backgrounds reiniciem em cada célula.
+
+Use `columns[].conditionalStyles` quando o destaque pertence a uma coluna específica, como texto negativo em vermelho, status em badge, valor monetário fora da faixa ou ícone contextual de uma célula.
+
+Padrão recomendado:
+
+```ts
+rowConditionalStyles: [
+  {
+    condition: { contains: [{ var: 'prioridadeNome' }, 'Alta'] },
+    cssClass: 'app-row--priority-high',
+    description: 'Prioridade alta recebe âncora visual de linha.',
+  },
+]
+```
+
+O editor especializado tambem persiste `effects: RuleEffectDefinition[]` em
+`rowConditionalStyles` e `columns[].conditionalStyles`. O runtime consome esses
+efeitos diretamente e ainda preserva `cssClass`/`style` como fallback de
+compatibilidade, mantendo o ciclo abrir -> aplicar/salvar -> reabrir sem exigir
+que consumidores recompilem manualmente os efeitos visuais.
+
+Para renderizacao condicional, `columns[].conditionalRenderers` tambem aceita
+`effects: RuleEffectDefinition[]` como fonte canonica para renderer, tooltip e
+animacao. `rowConditionalRenderers` fica tipado no contrato publico para tooltip
+e animacao de linha, preservando os campos planos `tooltip`/`animation` como
+fallback.
+
+Animações condicionais devem ser authoradas como decisão semântica, não como CSS
+manual em `style.animation`. Para animar a linha inteira, use
+`rowConditionalRenderers[].animation`; para animar somente uma célula/coluna, use
+`columns[].conditionalRenderers[].animation`. Prefira presets semânticos
+(`info-soft`, `success-confirm`, `warning-attention`, `critical-alert`,
+`audit-review`, `sync-pending` ou aliases como `pulse-soft`, `sla-breach`,
+`risk-critical`) antes de `type` bruto. Exemplo:
+
+```ts
+rowConditionalRenderers: [
+  {
+    id: 'salario-alto-pulse',
+    condition: { '>': [{ var: 'salario' }, 30000] },
+    animation: { preset: 'pulse-soft', trigger: 'onAppear', intensity: 'subtle', repeat: 'once' },
+    enabled: true,
+  },
+]
+```
+
+`appearance.animations.enabled = false` desativa animações; os flags
+`appearance.animations.specific.row` e `appearance.animations.specific.cell`
+desativam seletivamente animações condicionais de linha e célula.
+
+Colunas calculadas usam `columns[].computed.expression` como AST JSON Logic
+canonico. Regras, estilos e renderers condicionais podem referenciar esses
+valores via `computed.<field>`. Quando uma coluna calculada depende de outra
+coluna calculada, o runtime resolve a ordem de avaliacao por dependencias
+declaradas ou referencias `var: "computed.<field>"`, evitando que o resultado
+dependa da ordem fisica de `columns[]`.
+
+```scss
+.app-table .mat-mdc-row.app-row--priority-high {
+  background: linear-gradient(
+    90deg,
+    color-mix(in srgb, var(--md-sys-color-error-container) 42%, transparent),
+    transparent
+  );
+}
+
+.app-table .mat-mdc-row.app-row--priority-high .mat-mdc-cell {
+  background: transparent;
+}
+```
+
+Evite aplicar gradientes de estado de linha diretamente em `.mat-mdc-cell`. Como cada célula tem largura, sticky behavior e renderer próprios, o gradiente pode parecer quebrado por coluna, especialmente em tema dark.
+
 Exemplos de JSON Logic:
 
 ```json
@@ -428,14 +527,40 @@ Um botão de engrenagem será exibido no canto superior direito. Ao clicar n
 
 As alterações podem ser aplicadas temporariamente com **Aplicar** ou salvas de forma persistente com **Salvar & Fechar**.
 
+### Assistente de IA da Tabela
+
+Quando `enableCustomization` esta ativo, a tabela expoe o assistente de IA pelo shell canonico de `@praxisui/ai`.
+O chrome conversacional, `sessionId`, `clientTurnId`, respostas rapidas e ciclo de revisao/aplicacao sao orquestrados
+por `PraxisAssistantTurnOrchestratorService`; a semantica especifica da tabela continua em `TableAiAdapter` e no
+`TableAgenticAuthoringTurnFlow`.
+
+## Agentic Authoring & Manifest
+
+Para acoes globais de `toolbar`, `row` e `bulk`, o authoring agentic aceita somente `GlobalActionRef` governado:
+`actionId`, `payload`, `payloadExpr` e `meta`. O schema bloqueia propriedades arbitrarias e mantem `payloadExpr`
+como escape avancado explicito, nao como objeto livre. Configuracoes novas devem persistir a acao em
+`effects[].kind = "global-action"` com `effects[].globalAction`; `globalAction` plano permanece apenas como fallback
+de compatibilidade para documentos existentes.
+
+O `@praxisui/table` declara authoring agentic através de um `ComponentAuthoringManifest` canônico. O manifesto é a fonte versionada para descoberta de alvos, operações e validações de configuração da tabela.
+
+- **Component ID:** `praxis-table`
+- **Config Schema:** `TableConfig`
+- **Alvos Editáveis:** `column`, `computedColumn`, `renderer`, `conditionalRenderer`, `rowAction`, `toolbarAction`, `toolbar`, `filter`, `grouping`, `selection`, `export`, `appearance`, `expansion`, `rule`, `meta`, `bulkAction`, `contextAction`, `pagination`, `sorting`, `interaction`, `loading`, `emptyState`, `resizing`, `dragging`, `editing`, `messages`, `localization`, `performance`, `data`, `accessibility`.
+- **Famílias de Operações:** Operações com target resolvers próprios por operação, alinhadas ao contrato canônico de configuração da tabela e aos paths publicados pelo pacote.
+- **Validação:** Validadores determinísticos cobrem unicidade, integridade de caminhos, suporte a renderizadores, presets de formatação, segurança de estilos, segurança de resource binding somente em `expansion.detailSource.configure`, apresentação do detalhe expansível em `expansion.detailPresentation.configure`, e preservação de round-trip do editor.
+
+O manifesto (v2.0.0) é exportado como `PRAXIS_TABLE_AUTHORING_MANIFEST` e projetado no `ai_registry` como contrato canônico de authoring. Essa projeção não deve ser tratada como aprovação semântica automática: cada operação precisa manter evidência testada de target resolver, paths canônicos, efeitos coerentes e validators pertinentes ao que a operação realmente edita. O gate `validate:authoring-contracts` deve rejeitar cobertura nominal, como validators globais sem uso ou validators ligados a operações não relacionadas.
+
 ## 🚀 Instalação
 
 ```bash
-npm install @praxisui/core @praxisui/table
+npm install @praxisui/ai @praxisui/core @praxisui/table
 ```
 
 Peers necessários (instale no app host):
 - `@angular/core` `^20.0.0`, `@angular/common` `^20.0.0`
+- `@praxisui/ai` `^8.0.0-beta.0`
 - `@praxisui/core` `^0.0.1`
 - `@praxisui/dynamic-fields` `^0.0.1` (quando usar editores/inputs dinâmicos)
 - `@praxisui/dynamic-form` `^0.0.1` (quando integrar com formulários dinâmicos)
@@ -460,7 +585,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 /schemas/filtered?path=/api/human-resources/departamentos/all&operation=get&schemaType=response` para obter o schema estrutural usado no bootstrap 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/filter&operation=post&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.
 
 ### Consulta Declarativa com `queryContext`
@@ -523,8 +648,8 @@ sequenceDiagram
 
     activate Crud_Service
     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
+    Crud_Service->>Crud_Service: Deriva path="/api/human-resources/departamentos/filter"<br>operation="post", schemaType="response"
+    Crud_Service->>Docs_Controller: GET /schemas/filtered?path=.../filter&operation=post&schemaType=response
     deactivate Crud_Service
 
     activate Docs_Controller
@@ -896,7 +1021,7 @@ onSchemaStatus(ev: { outdated: boolean; serverHash?: string; lastVerifiedAt?: st
 
 - O backend anota o schema com `x-ui.resource.idField` (e `idFieldValid`) via `/schemas/filtered`.
 - A tabela adota o campo identificador automaticamente com a seguinte precedência:
-  - `@Input() idField` → `crudContext.idField` → `config.meta.idField` (persistido) → `GenericCrudService.getResourceIdField()` (derivado do schema) → `'id'`.
+  - `config.meta.idField` (persistido) → contexto runtime/serviço derivado do schema → `'id'`.
   - Se `config.meta.idField` divergir do servidor, o componente alerta o usuário e mantém o valor do TableConfig até reconciliação.
 - A resolução ocorre no `loadSchema()` e também é considerada em tempo de execução para evitar corridas.
 - Para recursos cuja PK não é `id`, defina `getIdFieldName()` no controller backend correspondente.
@@ -914,12 +1039,12 @@ sequenceDiagram
 
   PT->>GS: configure(resourcePath)
   PT->>GS: getSchema()
-  GS->>GS: deriva path=/api/.../all + schemaType=response
-  GS->>Docs: GET /schemas/filtered?path=.../all&operation=get&schemaType=response
+  GS->>GS: deriva path=/api/.../filter + operation=post + schemaType=response
+  GS->>Docs: GET /schemas/filtered?path=.../filter&operation=post&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'
+  Note over PT: idField = config.meta.idField || runtime/schema || 'id'
   PT->>PT: construir colunas e renderizar
 ```
 
@@ -944,7 +1069,7 @@ sequenceDiagram
 ### Troubleshooting rápido (idField)
 
 - A ação delete falhou por ID ausente: verifique se o schema contém `x-ui.resource.idField` e se a coluna correspondente existe no dataset.
-- O ID está em outra propriedade: defina `@Input() idField` ou `crudContext.idField` temporariamente; ajuste o backend com `getIdFieldName()` para persistir o comportamento.
+- O ID está em outra propriedade: defina `config.meta.idField` no TableConfig; ajuste o backend com `getIdFieldName()` para persistir o comportamento derivado do schema.
 - Cache 304 sem idField aplicado: confirme que o serviço recebeu o body pelo menos uma vez (200) e que `GenericCrudService.getResourceIdField()` retorna o valor esperado.
 
 ### Uso com Dados Locais (Client-Side)
@@ -1669,9 +1794,9 @@ Deteccao:
 - somente quando `FieldDefinition.controlType === 'avatar'`
 
 Renderer aplicado:
-- `renderer: { type: 'avatar', avatar: { srcField, initialsExpr, shape: 'circle', size: 28 } }`
+- `renderer: { type: 'avatar', avatar: { srcField, initialsField: 'nomeCompleto', shape: 'circle', size: 32 } }`
 - alinhamento central e largura compacta (~56px)
-- `initialsExpr` com fallback para `nomeCompleto|nome|fullName|name|title`
+- `initialsField` deriva as iniciais a partir de um campo textual bruto
 
 Avatar explicito:
 - `renderer: { type: 'avatar', avatar: { srcField, initialsExpr, initialsField, shape: 'circle', size: 28 } }`
@@ -1679,7 +1804,7 @@ Avatar explicito:
 - `initialsExpr` deve retornar as iniciais prontas; ele nao transforma automaticamente um campo bruto em iniciais
 - quando quiser derivar iniciais a partir de um campo textual, prefira `initialsField`
 - exemplo recomendado: `avatar: { srcField: 'photoUrl', initialsField: 'name' }`
-- exemplo de `initialsExpr` explicito: `avatar: { initialsExpr: \"= (row.name || '').trim().split(/\\s+/).slice(0,2).map(p => p[0] || '').join('').toUpperCase()\" }`
+- exemplo de `initialsExpr` explicito: `avatar: { initialsExpr: 'initials' }`
 
 Comportamento importante:
 - a autodeteccao ocorre apenas no bootstrap (nao sobrescreve configuracoes de colunas persistidas)
@@ -1689,8 +1814,11 @@ Comportamento importante:
 Ajustes comuns:
 - `renderer.avatar.shape`: `'square' | 'rounded' | 'circle'`
 - `renderer.avatar.size`: numero em px
+- `renderer.avatar.backgroundColor`: cor de fundo do circulo
+- `renderer.avatar.textColor`: cor das iniciais
 - `renderer.avatar.alt` / `altField`
 - use `conditionalRenderers` para variar renderer por linha
+- exemplo condicional: `condition: { ">": [{ "var": "salario" }, 30000] }` com `avatar: { initialsField: 'name', backgroundColor: '#D32F2F', textColor: '#FFFFFF' }`
 
 A11y, seguranca e performance:
 - `alt`/`altField` sao respeitados
@@ -1717,3 +1845,98 @@ Apache-2.0 — consulte `LICENSE` na raiz do workspace para detalhes.
 **Versão**: 2.0.0 (Unified Architecture)
 **Compatibilidade**: Angular 18+
 
+## Discovery contextual em ações por linha
+
+Use `actions.row.discovery.enabled=false` quando a tabela precisar operar em uma
+experiência corporativa estritamente curada pelo host. Nesse modo, o runtime
+mantém somente as ações declaradas em `actions.row.actions[]` e não adiciona
+ações descobertas dinamicamente por HATEOAS/capabilities.
+
+```ts
+actions: {
+  row: {
+    enabled: true,
+    display: 'buttons',
+    discovery: { enabled: false },
+    actions: [
+      { id: 'briefing', label: 'Briefing', action: 'inspect-surfaces' },
+      { id: 'capabilities', label: 'Capabilities', action: 'inspect-actions' },
+    ],
+  },
+}
+```
+
+O campo controla apenas a descoberta contextual de row actions. Ele não desativa
+`behavior.expansion.detail.source.mode="hypermedia"`; quando a expansão
+hypermedia estiver ativa, o detail ainda pode resolver `surfaces` e `actions`
+sob demanda ao expandir a linha. O default continua habilitado quando
+`actions.row.discovery.enabled` é omitido.
+
+## Row action para navegação interna
+
+Use `navigation.openRoute` quando a ação da linha precisar abrir uma rota
+interna levando o identificador do registro selecionado.
+
+```ts
+actions: {
+  row: {
+    enabled: true,
+    display: 'buttons',
+    discovery: { enabled: false },
+    actions: [
+      {
+        id: 'open-detail',
+        label: 'Abrir detalhe',
+        action: 'navigation.openRoute',
+        effects: [
+          {
+            kind: 'global-action',
+            globalAction: {
+              actionId: 'navigation.openRoute',
+              payload: {
+                path: '/clientes/detalhe',
+                query: {
+                  id: '${row.id}',
+                },
+              },
+            },
+          },
+        ],
+        globalAction: {
+          actionId: 'navigation.openRoute',
+          payload: {
+            path: '/clientes/detalhe',
+            query: {
+              id: '${row.id}',
+            },
+          },
+        },
+      },
+    ],
+  },
+}
+```
+
+O runtime da tabela resolve templates como `${row.id}` antes de executar a
+global action, o que permite reutilizar o mesmo contrato em `list` e `table`.
+Para configuracoes novas, `effects[].kind = 'global-action'` e o envelope
+canonico alinhado a `PraxisRuntimeGlobalActionEffect`; `globalAction` plano
+continua aceito como fallback de compatibilidade.
+O editor de acoes usa o mesmo adapter interno para toolbar, row e bulk actions:
+ao escolher novamente a mesma global action, ele preserva `payload` estruturado
+ou `payloadExpr` existente; ao trocar o `actionId`, ele descarta o payload antigo
+para evitar executar parametros de outra acao.
+
+As acoes por linha tambem usam Json Logic canonico para `visibleWhen` e
+`disabledWhen`. O editor de acoes preserva esses objetos no fluxo
+abrir -> aplicar/salvar -> reabrir, por exemplo:
+
+```ts
+{
+  id: 'edit-active',
+  label: 'Editar',
+  action: 'edit',
+  visibleWhen: { '===': [{ var: 'status' }, 'Ativo'] },
+  disabledWhen: { '===': [{ var: 'status' }, 'Bloqueado'] },
+}
+```

package/docs/DSL-Extensions-Guide.md

@@ -0,0 +1,23 @@
+# Guia Historico: Remocao da DSL Runtime
+
+O runtime DSL legado foi removido de `@praxisui/table`.
+
+Estado canonico atual:
+
+- JSON Logic e o unico contrato suportado para regras novas e para o editor de regras.
+- A tabela nao executa mais expressoes DSL em string no runtime.
+- Hosts que ainda possuam payloads DSL precisam migrar essas regras para JSON Logic antes de reutiliza-las.
+
+Nao existe mais:
+
+- registry publico de funcoes DSL
+- extensoes DSL publicas de data/JSON
+- path oficial de validacao DSL no runtime da tabela
+
+Para o caminho suportado, use:
+
+- [json-logic-operators-and-helpers.md](./json-logic-operators-and-helpers.md)
+- [praxis-table.json-api.md](../src/lib/praxis-table.json-api.md)
+- [table-rules-editor.component.ts](../src/lib/rules-editor/table-rules-editor.component.ts)
+
+Este arquivo permanece apenas para redirecionar links antigos que ainda apontavam para "DSL extensions".

package/docs/adr/2026-03-dynamic-filter-cross-lib-coupling.md

@@ -0,0 +1,107 @@
+---
+title: "ADR - Dynamic Filter as Cross-Library Feature"
+slug: "adr-dynamic-filter-cross-lib-coupling-2026-03"
+description: "Decisao de arquitetura para tratar o filtro dinamico como feature transversal entre table, dynamic-fields e metadata-starter, com documentacao e contrato coordenados."
+doc_type: "adr"
+document_kind: "adr-record"
+category: "architecture"
+audience:
+  - "frontend"
+  - "backend"
+  - "architect"
+  - "platform-team"
+level: "advanced"
+status: "implemented"
+owner: "praxis-ui"
+tags:
+  - "dynamic-filter"
+  - "table"
+  - "dynamic-fields"
+  - "metadata-starter"
+  - "architecture"
+toc: true
+sidebar: true
+related_docs:
+  - "dynamic-filter-architecture-overview"
+  - "dynamic-filter-payload-contract"
+  - "dynamic-filter-range-filters-guide"
+  - "dynamic-filter-host-integration-guide"
+  - "dynamic-filter-troubleshooting-guide"
+last_updated: "2026-03-07"
+---
+
+# ADR: Dynamic Filter as Cross-Library Feature
+
+## Status
+
+`implemented`
+
+## Context
+
+Historicamente, o filtro dinâmico podia ser lido de forma fragmentada:
+
+- `table` como componente “dono” da experiência;
+- `dynamic-fields` como catálogo de controles;
+- `metadata-starter` como detalhe backend separado.
+
+Esse modelo é insuficiente para documentação e governança porque os problemas reais atravessam as três camadas.
+
+Exemplos concretos:
+
+- o `PraxisFilter` decide variantes inline e persistência local;
+- os campos `filter-*-inline` definem UX, acessibilidade e envelopes de interação;
+- o backend normaliza ranges e rejeita payload inválido com `FILTER_PAYLOAD_INVALID`.
+
+Se a documentação tratar essas partes como silos, o resultado é incompleto.
+
+## Decision
+
+Adotar oficialmente o filtro dinâmico como feature transversal do ecossistema Praxis.
+
+Isso implica:
+
+- a entrada principal de uso público continua em `@praxisui/table`;
+- contratos visuais e metadata dos inline continuam canônicos em `@praxisui/dynamic-fields`;
+- contrato HTTP, normalização e semântica operacional do payload devem citar explicitamente `praxis-metadata-starter`;
+- a documentação da feature deve ser pensada como trilha, e não como README solto por biblioteca.
+
+## Consequences
+
+### Positivas
+
+- documentação mais didática e completa;
+- troubleshooting mais rápido;
+- menos divergência entre frontend e backend;
+- maior clareza sobre onde documentar payload, range e settings.
+
+### Custos
+
+- manutenção documental coordenada entre bibliotecas;
+- necessidade de `related_docs` e slugs estáveis;
+- revisão mais cuidadosa quando a feature evoluir.
+
+## Non-goals
+
+- fundir fisicamente as bibliotecas;
+- mover os componentes inline para dentro de `table`;
+- duplicar documentação canônica entre libs.
+
+## Implementation Outline
+
+1. Manter `table` como ponto de entrada da jornada.
+2. Referenciar `dynamic-fields` como fonte de verdade para catálogo inline e metadata.
+3. Referenciar `metadata-starter` como fonte de verdade para payload backend e normalização.
+4. Publicar a trilha documental completa sob `projects/praxis-table/docs`.
+
+## Acceptance Criteria
+
+- trilha documental cobrindo arquitetura, integração host, payload, range, catálogo inline e troubleshooting;
+- referências explícitas ao `metadata-starter` nos documentos de contrato;
+- navegação consistente entre docs relacionados.
+
+## Source References
+
+- `projects/praxis-table/src/lib/components/praxis-filter/praxis-filter.component.ts`
+- `projects/praxis-dynamic-fields/docs/dynamic-fields-inline-components-guide.md` (slug publicado: `dynamic-fields-inline-components-guide`)
+- `../praxis-metadata-starter/src/main/java/org/praxisplatform/uischema/filter/web/FilterRequestBodyAdvice.java`
+- `../praxis-metadata-starter/src/main/java/org/praxisplatform/uischema/filter/range/RangePayloadNormalizer.java`

package/docs/adr/2026-03-filter-drawer-adapter-light-entrypoint.md

@@ -0,0 +1,105 @@
+---
+title: "ADR - Lightweight Filter Drawer Adapter Entrypoint for @praxisui/table"
+slug: "adr-table-filter-drawer-adapter-light-entrypoint-2026-03"
+description: "Decisao de arquitetura para expor um sub-entrypoint leve de filter drawer adapter em @praxisui/table e reduzir impacto de bundle inicial em apps host."
+doc_type: "adr"
+document_kind: "adr-record"
+category: "architecture"
+audience:
+  - "frontend"
+  - "architect"
+  - "platform-team"
+level: "advanced"
+status: "implemented"
+owner: "praxis-ui"
+tags:
+  - "table"
+  - "filter"
+  - "drawer"
+  - "adapter"
+  - "bundle"
+  - "entrypoint"
+toc: true
+sidebar: true
+last_updated: "2026-03-06"
+---
+
+# ADR: Lightweight Filter Drawer Adapter Entrypoint for `@praxisui/table`
+
+## Status
+
+`implemented`
+
+## Context
+
+Hosts que registram `FILTER_DRAWER_ADAPTER` no bootstrap podem carregar partes desnecessarias do pacote no `initial bundle`.
+
+No estado atual:
+- O token `FILTER_DRAWER_ADAPTER` e o contrato leve publicado vivem em `projects/praxis-table/filter-drawer-adapter/src/filter-drawer-adapter.ts`.
+- O barrel raiz (`projects/praxis-table/src/public-api.ts`) exporta tabela, filtro, editores e recursos adicionais.
+
+Resultado observado no issue cross-lib:
+- inflacao relevante de bundle inicial com adapters ativos.
+
+## Decision
+
+Adotar sub-entrypoint leve para o contrato do adapter:
+
+- Novo path de consumo recomendado: `@praxisui/table/filter-drawer-adapter`
+- Exportar somente:
+  - `FILTER_DRAWER_ADAPTER`
+  - `FilterDrawerAdapter`
+  - contratos minimos relacionados ao adapter
+
+Compatibilidade:
+- manter um unico caminho publico para consumo host via sub-entrypoint leve.
+- atualizar docs/boilerplates para usar o subpath leve.
+
+## Non-goals
+
+- Alterar comportamento de `PraxisFilter` em runtime.
+- Redesenhar o contrato funcional do adapter.
+
+## Implementation Outline
+
+1. Criar entrypoint secundario focado em adapter/token.
+2. Publicar o subpath via secondary entrypoint do `ng-packagr`.
+3. Atualizar docs de integracao e boilerplates para usar subpath leve.
+4. Medir bundle no host de referencia antes/depois.
+
+## Acceptance Criteria
+
+- Subpath novo publicado e adotavel em host.
+- Documentacao atualizada com recomendacao canonica.
+- Reducao relevante do `initial bundle` com adapters ativos (meta orientadora: `-40%` sobre baseline atual).
+
+Estado atual dos criterios:
+- Publicacao do subpath: concluida.
+- Documentacao canonica: concluida.
+- Benchmark de bundle no host de referencia: pendente.
+
+## Implementation Status
+
+- Implementado em `2026-03-06`:
+  - secondary entrypoint `projects/praxis-table/filter-drawer-adapter`
+  - export removido do barrel raiz `projects/praxis-table/src/public-api.ts`
+  - docs/boilerplates atualizados para recomendar `@praxisui/table/filter-drawer-adapter`
+- Validacao concluida nesta workspace:
+  - build da lib e publicacao do subpath em `dist/praxis-table/filter-drawer-adapter`
+- Medicao de bundle host:
+  - pendente de benchmark reproduzivel do host de referencia nesta workspace
+
+## Risks and Mitigations
+
+- Risco: diferenca pequena de bundle em alguns perfis de build.
+  - Mitigacao: capturar metricas por perfil (dev/prod) e registrar resultado real.
+- Risco: divergencia entre token interno e token publicado no sub-entrypoint.
+  - Mitigacao: garantir singleton compartilhado e validar identidade em spec dedicada.
+- Risco: boilerplates permanecerem em path inconsistente.
+  - Mitigacao: checklist de migracao em docs/templates e PRs de ajuste.
+
+## Source References
+
+- `projects/praxis-table/filter-drawer-adapter/src/filter-drawer-adapter.ts`
+- `projects/praxis-table/src/public-api.ts`
+- `docs/issues/drawer-adapters-bundle-entrypoints.md` (historico cross-lib)

package/docs/adr/2026-03-table-editor-idfield-decision.md

@@ -0,0 +1,85 @@
+# ADR: Decisão Provisória Sobre `idField` no `TableAuthoringDocument`
+
+## Status
+
+Proposto
+
+## Contexto
+
+Durante o desenho do `tableEditorCapability`, surgiu uma ambiguidade estrutural sobre `idField`.
+
+No código atual de `praxis-table`, `idField` aparece em dois papéis:
+
+- como resolução operacional do host/runtime para identificar linhas;
+- como metadado persistido em `config.meta.idField` em alguns fluxos de apply/save.
+
+Isso cria ambiguidade arquitetural:
+
+- se `idField` for binding operacional, ele deve viver fora do `TableConfig` canônico;
+- se `idField` for semântica persistível do componente, ele deve viver no `TableConfig` e não em bindings paralelos.
+
+Enquanto essa decisão não for estabilizada, o contrato do documento de autoria permanece frágil.
+
+## Decisão
+
+Para o piloto de `praxis-table`, adotar temporariamente `idField` como parte de `bindings`, não como parte obrigatória de `config.meta`.
+
+Shape provisório:
+
+```ts
+interface TableBindings {
+  resourcePath?: string | null;
+  idField?: string;
+  horizontalScroll?: 'auto' | 'wrap' | 'none';
+}
+
+interface TableAuthoringDocument {
+  kind: 'praxis.table.editor';
+  version: 1;
+  config: TableConfig;
+  bindings?: TableBindings;
+}
+```
+
+## Regras decorrentes
+
+1. O documento persistível de autoria deve serializar `bindings.idField`, não depender de `config.meta.idField`.
+2. O parser de legado pode ler `config.meta.idField` e migrar para `bindings.idField`.
+3. `toCanonicalConfig()` não deve reescrever `config.meta.idField` por padrão.
+4. Se o runtime quiser persistir `meta.idField` por compatibilidade, isso deve ser decisão explícita do adapter/save flow, não efeito implícito da capability.
+5. A revisão futura deve decidir se:
+   - `idField` permanece binding de integração, ou
+   - `idField` sobe para semântica persistível do `TableConfig`.
+
+## Motivo da decisão
+
+Essa opção minimiza acoplamento prematuro com a semântica atual do runtime e evita consolidar como padrão algo que ainda parece misturar:
+
+- identidade persistível do componente
+- integração com dataset/servidor
+
+Também permite migrar o protocolo sem bloquear o piloto do `tableEditorCapability`.
+
+## Consequências
+
+### Positivas
+
+- simplifica a primeira iteração do documento canônico;
+- evita duplicação automática entre `bindings.idField` e `config.meta.idField`;
+- deixa explícito que a decisão definitiva ainda está em aberto.
+
+### Negativas
+
+- o piloto conviverá temporariamente com duas representações possíveis de `idField`;
+- adapters de compatibilidade talvez precisem continuar lendo/escrevendo `meta.idField` por um tempo;
+- a generalização cross-component ainda não fica fechada.
+
+## Critério para revisão futura
+
+Antes de promover o modelo como padrão do ecossistema, revisar esta ADR e decidir de forma definitiva:
+
+1. `idField` é binding operacional do host?
+2. `idField` é semântica persistível do componente?
+3. existe necessidade real de ambos?
+
+Sem essa decisão, o contrato do documento continua semanticamente ambíguo.