@adatechnology/conversations-ui 0.1.0-rc.27 → 0.1.0-rc.28

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

@@ -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

@@ -55,3 +55,19 @@ 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'

package/src/flows/workspaceContract.test.ts

@@ -0,0 +1,95 @@
+/**
+ * Copyright (c) 2026 Ada Technology. MIT License.
+ *
+ * O subpath `/flows` precisa exportar a TELA, não só as peças.
+ *
+ * Existe porque a ausência disso já custou: exportando apenas `FlowMapCanvas`, `FlowPalette` e
+ * `FlowNodePanel`, o financiamento montou a tela por conta — 973 linhas de página mais um fork local
+ * dos componentes, que ficou atrás do pacote. O quickcart, para ter a mesma tela, teria que copiar o
+ * arquivo. É exatamente a divergência que `pluggable-module.md` §4 proíbe.
+ *
+ * O teste é de superfície, não de comportamento: não prova que o canvas desenha certo, prova que
+ * existe UM lugar onde a tela mora, e que ela aceita customização por contrato em vez de por fork.
+ */
+
+import { describe, expect, it } from 'bun:test'
+
+import * as flows from './index'
+import { DEFAULT_FLOW_EDITOR_LABELS, mergeFlowEditorLabels } from './labels'
+
+const WORKSPACE_SOURCE = `${import.meta.dir}/FlowsWorkspace.tsx`
+
+describe('superfície composta', () => {
+  it('exporta a tela inteira', () => {
+    expect(typeof flows.FlowsWorkspace).toBe('function')
+  })
+
+  it('exporta as peças também — quem precisa de layout próprio não fica sem saída', () => {
+    // Workspace é o caminho recomendado, não uma prisão: um produto com layout radicalmente
+    // diferente compõe as peças, e isso é melhor que forkar o pacote.
+    for (const piece of ['FlowMapCanvas', 'FlowPalette', 'FlowNodePanel', 'FlowWhatsAppPreview']) {
+      expect(typeof (flows as Record<string, unknown>)[piece], piece).toBe('function')
+    }
+  })
+
+  it('as operações de grafo saem puras, sem passar pela tela', () => {
+    // São as que a tela consome de verdade (ver os imports em `FlowsWorkspace.tsx`). Exportá-las sem
+    // usá-las seria pior que não ter teste: teste verde sobre código que não roda em produção.
+    for (const operation of ['resolveConnection', 'applyConnection', 'removeNodeAndCleanRefs', 'mergedFlowKeysFrom']) {
+      expect(typeof (flows as Record<string, unknown>)[operation], operation).toBe('function')
+    }
+  })
+})
+
+describe('contrato de customização', () => {
+  it('nenhuma capacidade em forma de flag booleana `hasX`', async () => {
+    /**
+     * Capacidade opcional é por AUSÊNCIA de prop. `hasDelete` seria um segundo jeito de dizer o que
+     * `deletableFlowKeys` já diz, e dois jeitos divergem — alguém liga a flag sem a lista e a tela
+     * desenha um botão que não exclui nada.
+     */
+    const content = await Bun.file(WORKSPACE_SOURCE).text()
+
+    expect(content).not.toMatch(/readonly has[A-Z]/)
+  })
+
+  it('aceita labels, className e os slots de render', async () => {
+    const content = await Bun.file(WORKSPACE_SOURCE).text()
+
+    expect(content).toContain('labels?: Partial<')
+    // `className` é o que deixa o produto posicionar a tela no layout dele sem tocar no pacote.
+    expect(content).toContain('className?: string')
+    expect(content).toContain('renderMediaPicker?:')
+  })
+
+  it('nenhum texto visível escrito no componente — tudo passa por labels', async () => {
+    const content = await Bun.file(WORKSPACE_SOURCE).text()
+    /**
+     * Texto entre tags JSX que não seja `{...}`, que é o que `web.md` §6 proíbe.
+     *
+     * O `\s*` nas pontas não é detalhe: a primeira versão deste regex no notification-ui exigia o
+     * texto colado nas tags, e o Prettier põe o conteúdo em linha própria — o teste passava com
+     * `>\n  Configurações\n<` no meio do componente, provando nada.
+     */
+    const hardcoded = content.match(/>\s*[A-Za-zÀ-ÿ][A-Za-zÀ-ÿ ]{3,}\s*</g)
+
+    expect(hardcoded, `texto fixo: ${hardcoded?.join(' | ')}`).toBeNull()
+  })
+
+  it('o produto sobrescreve UM texto sem perder os outros do mesmo grupo', () => {
+    const merged = mergeFlowEditorLabels({ workspace: { ...DEFAULT_FLOW_EDITOR_LABELS.workspace, title: 'Jornadas' } })
+
+    expect(merged.workspace.title).toBe('Jornadas')
+    expect(merged.workspace.saveGraph).toBe(DEFAULT_FLOW_EDITOR_LABELS.workspace.saveGraph)
+  })
+
+  it('grupo novo de label entra no merge profundo', () => {
+    // Esquecer o grupo no `mergeFlowEditorLabels` deixa o override apagar os irmãos dele, e o
+    // sintoma é texto sumindo da tela — não erro.
+    for (const group of ['workspace', 'flowManager', 'validation', 'collectionChain'] as const) {
+      const merged = mergeFlowEditorLabels({ [group]: {} })
+
+      expect(Object.keys(merged[group]).length, group).toBe(Object.keys(DEFAULT_FLOW_EDITOR_LABELS[group]).length)
+    }
+  })
+})