@adatechnology/conversations-ui 0.1.0-rc.39 → 0.1.0-rc.40

package/src/flows/flowCanvasModel.ts

@@ -13,6 +13,7 @@
 import { namespaceNodeId, parseNamespacedId } from './flowEditorOps'
 import {
   NODE_CARD_WIDTH,
+  cascadeOrder,
   crossFlowKey,
   estimateNodeHeight,
   isCrossFlowTarget,
@@ -107,11 +108,12 @@ export function countLiveByNode(params: {
 }
 
 /**
- * Um layout só para TODOS os nós de TODOS os fluxos abertos juntos.
+ * Um layout só para TODOS os nós de TODOS os fluxos abertos juntos, na mesma cascata do fluxo
+ * único: um passo para a direita a cada avanço da conversa, um degrau para baixo a cada card.
  *
  * Posicionar cada fluxo à parte e deslocar não resolve: nada impede dois fluxos de ocuparem o mesmo
- * espaço, e a altura real de cada card é ignorada. Aqui o ranqueamento por BFS roda sobre o grafo
- * mesclado inteiro, com os saltos `flow:<key>` já resolvidos para o nó inicial do alvo.
+ * espaço, e a altura real de cada card é ignorada. Aqui a travessia roda sobre o grafo mesclado
+ * inteiro, com os saltos `flow:<key>` já resolvidos para o nó inicial do alvo.
  */
 export function computeMergedLayout(params: {
   readonly openKeys: readonly string[]
@@ -128,7 +130,10 @@ export function computeMergedLayout(params: {
     }
   }
 
-  function forwardEdges(flowKey: string, node: FlowNodeData): string[] {
+  function forwardEdges(id: string): string[] {
+    const node = nodeById.get(id)
+    if (!node) return []
+    const flowKey = parseNamespacedId(id).flowKey
     const result: string[] = []
 
     for (const { target } of targetsOf(node)) {
@@ -144,49 +149,19 @@ export function computeMergedLayout(params: {
     return result
   }
 
-  const rank = new Map<string, number>()
   const primaryGraph = graphs[primaryFlowKey]
-  const rootId = primaryGraph ? namespaceNodeId(primaryFlowKey, primaryGraph.startNodeId) : undefined
-
-  if (rootId && nodeById.has(rootId)) {
-    rank.set(rootId, 0)
-    const queue = [rootId]
-    while (queue.length > 0) {
-      const id = queue.shift()!
-      const node = nodeById.get(id)
-      if (!node) continue
-      for (const nextId of forwardEdges(parseNamespacedId(id).flowKey, node)) {
-        if (!rank.has(nextId)) {
-          rank.set(nextId, rank.get(id)! + 1)
-          queue.push(nextId)
-        }
-      }
-    }
-  }
-
-  // Todo nó não alcançado vai para UMA coluna extra depois de tudo. Uma coluna por órfão empurrava
-  // cada um mais para longe da área visível — e desligar um fio se lia como "o card sumiu".
-  const strayRank = Math.max(0, ...rank.values()) + 1
-  for (const id of nodeById.keys()) {
-    if (!rank.has(id)) rank.set(id, strayRank)
-  }
-
-  const layers = new Map<number, string[]>()
-  for (const [id, value] of rank) {
-    const layer = layers.get(value)
-    if (layer) layer.push(id)
-    else layers.set(value, [id])
-  }
+  const placed = cascadeOrder({
+    rootId: primaryGraph ? namespaceNodeId(primaryFlowKey, primaryGraph.startNodeId) : '',
+    allIds: [...nodeById.keys()],
+    forwardEdges,
+  })
 
   const positions = new Map<string, FlowNodePosition>()
-  for (const value of [...layers.keys()].sort((a, b) => a - b)) {
-    // Alinhado pelo topo, e não centralizado: coluna centralizada saltava inteira a cada nó a mais
-    // num ramo qualquer.
-    let cursorY = 0
-    for (const id of layers.get(value)!) {
-      positions.set(id, { x: value * COLUMN_GAP, y: cursorY })
-      cursorY += estimateNodeHeight(nodeById.get(id)!) + ROW_GAP
-    }
+  let cursorY = 0
+
+  for (const [id, { depth }] of [...placed.entries()].sort((a, b) => a[1].order - b[1].order)) {
+    positions.set(id, { x: depth * COLUMN_GAP, y: cursorY })
+    cursorY += estimateNodeHeight(nodeById.get(id)!) + ROW_GAP
   }
 
   return positions
@@ -256,6 +231,11 @@ export function buildFlowEdges(params: {
         const source = namespaceNodeId(flowKey, nodeId)
         const edgeTarget = namespaceNodeId(targetFlowKey, targetNodeId)
 
+        // Voltar ao próprio card não é trajeto, é comportamento — e como aresta não tem onde
+        // caber: por baixo some atrás do card, por cima o cobre. Quem mostra isso é o ícone de
+        // repetição na linha de saída, dentro do card (ver `FlowNodeCard`).
+        if (source === edgeTarget) continue
+
         if (isDefault) {
           edges.push({
             id: `${source}->${edgeTarget}-default`,
@@ -366,3 +346,33 @@ export function newNodeFromSpec(spec: NewNodeSpec, existingIds: ReadonlySet<stri
   const id = slugifyNodeId('nova_acao', existingIds)
   return { id, type: 'action', actionKind: spec.actionKind }
 }
+
+/** Distância vertical mínima entre dois cards para que não se leiam como um só. */
+const FREE_SLOT_STEP = 120
+
+/**
+ * Empurra a posição para baixo até achar espaço livre na mesma coluna.
+ *
+ * O "+" põe o nó novo à direita de quem o criou — e é justamente ali que costuma estar o nó que
+ * acabou de perder a ligação. Sem isto, os dois se sobrepõem e a tela mostra um card onde há dois,
+ * que é o mesmo susto de "sumiu" por outro caminho.
+ */
+export function findFreeSlot(params: {
+  readonly desired: FlowNodePosition
+  readonly taken: readonly FlowNodePosition[]
+  readonly step?: number
+}): FlowNodePosition {
+  const step = params.step ?? FREE_SLOT_STEP
+  const isOccupied = (candidate: FlowNodePosition) =>
+    params.taken.some(
+      (each) => Math.abs(each.x - candidate.x) < NODE_CARD_WIDTH && Math.abs(each.y - candidate.y) < step,
+    )
+
+  let slot = params.desired
+  // Teto igual ao número de cards: com N ocupados, N descidas bastam para sair de todos.
+  for (let attempt = 0; attempt <= params.taken.length && isOccupied(slot); attempt += 1) {
+    slot = { x: slot.x, y: slot.y + step }
+  }
+
+  return slot
+}

package/src/flows/flowEditorOps.test.ts

@@ -15,6 +15,7 @@ import type { FlowGraphData, FlowNodeData } from '@adatechnology/meta-whatsapp-c
 
 import {
   applyConnection,
+  clearConnection,
   isGraphDirty,
   mergedFlowKeysFrom,
   namespaceNodeId,
@@ -239,3 +240,37 @@ describe('rascunho sujo', () => {
     expect(isGraphDirty(published, undefined)).toBe(false)
   })
 })
+
+/**
+ * Desligar um fio é a operação que o relato de campo pegou errada: o card sumia. Some porque a
+ * opção deixa de existir no `byAnswer`, não porque alguém apagou o nó — e o teste fixa isso.
+ */
+describe('clearConnection', () => {
+  it('saída única vira destino vazio, e o nó continua lá', () => {
+    expect(clearConnection(node('a', 'b'), 'next').next).toBe('')
+  })
+
+  it('desligar uma opção NÃO apaga a chave — a opção sumindo levaria junto o botão do WhatsApp', () => {
+    const branching = node('a', { byAnswer: { sim: 'b', nao: 'c' }, default: 'd' })
+
+    const result = clearConnection(branching, 'sim')
+
+    expect(result.next).toEqual({ byAnswer: { sim: '', nao: 'c' }, default: 'd' })
+  })
+
+  it('desligar o fallback preserva as opções', () => {
+    const branching = node('a', { byAnswer: { sim: 'b' }, default: 'd' })
+
+    expect(clearConnection(branching, '__default').next).toEqual({ byAnswer: { sim: 'b' }, default: '' })
+  })
+
+  it('handle inexistente não inventa ramificação nem derruba as existentes', () => {
+    const branching = node('a', { byAnswer: { sim: 'b' }, default: 'd' })
+
+    expect(clearConnection(branching, 'talvez').next).toEqual({ byAnswer: { sim: 'b', talvez: '' }, default: 'd' })
+  })
+
+  it('nó sem next algum não quebra', () => {
+    expect(clearConnection(node('a'), 'next').next).toBe('')
+  })
+})

package/src/flows/flowEditorOps.ts

@@ -175,3 +175,28 @@ export function isGraphDirty(working: FlowGraphData | undefined, published: Flow
   if (!working || !published) return false
   return JSON.stringify(working) !== JSON.stringify(published)
 }
+
+/**
+ * Desliga UMA saída do nó, preservando as outras.
+ *
+ * O que não é óbvio: desligar é gravar destino vazio, nunca apagar a chave. Numa ramificação, a
+ * opção sem `byAnswer` some do card — e some junto o botão que o cliente via no WhatsApp, o que se
+ * lê como "o editor apagou minha opção". Vazio mantém a linha visível, cobrando a religação.
+ */
+export function clearConnection(node: FlowNodeData, handle: string): FlowNodeData {
+  if (handle === 'next' || typeof node.next === 'string' || node.next === undefined) {
+    return { ...node, next: '' }
+  }
+
+  if (handle === '__default') {
+    return { ...node, next: { byAnswer: node.next.byAnswer ?? {}, default: '' } }
+  }
+
+  return {
+    ...node,
+    next: {
+      byAnswer: { ...(node.next.byAnswer ?? {}), [handle]: '' },
+      default: node.next.default ?? '',
+    },
+  }
+}

package/src/flows/flowGraph.ts

@@ -38,6 +38,16 @@ export const BUILT_IN_ACTION_KINDS = FLOW_ACTION_KIND
 // (em vez de importado do contracts) de propósito: são três linhas triviais e importá-las como
 // valor puxaria o runtime do contracts para o bundle do frontend só por causa disso. O contracts
 // exporta as mesmas funções para o backend; a convenção "flow:" é o contrato de fato.
+/**
+ * Ações depois das quais a conversa CONTINUA no grafo, em vez de terminar.
+ *
+ * A distinção não é estética: o motor do bot só anda para o `next` depois de `send_media` — as
+ * demais ações (handoff, encerrar, simular, catálogo) encerram o passo ali. Dar saída a uma ação
+ * que o motor não atravessa desenharia um fio que o bot ignora em produção, deixando a conversa
+ * parada sem ninguém entender por quê — o mesmo erro que `resolveConnection` recusa cometer.
+ */
+export const PASS_THROUGH_ACTION_KINDS: readonly string[] = ['send_media']
+
 export const CROSS_FLOW_PREFIX = 'flow:'
 export const isCrossFlowTarget = (target: string): boolean => target.startsWith(CROSS_FLOW_PREFIX)
 export const crossFlowKey = (target: string): string => target.slice(CROSS_FLOW_PREFIX.length)
@@ -54,7 +64,10 @@ export function estimateNodeHeight(node: FlowNodeData): number {
   const ROW_HEIGHT = 34
   const rowCount =
     node.type === 'action'
-      ? 0
+      ? // Ação de passagem desenha uma linha de saída; terminal não desenha nenhuma.
+        node.actionKind && PASS_THROUGH_ACTION_KINDS.includes(node.actionKind)
+        ? 1
+        : 0
       : node.type === 'condition'
         ? 2
         : node.type === 'menu' || node.questionType === 'choice'
@@ -206,59 +219,71 @@ function findUnreachable(graph: FlowGraphData): string[] {
   return Object.keys(graph.nodes).filter((id) => !reachable.has(id))
 }
 
-// Auto-layout hierárquico (sem dependência externa): ranqueia por BFS a partir do início,
-// distribui cada camada horizontalmente e centraliza. Suficiente para fluxos de conversa
-// (grafos rasos, quase-árvores) sem puxar uma lib de layout inteira.
-export function computeAutoLayout(graph: FlowGraphData): Record<string, { x: number; y: number }> {
-  const H_GAP = 300
-  // Espaço extra entre a camada mais alta de uma linha e a próxima linha, além da altura real
-  // do card mais alto dela — sem isso, um menu com várias opções (card bem mais alto) encostaria
-  // na camada de baixo mesmo com um gap fixo pensado pra cards curtos.
-  const V_GAP = 90
-  const rank: Record<string, number> = {}
-  const queue: string[] = [graph.startNodeId]
-  rank[graph.startNodeId] = 0
-
-  while (queue.length > 0) {
-    const id = queue.shift()!
-    const node = graph.nodes[id]
-    if (!node) continue
-    for (const { target } of targetsOf(node)) {
-      if (isCrossFlowTarget(target) || !graph.nodes[target]) continue
-      if (rank[target] === undefined) {
-        rank[target] = rank[id]! + 1
-        queue.push(target)
-      }
-    }
+/** Distância horizontal entre um card e o seguinte na cascata. */
+export const LAYOUT_COLUMN_GAP = 300
+/** Folga vertical entre um card e o de baixo, somada à altura real do de cima. */
+export const LAYOUT_ROW_GAP = 40
+
+/**
+ * Ordem de leitura do grafo: profundidade primeiro, seguindo as saídas na ordem em que o card as
+ * mostra.
+ *
+ * Profundidade, e não largura, porque é ela que mantém um caminho de conversa junto na tela — com
+ * BFS, os dois ramos de uma decisão se intercalam linha a linha e o olho perde qual leva a qual.
+ */
+export function cascadeOrder(params: {
+  readonly rootId: string
+  readonly allIds: readonly string[]
+  readonly forwardEdges: (id: string) => readonly string[]
+}): Map<string, { depth: number; order: number }> {
+  const placed = new Map<string, { depth: number; order: number }>()
+
+  function visit(id: string, depth: number): void {
+    if (placed.has(id)) return
+    placed.set(id, { depth, order: placed.size })
+    for (const next of params.forwardEdges(id)) visit(next, depth + 1)
   }
 
-  // Nós não alcançáveis vão para uma camada abaixo da última, na ordem em que aparecem.
-  const maxRank = Math.max(0, ...Object.values(rank))
-  let strayRank = maxRank + 1
-  for (const id of Object.keys(graph.nodes)) {
-    if (rank[id] === undefined) rank[id] = strayRank++
-  }
+  if (params.allIds.includes(params.rootId)) visit(params.rootId, 0)
 
-  const layers: Record<number, string[]> = {}
-  for (const [id, r] of Object.entries(rank)) {
-    layers[r] = [...(layers[r] ?? []), id]
+  // Órfãos entram depois, todos na mesma coluna extra: uma coluna por órfão empurrava cada um para
+  // mais longe da área visível, e desligar um fio se lia como "o card sumiu".
+  const strayDepth = Math.max(0, ...[...placed.values()].map((each) => each.depth)) + 1
+  for (const id of params.allIds) {
+    if (!placed.has(id)) placed.set(id, { depth: strayDepth, order: placed.size })
   }
 
+  return placed
+}
+
+/**
+ * Auto-layout em cascata: avança para a direita a cada passo do fluxo e desce a cada card.
+ *
+ * **Um card por linha, sempre.** Empilhar por camada — todos do mesmo nível na mesma coluna, todas
+ * as colunas começando na mesma altura — deixava os fios correndo na horizontal, e um fio horizontal
+ * passa por trás de qualquer card que esteja entre a origem e o destino. Descendo um degrau por
+ * card, toda ligação vira uma diagonal curta e visível, e o caminho da conversa se lê de cima para
+ * baixo enquanto avança da esquerda para a direita.
+ */
+export function computeAutoLayout(graph: FlowGraphData): Record<string, { x: number; y: number }> {
+  const placed = cascadeOrder({
+    rootId: graph.startNodeId,
+    allIds: Object.keys(graph.nodes),
+    forwardEdges: (id) =>
+      targetsOf(graph.nodes[id] ?? { id, type: 'action' })
+        .map((edge) => edge.target)
+        .filter((target) => !isCrossFlowTarget(target) && Boolean(graph.nodes[target])),
+  })
+
+  const byOrder = [...placed.entries()].sort((a, b) => a[1].order - b[1].order)
   const positions: Record<string, { x: number; y: number }> = {}
-  const sortedRanks = Object.keys(layers)
-    .map(Number)
-    .sort((a, b) => a - b)
-  let cumulativeY = 0
-  for (const r of sortedRanks) {
-    const ids = layers[r]!
-    const width = (ids.length - 1) * H_GAP
-    let maxHeight = 0
-    ids.forEach((id, index) => {
-      maxHeight = Math.max(maxHeight, estimateNodeHeight(graph.nodes[id]!))
-      positions[id] = { x: index * H_GAP - width / 2, y: cumulativeY }
-    })
-    cumulativeY += maxHeight + V_GAP
+  let cursorY = 0
+
+  for (const [id, { depth }] of byOrder) {
+    positions[id] = { x: depth * LAYOUT_COLUMN_GAP, y: cursorY }
+    cursorY += estimateNodeHeight(graph.nodes[id]!) + LAYOUT_ROW_GAP
   }
+
   return positions
 }
 

package/src/flows/index.ts

@@ -6,7 +6,9 @@ export { FlowMapCanvas } from './FlowMapCanvas'
 export { FlowGroupFrame, flowGroupFrameNodeTypes } from './FlowGroupFrame'
 export { FlowGroupHeader, flowGroupHeaderNodeTypes } from './FlowGroupHeader'
 export { FlowPortalNode, flowPortalNodeTypes } from './FlowPortalNode'
-export { FlowPalette } from './FlowPalette'
+export { FlowPalette, FlowPaletteMenu } from './FlowPalette'
+export { FlowLegend } from './FlowLegend'
+export { FlowConnectionEdge, flowEdgeTypes } from './FlowConnectionEdge'
 export { FlowNodePanel } from './FlowNodePanel'
 export { FlowWhatsAppPreview } from './FlowWhatsAppPreview'
 export { FlowsWorkspace } from './FlowsWorkspace'
@@ -16,6 +18,7 @@ export { DEFAULT_FLOW_EDITOR_LABELS, mergeFlowEditorLabels } from './labels'
 export {
   CONDITION_OPERATORS,
   BUILT_IN_ACTION_KINDS,
+  PASS_THROUGH_ACTION_KINDS,
   NODE_CARD_WIDTH,
   WHATSAPP_LIMITS,
   CROSS_FLOW_PREFIX,

package/src/flows/labels.ts

@@ -56,6 +56,25 @@ export interface FlowEditorLabels {
     media: string
     mediaUnavailable: string
   }
+  quickAdd: {
+    fromHandle: string
+    title: string
+    disconnect: string
+  }
+  /** Legenda do canvas: o que cada traço e cada contorno querem dizer. */
+  legendPanel: {
+    title: string
+    nodes: string
+    connections: string
+    linear: string
+    branch: string
+    fallback: string
+    crossFlow: string
+    live: string
+    selfLoop: string
+    detached: string
+    startNode: string
+  }
   palette: {
     title: string
     question: string
@@ -224,6 +243,24 @@ export const DEFAULT_FLOW_EDITOR_LABELS: FlowEditorLabels = {
     media: 'Arquivos enviados neste ponto',
     mediaUnavailable: 'A biblioteca de arquivos não está disponível neste painel.',
   },
+  quickAdd: {
+    fromHandle: 'Criar o próximo nó já ligado aqui',
+    title: 'Ligar em um nó novo',
+    disconnect: 'Desligar este fio (o nó continua no fluxo)',
+  },
+  legendPanel: {
+    title: 'Legenda',
+    nodes: 'Cards',
+    connections: 'Ligações',
+    linear: 'Segue direto para o próximo',
+    branch: 'Caminho de uma opção escolhida',
+    fallback: 'Quando a resposta não casa com nenhuma opção',
+    crossFlow: 'Salta para outro fluxo',
+    live: 'Tem conversa passando por aqui agora',
+    selfLoop: 'Volta ao mesmo card — repete a pergunta',
+    detached: 'Ninguém aponta para este card: o bot não chega nele',
+    startNode: 'Onde o fluxo começa',
+  },
   palette: {
     title: 'Adicionar ao fluxo',
     question: 'Pergunta',
@@ -316,6 +353,8 @@ export function mergeFlowEditorLabels(override?: Partial<FlowEditorLabels>): Flo
     },
     questionTypeLabels: { ...DEFAULT_FLOW_EDITOR_LABELS.questionTypeLabels, ...override.questionTypeLabels },
     nodePanel: { ...DEFAULT_FLOW_EDITOR_LABELS.nodePanel, ...override.nodePanel },
+    quickAdd: { ...DEFAULT_FLOW_EDITOR_LABELS.quickAdd, ...override.quickAdd },
+    legendPanel: { ...DEFAULT_FLOW_EDITOR_LABELS.legendPanel, ...override.legendPanel },
     palette: { ...DEFAULT_FLOW_EDITOR_LABELS.palette, ...override.palette },
     flowMap: { ...DEFAULT_FLOW_EDITOR_LABELS.flowMap, ...override.flowMap },
     flowGroup: { ...DEFAULT_FLOW_EDITOR_LABELS.flowGroup, ...override.flowGroup },