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

package/src/flows/FlowConnectionEdge.tsx

@@ -0,0 +1,104 @@
+/**
+ * Copyright (c) 2026 Ada Technology. MIT License.
+ *
+ * A aresta do editor, com o botão de desligar em cima dela.
+ *
+ * Existe porque desligar um fio não tinha caminho nenhum no canvas: as arestas são derivadas do
+ * grafo a cada render, então clicar e apertar Delete não tem onde guardar a seleção. O botão no
+ * hover resolve sem estado de seleção — e é o único lugar em que a pessoa já está olhando quando
+ * quer trocar o destino.
+ */
+
+import { useEffect, useRef, useState } from 'react'
+import { BaseEdge, EdgeLabelRenderer, getBezierPath, type EdgeProps } from '@xyflow/react'
+import { X } from 'lucide-react'
+
+/** Folga para o ponteiro sair do traço e alcançar o botão sem que ele desapareça no caminho. */
+const HIDE_DELAY_MS = 320
+
+export type FlowConnectionEdgeData = {
+  /** Ausente em aresta que não se desliga daqui (salto entre fluxos via portal). */
+  readonly onDisconnect?: (() => void) | undefined
+  readonly disconnectLabel: string
+}
+
+export function FlowConnectionEdge({
+  id,
+  sourceX,
+  sourceY,
+  targetX,
+  targetY,
+  sourcePosition,
+  targetPosition,
+  markerEnd,
+  style,
+  data,
+  interactionWidth,
+}: EdgeProps) {
+  const [hovered, setHovered] = useState(false)
+  const hideTimer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined)
+  const { onDisconnect, disconnectLabel } = (data ?? {}) as FlowConnectionEdgeData
+
+  // Sair do traço não esconde o botão na hora: entre o fio e o botão há um vão de alguns pixels, e
+  // esconder no `mouseleave` seco fazia o alvo fugir do mouse a caminho dele.
+  function show() {
+    if (hideTimer.current) clearTimeout(hideTimer.current)
+    setHovered(true)
+  }
+
+  function scheduleHide() {
+    if (hideTimer.current) clearTimeout(hideTimer.current)
+    hideTimer.current = setTimeout(() => setHovered(false), HIDE_DELAY_MS)
+  }
+
+  useEffect(() => () => clearTimeout(hideTimer.current), [])
+
+  const [path, labelX, labelY] = getBezierPath({
+    sourceX,
+    sourceY,
+    sourcePosition,
+    targetX,
+    targetY,
+    targetPosition,
+  })
+
+  return (
+    <>
+      <BaseEdge id={id} path={path} markerEnd={markerEnd} style={style} interactionWidth={interactionWidth ?? 20} />
+
+      {/* Faixa invisível larga por cima do traço: o traço tem ~1,5px e mirar nele com o mouse é
+          tarefa de precisão que ninguém deveria ter. */}
+      <path
+        d={path}
+        fill="none"
+        strokeWidth={22}
+        stroke="transparent"
+        className="react-flow__edge-interaction"
+        onMouseEnter={show}
+        onMouseLeave={scheduleHide}
+      />
+
+      {onDisconnect && hovered && (
+        <EdgeLabelRenderer>
+          <button
+            type="button"
+            data-cv-tooltip={disconnectLabel}
+            aria-label={disconnectLabel}
+            onMouseEnter={show}
+            onMouseLeave={scheduleHide}
+            onClick={(event) => {
+              event.stopPropagation()
+              onDisconnect()
+            }}
+            style={{ transform: `translate(-50%, -50%) translate(${labelX}px, ${labelY}px)` }}
+            className="nodrag nopan pointer-events-auto absolute flex h-5 w-5 items-center justify-center rounded-full border border-gray-300 bg-white text-gray-500 shadow-sm hover:border-red-400 hover:text-red-500 dark:border-gray-600 dark:bg-gray-800 dark:text-gray-400"
+          >
+            <X size={12} strokeWidth={2.5} />
+          </button>
+        </EdgeLabelRenderer>
+      )}
+    </>
+  )
+}
+
+export const flowEdgeTypes = { flowConnection: FlowConnectionEdge }

package/src/flows/FlowGroupHeader.tsx

@@ -18,10 +18,20 @@ export function FlowGroupHeader({ data }: NodeProps) {
   return (
     <div className="flex items-center gap-2 rounded-full border border-cyan-300 dark:border-cyan-700 bg-cyan-50 dark:bg-cyan-950/50 px-3 py-1 text-xs font-medium text-cyan-800 dark:text-cyan-200 shadow-sm whitespace-nowrap">
       <span>{label}</span>
-      <button type="button" onClick={onFocus} title={labels.flowGroup.focus} className="hover:text-blue-600 dark:hover:text-blue-400">
+      <button
+        type="button"
+        onClick={onFocus}
+        data-cv-tooltip={labels.flowGroup.focus} aria-label={labels.flowGroup.focus}
+        className="hover:text-blue-600 dark:hover:text-blue-400"
+      >
         <Maximize2 size={12} />
       </button>
-      <button type="button" onClick={onClose} title={labels.flowGroup.close} className="hover:text-red-600 dark:hover:text-red-400">
+      <button
+        type="button"
+        onClick={onClose}
+        data-cv-tooltip={labels.flowGroup.close} aria-label={labels.flowGroup.close}
+        className="hover:text-red-600 dark:hover:text-red-400"
+      >
         <X size={12} />
       </button>
     </div>

package/src/flows/FlowLegend.tsx

@@ -0,0 +1,125 @@
+/**
+ * Copyright (c) 2026 Ada Technology. MIT License.
+ *
+ * Legenda do canvas.
+ *
+ * O editor distingue os tipos de ligação só por cor e traço — opção escolhida, fallback, salto entre
+ * fluxos, conversa viva — e nada na tela dizia o que era o quê. Quem não desenhou o fluxo lia um
+ * emaranhado colorido; a cor sem chave não informa, decora.
+ *
+ * Os contornos e marcas do card entram na mesma chave: card solto, início do fluxo e o ícone de
+ * repetição são vocabulário do editor tanto quanto as cores dos fios.
+ *
+ * Recolhida por padrão: em canvas cheio, uma caixa fixa cobre card. Quem já conhece o vocabulário
+ * não paga o espaço, e quem não conhece está a um clique.
+ */
+
+import { useState } from 'react'
+import { ChevronDown, ChevronUp, RotateCcw } from 'lucide-react'
+
+import type { FlowEditorLabels } from './labels'
+import type { FlowNodeType } from './flowGraph'
+
+export type FlowLegendEdgeSample = {
+  readonly color: string
+  readonly dash?: string | undefined
+  readonly label: string
+}
+
+export type FlowLegendProps = {
+  readonly labels: FlowEditorLabels
+  readonly edgeSamples: readonly FlowLegendEdgeSample[]
+  /** Classe de cor por tipo de card — a mesma que o `FlowNodeCard` usa, para a chave bater. */
+  readonly nodeSwatches: readonly { readonly type: FlowNodeType; readonly className: string }[]
+}
+
+function EdgeSample({ sample }: { sample: FlowLegendEdgeSample }) {
+  return (
+    <li className="flex items-center gap-2">
+      <svg width="28" height="12" viewBox="0 0 28 12" aria-hidden="true" className="shrink-0">
+        <line
+          x1="2"
+          y1="6"
+          x2="26"
+          y2="6"
+          stroke={sample.color}
+          strokeWidth="1.75"
+          {...(sample.dash ? { strokeDasharray: sample.dash } : {})}
+        />
+      </svg>
+      <span className="text-[11px] leading-tight text-gray-600 dark:text-gray-300">{sample.label}</span>
+    </li>
+  )
+}
+
+export function FlowLegend({ labels, edgeSamples, nodeSwatches }: FlowLegendProps) {
+  const [open, setOpen] = useState(false)
+
+  return (
+    <div className="rounded-lg border border-gray-200 bg-white/95 shadow-sm backdrop-blur dark:border-gray-700 dark:bg-gray-800/95">
+      <button
+        type="button"
+        onClick={() => setOpen((current) => !current)}
+        data-cv-tooltip={labels.legendPanel.title}
+        aria-label={labels.legendPanel.title}
+        aria-expanded={open}
+        className="flex w-full items-center justify-between gap-2 px-2.5 py-1.5 text-[11px] font-semibold uppercase tracking-wide text-gray-500 dark:text-gray-400"
+      >
+        {labels.legendPanel.title}
+        {open ? <ChevronDown size={13} /> : <ChevronUp size={13} />}
+      </button>
+
+      {open && (
+        <div className="max-h-72 w-64 overflow-y-auto border-t border-gray-100 px-2.5 py-2 dark:border-gray-700">
+          <p className="mb-1 text-[10px] font-semibold uppercase tracking-wide text-gray-400 dark:text-gray-500">
+            {labels.legendPanel.connections}
+          </p>
+          <ul className="space-y-1.5">
+            {edgeSamples.map((sample) => (
+              <EdgeSample key={sample.label} sample={sample} />
+            ))}
+          </ul>
+
+          <p className="mb-1 mt-3 text-[10px] font-semibold uppercase tracking-wide text-gray-400 dark:text-gray-500">
+            {labels.legendPanel.nodes}
+          </p>
+          <ul className="space-y-1.5">
+            {nodeSwatches.map((swatch) => (
+              <li key={swatch.type} className="flex items-center gap-2">
+                <span className={`h-3 w-5 shrink-0 rounded border-2 ${swatch.className}`} aria-hidden="true" />
+                <span className="text-[11px] leading-tight text-gray-600 dark:text-gray-300">
+                  {labels.legend[swatch.type]}
+                </span>
+              </li>
+            ))}
+            <li className="flex items-center gap-2">
+              <span
+                className="h-3 w-5 shrink-0 rounded border-2 border-dashed border-amber-400"
+                aria-hidden="true"
+              />
+              <span className="text-[11px] leading-tight text-gray-600 dark:text-gray-300">
+                {labels.legendPanel.detached}
+              </span>
+            </li>
+            <li className="flex items-center gap-2">
+              <span className="flex h-3 w-5 shrink-0 items-center justify-center" aria-hidden="true">
+                <span className="h-1.5 w-1.5 rounded-full bg-emerald-500" />
+              </span>
+              <span className="text-[11px] leading-tight text-gray-600 dark:text-gray-300">
+                {labels.legendPanel.startNode}
+              </span>
+            </li>
+            <li className="flex items-center gap-2">
+              <span className="flex h-3 w-5 shrink-0 items-center justify-center text-gray-400" aria-hidden="true">
+                <RotateCcw size={12} strokeWidth={2.5} />
+              </span>
+              <span className="text-[11px] leading-tight text-gray-600 dark:text-gray-300">
+                {labels.legendPanel.selfLoop}
+              </span>
+            </li>
+          </ul>
+        </div>
+      )}
+    </div>
+  )
+}

package/src/flows/FlowMapCanvas.tsx

@@ -27,18 +27,21 @@ export function FlowMapCanvas({ graphs, rootKey, onOpenFlow, labels: labelsOverr
   const positions = useMemo(() => computeFlowMapLayout(graphs, rootKey), [graphs, rootKey])
 
   const nodes = useMemo<Node[]>(
-    () => Object.values(graphs).map((g): Node => ({
-      id: g.key,
-      type: 'flowMapNode',
-      position: positions[g.key] ?? { x: 0, y: 0 },
-      data: {
-        label: g.label,
-        nodeCount: Object.keys(g.nodes).length,
-        isRoot: g.key === rootKey,
-        labels,
-        onOpen: () => onOpenFlow(g.key),
-      } satisfies FlowMapNodeData,
-    })),
+    () =>
+      Object.values(graphs).map(
+        (g): Node => ({
+          id: g.key,
+          type: 'flowMapNode',
+          position: positions[g.key] ?? { x: 0, y: 0 },
+          data: {
+            label: g.label,
+            nodeCount: Object.keys(g.nodes).length,
+            isRoot: g.key === rootKey,
+            labels,
+            onOpen: () => onOpenFlow(g.key),
+          } satisfies FlowMapNodeData,
+        }),
+      ),
     [graphs, positions, rootKey, onOpenFlow, labels],
   )
 

package/src/flows/FlowMapNode.tsx

@@ -21,10 +21,13 @@ export function FlowMapNode({ data }: NodeProps) {
       <div className="flex items-center gap-1.5 text-emerald-700 dark:text-emerald-300">
         <GitBranch size={14} />
         <span className="text-sm font-semibold truncate">{label}</span>
-        {isRoot && <span className="h-1.5 w-1.5 rounded-full bg-emerald-500 shrink-0" title={labels.startNodeTooltip} />}
+        {isRoot && (
+          <span className="h-1.5 w-1.5 rounded-full bg-emerald-500 shrink-0" data-cv-tooltip={labels.startNodeTooltip} />
+        )}
       </div>
       <p className="text-xs text-gray-500 dark:text-gray-400 mt-1">{labels.flowMap.nodeCount(nodeCount)}</p>
       <button
+        data-cv-tooltip={labels.flowMap.openFlow} aria-label={labels.flowMap.openFlow}
         type="button"
         onClick={onOpen}
         className="mt-2 inline-flex items-center gap-1 text-xs font-medium text-blue-600 dark:text-blue-400 hover:underline"

package/src/flows/FlowNodeCard.tsx

@@ -1,9 +1,32 @@
+import { useState } from 'react'
 import { Handle, Position, type NodeProps } from '@xyflow/react'
-import { MessageCircleQuestion, GitBranch, Zap, ListTree, Diamond, AlertTriangle, AlertCircle, Headset, Clock3, ShoppingBag, type LucideIcon } from 'lucide-react'
+import {
+  MessageCircleQuestion,
+  Plus,
+  GitBranch,
+  Zap,
+  ListTree,
+  Diamond,
+  AlertTriangle,
+  AlertCircle,
+  Headset,
+  Clock3,
+  ShoppingBag,
+  RotateCcw,
+  type LucideIcon,
+} from 'lucide-react'
 import type { FlowEditorLabels } from './labels'
-import type { FlowNodeData, GraphIssue } from './flowGraph'
+import { PASS_THROUGH_ACTION_KINDS, type FlowNodeData, type GraphIssue } from './flowGraph'
 
-const NODE_TYPE_COLOR: Record<FlowNodeData['type'], string> = {
+/**
+ * Diâmetro dos pontos de ligação.
+ *
+ * O padrão do react-flow tem ~6px, e mirar nele com o mouse é tarefa de precisão — some com a
+ * borda do card e não se lê como "puxe daqui". Vale para o alvo (topo) e para cada saída.
+ */
+const HANDLE_SIZE_PX = 14
+
+export const NODE_TYPE_COLOR: Record<FlowNodeData['type'], string> = {
   question: 'border-blue-300 bg-blue-50 dark:bg-blue-950/40 dark:border-blue-800',
   entrada_choice: 'border-purple-300 bg-purple-50 dark:bg-purple-950/40 dark:border-purple-800',
   action: 'border-orange-300 bg-orange-50 dark:bg-orange-950/40 dark:border-orange-800',
@@ -31,6 +54,9 @@ const DEFAULT_ACTION_KIND_ICON: Record<string, LucideIcon> = {
 // que só faz sentido para quem escreveu o interpretador do fluxo, não para quem está editando.
 export function nodeLabel(node: FlowNodeData | undefined, labels: FlowEditorLabels): string {
   if (!node) return '—'
+  // Apelido dado no editor manda sobre qualquer texto derivado: dois nós de mesma ação ficam
+  // idênticos no card sem ele, e é exatamente para desempatá-los que o campo existe.
+  if (node.label) return node.label
   if (node.type === 'action') {
     const actionKindLabel = node.actionKind ? labels.actionKindLabels[node.actionKind] : undefined
     // Sempre retorna string: um actionKind futuro sem label mapeado cai no próprio valor bruto
@@ -50,82 +76,230 @@ export type FlowNodeCardData = {
   liveCount: number
   isStart: boolean
   isSelected: boolean
+  /**
+   * Nó sem nenhuma ligação de entrada — o bot nunca chega nele. Contorno tracejado e pulso: sem
+   * isso, desconectar um fio ou criar um card solto passa despercebido até o fluxo quebrar em
+   * produção.
+   */
+  isDetached?: boolean
   issues: GraphIssue[]
   labels: FlowEditorLabels
   actionKindIcons?: Record<string, LucideIcon>
   onSelect: (id: string) => void
+  /**
+   * Criar o próximo nó já ligado nesta saída. Capacidade por ausência: sem o callback, o "+" não
+   * aparece — puxar o fio à mão continua funcionando igual.
+   */
+  onQuickAdd?: ((params: { nodeId: string; handle: string; anchor: { x: number; y: number } }) => void) | undefined
 }
 
 // Uma linha por saída: nós de escolha (question+choice ou menu) ganham UMA linha por opção mais
 // uma linha "caso contrário" — cada uma com seu próprio handle, arrastável pra uma conexão
 // condicional distinta. Nós lineares (pergunta simples) têm uma única linha "Próximo". Ações são
 // terminais (o motor do host nunca continua a partir de 'next' de uma ação) — sem linha.
-function sourceRows(node: FlowNodeData, labels: FlowEditorLabels): { id: string; label: string; isDefault: boolean }[] {
-  if (node.type === 'action') return []
+type SourceRowSpec = { id: string; label: string; isDefault: boolean; isSelfLoop: boolean }
+
+/**
+ * Quais saídas deste card voltam para ele mesmo.
+ *
+ * Sai do próprio nó porque é o único lugar que sabe: uma aresta de A para A não tem trajeto para
+ * desenhar, então quem mostra o comportamento é a linha de saída, com um ícone de repetição.
+ */
+function selfLoopHandles(node: FlowNodeData): Set<string> {
+  const loops = new Set<string>()
+  if (typeof node.next === 'string') {
+    if (node.next === node.id) loops.add('next')
+    return loops
+  }
+  if (!node.next) return loops
+
+  for (const [optionId, target] of Object.entries(node.next.byAnswer ?? {})) {
+    if (target === node.id) loops.add(optionId)
+  }
+  if (node.next.default === node.id) loops.add('__default')
+
+  return loops
+}
+
+function sourceRows(node: FlowNodeData, labels: FlowEditorLabels): SourceRowSpec[] {
+  // Ação de passagem tem saída; ação terminal, não — ver `PASS_THROUGH_ACTION_KINDS`.
+  if (node.type === 'action') {
+    return node.actionKind && PASS_THROUGH_ACTION_KINDS.includes(node.actionKind)
+      ? [{ id: 'next', label: labels.nodePanel.nextRowLabel, isDefault: false, isSelfLoop: false }]
+      : []
+  }
+
+  const loops = selfLoopHandles(node)
   if (node.type === 'condition') {
     return [
-      { id: 'true', label: labels.nodePanel.conditionTrue, isDefault: false },
-      { id: 'false', label: labels.nodePanel.conditionFalse, isDefault: false },
+      { id: 'true', label: labels.nodePanel.conditionTrue, isDefault: false, isSelfLoop: loops.has('true') },
+      { id: 'false', label: labels.nodePanel.conditionFalse, isDefault: false, isSelfLoop: loops.has('false') },
     ]
   }
   const isChoice = node.type === 'menu' || node.questionType === 'choice'
-  if (!isChoice) return [{ id: 'next', label: labels.nodePanel.nextRowLabel, isDefault: false }]
+  if (!isChoice)
+    return [{ id: 'next', label: labels.nodePanel.nextRowLabel, isDefault: false, isSelfLoop: loops.has('next') }]
   const options = node.options ?? []
   return [
-    ...options.map(([id, label]) => ({ id, label, isDefault: false })),
-    { id: '__default', label: labels.edgeFallbackLabel, isDefault: true },
+    ...options.map(([id, label]) => ({ id, label, isDefault: false, isSelfLoop: loops.has(id) })),
+    { id: '__default', label: labels.edgeFallbackLabel, isDefault: true, isSelfLoop: loops.has('__default') },
   ]
 }
 
 // Uma linha de saída, com seu próprio handle ancorado na borda direita da própria linha (não
 // mais distribuído na borda inferior do card) — assim dá pra ler "opção → destino" sem seguir
 // o fio até o label da ligação, que é justamente o que confundia num fluxo com muitos ramos.
-function SourceRow({ label, isDefault, handleId }: { label: string; isDefault: boolean; handleId: string }) {
+/**
+ * Uma saída do card: o rótulo, o ponto de onde se puxa o fio e o "+" que cria o próximo nó já
+ * ligado nele.
+ *
+ * Duas decisões que vieram de ver alguém usar:
+ *
+ * O "+" está **sempre visível**, esmaecido, e não aparece no hover. Aparecer no hover criava uma
+ * corrida contra o mouse: o botão fica à direita da linha, então o ponteiro atravessava o vão
+ * entre os dois, o hover caía e o botão sumia antes de ser alcançado.
+ *
+ * E a área que reage ao mouse **engloba o botão** (o `pr-9` do container), em vez de terminar na
+ * borda da linha — sem isso o vão continuaria existindo para o realce.
+ */
+function SourceRow({
+  label,
+  isDefault,
+  handleId,
+  addLabel,
+  isSelfLoop,
+  selfLoopLabel,
+  onQuickAdd,
+}: {
+  label: string
+  isDefault: boolean
+  handleId: string
+  addLabel: string
+  isSelfLoop: boolean
+  selfLoopLabel: string
+  onQuickAdd?: ((params: { handle: string; anchor: { x: number; y: number } }) => void) | undefined
+}) {
+  const [hovered, setHovered] = useState(false)
+
   return (
-    <div className="relative flex items-center gap-1.5 rounded-md border border-gray-200 dark:border-gray-600 bg-white/70 dark:bg-gray-900/40 px-2 py-1 pr-3">
-      <span className={`text-xs truncate flex-1 ${isDefault ? 'italic text-gray-400 dark:text-gray-500' : 'text-gray-700 dark:text-gray-200'}`}>
-        {label}
-      </span>
-      <Handle
-        type="source"
-        position={Position.Right}
-        id={handleId}
-        style={{ position: 'absolute', right: -7, top: '50%', transform: 'translateY(-50%)' }}
-        className={isDefault ? '!bg-gray-400 dark:!bg-gray-500' : '!bg-purple-500'}
-      />
+    <div
+      className={`relative ${onQuickAdd ? 'pr-9' : ''}`}
+      onMouseEnter={() => setHovered(true)}
+      onMouseLeave={() => setHovered(false)}
+    >
+      <div className="relative flex items-center gap-1.5 rounded-md border border-gray-200 dark:border-gray-600 bg-white/70 dark:bg-gray-900/40 px-2 py-1 pr-3">
+        <span
+          className={`text-xs truncate flex-1 ${isDefault ? 'italic text-gray-400 dark:text-gray-500' : 'text-gray-700 dark:text-gray-200'}`}
+        >
+          {label}
+        </span>
+        {isSelfLoop && (
+          <RotateCcw
+            size={12}
+            strokeWidth={2.5}
+            data-cv-tooltip={selfLoopLabel}
+            aria-label={selfLoopLabel}
+            className="shrink-0 text-gray-400 dark:text-gray-500"
+          />
+        )}
+        <Handle
+          type="source"
+          position={Position.Right}
+          id={handleId}
+          style={{
+            position: 'absolute',
+            right: -(HANDLE_SIZE_PX / 2 + 1),
+            top: '50%',
+            transform: 'translateY(-50%)',
+            width: HANDLE_SIZE_PX,
+            height: HANDLE_SIZE_PX,
+          }}
+          className={`!border-2 !border-white dark:!border-gray-800 ${isDefault ? '!bg-gray-400 dark:!bg-gray-500' : '!bg-purple-500'}`}
+        />
+      </div>
+      {onQuickAdd && (
+        <button
+          type="button"
+          data-cv-tooltip={addLabel}
+          aria-label={addLabel}
+          onClick={(event) => {
+            event.stopPropagation()
+            const rect = event.currentTarget.getBoundingClientRect()
+            onQuickAdd({ handle: handleId, anchor: { x: rect.right, y: rect.top } })
+          }}
+          // Opacidade inline, e não classe utilitária: o realce é estado de interação deste
+          // botão, e prende o valor ao componente em vez de depender do CSS gerado no build.
+          style={{ opacity: hovered ? 1 : 0.35 }}
+          className="nodrag absolute right-0 top-1/2 flex h-5 w-5 -translate-y-1/2 items-center justify-center rounded-full border border-blue-300 bg-white text-blue-600 shadow-sm transition-opacity hover:bg-blue-50 dark:border-blue-700 dark:bg-gray-800 dark:text-blue-400 dark:hover:bg-gray-700"
+        >
+          <Plus size={12} strokeWidth={3} />
+        </button>
+      )}
     </div>
   )
 }
 
 export function FlowNodeCard({ data }: NodeProps) {
-  const { node, liveCount, isStart, isSelected, issues, labels, actionKindIcons, onSelect } = data as unknown as FlowNodeCardData
+  const { node, liveCount, isStart, isSelected, isDetached, issues, labels, actionKindIcons, onSelect, onQuickAdd } =
+    data as unknown as FlowNodeCardData
   const label = nodeLabel(node, labels)
   const iconMap = { ...DEFAULT_ACTION_KIND_ICON, ...actionKindIcons }
-  const Icon = node.type === 'action' && node.actionKind ? (iconMap[node.actionKind] ?? NODE_TYPE_ICON[node.type]) : NODE_TYPE_ICON[node.type]
+  const Icon =
+    node.type === 'action' && node.actionKind
+      ? (iconMap[node.actionKind] ?? NODE_TYPE_ICON[node.type])
+      : NODE_TYPE_ICON[node.type]
   const rows = sourceRows(node, labels)
-  const hasError = issues.some((i) => i.severity === 'error')
-  const hasWarning = !hasError && issues.some((i) => i.severity === 'warning')
+  // Filtrado pelo nó, e não pelo fluxo: sem isto TODO card do fluxo acendia o alerta quando UM
+  // deles tinha problema, e o ícone deixava de apontar qualquer coisa. Aviso sem alvo é ruído.
+  const nodeIssues = issues.filter((issue) => issue.nodeId === node.id)
+  const errors = nodeIssues.filter((issue) => issue.severity === 'error')
+  const warnings = nodeIssues.filter((issue) => issue.severity === 'warning')
+  const hasError = errors.length > 0
+  const hasWarning = !hasError && warnings.length > 0
+  // Separador em vez de quebra de linha: o balão não preserva `\n`. O ícone dizia que havia algo
+  // errado sem dizer o quê, e corrigir passava por abrir o painel de cada card procurando.
+  const issueTooltip = (hasError ? errors : warnings).map((issue) => issue.message).join(' · ')
 
   return (
     <div
-      title={label}
-      className={`relative rounded-lg border-2 px-3 py-2 w-60 cursor-pointer shadow-sm hover:shadow-md transition-shadow ${NODE_TYPE_COLOR[node.type]} ${isSelected ? 'ring-2 ring-blue-500 ring-offset-2 dark:ring-offset-gray-900' : ''}`}
+      data-cv-tooltip={isDetached ? labels.detachedNodeTooltip : label}
+      className={`relative rounded-lg border-2 px-3 py-2 w-60 cursor-pointer shadow-sm hover:shadow-md transition-shadow ${NODE_TYPE_COLOR[node.type]} ${isSelected ? 'ring-2 ring-blue-500 ring-offset-2 dark:ring-offset-gray-900' : ''} ${isDetached ? 'border-dashed !border-amber-400 animate-pulse' : ''}`}
       onClick={() => onSelect(node.id)}
     >
-      <Handle type="target" position={Position.Top} id="target" className="!bg-gray-400 dark:!bg-gray-500" />
+      <Handle
+        type="target"
+        position={Position.Top}
+        id="target"
+        style={{ width: HANDLE_SIZE_PX, height: HANDLE_SIZE_PX }}
+        className="!bg-gray-400 !border-2 !border-white dark:!bg-gray-500 dark:!border-gray-800"
+      />
 
       <div className="flex items-center justify-between gap-2">
         <span className="flex items-center gap-1.5 uppercase tracking-wide font-semibold text-gray-500 dark:text-gray-400 text-xs">
           <Icon size={12} strokeWidth={2.5} />
-          {isStart && <span className="h-1.5 w-1.5 rounded-full bg-emerald-500" title={labels.startNodeTooltip} />}
+          {isStart && <span className="h-1.5 w-1.5 rounded-full bg-emerald-500" data-cv-tooltip={labels.startNodeTooltip} />}
           {labels.legend[node.type]}
         </span>
         <div className="flex items-center gap-1">
-          {hasError && <AlertCircle size={13} className="text-red-600 dark:text-red-400" />}
-          {hasWarning && <AlertTriangle size={13} className="text-amber-500 dark:text-amber-400" />}
+          {hasError && (
+            <AlertCircle
+              size={13}
+              data-cv-tooltip={issueTooltip}
+              aria-label={issueTooltip}
+              className="text-red-600 dark:text-red-400"
+            />
+          )}
+          {hasWarning && (
+            <AlertTriangle
+              size={13}
+              data-cv-tooltip={issueTooltip}
+              aria-label={issueTooltip}
+              className="text-amber-500 dark:text-amber-400"
+            />
+          )}
           {liveCount > 0 && (
             <span
-              title={labels.liveCountTooltip(liveCount)}
+              data-cv-tooltip={labels.liveCountTooltip(liveCount)}
               className="font-bold bg-blue-600 text-white rounded-full px-1.5 py-0.5 text-xs"
             >
               {liveCount}
@@ -139,7 +313,18 @@ export function FlowNodeCard({ data }: NodeProps) {
       {rows.length > 0 && (
         <div className="mt-2 space-y-1">
           {rows.map((row) => (
-            <SourceRow key={row.id} label={row.label} isDefault={row.isDefault} handleId={row.id} />
+            <SourceRow
+              key={row.id}
+              label={row.label}
+              isDefault={row.isDefault}
+              handleId={row.id}
+              addLabel={labels.quickAdd.fromHandle}
+              isSelfLoop={row.isSelfLoop}
+              selfLoopLabel={labels.legendPanel.selfLoop}
+              {...(onQuickAdd
+                ? { onQuickAdd: (params) => onQuickAdd({ nodeId: node.id, ...params }) }
+                : {})}
+            />
           ))}
         </div>
       )}