---
title: "Dynamic Form Hot Metadata Updates"
slug: "dynamic-form-hot-metadata-updates"
description: "Guia operacional para aplicar patches de metadata em runtime no PraxisDynamicForm sem rebuild estrutural desnecessario."
doc_type: "guide"
document_kind: "host-guide"
component: "dynamic-form"
category: "integration"
audience:
  - "frontend"
  - "host"
  - "architect"
  - "platform-team"
level: "advanced"
status: "active"
owner: "praxis-ui"
tags:
  - "dynamic-form"
  - "hot-metadata"
  - "runtime"
  - "dynamic-fields"
last_updated: "2026-03-07"
toc: true
sidebar: true
related_docs:
  - "dynamic-form-overview"
  - "praxis-dynamic-form-json-api"
  - "dynamic-fields-host-custom-field-guide"
keywords:
  - "hot update"
  - "field metadata patch"
  - "dynamic field loader"
  - "component metadata registry"
source_of_truth:
  - "projects/praxis-dynamic-form/src/lib/praxis-dynamic-form.ts"
  - "projects/praxis-dynamic-fields/src/lib/directives/dynamic-field-loader.directive.ts"
---

# Dynamic Form Hot Metadata Updates

## Objetivo

Explicar como o `PraxisDynamicForm` aplica patches de metadata em runtime sem reconstruir o formulario inteiro quando isso nao e necessario.

```mermaid
flowchart LR
    Patch["host aplica patch de metadata"] --> Runtime["PraxisDynamicForm"]
    Runtime --> Hot["reaplica metadata no componente vivo"]
    Runtime --> Refresh["refresh do loader afetado"]
    Runtime --> Rebuild["buildFormFromConfig como fallback"]
```

## Pre-requisitos

- entendimento basico de `FormConfig`, `FieldMetadata` e `DynamicFieldLoaderDirective`
- familiaridade com o fluxo de configuracao de campos no `PraxisDynamicForm`

## O que mudou no runtime

- `PraxisDynamicForm` mantem referencias para os `DynamicFieldLoaderDirective` ativos, um por coluna.
- Depois de aplicar um patch de metadata:
  - atualiza o `FieldMetadata` canonico dentro da configuracao persistida;
  - reusa o `FormControl` atual quando a mudanca e apenas de validacao/comportamento;
  - reaplica metadata diretamente no componente vivo quando ele suporta hot metadata;
  - faz `refresh()` apenas no loader afetado quando a mudanca exige rerender;
  - cai em `buildFormFromConfig()` apenas como fallback seguro.

## Quando o update continua hot

O caminho de hot update e usado quando a alteracao nao muda a estrutura do campo, por exemplo:

- `required`
- `readonly`
- `disabled`
- `hidden`
- `min`, `max`, `pattern`
- labels, hints e metadata de apresentacao que o componente consegue receber em runtime

Nesses casos o runtime:

1. recalcula validators via `DynamicFormService.updateControlFromMetadata`;
2. reaplica a metadata no componente por `setInputMetadata(...)` ou `WritableSignal`;
3. evita rebuild completo do formulario.

## Quando vira refresh estrutural

Mudancas estruturais ainda exigem rerender do loader para manter integridade:

- troca de `controlType`
- inclusao ou remocao de campos
- mudancas que alteram o conjunto de bindings esperados pelo componente

Regra operacional:

- se o loader da coluna for localizado, apenas ele e atualizado;
- se o loader nao puder ser localizado, o runtime usa fallback seguro de rebuild do form.

## Melhorias no DynamicFieldLoader

O guard de rerender do loader passou a incluir no snapshot:

- `required`
- `readonly`
- `disabled`
- `hidden`

Isso reduz casos em que o host alterava metadata valida mas a UI nao refletia a mudanca imediatamente.

## Limites e pre-requisitos

O hot update funciona melhor quando o field component:

- expõe metadata por `WritableSignal`; ou
- implementa `setInputMetadata(metadata)`; e
- trabalha ligado a um `FormControl`

Se o componente custom nao suporta isso, o runtime ainda funciona, mas cai no caminho de `loader.refresh()`.

## Extensao no host

Para fields custom do host:

- registre o componente no `ComponentRegistryService`;
- registre metadados editoriais no `ComponentMetadataRegistry`;
- mantenha `controlType` e id de metadata alinhados;
- implemente `setInputMetadata(...)` ou sinal equivalente para aproveitar hot updates.

## Por que isso importa

Em cenarios corporativos, esse fluxo reduz:

- flicker visual
- rebuilds desnecessarios
- perda de foco durante configuracao de campos
- custo de reconciliacao manual no host

## Documentos relacionados

- Dynamic Form overview: `dynamic-form-overview`
- [Dynamic Form API](../src/lib/praxis-dynamic-form.json-api.md)
- [Dynamic Fields Host Custom Field Guide](../../praxis-dynamic-fields/docs/dynamic-fields-host-custom-field-guide.md)
