@praxisui/table 9.0.5-rc.2 → 9.0.5-rc.21

package/docs/dynamic-filter-architecture-overview.md

@@ -29,7 +29,7 @@ reading_time: 16
 estimated_setup_time: 35
 version: "1.0"
 related_docs:
-  - "table-overview"
+  - "praxis-table-json-api"
   - "dynamic-filter-payload-contract"
   - "dynamic-filter-range-filters-guide"
   - "dynamic-fields-inline-components-guide"
@@ -91,6 +91,21 @@ No Praxis, o filtro dinâmico é uma pipeline de seis etapas:
 - persistência local do estado do DTO e das preferências de exibição com chaves `filter-dto:<key>` e `filter-config:<key>`;
 - heurísticas que convertem `controlType` genérico para inline canônico quando a feature pede experiência compacta.
 
+Na toolbar da tabela, essa responsabilidade é materializada em quatro regiões
+semânticas governadas pela largura do próprio container:
+
+- `identity`: identidade e contexto da coleção;
+- `scope`: quick filters mutuamente exclusivos e removíveis;
+- `query`: campos de filtro e atalhos projetados;
+- `commands`: ações de negócio, utilidades e authoring.
+
+Dentro de `PraxisFilter`, `query` se divide em `criteria` e
+`query-auxiliary`. A primeira região contém os campos selecionados e sempre
+visíveis. A segunda mantém tags/atalhos e comandos de gerenciamento como um
+cluster único. O reflow move regiões completas e preserva ordem visual, ordem de
+teclado e paridade de comandos; hosts não devem reconstruir essa composição com
+breakpoints locais.
+
 Esse acoplamento existe em `projects/praxis-table/src/lib/components/praxis-filter/praxis-filter.component.ts` e `projects/praxis-table/src/lib/services/filter-config.service.ts`.
 
 ### 2. `praxis-dynamic-fields`: superfície dos controles
@@ -153,6 +168,12 @@ O runtime persiste:
 
 Isso permite restaurar seleção de campos, preferências visuais e estado operacional do filtro.
 
+Tags fornecidas por `tags` são presets governados e não pertencem ao conjunto
+editável de atalhos salvos pelo usuário. O runtime permite aplicá-las e removê-las,
+mas não renomeá-las ou excluí-las. O `patch` de cada tag deve usar os nomes e
+shapes canônicos do `FilterDTO`; um campo desconhecido não ganha semântica apenas
+por estar presente no JSON do host.
+
 ### Etapa 4. Emissão de payload
 
 No modo avançado, `onAdvancedChange(event)` trabalha sobre `event.formData`. Os eventos `change` e `submit` são o contrato que o host normalmente observa para disparar integração com a API.

package/docs/dynamic-filter-host-integration-guide.md

@@ -28,7 +28,7 @@ reading_time: 18
 estimated_setup_time: 45
 version: "1.0"
 related_docs:
-  - "table-overview"
+  - "praxis-table-json-api"
   - "dynamic-filter-architecture-overview"
   - "dynamic-filter-payload-contract"
   - "dynamic-filter-editor-settings-guide"
@@ -125,6 +125,44 @@ e emite o novo payload para evitar filtro invisível. Use `alwaysVisibleFields`
 apenas para campos realmente fixos, porque eles não entram nessa remoção rápida
 do usuário.
 
+#### Preservar a hierarquia da consulta na toolbar
+
+O host declara a semântica, mas não posiciona controles com CSS próprio. O
+`praxis-filter` organiza a consulta em duas regiões internas:
+
+- **critérios**: campos sempre visíveis e campos adicionados por
+  `selectedFieldIds`;
+- **auxiliar**: atalhos salvos/tags e comandos de gerenciamento, como adicionar
+  filtros, limpar critérios e abrir o formulário avançado.
+
+Em containers largos, as duas regiões podem compartilhar a mesma faixa. Quando
+o espaço diminui, a região auxiliar desce como um bloco completo; atalhos e
+comandos não devem se espalhar por linhas diferentes nem comprimir campos de
+data, intervalo ou lookup abaixo da largura utilizável. Em containers estreitos,
+os critérios passam para uma coluna e o cluster auxiliar pode quebrar
+internamente, preservando a ordem de leitura e de teclado.
+
+Essa adaptação usa a largura do container da tabela, não apenas a viewport. Por
+isso, o mesmo contrato continua válido dentro de páginas, cards, drawers e split
+panes. Não crie breakpoints no host nem projete atalhos dentro da região de
+campos: use os inputs e slots públicos, e deixe o runtime materializar a
+geometria. Valide pelo menos os estados sem valor, preenchido, foco, erro e
+disabled em tema claro/escuro, zoom de 200% e labels localizados longos.
+
+Atalhos declarados em `tags` devem usar exatamente as chaves e os shapes do DTO
+de filtro descoberto. Um atalho de faixa salarial, por exemplo, deve escrever o
+mesmo campo de intervalo materializado pelo controle inline; criar um alias
+apenas no host produz critério invisível. Tags predefinidas são somente leitura
+quanto a renomear e excluir, mas continuam acionáveis e removíveis pelo operador.
+O host deve observar `submit` quando atalhos precisam disparar consulta imediata;
+`change` permanece a cadência de edição dos campos.
+
+Controles projetados no slot `[toolbar]` recebem orçamento limitado e podem
+quebrar dentro do cluster de consulta. Eles devem aceitar redução de largura e
+não podem impor `min-width` maior que o slot. Se a operação precisar manter
+largura intrínseca rígida, materialize-a como ação governada/overflow em vez de
+forçar geometria local.
+
 #### Padronizar `materialDesign` dos campos de filtro
 
 O `praxis-filter` normaliza a metadata efetiva de filtros com uma politica