@ngx-smz/core 21.1.21 → 21.2.2

package/README.md

@@ -58,6 +58,43 @@ ng e2e
 
 Angular CLI does not come with an end-to-end testing framework by default. You can choose one that suits your needs.
 
+## `smz-form-group`: eventos de alteração e `statusChanges`
+
+O seletor `smz-form-group` expõe três saídas (`@Output`) que parecem relacionadas, mas respondem a **gatilhos e comparações diferentes**. Todas emitem `SmzFormsResponse` (o mesmo retorno de `getData()`), com `data`, `isValid`, `hasUnsavedChanges`, `validationMessagesByField`, etc.
+
+### `statusChanges`
+
+- **O que é:** um `EventEmitter` do componente — **não** é o `statusChanges` do `FormGroup` do Angular exposto diretamente no template.
+- **Quando dispara:** após o `FormGroup` notificar mudança de status, com **debounce** (`config.behaviors.debounceTime`, padrão `400` ms). Nesse ciclo o componente roda validação customizada (`customValidator`), `customBehavior`, visibilidade e avisos, e em seguida emite o payload atual.
+- **Também no carregamento:** na primeira carga, em geral emite uma vez com os dados iniciais, **exceto** se `config.behaviors.skipEmitChangesOnLoad` estiver ativo ou se `runCustomFunctionsOnLoad` alterar esse fluxo.
+- **Uso típico:** reagir a **cada ciclo de revalidação/reprocessamento** do formulário (ex.: sincronizar UI com erros globais ou com o resultado de `customBehavior`).
+
+### `initialStateChanged`
+
+- **O que significa:** o snapshot atual dos dados (**serializado**) é **diferente do estado inicial** guardado quando o formulário realizou `resetState()` (por exemplo logo após a montagem ou após você restaurar a linha base com APIs do componente).
+- **`hasUnsavedChanges`:** no `SmzFormsResponse` emitido/atualizado, esse flag está alinhado a “mudou em relação ao estado inicial”.
+- **Uso típico:** habilitar **“Salvar”** apenas quando há alterações em relação ao registro/modelo original, ou alertar que há rascunho não persistido desde a última baseline.
+
+### `previousStateChanged`
+
+- **O que significa:** o snapshot atual dos dados é **diferente do estado no ciclo anterior** de `updateHasChanges()` (internamente compara com o último valor conhecido antes de atualizar essa cópia).
+- **Contraste com `initialStateChanged`:** não olha apenas para o “primeiro estado após load”, e sim para **“mudou desde a última vez que o componente avaliou mudanças”** — granularidade passo a passo a cada ciclo que chama `updateHasChanges`.
+- **Uso típico:** lógicas que precisam detectar **variações incrementais** entre emissões consecutivas (por exemplo atualizar apenas um campo derivado quando algo mudou desde o último processamento).
+
+### Emitir todas as saídas no primeiro load
+
+Com `config.behaviors.emitAllOutputsOnLoad === true`, no carregamento o componente pode emitir `initialStateChanged`, `previousStateChanged` e `statusChanges` com o mesmo `getData()`, para inicializar fluxos que dependem desses handlers sem esperar o primeiro debounce interativo.
+
+### Resumo rápido
+
+| Evento                   | Comparado com                                      | Gatilho principal                                              |
+|-------------------------|-----------------------------------------------------|----------------------------------------------------------------|
+| `statusChanges`         | (não é comparação de snapshot)                       | Ciclo pós mudança de status do formulário (+ debounce) + carga inicial conforme comportamentos |
+| `initialStateChanged`   | Baseline da última `resetState()` / estado inicial  | Mudança do payload atual em relação a esse baseline          |
+| `previousStateChanged`  | Snapshot do ciclo anterior de `updateHasChanges`    | Mudança desde o último processamento de “has changes”       |
+
+Para detalhes de implementação (ordem das chamadas, `emitChanges`, `runStatusChangesOnConfigUpdate`, etc.), consulte `form-group.component.ts` e `form-viewdata.ts`.
+
 ## Additional Resources
 
 For more information on using the Angular CLI, including detailed command references, visit the [Angular CLI Overview and Command Reference](https://angular.dev/tools/cli) page.