@praxisui/table 9.0.5-rc.13 → 9.0.5-rc.14

package/README.md

@@ -249,27 +249,32 @@ const config: TableConfig = {
 `PraxisTableToolbar` materializes the toolbar as semantic regions rather than one wrapping row:
 
 - **identity** — title, subtitle and table context;
-- **query** — quick filters, always-visible dynamic filters and projected query shortcuts;
+- **scope** — a small, mutually exclusive and removable set of governed quick filters;
+- **query** — always-visible dynamic filters and projected query shortcuts;
 - **commands** — collection/business actions, table utilities and authoring entrypoints.
 
 The runtime owns the responsive composition through container queries. This is important when a table
 is rendered inside a drawer, split pane or dashboard card: behavior follows the width actually available
-to the table, not only the browser viewport. At wide widths, identity and commands share the first band
-and query controls use a stable second band. At compact widths, the regions move as complete units and
+to the table, not only the browser viewport. At wide widths, identity and commands share the first band,
+while scope and query share a stable second band. At compact widths, the regions move as complete units and
 commands are consolidated under one localized `Mais ações` entrypoint without losing export, column or
-density controls.
+density controls. At narrow widths the first band preserves identity and commands before the scope and
+query bands, so keyboard focus follows the same reading order presented visually.
 
 Authoring guidance:
 
 - use `toolbar.filters.quickFilters` for a small governed scope switch, not as a substitute for every filter;
+  one quick filter can be active at a time, and activating the current item again restores the previous criteria;
 - use `advancedFilters.settings.alwaysVisibleFields` for frequent editable criteria;
 - keep one clear collection/business action primary; export, columns and density are utilities;
 - project custom shortcuts through the toolbar slots, but do not target internal layout classes from the host;
 - validate the component container at `1440`, `1024`, `768`, `480` and `320` px, including long localized labels, zoom and keyboard focus.
 
-Adding filters or actions never requires a host breakpoint. When the command set grows, the compact menu
-preserves capability parity and keyboard order while the query region remains independently scroll-free at
-the page level.
+Adding supported filters or actions never requires a host breakpoint. When the command set grows, the compact
+menu preserves capability parity and keyboard order. Projected query shortcuts are grouped by the runtime,
+receive a bounded width budget and wrap as one semantic cluster; projected controls must remain intrinsically
+shrinkable and must not declare a fixed minimum width larger than their slot. Hosts must not rely on internal
+selectors to position them. The query region remains independently scroll-free at the page level.
 
 The existing `toolbar.layout` fields are materialized by the same runtime: `alignment` aligns the identity
 and command regions, `padding` and `backgroundColor` project governed chrome, `height` defines the minimum

package/ai/component-registry.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": "1.0.0",
-  "generatedAt": "2026-08-13T17:03:40.689Z",
+  "generatedAt": "2026-08-13T20:07:32.063Z",
   "packageName": "@praxisui/table",
-  "packageVersion": "9.0.5-rc.13",
+  "packageVersion": "9.0.5-rc.14",
   "sourceRegistry": "praxis-component-registry-ingestion",
   "sourceRegistryVersion": "1.0.0",
   "componentCount": 3,
@@ -16036,6 +16036,7 @@
           "description": "Configuração de toolbar.filters.* e quickFilters.",
           "rules": [
             "quickFilters[].filter deve seguir a estrutura do filtro suportado.",
+            "quickFilters representa um pequeno seletor de escopo exclusivo e removível; use filtros avançados para critérios combináveis.",
             "enabled depende de behavior.filtering.enabled."
           ],
           "examples": [
@@ -30775,9 +30776,9 @@
         {
           "chunkIndex": 144,
           "chunkKind": "context_pack",
-          "content": "{\"componentId\":\"praxis-table\",\"chunkSection\":\"aiConcepts\",\"aiConcepts\":{\"behavior-expansion\":{\"id\":\"behavior-expansion\",\"title\":\"Expansion (Behavior)\",\"description\":\"Configuração de behavior.expansion.* para detail rows schema-driven.\",\"rules\":[\"detail é sempre schema-driven; varie source.mode (inline/resource/resourcePath), não detail.type.\",\"detail.schemaContract.kind/version deve ser informado para validação e migração.\",\"Em virtualização, prefira detail.height.mode=fixed com virtualization.policy=fixed-height-only.\",\"Use eventExposureDefault hashed/redacted por padrão em ambiente corporativo.\"],\"examples\":[\"{ behavior: { expansion: { enabled: true, state: { mode: \\\"controlled\\\" }, detail: { schemaContract: { kind: \\\"praxis.detail.schema\\\", version: \\\"1.0.0\\\" }, source: { mode: \\\"resource\\\", resource: { kind: \\\"ui-composition\\\", id: \\\"customer-detail-v2\\\", version: \\\"2.1.0\\\" } }, rendering: { strategy: \\\"registry\\\", registryId: \\\"praxis.detail.default\\\" } } } } }\"],\"antiPatterns\":[\"{ behavior: { expansion: { detail: { type: \\\"template\\\", templateId: \\\"legacy-id\\\" } } } }\"]},\"appearance\":{\"id\":\"appearance\",\"title\":\"Aparência e Layout\",\"description\":\"Densidade, bordas, cores, tipografia, espaçamento e responsividade.\",\"rules\":[\"appearance.density deve usar valores compact/comfortable/spacious.\",\"Cores devem usar tokens do tema ou hex válido.\",\"responsive.mobile.cardMode deve ser combinado com colunas prioritárias.\",\"Se animations.enabled for true, respeite reduceMotion.\",\"appearance.animations.specific.row e appearance.animations.specific.cell controlam animações condicionais por escopo.\"],\"examples\":[\"{ appearance: { density: \\\"compact\\\", borders: { showRowBorders: true } } }\",\"{ appearance: { typography: { fontSize: \\\"14px\\\" }, spacing: { cellPadding: \\\"8px 16px\\\" } } }\"],\"antiPatterns\":[\"{ appearance: { density: \\\"tiny\\\" } }\"]},\"appearance-details\":{\"id\":\"appearance-details\",\"title\":\"Detalhes de Aparência\",\"description\":\"Bordas, cores, tipografia, spacing, elevation e responsive autoAdjust.\",\"rules\":[\"borders.style deve ser solid/dashed/dotted quando aplicável.\",\"typography.headerFontWeight deve ser string numerica ou token.\",\"responsive.autoAdjust controla ajustes automáticos em telas menores.\"],\"examples\":[\"{ appearance: { borders: { showOuterBorder: true, style: \\\"solid\\\" }, colors: { alternateRowBackground: \\\"#f7f9fc\\\" } } }\",\"{ appearance: { responsive: { mobile: { cardMode: true, priorityColumns: [\\\"name\\\", \\\"status\\\"] } } } }\"],\"antiPatterns\":[\"{ appearance: { borders: { style: \\\"double\\\" } } }\"]},\"toolbar\":{\"id\":\"toolbar\",\"title\":\"Toolbar\",\"description\":\"Configurações gerais da toolbar.\",\"rules\":[\"toolbar.visible controla exibição global da barra.\",\"Use toolbar.layout.alignment para ajustar distribuição.\",\"toolbar.filters.enabled depende de filtering.enabled.\",\"settingsMenu.enabled expõe opções de densidade e colunas.\"],\"examples\":[\"{ toolbar: { visible: true, position: \\\"top\\\", title: \\\"Pedidos\\\" } }\"],\"antiPatterns\":[\"{ toolbar: { position: \\\"left\\\" } }\"]},\"toolbar-layout\":{\"id\":\"toolbar-layout\",\"title\":\"Layout da Toolbar\",\"description\":\"Configuração de toolbar.layout.*\",\"rules\":[\"alignment deve ser start/center/end/space-between.\",\"height e padding devem ser coerentes com o tema.\"],\"examples\":[\"{ toolbar: { layout: { alignment: \\\"space-between\\\", height: 56, showSeparator: true } } }\"],\"antiPatterns\":[\"{ toolbar: { layout: { alignment: \\\"between\\\" } } }\"]},\"toolbar-actions\":{\"id\":\"toolbar-actions\",\"title\":\"Ações da Toolbar\",\"description\":\"Definições de toolbar.actions[].\",\"rules\":[\"toolbar.actions[].id deve ser único.\",\"action deve ser string, não função JS.\",\"type deve ser button/icon/fab/menu.\",\"visibleWhen usa expressao condicional canonica em JSON Logic.\"],\"examples\":[\"{ toolbar: { actions: [{ id: \\\"add\\\", label: \\\"Adicionar\\\", type: \\\"button\\\", action: \\\"create\\\", position: \\\"end\\\" }] } }\",\"{ toolbar: { actions: [{ id: \\\"more\\\", label: \\\"Mais\\\", type: \\\"menu\\\", action: \\\"noop\\\", children: [{ id: \\\"export\\\", label: \\\"Exportar\\\", type: \\\"button\\\", action: \\\"export\\\" }] }] } }\"],\"antiPatterns\":[\"{ actions: [{ action: \\\"() => doSomething()\\\" }] }\"]},\"toolbar-filters\":{\"id\":\"toolbar-filters\",\"title\":\"Filtros da Toolbar\",\"description\":\"Configuração de toolbar.filters.* e quickFilters.\",\"rules\":[\"quickFilters[].filter deve seguir a estrutura do filtro suportado.\",\"enabled depende de behavior.filtering.enabled.\"],\"examples\":[\"{ toolbar: { filters: { enabled: true, quickFilters: [{ id: \\\"active\\\", label: \\\"Ativos\\\", filter: { status: \\\"active\\\" } }] } } }\"],\"antiPatterns\":[\"{ toolbar: { filters: { quickFilters: [{ filter: \\\"status=active\\\" }] } } }\"]},\"toolbar-settings\":{\"id\":\"toolbar-settings\",\"title\":\"Menu de Configuracoes\",\"description\":\"Configuração de toolbar.settingsMenu.*\",\"rules\":[\"settingsMenu.options[].type deve ser toggle/select/action.\",\"options deve listar valores validos quando type for select.\"],\"examples\":[\"{ toolbar: { settingsMenu: { enabled: true, options: [{ id: \\\"density\\\", label: \\\"Densidade\\\", type: \\\"select\\\", options: [\\\"compact\\\", \\\"comfortable\\\", \\\"spacious\\\"] }] } } }\"],\"antiPatterns\":[\"{ settingsMenu: { options: [{ type: \\\"dropdown\\\" }] } }\"]},\"row-actions\":{\"id\":\"row-actions\",\"title\":\"Acoes por Linha\",\"description\":\"Configuração de actions.row.*\",\"rules\":[\"enabled deve estar true para mostrar coluna de ações.\",\"display deve ser menu/buttons/icons.\",\"trigger deve ser hover/always/click.\",\"actions[].action deve ser string.\"],\"examples\":[\"{ actions: { row: { enabled: true, display: \\\"menu\\\", trigger: \\\"hover\\\", actions: [{ id: \\\"edit\\\", label: \\\"Editar\\\", action: \\\"edit\\\" }] } } }\"],\"antiPatterns\":[\"{ actions: { row: { display: \\\"dropdown\\\" } } }\"]},\"row-actions-advanced\":{\"id\":\"row-actions-advanced\",\"title\":\"Acoes por Linha Avancadas\",\"description\":\"Header, overflow, menu e comportamento avançado.\",\"rules\":[\"header.align deve ser start/center/end.\",\"behavior.maxInline deve ser numero ou objeto de breakpoints.\",\"menuIcon e menuButtonColor devem ser valores suportados.\",\"discovery.enabled=false mantem apenas as actions configuradas e bloqueia a descoberta contextual por HATEOAS/capabilities.\"],\"examples\":[\"{ actions: { row: { header: { label: \\\"Ações\\\", align: \\\"end\\\" }, maxVisibleActions: 3, behavior: { enabled: true, maxInline: 2 } } } }\",\"{ actions: { row: { enabled: true, display: \\\"buttons\\\", discovery: { enabled: false }, actions: [{ id: \\\"briefing\\\", label: \\\"Briefing\\\", action: \\\"inspect-surfaces\\\" }] } } }\"],\"antiPatterns\":[\"{ row: { header: { align: \\\"middle\\\" } } }\"]},\"bulk-actions\":{\"id\":\"bulk-actions\",\"title\":\"Acoes em Lote\",\"description\":\"Configuração de actions.bulk.*\",\"rules\":[\"bulk.enabled exige selection.enabled.\",\"floating.position deve ser bottom-right/bottom-left/top-right/top-left.\",\"hideWhenEmpty evita botão flutuante quando nada selecionado.\"],\"examples\":[\"{ actions: { bulk: { enabled: true, position: \\\"toolbar\\\", actions: [{ id: \\\"delete\\\", label: \\\"Excluir\\\", action: \\\"bulk-delete\\\", requiresConfirmation: true }], floating: { position: \\\"bottom-right\\\", hideWhenEmpty: true } } } }\"],\"antiPatterns\":[\"{ actions: { bulk: { enabled: true } } } sem selection.enabled\"]},\"context-actions\":{\"id\":\"context-actions\",\"title\":\"Menu de Contexto\",\"description\":\"Configuração de actions.context.*\",\"rules\":[\"trigger deve ser right-click/long-press/both.\",\"actions[].action deve ser string.\"],\"examples\":[\"{ actions: { context: { enabled: true, trigger: \\\"right-click\\\", actions: [{ id: \\\"copy\\\", label: \\\"Copiar\\\", action: \\\"copy\\\" }] } } }\"],\"antiPatterns\":[\"{ context: { trigger: \\\"click\\\" } }\"]}}}",
+          "content": "{\"componentId\":\"praxis-table\",\"chunkSection\":\"aiConcepts\",\"aiConcepts\":{\"behavior-expansion\":{\"id\":\"behavior-expansion\",\"title\":\"Expansion (Behavior)\",\"description\":\"Configuração de behavior.expansion.* para detail rows schema-driven.\",\"rules\":[\"detail é sempre schema-driven; varie source.mode (inline/resource/resourcePath), não detail.type.\",\"detail.schemaContract.kind/version deve ser informado para validação e migração.\",\"Em virtualização, prefira detail.height.mode=fixed com virtualization.policy=fixed-height-only.\",\"Use eventExposureDefault hashed/redacted por padrão em ambiente corporativo.\"],\"examples\":[\"{ behavior: { expansion: { enabled: true, state: { mode: \\\"controlled\\\" }, detail: { schemaContract: { kind: \\\"praxis.detail.schema\\\", version: \\\"1.0.0\\\" }, source: { mode: \\\"resource\\\", resource: { kind: \\\"ui-composition\\\", id: \\\"customer-detail-v2\\\", version: \\\"2.1.0\\\" } }, rendering: { strategy: \\\"registry\\\", registryId: \\\"praxis.detail.default\\\" } } } } }\"],\"antiPatterns\":[\"{ behavior: { expansion: { detail: { type: \\\"template\\\", templateId: \\\"legacy-id\\\" } } } }\"]},\"appearance\":{\"id\":\"appearance\",\"title\":\"Aparência e Layout\",\"description\":\"Densidade, bordas, cores, tipografia, espaçamento e responsividade.\",\"rules\":[\"appearance.density deve usar valores compact/comfortable/spacious.\",\"Cores devem usar tokens do tema ou hex válido.\",\"responsive.mobile.cardMode deve ser combinado com colunas prioritárias.\",\"Se animations.enabled for true, respeite reduceMotion.\",\"appearance.animations.specific.row e appearance.animations.specific.cell controlam animações condicionais por escopo.\"],\"examples\":[\"{ appearance: { density: \\\"compact\\\", borders: { showRowBorders: true } } }\",\"{ appearance: { typography: { fontSize: \\\"14px\\\" }, spacing: { cellPadding: \\\"8px 16px\\\" } } }\"],\"antiPatterns\":[\"{ appearance: { density: \\\"tiny\\\" } }\"]},\"appearance-details\":{\"id\":\"appearance-details\",\"title\":\"Detalhes de Aparência\",\"description\":\"Bordas, cores, tipografia, spacing, elevation e responsive autoAdjust.\",\"rules\":[\"borders.style deve ser solid/dashed/dotted quando aplicável.\",\"typography.headerFontWeight deve ser string numerica ou token.\",\"responsive.autoAdjust controla ajustes automáticos em telas menores.\"],\"examples\":[\"{ appearance: { borders: { showOuterBorder: true, style: \\\"solid\\\" }, colors: { alternateRowBackground: \\\"#f7f9fc\\\" } } }\",\"{ appearance: { responsive: { mobile: { cardMode: true, priorityColumns: [\\\"name\\\", \\\"status\\\"] } } } }\"],\"antiPatterns\":[\"{ appearance: { borders: { style: \\\"double\\\" } } }\"]},\"toolbar\":{\"id\":\"toolbar\",\"title\":\"Toolbar\",\"description\":\"Configurações gerais da toolbar.\",\"rules\":[\"toolbar.visible controla exibição global da barra.\",\"Use toolbar.layout.alignment para ajustar distribuição.\",\"toolbar.filters.enabled depende de filtering.enabled.\",\"settingsMenu.enabled expõe opções de densidade e colunas.\"],\"examples\":[\"{ toolbar: { visible: true, position: \\\"top\\\", title: \\\"Pedidos\\\" } }\"],\"antiPatterns\":[\"{ toolbar: { position: \\\"left\\\" } }\"]},\"toolbar-layout\":{\"id\":\"toolbar-layout\",\"title\":\"Layout da Toolbar\",\"description\":\"Configuração de toolbar.layout.*\",\"rules\":[\"alignment deve ser start/center/end/space-between.\",\"height e padding devem ser coerentes com o tema.\"],\"examples\":[\"{ toolbar: { layout: { alignment: \\\"space-between\\\", height: 56, showSeparator: true } } }\"],\"antiPatterns\":[\"{ toolbar: { layout: { alignment: \\\"between\\\" } } }\"]},\"toolbar-actions\":{\"id\":\"toolbar-actions\",\"title\":\"Ações da Toolbar\",\"description\":\"Definições de toolbar.actions[].\",\"rules\":[\"toolbar.actions[].id deve ser único.\",\"action deve ser string, não função JS.\",\"type deve ser button/icon/fab/menu.\",\"visibleWhen usa expressao condicional canonica em JSON Logic.\"],\"examples\":[\"{ toolbar: { actions: [{ id: \\\"add\\\", label: \\\"Adicionar\\\", type: \\\"button\\\", action: \\\"create\\\", position: \\\"end\\\" }] } }\",\"{ toolbar: { actions: [{ id: \\\"more\\\", label: \\\"Mais\\\", type: \\\"menu\\\", action: \\\"noop\\\", children: [{ id: \\\"export\\\", label: \\\"Exportar\\\", type: \\\"button\\\", action: \\\"export\\\" }] }] } }\"],\"antiPatterns\":[\"{ actions: [{ action: \\\"() => doSomething()\\\" }] }\"]},\"toolbar-filters\":{\"id\":\"toolbar-filters\",\"title\":\"Filtros da Toolbar\",\"description\":\"Configuração de toolbar.filters.* e quickFilters.\",\"rules\":[\"quickFilters[].filter deve seguir a estrutura do filtro suportado.\",\"quickFilters representa um pequeno seletor de escopo exclusivo e removível; use filtros avançados para critérios combináveis.\",\"enabled depende de behavior.filtering.enabled.\"],\"examples\":[\"{ toolbar: { filters: { enabled: true, quickFilters: [{ id: \\\"active\\\", label: \\\"Ativos\\\", filter: { status: \\\"active\\\" } }] } } }\"],\"antiPatterns\":[\"{ toolbar: { filters: { quickFilters: [{ filter: \\\"status=active\\\" }] } } }\"]},\"toolbar-settings\":{\"id\":\"toolbar-settings\",\"title\":\"Menu de Configuracoes\",\"description\":\"Configuração de toolbar.settingsMenu.*\",\"rules\":[\"settingsMenu.options[].type deve ser toggle/select/action.\",\"options deve listar valores validos quando type for select.\"],\"examples\":[\"{ toolbar: { settingsMenu: { enabled: true, options: [{ id: \\\"density\\\", label: \\\"Densidade\\\", type: \\\"select\\\", options: [\\\"compact\\\", \\\"comfortable\\\", \\\"spacious\\\"] }] } } }\"],\"antiPatterns\":[\"{ settingsMenu: { options: [{ type: \\\"dropdown\\\" }] } }\"]},\"row-actions\":{\"id\":\"row-actions\",\"title\":\"Acoes por Linha\",\"description\":\"Configuração de actions.row.*\",\"rules\":[\"enabled deve estar true para mostrar coluna de ações.\",\"display deve ser menu/buttons/icons.\",\"trigger deve ser hover/always/click.\",\"actions[].action deve ser string.\"],\"examples\":[\"{ actions: { row: { enabled: true, display: \\\"menu\\\", trigger: \\\"hover\\\", actions: [{ id: \\\"edit\\\", label: \\\"Editar\\\", action: \\\"edit\\\" }] } } }\"],\"antiPatterns\":[\"{ actions: { row: { display: \\\"dropdown\\\" } } }\"]},\"row-actions-advanced\":{\"id\":\"row-actions-advanced\",\"title\":\"Acoes por Linha Avancadas\",\"description\":\"Header, overflow, menu e comportamento avançado.\",\"rules\":[\"header.align deve ser start/center/end.\",\"behavior.maxInline deve ser numero ou objeto de breakpoints.\",\"menuIcon e menuButtonColor devem ser valores suportados.\",\"discovery.enabled=false mantem apenas as actions configuradas e bloqueia a descoberta contextual por HATEOAS/capabilities.\"],\"examples\":[\"{ actions: { row: { header: { label: \\\"Ações\\\", align: \\\"end\\\" }, maxVisibleActions: 3, behavior: { enabled: true, maxInline: 2 } } } }\",\"{ actions: { row: { enabled: true, display: \\\"buttons\\\", discovery: { enabled: false }, actions: [{ id: \\\"briefing\\\", label: \\\"Briefing\\\", action: \\\"inspect-surfaces\\\" }] } } }\"],\"antiPatterns\":[\"{ row: { header: { align: \\\"middle\\\" } } }\"]},\"bulk-actions\":{\"id\":\"bulk-actions\",\"title\":\"Acoes em Lote\",\"description\":\"Configuração de actions.bulk.*\",\"rules\":[\"bulk.enabled exige selection.enabled.\",\"floating.position deve ser bottom-right/bottom-left/top-right/top-left.\",\"hideWhenEmpty evita botão flutuante quando nada selecionado.\"],\"examples\":[\"{ actions: { bulk: { enabled: true, position: \\\"toolbar\\\", actions: [{ id: \\\"delete\\\", label: \\\"Excluir\\\", action: \\\"bulk-delete\\\", requiresConfirmation: true }], floating: { position: \\\"bottom-right\\\", hideWhenEmpty: true } } } }\"],\"antiPatterns\":[\"{ actions: { bulk: { enabled: true } } } sem selection.enabled\"]},\"context-actions\":{\"id\":\"context-actions\",\"title\":\"Menu de Contexto\",\"description\":\"Configuração de actions.context.*\",\"rules\":[\"trigger deve ser right-click/long-press/both.\",\"actions[].action deve ser string.\"],\"examples\":[\"{ actions: { context: { enabled: true, trigger: \\\"right-click\\\", actions: [{ id: \\\"copy\\\", label: \\\"Copiar\\\", action: \\\"copy\\\" }] } } }\"],\"antiPatterns\":[\"{ context: { trigger: \\\"click\\\" } }\"]}}}",
           "sourcePointer": "projects/praxis-table/src/lib/ai/table-context-pack.ts",
-          "contentHash": "d5538c651ed8883fdf89d5bad8b5cd45e912912913ca352a249a02d927b40eac",
+          "contentHash": "53d73757e5371b6d7de9c66090fbec49c0866649166fe4e28f040f564b3f07c3",
           "sourceKind": "component_definition",
           "sourceId": "praxis-table",
           "corpusVersion": "1.0.0"

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