mentors-data-mapper-ui

Editor visual canônico do Data Mapper do Mentors IPaaS (ADR-0005): biblioteca React embarcável que cobre 100% do contrato v3 da lib Java mentorstec-data-mapper — e é validada de ponta a ponta contra o runtime real.

• 10 tipos de operação: 1:1, N:1 (concatenado/objeto/array), 1:N (split), Para-cada (⟳), Condicional, Grupo estruturado, Agregação (Σ), Agrupar-por (BY), Junção (⋈) e Sub-mapping (ƒ)
• Recursos v3: condições compostas (AND/OR/NOT + 13 operadores), estágios de coleção (filter → distinct → sort → skip → limit), mapeamentos internos, formatação de saída, parâmetros $params IN/OUT e multi-source/multi-target com fontes nomeadas
• Edição: drag & drop com fio ao vivo na cor do tipo (Esc cancela), undo/redo, copiar/colar/recortar, exclusão, busca nos painéis, contador de mapeados, sugestões assistidas (IA) e import de schema (DDL SQL / lista)
• Tema: dark/light via tokens light-dark(), controlado pelo host
• Zero dependências de UI (peer deps: react, react-dom, reactflow)

Embedding

npm install mentors-data-mapper-ui

import {
  DataMapperEditor,
  loadCanonical,
  fromCanonical,
  toCanonical,
  serializeCanonical
} from 'mentors-data-mapper-ui';
import 'mentors-data-mapper-ui/styles.css';

function MeuEditor({ persisted }: { persisted: string | null }) {
  // Aceita o contrato canônico (JSON) e o formato legado (lista de nomes)
  const initial = loadCanonical(persisted);
  const restored = initial ? fromCanonical(initial) : null;

  const [mappings, setMappings] = useState(restored?.mappings ?? []);

  return (
    <DataMapperEditor
      contract={contract}                 // catálogo (ver Backend abaixo)
      sourceTree={restored?.sourceTree ?? []}
      targetTree={restored?.targetTree ?? []}
      mappings={mappings}
      colorScheme="dark"                  // segue o tema do host
      onMappingCreate={(m) => setMappings((curr) => [...curr, m])}
      onMappingChange={(m) => setMappings((curr) => curr.map((x) => (x.id === m.id ? m : x)))}
      onMappingsReorder={setMappings}
      onMappingsRestore={setMappings}     // habilita undo/redo
      onMappingDelete={(id) => setMappings((curr) => curr.filter((x) => x.id !== id))}
      onSave={(state) => {
        const canonical = toCanonical(state, { id: 'map-1', name: 'Meu mapeamento' });
        persistir(serializeCanonical(canonical));
      }}
    />
  );
}

Multi-source/multi-target: passe sources/targets (NamedTreeSet[] — id, árvore, formato) no lugar de sourceTree/targetTree; um painel é renderizado por fonte/destino e os mapeamentos criados por drag ganham sourceRef/targetRef.

Contratos e serialização

Três formatos coexistem no ecossistema — esta lib é a fonte dos dois primeiros:

| Formato | Função | API | |---|---|---| | Canônico (MappingConfig) | Persistência pelo host (no admin: MapeamentoDadoDto.origens); carrega schemas (inclusive por fonte nomeada), posições e o bloco v3 por mapeamento | toCanonical / fromCanonical / serializeCanonical / parseCanonical / loadCanonical (aceita legado) | | Runtime (MappingConfiguration flat) | O que o engine Java/CLI executa; implementação de referência da conversão que o backend faz | toRuntimeContract | | Export compacto | Apenas demo/E2E — não expressa v3 | serializeDemoExport |

Retrocompatibilidade: payloads antigos (sem bloco v3) carregam normalmente e leitores antigos ignoram os campos novos.

Backend

O editor é puro (props). A porta DataMapperBackend + createHttpBackend produzem as props a partir de qualquer backend:

import { createHttpBackend, assistedMappingProvider } from 'mentors-data-mapper-ui';

const backend = createHttpBackend({
  baseUrl: '/api/v1',
  headers: () => ({ Authorization: `Bearer ${token}` })
  // endpoints, mapContract e mapSuggestions adaptam backends com shapes próprios
});

const contract = await backend.loadContract();       // GET /datamapper/contract
const assisted = assistedMappingProvider(backend);    // POST /assist/suggest-mapping

Convenções padrão são as do Mentors IPaaS; outros backends entram por opção da fábrica ou implementando a interface diretamente.

Pontos de extensão

| Prop | Habilita | |---|---| | assistedMapping | Botão Sugerir + painel de sugestões (IA do host ou heurística) | | onSchemaImported | Diálogo embutido de import (DDL SQL / lista nome:tipo) | | onImportSchema | Delegação total do import ao host (ex.: YAML Embulk no admin) — tem precedência | | parameters / onParametersChange | Aba Contrato com parâmetros $params IN/OUT | | renderCanvas | Substituição completa do canvas |

Demo

npm install
npm run dev        # http://localhost:5173 — cenários: json-xml, csv-json,
                   # avro-protobuf, fan-in-out, pedidos-clientes (multi-source)

A demo expõe superfícies para validação automatizada:

• window.__DATA_MAPPER_LAST_SAVE__ — estado bruto do editor
• window.__DATA_MAPPER_LAST_CANONICAL__ — contrato canônico
• window.__DATA_MAPPER_LAST_RUNTIME__ — contrato de runtime (CLI-ready)
• window.__DATA_MAPPER_LAST_SERIALIZED__ — export compacto (legado da demo)

Testes

70 specs E2E (Playwright) + 32 unitários (Vitest) — incluindo a matriz de runtime: cada tipo de operação montado na interface e executado pelo CLI Java real, e combinações por complexidade (kitchen-sinks, joins multi-source com entradas nomeadas, condições aninhadas, parâmetros de saída via stderr).

npm run test:unit                  # Vitest (serialização, parsers, backend)
npx playwright test                # E2E completo
npx playwright test --headed --workers=1   # assistindo

Os specs de runtime exigem o CLI Java compilado (são pulados sem ele):

cd ../mentorstec-data-mapper
mvn -pl mentors-data-mapper-cli -am package -DskipTests
# caminho padrão: ../mentorstec-data-mapper/.../quarkus-run.jar
# override: DATA_MAPPER_CLI_JAR=/caminho/quarkus-run.jar

Build da lib

npm run build      # dist/index.js + dist/style.css + dist/types
npm run typecheck

Documentos

• docs/CONVERGENCIA-ADMIN.md — plano executado da convergência (F1–F5), decisões técnicas e gaps conhecidos
• ADR-0005 (repo mentorstec-data-integration-admin, docs/mentors-ipaas-openspec/docs/adr/) — decisão do editor canônico
• ADRs/RFCs do contrato: repo mentors-data-mapper, docs/ e openspec/