@wgalleti/primevue-components 0.32.0 → 0.32.1

package/dist/types/column.d.ts

@@ -1,8 +1,8 @@
 export type ColumnType = 'text' | 'boolean' | 'date' | 'datetime' | 'number' | 'currency' | 'image' | 'custom';
 /** Severidade do tag de status (mesmos nomes do PrimeVue; a cor vem dos tokens do app). */
 export type TagSeverity = 'success' | 'info' | 'warn' | 'danger' | 'secondary' | 'contrast' | 'primary';
-/** Filtro declarativo de coluna — renderizado na barra de filtros e enviado
- *  como parâmetro na requisição de `list`. Opt-in por coluna. */
+/** Filtro declarativo de coluna — renderizado na toolbar do grid, ao lado da
+ *  busca, e enviado como parâmetro na requisição de `list`. Opt-in por coluna. */
 export interface ColumnFilter {
     /** Widget do filtro. Default: 'text'. */
     type?: 'text' | 'select' | 'boolean' | 'numeric';
@@ -37,6 +37,6 @@ export interface ColumnDef {
     /** `type: 'boolean'` — cor do tag no `false` (default 'danger'). `null` = texto neutro,
      *  sem tag — para boolean que não é status (ex.: `nao_exige_analise` → "—"). */
     falseSeverity?: TagSeverity | null;
-    /** Filtro declarativo desta coluna (aparece na barra de filtros). */
+    /** Filtro declarativo desta coluna (aparece na toolbar do grid, junto da busca). */
     filter?: ColumnFilter;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wgalleti/primevue-components",
-  "version": "0.32.0",
+  "version": "0.32.1",
   "type": "module",
   "license": "MIT",
   "publishConfig": {

package/skill/SKILL.md

@@ -20,6 +20,7 @@ Biblioteca interna de componentes **Vue 3 + PrimeVue 4** para CRUD, formulários
 3. **Endpoints são strings**; a resposta paginada esperada é `{ data, page, page_size, rows }`.
 4. **Datas**: use `WDatePicker` (v-model string `YYYY-MM-DD`). Nunca `parseDate`/`toISOString` à mão.
 5. Antes de inventar prop, confirme a API nos tipos publicados: `node_modules/@wgalleti/primevue-components/dist/*.d.ts` (`FieldDef`, `ColumnDef`, `CrudManagerConfig`, props dos componentes).
+6. **Filtro de listagem mora na toolbar do grid, ao lado da busca** — declarado em `ColumnDef.filter` (padrão) ou, quando o declarativo não cobre (FK, período), no slot `toolbar-filters`. Nunca em faixa própria acima da tabela, painel lateral ou `before-table`.
 
 ## Fluxo rápido
 

package/skill/references/crud.md

@@ -27,6 +27,15 @@ Retornos úteis do `crud` (além de alimentar o WCrudView): `selectedItems`, `cl
 
 `<WCrudView>` aceita `title`, `subtitle`, `dialog-width`, e **slots** para sobrescrever qualquer seção (toolbar, ações de linha, etc.).
 
+### Filtros: sempre na toolbar do grid, ao lado da busca
+
+Todo filtro de uma listagem mora **dentro do grid**, na mesma toolbar da busca — nunca numa faixa própria acima da tabela, num painel lateral, no cabeçalho da página ou em `before-table`. Ordem fixa na toolbar: busca → `toolbar-start` → filtros declarativos (`ColumnDef.filter`) → slot `toolbar-filters` → "Limpar filtros". Dois caminhos, nessa ordem de preferência:
+
+1. **Declarativo** (`ColumnDef.filter` no schema) — select, boolean, text, numeric. É o padrão; o WCrudView renderiza na toolbar sozinho.
+2. **Slot `toolbar-filters`** — só para o que o declarativo não cobre: FK com busca no servidor (`WAutoCompleteFK` com o schema da entidade, sem CRUD), período, alternador. Grava pelo mesmo `crud.setColumnFilter(param, valor)`, então "Limpar filtros" limpa tudo junto.
+
+`before-table` é para o que **não** é filtro (KPIs, funil clicável). Filtro fora da toolbar é defeito — corrija movendo para o schema ou para o slot, não com CSS.
+
 ## ColumnDef (tabela)
 
 ```ts
@@ -35,14 +44,14 @@ Retornos úteis do `crud` (além de alimentar o WCrudView): `selectedItems`, `cl
 
 `type`: `text | boolean | date | datetime | number | currency | image | custom`. Sem `type` → texto cru. Para célula custom, use `type: 'custom'` + slot, ou `WCrudColumnRenderer`.
 
-Outros campos: `format(value, row) => string` (render próprio), `visible`, `decimals`, `tagValue`/`tagSeverity` (renderiza como tag), e **`filter`** — filtro declarativo por coluna que aparece na barra de filtros e vai como parâmetro no `list`:
+Outros campos: `format(value, row) => string` (render próprio), `visible`, `decimals`, `tagValue`/`tagSeverity` (renderiza como tag), e **`filter`** — filtro declarativo por coluna que aparece na toolbar do grid (ao lado da busca) e vai como parâmetro no `list`:
 
 ```ts
 { field: 'status', header: 'Status', filter: { type: 'select', options: [
   { label: 'Ativo', value: 'A' }, { label: 'Inativo', value: 'I' },
 ] } }
 ```
-`filter.type`: `text | select | boolean | numeric`. Sem `param`, usa o `field`.
+`filter.type`: `text | select | boolean | numeric`. Sem `param`, usa o `field` — e o nome tem de existir na allowlist de filtros da API.
 
 ## FieldDef (formulário)