@sankhyalabs/ezui-docs 7.3.4-rc.1 → 7.3.5-dev.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -55,6 +55,7 @@ Type: `Promise<void>`
55
55
  - [ez-classic-search](../ez-classic-search)
56
56
  - [ez-dialog](../ez-dialog)
57
57
  - [ez-double-list](../ez-double-list)
58
+ - [ez-filter](../ez-filter)
58
59
  - [ez-grid](../ez-grid)
59
60
  - [ez-grid-pagination](../ez-grid-pagination)
60
61
  - [ez-guide-navigator](../ez-guide-navigator)
@@ -84,6 +85,7 @@ graph TD;
84
85
  ez-classic-search --> ez-button
85
86
  ez-dialog --> ez-button
86
87
  ez-double-list --> ez-button
88
+ ez-filter --> ez-button
87
89
  ez-grid --> ez-button
88
90
  ez-grid-pagination --> ez-button
89
91
  ez-guide-navigator --> ez-button
@@ -0,0 +1,401 @@
1
+ # ez-filter
2
+
3
+ Painel lateral de filtros, **agnóstico ao contexto de negócio**. Oferece uma estrutura flexível e
4
+ reutilizável para montar filtros, gerando os campos automaticamente a partir da **metadata do core**
5
+ (`UnitMetadata` via `DataUnit`) — o mesmo motor usado pelo `ez-form` (`buildFormMetadata` +
6
+ `ez-form-view` + `DataBinder`).
7
+
8
+ O componente cuida de **estrutura, comportamento e coleta/validação de valores**. Ele **emite eventos**
9
+ de aplicação/remoção/limpeza; a tradução dos valores para `Filter`/`QuickFilter` e a aplicação efetiva
10
+ (ex.: `dataUnit.loadData(...)`) ficam por conta do consumidor, mantendo a biblioteca sem regra de negócio.
11
+
12
+ ## Modos de interação
13
+
14
+ - **`overlay`** (padrão): o painel é fixo e sobrepõe o conteúdo da página (com backdrop/scrim opcional),
15
+ sem alterar o layout.
16
+ - **`push`**: o painel ocupa espaço no fluxo, deslocando (empurrando) o conteúdo irmão. Nesse modo,
17
+ posicione o `ez-filter` num container flex/grid ao lado do conteúdo principal.
18
+
19
+ ## Uso
20
+
21
+ ```tsx
22
+ // React (@sankhyalabs/react-ezui)
23
+ <EzFilter
24
+ ref={filterRef}
25
+ interactionMode="push"
26
+ metadata={unitMetadata} // metadata do core
27
+ fields={[{ name: "NOMEPARC" }, { name: "DATANEG", required: true }]}
28
+ initialValues={{ ATIVO: "S" }}
29
+ onEzApplyFilter={(e) => aplicarFiltros(e.detail.values)}
30
+ onEzClearFilter={() => limparFiltros()}
31
+ />;
32
+
33
+ // Abrir/fechar e alterar valores por método
34
+ await filterRef.current.open();
35
+ await filterRef.current.setFieldValue("NOMEPARC", "Sankhya");
36
+ const valores = await filterRef.current.getValues();
37
+ ```
38
+
39
+ ```html
40
+ <!-- HTML puro: DataUnit já carregado é passado via propriedade -->
41
+ <ez-filter id="meuFiltro" interaction-mode="overlay"></ez-filter>
42
+ <script>
43
+ const el = document.querySelector("#meuFiltro");
44
+ el.dataUnit = meuDataUnit; // com metadata do core já carregada
45
+ el.addEventListener("ezApplyFilter", (e) => console.log(e.detail.values));
46
+ el.open();
47
+ </script>
48
+ ```
49
+
50
+ ## Campos customizados
51
+
52
+ Campos que não existem na metadata padrão podem ser adicionados como campos `standAlone`, participando
53
+ normalmente da coleta de valores, limpeza e validação:
54
+
55
+ ```ts
56
+ await filterRef.current.registerCustomField({
57
+ name: "FAIXA_PRECO",
58
+ label: "Faixa de preço",
59
+ userInterface: UserInterface.DECIMALNUMBER,
60
+ required: false,
61
+ });
62
+ ```
63
+
64
+ Para conteúdo totalmente livre (fora do fluxo de valores/validação), há o slot `custom-fields` como
65
+ escape hatch.
66
+
67
+ <!-- Auto Generated Below -->
68
+
69
+
70
+ ## Overview
71
+
72
+ Painel lateral de filtros, agnóstico ao contexto de negócio.
73
+
74
+ Gera os campos automaticamente a partir da metadata do core (`UnitMetadata` via `DataUnit`),
75
+ reutilizando o mesmo motor de dados do formulário (`buildFormMetadata` + `ez-form-view` + `DataBinder`).
76
+
77
+ O componente é responsável apenas por estrutura, comportamento e coleta/validação de valores:
78
+ ele **emite eventos** de aplicação/remoção/limpeza, deixando a tradução para `Filter`/`QuickFilter`
79
+ e a aplicação efetiva (ex.: `dataUnit.loadData(...)`) por conta do consumidor.
80
+
81
+ ## Properties
82
+
83
+ | Property | Attribute | Description | Type | Default |
84
+ | ------------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | ----------- |
85
+ | `applyButtonLabel` | `apply-button-label` | Rótulo do botão de aplicar filtros. | `string` | `undefined` |
86
+ | `applyOnEnter` | `apply-on-enter` | Aplica os filtros ao pressionar `Enter` com o painel aberto. | `boolean` | `true` |
87
+ | `clearButtonLabel` | `clear-button-label` | Rótulo do botão de limpar filtros. | `string` | `undefined` |
88
+ | `closeOnEsc` | `close-on-esc` | Fecha o painel ao pressionar `Esc`. | `boolean` | `true` |
89
+ | `closeOnScrimClick` | `close-on-scrim-click` | Fecha o painel ao clicar no backdrop (modo `overlay`). | `boolean` | `true` |
90
+ | `dataUnit` | -- | Unidade de dados que controla os valores e a metadata dos filtros. Quando ausente, o componente cria uma instância interna. | `DataUnit` | `undefined` |
91
+ | `fields` | -- | Seleção, ordem e sobrescrita (label, obrigatoriedade, valor padrão) dos campos. Quando ausente, todos os campos visíveis da metadata são apresentados. | `IFieldConfig[]` | `undefined` |
92
+ | `initialValues` | -- | Valores iniciais dos filtros, no formato `{ nomeDoCampo: valor }`. | `{ [fieldName: string]: any; }` | `undefined` |
93
+ | `interactionMode` | `interaction-mode` | Define como o painel interage com o conteúdo principal. - `overlay`: sobrepõe o conteúdo, sem alterar o layout da página. - `push`: ocupa espaço no fluxo, deslocando (empurrando) o conteúdo irmão. | `"overlay" \| "push"` | `"overlay"` |
94
+ | `metadata` | -- | Metadata do core usada para gerar os campos. Alternativa a fornecer um `dataUnit` já carregado. | `UnitMetadata` | `undefined` |
95
+ | `opened` | `opened` | Define se o painel está aberto. | `boolean` | `false` |
96
+ | `panelTitle` | `panel-title` | Título exibido no cabeçalho do painel. | `string` | `undefined` |
97
+ | `recordValidator` | -- | Validador customizado responsável pela integridade dos filtros. | `IRecordValidator` | `undefined` |
98
+ | `showScrim` | `show-scrim` | Exibe o backdrop (scrim) no modo `overlay`. | `boolean` | `true` |
99
+
100
+
101
+ ## Events
102
+
103
+ | Event | Description | Type |
104
+ | ---------------- | -------------------------------------------------------- | ------------------------------------------------- |
105
+ | `ezApplyFilter` | Emitido ao aplicar os filtros (após a validação). | `CustomEvent<IFilterChange>` |
106
+ | `ezChange` | Emitido quando o valor de um campo do filtro é alterado. | `CustomEvent<{ fieldName: string; value: any; }>` |
107
+ | `ezClearFilter` | Emitido ao limpar todos os filtros. | `CustomEvent<void>` |
108
+ | `ezClose` | Emitido quando o painel é fechado. | `CustomEvent<void>` |
109
+ | `ezOpen` | Emitido quando o painel é aberto. | `CustomEvent<void>` |
110
+ | `ezRemoveFilter` | Emitido ao remover um filtro específico. | `CustomEvent<{ fieldName: string; }>` |
111
+
112
+
113
+ ## Methods
114
+
115
+ ### `addCustomEditor(fieldName: string, editor: ICustomEditor) => Promise<void>`
116
+
117
+ Registra um editor customizado para um campo já existente na metadata.
118
+
119
+ #### Returns
120
+
121
+ Type: `Promise<void>`
122
+
123
+ ---
124
+
125
+ ### `apply() => Promise<boolean>`
126
+
127
+ Valida e, quando válido, emite `ezApplyFilter` com os valores atuais.
128
+
129
+ #### Returns
130
+
131
+ Type: `Promise<boolean>`
132
+
133
+ `true` quando aplicado; `false` quando bloqueado pela validação.
134
+
135
+ ---
136
+
137
+ ### `clear() => Promise<void>`
138
+
139
+ Limpa todos os filtros (esvazia o valor de cada campo) e emite `ezClearFilter`.
140
+
141
+ #### Returns
142
+
143
+ Type: `Promise<void>`
144
+
145
+ ---
146
+
147
+ ### `close() => Promise<void>`
148
+
149
+ Fecha o painel de filtros.
150
+
151
+ #### Returns
152
+
153
+ Type: `Promise<void>`
154
+
155
+ ---
156
+
157
+ ### `getValues() => Promise<{ [fieldName: string]: any; }>`
158
+
159
+ Retorna os valores atuais dos filtros preenchidos.
160
+
161
+ #### Returns
162
+
163
+ Type: `Promise<{ [fieldName: string]: any; }>`
164
+
165
+ Mapa `nomeDoCampo` → `valor`.
166
+
167
+ ---
168
+
169
+ ### `open() => Promise<void>`
170
+
171
+ Abre o painel de filtros.
172
+
173
+ #### Returns
174
+
175
+ Type: `Promise<void>`
176
+
177
+ ---
178
+
179
+ ### `registerCustomField(field: IFilterCustomField) => Promise<void>`
180
+
181
+ Adiciona um campo customizado que não existe na metadata padrão do core.
182
+
183
+ #### Returns
184
+
185
+ Type: `Promise<void>`
186
+
187
+ ---
188
+
189
+ ### `removeFilter(fieldName: string) => Promise<void>`
190
+
191
+ Remove um filtro específico (limpa seu valor) e emite `ezRemoveFilter`.
192
+
193
+ #### Returns
194
+
195
+ Type: `Promise<void>`
196
+
197
+ ---
198
+
199
+ ### `setFieldValue(fieldName: string, value: any) => Promise<void>`
200
+
201
+ Altera o valor de um filtro.
202
+
203
+ #### Returns
204
+
205
+ Type: `Promise<void>`
206
+
207
+ ---
208
+
209
+ ### `toggle() => Promise<void>`
210
+
211
+ Alterna o estado de abertura do painel.
212
+
213
+ #### Returns
214
+
215
+ Type: `Promise<void>`
216
+
217
+ ---
218
+
219
+ ### `validate() => Promise<boolean>`
220
+
221
+ Valida os filtros (campos obrigatórios e validador customizado).
222
+
223
+ #### Returns
224
+
225
+ Type: `Promise<boolean>`
226
+
227
+ `true` quando válido; `false` caso contrário.
228
+
229
+
230
+ ## Shadow Parts
231
+
232
+ | Part | Description |
233
+ | ---------- | ----------- |
234
+ | `"body"` | |
235
+ | `"footer"` | |
236
+ | `"header"` | |
237
+ | `"panel"` | |
238
+ | `"scrim"` | |
239
+ | `"title"` | |
240
+
241
+
242
+ ## Dependencies
243
+
244
+ ### Depends on
245
+
246
+ - [ez-button](../ez-button)
247
+ - [ez-form-view](../ez-form-view)
248
+
249
+ ### Graph
250
+ ```mermaid
251
+ graph TD;
252
+ ez-filter --> ez-button
253
+ ez-filter --> ez-form-view
254
+ ez-button --> ez-icon
255
+ ez-form-view --> ez-custom-form-input
256
+ ez-form-view --> ez-collapsible-box
257
+ ez-form-view --> ez-check
258
+ ez-form-view --> ez-classic-combo-box
259
+ ez-form-view --> ez-combo-box
260
+ ez-form-view --> ez-classic-date-input
261
+ ez-form-view --> ez-date-input
262
+ ez-form-view --> ez-classic-time-input
263
+ ez-form-view --> ez-time-input
264
+ ez-form-view --> ez-classic-date-time-input
265
+ ez-form-view --> ez-date-time-input
266
+ ez-form-view --> ez-upload
267
+ ez-form-view --> ez-classic-number-input
268
+ ez-form-view --> ez-number-input
269
+ ez-form-view --> ez-classic-text-area
270
+ ez-form-view --> ez-text-area
271
+ ez-form-view --> ez-classic-input
272
+ ez-form-view --> ez-text-input
273
+ ez-form-view --> ez-classic-search-plus
274
+ ez-form-view --> ez-search-plus
275
+ ez-form-view --> ez-classic-search
276
+ ez-form-view --> ez-search
277
+ ez-form-view --> ez-rich-text
278
+ ez-form-view --> ez-image-input
279
+ ez-form-view --> ez-multi-select-input
280
+ ez-collapsible-box --> ez-icon
281
+ ez-collapsible-box --> ez-text-edit
282
+ ez-text-edit --> ez-text-input
283
+ ez-text-edit --> ez-button
284
+ ez-text-input --> ez-tooltip
285
+ ez-text-input --> ez-icon
286
+ ez-classic-combo-box --> ez-classic-input
287
+ ez-classic-combo-box --> ez-popover-core
288
+ ez-classic-input --> ez-icon
289
+ ez-combo-box --> ez-text-input
290
+ ez-combo-box --> ez-icon
291
+ ez-combo-box --> ez-popover-plus
292
+ ez-combo-box --> ez-combo-box-list
293
+ ez-popover-plus --> ez-popover-core
294
+ ez-classic-date-input --> ez-classic-input
295
+ ez-classic-date-input --> ez-popover-plus
296
+ ez-classic-date-input --> ez-calendar
297
+ ez-date-input --> ez-text-input
298
+ ez-date-input --> ez-popover-plus
299
+ ez-date-input --> ez-calendar
300
+ ez-classic-time-input --> ez-classic-input
301
+ ez-time-input --> ez-text-input
302
+ ez-time-input --> ez-icon
303
+ ez-classic-date-time-input --> ez-classic-input
304
+ ez-classic-date-time-input --> ez-popover-plus
305
+ ez-classic-date-time-input --> ez-calendar
306
+ ez-date-time-input --> ez-text-input
307
+ ez-date-time-input --> ez-popover-plus
308
+ ez-date-time-input --> ez-calendar
309
+ ez-classic-number-input --> ez-classic-input
310
+ ez-number-input --> ez-text-input
311
+ ez-classic-text-area --> ez-icon
312
+ ez-text-area --> ez-tooltip
313
+ ez-text-area --> ez-icon
314
+ ez-classic-search-plus --> ez-classic-input
315
+ ez-classic-search-plus --> ez-popover-plus
316
+ ez-classic-search-plus --> ez-classic-search-result-list
317
+ ez-classic-search-result-list --> ez-card-item
318
+ ez-classic-search-result-list --> ez-skeleton
319
+ ez-search-plus --> ez-icon
320
+ ez-search-plus --> ez-text-input
321
+ ez-search-plus --> ez-popover-plus
322
+ ez-search-plus --> ez-search-result-list
323
+ ez-search-result-list --> ez-card-item
324
+ ez-search-result-list --> ez-skeleton
325
+ ez-classic-search --> ez-button
326
+ ez-classic-search --> ez-classic-input
327
+ ez-classic-search --> ez-popover-plus
328
+ ez-classic-search --> classic-search-list
329
+ classic-search-list --> ez-card-item
330
+ ez-search --> ez-button
331
+ ez-search --> ez-text-input
332
+ ez-search --> ez-icon
333
+ ez-search --> ez-popover-plus
334
+ ez-search --> search-list
335
+ search-list --> ez-card-item
336
+ ez-rich-text --> ez-text-area
337
+ ez-rich-text --> ez-rich-toolbar
338
+ ez-rich-text --> ez-link-builder
339
+ ez-rich-text --> ez-simple-image-uploader
340
+ ez-rich-toolbar --> ez-rich-toolbar-arrows
341
+ ez-rich-toolbar --> ez-rich-toolbar-letters
342
+ ez-rich-toolbar --> ez-rich-toolbar-configs
343
+ ez-rich-toolbar-arrows --> ez-rich-toolbar-item
344
+ ez-rich-toolbar-item --> ez-icon
345
+ ez-rich-toolbar-letters --> ez-rich-toolbar-item
346
+ ez-rich-toolbar-configs --> ez-rich-toolbar-item
347
+ ez-link-builder --> ez-popup
348
+ ez-link-builder --> ez-modal-container
349
+ ez-link-builder --> ez-text-input
350
+ ez-link-builder --> ez-check
351
+ ez-popup --> ez-button
352
+ ez-modal-container --> ez-icon
353
+ ez-modal-container --> ez-button
354
+ ez-simple-image-uploader --> ez-popup
355
+ ez-simple-image-uploader --> ez-modal-container
356
+ ez-simple-image-uploader --> ez-tooltip
357
+ ez-simple-image-uploader --> ez-text-input
358
+ ez-simple-image-uploader --> ez-icon
359
+ ez-image-input --> ez-skeleton
360
+ ez-image-input --> ez-button
361
+ ez-image-input --> ez-icon
362
+ ez-image-input --> ez-popup
363
+ ez-multi-select-input --> ez-icon
364
+ ez-multi-select-input --> ez-tooltip
365
+ ez-multi-select-input --> ez-popover-core
366
+ ez-multi-select-input --> ez-multi-selection-list
367
+ ez-multi-selection-list --> ez-check
368
+ ez-multi-selection-list --> ez-list
369
+ ez-multi-selection-list --> ez-icon
370
+ ez-multi-selection-list --> multi-selection-box-message
371
+ ez-multi-selection-list --> ez-filter-input
372
+ ez-multi-selection-list --> ez-search
373
+ ez-list --> ez-check
374
+ ez-filter-input --> ez-text-input
375
+ ez-filter-input --> ez-icon
376
+ style ez-filter fill:#f9f,stroke:#333,stroke-width:4px
377
+ ```
378
+
379
+ ----------------------------------------------
380
+
381
+
382
+
383
+
384
+ ## CSS Variables
385
+ | Variable | Description |
386
+ |-|-|
387
+ | --ez-filter--width | Define a largura do painel de filtros. |
388
+ | --ez-filter--background-color | Define a cor de fundo do painel. |
389
+ | --ez-filter--padding | Define o espaçamento interno do cabeçalho, corpo e rodapé. |
390
+ | --ez-filter--border-radius | Define o raio da borda do painel (aplicado aos cantos direitos). |
391
+ | --ez-filter--z-index | Define a camada de exibição do painel no modo overlay. |
392
+ | --ez-filter--transition-duration | Define a duração da transição de abertura/fechamento. |
393
+ | --ez-filter--transition-timing | Define a curva de aceleração da transição de abertura/fechamento. |
394
+ | --ez-filter--scrim-color | Define a cor do backdrop (scrim) no modo overlay. |
395
+ | --ez-filter--scrim-blur | Define o desfoque do backdrop (scrim) no modo overlay. |
396
+ | --ez-filter--box-shadow | Define a sombra do painel no modo overlay. |
397
+ | --ez-filter--title-color | Define a cor do título do painel. |
398
+ | --ez-filter--title-font-size | Define o tamanho da fonte do título do painel. |
399
+ | --ez-filter--divider-color | Define a cor da borda que separa cabeçalho e rodapé do corpo. |
400
+ | --ez-filter--header-gap | Define o espaçamento entre os itens do cabeçalho. |
401
+ | --ez-filter--footer-gap | Define o espaçamento entre os botões do rodapé. |
@@ -61,6 +61,7 @@ Type: `Promise<void>`
61
61
 
62
62
  ### Used by
63
63
 
64
+ - [ez-filter](../ez-filter)
64
65
  - [ez-form](../ez-form)
65
66
 
66
67
  ### Depends on
@@ -216,6 +217,7 @@ graph TD;
216
217
  ez-list --> ez-check
217
218
  ez-filter-input --> ez-text-input
218
219
  ez-filter-input --> ez-icon
220
+ ez-filter --> ez-form-view
219
221
  ez-form --> ez-form-view
220
222
  style ez-form-view fill:#f9f,stroke:#333,stroke-width:4px
221
223
  ```
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sankhyalabs/ezui-docs",
3
- "version": "7.3.4-rc.1",
3
+ "version": "7.3.5-dev.1",
4
4
  "description": "Documentação da biblioteca de componentes Sankhya.",
5
5
  "main": "",
6
6
  "files": [