@adatechnology/conversations-ui 0.1.0-rc.9 → 0.1.1

package/src/flows/flowEditorOps.ts

@@ -0,0 +1,202 @@
+/**
+ * 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)
+}
+
+/**
+ * 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

@@ -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,16 +29,25 @@ 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
 // 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
 }
 
@@ -372,7 +397,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/flowMenuPlacement.test.ts

@@ -0,0 +1,130 @@
+/**
+ * Copyright (c) 2026 Ada Technology. MIT License.
+ *
+ * O caso que originou isto: o submenu "Ação" aberto perto do rodapé mostrava metade da lista, com
+ * "Enviar catálogo de produtos" cortado pela borda — e sem rolagem, o item era inalcançável.
+ */
+
+import { describe, expect, it } from 'bun:test'
+
+import { placeFloatingPanel } from './flowMenuPlacement'
+
+const VIEWPORT = { width: 1200, height: 800 }
+const rect = (left: number, top: number, width = 0, height = 0) => ({
+  left,
+  top,
+  right: left + width,
+  bottom: top + height,
+})
+
+describe('menu abaixo do ponto clicado', () => {
+  it('fica onde foi pedido quando há espaço', () => {
+    const placement = placeFloatingPanel({
+      anchor: rect(100, 100),
+      panel: { width: 256, height: 300 },
+      viewport: VIEWPORT,
+      prefer: 'below',
+    })
+
+    expect(placement.left).toBeGreaterThanOrEqual(100)
+    expect(placement.top).toBe(100)
+    expect(placement.maxHeight).toBe(300)
+  })
+
+  it('encosta na borda direita em vez de sair dela', () => {
+    const placement = placeFloatingPanel({
+      anchor: rect(1150, 100),
+      panel: { width: 256, height: 300 },
+      viewport: VIEWPORT,
+      prefer: 'below',
+    })
+
+    expect(placement.left + 256).toBeLessThanOrEqual(VIEWPORT.width)
+  })
+
+  it('sobe quando não cabe para baixo, em vez de vazar pelo rodapé', () => {
+    const placement = placeFloatingPanel({
+      anchor: rect(100, 700),
+      panel: { width: 256, height: 300 },
+      viewport: VIEWPORT,
+      prefer: 'below',
+    })
+
+    expect(placement.top + placement.maxHeight).toBeLessThanOrEqual(VIEWPORT.height)
+    expect(placement.top).toBeLessThan(700)
+  })
+})
+
+describe('submenu ao lado do item', () => {
+  it('abre à direita quando cabe', () => {
+    const placement = placeFloatingPanel({
+      anchor: rect(300, 200, 256, 36),
+      panel: { width: 256, height: 240 },
+      viewport: VIEWPORT,
+      prefer: 'side',
+    })
+
+    expect(placement.left).toBeGreaterThanOrEqual(300 + 256)
+  })
+
+  it('vira para a esquerda quando não cabe à direita', () => {
+    const placement = placeFloatingPanel({
+      anchor: rect(900, 200, 256, 36),
+      panel: { width: 256, height: 240 },
+      viewport: VIEWPORT,
+      prefer: 'side',
+    })
+
+    expect(placement.left).toBeLessThan(900)
+    expect(placement.left).toBeGreaterThanOrEqual(0)
+  })
+
+  it('lista longa perto do rodapé ganha rolagem em vez de ser cortada', () => {
+    // O caso da captura: submenu de ações mais alto que o espaço abaixo do item.
+    const placement = placeFloatingPanel({
+      anchor: rect(300, 620, 256, 36),
+      panel: { width: 256, height: 520 },
+      viewport: VIEWPORT,
+      prefer: 'side',
+    })
+
+    expect(placement.top + placement.maxHeight).toBeLessThanOrEqual(VIEWPORT.height)
+    expect(placement.maxHeight).toBeLessThanOrEqual(520)
+  })
+
+  it('painel mais alto que a tela cabe inteiro na tela, rolando por dentro', () => {
+    const placement = placeFloatingPanel({
+      anchor: rect(300, 400, 256, 36),
+      panel: { width: 256, height: 2000 },
+      viewport: VIEWPORT,
+      prefer: 'side',
+    })
+
+    expect(placement.top).toBeGreaterThanOrEqual(0)
+    expect(placement.maxHeight).toBeLessThan(VIEWPORT.height)
+    expect(placement.top + placement.maxHeight).toBeLessThanOrEqual(VIEWPORT.height)
+  })
+})
+
+describe('os menus do editor usam a conta acima', () => {
+  /**
+   * A função pura pode estar correta e ninguém chamá-la. Estes dois amarram o uso: sem eles a
+   * correção some no primeiro refactor e o menu volta a encostar na borda.
+   */
+  it('o menu do "+" mede antes de posicionar, em vez de usar a âncora crua', async () => {
+    const content = await Bun.file(`${import.meta.dir}/FlowsWorkspace.tsx`).text()
+
+    expect(content).toContain('placeFloatingPanel')
+    expect(content).not.toContain('left: quickAddFrom.anchor.x + 12')
+  })
+
+  it('o submenu não fica mais preso ao item por CSS', async () => {
+    const content = await Bun.file(`${import.meta.dir}/FlowPalette.tsx`).text()
+
+    expect(content).toContain('placeFloatingPanel')
+    // Verifica o uso em JSX, não a menção: o comentário do arquivo cita a classe antiga para
+    // explicar o que mudou, e casar com o texto solto reprovaria a própria explicação.
+    expect(content).not.toContain('className="absolute left-full')
+    expect(content).toContain('overflowY')
+  })
+})

package/src/flows/flowMenuPlacement.ts

@@ -0,0 +1,86 @@
+/**
+ * Copyright (c) 2026 Ada Technology. MIT License.
+ *
+ * Onde um menu flutuante do editor pode aparecer sem sair da tela.
+ *
+ * Existe porque tanto o menu do "+" quanto os submenus dele eram posicionados por uma âncora crua:
+ * o menu em `fixed` na coordenada do clique, os submenus em `left-full top-0`. Card perto da borda
+ * direita jogava o menu para fora; item de ação perto do rodapé cortava a lista no meio, e não havia
+ * como rolar nem alcançar o resto — o menu ficava preso contra a borda.
+ *
+ * A conta é pura de propósito: é ela que decide se o operador consegue clicar na opção, e testá-la
+ * exige apenas números.
+ */
+
+/** Retângulo do gatilho. Um clique é um retângulo de tamanho zero. */
+export type AnchorRect = {
+  readonly left: number
+  readonly top: number
+  readonly right: number
+  readonly bottom: number
+}
+
+export type PanelSize = {
+  readonly width: number
+  readonly height: number
+}
+
+export type ViewportSize = {
+  readonly width: number
+  readonly height: number
+}
+
+export type FloatingPlacement = {
+  readonly left: number
+  readonly top: number
+  /** Teto de altura: acima disso o painel rola por dentro em vez de vazar pelo rodapé. */
+  readonly maxHeight: number
+}
+
+export type PlaceFloatingPanelParams = {
+  readonly anchor: AnchorRect
+  readonly panel: PanelSize
+  readonly viewport: ViewportSize
+  /** `side`: submenu sai ao lado do item; `below`: menu sai abaixo do ponto clicado. */
+  readonly prefer: 'side' | 'below'
+  readonly gap?: number
+  readonly margin?: number
+}
+
+const DEFAULT_GAP = 4
+const DEFAULT_MARGIN = 8
+
+function clamp(value: number, minimum: number, maximum: number): number {
+  // `maximum` menor que `minimum` acontece com painel maior que a viewport: a margem de cima manda,
+  // porque cortar em cima esconde o começo da lista.
+  return Math.max(minimum, Math.min(value, Math.max(minimum, maximum)))
+}
+
+export function placeFloatingPanel({
+  anchor,
+  panel,
+  viewport,
+  prefer,
+  gap = DEFAULT_GAP,
+  margin = DEFAULT_MARGIN,
+}: PlaceFloatingPanelParams): FloatingPlacement {
+  const maxHeight = Math.min(panel.height, viewport.height - margin * 2)
+
+  let left: number
+  if (prefer === 'side') {
+    // Vira para a esquerda quando não cabe à direita — o inverso de escolher sempre um lado.
+    const toTheRight = anchor.right + gap
+    const toTheLeft = anchor.left - gap - panel.width
+    left = toTheRight + panel.width <= viewport.width - margin ? toTheRight : toTheLeft
+  } else {
+    left = anchor.left + gap
+  }
+  left = clamp(left, margin, viewport.width - margin - panel.width)
+
+  const top = prefer === 'side' ? anchor.top : anchor.bottom
+  return {
+    left,
+    top: clamp(top, margin, viewport.height - margin - maxHeight),
+    maxHeight,
+  }
+}

package/src/flows/index.ts

@@ -6,15 +6,19 @@ 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'
 
 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,
@@ -43,7 +47,15 @@ export type {
   CollectionChain,
 } from './flowGraph'
 
-export type { FlowEditorLabels } from './labels'
+export type { FlowEditorLabels, FlowValidationLabels } from './labels'
+export type {
+  FlowsWorkspaceProps,
+  FlowsWorkspaceApi,
+  FlowLivePosition,
+  FlowLiveNodeCount,
+  FlowLivePositionInput,
+  CreateFlowInput,
+} from './FlowsWorkspace'
 export type { FlowNodeCardData } from './FlowNodeCard'
 export type { FlowMapNodeData } from './FlowMapNode'
 export type { FlowMapCanvasProps } from './FlowMapCanvas'
@@ -53,3 +65,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'
+// Os formatos de posição viva já saem pelo `FlowsWorkspace`, que é onde o produto os encontra ao
+// implementar a api — exportar de novo aqui daria dois caminhos para o mesmo tipo.
+export type { FlowEdgeKind, FlowEdgeSpec, FlowNodePosition } from './flowCanvasModel'