@praxisui/dynamic-fields 9.0.65 → 9.0.67
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.
- package/README.md +6 -0
- package/ai/component-registry.json +3604 -1063
- package/docs/color-components-evolution-plan.md +369 -0
- package/docs/dynamic-fields-field-catalog.md +28 -28
- package/docs/dynamic-fields-inline-components-guide.md +1 -0
- package/docs/dynamic-fields-inline-filter-catalog.md +11 -2
- package/docs/dynamic-fields-inline-filter-runtime-contract.md +2 -0
- package/docs/dynamic-fields-inventory.md +83 -82
- package/docs/governed-color-token-selection-observation-rfc.md +38 -0
- package/fesm2022/praxisui-dynamic-fields.mjs +4244 -936
- package/package.json +4 -3
- package/src/lib/components/color-input/pdx-color-input.json-api.md +209 -171
- package/src/lib/components/color-picker/pdx-color-picker.json-api.md +273 -245
- package/src/lib/components/inline-color-label/pdx-inline-color-label.json-api.md +224 -195
- package/types/praxisui-dynamic-fields.d.ts +233 -12
|
@@ -23,7 +23,7 @@ source_of_truth:
|
|
|
23
23
|
- "projects/praxis-dynamic-fields/src/lib/base/simple-base-input.component.ts"
|
|
24
24
|
- "projects/praxis-core/src/lib/models/material-field-metadata.interface.ts"
|
|
25
25
|
source_of_truth_last_verified: "2026-03-06"
|
|
26
|
-
last_updated: "2026-
|
|
26
|
+
last_updated: "2026-09-05"
|
|
27
27
|
toc: true
|
|
28
28
|
sidebar: true
|
|
29
29
|
tags:
|
|
@@ -33,7 +33,7 @@ tags:
|
|
|
33
33
|
api_stability: "canonical"
|
|
34
34
|
schema_verified: true
|
|
35
35
|
runtime_verified: true
|
|
36
|
-
editor_coverage_verified:
|
|
36
|
+
editor_coverage_verified: true
|
|
37
37
|
runtime_scope: "public"
|
|
38
38
|
legacy_paths_present: false
|
|
39
39
|
has_known_mismatches: false
|
|
@@ -55,30 +55,32 @@ Este documento e a referencia canonica da API JSON de pdx-color-input.
|
|
|
55
55
|
|
|
56
56
|
## Purpose and scope
|
|
57
57
|
|
|
58
|
+
Paletas governadas preservam a associação entre token e cor pela projeção `materializeGovernedPaletteEntries` do Core. Cada amostra expõe nome publicado, tokenId, papel semântico e cor no tooltip; busca inclui nomes e aliases, e variantes da mesma família podem ser comparadas explicitamente. Tokens distintos não são colapsados por terem cores iguais. A seleção continua confirmando HEX imediatamente; `governedSelectionChange` expõe a identidade correspondente separadamente, sem mudar o payload. Recentes e entrada livre emitem identidade `null`, sem inferência por cor.
|
|
59
|
+
|
|
58
60
|
- O componente consome payload JSON metadata-driven e expoe comportamento runtime configuravel por contrato.
|
|
59
61
|
- Esta referencia cobre contrato publico, classificacao de paths e semantica de cobertura (runtime/schema/editor).
|
|
60
62
|
- Fora de escopo: quickstart, tutorial narrativo e notas arquiteturais que nao alteram contrato publico.
|
|
61
63
|
|
|
62
64
|
## Consulta rapida (obrigatorio)
|
|
63
65
|
|
|
64
|
-
| Regra/tema
|
|
65
|
-
|
|
|
66
|
-
| Component id
|
|
67
|
-
| Primary contract source | `runtime-and-code` | Runtime, schema e docs devem permanecer rastreaveis
|
|
68
|
-
| Runtime coverage
|
|
69
|
-
| Schema/type coverage
|
|
70
|
-
| Editor/tooling coverage | `false`
|
|
71
|
-
| Legacy paths
|
|
72
|
-
| Known mismatches
|
|
66
|
+
| Regra/tema | Observado | Canonico desejado | Status | Evidencia |
|
|
67
|
+
| ----------------------- | ------------------ | ---------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
68
|
+
| Component id | `pdx-color-input` | Manter ID canonico estavel e versionado por contrato | Active | frontmatter.component |
|
|
69
|
+
| Primary contract source | `runtime-and-code` | Runtime, schema e docs devem permanecer rastreaveis | Partial | frontmatter.contract_source + source_of_truth |
|
|
70
|
+
| Runtime coverage | `true` | Comportamentos runtime criticos devem ficar explicitamente verificados | Active | `projects/praxis-dynamic-fields/src/lib/components/color-input/color-input.metadata.ts`, `projects/praxis-dynamic-fields/src/lib/components/color-input/color-input.component.ts` |
|
|
71
|
+
| Schema/type coverage | `true` | Tipos e schema devem refletir paths publicos do contrato | Active | source_of_truth + Detailed API reference |
|
|
72
|
+
| Editor/tooling coverage | `false` | Editor/tooling deve espelhar somente contrato publico suportado | Partial | `projects/praxis-core/src/lib/metadata/field-selector-control-type.constants.ts`, `projects/praxis-dynamic-fields/src/lib/services/component-registry/component-registry.service.ts` |
|
|
73
|
+
| Legacy paths | `false` | Segregar legado de caminhos canonicos com janela de migracao | Active | frontmatter.legacy_paths_present |
|
|
74
|
+
| Known mismatches | `false` | Registrar observed vs desired de forma auditavel | Active | frontmatter.has_known_mismatches |
|
|
73
75
|
|
|
74
76
|
## Source of truth
|
|
75
77
|
|
|
76
|
-
| Source
|
|
77
|
-
|
|
|
78
|
-
| projects/praxis-dynamic-fields/src/lib/components/color-input/color-input.metadata.ts
|
|
79
|
-
| projects/praxis-dynamic-fields/src/lib/components/color-input/color-input.component.ts | runtime-code
|
|
80
|
-
| projects/praxis-dynamic-fields/src/lib/base/simple-base-input.component.ts
|
|
81
|
-
| projects/praxis-core/src/lib/models/material-field-metadata.interface.ts
|
|
78
|
+
| Source | Kind | Notes |
|
|
79
|
+
| -------------------------------------------------------------------------------------- | --------------- | ------------------------------------------------------------------- |
|
|
80
|
+
| projects/praxis-dynamic-fields/src/lib/components/color-input/color-input.metadata.ts | schema-metadata | Arquivo presente no repositorio e usado como evidencia de contrato. |
|
|
81
|
+
| projects/praxis-dynamic-fields/src/lib/components/color-input/color-input.component.ts | runtime-code | Arquivo presente no repositorio e usado como evidencia de contrato. |
|
|
82
|
+
| projects/praxis-dynamic-fields/src/lib/base/simple-base-input.component.ts | runtime-code | Arquivo presente no repositorio e usado como evidencia de contrato. |
|
|
83
|
+
| projects/praxis-core/src/lib/models/material-field-metadata.interface.ts | schema-types | Arquivo presente no repositorio e usado como evidencia de contrato. |
|
|
82
84
|
|
|
83
85
|
## Support legend
|
|
84
86
|
|
|
@@ -90,32 +92,32 @@ Este documento e a referencia canonica da API JSON de pdx-color-input.
|
|
|
90
92
|
|
|
91
93
|
## Contract status snapshot
|
|
92
94
|
|
|
93
|
-
| Item
|
|
94
|
-
|
|
|
95
|
-
| Reference mode
|
|
96
|
-
| Contract format
|
|
97
|
-
| Contract source
|
|
98
|
-
| Runtime scope
|
|
99
|
-
| Runtime verified
|
|
100
|
-
| Schema verified
|
|
101
|
-
| Editor coverage verified | `false`
|
|
102
|
-
| Legacy paths present
|
|
103
|
-
| Has known mismatches
|
|
95
|
+
| Item | Value | Notes |
|
|
96
|
+
| ------------------------ | ------------------ | ---------------------------------------------- |
|
|
97
|
+
| Reference mode | `canonical` | Deve permanecer canonico |
|
|
98
|
+
| Contract format | `json` | Contrato metadata-driven |
|
|
99
|
+
| Contract source | `runtime-and-code` | Alinhar com source_of_truth |
|
|
100
|
+
| Runtime scope | `public` | Escopo publicado para consumidores |
|
|
101
|
+
| Runtime verified | `true` | Revisar sempre com evidencia de runtime |
|
|
102
|
+
| Schema verified | `true` | Revisar sempre com evidencia de tipos/schema |
|
|
103
|
+
| Editor coverage verified | `false` | Revisar sempre com evidencia de editor/tooling |
|
|
104
|
+
| Legacy paths present | `false` | Segregar legado de contrato canonico |
|
|
105
|
+
| Has known mismatches | `false` | Divergencias devem aparecer em secao dedicada |
|
|
104
106
|
|
|
105
107
|
## Contract classification (obrigatorio)
|
|
106
108
|
|
|
107
109
|
### Canonical paths (public contract)
|
|
108
110
|
|
|
109
|
-
| Path
|
|
110
|
-
|
|
|
111
|
-
| `metadata`
|
|
112
|
-
| `readonlyMode`
|
|
113
|
-
| `disabledMode`
|
|
114
|
-
| `visible`
|
|
115
|
-
| `presentationMode`
|
|
116
|
-
| `metadata.controlType`
|
|
117
|
-
| `metadata.inputType`
|
|
118
|
-
| `metadata.palettePreset` | string
|
|
111
|
+
| Path | Type | Required | Default | Status | Notes |
|
|
112
|
+
| ------------------------ | ------- | -------- | ------- | ------- | ------------------------------------------------- |
|
|
113
|
+
| `metadata` | object | true | n/a | Partial | See Detailed API reference for runtime semantics. |
|
|
114
|
+
| `readonlyMode` | boolean | false | n/a | Partial | See Detailed API reference for runtime semantics. |
|
|
115
|
+
| `disabledMode` | boolean | false | n/a | Partial | See Detailed API reference for runtime semantics. |
|
|
116
|
+
| `visible` | boolean | false | n/a | Partial | See Detailed API reference for runtime semantics. |
|
|
117
|
+
| `presentationMode` | boolean | false | n/a | Partial | See Detailed API reference for runtime semantics. |
|
|
118
|
+
| `metadata.controlType` | string | false | n/a | Partial | See Detailed API reference for runtime semantics. |
|
|
119
|
+
| `metadata.inputType` | string | false | n/a | Partial | See Detailed API reference for runtime semantics. |
|
|
120
|
+
| `metadata.palettePreset` | string | false | n/a | Partial | See Detailed API reference for runtime semantics. |
|
|
119
121
|
|
|
120
122
|
### Supported legacy paths
|
|
121
123
|
|
|
@@ -133,73 +135,73 @@ Nao ha paths experimentais confirmados no contrato publico desta revisao.
|
|
|
133
135
|
|
|
134
136
|
### Top-level configuration blocks
|
|
135
137
|
|
|
136
|
-
| Block
|
|
137
|
-
|
|
|
138
|
-
| `metadata`
|
|
139
|
-
| `readonlyMode`
|
|
140
|
-
| `disabledMode`
|
|
141
|
-
| `visible`
|
|
142
|
-
| `presentationMode` | Renderizacao de apresentacao sem interacao
|
|
138
|
+
| Block | Purpose | Required | Merge strategy | Notes |
|
|
139
|
+
| ------------------ | ------------------------------------------- | -------- | -------------- | ---------------------------------------------------------------------- |
|
|
140
|
+
| `metadata` | Payload declarativo principal do componente | true | deep-merge | runtime linkage verified for core flows (component specs, 2026-03-06). |
|
|
141
|
+
| `readonlyMode` | Override de readonly no host/runtime | false | override | runtime linkage verified for core flows (component specs, 2026-03-06). |
|
|
142
|
+
| `disabledMode` | Override de disabled no host/runtime | false | override | runtime linkage verified for core flows (component specs, 2026-03-06). |
|
|
143
|
+
| `visible` | Override de visibilidade no host/runtime | false | override | runtime linkage verified for core flows (component specs, 2026-03-06). |
|
|
144
|
+
| `presentationMode` | Renderizacao de apresentacao sem interacao | false | override | runtime linkage verified for core flows (component specs, 2026-03-06). |
|
|
143
145
|
|
|
144
146
|
### Nested configuration blocks
|
|
145
147
|
|
|
146
|
-
| Path
|
|
147
|
-
|
|
|
148
|
-
| `metadata.controlType`
|
|
149
|
-
| `metadata.inputType`
|
|
150
|
-
| `metadata.palettePreset`
|
|
151
|
-
| `metadata.paletteColors`
|
|
152
|
-
| `metadata.columns`
|
|
153
|
-
| `metadata.popupWidth`
|
|
154
|
-
| `metadata.preview`
|
|
155
|
-
| `metadata.showRecent`
|
|
156
|
-
| `metadata.maxRecent`
|
|
157
|
-
| `metadata.showNativeOption` | boolean | false
|
|
148
|
+
| Path | Type | Required | Default | Constraints | Notes |
|
|
149
|
+
| --------------------------- | ------- | -------- | ------- | ----------------- | ------------------------------------ |
|
|
150
|
+
| `metadata.controlType` | string | false | n/a | component-defined | Partial; verify per source_of_truth. |
|
|
151
|
+
| `metadata.inputType` | string | false | n/a | component-defined | Partial; verify per source_of_truth. |
|
|
152
|
+
| `metadata.palettePreset` | string | false | n/a | component-defined | Partial; verify per source_of_truth. |
|
|
153
|
+
| `metadata.paletteColors` | array | false | n/a | component-defined | Partial; verify per source_of_truth. |
|
|
154
|
+
| `metadata.columns` | array | false | n/a | component-defined | Partial; verify per source_of_truth. |
|
|
155
|
+
| `metadata.popupWidth` | number | false | n/a | component-defined | Partial; verify per source_of_truth. |
|
|
156
|
+
| `metadata.preview` | boolean | false | n/a | component-defined | Partial; verify per source_of_truth. |
|
|
157
|
+
| `metadata.showRecent` | boolean | false | n/a | component-defined | Partial; verify per source_of_truth. |
|
|
158
|
+
| `metadata.maxRecent` | unknown | false | n/a | component-defined | Partial; verify per source_of_truth. |
|
|
159
|
+
| `metadata.showNativeOption` | boolean | false | n/a | component-defined | Partial; verify per source_of_truth. |
|
|
158
160
|
|
|
159
161
|
### Input bindings (inbound data)
|
|
160
162
|
|
|
161
|
-
| Binding/Path
|
|
162
|
-
|
|
|
163
|
-
| `metadata`
|
|
164
|
-
| `readonlyMode`
|
|
165
|
-
| `disabledMode`
|
|
166
|
-
| `visible`
|
|
167
|
-
| `presentationMode` | boolean | false
|
|
163
|
+
| Binding/Path | Type | Required | Source | Runtime normalization | Notes |
|
|
164
|
+
| ------------------ | ------- | -------- | ------------ | --------------------- | --------------------------------- |
|
|
165
|
+
| `metadata` | object | true | host-json | component-defined | Primary inbound contract payload. |
|
|
166
|
+
| `readonlyMode` | boolean | false | host-runtime | not-yet-verified | Host-level behavioral override. |
|
|
167
|
+
| `disabledMode` | boolean | false | host-runtime | not-yet-verified | Host-level behavioral override. |
|
|
168
|
+
| `visible` | boolean | false | host-runtime | not-yet-verified | Host-level behavioral override. |
|
|
169
|
+
| `presentationMode` | boolean | false | host-runtime | not-yet-verified | Host-level behavioral override. |
|
|
168
170
|
|
|
169
171
|
### Output events
|
|
170
172
|
|
|
171
|
-
| Event
|
|
172
|
-
|
|
|
173
|
+
| Event | Payload | Trigger | Stability | Notes |
|
|
174
|
+
| ------------------ | ------- | ------------- | ------------ | ----------------------------------------------- |
|
|
173
175
|
| `validationChange` | unknown | runtime-event | Experimental | Validate payload shape against source_of_truth. |
|
|
174
|
-
| `valueChange`
|
|
175
|
-
| `focusChange`
|
|
176
|
-
| `nativeBlur`
|
|
177
|
-
| `nativeChange`
|
|
176
|
+
| `valueChange` | unknown | runtime-event | Experimental | Validate payload shape against source_of_truth. |
|
|
177
|
+
| `focusChange` | unknown | runtime-event | Experimental | Validate payload shape against source_of_truth. |
|
|
178
|
+
| `nativeBlur` | unknown | runtime-event | Experimental | Validate payload shape against source_of_truth. |
|
|
179
|
+
| `nativeChange` | unknown | runtime-event | Experimental | Validate payload shape against source_of_truth. |
|
|
178
180
|
|
|
179
181
|
### External side channels
|
|
180
182
|
|
|
181
|
-
| Channel
|
|
182
|
-
|
|
|
183
|
+
| Channel | Direction | Contract | Failure mode | Notes |
|
|
184
|
+
| ----------------------- | ------------- | ----------------- | ----------------- | ------------------------------------------------------------------------- |
|
|
183
185
|
| `host/services/storage` | bidirectional | component-defined | component-defined | Side channels variam por componente e host; verificar em source_of_truth. |
|
|
184
186
|
|
|
185
187
|
### Host/runtime dependencies
|
|
186
188
|
|
|
187
|
-
| Dependency
|
|
188
|
-
|
|
|
189
|
-
| `color-input.metadata.ts`
|
|
190
|
-
| `color-input.component.ts`
|
|
191
|
-
| `simple-base-input.component.ts`
|
|
192
|
-
| `material-field-metadata.interface.ts` | true
|
|
189
|
+
| Dependency | Required | Environment | Purpose | Notes |
|
|
190
|
+
| -------------------------------------- | -------- | -------------------- | ------------------- | -------------------------------------------------------------------------------------------------- |
|
|
191
|
+
| `color-input.metadata.ts` | true | browser/dev/prod/ssr | contract resolution | Refer to `projects/praxis-dynamic-fields/src/lib/components/color-input/color-input.metadata.ts`. |
|
|
192
|
+
| `color-input.component.ts` | true | browser/dev/prod/ssr | contract resolution | Refer to `projects/praxis-dynamic-fields/src/lib/components/color-input/color-input.component.ts`. |
|
|
193
|
+
| `simple-base-input.component.ts` | true | browser/dev/prod/ssr | contract resolution | Refer to `projects/praxis-dynamic-fields/src/lib/base/simple-base-input.component.ts`. |
|
|
194
|
+
| `material-field-metadata.interface.ts` | true | browser/dev/prod/ssr | contract resolution | Refer to `projects/praxis-core/src/lib/models/material-field-metadata.interface.ts`. |
|
|
193
195
|
|
|
194
196
|
## Coverage by surface (obrigatorio)
|
|
195
197
|
|
|
196
198
|
### Coverage matrix (runtime, schema/type, editor/tooling)
|
|
197
199
|
|
|
198
|
-
| Surface
|
|
199
|
-
|
|
|
200
|
-
| Runtime
|
|
201
|
-
| Schema/Types
|
|
202
|
-
| Editor/Tooling | `false`
|
|
200
|
+
| Surface | Verified | Coverage status | Evidence | Notes |
|
|
201
|
+
| -------------- | -------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
202
|
+
| Runtime | `true` | Active | `projects/praxis-dynamic-fields/src/lib/components/color-input/color-input.metadata.ts`, `projects/praxis-dynamic-fields/src/lib/components/color-input/color-input.component.ts` | Core runtime flows verified via focused component specs on 2026-03-06; editor/tooling coverage remains independent. |
|
|
203
|
+
| Schema/Types | `true` | Active | source_of_truth + Detailed API reference | Reconcile schema/types with canonical paths during follow-up when needed. |
|
|
204
|
+
| Editor/Tooling | `false` | Partial | `projects/praxis-core/src/lib/metadata/field-selector-control-type.constants.ts`, `projects/praxis-dynamic-fields/src/lib/services/component-registry/component-registry.service.ts` | Selector/control-type tooling linkage verified via default selector map and registry seeding; visual editor end-to-end coverage remains not-yet-verified. |
|
|
203
205
|
|
|
204
206
|
### Runtime coverage boundaries
|
|
205
207
|
|
|
@@ -245,9 +247,9 @@ Em conflito entre alias legado e path canonico, priorizar path canonico e regist
|
|
|
245
247
|
|
|
246
248
|
### Validation model
|
|
247
249
|
|
|
248
|
-
| Path/Rule
|
|
249
|
-
|
|
|
250
|
-
| canonical-paths | parse/runtime
|
|
250
|
+
| Path/Rule | Validation phase | Behavior on fail | Error code / warning | Notes |
|
|
251
|
+
| --------------- | ---------------- | --------------------------------------- | -------------------- | -------------------------------------------------------------------- |
|
|
252
|
+
| canonical-paths | parse/runtime | component-defined (warn/reject/default) | not-yet-standardized | Semantica detalhada preservada na referencia tecnica por componente. |
|
|
251
253
|
|
|
252
254
|
### Invalid and unknown field handling
|
|
253
255
|
|
|
@@ -257,73 +259,84 @@ Em conflito entre alias legado e path canonico, priorizar path canonico e regist
|
|
|
257
259
|
|
|
258
260
|
### Fail-open / fail-closed behavior
|
|
259
261
|
|
|
260
|
-
| Condition
|
|
261
|
-
|
|
|
262
|
+
| Condition | Mode | Runtime behavior | Consumer impact |
|
|
263
|
+
| ------------------------ | ----------------- | ---------------- | ---------------------------------------------------------------------------- |
|
|
262
264
|
| invalid-or-unknown-field | component-defined | not-yet-verified | Pode gerar warning, fallback silencioso ou rejeicao; validar por componente. |
|
|
263
265
|
|
|
264
266
|
### Runtime warnings vs hard failures
|
|
265
267
|
|
|
266
|
-
| Condition
|
|
267
|
-
|
|
|
268
|
-
| partial-or-declared-only-coverage | warning
|
|
269
|
-
| mismatch-confirmed
|
|
268
|
+
| Condition | Severity | Observability | Consumer action |
|
|
269
|
+
| --------------------------------- | ---------------- | ----------------------------- | ----------------------------------------------- |
|
|
270
|
+
| partial-or-declared-only-coverage | warning | logs/eventos do componente | Confirmar ligacao runtime antes de uso critico. |
|
|
271
|
+
| mismatch-confirmed | error-or-warning | componente/host observability | Planejar migracao e corrigir contrato/runtime. |
|
|
270
272
|
|
|
271
273
|
## Detailed API reference
|
|
274
|
+
|
|
272
275
|
### Preserved technical reference (normalized from previous revision)
|
|
273
276
|
|
|
274
277
|
### 1. Visao Geral e Quando Usar
|
|
278
|
+
|
|
275
279
|
`pdx-color-input` e o campo de cor orientado por JSON em `@praxisui/dynamic-fields`.
|
|
276
280
|
|
|
277
281
|
Use quando precisar:
|
|
282
|
+
|
|
278
283
|
- selecao de cor via paleta popup + seletor nativo;
|
|
279
284
|
- preview visual imediato da cor selecionada;
|
|
280
285
|
- armazenamento de cores recentes no browser;
|
|
281
286
|
- integracao com formulario reativo e estados de host.
|
|
282
287
|
|
|
283
288
|
### 2. API do Componente (Inputs/Outputs)
|
|
284
|
-
|
|
285
|
-
|
|
|
286
|
-
|
|
|
287
|
-
| `
|
|
288
|
-
| `
|
|
289
|
-
| `
|
|
290
|
-
| `
|
|
291
|
-
| `
|
|
292
|
-
| `
|
|
293
|
-
| `
|
|
294
|
-
| `
|
|
295
|
-
| `
|
|
296
|
-
| `
|
|
297
|
-
| `
|
|
298
|
-
| `
|
|
299
|
-
| `
|
|
289
|
+
|
|
290
|
+
| Propriedade | Tipo | Padrao | Obrigatorio | Comportamento |
|
|
291
|
+
| ------------------ | --------------------------------------------- | ------------ | ----------- | ------------------------------------- |
|
|
292
|
+
| `metadata` | `MaterialColorInputMetadata` | - | Sim | Contrato principal do componente. |
|
|
293
|
+
| `readonlyMode` | `boolean` | `false` | Nao | Sobrescreve leitura no host. |
|
|
294
|
+
| `disabledMode` | `boolean` | `false` | Nao | Sobrescreve disabled no host. |
|
|
295
|
+
| `visible` | `boolean` | `true` | Nao | Controla exibicao no host. |
|
|
296
|
+
| `presentationMode` | `boolean` | `false` | Nao | Modo de apresentacao (sem edicao). |
|
|
297
|
+
| `palettePreset` | `'basic' \| 'office' \| 'material' \| string` | `'material'` | Nao | Preset da paleta exibida no menu. |
|
|
298
|
+
| `paletteColors` | `string[]` | `undefined` | Nao | Sobrescreve totalmente a paleta. |
|
|
299
|
+
| `columns` | `number` | `8` | Nao | Colunas de swatches no popup. |
|
|
300
|
+
| `popupWidth` | `number \| string` | `320` | Nao | Largura do popup de paleta. |
|
|
301
|
+
| `preview` | `boolean` | `true` | Nao | Exibe cabecalho com preview e valor. |
|
|
302
|
+
| `showRecent` | `boolean` | `true` | Nao | Exibe secao de cores recentes. |
|
|
303
|
+
| `maxRecent` | `number` | `12` | Nao | Quantidade maxima de recentes. |
|
|
304
|
+
| `showNativeOption` | `boolean` | `true` | Nao | Exibe seletor nativo dentro do popup. |
|
|
305
|
+
| `validationChange` | `ValidationErrors \| null` | - | Output | Emite resultado da validacao. |
|
|
306
|
+
| `governedSelectionChange` | `GovernedColorTokenSelection \| null` | - | Output | Emite a identidade do token governado ou `null` para entrada livre/local, sem alterar o valor CSS do formulario. |
|
|
300
307
|
|
|
301
308
|
### 3. Matriz de Cobertura JSON (Completa)
|
|
309
|
+
|
|
302
310
|
#### 3.1 Campos especificos do componente
|
|
303
|
-
|
|
304
|
-
|
|
|
305
|
-
|
|
|
306
|
-
| `metadata.
|
|
307
|
-
| `metadata.
|
|
308
|
-
| `metadata.
|
|
309
|
-
| `metadata.
|
|
310
|
-
| `metadata.
|
|
311
|
-
| `metadata.
|
|
312
|
-
| `metadata.
|
|
313
|
-
| `metadata.
|
|
314
|
-
| `metadata.
|
|
315
|
-
| `metadata.
|
|
311
|
+
|
|
312
|
+
| Caminho JSON | Tipo | Status | Comportamento em runtime |
|
|
313
|
+
| --------------------------- | ------------------ | ------------------- | ------------------------------------------------------------------------------------------------- |
|
|
314
|
+
| `metadata.controlType` | `'color'` | Ativo | Identifica contrato do componente. |
|
|
315
|
+
| `metadata.inputType` | `'color'` | Parcial | Interface indica `color`, mas o input principal e `type="text"`; cor e aplicada via popup/picker. |
|
|
316
|
+
| `metadata.palettePreset` | `string` | Extensao de runtime | Mapeado para `palettePreset` no componente. |
|
|
317
|
+
| `metadata.paletteColors` | `string[]` | Extensao de runtime | Mapeado para paleta customizada. |
|
|
318
|
+
| `metadata.columns` | `number` | Extensao de runtime | Define colunas da grade de swatches. |
|
|
319
|
+
| `metadata.popupWidth` | `number \| string` | Extensao de runtime | Define largura do popup. |
|
|
320
|
+
| `metadata.preview` | `boolean` | Extensao de runtime | Mostra/oculta preview superior. |
|
|
321
|
+
| `metadata.showRecent` | `boolean` | Extensao de runtime | Mostra/oculta secao de recentes. |
|
|
322
|
+
| `metadata.maxRecent` | `number` | Extensao de runtime | Limita recentes persistidos em `localStorage`. |
|
|
323
|
+
| `metadata.showNativeOption` | `boolean` | Extensao de runtime | Ativa input nativo dentro do popup. |
|
|
324
|
+
| `metadata.placeholder` | `string` | Parcial | Explicitamente removido em `setInputMetadata`; placeholder nao e aplicado no input principal. |
|
|
316
325
|
|
|
317
326
|
#### 3.2 Campos herdados compartilhados (exaustivo)
|
|
327
|
+
|
|
318
328
|
Contrato completo dos campos herdados consumidos por `SimpleBaseInput`:
|
|
329
|
+
|
|
319
330
|
- [pdx-base-input-runtime-contract.json-api.md](projects/praxis-dynamic-fields/src/lib/base/pdx-base-input-runtime-contract.json-api.md)
|
|
320
331
|
|
|
321
332
|
Resumo de composicao deste componente:
|
|
333
|
+
|
|
322
334
|
- `Ativo`: contrato herdado + paleta/picker + `validationChange`.
|
|
323
335
|
- `Parcial`: `inputType=color` apenas no contrato; render principal usa `text`.
|
|
324
336
|
- `Extensao de runtime`: `metadata.palette*`, `metadata.popupWidth`, `metadata.preview`, `metadata.showRecent`, `metadata.maxRecent`, `metadata.showNativeOption`.
|
|
325
337
|
|
|
326
338
|
### 4. Mapeamento de Comportamento
|
|
339
|
+
|
|
327
340
|
- Paginacao: nao se aplica.
|
|
328
341
|
- Ordenacao: nao se aplica.
|
|
329
342
|
- Selecao: valor string de cor (preferencialmente hex).
|
|
@@ -331,6 +344,7 @@ Resumo de composicao deste componente:
|
|
|
331
344
|
- Renderizacao: preview de cor + menu de swatches + picker nativo + clear opcional.
|
|
332
345
|
|
|
333
346
|
### 5. Exemplo Minimo (JSON + Uso)
|
|
347
|
+
|
|
334
348
|
```json
|
|
335
349
|
{
|
|
336
350
|
"componentId": "pdx-color-input",
|
|
@@ -342,9 +356,11 @@ Resumo de composicao deste componente:
|
|
|
342
356
|
}
|
|
343
357
|
}
|
|
344
358
|
```
|
|
359
|
+
|
|
345
360
|
Uso: abre paleta para selecionar cor e grava valor no controle do formulario.
|
|
346
361
|
|
|
347
362
|
### 6. Exemplo Corporativo (JSON + Uso)
|
|
363
|
+
|
|
348
364
|
```json
|
|
349
365
|
{
|
|
350
366
|
"componentId": "pdx-color-input",
|
|
@@ -370,30 +386,34 @@ Uso: abre paleta para selecionar cor e grava valor no controle do formulario.
|
|
|
370
386
|
"visible": true
|
|
371
387
|
}
|
|
372
388
|
```
|
|
389
|
+
|
|
373
390
|
Uso: selecao corporativa de cores com preset consistente e historico local por usuario.
|
|
374
391
|
|
|
375
392
|
### 7. Troubleshooting e Armadilhas Comuns
|
|
393
|
+
|
|
376
394
|
1. Placeholder nao aparece no input de cor.
|
|
377
|
-
Correcao: comportamento esperado; componente ignora placeholder no `setInputMetadata`.
|
|
395
|
+
Correcao: comportamento esperado; componente ignora placeholder no `setInputMetadata`.
|
|
378
396
|
|
|
379
397
|
2. Cor digitada nao normaliza automaticamente para hex.
|
|
380
|
-
Correcao: preferir selecao por swatch/picker nativo para garantir normalizacao.
|
|
398
|
+
Correcao: preferir selecao por swatch/picker nativo para garantir normalizacao.
|
|
381
399
|
|
|
382
400
|
3. Cores recentes nao persistem.
|
|
383
|
-
Correcao: verificar restricoes de `localStorage` no browser/politica corporativa.
|
|
401
|
+
Correcao: verificar restricoes de `localStorage` no browser/politica corporativa.
|
|
384
402
|
|
|
385
403
|
4. Valor de `inputType` esperado como `color` no DOM principal.
|
|
386
|
-
Correcao: neste componente o input principal e textual; o picker de cor e complementar.
|
|
404
|
+
Correcao: neste componente o input principal e textual; o picker de cor e complementar.
|
|
387
405
|
|
|
388
406
|
5. Paleta corporativa precisa ser fixa por dominio.
|
|
389
|
-
Correcao: enviar `metadata.paletteColors` com lista controlada pelo backend.
|
|
407
|
+
Correcao: enviar `metadata.paletteColors` com lista controlada pelo backend.
|
|
390
408
|
|
|
391
409
|
### 8. Cross-links
|
|
410
|
+
|
|
392
411
|
- `projects/praxis-dynamic-fields/src/lib/base/pdx-base-input-runtime-contract.json-api.md`
|
|
393
412
|
- `projects/praxis-dynamic-fields/src/lib/components/color-picker/pdx-color-picker.metadata.ts`
|
|
394
413
|
- `projects/praxis-dynamic-fields/src/lib/components/material-colorpicker/material-colorpicker.metadata.ts`
|
|
395
414
|
|
|
396
415
|
### 9. Relatorio de Validacao Estrutural
|
|
416
|
+
|
|
397
417
|
- Visao geral: PASS
|
|
398
418
|
- API (inputs/outputs): PASS
|
|
399
419
|
- Cobertura JSON completa (especifico + herdado): PASS
|
|
@@ -404,50 +424,50 @@ Correcao: enviar `metadata.paletteColors` com lista controlada pelo backend.
|
|
|
404
424
|
|
|
405
425
|
## JSON path index (obrigatorio)
|
|
406
426
|
|
|
407
|
-
| Path
|
|
408
|
-
|
|
|
409
|
-
| `metadata`
|
|
410
|
-
| `readonlyMode`
|
|
411
|
-
| `disabledMode`
|
|
412
|
-
| `visible`
|
|
413
|
-
| `presentationMode`
|
|
414
|
-
| `metadata.controlType`
|
|
415
|
-
| `metadata.inputType`
|
|
416
|
-
| `metadata.palettePreset`
|
|
417
|
-
| `metadata.paletteColors`
|
|
418
|
-
| `metadata.columns`
|
|
419
|
-
| `metadata.popupWidth`
|
|
420
|
-
| `metadata.preview`
|
|
421
|
-
| `metadata.showRecent`
|
|
422
|
-
| `metadata.maxRecent`
|
|
423
|
-
| `metadata.showNativeOption` | boolean | false
|
|
424
|
-
| `metadata.placeholder`
|
|
425
|
-
| `metadata.palette*`
|
|
427
|
+
| Path | Type | Required | Default | Status | Notes |
|
|
428
|
+
| --------------------------- | ------- | -------- | ------- | ------- | --------------------------- |
|
|
429
|
+
| `metadata` | object | true | n/a | Partial | See Detailed API reference. |
|
|
430
|
+
| `readonlyMode` | boolean | false | n/a | Partial | See Detailed API reference. |
|
|
431
|
+
| `disabledMode` | boolean | false | n/a | Partial | See Detailed API reference. |
|
|
432
|
+
| `visible` | boolean | false | n/a | Partial | See Detailed API reference. |
|
|
433
|
+
| `presentationMode` | boolean | false | n/a | Partial | See Detailed API reference. |
|
|
434
|
+
| `metadata.controlType` | string | false | n/a | Partial | See Detailed API reference. |
|
|
435
|
+
| `metadata.inputType` | string | false | n/a | Partial | See Detailed API reference. |
|
|
436
|
+
| `metadata.palettePreset` | string | false | n/a | Partial | See Detailed API reference. |
|
|
437
|
+
| `metadata.paletteColors` | array | false | n/a | Partial | See Detailed API reference. |
|
|
438
|
+
| `metadata.columns` | array | false | n/a | Partial | See Detailed API reference. |
|
|
439
|
+
| `metadata.popupWidth` | number | false | n/a | Partial | See Detailed API reference. |
|
|
440
|
+
| `metadata.preview` | boolean | false | n/a | Partial | See Detailed API reference. |
|
|
441
|
+
| `metadata.showRecent` | boolean | false | n/a | Partial | See Detailed API reference. |
|
|
442
|
+
| `metadata.maxRecent` | unknown | false | n/a | Partial | See Detailed API reference. |
|
|
443
|
+
| `metadata.showNativeOption` | boolean | false | n/a | Partial | See Detailed API reference. |
|
|
444
|
+
| `metadata.placeholder` | string | false | n/a | Partial | See Detailed API reference. |
|
|
445
|
+
| `metadata.palette*` | unknown | false | n/a | Partial | See Detailed API reference. |
|
|
426
446
|
|
|
427
447
|
## Events reference (obrigatorio)
|
|
428
448
|
|
|
429
|
-
| Event
|
|
430
|
-
|
|
|
449
|
+
| Event | Payload | Trigger | Stability | Notes |
|
|
450
|
+
| ------------------ | ------- | ------------- | ------------ | --------------------------------------- |
|
|
431
451
|
| `validationChange` | unknown | runtime-event | Experimental | Check component/runtime implementation. |
|
|
432
|
-
| `valueChange`
|
|
433
|
-
| `focusChange`
|
|
434
|
-
| `nativeBlur`
|
|
435
|
-
| `nativeChange`
|
|
452
|
+
| `valueChange` | unknown | runtime-event | Experimental | Check component/runtime implementation. |
|
|
453
|
+
| `focusChange` | unknown | runtime-event | Experimental | Check component/runtime implementation. |
|
|
454
|
+
| `nativeBlur` | unknown | runtime-event | Experimental | Check component/runtime implementation. |
|
|
455
|
+
| `nativeChange` | unknown | runtime-event | Experimental | Check component/runtime implementation. |
|
|
436
456
|
|
|
437
457
|
## Styling API (obrigatorio quando aplicavel)
|
|
438
458
|
|
|
439
|
-
| Token/Class
|
|
440
|
-
|
|
|
459
|
+
| Token/Class | Scope | Purpose | Notes |
|
|
460
|
+
| ------------------------ | --------- | ------------------------- | ---------------------------------------- |
|
|
441
461
|
| `metadata.paletteColors` | component | Styling-related JSON path | Validate against runtime implementation. |
|
|
442
462
|
|
|
443
463
|
## Examples (obrigatorio)
|
|
444
464
|
|
|
445
|
-
| Example
|
|
446
|
-
|
|
|
447
|
-
| `Minimal valid`
|
|
448
|
-
| `Common setup`
|
|
449
|
-
| `Advanced setup`
|
|
450
|
-
| `Enterprise scenario` | governance/legacy/migration context | auditability and compatibility boundaries | Include tenant-specific constraints when applicable.
|
|
465
|
+
| Example | Scenario | Validates | Notes |
|
|
466
|
+
| --------------------- | ----------------------------------- | ----------------------------------------- | ------------------------------------------------------------ |
|
|
467
|
+
| `Minimal valid` | baseline payload | required contract blocks | Extracted from preserved technical reference when available. |
|
|
468
|
+
| `Common setup` | common component usage | standard runtime behavior | Validate against host integration path. |
|
|
469
|
+
| `Advanced setup` | richer config with overrides | precedence and normalization | Requires runtime confirmation for edge cases. |
|
|
470
|
+
| `Enterprise scenario` | governance/legacy/migration context | auditability and compatibility boundaries | Include tenant-specific constraints when applicable. |
|
|
451
471
|
|
|
452
472
|
### Minimal valid
|
|
453
473
|
|
|
@@ -553,21 +573,39 @@ Correcao: enviar `metadata.paletteColors` com lista controlada pelo backend.
|
|
|
553
573
|
|
|
554
574
|
## Compatibility and migration notes (recomendado)
|
|
555
575
|
|
|
556
|
-
|
|
557
|
-
|
|
558
|
-
|
|
576
|
+
### Paleta governada
|
|
577
|
+
|
|
578
|
+
`metadata.governedPaletteRef` resolve tokens publicados pelo Praxis Config e prevalece sobre `metadata.paletteColors`. A referência aceita `paletteKey`, `version`, `etag` e `purposes`; o valor escolhido continua sendo a referência CSS/fallback materializada pelo contrato publicado. O editor visual expõe tanto a paleta local estruturada quanto a referência governada.
|
|
579
|
+
|
|
580
|
+
Quando a referência governada está ativa, a paleta oferece busca local por `displayName`, `aliases`, `tokenId`, `semanticRole`, `purposes` e valor CSS, com comparação sem diferença de caixa ou acentos. Os resultados são organizados visualmente por `semanticRole`; essa organização não cria grupos nem regras de negócio. Paletas publicadas com a mesma `familyKey` aparecem como variantes explícitas, sem inferência por tema ou nome. A busca é limpa a cada abertura, cores locais não recebem identidade inferida e uma pesquisa sem correspondência apresenta estado vazio explícito.
|
|
581
|
+
|
|
582
|
+
O cabeçalho da paleta identifica `displayName`, variante, `version` e a contagem filtrada/total; o ETag fica disponível como contexto técnico no tooltip. A faixa de variantes, busca e contexto permanecem fora da região rolável de resultados. Nomes, aliases e família são consumidos exclusivamente da projeção publicada pelo Praxis Config.
|
|
583
|
+
|
|
584
|
+
```json
|
|
585
|
+
{
|
|
586
|
+
"governedPaletteRef": {
|
|
587
|
+
"paletteKey": "praxis.corporate.main",
|
|
588
|
+
"version": 4,
|
|
589
|
+
"purposes": ["fill"]
|
|
590
|
+
}
|
|
591
|
+
}
|
|
592
|
+
```
|
|
593
|
+
|
|
594
|
+
| Concern | Affected versions | Migration action | Deadline | Notes |
|
|
595
|
+
| ------------------------------------------- | ----------------- | ------------------------------------------------ | -------- | ----------------------------------------------------- |
|
|
596
|
+
| No legacy path detected in current revision | n/a | No migration action required for canonical paths | n/a | Re-evaluate if backward-compat aliases are introduced |
|
|
559
597
|
|
|
560
598
|
## Known limitations and mismatches (recomendado)
|
|
561
599
|
|
|
562
|
-
| Path/Behavior
|
|
563
|
-
|
|
|
564
|
-
| Canonical contract parity | No confirmed mismatch in this revision; runtime linkage verified for core flows (2026-03-06), with editor/tooling coverage pending | Keep runtime/schema/editor alignment evidence updated | Low
|
|
600
|
+
| Path/Behavior | Observed behavior (runtime) | Desired behavior | Impact | Tracking issue | Target fix |
|
|
601
|
+
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | ------ | -------------- | ------------------------- |
|
|
602
|
+
| Canonical contract parity | No confirmed mismatch in this revision; runtime linkage verified for core flows (2026-03-06), with editor/tooling coverage pending | Keep runtime/schema/editor alignment evidence updated | Low | n/a | Monitor in periodic audit |
|
|
565
603
|
|
|
566
604
|
## Source references (obrigatorio)
|
|
567
605
|
|
|
568
|
-
| Source type
|
|
569
|
-
|
|
|
570
|
-
| schema-metadata | projects/praxis-dynamic-fields/src/lib/components/color-input/color-input.metadata.ts
|
|
571
|
-
| runtime-code
|
|
572
|
-
| runtime-code
|
|
573
|
-
| schema-types
|
|
606
|
+
| Source type | Path/URL | Why it is source of truth | Last verified (YYYY-MM-DD) | Notes |
|
|
607
|
+
| --------------- | -------------------------------------------------------------------------------------- | -------------------------------------------------- | -------------------------- | ------------- |
|
|
608
|
+
| schema-metadata | projects/praxis-dynamic-fields/src/lib/components/color-input/color-input.metadata.ts | Primary source of truth for contract and behavior. | 2026-03-06 | verified-path |
|
|
609
|
+
| runtime-code | projects/praxis-dynamic-fields/src/lib/components/color-input/color-input.component.ts | Primary source of truth for contract and behavior. | 2026-03-06 | verified-path |
|
|
610
|
+
| runtime-code | projects/praxis-dynamic-fields/src/lib/base/simple-base-input.component.ts | Primary source of truth for contract and behavior. | 2026-03-06 | verified-path |
|
|
611
|
+
| schema-types | projects/praxis-core/src/lib/models/material-field-metadata.interface.ts | Primary source of truth for contract and behavior. | 2026-03-06 | verified-path |
|