jsegd-bpm 0.1.8 → 0.1.10

package/README.md

@@ -1,7 +1,7 @@
 # jsEGD BPM
 
-Biblioteca TypeScript de runtime para desenvolvimento de formulários e workflows no ambiente **EGD BPM** — EGD Tecnologia.  
-Fornece componentes de anexo, gerenciamento de workers para datasets, controle do ciclo de vida do workflow e utilitários de formulário integrados ao DOM do EGD BPM.
+Biblioteca TypeScript de runtime para desenvolvimento de formulários e workflows em um ambiente BPM genérico.  
+Fornece componentes de anexo, gerenciamento de workers para datasets, controle do ciclo de vida do fluxo e utilitários de formulário integrados ao DOM.
 
 > **Dependências par obrigatórias:** [`jsegd`](https://jsegd.netlify.app) ≥ 1.1.0 e [`alpinejs`](https://alpinejs.dev) ≥ 3.0.0
 
@@ -25,7 +25,7 @@ npm install jsegd-bpm jsegd alpinejs
 
 ## `WorkerManager` — Consultas de Dataset em Web Workers
 
-Gerencia um pool de Web Workers para executar consultas à API de Datasets do EGD BPM fora da thread principal. Suporta deduplicação de requisições, cache em IndexedDB e cancelamento HTTP real via `AbortController`.
+Gerencia um pool de Web Workers para executar consultas à API de datasets fora da thread principal. Suporta deduplicação de requisições, cache em IndexedDB e cancelamento HTTP real via `AbortController`.
 
 ```typescript
 import { WorkerManager, ConstraintsType } from 'jsegd-bpm'
@@ -37,8 +37,8 @@ cache.initialize({ storeName: 'datasets', cacheExpirationMs: 60 * 60 * 1000 })
 
 const manager = new WorkerManager({ poolSize: 4, cache })
 
-const { promise, cancel } = manager.query('https://tenant.bpm.empresa.com', {
-    datasetId: 'dsColaboradores',
+const { promise, cancel } = manager.query('https://exemplo.local', {
+    datasetId: 'dsRegistros',
     field: ['nome', 'email', 'matricula'],
     constraintsField: ['ativo'],
     constraintsInitialValue: ['true'],
@@ -87,13 +87,13 @@ Botão com dropdown para upload de arquivos vinculados ao processo.
 
 ```html
 <!-- Tipo de anexo fixo -->
-<attachment-button description="CONTRATO"></attachment-button>
+<attachment-button description="DOCUMENTO"></attachment-button>
 
 <!-- Prompt ao usuário para informar a descrição no upload -->
 <attachment-button></attachment-button>
 
 <!-- Somente leitura: oculta botão de adicionar -->
-<attachment-button description="CONTRATO" noaddbutton></attachment-button>
+<attachment-button description="DOCUMENTO" noaddbutton></attachment-button>
 ```
 
 | Atributo         | Tipo     | Descrição                                                        |
@@ -117,7 +117,7 @@ Tabela que lista os anexos do processo com suporte a drag-and-drop para reordena
 
 ## `BeforeSendValidate` — Validação com feedback visual
 
-Integra validação de campos com o sistema de erros visuais do tema EGD BPM (`data-group` / `data-helper`).
+Integra validação de campos com o sistema de erros visuais do tema do formulário (`data-group` / `data-helper`).
 
 ```typescript
 import { BeforeSendValidate } from 'jsegd-bpm'
@@ -126,9 +126,9 @@ import type { FieldError } from 'jsegd-bpm'
 function validarFormulario() {
     const erros: FieldError[] = []
 
-    const campoNome = document.querySelector<HTMLInputElement>('[name="nome_solicitante"]')
-    if (!campoNome?.value) {
-        erros.push({ field: campoNome, errorMessage: 'Informe o nome do solicitante' })
+    const campoTexto = document.querySelector<HTMLInputElement>('[name="nome"]')
+    if (!campoTexto?.value) {
+        erros.push({ field: campoTexto, errorMessage: 'Informe o nome' })
     }
 
     if (erros.length > 0) {
@@ -138,13 +138,115 @@ function validarFormulario() {
 }
 ```
 
-`throwValidationError` lança sempre — use dentro de `beforeSendValidate` do EGD BPM ou em hooks de `WorkflowViewPatcher`.
+`throwValidationError` lança sempre — use dentro de `beforeSendValidate` do formulário ou em hooks de `WorkflowViewPatcher`.
+
+---
+
+## `Validator` — Validação local e de submit
+
+O `Validator` tem dois usos complementares:
+- `Validator.add(...)` cria um validador isolado para cada instância de `Alpine.data(...)`
+- `Validator.getInstance().register(code, rules)` agrupa várias regras de submit sob o mesmo código numérico
+
+```typescript
+import { Validator } from 'jsegd-bpm'
+
+function departamentoComponent() {
+    const regras: Record<string, () => boolean | Promise<boolean>> = {
+        taxa: () => this.possuiTaxa === '1' && !this.taxa,
+        campoExtra: () => this.possuiTaxa === '1' && this.campoExtra === 'invalido',
+        campoIndependente: () => !this.campoIndependente,
+    }
+
+    const validadores = Validator.add(regras)
+
+    return {
+        possuiTaxa: '0',
+        taxa: '',
+        campoExtra: '',
+        campoIndependente: '',
+        temErro: false,
+
+        async init() {
+            this.$watch('possuiTaxa', async () => {
+                await validadores.validate('taxa')
+                await validadores.validate('campoExtra')
+                this.temErro = await validadores.hasError()
+            })
+        },
+
+        async onInput(field: string) {
+            await validadores.validate(field)
+            this.temErro = await validadores.hasError()
+        },
+    }
+}
+```
+
+`hasError()` e `validate(field)` são assíncronos — armazene o resultado em uma propriedade reativa (`temErro`) para que o Alpine reflita o estado no template. Funções síncronas continuam aceitas sem alteração.
+
+```typescript
+import { Validator } from 'jsegd-bpm'
+
+const cancelarSubmit = Validator.getInstance().register(100, {
+    taxa: () => this.possuiTaxa === '1' && !this.taxa,
+    // exemplo de regra assíncrona — ex.: validação remota
+    campoExtra: async () => {
+        const resultado = await verificarCampoNoServidor(this.campoExtra)
+        return resultado.valido
+    },
+    campoIndependente: () => !this.campoIndependente,
+})
+
+try {
+    await Validator.getInstance().execute(100)
+} catch (error) {
+    // impede o envio do formulário
+}
+
+cancelarSubmit()
+```
+
+`register(code, rules)` aceita tanto uma função única quanto um mapa de regras — síncronas ou assíncronas. `unregister(code, rules)` remove o mesmo conjunto informado.
+
+### Exemplo no HTML
+
+```html
+<section x-data="departamentoComponent()">
+    <label>
+        Possui taxa?
+        <select x-model="possuiTaxa" @change="onInput('taxa')">
+            <option value="0">Nao</option>
+            <option value="1">Sim</option>
+        </select>
+    </label>
+
+    <label>
+        Taxa
+        <input type="text" x-model="taxa" @input="onInput('taxa')" />
+    </label>
+
+    <label>
+        Campo extra
+        <input type="text" x-model="campoExtra" @input="onInput('campoExtra')" />
+    </label>
+
+    <label>
+        Campo independente
+        <input type="text" x-model="campoIndependente" @input="onInput('campoIndependente')" />
+    </label>
+
+    <p x-show="temErro">Existem campos invalidos.</p>
+</section>
+```
+
+> Como `hasError()` agora é assíncrono, use uma propriedade reativa (`temErro`) em vez de um getter direto no `x-show`.
 
 ---
 
 ## `WorkflowViewPatcher` — Hooks no widget de processo
 
-Substitui métodos do widget nativo `ECM_WKFView` para interceptar o ciclo de envio do processo sem modificar o EGD BPM.
+Substitui métodos do widget nativo `ECM_WKFView` para interceptar o ciclo de envio do fluxo sem modificar o formulário.
 
 ```typescript
 import { WorkflowViewPatcher } from 'jsegd-bpm'
@@ -159,8 +261,8 @@ WorkflowViewPatcher.patchAll()
 WorkflowViewPatcher.addBeforeValidate(async () => {
     // Executado antes da validação do widget.
     // Lançar exceção cancela o envio e reabilita os botões.
-    const valor = document.querySelector<HTMLInputElement>('[name="campo_critico"]')?.value
-    if (!valor) throw new Error('Campo crítico obrigatório')
+    const valor = document.querySelector<HTMLInputElement>('[name="campo_principal"]')?.value
+    if (!valor) throw new Error('Campo principal obrigatório')
 })
 
 WorkflowViewPatcher.addAfterValidate(async () => {
@@ -178,7 +280,7 @@ WorkflowViewPatcher.addOnMoveError(() => {
 
 WorkflowViewPatcher.addOnCompletionLinkAdd((message) => {
     // Adiciona links à tela de conclusão após a movimentação
-    message.links.push({ description: 'Abrir tarefa seguinte', href: '/minha-tarefa' })
+    message.links.push({ description: 'Abrir próxima etapa', href: '/proxima-etapa' })
 })
 
 // Ao desmontar o formulário (SPAs): restaura os métodos originais
@@ -217,12 +319,12 @@ onde `{domínio}` é o identificador do **agregado de negócio** ao qual o campo
 
 | Campo no DOM        | Domínio     | Atributo no modelo |
 | ------------------- | ----------- | ------------------ |
-| `contrato_indice`   | `contrato`  | `indice`           |
-| `imovel_cep`        | `imovel`    | `cep`              |
-| `vigencia_prazo`    | `vigencia`  | `prazo`            |
-| `fornecedor_cep`    | `fornecedor`| `cep`              |
+| `departamento_indice`   | `departamento`  | `indice`           |
+| `area_cep`              | `area`          | `cep`              |
+| `vigencia_prazo`        | `vigencia`      | `prazo`            |
+| `cadastro_cep`          | `cadastro`      | `cep`              |
 
-> **Importante:** o `{domínio}` é o prefixo persistido no banco pelo Fluig — é parte integrante do nome da coluna e **não deve ser omitido** no HTML. O `load` e o `save` gerenciam a conversão entre o nome DOM e o atributo do modelo de forma transparente.
+> **Importante:** o `{domínio}` é o prefixo persistido no banco — é parte integrante do nome da coluna e **não deve ser omitido** no HTML. O `load` e o `save` gerenciam a conversão entre o nome DOM e o atributo do modelo de forma transparente.
 
 O `moduleId` do workflow (quem exibe o campo na tela) e o `stage` (em que fase do processo estamos) são **independentes** do domínio do campo — um mesmo módulo pode exibir campos de múltiplos domínios.
 
@@ -236,13 +338,13 @@ Lê e escreve diretamente nos elementos `input`, `select` e `textarea` do formul
 ```typescript
 import { BpmFormRepository } from 'jsegd-bpm'
 
-interface Contrato {
+interface Departamento {
     indice: string
     primeiroPagamento: string
     reajuste: string
 }
 
-interface Imovel {
+interface Area {
     cep: string
     logradouro: string
     municipio: string
@@ -255,22 +357,22 @@ interface ItemTabela {
 
 const repo = new BpmFormRepository()
 
-// Ler domínio 'contrato' — lê campos com name="contrato_*" do DOM
-// DOM: contrato_indice, contrato_primeiro_pagamento, contrato_reajuste
-const contrato = repo.load<Contrato>('contrato')
-console.log(contrato.indice)           // valor de input[name="contrato_indice"]
-console.log(contrato.primeiroPagamento) // valor de input[name="contrato_primeiro_pagamento"]
+// Ler domínio 'departamento' — lê campos com name="departamento_*" do DOM
+// DOM: departamento_indice, departamento_primeiro_pagamento, departamento_reajuste
+const departamento = repo.load<Departamento>('departamento')
+console.log(departamento.indice)            // valor de input[name="departamento_indice"]
+console.log(departamento.primeiroPagamento) // valor de input[name="departamento_primeiro_pagamento"]
 
-// Ler domínio 'imovel' — desambigua de 'fornecedor_cep', 'contrato_cep', etc.
-const imovel = repo.load<Imovel>('imovel')
-console.log(imovel.cep) // valor de input[name="imovel_cep"]
+// Ler domínio 'area' — desambigua de 'cadastro_cep', 'departamento_cep', etc.
+const area = repo.load<Area>('area')
+console.log(area.cep) // valor de input[name="area_cep"]
 
 // Ler tabela filha
 const itens = repo.loadTable<ItemTabela>('tabItens')
 
 // Persistir no DOM — save converte camelCase → prefixo+snake_case
-repo.save<Contrato>('contrato', { indice: 'IGPM', primeiroPagamento: '2026-02-01' })
-// escreve: input[name="contrato_indice"] e input[name="contrato_primeiro_pagamento"]
+repo.save<Departamento>('departamento', { indice: 'IGPM', primeiroPagamento: '2026-02-01' })
+// escreve: input[name="departamento_indice"] e input[name="departamento_primeiro_pagamento"]
 
 // Substituir linhas da tabela filha
 repo.saveTable<ItemTabela>('tabItens', [
@@ -314,18 +416,18 @@ Processos existentes cujos campos não seguem a convenção `{domínio}_{atribut
 ```typescript
 import { loadFields } from 'jsegd-bpm'
 
-interface Solicitante {
+interface Requisitante {
     nome: string
     email: string
 }
 
-// Campo legado: sufixo em vez de prefixo — nome_solicitante, email_solicitante
-const dados = loadFields<Solicitante>({
-    nome: 'nome_solicitante',
-    email: 'email_solicitante',
+// Campo legado: sufixo em vez de prefixo — nome_requisitante, email_requisitante
+const dados = loadFields<Requisitante>({
+    nome: 'nome_requisitante',
+    email: 'email_requisitante',
 })
-// dados.nome === valor de input[name="nome_solicitante"]
-// dados.email === valor de input[name="email_solicitante"]
+// dados.nome === valor de input[name="nome_requisitante"]
+// dados.email === valor de input[name="email_requisitante"]
 ```
 
 > **Regra:** `loadFields` **não faz parte de `IFormRepository`** — é um utilitário de compatibilidade para processos legados. Novos processos devem usar `repository.load(section)` exclusivamente.
@@ -346,59 +448,59 @@ import { defineWorkflowConfig } from 'jsegd-bpm'
 export const workflowConfig = defineWorkflowConfig({
     modules: [
         {
-            moduleId: 'solicitante',
+            moduleId: 'areaInicial',
             label: 'Dados Iniciais',
             icon: 'file-text',
             order: 1,
             showInNavigation: true,
             renderContent: true,
-            contentIncludePath: 'solicitante.html',
+            contentIncludePath: 'area-inicial.html',
         },
         {
-            moduleId: 'juridico',
-            label: 'Jurídico',
+            moduleId: 'areaA',
+            label: 'Área A',
             icon: 'gavel',
             order: 2,
             showInNavigation: true,
             renderContent: true,
-            contentIncludePath: 'juridico.html',
+            contentIncludePath: 'area-a.html',
         },
         {
-            moduleId: 'financeiro',
-            label: 'Financeiro',
+            moduleId: 'areaB',
+            label: 'Área B',
             icon: 'dollar-sign',
             order: 3,
             showInNavigation: true,
             renderContent: true,
-            contentIncludePath: 'financeiro.html',
+            contentIncludePath: 'area-b.html',
         },
     ],
     activities: [
         {
             sequence: 9,
-            description: 'Solicitação inicial',
+            description: 'Etapa inicial',
             kind: 'human',
-            stage: 'solicitacao',
-            modules: { visible: ['solicitante'], editable: ['solicitante'], active: 'solicitante' },
+            stage: 'inicio',
+            modules: { visible: ['areaInicial'], editable: ['areaInicial'], active: 'areaInicial' },
         },
         {
             sequence: 53,
-            description: 'Aprovação jurídica',
+            description: 'Análise da área A',
             kind: 'human',
-            stage: 'juridico',
-            modules: { visible: ['solicitante', 'juridico'], editable: ['juridico'], active: 'juridico' },
+            stage: 'analiseA',
+            modules: { visible: ['areaInicial', 'areaA'], editable: ['areaA'], active: 'areaA' },
         },
         {
             sequence: 61,
-            description: 'Análise financeira',
+            description: 'Análise da área B',
             kind: 'human',
-            stage: 'financeiro',
-            modules: { visible: ['solicitante', 'juridico', 'financeiro'], editable: ['financeiro'] },
+            stage: 'analiseB',
+            modules: { visible: ['areaInicial', 'areaA', 'areaB'], editable: ['areaB'] },
         },
         { sequence: 88, description: 'Roteamento interno', kind: 'routing' },
     ],
 } as const)
-// Tipo de ModuleId inferido: 'solicitante' | 'juridico' | 'financeiro'
+// Tipo de ModuleId inferido: 'areaInicial' | 'areaA' | 'areaB'
 ```
 
 **`ActivityKind`** — controla o comportamento na barra de progresso:
@@ -425,10 +527,10 @@ const currentSequence: number = parent.ECM.workflowView.processDefinition.cardIn
 const historyType: string | null = parent.ECM.workflowView.processDefinition.historyType ?? null
 
 const completedStages = extractCompletedStages(rawHistory, workflowConfig.activities)
-// Ex: ['solicitacao', 'juridico']
+// Ex: ['inicio', 'analiseA']
 
 const currentStage = extractCurrentStage(currentSequence, historyType, workflowConfig.activities)
-// Ex: { stage: 'financeiro', status: 'current' }
+// Ex: { stage: 'analiseB', status: 'current' }
 
 const processHistory: ProcessHistory = { completedStages, currentStage }
 ```
@@ -445,9 +547,9 @@ import { resolveWorkflowScreen } from 'jsegd-bpm'
 const screen = resolveWorkflowScreen(workflowConfig, currentSequence, processHistory)
 
 // Visibilidade e editabilidade
-screen.isVisible('juridico') // true
-screen.isEditable('financeiro') // false
-screen.isActive('juridico') // true
+screen.isVisible('areaA') // true
+screen.isEditable('areaB') // false
+screen.isActive('areaA') // true
 
 // Estado da atividade
 screen.isAwaitingSystem() // true quando kind === 'system' ou status === 'waiting'
@@ -456,9 +558,9 @@ screen.isInSupport() // true para kind === 'support'
 // Barra de progresso
 const stages = screen.getProgressBarStages()
 // [
-//   { stage: 'solicitacao', status: 'done' },
-//   { stage: 'juridico',    status: 'done' },
-//   { stage: 'financeiro',  status: 'current' },
+//   { stage: 'inicio',   status: 'done' },
+//   { stage: 'analiseA',  status: 'done' },
+//   { stage: 'analiseB',  status: 'current' },
 // ]
 
 // Módulos
@@ -518,7 +620,7 @@ customElements.define('attachments-table', AttachmentsTable)
 
 // Alpine stores
 const stores = registerStores(Alpine, {
-    solicitante: { nome: '', departamento: '' },
+    departamento: { nome: '', area: '' },
     ui: { carregando: false },
 })
 
@@ -539,8 +641,8 @@ await WorkflowViewPatcher.init()
 WorkflowViewPatcher.patchAll()
 WorkflowViewPatcher.addBeforeValidate(async () => {
     const repo = new BpmFormRepository()
-    const dados = repo.load<{ nome: string }>('solicitante')
-    if (!dados.nome) throw new Error('Informe o nome do solicitante')
+    const dados = repo.load<{ nome: string }>('departamento')
+    if (!dados.nome) throw new Error('Informe o nome')
 })
 
 Alpine.start()
@@ -550,4 +652,4 @@ Alpine.start()
 
 ## Licença
 
-Proprietária — EGD Tecnologia. Uso restrito a projetos autorizados.
+Proprietária — uso restrito a projetos autorizados.

package/dist/jsegd-bpm.d.ts

@@ -1076,7 +1076,12 @@ type StoreProxy<T extends StoreMap> = {
  */
 declare function registerStores<T extends StoreMap>(alpine: Pick<Alpine, 'store'>, storeMap: T): StoreProxy<T>;
 
-type ValidationFn = (...args: unknown[]) => boolean;
+type ValidationFn = (...args: unknown[]) => boolean | Promise<boolean>;
+type ValidationRules = Record<string, ValidationFn>;
+type ValidatorHandle = {
+    validate(field?: string): Promise<boolean>;
+    hasError(): Promise<boolean>;
+};
 /**
  * Validador tipado com padrão singleton.
  * Permite registrar, remover e executar funções de validação associadas a códigos numéricos.
@@ -1097,24 +1102,50 @@ declare class Validator {
      */
     static getInstance(): Validator;
     /**
-     * Registra uma função de validação associada a um código numérico.
-     * Retorna uma função para cancelar o registro.
+     * Cria um validador isolado para um conjunto de regras nomeadas.
+     * Cada chamada retorna um handle independente, útil para instâncias locais de Alpine.data().
+     * @example
+     * const validadores = Validator.add({
+        *     taxa: () => this.possuiTaxa === '1' && !this.taxa,
+        *     campoExtra: () => this.possuiTaxa === '1' && this.campoExtra === 'invalido',
+     * })
+     */
+    static add(rules: ValidationRules): ValidatorHandle;
+    private addRule;
+    private removeRule;
+    private normalizeRules;
+    private unregisterAll;
+    /**
+     * Registra uma validação associada a um código numérico.
+     * Aceita uma única função ou um lote de regras nomeadas.
+     * Retorna uma função para cancelar o registro do mesmo conjunto informado.
      * @example Validator.getInstance().register(100, () => value > 0)
+     * @example Validator.getInstance().register(100, {
+     *     fieldA: () => valueA > 0,
+     *     fieldB: () => valueB !== '',
+     * })
      */
-    register(code: number, fn: ValidationFn): () => void;
+    register(code: number, rules: ValidationFn): () => void;
+    register(code: number, rules: ValidationRules): () => void;
     /**
-     * Remove uma função de validação específica associada a um código numérico.
+     * Remove uma validação associada a um código numérico.
+     * Aceita uma única função ou o mesmo lote de regras nomeadas usado no registro.
      * @example Validator.getInstance().unregister(100, myFn)
+     * @example Validator.getInstance().unregister(100, {
+     *     fieldA: () => valueA > 0,
+     *     fieldB: () => valueB !== '',
+     * })
      */
-    unregister(code: number, fn: ValidationFn): void;
+    unregister(code: number, rules: ValidationFn): void;
+    unregister(code: number, rules: ValidationRules): void;
     /**
      * Executa todas as funções de validação registradas para o código informado.
      * Lança um erro se qualquer função retornar `false`.
      * Se não houver validações registradas para o código, retorna silenciosamente.
-     * @example Validator.getInstance().execute(100)
+     * @example await Validator.getInstance().execute(100)
      * @throws {Error} Se alguma validação falhar.
      */
-    execute(code: number): void;
+    execute(code: number): Promise<void>;
     /**
      * Remove todas as funções de validação de um código específico, ou limpa todos os registros se nenhum código for informado.
      * @example