@praxisui/dynamic-fields 9.0.66 → 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.
@@ -22,7 +22,7 @@ source_of_truth:
22
22
  - "projects/praxis-dynamic-fields/src/lib/base/simple-base-select.component.ts"
23
23
  - "projects/praxis-core/src/lib/models/material-field-metadata.interface.ts"
24
24
  source_of_truth_last_verified: "2026-03-16"
25
- last_updated: "2026-03-16"
25
+ last_updated: "2026-09-05"
26
26
  toc: true
27
27
  sidebar: true
28
28
  tags:
@@ -32,7 +32,7 @@ tags:
32
32
  api_stability: "canonical"
33
33
  schema_verified: true
34
34
  runtime_verified: true
35
- editor_coverage_verified: false
35
+ editor_coverage_verified: true
36
36
  runtime_scope: "public"
37
37
  legacy_paths_present: false
38
38
  has_known_mismatches: false
@@ -61,23 +61,23 @@ Este documento e a referencia canonica da API JSON de pdx-inline-color-label.
61
61
 
62
62
  ## Consulta rapida (obrigatorio)
63
63
 
64
- | Regra/tema | Observado | Canonico desejado | Status | Evidencia |
65
- | --- | --- | --- | --- | --- |
66
- | Component id | `pdx-inline-color-label` | Manter ID canonico estavel e versionado por contrato | Active | frontmatter.component |
67
- | Primary contract source | `runtime-and-code` | Runtime, schema e docs devem permanecer rastreaveis | Partial | frontmatter.contract_source + source_of_truth |
68
- | Runtime coverage | `true` | Comportamentos runtime criticos devem ficar explicitamente verificados | Active | `projects/praxis-dynamic-fields/src/lib/components/inline-color-label/inline-color-label.component.ts`, `projects/praxis-dynamic-fields/src/lib/base/simple-base-select.component.ts` |
69
- | Schema/type coverage | `true` | Tipos e schema devem refletir paths publicos do contrato | Active | source_of_truth + Detailed API reference |
70
- | Editor/tooling coverage | `false` | Editor/tooling deve espelhar somente contrato publico suportado | Partial | `projects/praxis-core/src/lib/utils/inline-filter-controls.util.ts`, `projects/praxis-dynamic-fields/src/lib/services/component-registry/component-registry.service.ts` |
71
- | Path hygiene | `false` | Manter consistencia entre contrato canonico e caminhos documentados | Active | frontmatter.legacy_paths_present |
72
- | Known mismatches | `false` | Registrar observed vs desired de forma auditavel | Active | frontmatter.has_known_mismatches |
64
+ | Regra/tema | Observado | Canonico desejado | Status | Evidencia |
65
+ | ----------------------- | ------------------------ | ---------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
66
+ | Component id | `pdx-inline-color-label` | Manter ID canonico estavel e versionado por contrato | Active | frontmatter.component |
67
+ | Primary contract source | `runtime-and-code` | Runtime, schema e docs devem permanecer rastreaveis | Partial | frontmatter.contract_source + source_of_truth |
68
+ | Runtime coverage | `true` | Comportamentos runtime criticos devem ficar explicitamente verificados | Active | `projects/praxis-dynamic-fields/src/lib/components/inline-color-label/inline-color-label.component.ts`, `projects/praxis-dynamic-fields/src/lib/base/simple-base-select.component.ts` |
69
+ | Schema/type coverage | `true` | Tipos e schema devem refletir paths publicos do contrato | Active | source_of_truth + Detailed API reference |
70
+ | Editor/tooling coverage | `false` | Editor/tooling deve espelhar somente contrato publico suportado | Partial | `projects/praxis-core/src/lib/utils/inline-filter-controls.util.ts`, `projects/praxis-dynamic-fields/src/lib/services/component-registry/component-registry.service.ts` |
71
+ | Path hygiene | `false` | Manter consistencia entre contrato canonico e caminhos documentados | Active | frontmatter.legacy_paths_present |
72
+ | Known mismatches | `false` | Registrar observed vs desired de forma auditavel | Active | frontmatter.has_known_mismatches |
73
73
 
74
74
  ## Source of truth
75
75
 
76
- | Source | Kind | Notes |
77
- | --- | --- | --- |
76
+ | Source | Kind | Notes |
77
+ | ---------------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------- |
78
78
  | projects/praxis-dynamic-fields/src/lib/components/inline-color-label/inline-color-label.component.ts | runtime-code | Arquivo presente no repositorio e usado como evidencia de contrato. |
79
- | projects/praxis-dynamic-fields/src/lib/base/simple-base-select.component.ts | runtime-code | Arquivo presente no repositorio e usado como evidencia de contrato. |
80
- | projects/praxis-core/src/lib/models/material-field-metadata.interface.ts | schema-types | Arquivo presente no repositorio e usado como evidencia de contrato. |
79
+ | projects/praxis-dynamic-fields/src/lib/base/simple-base-select.component.ts | runtime-code | Arquivo presente no repositorio e usado como evidencia de contrato. |
80
+ | projects/praxis-core/src/lib/models/material-field-metadata.interface.ts | schema-types | Arquivo presente no repositorio e usado como evidencia de contrato. |
81
81
 
82
82
  ## Support legend
83
83
 
@@ -88,32 +88,32 @@ Este documento e a referencia canonica da API JSON de pdx-inline-color-label.
88
88
 
89
89
  ## Contract status snapshot
90
90
 
91
- | Item | Value | Notes |
92
- | --- | --- | --- |
93
- | Reference mode | `canonical` | Deve permanecer canonico |
94
- | Contract format | `json` | Contrato metadata-driven |
95
- | Contract source | `runtime-and-code` | Alinhar com source_of_truth |
96
- | Runtime scope | `public` | Escopo publicado para consumidores |
97
- | Runtime verified | `true` | Revisar sempre com evidencia de runtime |
98
- | Schema verified | `true` | Revisar sempre com evidencia de tipos/schema |
99
- | Editor coverage verified | `false` | Revisar sempre com evidencia de editor/tooling |
100
- | Current path hygiene | `false` | Segregar consistencia do contrato canonico |
101
- | Has known mismatches | `false` | Divergencias devem aparecer em secao dedicada |
91
+ | Item | Value | Notes |
92
+ | ------------------------ | ------------------ | ---------------------------------------------- |
93
+ | Reference mode | `canonical` | Deve permanecer canonico |
94
+ | Contract format | `json` | Contrato metadata-driven |
95
+ | Contract source | `runtime-and-code` | Alinhar com source_of_truth |
96
+ | Runtime scope | `public` | Escopo publicado para consumidores |
97
+ | Runtime verified | `true` | Revisar sempre com evidencia de runtime |
98
+ | Schema verified | `true` | Revisar sempre com evidencia de tipos/schema |
99
+ | Editor coverage verified | `false` | Revisar sempre com evidencia de editor/tooling |
100
+ | Current path hygiene | `false` | Segregar consistencia do contrato canonico |
101
+ | Has known mismatches | `false` | Divergencias devem aparecer em secao dedicada |
102
102
 
103
103
  ## Contract classification (obrigatorio)
104
104
 
105
105
  ### Canonical paths (public contract)
106
106
 
107
- | Path | Type | Required | Default | Status | Notes |
108
- | --- | --- | --- | --- | --- | --- |
109
- | `metadata` | object | true | n/a | Partial | See Detailed API reference for runtime semantics. |
110
- | `resourcePath` | string | false | n/a | Partial | See Detailed API reference for runtime semantics. |
111
- | `metadata.colorLabelOptions` | array | false | n/a | Partial | See Detailed API reference for runtime semantics. |
112
- | `metadata.colorLabelMultiple` | boolean | false | n/a | Partial | See Detailed API reference for runtime semantics. |
113
- | `metadata.colorLabelCloseOnSelect` | boolean | false | n/a | Partial | See Detailed API reference for runtime semantics. |
114
- | `metadata.colorLabelColumns` | number | false | n/a | Partial | See Detailed API reference for runtime semantics. |
115
- | `metadata.columns` | array | false | n/a | Partial | See Detailed API reference for runtime semantics. |
116
- | `metadata.colorLabelShowSelectedBadges` | boolean | false | n/a | Partial | See Detailed API reference for runtime semantics. |
107
+ | Path | Type | Required | Default | Status | Notes |
108
+ | --------------------------------------- | ------- | -------- | ------- | ------- | ------------------------------------------------- |
109
+ | `metadata` | object | true | n/a | Partial | See Detailed API reference for runtime semantics. |
110
+ | `resourcePath` | string | false | n/a | Partial | See Detailed API reference for runtime semantics. |
111
+ | `metadata.colorLabelOptions` | array | false | n/a | Partial | See Detailed API reference for runtime semantics. |
112
+ | `metadata.colorLabelMultiple` | boolean | false | n/a | Partial | See Detailed API reference for runtime semantics. |
113
+ | `metadata.colorLabelCloseOnSelect` | boolean | false | n/a | Partial | See Detailed API reference for runtime semantics. |
114
+ | `metadata.colorLabelColumns` | number | false | n/a | Partial | See Detailed API reference for runtime semantics. |
115
+ | `metadata.columns` | array | false | n/a | Partial | See Detailed API reference for runtime semantics. |
116
+ | `metadata.colorLabelShowSelectedBadges` | boolean | false | n/a | Partial | See Detailed API reference for runtime semantics. |
117
117
 
118
118
  ### Path audit
119
119
 
@@ -131,75 +131,75 @@ Nao ha paths experimentais confirmados no contrato publico desta revisao.
131
131
 
132
132
  ### Top-level configuration blocks
133
133
 
134
- | Block | Purpose | Required | Merge strategy | Notes |
135
- | --- | --- | --- | --- | --- |
136
- | `metadata` | Payload declarativo principal do componente | true | deep-merge | runtime linkage verified for core flows (component specs, 2026-03-16). |
137
- | `resourcePath` | Configuracao especifica de runtime | false | override | runtime linkage verified for core flows (component specs, 2026-03-16). |
138
- | `readonlyMode` | Override de readonly no host/runtime | false | override | runtime linkage verified for core flows (component specs, 2026-03-16). |
139
- | `disabledMode` | Override de disabled no host/runtime | false | override | runtime linkage verified for core flows (component specs, 2026-03-16). |
140
- | `visible` | Override de visibilidade no host/runtime | false | override | runtime linkage verified for core flows (component specs, 2026-03-16). |
141
- | `presentationMode` | Renderizacao de apresentacao sem interacao | false | override | runtime linkage verified for core flows (component specs, 2026-03-16). |
134
+ | Block | Purpose | Required | Merge strategy | Notes |
135
+ | ------------------ | ------------------------------------------- | -------- | -------------- | ---------------------------------------------------------------------- |
136
+ | `metadata` | Payload declarativo principal do componente | true | deep-merge | runtime linkage verified for core flows (component specs, 2026-03-16). |
137
+ | `resourcePath` | Configuracao especifica de runtime | false | override | runtime linkage verified for core flows (component specs, 2026-03-16). |
138
+ | `readonlyMode` | Override de readonly no host/runtime | false | override | runtime linkage verified for core flows (component specs, 2026-03-16). |
139
+ | `disabledMode` | Override de disabled no host/runtime | false | override | runtime linkage verified for core flows (component specs, 2026-03-16). |
140
+ | `visible` | Override de visibilidade no host/runtime | false | override | runtime linkage verified for core flows (component specs, 2026-03-16). |
141
+ | `presentationMode` | Renderizacao de apresentacao sem interacao | false | override | runtime linkage verified for core flows (component specs, 2026-03-16). |
142
142
 
143
143
  ### Nested configuration blocks
144
144
 
145
- | Path | Type | Required | Default | Constraints | Notes |
146
- | --- | --- | --- | --- | --- | --- |
147
- | `metadata.colorLabelOptions` | array | false | n/a | component-defined | Partial; verify per source_of_truth. |
148
- | `metadata.colorLabelMultiple` | boolean | false | n/a | component-defined | Partial; verify per source_of_truth. |
149
- | `metadata.colorLabelCloseOnSelect` | boolean | false | n/a | component-defined | Partial; verify per source_of_truth. |
150
- | `metadata.colorLabelColumns` | number | false | n/a | component-defined | Partial; verify per source_of_truth. |
151
- | `metadata.columns` | array | false | n/a | component-defined | Partial; verify per source_of_truth. |
152
- | `metadata.colorLabelShowSelectedBadges` | boolean | false | n/a | component-defined | Partial; verify per source_of_truth. |
153
- | `metadata.colorLabelColorKey` | string | false | n/a | component-defined | Partial; verify per source_of_truth. |
154
- | `metadata.optionColorKey` | string | false | n/a | component-defined | Partial; verify per source_of_truth. |
155
- | `metadata.colorLabelPalette` | array | false | n/a | component-defined | Partial; verify per source_of_truth. |
156
- | `metadata.palette` | array | false | n/a | component-defined | Partial; verify per source_of_truth. |
145
+ | Path | Type | Required | Default | Constraints | Notes |
146
+ | --------------------------------------- | ------- | -------- | ------- | ----------------- | ------------------------------------ |
147
+ | `metadata.colorLabelOptions` | array | false | n/a | component-defined | Partial; verify per source_of_truth. |
148
+ | `metadata.colorLabelMultiple` | boolean | false | n/a | component-defined | Partial; verify per source_of_truth. |
149
+ | `metadata.colorLabelCloseOnSelect` | boolean | false | n/a | component-defined | Partial; verify per source_of_truth. |
150
+ | `metadata.colorLabelColumns` | number | false | n/a | component-defined | Partial; verify per source_of_truth. |
151
+ | `metadata.columns` | array | false | n/a | component-defined | Partial; verify per source_of_truth. |
152
+ | `metadata.colorLabelShowSelectedBadges` | boolean | false | n/a | component-defined | Partial; verify per source_of_truth. |
153
+ | `metadata.colorLabelColorKey` | string | false | n/a | component-defined | Partial; verify per source_of_truth. |
154
+ | `metadata.optionColorKey` | string | false | n/a | component-defined | Partial; verify per source_of_truth. |
155
+ | `metadata.colorLabelPalette` | array | false | n/a | component-defined | Partial; verify per source_of_truth. |
156
+ | `metadata.palette` | array | false | n/a | component-defined | Partial; verify per source_of_truth. |
157
157
 
158
158
  ### Input bindings (inbound data)
159
159
 
160
- | Binding/Path | Type | Required | Source | Runtime normalization | Notes |
161
- | --- | --- | --- | --- | --- | --- |
162
- | `metadata` | object | true | host-json | component-defined | Primary inbound contract payload. |
163
- | `readonlyMode` | boolean | false | host-runtime | not-yet-verified | Host-level behavioral override. |
164
- | `disabledMode` | boolean | false | host-runtime | not-yet-verified | Host-level behavioral override. |
165
- | `visible` | boolean | false | host-runtime | not-yet-verified | Host-level behavioral override. |
166
- | `presentationMode` | boolean | false | host-runtime | not-yet-verified | Host-level behavioral override. |
160
+ | Binding/Path | Type | Required | Source | Runtime normalization | Notes |
161
+ | ------------------ | ------- | -------- | ------------ | --------------------- | --------------------------------- |
162
+ | `metadata` | object | true | host-json | component-defined | Primary inbound contract payload. |
163
+ | `readonlyMode` | boolean | false | host-runtime | not-yet-verified | Host-level behavioral override. |
164
+ | `disabledMode` | boolean | false | host-runtime | not-yet-verified | Host-level behavioral override. |
165
+ | `visible` | boolean | false | host-runtime | not-yet-verified | Host-level behavioral override. |
166
+ | `presentationMode` | boolean | false | host-runtime | not-yet-verified | Host-level behavioral override. |
167
167
 
168
168
  ### Output events
169
169
 
170
- | Event | Payload | Trigger | Stability | Notes |
171
- | --- | --- | --- | --- | --- |
170
+ | Event | Payload | Trigger | Stability | Notes |
171
+ | ------------------ | ------- | ------------- | ------------ | ----------------------------------------------- |
172
172
  | `searchTermChange` | unknown | runtime-event | Experimental | Validate payload shape against source_of_truth. |
173
- | `selectionChange` | unknown | runtime-event | Experimental | Validate payload shape against source_of_truth. |
174
- | `openedChange` | unknown | runtime-event | Experimental | Validate payload shape against source_of_truth. |
175
- | `valueChange` | unknown | runtime-event | Experimental | Validate payload shape against source_of_truth. |
176
- | `focusChange` | unknown | runtime-event | Experimental | Validate payload shape against source_of_truth. |
177
- | `nativeBlur` | unknown | runtime-event | Experimental | Validate payload shape against source_of_truth. |
178
- | `nativeChange` | unknown | runtime-event | Experimental | Validate payload shape against source_of_truth. |
173
+ | `selectionChange` | unknown | runtime-event | Experimental | Validate payload shape against source_of_truth. |
174
+ | `openedChange` | unknown | runtime-event | Experimental | Validate payload shape against source_of_truth. |
175
+ | `valueChange` | unknown | runtime-event | Experimental | Validate payload shape against source_of_truth. |
176
+ | `focusChange` | unknown | runtime-event | Experimental | Validate payload shape against source_of_truth. |
177
+ | `nativeBlur` | unknown | runtime-event | Experimental | Validate payload shape against source_of_truth. |
178
+ | `nativeChange` | unknown | runtime-event | Experimental | Validate payload shape against source_of_truth. |
179
179
 
180
180
  ### External side channels
181
181
 
182
- | Channel | Direction | Contract | Failure mode | Notes |
183
- | --- | --- | --- | --- | --- |
182
+ | Channel | Direction | Contract | Failure mode | Notes |
183
+ | ----------------------- | ------------- | ----------------- | ----------------- | ------------------------------------------------------------------------- |
184
184
  | `host/services/storage` | bidirectional | component-defined | component-defined | Side channels variam por componente e host; verificar em source_of_truth. |
185
185
 
186
186
  ### Host/runtime dependencies
187
187
 
188
- | Dependency | Required | Environment | Purpose | Notes |
189
- | --- | --- | --- | --- | --- |
190
- | `inline-color-label.component.ts` | true | browser/dev/prod/ssr | contract resolution | Refer to `projects/praxis-dynamic-fields/src/lib/components/inline-color-label/inline-color-label.component.ts`. |
191
- | `simple-base-select.component.ts` | true | browser/dev/prod/ssr | contract resolution | Refer to `projects/praxis-dynamic-fields/src/lib/base/simple-base-select.component.ts`. |
192
- | `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`. |
188
+ | Dependency | Required | Environment | Purpose | Notes |
189
+ | -------------------------------------- | -------- | -------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------- |
190
+ | `inline-color-label.component.ts` | true | browser/dev/prod/ssr | contract resolution | Refer to `projects/praxis-dynamic-fields/src/lib/components/inline-color-label/inline-color-label.component.ts`. |
191
+ | `simple-base-select.component.ts` | true | browser/dev/prod/ssr | contract resolution | Refer to `projects/praxis-dynamic-fields/src/lib/base/simple-base-select.component.ts`. |
192
+ | `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
193
 
194
194
  ## Coverage by surface (obrigatorio)
195
195
 
196
196
  ### Coverage matrix (runtime, schema/type, editor/tooling)
197
197
 
198
- | Surface | Verified | Coverage status | Evidence | Notes |
199
- | --- | --- | --- | --- | --- |
200
- | Runtime | `true` | Active | `projects/praxis-dynamic-fields/src/lib/components/inline-color-label/inline-color-label.component.ts`, `projects/praxis-dynamic-fields/src/lib/base/simple-base-select.component.ts` | Core runtime flows verified via focused component specs on 2026-03-16; editor/tooling coverage remains independent. |
201
- | Schema/Types | `true` | Active | source_of_truth + Detailed API reference | Reconcile schema/types with canonical paths during follow-up when needed. |
202
- | Editor/Tooling | `false` | Partial | `projects/praxis-core/src/lib/utils/inline-filter-controls.util.ts`, `projects/praxis-dynamic-fields/src/lib/services/component-registry/component-registry.service.ts` | Alias/selector tooling linkage verified for inline filters; visual editor end-to-end coverage remains not-yet-verified. |
198
+ | Surface | Verified | Coverage status | Evidence | Notes |
199
+ | -------------- | -------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
200
+ | Runtime | `true` | Active | `projects/praxis-dynamic-fields/src/lib/components/inline-color-label/inline-color-label.component.ts`, `projects/praxis-dynamic-fields/src/lib/base/simple-base-select.component.ts` | Core runtime flows verified via focused component specs on 2026-03-16; editor/tooling coverage remains independent. |
201
+ | Schema/Types | `true` | Active | source_of_truth + Detailed API reference | Reconcile schema/types with canonical paths during follow-up when needed. |
202
+ | Editor/Tooling | `false` | Partial | `projects/praxis-core/src/lib/utils/inline-filter-controls.util.ts`, `projects/praxis-dynamic-fields/src/lib/services/component-registry/component-registry.service.ts` | Alias/selector tooling linkage verified for inline filters; visual editor end-to-end coverage remains not-yet-verified. |
203
203
 
204
204
  ### Runtime coverage boundaries
205
205
 
@@ -245,9 +245,9 @@ Em conflito entre caminho historico e path canonico, priorizar path canonico e r
245
245
 
246
246
  ### Validation model
247
247
 
248
- | Path/Rule | Validation phase | Behavior on fail | Error code / warning | Notes |
249
- | --- | --- | --- | --- | --- |
250
- | canonical-paths | parse/runtime | component-defined (warn/reject/default) | not-yet-standardized | Semantica detalhada preservada na referencia tecnica por componente. |
248
+ | Path/Rule | Validation phase | Behavior on fail | Error code / warning | Notes |
249
+ | --------------- | ---------------- | --------------------------------------- | -------------------- | -------------------------------------------------------------------- |
250
+ | canonical-paths | parse/runtime | component-defined (warn/reject/default) | not-yet-standardized | Semantica detalhada preservada na referencia tecnica por componente. |
251
251
 
252
252
  ### Invalid and unknown field handling
253
253
 
@@ -257,73 +257,87 @@ Em conflito entre caminho historico e path canonico, priorizar path canonico e r
257
257
 
258
258
  ### Fail-open / fail-closed behavior
259
259
 
260
- | Condition | Mode | Runtime behavior | Consumer impact |
261
- | --- | --- | --- | --- |
260
+ | Condition | Mode | Runtime behavior | Consumer impact |
261
+ | ------------------------ | ----------------- | ---------------- | ---------------------------------------------------------------------------- |
262
262
  | invalid-or-unknown-field | component-defined | not-yet-verified | Pode gerar warning, fallback silencioso ou rejeicao; validar por componente. |
263
263
 
264
264
  ### Runtime warnings vs hard failures
265
265
 
266
- | Condition | Severity | Observability | Consumer action |
267
- | --- | --- | --- | --- |
268
- | partial-or-declared-only-coverage | warning | logs/eventos do componente | Confirmar ligacao runtime antes de uso critico. |
269
- | mismatch-confirmed | error-or-warning | componente/host observability | Planejar migracao e corrigir contrato/runtime. |
266
+ | Condition | Severity | Observability | Consumer action |
267
+ | --------------------------------- | ---------------- | ----------------------------- | ----------------------------------------------- |
268
+ | partial-or-declared-only-coverage | warning | logs/eventos do componente | Confirmar ligacao runtime antes de uso critico. |
269
+ | mismatch-confirmed | error-or-warning | componente/host observability | Planejar migracao e corrigir contrato/runtime. |
270
270
 
271
271
  ## Detailed API reference
272
+
272
273
  ### Preserved technical reference (normalized from previous revision)
273
274
 
274
275
  ### 1. Visao Geral e Quando Usar
276
+
275
277
  `pdx-inline-color-label` e o seletor inline de cor/label com cards visuais, badges e popover nao modal.
276
278
 
277
279
  Use quando precisar:
280
+
278
281
  - filtro visual por cor/status com alta legibilidade;
279
282
  - modo single ou multiplo configuravel por JSON;
280
283
  - personalizar paleta, textos e layout de cards.
281
284
 
282
285
  ### 2. API do Componente (Inputs/Outputs)
283
- | Propriedade | Tipo | Padrao | Obrigatorio | Comportamento |
284
- | --- | --- | --- | --- | --- |
285
- | `metadata` | `MaterialSelectMetadata` | - | Sim | Contrato principal do filtro color label. |
286
- | `readonlyMode/disabledMode/visible/presentationMode` | `boolean` | `false/false/true/false` | Nao | Estados de host do campo inline. |
287
- | `selectionChange` | `T \| T[]` | - | Output herdado | Valor selecionado (single/multiple). |
288
- | `optionSelected` | `SelectOption` | - | Output herdado | Opção acionada no painel. |
289
- | `optionsLoaded` | `SelectOption[]` | - | Output herdado | Carga remota quando `resourcePath` for usado. |
286
+
287
+ | Propriedade | Tipo | Padrao | Obrigatorio | Comportamento |
288
+ | ---------------------------------------------------- | ------------------------ | ------------------------ | -------------- | --------------------------------------------- |
289
+ | `metadata` | `MaterialSelectMetadata` | - | Sim | Contrato principal do filtro color label. |
290
+ | `readonlyMode/disabledMode/visible/presentationMode` | `boolean` | `false/false/true/false` | Nao | Estados de host do campo inline. |
291
+ | `selectionChange` | `T \| T[]` | - | Output herdado | Valor selecionado (single/multiple). |
292
+ | `optionSelected` | `SelectOption` | - | Output herdado | Opção acionada no painel. |
293
+ | `optionsLoaded` | `SelectOption[]` | - | Output herdado | Carga remota quando `resourcePath` for usado. |
290
294
 
291
295
  ### 3. Matriz de Cobertura JSON (Completa)
296
+
292
297
  #### 3.1 Campos especificos do componente
293
- | Caminho JSON | Tipo | Status | Comportamento em runtime |
294
- | --- | --- | --- | --- |
295
- | `metadata.colorLabelOptions` | `array \| string(JSON)` | Ativo | Fonte principal dos cards de cor. |
296
- | `metadata.colorLabelMultiple` | `boolean` | Ativo | Define modo multiplo quando `multiple` nao vier. |
297
- | `metadata.colorLabelCloseOnSelect` | `boolean` | Ativo | Fecha painel apos selecionar em modo single. |
298
- | `metadata.colorLabelColumns` / `metadata.columns` | `number` | Ativo | Numero de colunas da grade (1..6). |
299
- | `metadata.colorLabelShowSelectedBadges` | `boolean` | Ativo | Mostra/oculta badges de selecionados. |
300
- | `metadata.colorLabelColorKey` / `metadata.optionColorKey` | `string` | Ativo | Chave do payload usada para cor da opcao. |
301
- | `metadata.colorLabelPalette` / `metadata.palette` | `array \| string(csv/json)` | Ativo | Paleta fallback para cards sem cor explicita. |
302
- | `metadata.colorLabelTexts` / `metadata.inlineTexts` | `object \| string(JSON)` | Ativo | Textos de aria, empty state, subtitle e labels de acao; templates devem usar `{{label}}` no contrato canonico, com compatibilidade legada para `{label}` em metadata. |
303
- | `metadata.inlineOverlay.applyMode` | `"auto" \| "explicit"` | Ativo | Define se cards e badges comitam imediatamente ou ficam em rascunho ate `Aplicar`. |
304
- | `metadata.inlineOverlay.actions.apply` | `object` | Ativo | Configura label, aria-label, icone, `appearance` e `colorRole` da acao de commit. |
305
- | `metadata.inlineOverlay.actions.cancel` | `object` | Ativo | Configura a acao que descarta rascunho e fecha o painel. |
306
- | `metadata.inlineOverlay.actions.clear` | `object` | Ativo | Configura a acao que remove a selecao aplicada/rascunho usando tokens do tema. |
307
- | `metadata.prefixIcon` / `metadata.colorLabelIcon` | `string` | Ativo | Icone do trigger e cabecalho do painel. |
308
- | `metadata.inlineAutoSize.*` | `object` | Ativo | Largura da pill e do painel (desktop/mobile). |
309
- | `metadata.searchable` | `boolean` | Parcial | Ignorado no template; componente usa grade dedicada sem busca textual. |
298
+
299
+ | Caminho JSON | Tipo | Status | Comportamento em runtime |
300
+ | --------------------------------------------------------- | --------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
301
+ | `metadata.colorLabelOptions` | `array \| string(JSON)` | Ativo | Fonte principal dos cards de cor. |
302
+ | `metadata.colorLabelMultiple` | `boolean` | Ativo | Define modo multiplo quando `multiple` nao vier. |
303
+ | `metadata.colorLabelCloseOnSelect` | `boolean` | Ativo | Fecha painel apos selecionar em modo single. |
304
+ | `metadata.colorLabelColumns` / `metadata.columns` | `number` | Ativo | Numero de colunas da grade (1..6). |
305
+ | `metadata.colorLabelShowSelectedBadges` | `boolean` | Ativo | Mostra/oculta badges de selecionados. |
306
+ | `metadata.colorLabelColorKey` / `metadata.optionColorKey` | `string` | Ativo | Chave do payload usada para cor da opcao. |
307
+ | `metadata.colorLabelPalette` / `metadata.palette` | `array \| string(csv/json)` | Ativo | Paleta fallback para cards sem cor explicita. |
308
+ | `metadata.colorLabelTexts` / `metadata.inlineTexts` | `object \| string(JSON)` | Ativo | Textos de aria, empty state, subtitle e labels de acao; templates devem usar `{{label}}` no contrato canonico, com compatibilidade legada para `{label}` em metadata. |
309
+ | `metadata.inlineOverlay.applyMode` | `"auto" \| "explicit"` | Ativo | Define se cards e badges comitam imediatamente ou ficam em rascunho ate `Aplicar`. |
310
+ | `metadata.inlineOverlay.actions.apply` | `object` | Ativo | Configura label, aria-label, icone, `appearance` e `colorRole` da acao de commit. |
311
+ | `metadata.inlineOverlay.actions.cancel` | `object` | Ativo | Configura a acao que descarta rascunho e fecha o painel. |
312
+ | `metadata.inlineOverlay.actions.clear` | `object` | Ativo | Configura a acao que remove a selecao aplicada/rascunho usando tokens do tema. |
313
+ | `metadata.prefixIcon` / `metadata.colorLabelIcon` | `string` | Ativo | Icone do trigger e cabecalho do painel. |
314
+ | `metadata.inlineAutoSize.*` | `object` | Ativo | Largura da pill e do painel (desktop/mobile). |
315
+ | `metadata.searchable` | `boolean` | Ativo local | Opt-in (false por padrão): busca compartilhada sobre opções locais, por label, value e description/subtitle, ignorando caixa e acentos. Sem campo de busca quando resourcePath está configurado. |
310
316
 
311
317
  #### 3.2 Campos herdados compartilhados (exaustivo)
318
+
312
319
  - `projects/praxis-dynamic-fields/src/lib/components/material-select/pdx-material-select.json-api.md`
313
320
  - `projects/praxis-dynamic-fields/src/lib/base/pdx-base-select-runtime-contract.json-api.md`
314
321
 
315
322
  Resumo de composicao deste componente:
323
+
316
324
  - `Ativo`: grade visual, single/multiple, badges, paleta e textos configuraveis.
317
- - `Parcial`: campo `searchable` do contrato base sem input de busca aqui.
325
+ - `Ativo local`: `searchable` filtra somente a grade; badges e valores selecionados fora dos resultados são preservados. Limpar a busca não limpa a seleção. Reabrir o painel ou atualizar metadados reinicia o termo. Escape/Cancelar descarta o rascunho; Aplicar confirma a seleção completa.
326
+ - `Parcial`: busca remota com `resourcePath` ainda não materializa campo de busca neste componente. Não inferir suporte remoto a partir do suporte local.
318
327
 
319
328
  ### 4. Mapeamento de Comportamento
329
+
320
330
  - Opcoes aceitam array direto ou string JSON (`colorLabelOptions`).
331
+ - Nas opções locais, `group` textual não vazio produz um cabeçalho. Grupos seguem a ordem de primeira ocorrência na lista original; itens mantêm a ordem original dentro de cada grupo. Itens sem grupo permanecem disponíveis, sem cabeçalho artificial. Valores em branco ou não textuais são tratados como ausência de grupo.
332
+ - A busca remove grupos sem resultados, sem descartar seleções ou badges. O nome do grupo não integra o índice de busca. Agrupar reorganiza apenas a apresentação, nunca o payload ou a identidade da opção.
333
+ - `group` é texto authorado das opções, não inferência de `semanticRole`, `purposes`, nome ou valor de uma cor. O editor JSON preserva o atributo; não há novo toggle. Com `resourcePath`, o componente não promete agrupamento remoto.
321
334
  - Em multiplo, respeita `maxSelections` herdado do base select.
322
335
  - Em single, pode fechar automaticamente via `colorLabelCloseOnSelect`.
323
336
  - Cores seguem ordem: chave custom > `color/tint` > paleta configurada > paleta default interna.
324
337
  - Quando `inlineOverlay.applyMode` e `"explicit"`, selecoes no painel alteram apenas o rascunho; `Aplicar` comita, `Cancelar`, `Esc` e clique externo descartam, e `Limpar` remove a selecao.
325
338
 
326
339
  ### 5. Exemplo Minimo (JSON + Uso)
340
+
327
341
  ```json
328
342
  {
329
343
  "componentId": "pdx-inline-color-label",
@@ -338,9 +352,11 @@ Resumo de composicao deste componente:
338
352
  }
339
353
  }
340
354
  ```
355
+
341
356
  Uso: filtro visual simples por cor.
342
357
 
343
358
  ### 6. Exemplo Corporativo (JSON + Uso)
359
+
344
360
  ```json
345
361
  {
346
362
  "componentId": "pdx-inline-color-label",
@@ -376,29 +392,33 @@ Uso: filtro visual simples por cor.
376
392
  }
377
393
  }
378
394
  ```
395
+
379
396
  Uso: filtro corporativo de risco com multi-selecao visual e confirmacao explicita antes de aplicar.
380
397
 
381
398
  ### 7. Troubleshooting e Armadilhas Comuns
399
+
382
400
  1. Cards sem cor esperada.
383
- Correcao: revisar `colorLabelColorKey/optionColorKey` e fallback de paleta.
401
+ Correcao: revisar `colorLabelColorKey/optionColorKey` e fallback de paleta.
384
402
 
385
403
  2. Nao fecha apos selecionar.
386
- Correcao: habilitar `colorLabelCloseOnSelect=true` (single).
404
+ Correcao: habilitar `colorLabelCloseOnSelect=true` (single).
387
405
 
388
406
  3. Grade com coluna errada.
389
- Correcao: ajustar `colorLabelColumns` (1..6).
407
+ Correcao: ajustar `colorLabelColumns` (1..6).
390
408
 
391
409
  4. Busca nao aparece.
392
- Correcao: este componente nao usa campo de busca textual.
410
+ Correcao: este componente nao usa campo de busca textual.
393
411
 
394
412
  5. Badges de selecionados nao aparecem.
395
- Correcao: validar `multiple=true` e `colorLabelShowSelectedBadges`.
413
+ Correcao: validar `multiple=true` e `colorLabelShowSelectedBadges`.
396
414
 
397
415
  ### 8. Cross-links
416
+
398
417
  - `projects/praxis-dynamic-fields/src/lib/components/material-select/pdx-material-select.json-api.md`
399
418
  - `projects/praxis-dynamic-fields/src/lib/base/pdx-base-select-runtime-contract.json-api.md`
400
419
 
401
420
  ### 9. Relatorio de Validacao Estrutural
421
+
402
422
  - Visao geral: PASS
403
423
  - API (inputs/outputs): PASS
404
424
  - Cobertura JSON completa (especifico + herdado): PASS
@@ -409,64 +429,64 @@ Correcao: validar `multiple=true` e `colorLabelShowSelectedBadges`.
409
429
 
410
430
  ## JSON path index (obrigatorio)
411
431
 
412
- | Path | Type | Required | Default | Status | Notes |
413
- | --- | --- | --- | --- | --- | --- |
414
- | `metadata` | object | true | n/a | Partial | See Detailed API reference. |
415
- | `resourcePath` | string | false | n/a | Partial | See Detailed API reference. |
416
- | `metadata.colorLabelOptions` | array | false | n/a | Partial | See Detailed API reference. |
417
- | `metadata.colorLabelMultiple` | boolean | false | n/a | Partial | See Detailed API reference. |
418
- | `metadata.colorLabelCloseOnSelect` | boolean | false | n/a | Partial | See Detailed API reference. |
419
- | `metadata.colorLabelColumns` | number | false | n/a | Partial | See Detailed API reference. |
420
- | `metadata.columns` | number | false | n/a | Partial | See Detailed API reference. |
421
- | `metadata.colorLabelShowSelectedBadges` | boolean | false | n/a | Partial | See Detailed API reference. |
422
- | `metadata.colorLabelColorKey` | string | false | n/a | Partial | See Detailed API reference. |
423
- | `metadata.optionColorKey` | string | false | n/a | Partial | See Detailed API reference. |
424
- | `metadata.colorLabelPalette` | array | false | n/a | Partial | See Detailed API reference. |
425
- | `metadata.palette` | array | false | n/a | Partial | See Detailed API reference. |
426
- | `metadata.colorLabelTexts` | unknown | false | n/a | Partial | See Detailed API reference. |
427
- | `metadata.inlineTexts` | unknown | false | n/a | Partial | See Detailed API reference. |
428
- | `metadata.inlineOverlay.applyMode` | string | false | `auto` | Active | `explicit` mantém rascunho até commit. |
429
- | `metadata.inlineOverlay.actions.apply` | object | false | n/a | Active | Label, aria, icon, appearance and colorRole for Apply. |
430
- | `metadata.inlineOverlay.actions.cancel` | object | false | n/a | Active | Label, aria, icon, appearance and colorRole for Cancel. |
431
- | `metadata.inlineOverlay.actions.clear` | object | false | n/a | Active | Label, aria, icon, appearance and colorRole for Clear. |
432
- | `metadata.prefixIcon` | string | false | n/a | Partial | See Detailed API reference. |
433
- | `metadata.colorLabelIcon` | string | false | n/a | Partial | See Detailed API reference. |
434
- | `metadata.inlineAutoSize.*` | object | false | n/a | Partial | See Detailed API reference. |
435
- | `metadata.searchable` | boolean | false | n/a | Partial | See Detailed API reference. |
436
- | `readonlyMode` | boolean | false | n/a | Partial | See Detailed API reference. |
437
- | `disabledMode` | boolean | false | n/a | Partial | See Detailed API reference. |
432
+ | Path | Type | Required | Default | Status | Notes |
433
+ | --------------------------------------- | ------- | -------- | ------- | ------- | ------------------------------------------------------- |
434
+ | `metadata` | object | true | n/a | Partial | See Detailed API reference. |
435
+ | `resourcePath` | string | false | n/a | Partial | See Detailed API reference. |
436
+ | `metadata.colorLabelOptions` | array | false | n/a | Partial | See Detailed API reference. |
437
+ | `metadata.colorLabelMultiple` | boolean | false | n/a | Partial | See Detailed API reference. |
438
+ | `metadata.colorLabelCloseOnSelect` | boolean | false | n/a | Partial | See Detailed API reference. |
439
+ | `metadata.colorLabelColumns` | number | false | n/a | Partial | See Detailed API reference. |
440
+ | `metadata.columns` | number | false | n/a | Partial | See Detailed API reference. |
441
+ | `metadata.colorLabelShowSelectedBadges` | boolean | false | n/a | Partial | See Detailed API reference. |
442
+ | `metadata.colorLabelColorKey` | string | false | n/a | Partial | See Detailed API reference. |
443
+ | `metadata.optionColorKey` | string | false | n/a | Partial | See Detailed API reference. |
444
+ | `metadata.colorLabelPalette` | array | false | n/a | Partial | See Detailed API reference. |
445
+ | `metadata.palette` | array | false | n/a | Partial | See Detailed API reference. |
446
+ | `metadata.colorLabelTexts` | unknown | false | n/a | Partial | See Detailed API reference. |
447
+ | `metadata.inlineTexts` | unknown | false | n/a | Partial | See Detailed API reference. |
448
+ | `metadata.inlineOverlay.applyMode` | string | false | `auto` | Active | `explicit` mantém rascunho até commit. |
449
+ | `metadata.inlineOverlay.actions.apply` | object | false | n/a | Active | Label, aria, icon, appearance and colorRole for Apply. |
450
+ | `metadata.inlineOverlay.actions.cancel` | object | false | n/a | Active | Label, aria, icon, appearance and colorRole for Cancel. |
451
+ | `metadata.inlineOverlay.actions.clear` | object | false | n/a | Active | Label, aria, icon, appearance and colorRole for Clear. |
452
+ | `metadata.prefixIcon` | string | false | n/a | Partial | See Detailed API reference. |
453
+ | `metadata.colorLabelIcon` | string | false | n/a | Partial | See Detailed API reference. |
454
+ | `metadata.inlineAutoSize.*` | object | false | n/a | Partial | See Detailed API reference. |
455
+ | `metadata.searchable` | boolean | false | n/a | Active local | Local option search only; remote search remains unsupported in this panel. |
456
+ | `readonlyMode` | boolean | false | n/a | Partial | See Detailed API reference. |
457
+ | `disabledMode` | boolean | false | n/a | Partial | See Detailed API reference. |
438
458
 
439
459
  ## Events reference (obrigatorio)
440
460
 
441
- | Event | Payload | Trigger | Stability | Notes |
442
- | --- | --- | --- | --- | --- |
461
+ | Event | Payload | Trigger | Stability | Notes |
462
+ | ------------------ | ------- | ------------- | ------------ | --------------------------------------- |
443
463
  | `searchTermChange` | unknown | runtime-event | Experimental | Check component/runtime implementation. |
444
- | `selectionChange` | unknown | runtime-event | Experimental | Check component/runtime implementation. |
445
- | `openedChange` | unknown | runtime-event | Experimental | Check component/runtime implementation. |
446
- | `valueChange` | unknown | runtime-event | Experimental | Check component/runtime implementation. |
447
- | `focusChange` | unknown | runtime-event | Experimental | Check component/runtime implementation. |
448
- | `nativeBlur` | unknown | runtime-event | Experimental | Check component/runtime implementation. |
449
- | `nativeChange` | unknown | runtime-event | Experimental | Check component/runtime implementation. |
464
+ | `selectionChange` | unknown | runtime-event | Experimental | Check component/runtime implementation. |
465
+ | `openedChange` | unknown | runtime-event | Experimental | Check component/runtime implementation. |
466
+ | `valueChange` | unknown | runtime-event | Experimental | Check component/runtime implementation. |
467
+ | `focusChange` | unknown | runtime-event | Experimental | Check component/runtime implementation. |
468
+ | `nativeBlur` | unknown | runtime-event | Experimental | Check component/runtime implementation. |
469
+ | `nativeChange` | unknown | runtime-event | Experimental | Check component/runtime implementation. |
450
470
 
451
471
  ## Styling API (obrigatorio quando aplicavel)
452
472
 
453
- | Token/Class | Scope | Purpose | Notes |
454
- | --- | --- | --- | --- |
455
- | `metadata.colorLabelOptions` | component | Styling-related JSON path | Validate against runtime implementation. |
456
- | `metadata.colorLabelMultiple` | component | Styling-related JSON path | Validate against runtime implementation. |
457
- | `metadata.colorLabelCloseOnSelect` | component | Styling-related JSON path | Validate against runtime implementation. |
458
- | `metadata.colorLabelColumns` | component | Styling-related JSON path | Validate against runtime implementation. |
473
+ | Token/Class | Scope | Purpose | Notes |
474
+ | --------------------------------------- | --------- | ------------------------- | ---------------------------------------- |
475
+ | `metadata.colorLabelOptions` | component | Styling-related JSON path | Validate against runtime implementation. |
476
+ | `metadata.colorLabelMultiple` | component | Styling-related JSON path | Validate against runtime implementation. |
477
+ | `metadata.colorLabelCloseOnSelect` | component | Styling-related JSON path | Validate against runtime implementation. |
478
+ | `metadata.colorLabelColumns` | component | Styling-related JSON path | Validate against runtime implementation. |
459
479
  | `metadata.colorLabelShowSelectedBadges` | component | Styling-related JSON path | Validate against runtime implementation. |
460
- | `metadata.colorLabelColorKey` | component | Styling-related JSON path | Validate against runtime implementation. |
480
+ | `metadata.colorLabelColorKey` | component | Styling-related JSON path | Validate against runtime implementation. |
461
481
 
462
482
  ## Examples (obrigatorio)
463
483
 
464
- | Example | Scenario | Validates | Notes |
465
- | --- | --- | --- | --- |
466
- | `Minimal valid` | baseline payload | required contract blocks | Extracted from preserved technical reference when available. |
467
- | `Common setup` | common component usage | standard runtime behavior | Validate against host integration path. |
468
- | `Advanced setup` | richer config with overrides | precedence and normalization | Requires runtime confirmation for edge cases. |
469
- | `Enterprise scenario` | governance/legacy/migration context | auditability and compatibility boundaries | Include tenant-specific constraints when applicable. |
484
+ | Example | Scenario | Validates | Notes |
485
+ | --------------------- | ----------------------------------- | ----------------------------------------- | ------------------------------------------------------------ |
486
+ | `Minimal valid` | baseline payload | required contract blocks | Extracted from preserved technical reference when available. |
487
+ | `Common setup` | common component usage | standard runtime behavior | Validate against host integration path. |
488
+ | `Advanced setup` | richer config with overrides | precedence and normalization | Requires runtime confirmation for edge cases. |
489
+ | `Enterprise scenario` | governance/legacy/migration context | auditability and compatibility boundaries | Include tenant-specific constraints when applicable. |
470
490
 
471
491
  ### Minimal valid
472
492
 
@@ -507,11 +527,7 @@ Correcao: validar `multiple=true` e `colorLabelShowSelectedBadges`.
507
527
  "colorLabelColumns": 3,
508
528
  "colorLabelShowSelectedBadges": true,
509
529
  "colorLabelColorKey": "hex",
510
- "colorLabelPalette": [
511
- "#ef4444",
512
- "#f59e0b",
513
- "#22a45d"
514
- ],
530
+ "colorLabelPalette": ["#ef4444", "#f59e0b", "#22a45d"],
515
531
  "colorLabelTexts": {
516
532
  "panelSubtitle": "Classifique por banda de risco",
517
533
  "emptyStateText": "Nenhuma banda disponível",
@@ -553,11 +569,7 @@ Correcao: validar `multiple=true` e `colorLabelShowSelectedBadges`.
553
569
  "colorLabelColumns": 3,
554
570
  "colorLabelShowSelectedBadges": true,
555
571
  "colorLabelColorKey": "hex",
556
- "colorLabelPalette": [
557
- "#ef4444",
558
- "#f59e0b",
559
- "#22a45d"
560
- ],
572
+ "colorLabelPalette": ["#ef4444", "#f59e0b", "#22a45d"],
561
573
  "colorLabelTexts": {
562
574
  "panelSubtitle": "Classifique por banda de risco",
563
575
  "emptyStateText": "Nenhuma banda disponível",
@@ -600,11 +612,7 @@ Correcao: validar `multiple=true` e `colorLabelShowSelectedBadges`.
600
612
  "colorLabelColumns": 3,
601
613
  "colorLabelShowSelectedBadges": true,
602
614
  "colorLabelColorKey": "hex",
603
- "colorLabelPalette": [
604
- "#ef4444",
605
- "#f59e0b",
606
- "#22a45d"
607
- ],
615
+ "colorLabelPalette": ["#ef4444", "#f59e0b", "#22a45d"],
608
616
  "colorLabelTexts": {
609
617
  "panelSubtitle": "Classifique por banda de risco",
610
618
  "emptyStateText": "Nenhuma banda disponível",
@@ -637,20 +645,41 @@ Correcao: validar `multiple=true` e `colorLabelShowSelectedBadges`.
637
645
 
638
646
  ## Compatibility and migration notes (recomendado)
639
647
 
640
- | Concern | Affected versions | Migration action | Deadline | Notes |
641
- | --- | --- | --- | --- | --- |
642
- | 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 |
648
+ ### Paleta governada sem perder a identidade semântica
649
+
650
+ `metadata.governedPaletteRef` substitui somente a representação cromática das opções. Os `value`/IDs semânticos usados no payload do filtro permanecem os valores authorados em `metadata.options`. `paletteKey`, `version`, `etag` e `purposes` permitem fixar a projeção publicada e impedir que uma cor local se torne fonte paralela da decisão.
651
+
652
+ Com paleta governada, `colorLabelColorKey` (ou `optionColorKey`) identifica o campo da opção que contém o `tokenId` exato da paleta. Sem uma chave configurada, o runtime lê `color`/`tint` como esse identificador. A associação não usa posição, rótulo ou aproximação textual. Reordenar ou filtrar opções preserva a cor do mesmo valor. Um token ausente, desconhecido ou excluído por `purposes` resulta em cor transparente, preservando o rótulo e o valor da opção.
653
+
654
+ ```json
655
+ {
656
+ "colorLabelColorKey": "colorTokenId",
657
+ "colorLabelOptions": [
658
+ { "label": "Crítico", "value": "critical", "colorTokenId": "status.critical" },
659
+ { "label": "Aprovado", "value": "approved", "colorTokenId": "status.positive" }
660
+ ],
661
+ "governedPaletteRef": {
662
+ "paletteKey": "praxis.corporate.main",
663
+ "version": 4,
664
+ "purposes": ["state"]
665
+ }
666
+ }
667
+ ```
668
+
669
+ | Concern | Affected versions | Migration action | Deadline | Notes |
670
+ | ------------------------------------------- | ----------------- | ------------------------------------------------ | -------- | ----------------------------------------------------- |
671
+ | 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 |
643
672
 
644
673
  ## Known limitations and mismatches (recomendado)
645
674
 
646
- | Path/Behavior | Observed behavior (runtime) | Desired behavior | Impact | Tracking issue | Target fix |
647
- | --- | --- | --- | --- | --- | --- |
648
- | Canonical contract parity | Runtime e exemplos desta referencia foram realinhados em 2026-03-16 para o contrato de i18n shared `{{...}}`; metadata legada com `{...}` continua aceita apenas por compatibilidade | Manter exemplos e host overrides no formato canonico `{{...}}` | Low | n/a | Monitor in periodic audit |
675
+ | Path/Behavior | Observed behavior (runtime) | Desired behavior | Impact | Tracking issue | Target fix |
676
+ | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------- | ------ | -------------- | ------------------------- |
677
+ | Canonical contract parity | Runtime e exemplos desta referencia foram realinhados em 2026-03-16 para o contrato de i18n shared `{{...}}`; metadata legada com `{...}` continua aceita apenas por compatibilidade | Manter exemplos e host overrides no formato canonico `{{...}}` | Low | n/a | Monitor in periodic audit |
649
678
 
650
679
  ## Source references (obrigatorio)
651
680
 
652
- | Source type | Path/URL | Why it is source of truth | Last verified (YYYY-MM-DD) | Notes |
653
- | --- | --- | --- | --- | --- |
654
- | runtime-code | projects/praxis-dynamic-fields/src/lib/components/inline-color-label/inline-color-label.component.ts | Primary source of truth for contract and behavior. | 2026-03-16 | verified-path |
655
- | runtime-code | projects/praxis-dynamic-fields/src/lib/base/simple-base-select.component.ts | Primary source of truth for contract and behavior. | 2026-03-16 | verified-path |
656
- | schema-types | projects/praxis-core/src/lib/models/material-field-metadata.interface.ts | Primary source of truth for contract and behavior. | 2026-03-16 | verified-path |
681
+ | Source type | Path/URL | Why it is source of truth | Last verified (YYYY-MM-DD) | Notes |
682
+ | ------------ | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------- | -------------------------- | ------------- |
683
+ | runtime-code | projects/praxis-dynamic-fields/src/lib/components/inline-color-label/inline-color-label.component.ts | Primary source of truth for contract and behavior. | 2026-03-16 | verified-path |
684
+ | runtime-code | projects/praxis-dynamic-fields/src/lib/base/simple-base-select.component.ts | Primary source of truth for contract and behavior. | 2026-03-16 | verified-path |
685
+ | schema-types | projects/praxis-core/src/lib/models/material-field-metadata.interface.ts | Primary source of truth for contract and behavior. | 2026-03-16 | verified-path |