@adatechnology/conversations-ui 0.1.0-rc.3 → 0.1.0-rc.30

package/src/flows/flowEditorOps.test.ts

@@ -0,0 +1,241 @@
+/**
+ * Copyright (c) 2026 Ada Technology. MIT License.
+ *
+ * Estas funções decidem o que acontece com o fluxo que alguém desenhou, e o modo de falhar delas é
+ * silencioso: aresta apontando para nó apagado não dá erro no editor — dá conversa travada no meio
+ * para o cliente. Salto para nó do meio de outro fluxo não dá erro — o motor simplesmente ignora, e
+ * o atendimento para sem ninguém entender.
+ *
+ * São puras de propósito: rodam sem navegador, sem React e sem estado, o que é exatamente o que
+ * faltava enquanto elas viviam dentro de uma página de 973 linhas.
+ */
+
+import { describe, expect, it } from 'bun:test'
+import type { FlowGraphData, FlowNodeData } from '@adatechnology/meta-whatsapp-contracts'
+
+import {
+  applyConnection,
+  isGraphDirty,
+  mergedFlowKeysFrom,
+  namespaceNodeId,
+  parseNamespacedId,
+  removeNodeAndCleanRefs,
+  resolveConnection,
+} from './flowEditorOps'
+
+/** Nó mínimo VÁLIDO pelo contrato — sem `as`, para o teste falhar se a forma do nó mudar. */
+function node(id: string, next?: FlowNodeData['next']): FlowNodeData {
+  return { id, type: 'question', question: id, ...(next === undefined ? {} : { next }) }
+}
+
+/**
+ * Grafo mínimo VÁLIDO. `key` e `version` são obrigatórios no contrato, e sem `as` o teste passa a
+ * quebrar quando o contrato ganhar campo novo — que é exatamente o drift que o comentário do
+ * `flowGraph.ts` registra ter acontecido antes com o `version`.
+ */
+function graph(params: { key: string; start: string; nodes: FlowNodeData[] }): FlowGraphData {
+  return {
+    key: params.key,
+    label: params.key,
+    version: 1,
+    startNodeId: params.start,
+    nodes: Object.fromEntries(params.nodes.map((each) => [each.id, each])),
+  }
+}
+
+describe('id no canvas mesclado', () => {
+  it('vai e volta', () => {
+    expect(parseNamespacedId(namespaceNodeId('menu', 'inicio'))).toEqual({ flowKey: 'menu', nodeId: 'inicio' })
+  })
+
+  it('nó com separador no próprio id não parte errado', () => {
+    // O separador aparece no PRIMEIRO índice: um id que contenha `::` continua íntegro.
+    expect(parseNamespacedId('menu::passo::dois')).toEqual({ flowKey: 'menu', nodeId: 'passo::dois' })
+  })
+
+  it('id sem prefixo devolve fluxo vazio, em vez de adivinhar', () => {
+    expect(parseNamespacedId('inicio')).toEqual({ flowKey: '', nodeId: 'inicio' })
+  })
+})
+
+describe('apagar nó limpa quem apontava para ele', () => {
+  it('saída única que ia para o apagado fica vazia, não pendurada', () => {
+    const nodes = { a: node('a', 'b'), b: node('b') }
+
+    const result = removeNodeAndCleanRefs(nodes, 'b')
+
+    expect(Object.keys(result)).toEqual(['a'])
+    // Vazio e não `'b'`: aresta para nó inexistente trava a conversa no motor do bot.
+    expect(result.a?.next).toBe('')
+  })
+
+  it('ramificação perde o destino mas MANTÉM a opção', () => {
+    const nodes = {
+      pergunta: node('pergunta', { byAnswer: { sim: 'aprovado', nao: 'recusado' }, default: 'aprovado' }),
+      aprovado: node('aprovado'),
+      recusado: node('recusado'),
+    }
+
+    const result = removeNodeAndCleanRefs(nodes, 'aprovado')
+    const next = result.pergunta?.next as { byAnswer: Record<string, string>; default: string }
+
+    // A chave `sim` continua existindo com destino vazio: removê-la esconderia da tela que a opção
+    // existe e não leva a lugar nenhum, e alguém publicaria assim.
+    expect(next.byAnswer).toEqual({ sim: '', nao: 'recusado' })
+    expect(next.default).toBe('')
+  })
+
+  it('não mexe em quem não apontava para o apagado', () => {
+    const nodes = { a: node('a', 'c'), b: node('b'), c: node('c') }
+
+    expect(removeNodeAndCleanRefs(nodes, 'b').a?.next).toBe('c')
+  })
+
+  it('nó sem next segue sem next, e não ganha um vazio', () => {
+    expect(removeNodeAndCleanRefs({ a: node('a'), b: node('b') }, 'b').a?.next).toBeUndefined()
+  })
+})
+
+describe('fecho transitivo dos fluxos abertos juntos', () => {
+  const graphs = {
+    menu: graph({ key: 'menu', start: 'inicio', nodes: [node('inicio', 'flow:simulacao')] }),
+    simulacao: graph({ key: 'simulacao', start: 's1', nodes: [node('s1', 'flow:documentos')] }),
+    documentos: graph({ key: 'documentos', start: 'd1', nodes: [node('d1')] }),
+    orfao: graph({ key: 'orfao', start: 'o1', nodes: [node('o1')] }),
+  }
+
+  it('alcança em profundidade e ignora quem ninguém referencia', () => {
+    expect([...mergedFlowKeysFrom('menu', graphs)].sort()).toEqual(['documentos', 'menu', 'simulacao'])
+  })
+
+  it('ciclo não estoura — menu que volta ao menu é o caso mais comum que existe', () => {
+    const cyclic = {
+      menu: graph({ key: 'menu', start: 'i', nodes: [node('i', 'flow:sub')] }),
+      sub: graph({ key: 'sub', start: 's', nodes: [node('s', 'flow:menu')] }),
+    }
+
+    expect([...mergedFlowKeysFrom('menu', cyclic)].sort()).toEqual(['menu', 'sub'])
+  })
+
+  it('referência para fluxo que não existe é ignorada em vez de abrir aba vazia', () => {
+    const dangling = { menu: graph({ key: 'menu', start: 'i', nodes: [node('i', 'flow:apagado')] }) }
+
+    expect(mergedFlowKeysFrom('menu', dangling)).toEqual(['menu'])
+  })
+})
+
+describe('conectar aresta', () => {
+  const graphs = {
+    menu: graph({ key: 'menu', start: 'inicio', nodes: [node('inicio'), node('meio')] }),
+    simulacao: graph({ key: 'simulacao', start: 's1', nodes: [node('s1'), node('s2')] }),
+  }
+
+  it('dentro do mesmo fluxo grava o id local', () => {
+    const resolved = resolveConnection({
+      connection: { source: 'menu::inicio', target: 'menu::meio' },
+      graphs,
+    })
+
+    expect(resolved).toMatchObject({ flowKey: 'menu', nodeId: 'inicio', targetValue: 'meio' })
+  })
+
+  it('para o nó INICIAL de outro fluxo grava o salto `flow:`', () => {
+    const resolved = resolveConnection({
+      connection: { source: 'menu::inicio', target: 'simulacao::s1' },
+      graphs,
+    })
+
+    expect(resolved?.targetValue).toBe('flow:simulacao')
+  })
+
+  it('para o MEIO de outro fluxo é RECUSADO — o motor não sabe pular para lá', () => {
+    // Recusa silenciosa é melhor que gravar um salto que o bot ignora em produção: o sintoma seria
+    // conversa parada, longe de quem editou.
+    const resolved = resolveConnection({
+      connection: { source: 'menu::inicio', target: 'simulacao::s2' },
+      graphs,
+    })
+
+    expect(resolved).toBeUndefined()
+  })
+
+  it('nó em si mesmo é recusado', () => {
+    expect(
+      resolveConnection({ connection: { source: 'menu::inicio', target: 'menu::inicio' }, graphs }),
+    ).toBeUndefined()
+  })
+
+  it('fluxo de destino inexistente é recusado', () => {
+    expect(resolveConnection({ connection: { source: 'menu::inicio', target: 'sumiu::x' }, graphs })).toBeUndefined()
+  })
+})
+
+describe('aplicar a conexão no nó', () => {
+  it('handle `next` vira saída única', () => {
+    const result = applyConnection(node('a'), { flowKey: 'menu', nodeId: 'a', handle: 'next', targetValue: 'b' })
+
+    expect(result.next).toBe('b')
+  })
+
+  it('handle de resposta acrescenta no byAnswer e PRESERVA o resto', () => {
+    const existing = node('a', { byAnswer: { sim: 'x' }, default: 'y' })
+
+    const result = applyConnection(existing, { flowKey: 'menu', nodeId: 'a', handle: 'nao', targetValue: 'z' })
+    const next = result.next as { byAnswer: Record<string, string>; default: string }
+
+    expect(next.byAnswer).toEqual({ sim: 'x', nao: 'z' })
+    // O default não pode ser perdido ao ligar um ramo: seria mudança silenciosa de comportamento.
+    expect(next.default).toBe('y')
+  })
+
+  it('handle `__default` troca só o default', () => {
+    const existing = node('a', { byAnswer: { sim: 'x' }, default: 'y' })
+
+    const next = applyConnection(existing, { flowKey: 'menu', nodeId: 'a', handle: '__default', targetValue: 'z' })
+      .next as { byAnswer: Record<string, string>; default: string }
+
+    expect(next).toEqual({ byAnswer: { sim: 'x' }, default: 'z' })
+  })
+
+  it('ramificar um nó que tinha saída única não carrega a antiga como default', () => {
+    // A saída única vira ramificação: o default nasce vazio, e a validação do grafo cobra. Herdar a
+    // antiga faria o ramo não configurado seguir para onde o nó ia antes, sem ninguém pedir.
+    const next = applyConnection(node('a', 'antigo'), {
+      flowKey: 'menu',
+      nodeId: 'a',
+      handle: 'sim',
+      targetValue: 'novo',
+    }).next as { byAnswer: Record<string, string>; default: string }
+
+    expect(next).toEqual({ byAnswer: { sim: 'novo' }, default: '' })
+  })
+})
+
+describe('rascunho sujo', () => {
+  const published = graph({ key: 'menu', start: 'i', nodes: [node('i', 'b'), node('b')] })
+
+  it('igual ao publicado não está sujo', () => {
+    expect(isGraphDirty(structuredClone(published), published)).toBe(false)
+  })
+
+  it('texto mudado está sujo', () => {
+    const working = structuredClone(published)
+    working.nodes.i!.question = 'outro'
+
+    expect(isGraphDirty(working, published)).toBe(true)
+  })
+
+  it('posição mudada TAMBÉM está sujo — arrastar card é edição que se publica', () => {
+    const working = structuredClone(published)
+    working.nodes.i!.position = { x: 10, y: 20 }
+
+    expect(isGraphDirty(working, published)).toBe(true)
+  })
+
+  it('sem rascunho ou sem publicado não está sujo, em vez de sujo por ausência', () => {
+    // Durante o carregamento os dois lados chegam separados; sujo aqui faria a tela pedir
+    // confirmação de descarte antes de o usuário ter tocado em nada.
+    expect(isGraphDirty(undefined, published)).toBe(false)
+    expect(isGraphDirty(published, undefined)).toBe(false)
+  })
+})

package/src/flows/flowEditorOps.ts

@@ -0,0 +1,177 @@
+/**
+ * Copyright (c) 2026 Ada Technology. MIT License.
+ *
+ * Operações puras de grafo que o editor de fluxo precisa, e que viviam soltas dentro da página de
+ * 973 linhas do financiamento.
+ *
+ * Puras e separadas do hook de propósito: são a parte que dá para testar sem navegador, sem React e
+ * sem estado — e três delas (`removeNodeAndCleanRefs`, `resolveConnection`, `mergedFlowKeysFrom`)
+ * decidem o que acontece com o fluxo que alguém desenhou. Errar ali não dá erro; dá aresta apontando
+ * para nó que não existe mais, ou fluxo que some do canvas.
+ */
+
+// Os TIPOS do grafo vêm do meta-whatsapp-contracts, fonte única da verdade do trio
+// (`pluggable-module.md` §2) — mesmo motivo documentado em `flowGraph.ts`. `import type` puro: nada
+// do contracts entra por aqui em tempo de execução.
+import type { FlowGraphData, FlowNodeData, FlowNodeNext } from '@adatechnology/meta-whatsapp-contracts'
+
+// A constante vem do `flowGraph`, que já a define, e não do contracts: duas fontes do mesmo prefixo
+// divergem em silêncio, e o sintoma seria salto entre fluxos que o motor do bot não reconhece.
+import { CROSS_FLOW_PREFIX, crossFlowTargetsOf } from './flowGraph'
+
+const NAMESPACE_SEPARATOR = '::'
+
+/**
+ * Id de nó no canvas mesclado: vários fluxos dividem o mesmo espaço, e `boas-vindas` pode existir em
+ * dois deles. Sem o prefixo, arrastar um card moveria o homônimo do outro fluxo.
+ */
+export function namespaceNodeId(flowKey: string, nodeId: string): string {
+  return `${flowKey}${NAMESPACE_SEPARATOR}${nodeId}`
+}
+
+export function parseNamespacedId(value: string): { flowKey: string; nodeId: string } {
+  const index = value.indexOf(NAMESPACE_SEPARATOR)
+  // Sem separador é id de fluxo único — trata como do fluxo vazio para o chamador decidir.
+  if (index === -1) return { flowKey: '', nodeId: value }
+  return { flowKey: value.slice(0, index), nodeId: value.slice(index + NAMESPACE_SEPARATOR.length) }
+}
+
+/**
+ * Apaga o nó E as referências a ele.
+ *
+ * A limpeza não é cortesia: uma aresta apontando para nó inexistente faz o motor do bot parar a
+ * conversa no meio, e o sintoma aparece para o cliente, não para quem editou.
+ */
+export function removeNodeAndCleanRefs(
+  nodes: Readonly<Record<string, FlowNodeData>>,
+  removedId: string,
+): Record<string, FlowNodeData> {
+  const remaining: Record<string, FlowNodeData> = {}
+
+  for (const [id, node] of Object.entries(nodes)) {
+    if (id === removedId) continue
+    remaining[id] = { ...node, next: cleanNext(node.next, removedId) }
+  }
+
+  return remaining
+}
+
+function cleanNext(next: FlowNodeNext | undefined, removedId: string): FlowNodeNext | undefined {
+  if (next === undefined) return undefined
+  if (typeof next === 'string') return next === removedId ? '' : next
+
+  const byAnswer: Record<string, string> = {}
+  for (const [answer, target] of Object.entries(next.byAnswer ?? {})) {
+    // Resposta que levava ao nó apagado fica com destino vazio, e não é removida: apagar a chave
+    // esconderia da tela que aquela opção existe e não vai a lugar nenhum.
+    byAnswer[answer] = target === removedId ? '' : target
+  }
+
+  return { byAnswer, default: next.default === removedId ? '' : (next.default ?? '') }
+}
+
+/**
+ * O fecho transitivo dos fluxos alcançáveis a partir de um — é o conjunto que o canvas abre junto.
+ *
+ * BFS e não recursão: fluxo que referencia a si mesmo (menu que volta ao menu) é comum, e recursão
+ * ingênua estouraria a pilha no caso mais banal que existe.
+ */
+export function mergedFlowKeysFrom(
+  rootKey: string,
+  graphs: Readonly<Record<string, FlowGraphData>>,
+): readonly string[] {
+  const visited = new Set<string>()
+  const queue = [rootKey]
+
+  while (queue.length > 0) {
+    const key = queue.shift()!
+    if (visited.has(key) || !graphs[key]) continue
+    visited.add(key)
+    for (const target of crossFlowTargetsOf(graphs[key]!)) {
+      if (!visited.has(target) && graphs[target]) queue.push(target)
+    }
+  }
+
+  return [...visited]
+}
+
+export type ConnectionRequest = {
+  readonly source: string
+  readonly target: string
+  readonly sourceHandle?: string | null | undefined
+}
+
+export type ResolvedConnection = {
+  readonly flowKey: string
+  readonly nodeId: string
+  readonly handle: string
+  /** O que gravar no `next`: id de nó local, ou `flow:<key>` quando atravessa fluxo. */
+  readonly targetValue: string
+}
+
+/**
+ * Traduz um arraste de aresta no valor que vai para o `next` — e recusa o que o motor do bot não
+ * sabe executar.
+ *
+ * A regra que não é óbvia: conectar num nó de OUTRO fluxo só funciona se for o nó inicial dele,
+ * porque o motor só sabe pular para o começo de um fluxo, não para um nó do meio. Conectar no meio
+ * devolve `undefined` — recusa silenciosa é melhor que gravar um salto que o bot vai ignorar em
+ * produção, deixando a conversa parada sem ninguém entender por quê.
+ */
+export function resolveConnection(params: {
+  readonly connection: ConnectionRequest
+  readonly graphs: Readonly<Record<string, FlowGraphData>>
+}): ResolvedConnection | undefined {
+  const { source, target, sourceHandle } = params.connection
+  if (!source || !target || source === target) return undefined
+
+  const sourceRef = parseNamespacedId(source)
+  const targetRef = parseNamespacedId(target)
+
+  let targetValue: string
+  if (targetRef.flowKey === sourceRef.flowKey) {
+    targetValue = targetRef.nodeId
+  } else {
+    const targetGraph = params.graphs[targetRef.flowKey]
+    if (!targetGraph || targetGraph.startNodeId !== targetRef.nodeId) return undefined
+    targetValue = `${CROSS_FLOW_PREFIX}${targetRef.flowKey}`
+  }
+
+  return {
+    flowKey: sourceRef.flowKey,
+    nodeId: sourceRef.nodeId,
+    handle: sourceHandle ?? 'next',
+    targetValue,
+  }
+}
+
+/** Aplica a conexão resolvida no nó. `next` string para saída única, objeto para ramificação. */
+export function applyConnection(node: FlowNodeData, resolved: ResolvedConnection): FlowNodeData {
+  const currentNext = typeof node.next === 'object' && node.next ? node.next : undefined
+
+  if (resolved.handle === 'next') return { ...node, next: resolved.targetValue }
+
+  if (resolved.handle === '__default') {
+    return { ...node, next: { byAnswer: currentNext?.byAnswer ?? {}, default: resolved.targetValue } }
+  }
+
+  return {
+    ...node,
+    next: {
+      byAnswer: { ...(currentNext?.byAnswer ?? {}), [resolved.handle]: resolved.targetValue },
+      default: currentNext?.default ?? '',
+    },
+  }
+}
+
+/**
+ * Um fluxo está sujo quando o rascunho difere do publicado.
+ *
+ * Comparação estrutural por JSON: é grosseira, e é suficiente porque o grafo é dado serializável sem
+ * ordem significativa de chave — o servidor devolve o que gravou. Comparar campo a campo daria a
+ * mesma resposta com mais código para errar.
+ */
+export function isGraphDirty(working: FlowGraphData | undefined, published: FlowGraphData | undefined): boolean {
+  if (!working || !published) return false
+  return JSON.stringify(working) !== JSON.stringify(published)
+}

package/src/flows/flowGraph.ts

@@ -13,6 +13,7 @@ import type {
   FlowNodeData,
   FlowGraphData,
 } from '@adatechnology/meta-whatsapp-contracts'
+import { FLOW_ACTION_KIND } from '@adatechnology/meta-whatsapp-contracts'
 
 export type {
   FlowNodeType,
@@ -28,11 +29,10 @@ export const CONDITION_OPERATORS: FlowConditionOperator[] = ['>', '>=', '<', '<=
 
 // Kinds de ação genéricos que o pacote conhece de fábrica — o host pode registrar quaisquer
 // outros via `actionKindLabels`/`actionKinds` nos componentes (ver FlowPalette, labels.ts).
-export const BUILT_IN_ACTION_KINDS = {
-  HANDOFF: 'handoff',
-  RATE_LIMITED_HANDOFF: 'rate_limited_handoff',
-  SEND_PRODUCT_LIST: 'send_product_list',
-} as const
+// Reexporta o vocabulário do contrato em vez de redeclarar os literais: o editor oferece na
+// paleta exatamente os `actionKind` que o backend sabe interpretar, e duas listas separadas
+// divergiriam em silêncio (um nó publicável que nenhum handler atende).
+export const BUILT_IN_ACTION_KINDS = FLOW_ACTION_KIND
 
 // Destinos "flow:<key>" são saltos para outro fluxo, resolvidos pelo motor do host. Duplicado
 // (em vez de importado do contracts) de propósito: são três linhas triviais e importá-las como
@@ -372,7 +372,7 @@ export function findCollectionChains(graph: FlowGraphData): CollectionChain[] {
 }
 
 // Gera um id de nó único e legível a partir do rótulo (ex.: "Qual sua renda?" → "qual_sua_renda").
-export function slugifyNodeId(label: string, existing: Set<string>): string {
+export function slugifyNodeId(label: string, existing: ReadonlySet<string>): string {
   const base =
     label
       .toLowerCase()

package/src/flows/index.ts

@@ -9,6 +9,7 @@ export { FlowPortalNode, flowPortalNodeTypes } from './FlowPortalNode'
 export { FlowPalette } from './FlowPalette'
 export { FlowNodePanel } from './FlowNodePanel'
 export { FlowWhatsAppPreview } from './FlowWhatsAppPreview'
+export { FlowsWorkspace } from './FlowsWorkspace'
 
 export { DEFAULT_FLOW_EDITOR_LABELS, mergeFlowEditorLabels } from './labels'
 
@@ -43,7 +44,8 @@ export type {
   CollectionChain,
 } from './flowGraph'
 
-export type { FlowEditorLabels } from './labels'
+export type { FlowEditorLabels, FlowValidationLabels } from './labels'
+export type { FlowsWorkspaceProps, FlowsWorkspaceApi, FlowLivePosition, CreateFlowInput } from './FlowsWorkspace'
 export type { FlowNodeCardData } from './FlowNodeCard'
 export type { FlowMapNodeData } from './FlowMapNode'
 export type { FlowMapCanvasProps } from './FlowMapCanvas'
@@ -53,3 +55,40 @@ export type { FlowPortalNodeData } from './FlowPortalNode'
 export type { FlowPaletteProps, FlowPaletteActionOption, NewNodeSpec } from './FlowPalette'
 export type { FlowNodePanelProps } from './FlowNodePanel'
 export type { FlowWhatsAppPreviewProps } from './FlowWhatsAppPreview'
+
+/**
+ * Operações do EDITOR de fluxo, puras. Vinham soltas dentro da página de 973 linhas do
+ * financiamento; são a base do `FlowsWorkspace` (ADR 0002) e a parte que carrega o risco de perder
+ * trabalho de quem edita.
+ */
+export {
+  applyConnection,
+  isGraphDirty,
+  mergedFlowKeysFrom,
+  namespaceNodeId,
+  parseNamespacedId,
+  removeNodeAndCleanRefs,
+  resolveConnection,
+} from './flowEditorOps'
+export type { ConnectionRequest, ResolvedConnection } from './flowEditorOps'
+
+/**
+ * Modelo do canvas: posições, arestas, contagem ao vivo e o nó novo da paleta.
+ *
+ * Exportado porque é consumido pelo `FlowsWorkspace` e tem teste próprio — as decisões daqui não dão
+ * erro quando erram, dão conversa parada e card fora da tela.
+ */
+export {
+  buildFlowEdges,
+  chainFrameBounds,
+  chainFrameNodeId,
+  computeMergedLayout,
+  countLiveByNode,
+  detachedNodeIds,
+  newNodeFromSpec,
+  portalNodeId,
+  GROUP_HEADER_NODE_ID,
+} from './flowCanvasModel'
+// `FlowLivePosition` já sai pelo `FlowsWorkspace`, que é onde o produto a encontra ao implementar a
+// api — exportar de novo aqui daria dois caminhos para o mesmo tipo.
+export type { FlowEdgeKind, FlowEdgeSpec, FlowNodePosition } from './flowCanvasModel'