@praxisui/dynamic-fields 8.0.0-beta.19 → 8.0.0-beta.20

package/docs/dynamic-fields-host-custom-field-troubleshooting.md

@@ -0,0 +1,160 @@
+---
+title: "Dynamic Fields Host Custom Field Troubleshooting"
+slug: "dynamic-fields-host-custom-field-troubleshooting"
+description: "Troubleshooting guide para criacao e registro de fields custom no host com @praxisui/dynamic-fields."
+doc_type: "guide"
+document_kind: "runbook"
+component: "dynamic-fields"
+category: "components"
+audience:
+  - "host"
+  - "frontend"
+  - "ops"
+level: "advanced"
+status: "active"
+owner: "praxis-ui"
+tags:
+  - "dynamic-fields"
+  - "troubleshooting"
+  - "custom field"
+  - "host"
+order: 37
+icon: "build"
+toc: true
+sidebar: true
+search_boost: 1.05
+reading_time: 12
+estimated_setup_time: 20
+version: "1.0"
+related_docs:
+  - "dynamic-fields-host-custom-field-guide"
+  - "dynamic-fields-field-selection-guide"
+  - "dynamic-fields-inventory"
+keywords:
+  - "field not render"
+  - "controlType not registered"
+  - "hot update"
+  - "CVA error"
+last_updated: "2026-03-07"
+---
+
+# Dynamic Fields Host Custom Field Troubleshooting
+
+## Objetivo
+
+Fornecer resposta operacional rapida para falhas comuns na extensao de fields custom no host.
+
+## Resposta operacional
+
+1. confirme o `controlType` do contrato;
+2. confirme runtime registry e metadata registry;
+3. confirme compatibilidade com Angular Forms;
+4. confirme se a falha e estrutural ou apenas de metadata/hot update;
+5. confirme escopo correto de providers.
+
+## 1. Field nao renderiza
+
+### Check
+
+- o `controlType` do contrato bate com o id registrado?
+- o `ENVIRONMENT_INITIALIZER` roda no root app?
+- o import dinamico retorna o componente certo?
+
+### Typical root cause
+
+`ComponentRegistryService.register(...)` nao foi executado ou foi executado em escopo errado.
+
+## 2. controlType nao registrado
+
+### Symptom
+
+O runtime loga que o componente nao esta registrado.
+
+### Fix
+
+- registre o `controlType` exato;
+- evite drift entre `my-custom`, `myCustom` e `my-custom-field`;
+- mantenha um id canônico e unificado.
+
+## 3. Editor nao mostra nome ou icone
+
+### Root cause
+
+O componente foi registrado no runtime, mas nao no `ComponentMetadataRegistry`.
+
+### Fix
+
+Registre um `ComponentDocMeta` com `id` identico ao `controlType`.
+
+## 4. Hot update nao aplica
+
+### Check
+
+- o componente expoe `setInputMetadata(metadata)`?
+- ou mantem metadata em signal reativa?
+- a mudanca foi estrutural (`controlType`, add/remove field) ou apenas comportamental?
+
+### Important
+
+Mudancas estruturais ainda podem exigir refresh do loader. Hot update otimiza principalmente mudancas comportamentais/validacao.
+
+## 5. Erro de forms / CVA
+
+### Symptom
+
+- valor nao propaga;
+- touched nao propaga;
+- disabled nao sincroniza;
+- Angular reclama de value accessor.
+
+### Fix
+
+- implemente `ControlValueAccessor`, ou
+- aceite `[formControl]` corretamente;
+- propague `writeValue`, `registerOnChange`, `registerOnTouched`, `setDisabledState`.
+
+## 6. Alias / selectors em conflito
+
+### Symptom
+
+Um alias antigo aponta para componente inesperado.
+
+### Fix
+
+- revise `FieldSelectorRegistry` e base/overrides;
+- use `providePraxisDynamicFieldsNoDefaults()` apenas quando realmente quiser substituir a base;
+- evite colisao de alias entre bibliotecas internas do host.
+
+## 7. Provider em escopo errado
+
+### Root cause
+
+`FIELD_SELECTOR_REGISTRY_DISABLE_DEFAULTS` ou inicializadores foram fornecidos em modulo lazy, mas o singleton efetivo nasceu no root.
+
+### Fix
+
+Registre providers de governanca no root injector.
+
+## 8. Tokens / tema quebram UX
+
+### Symptom
+
+- contraste ruim;
+- largura inconsistente;
+- estados de foco ilegiveis.
+
+### Fix
+
+- valide tokens M3 do host;
+- garanta que tema e componentes compartilham o mesmo escopo;
+- nao dependa de estilos locais fora dos contratos do design system.
+
+## Final checklist
+
+- `controlType` correto e unico.
+- runtime registry ativo.
+- metadata registry ativo.
+- forms integration valida.
+- hot update tratado.
+- providers no root.
+- tokens e tema validados.