@praxisui/dynamic-form 8.0.0-beta.2 → 8.0.0-beta.21

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.
@@ -0,0 +1,507 @@
1
+ ---
2
+ title: "praxis-filter-form JSON API (Canonical)"
3
+ slug: "praxis-filter-form-json-api"
4
+ doc_type: "api-reference"
5
+ component: "praxis-filter-form"
6
+ document_kind: "json-api-canonical"
7
+ reference_mode: "canonical"
8
+ contract_format: "json"
9
+ contract_source: "runtime-and-code"
10
+ description: "Referencia canonica do contrato JSON do componente praxis-filter-form."
11
+ category: "components"
12
+ sub_category: "dynamic-form"
13
+ audience:
14
+ - "frontend"
15
+ - "architect"
16
+ - "platform-team"
17
+ level: "advanced"
18
+ status: "active"
19
+ owner: "praxis-ui"
20
+ source_of_truth:
21
+ - "projects/praxis-dynamic-form/src/lib/filter-form/praxis-filter-form.metadata.ts"
22
+ - "projects/praxis-dynamic-form/src/lib/filter-form/praxis-filter-form.ts"
23
+ - "projects/praxis-dynamic-form/src/lib/filter-form/praxis-filter-form.html"
24
+ - "projects/praxis-core/src/lib/models/form/form-config.model.ts"
25
+ - "projects/praxis-dynamic-fields/src/lib/directives/dynamic-field-loader.directive.ts"
26
+ source_of_truth_last_verified: "2026-03-05"
27
+ last_updated: "2026-03-05"
28
+ toc: true
29
+ sidebar: true
30
+ tags:
31
+ - "json-api"
32
+ - "canonical-contract"
33
+ - "praxis-filter-form"
34
+ api_stability: "canonical"
35
+ schema_verified: true
36
+ runtime_verified: false
37
+ editor_coverage_verified: false
38
+ runtime_scope: "public"
39
+ legacy_paths_present: false
40
+ has_known_mismatches: true
41
+ related_components:
42
+ - "praxis-table"
43
+ ---
44
+
45
+ # praxis-filter-form
46
+
47
+ Este documento e a referencia canonica da API JSON de praxis-filter-form.
48
+
49
+ ## Summary
50
+
51
+ - Tipo documental: API reference canonica de contrato JSON.
52
+ - Source of truth: runtime e codigo declarados no frontmatter.
53
+ - Objetivo operacional: consulta rapida, auditavel e deterministica sob pressao.
54
+ - Resumo funcional herdado: `praxis-filter-form` e um runtime de filtro JSON-first para cenarios de busca/listagem. Ele constroi um `FormGroup` a partir de `config.fieldMetadata`, renderiza os campos via `dynamicFieldLoader` e emite eventos de ciclo (`formReady`, `valueChange`, `requestSearch`, `submit`, `validityChange`) para o host.
55
+
56
+ ## Scope and positioning
57
+
58
+ - Escopo: contrato JSON publico e limites de comportamento observavel.
59
+ - Fora de escopo: tutorial de adocao e walkthrough operacional detalhado.
60
+ - Posicionamento: referencia canonicamente governada para consumidores, arquitetos e mantenedores.
61
+
62
+ ## Source of truth
63
+
64
+ | Source | Kind | Notes |
65
+ | --- | --- | --- |
66
+ | projects/praxis-dynamic-form/src/lib/filter-form/praxis-filter-form.metadata.ts | runtime-code | Source de implementacao declarado no repositorio. |
67
+ | projects/praxis-dynamic-form/src/lib/filter-form/praxis-filter-form.ts | runtime-code | Source de implementacao declarado no repositorio. |
68
+ | projects/praxis-dynamic-form/src/lib/filter-form/praxis-filter-form.html | template-style | Source de implementacao declarado no repositorio. |
69
+ | projects/praxis-core/src/lib/models/form/form-config.model.ts | runtime-code | Source de implementacao declarado no repositorio. |
70
+ | projects/praxis-dynamic-fields/src/lib/directives/dynamic-field-loader.directive.ts | runtime-code | Source de implementacao declarado no repositorio. |
71
+
72
+ ## Support legend
73
+
74
+ - Active: suportado e observado no runtime atual.
75
+ - Partial: suporte parcial, com restricoes conhecidas.
76
+ - Declared-only: declarado em tipos/schema sem ligacao runtime confirmada.
77
+ - Schema-only: presente em schema/modelo sem confirmacao de execucao.
78
+ - Deprecated: mantido por compatibilidade legada com migracao prevista.
79
+
80
+ ## Contract classification
81
+
82
+ ### Canonical paths (public contract)
83
+
84
+ | Path | Type | Required | Default | Status | Notes |
85
+ | --- | --- | --- | --- | --- | --- |
86
+ | `config.fieldMetadata[]` | `FieldMetadata[]` | Sim (na pratica) | n/a | Active | Base para criar controles e renderizar campos. |
87
+ | `config.sections[]` | `FormSection[]` | Nao | n/a | Active | Se presente, organiza render em secoes/linhas/colunas. |
88
+ | `config.sections[].rows[].columns[].fields[]` | `string[]` | Nao | n/a | Active | Mapeia quais campos de `fieldMetadata` vao em cada coluna. |
89
+ | Outros blocos de `FormConfig` (`actions`, `messages`, `behavior`, `hooks`, etc.) | varios | Nao | n/a | Declared-only | Nao possuem leitura dedicada neste componente. |
90
+
91
+ ### Supported legacy paths
92
+
93
+ Nenhum path legado suportado foi identificado nesta revisão baseada em evidência textual preservada.
94
+
95
+ ### Internal-only paths
96
+
97
+ | Path | Internal consumer | Runtime presence | Public support | Notes |
98
+ | --- | --- | --- | --- | --- |
99
+ | not-yet-mapped | not-yet-verified | not-yet-verified | No | Caminhos internos nao mapeados explicitamente nesta revisao automatizada. |
100
+
101
+ ### Experimental paths
102
+
103
+ | Path | Enablement (flag/guard) | Stability | Rollout notes | Notes |
104
+ | --- | --- | --- | --- | --- |
105
+ | not-yet-mapped | not-yet-verified | Experimental | not-yet-verified | Registrar somente quando houver evidencia em runtime/codigo. |
106
+
107
+ ## Overview
108
+
109
+ Este arquivo foi adaptado para o padrao canonico atual sem remover conteudo tecnico existente. O conteudo detalhado anterior foi preservado para manter rastreabilidade historica e reduzir perda de contexto.
110
+
111
+ ## Public contract surface
112
+
113
+ ### Top-level configuration blocks
114
+
115
+ | Block | Purpose | Required | Merge strategy | Notes |
116
+ | --- | --- | --- | --- | --- |
117
+ | config | Configuração top-level identificada na referência preservada. | not-yet-verified | component-defined | 3 path(s) mapeado(s), status predominante Active. |
118
+
119
+ ### Nested configuration blocks
120
+
121
+ | Path | Type | Required | Default | Constraints | Notes |
122
+ | --- | --- | --- | --- | --- | --- |
123
+ | `config.fieldMetadata[]` | `FieldMetadata[]` | Sim (na pratica) | n/a | component-defined | Base para criar controles e renderizar campos. |
124
+ | `config.sections[]` | `FormSection[]` | Nao | n/a | component-defined | Se presente, organiza render em secoes/linhas/colunas. |
125
+ | `config.sections[].rows[].columns[].fields[]` | `string[]` | Nao | n/a | component-defined | Mapeia quais campos de `fieldMetadata` vao em cada coluna. |
126
+ | Outros blocos de `FormConfig` (`actions`, `messages`, `behavior`, `hooks`, etc.) | varios | Nao | n/a | component-defined | Nao possuem leitura dedicada neste componente. |
127
+
128
+ ### Input bindings
129
+
130
+ | Binding/Path | Type | Required | Source | Runtime normalization | Notes |
131
+ | --- | --- | --- | --- | --- | --- |
132
+ | `config` | `FormConfig` | Sim | component-input | not-yet-verified | Fonte principal de `fieldMetadata` e layout (`sections`). |
133
+ | `formId` | `string \| undefined` | Nao | component-input | not-yet-verified | Declarado no metadata; sem consumo direto no runtime atual. |
134
+ | `resourcePath` | `string \| undefined` | Nao | component-input | not-yet-verified | Declarado no metadata; sem consumo direto no runtime atual. |
135
+ | `mode` | `string \| undefined` | Nao | component-input | not-yet-verified | Declarado no metadata; sem condicao de fluxo no runtime atual. |
136
+
137
+ ### Output events
138
+
139
+ | Event | Payload | Trigger | Stability | Notes |
140
+ | --- | --- | --- | --- | --- |
141
+ | `formReady` | `{ formGroup: FormGroup<Record<string, any>> }` | Quando o form e recriado a partir do `config`. | Partial | Preservado da documentação anterior. |
142
+ | `valueChange` | `{ formData: Record<string, any> }` | Em toda mudanca de valor do formulario. | Partial | Preservado da documentação anterior. |
143
+ | `requestSearch` | `{ formData: Record<string, any> }` | Alias seguro e preferencial para o submit do `<form>` (inclui Enter). | Active | Recomendado para evitar colisao com submit nativo do DOM em hosts Angular. |
144
+ | `submit` | `{ formData: Record<string, any> }` | No submit do `<form>` (inclui Enter). | Partial | Mantido por compatibilidade; prefira `requestSearch`. |
145
+ | `validityChange` | `boolean` | Na inicializacao e em cada `statusChanges` do form. | Partial | Preservado da documentação anterior. |
146
+
147
+ ### External side channels
148
+
149
+ | Channel | Direction | Contract | Failure mode | Notes |
150
+ | --- | --- | --- | --- | --- |
151
+ | host/services/storage | bidirectional | see-detailed-api | not-yet-verified | Side channels dependem do componente e do host consumidor. |
152
+
153
+ ### Host/runtime dependencies
154
+
155
+ | Dependency | Required | Environment | Purpose | Notes |
156
+ | --- | --- | --- | --- | --- |
157
+ | see-source-of-truth | true | browser/dev/prod/ssr | runtime linkage | Confirmar por componente quando necessario. |
158
+
159
+ ## Coverage matrix
160
+
161
+ | Surface | Verified | Coverage status | Evidence | Notes |
162
+ | --- | --- | --- | --- | --- |
163
+ | Runtime | false | Partial | source_of_truth + conteudo preservado | Revisao estrutural concluida; validacao comportamental fina pode exigir follow-up. |
164
+ | Schema/Types | true | Partial | interfaces/modelos citados | Mapeamento formal de todos os campos ainda pode requerer refinamento. |
165
+ | Editor/Tooling | false | Partial | secoes de editor quando presentes | Cobertura de editor/tooling nem sempre confirmada por evidencia direta. |
166
+
167
+ ## Runtime coverage boundaries
168
+
169
+ - Cobertura consolidada com base em documentacao existente e source of truth declarado.
170
+ - Comportamentos fora de evidencia direta foram marcados como not-yet-verified ou Partial.
171
+ - Compatibilidade legada, quando detectada, foi separada em classificacao explicita.
172
+
173
+ ## Resolution model
174
+
175
+ ### Merge order
176
+
177
+ 1. defaults do componente
178
+ 2. contrato JSON recebido
179
+ 3. overrides de host/runtime
180
+ 4. normalizacoes internas
181
+
182
+ ### Fallback order
183
+
184
+ contrato explicito -> aliases legados (quando suportados) -> defaults internos -> comportamento seguro
185
+
186
+ ### Override points
187
+
188
+ - inputs publicos do componente
189
+ - configuracao JSON de runtime
190
+ - integracoes de host (servicos/tokens/adapters)
191
+
192
+ ### Runtime normalization
193
+
194
+ Campos e aliases preservados do documento anterior devem convergir progressivamente para paths canonicos declarados.
195
+
196
+ ### Precedence rules
197
+
198
+ Quando houver conflito entre alias e path canonico, priorizar path canonico e manter alias apenas para backward compatibility.
199
+
200
+ ## Validation and error semantics
201
+
202
+ ### Validation model
203
+
204
+ | Path/Rule | Validation phase | Behavior on fail | Error code / warning | Notes |
205
+ | --- | --- | --- | --- | --- |
206
+ | see-detailed-api | runtime | warn-or-reject | not-yet-standardized | Semantica de validacao preservada do documento anterior. |
207
+
208
+ ### Error semantics
209
+
210
+ Erros devem ser classificados em warnings recuperaveis versus falhas bloqueantes. Quando a evidencia nao estiver explicita, tratar como not yet verified.
211
+
212
+ ### Fail-open / fail-closed behavior
213
+
214
+ | Condition | Mode | Runtime behavior | Consumer impact |
215
+ | --- | --- | --- | --- |
216
+ | invalid-or-unknown-field | component-defined | not-yet-verified | Variavel por componente; requer verificacao em runtime. |
217
+
218
+ ### Invalid or unknown field handling
219
+
220
+ - Campos desconhecidos: comportamento depende da estrategia do componente (ignore, warn ou reject).
221
+ - Campos invalidos: podem gerar fallback, warning ou falha conforme implementacao.
222
+ - Registrar divergencias observadas em Known limitations and mismatches.
223
+
224
+ ### Runtime warnings vs hard failures
225
+
226
+ | Condition | Severity | Observability | Consumer action |
227
+ | --- | --- | --- | --- |
228
+ | partial-or-declared-only-coverage | warning | logs/eventos do componente | confirmar ligacao runtime antes de uso critico |
229
+
230
+ ## Detailed API
231
+
232
+ ### Preserved technical reference (normalized from previous revision)
233
+
234
+ ### 1. Visao Geral e Quando Usar
235
+ `praxis-filter-form` e um runtime de filtro JSON-first para cenarios de busca/listagem.
236
+ Ele constroi um `FormGroup` a partir de `config.fieldMetadata`, renderiza os campos via `dynamicFieldLoader` e emite eventos de ciclo (`formReady`, `valueChange`, `submit`, `validityChange`) para o host.
237
+
238
+ Use quando precisar de:
239
+ - formulario de filtros dirigido por JSON (`FormConfig`);
240
+ - layout opcional por `sections/rows/columns` com fallback para lista plana de campos;
241
+ - emissao continua de valores para busca reativa;
242
+ - submit por Enter (sem necessidade de botao visivel de acao).
243
+
244
+ ### 2. Referencia do Contrato JSON
245
+
246
+ #### 2.1 Inputs do Componente
247
+ | Input | Tipo | Padrao | Obrigatorio | Status | Comportamento no runtime |
248
+ | --- | --- | --- | --- | --- | --- |
249
+ | `config` | `FormConfig` | - | Sim | Active | Fonte principal de `fieldMetadata` e layout (`sections`). |
250
+ | `formId` | `string \| undefined` | `undefined` | Nao | Declared-only | Declarado no metadata; sem consumo direto no runtime atual. |
251
+ | `resourcePath` | `string \| undefined` | `undefined` | Nao | Declared-only | Declarado no metadata; sem consumo direto no runtime atual. |
252
+ | `mode` | `string \| undefined` | `undefined` | Nao | Declared-only | Declarado no metadata; sem condicao de fluxo no runtime atual. |
253
+
254
+ #### 2.2 Estrutura JSON Consumida de `config`
255
+ | Caminho JSON | Tipo | Obrigatorio | Status | Comportamento |
256
+ | --- | --- | --- | --- | --- |
257
+ | `config.fieldMetadata[]` | `FieldMetadata[]` | Sim (na pratica) | Active | Base para criar controles e renderizar campos. |
258
+ | `config.sections[]` | `FormSection[]` | Nao | Active | Se presente, organiza render em secoes/linhas/colunas. |
259
+ | `config.sections[].rows[].columns[].fields[]` | `string[]` | Nao | Active | Mapeia quais campos de `fieldMetadata` vao em cada coluna. |
260
+ | Outros blocos de `FormConfig` (`actions`, `messages`, `behavior`, `hooks`, etc.) | varios | Nao | Declared-only | Nao possuem leitura dedicada neste componente. |
261
+
262
+ #### 2.3 Outputs
263
+ | Output | Payload | Quando emite |
264
+ | --- | --- | --- |
265
+ | `formReady` | `{ formGroup: FormGroup<Record<string, any>> }` | Quando o form e recriado a partir do `config`. |
266
+ | `valueChange` | `{ formData: Record<string, any> }` | Em toda mudanca de valor do formulario. |
267
+ | `requestSearch` | `{ formData: Record<string, any> }` | Alias seguro e preferencial para o submit do `<form>` (inclui Enter). |
268
+ | `submit` | `{ formData: Record<string, any> }` | No submit do `<form>` (inclui Enter); mantido por compatibilidade. |
269
+ | `validityChange` | `boolean` | Na inicializacao e em cada `statusChanges` do form. |
270
+
271
+ ### 3. Mapeamento de Comportamento
272
+ - Inicializacao/rebuild:
273
+ - Quando `config` muda e `config.fieldMetadata` existe, o componente recria o `FormGroup`.
274
+ - Antes do rebuild, ele captura `getRawValue()` anterior e aplica `patchValue` no novo form para preservar valores por chave.
275
+ - Render:
276
+ - Com `sections` preenchido, usa layout estruturado (`section > row > column`).
277
+ - Sem `sections`, renderiza todos os itens de `fieldMetadata` em grade simples.
278
+ - Em ambos os casos, o render de campo delega para `dynamicFieldLoader` com `enableExternalControlBinding=true`.
279
+ - Submit:
280
+ - O template inclui um botao submit oculto para garantir submit por teclado (Enter).
281
+ - Validade:
282
+ - Emite `validityChange` imediatamente apos criar o form.
283
+ - Continua emitindo em cada mudanca de status.
284
+
285
+ Resumo de cobertura:
286
+ - `Ativo`: `config.fieldMetadata`, `config.sections`, `formReady`, `valueChange`, `submit`, `validityChange`.
287
+ - `Parcial`: preservacao de valor depende de correspondencia de `name` entre versao anterior e nova do metadata.
288
+ - `Declared-only`: `formId`, `resourcePath`, `mode` (sem impacto funcional hoje).
289
+
290
+ ### 4. Exemplo Minimo (JSON + Uso)
291
+ ```json
292
+ {
293
+ "config": {
294
+ "sections": [],
295
+ "fieldMetadata": [
296
+ {
297
+ "name": "term",
298
+ "label": "Busca",
299
+ "controlType": "input"
300
+ }
301
+ ]
302
+ }
303
+ }
304
+ ```
305
+
306
+ Uso:
307
+ ```html
308
+ <praxis-filter-form
309
+ [config]="filterConfig"
310
+ (valueChange)="onFilterLiveChange($event.formData)"
311
+ (requestSearch)="onFilterSubmit($event.formData)"
312
+ ></praxis-filter-form>
313
+ ```
314
+
315
+ ### 5. Exemplo Corporativo (JSON + Uso)
316
+ ```json
317
+ {
318
+ "config": {
319
+ "sections": [
320
+ {
321
+ "id": "main-filters",
322
+ "title": "Filtros de Operacao",
323
+ "rows": [
324
+ {
325
+ "id": "row-1",
326
+ "columns": [
327
+ { "id": "c-term", "fields": ["term"] },
328
+ { "id": "c-status", "fields": ["status"] },
329
+ { "id": "c-date", "fields": ["createdAt"] }
330
+ ]
331
+ }
332
+ ]
333
+ }
334
+ ],
335
+ "fieldMetadata": [
336
+ {
337
+ "name": "term",
338
+ "label": "Texto",
339
+ "controlType": "input",
340
+ "placeholder": "Cliente, pedido ou protocolo"
341
+ },
342
+ {
343
+ "name": "status",
344
+ "label": "Status",
345
+ "controlType": "select",
346
+ "selectOptions": [
347
+ { "label": "Ativo", "value": "ACTIVE" },
348
+ { "label": "Inativo", "value": "INACTIVE" }
349
+ ]
350
+ },
351
+ {
352
+ "name": "createdAt",
353
+ "label": "Criado em",
354
+ "controlType": "dateInput"
355
+ }
356
+ ]
357
+ },
358
+ "formId": "operations-filter-v1",
359
+ "resourcePath": "/api/operations",
360
+ "mode": "view"
361
+ }
362
+ ```
363
+
364
+ Uso:
365
+ ```html
366
+ <praxis-filter-form
367
+ [config]="operationsFilterConfig"
368
+ [formId]="'operations-filter-v1'"
369
+ [resourcePath]="'/api/operations'"
370
+ [mode]="'view'"
371
+ (formReady)="onFilterReady($event.formGroup)"
372
+ (valueChange)="onFilterLiveChange($event.formData)"
373
+ (validityChange)="onFilterValidity($event)"
374
+ (requestSearch)="runSearch($event.formData)"
375
+ ></praxis-filter-form>
376
+ ```
377
+
378
+ Nota: no runtime atual, `formId/resourcePath/mode` ainda nao alteram a execucao do componente; servem como contrato de integracao e contexto para o host.
379
+
380
+ ### 6. Problemas Comuns e Armadilhas
381
+ 1. Enviar `config` sem `fieldMetadata` e esperar formulario funcional.
382
+ Correcao: garanta `fieldMetadata` preenchido; sem ele o build nao ocorre.
383
+
384
+ 2. Usar `sections` com `fields` que nao existem em `fieldMetadata`.
385
+ Correcao: mantenha integridade entre nomes de campos no layout e no metadata.
386
+
387
+ 3. Esperar que `actions/messages/behavior/hooks` de `FormConfig` tenham efeito neste componente.
388
+ Correcao: este runtime de filtro usa apenas subset estrutural (`fieldMetadata` + `sections`).
389
+
390
+ 4. Assumir que `mode` muda regras de leitura/edicao automaticamente.
391
+ Correcao: no estado atual, `mode` e apenas declarado; regras devem ser aplicadas pelo host/metadata dos campos.
392
+
393
+ 5. Perder valores em reload de config por trocar `name` de campos.
394
+ Correcao: preserve `name` estavel para aproveitar `patchValue` entre rebuilds.
395
+
396
+ 6. Confiar apenas em `valueChange` para disparar busca sem checar validade.
397
+ Correcao: combine `valueChange` com `validityChange` para evitar chamadas invalidas.
398
+
399
+ ### 7. Referencias Cruzadas
400
+ - Runtime principal: `projects/praxis-dynamic-form/src/lib/praxis-dynamic-form.ts`
401
+ - Loader de campos: `projects/praxis-dynamic-fields/src/lib/directives/dynamic-field-loader.directive.ts`
402
+ - Contrato base de config: `projects/praxis-core/src/lib/models/form/form-config.model.ts`
403
+ - Componente de acoes de form completo: `projects/praxis-dynamic-form/src/lib/components/praxis-form-actions/praxis-form-actions.component.ts`
404
+
405
+ ### 8. Premissas
406
+ - O host e responsavel por orquestrar busca/persistencia usando os eventos emitidos.
407
+ - Os componentes de campo referenciados em `fieldMetadata` precisam estar registrados no ecossistema `dynamic-fields`.
408
+ - Regras de negocio, autorizacao e throttling de chamadas de busca devem ser aplicadas fora do componente.
409
+
410
+ ### 9. Relatorio de Validacao Estrutural
411
+ - Visao geral: PASS
412
+ - Referencia do contrato JSON (com status Active/Declared-only): PASS
413
+ - Mapeamento de comportamento real: PASS
414
+ - Exemplo minimo: PASS
415
+ - Exemplo corporativo: PASS
416
+ - Problemas comuns (>=5 itens): PASS
417
+ - Referencias cruzadas: PASS
418
+ - Premissas explicitas: PASS
419
+
420
+ ## JSON path index
421
+
422
+ | Path | Type | Required | Default | Status | Notes |
423
+ | --- | --- | --- | --- | --- | --- |
424
+ | `config.fieldMetadata[]` | `FieldMetadata[]` | Sim (na pratica) | n/a | Active | Base para criar controles e renderizar campos. |
425
+ | `config.sections[]` | `FormSection[]` | Nao | n/a | Active | Se presente, organiza render em secoes/linhas/colunas. |
426
+ | `config.sections[].rows[].columns[].fields[]` | `string[]` | Nao | n/a | Active | Mapeia quais campos de `fieldMetadata` vao em cada coluna. |
427
+ | Outros blocos de `FormConfig` (`actions`, `messages`, `behavior`, `hooks`, etc.) | varios | Nao | n/a | Declared-only | Nao possuem leitura dedicada neste componente. |
428
+
429
+ ## Events
430
+
431
+ | Event | Payload | Trigger | Stability | Notes |
432
+ | --- | --- | --- | --- | --- |
433
+ | `formReady` | `{ formGroup: FormGroup<Record<string, any>> }` | Quando o form e recriado a partir do `config`. | Partial | Preservado da documentação anterior. |
434
+ | `valueChange` | `{ formData: Record<string, any> }` | Em toda mudanca de valor do formulario. | Partial | Preservado da documentação anterior. |
435
+ | `requestSearch` | `{ formData: Record<string, any> }` | Alias seguro e preferencial para o submit do `<form>` (inclui Enter). | Active | Recomendado para evitar colisao com submit nativo do DOM em hosts Angular. |
436
+ | `submit` | `{ formData: Record<string, any> }` | No submit do `<form>` (inclui Enter). | Partial | Mantido por compatibilidade; prefira `requestSearch`. |
437
+ | `validityChange` | `boolean` | Na inicializacao e em cada `statusChanges` do form. | Partial | Preservado da documentação anterior. |
438
+
439
+ ## Styling API
440
+
441
+ | Token/Class | Scope | Purpose | Notes |
442
+ | --- | --- | --- | --- |
443
+ | see-detailed-api | component | styling/runtime | Consolidar naming canonico quando aplicavel. |
444
+
445
+ ## Editor and tooling notes
446
+
447
+ - Cobertura de editor/tooling foi separada da cobertura de runtime para evitar confusao de suporte.
448
+ - Quando nao houver evidencia direta no codigo, o status deve permanecer not yet verified.
449
+
450
+ ## Examples
451
+
452
+ ### Minimal valid
453
+
454
+ ```json
455
+ {
456
+ "config": {
457
+ "sections": [],
458
+ "fieldMetadata": [
459
+ {
460
+ "name": "term",
461
+ "label": "Busca",
462
+ "controlType": "input"
463
+ }
464
+ ]
465
+ }
466
+ }
467
+ ```
468
+
469
+ ### Typical/common
470
+
471
+ ```json
472
+ {}
473
+ ```
474
+
475
+ ### Advanced
476
+
477
+ ```json
478
+ {}
479
+ ```
480
+
481
+ ### Enterprise scenario
482
+
483
+ ```json
484
+ {}
485
+ ```
486
+
487
+ ## Known limitations and mismatches
488
+
489
+ | Path/Behavior | Observed behavior (runtime) | Desired behavior | Impact | Tracking issue | Target fix |
490
+ | --- | --- | --- | --- | --- | --- |
491
+ | coverage/mapping | Evidência textual preservada indica itens Partial/Declared-only. | Cobertura confirmada por evidência runtime + schema + editor. | Pode gerar uso de paths não totalmente ligados. | to-be-linked | next-doc-cycle |
492
+
493
+ ## Compatibility and migration notes
494
+
495
+ | Concern | Affected versions | Migration action | Deadline | Notes |
496
+ | --- | --- | --- | --- | --- |
497
+ | legacy aliases and mixed status vocabulary | pre-canonical docs | unificar para taxonomia canonica (Active/Partial/Declared-only/...) | next-doc-cycle | manter backward compatibility documentada |
498
+
499
+ ## Source references
500
+
501
+ | Source type | Path/URL | Why it is source of truth | Last verified (YYYY-MM-DD) | Notes |
502
+ | --- | --- | --- | --- | --- |
503
+ | local-file | projects/praxis-dynamic-form/src/lib/filter-form/praxis-filter-form.metadata.ts | Evidencia de implementacao e contrato. | 2026-03-05 | referencia preservada da versao anterior |
504
+ | local-file | projects/praxis-dynamic-form/src/lib/filter-form/praxis-filter-form.ts | Evidencia de implementacao e contrato. | 2026-03-05 | referencia preservada da versao anterior |
505
+ | local-file | projects/praxis-dynamic-form/src/lib/filter-form/praxis-filter-form.html | Evidencia de implementacao e contrato. | 2026-03-05 | referencia preservada da versao anterior |
506
+ | local-file | projects/praxis-core/src/lib/models/form/form-config.model.ts | Evidencia de implementacao e contrato. | 2026-03-05 | referencia preservada da versao anterior |
507
+ | local-file | projects/praxis-dynamic-fields/src/lib/directives/dynamic-field-loader.directive.ts | Evidencia de implementacao e contrato. | 2026-03-05 | referencia preservada da versao anterior |