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

package/src/Tooltip.tsx

@@ -0,0 +1,164 @@
+/**
+ * Camada única de dicas do pacote.
+ *
+ * O `title` nativo existia em todos os botões e mesmo assim a dica "não aparecia": o navegador
+ * espera de 1 a 2 segundos antes de desenhar, o balão sai fora do tema e some ao menor movimento do
+ * mouse. Aqui a dica é do produto — aparece em 120ms, com o mesmo contraste do resto da interface.
+ *
+ * Um só ouvinte no documento atende a interface inteira: cada botão declara `data-cv-tooltip` e não
+ * precisa de estado, ref ou wrapper próprio. O balão é impresso em `document.body` via portal
+ * porque `overflow` de container (a régua de respostas rápidas rola na horizontal) recortaria um
+ * balão desenhado dentro do próprio botão.
+ */
+
+import { useEffect, useRef, useState } from 'react'
+import { createPortal } from 'react-dom'
+
+/** Atributo que marca um elemento como portador de dica. */
+export const TOOLTIP_ATTRIBUTE = 'data-cv-tooltip'
+
+const TOOLTIP_DELAY_MS = 120
+const TOOLTIP_GAP_PX = 8
+/** Margem para o balão não colar na borda da janela quando o alvo está no canto. */
+const TOOLTIP_EDGE_PX = 72
+
+export type TooltipPlacement = 'top' | 'bottom'
+
+export interface TooltipPositionParams {
+  readonly targetRect: { top: number; bottom: number; left: number; width: number }
+  readonly viewportWidth: number
+}
+
+export interface TooltipPosition {
+  left: number
+  top: number
+  placement: TooltipPlacement
+}
+
+interface TooltipState extends TooltipPosition {
+  text: string
+}
+
+/** Separado do componente por ser a única parte com regra: o resto é ouvir evento e desenhar. */
+export function tooltipPositionOf({ targetRect, viewportWidth }: TooltipPositionParams): TooltipPosition {
+  // Sem espaço acima (botão no topo da tela), o balão desce em vez de sair da janela.
+  const placement: TooltipPlacement = targetRect.top < TOOLTIP_EDGE_PX ? 'bottom' : 'top'
+  const centerX = targetRect.left + targetRect.width / 2
+
+  return {
+    left: Math.min(Math.max(centerX, TOOLTIP_EDGE_PX), viewportWidth - TOOLTIP_EDGE_PX),
+    top: placement === 'top' ? targetRect.top - TOOLTIP_GAP_PX : targetRect.bottom + TOOLTIP_GAP_PX,
+    placement,
+  }
+}
+
+function tooltipStateFor(target: HTMLElement, text: string): TooltipState {
+  const position = tooltipPositionOf({
+    targetRect: target.getBoundingClientRect(),
+    viewportWidth: window.innerWidth,
+  })
+
+  return { text, ...position }
+}
+
+/**
+ * Só uma camada desenha por vez. A camada é montada por cada superfície do pacote (inbox, fluxos,
+ * documentos) para o host não precisar montá-la à mão; duas superfícies na mesma tela renderizariam
+ * dois balões sobrepostos sem essa trava.
+ */
+let layerOwner: object | undefined
+
+export function TooltipLayer() {
+  const identity = useRef({})
+  const [isOwner, setIsOwner] = useState(false)
+  const [tooltip, setTooltip] = useState<TooltipState | undefined>(undefined)
+
+  useEffect(() => {
+    const owned = identity.current
+    if (layerOwner && layerOwner !== owned) return undefined
+    layerOwner = owned
+    setIsOwner(true)
+
+    return () => {
+      if (layerOwner === owned) layerOwner = undefined
+    }
+  }, [])
+
+  useEffect(() => {
+    if (!isOwner) return undefined
+
+    let timer: ReturnType<typeof setTimeout> | undefined
+
+    function cancelPending() {
+      if (timer) clearTimeout(timer)
+      timer = undefined
+    }
+
+    function hide() {
+      cancelPending()
+      setTooltip(undefined)
+    }
+
+    function handleEnter(event: Event) {
+      const origin = event.target
+      if (!(origin instanceof Element)) return
+      const target = origin.closest(`[${TOOLTIP_ATTRIBUTE}]`)
+      if (!(target instanceof HTMLElement)) {
+        hide()
+        return
+      }
+      const text = target.getAttribute(TOOLTIP_ATTRIBUTE)
+      if (!text) {
+        hide()
+        return
+      }
+      cancelPending()
+      timer = setTimeout(() => setTooltip(tooltipStateFor(target, text)), TOOLTIP_DELAY_MS)
+    }
+
+    // Sair da janela não dispara `pointerover` em elemento nenhum: sem isto, o balão ficaria aceso
+    // depois que o ponteiro já saiu da página.
+    function handleLeaveWindow(event: PointerEvent) {
+      if (!event.relatedTarget) hide()
+    }
+
+    function handleKeyDown(event: KeyboardEvent) {
+      if (event.key === 'Escape') hide()
+    }
+
+    document.addEventListener('pointerover', handleEnter)
+    document.addEventListener('pointerout', handleLeaveWindow)
+    document.addEventListener('focusin', handleEnter)
+    document.addEventListener('pointerdown', hide)
+    document.addEventListener('focusout', hide)
+    document.addEventListener('keydown', handleKeyDown)
+    // Captura: rolagem em qualquer container interno invalida a posição já medida.
+    window.addEventListener('scroll', hide, true)
+    window.addEventListener('resize', hide)
+
+    return () => {
+      cancelPending()
+      document.removeEventListener('pointerover', handleEnter)
+      document.removeEventListener('pointerout', handleLeaveWindow)
+      document.removeEventListener('focusin', handleEnter)
+      document.removeEventListener('pointerdown', hide)
+      document.removeEventListener('focusout', hide)
+      document.removeEventListener('keydown', handleKeyDown)
+      window.removeEventListener('scroll', hide, true)
+      window.removeEventListener('resize', hide)
+    }
+  }, [isOwner])
+
+  if (!tooltip) return null
+
+  return createPortal(
+    <div
+      role="tooltip"
+      className={`cv-tooltip cv-tooltip--${tooltip.placement}`}
+      style={{ left: tooltip.left, top: tooltip.top }}
+    >
+      {tooltip.text}
+    </div>,
+    document.body,
+  )
+}

package/src/WhatsAppMessageEditor.tsx

@@ -117,13 +117,13 @@ export function WhatsAppMessageEditor({
   return (
     <div>
       <div className="flex flex-wrap items-center gap-1.5 mb-2">
-        <button type="button" onClick={() => wrapSelection('*')} className={toolbarButtonClass} title={editorLabels.boldHint} aria-label={editorLabels.bold}>
+        <button type="button" onClick={() => wrapSelection('*')} className={toolbarButtonClass} data-cv-tooltip={editorLabels.boldHint} aria-label={editorLabels.bold}>
           <Bold size={15} />
         </button>
-        <button type="button" onClick={() => wrapSelection('_')} className={toolbarButtonClass} title={editorLabels.italicHint} aria-label={editorLabels.italic}>
+        <button type="button" onClick={() => wrapSelection('_')} className={toolbarButtonClass} data-cv-tooltip={editorLabels.italicHint} aria-label={editorLabels.italic}>
           <Italic size={15} />
         </button>
-        <button type="button" onClick={() => wrapSelection('~')} className={toolbarButtonClass} title={editorLabels.strikethroughHint} aria-label={editorLabels.strikethrough}>
+        <button type="button" onClick={() => wrapSelection('~')} className={toolbarButtonClass} data-cv-tooltip={editorLabels.strikethroughHint} aria-label={editorLabels.strikethrough}>
           <Strikethrough size={15} />
         </button>
         {placeholders.length > 0 && (
@@ -135,7 +135,7 @@ export function WhatsAppMessageEditor({
                 type="button"
                 onClick={() => insertAtCursor(token)}
                 className="inline-flex items-center h-8 px-2 rounded-lg border border-gray-200 dark:border-gray-600 text-xs text-blue-600 dark:text-blue-300 hover:bg-blue-50 dark:hover:bg-blue-900/40 transition-colors"
-                title={editorLabels.insertPlaceholder(token)}
+                data-cv-tooltip={editorLabels.insertPlaceholder(token)} aria-label={editorLabels.insertPlaceholder(token)}
               >
                 {token}
               </button>

package/src/WindowExpiredNotice.tsx

@@ -6,7 +6,10 @@
  * cumpre. O caminho que resta — template — fica visível na mesma altura da tela.
  */
 
+import { AlarmClock, Send } from 'lucide-react'
+
 import { CONVERSATION_WINDOW, type ConversationWindow } from './conversationWindow'
+import { ICON_SIZE_ACTION, ICON_SIZE_INLINE } from './icon.constant'
 import { cn } from './lib/cn'
 
 export interface WindowExpiredNoticeLabels {
@@ -15,10 +18,11 @@ export interface WindowExpiredNoticeLabels {
   sendTemplate: string
 }
 
+// Sem emoji no rótulo: o ícone vem ao lado, da mesma biblioteca do resto da tela.
 export const DEFAULT_WINDOW_EXPIRED_LABELS: WindowExpiredNoticeLabels = {
-  title: '⏰ Janela de 24h expirada — o WhatsApp não aceita mensagens livres.',
+  title: 'Janela de 24h expirada — o WhatsApp não aceita mensagens livres.',
   description: 'Envie uma mensagem de template para reabrir a conversa com o cliente.',
-  sendTemplate: '📨 Enviar Template (HSM)',
+  sendTemplate: 'Enviar Template (HSM)',
 }
 
 export interface WindowExpiredNoticeProps {
@@ -38,10 +42,14 @@ export function WindowExpiredNotice({
 
   return (
     <div role="status" className={cn('border-t bg-yellow-50 px-4 py-3 text-sm dark:bg-yellow-950', className)}>
-      <p className="font-medium text-yellow-900 dark:text-yellow-200">{labels.title}</p>
+      <p className="flex items-center gap-2 font-medium text-yellow-900 dark:text-yellow-200">
+        <AlarmClock size={ICON_SIZE_INLINE} aria-hidden="true" className="shrink-0" />
+        {labels.title}
+      </p>
       <p className="text-yellow-800 dark:text-yellow-300">{labels.description}</p>
       {onSendTemplate ? (
-        <button type="button" onClick={onSendTemplate} disabled={disabled} className="cv-header-action mt-2">
+        <button data-cv-tooltip={labels.sendTemplate} aria-label={labels.sendTemplate} type="button" onClick={onSendTemplate} disabled={disabled} className="cv-header-action mt-2">
+          <Send size={ICON_SIZE_ACTION} aria-hidden="true" />
           {labels.sendTemplate}
         </button>
       ) : null}

package/src/composer.constant.ts

@@ -0,0 +1,33 @@
+/**
+ * Aparência da barra de composição, compartilhada pelo `MessageComposer` e pelo
+ * `RichMessageComposer`. São a mesma superfície na tela: divergir aqui é o que fazia a barra rica
+ * aparecer branca sobre o fundo branco da página, com os atalhos flutuando sem faixa própria.
+ */
+
+/** Faixa cinza de largura cheia; o campo de texto dentro dela é que arredonda — ordem do WhatsApp. */
+export const COMPOSER_BAR_CLASS = 'cv-composer-bar'
+
+/** Botão redondo da barra: formatação, emoji, variáveis e anexo têm o mesmo peso visual. */
+export const COMPOSER_TOOL_BUTTON_CLASS =
+  'flex h-9 w-9 flex-shrink-0 items-center justify-center rounded-full transition-colors hover:bg-teal-50 hover:text-teal-600 dark:hover:bg-teal-900/30 dark:hover:text-teal-400'
+
+/** Formatação em vigor no cursor. Sem isto o operador não sabe se o próximo caractere sai em negrito. */
+export const COMPOSER_TOOL_BUTTON_ACTIVE_CLASS = 'bg-teal-50 text-teal-600 dark:bg-teal-900/40 dark:text-teal-400'
+
+export const COMPOSER_TOOL_BUTTON_IDLE_CLASS = 'text-gray-400 dark:text-gray-500'
+
+/** Marcação do monoespaçado dentro do campo — a mesma que o `waToHTML` escreve, para o trecho não
+ *  mudar de cara ao recarregar um rascunho. */
+export const COMPOSER_MONOSPACE_CLASS = 'bg-black/5 dark:bg-white/10 rounded px-0.5 font-mono text-sm'
+
+/**
+ * Abaixo desta largura de barra (em px) os quatro botões de formatação recolhem num único botão com
+ * popover. Com todos abertos, sobram ~200px de barra para os oito controles e o campo de texto fica
+ * mais estreito que o próprio placeholder. É a largura da barra, não da janela: quem estreita a
+ * coluna é a prévia do simulador ao lado, com a janela intacta.
+ */
+export const COMPOSER_COMPACT_WIDTH = 480
+
+/** Atalho de resposta rápida: pílula branca, que só tem contraste porque a faixa é cinza. */
+export const QUICK_REPLY_PILL_CLASS =
+  'whitespace-nowrap rounded-full border border-gray-200 bg-white px-3 py-1.5 text-xs text-gray-600 shadow-sm transition-colors hover:border-teal-200 hover:bg-teal-50 hover:text-teal-700 dark:border-gray-600 dark:bg-gray-800 dark:text-gray-400 dark:hover:border-teal-800 dark:hover:bg-teal-950/40 dark:hover:text-teal-400'

package/src/conversationWindow.ts

@@ -22,12 +22,14 @@ export const CONVERSATION_WINDOW = {
 } as const
 export type ConversationWindow = (typeof CONVERSATION_WINDOW)[keyof typeof CONVERSATION_WINDOW]
 
+// O tom pinta o próprio chip, em vez de uma bolinha ao lado do rótulo: a bolinha somava ~14px por
+// filtro e era o que fazia a fila de cinco quebrar em duas linhas na coluna da lista.
 export const WINDOW_FILTERS = [
-  { value: CONVERSATION_WINDOW.ALL, label: 'Todas', dotClass: '' },
-  { value: CONVERSATION_WINDOW.FRESH, label: '<12h', dotClass: 'bg-green-500' },
-  { value: CONVERSATION_WINDOW.WARNING, label: '12-21h', dotClass: 'bg-yellow-500' },
-  { value: CONVERSATION_WINDOW.CRITICAL, label: '21-24h', dotClass: 'bg-red-500' },
-  { value: CONVERSATION_WINDOW.EXPIRED, label: '>24h', dotClass: 'bg-gray-400' },
+  { value: CONVERSATION_WINDOW.ALL, label: 'Todas', tone: '' },
+  { value: CONVERSATION_WINDOW.FRESH, label: '<12h', tone: 'fresh' },
+  { value: CONVERSATION_WINDOW.WARNING, label: '12-21h', tone: 'warning' },
+  { value: CONVERSATION_WINDOW.CRITICAL, label: '21-24h', tone: 'critical' },
+  { value: CONVERSATION_WINDOW.EXPIRED, label: '>24h', tone: 'expired' },
 ] as const
 
 // Proporções da janela: 12h e 21h numa janela de 24h, mas expressas como fração para acompanharem

package/src/documents/DocumentsWorkspace.tsx

@@ -28,6 +28,7 @@ import {
 import { useDebouncedValue, useUrlArrayState, useUrlNumberState, useUrlStringState } from '../hooks/useUrlFilterState'
 import type { CompanyDocument } from '../providers/types'
 import { DEFAULT_DOCUMENTS_WORKSPACE_LABELS, type DocumentsWorkspaceLabels } from './labels'
+import { TooltipLayer } from '../Tooltip'
 
 const DEFAULT_PER_PAGE = 20
 const DEFAULT_PER_PAGE_OPTIONS = [10, 20, 50, 100] as const
@@ -249,6 +250,7 @@ export function DocumentsWorkspace({
 
   return (
     <div className={cn('space-y-4', classNames?.root, className)}>
+      <TooltipLayer />
       <header className={cn('space-y-0.5', classNames?.header)}>
         <h2 className="text-lg font-semibold">{labels.title}</h2>
         <p className="text-sm text-gray-500 dark:text-gray-400">{labels.subtitle(total)}</p>
@@ -297,7 +299,7 @@ export function DocumentsWorkspace({
         {renderFilters?.({ extra, setExtra })}
 
         {hasFilters ? (
-          <button type="button" onClick={clearFilters} className="cv-header-action inline-flex items-center gap-1">
+          <button data-cv-tooltip={labels.clearFilters} aria-label={labels.clearFilters} type="button" onClick={clearFilters} className="cv-header-action inline-flex items-center gap-1">
             <X size={12} aria-hidden="true" />
             {labels.clearFilters}
           </button>
@@ -313,6 +315,7 @@ export function DocumentsWorkspace({
         >
           {downloadArchive ? (
             <button
+              data-cv-tooltip={labels.bulkDownloadZip} aria-label={labels.bulkDownloadZip}
               type="button"
               onClick={() => void handleDownloadArchive()}
               disabled={busy}
@@ -324,6 +327,7 @@ export function DocumentsWorkspace({
           ) : null}
           {removeDocument ? (
             <button
+              data-cv-tooltip={labels.bulkRemove(selectedIds.size)} aria-label={labels.bulkRemove(selectedIds.size)}
               type="button"
               onClick={() => {
                 if (window.confirm(labels.bulkRemoveConfirm(selectedIds.size))) void handleRemove(Array.from(selectedIds))
@@ -389,7 +393,7 @@ export function DocumentsWorkspace({
                 <td className="max-w-xs px-3 py-2">
                   <div className="flex min-w-0 items-center gap-2">
                     <FileIcon filename={document.filename} mimeType={document.mimeType} />
-                    <span className="truncate font-medium" title={document.filename}>
+                    <span className="truncate font-medium" data-cv-tooltip={document.filename}>
                       {document.filename}
                     </span>
                   </div>
@@ -402,7 +406,7 @@ export function DocumentsWorkspace({
                     <button
                       type="button"
                       onClick={() => onOpenConversation(document.conversationId)}
-                      title={labels.openConversation}
+                      data-cv-tooltip={labels.openConversation} aria-label={labels.openConversation}
                       className="cv-header-action inline-flex items-center gap-1"
                     >
                       <MessageSquare size={12} aria-hidden="true" />
@@ -425,7 +429,7 @@ export function DocumentsWorkspace({
                     <button
                       type="button"
                       onClick={() => void handleOpen(document.id, 'inline')}
-                      title={labels.view}
+                      data-cv-tooltip={labels.view}
                       aria-label={`${labels.view}: ${document.filename}`}
                       className="cv-header-icon"
                     >
@@ -434,7 +438,7 @@ export function DocumentsWorkspace({
                     <button
                       type="button"
                       onClick={() => void handleOpen(document.id, 'attachment')}
-                      title={labels.download}
+                      data-cv-tooltip={labels.download}
                       aria-label={`${labels.download}: ${document.filename}`}
                       className="cv-header-icon"
                     >
@@ -447,7 +451,7 @@ export function DocumentsWorkspace({
                           if (window.confirm(labels.removeConfirm(document.filename))) void handleRemove([document.id])
                         }}
                         disabled={busy}
-                        title={labels.remove}
+                        data-cv-tooltip={labels.remove}
                         aria-label={`${labels.remove}: ${document.filename}`}
                         className="cv-header-icon disabled:opacity-40"
                       >

package/src/flows/FlowGroupHeader.tsx

@@ -21,7 +21,7 @@ export function FlowGroupHeader({ data }: NodeProps) {
       <button
         type="button"
         onClick={onFocus}
-        title={labels.flowGroup.focus}
+        data-cv-tooltip={labels.flowGroup.focus} aria-label={labels.flowGroup.focus}
         className="hover:text-blue-600 dark:hover:text-blue-400"
       >
         <Maximize2 size={12} />
@@ -29,7 +29,7 @@ export function FlowGroupHeader({ data }: NodeProps) {
       <button
         type="button"
         onClick={onClose}
-        title={labels.flowGroup.close}
+        data-cv-tooltip={labels.flowGroup.close} aria-label={labels.flowGroup.close}
         className="hover:text-red-600 dark:hover:text-red-400"
       >
         <X size={12} />

package/src/flows/FlowMapNode.tsx

@@ -22,11 +22,12 @@ export function FlowMapNode({ data }: NodeProps) {
         <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} />
+          <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

@@ -135,7 +135,7 @@ export function FlowNodeCard({ data }: NodeProps) {
 
   return (
     <div
-      title={isDetached ? labels.detachedNodeTooltip : label}
+      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)}
     >
@@ -144,7 +144,7 @@ export function FlowNodeCard({ data }: NodeProps) {
       <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">
@@ -152,7 +152,7 @@ export function FlowNodeCard({ data }: NodeProps) {
           {hasWarning && <AlertTriangle size={13} 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}

package/src/flows/FlowNodePanel.tsx

@@ -181,7 +181,7 @@ export function FlowNodePanel({
     <div className="fixed inset-y-0 right-0 w-96 bg-white dark:bg-gray-800 border-l border-gray-200 dark:border-gray-700 shadow-xl z-50 flex flex-col">
       <div className="flex items-center justify-between px-4 py-3 border-b border-gray-100 dark:border-gray-700">
         <h3 className="text-sm font-semibold text-gray-900 dark:text-gray-100">{labels.nodePanel.title}</h3>
-        <button onClick={onClose} className="text-gray-400 hover:text-gray-600">
+        <button data-cv-tooltip={labels.nodePanel.close} aria-label={labels.nodePanel.close} onClick={onClose} className="text-gray-400 hover:text-gray-600">
           <X size={18} />
         </button>
       </div>
@@ -358,7 +358,7 @@ export function FlowNodePanel({
           <div>
             <div className="flex items-center justify-between mb-1.5">
               <label className="text-xs font-medium text-gray-500 dark:text-gray-400">{labels.nodePanel.options}</label>
-              <button onClick={addOption} className="text-xs text-blue-600 hover:underline flex items-center gap-1">
+              <button data-cv-tooltip={labels.nodePanel.addOption} aria-label={labels.nodePanel.addOption} onClick={addOption} className="text-xs text-blue-600 hover:underline flex items-center gap-1">
                 <Plus size={12} /> {labels.nodePanel.addOption}
               </button>
             </div>
@@ -377,7 +377,7 @@ export function FlowNodePanel({
                     placeholder={labels.nodePanel.optionLabel}
                     className={`flex-1 ${INPUT_CLASSNAME}`}
                   />
-                  <button onClick={() => removeOption(i)} className="text-gray-400 hover:text-red-600">
+                  <button data-cv-tooltip={labels.nodePanel.removeOption} aria-label={labels.nodePanel.removeOption} onClick={() => removeOption(i)} className="text-gray-400 hover:text-red-600">
                     <Trash2 size={14} />
                   </button>
                 </div>
@@ -441,6 +441,7 @@ export function FlowNodePanel({
 
       <div className="p-4 border-t border-gray-100 dark:border-gray-700 flex gap-2">
         <button
+          data-cv-tooltip={labels.nodePanel.save} aria-label={labels.nodePanel.save}
           onClick={() => onChange(draft)}
           className="flex-1 inline-flex items-center justify-center gap-2 rounded-lg bg-blue-600 px-4 py-2 text-sm font-medium text-white hover:bg-blue-700"
         >
@@ -451,13 +452,13 @@ export function FlowNodePanel({
             onClick={() => {
               if (window.confirm(labels.nodePanel.deleteConfirm)) onDelete(node.id)
             }}
-            title={labels.nodePanel.delete}
+            data-cv-tooltip={labels.nodePanel.delete} aria-label={labels.nodePanel.delete}
             className="px-3 py-2 text-sm text-red-600 dark:text-red-400 hover:bg-red-50 dark:hover:bg-red-950/30 rounded-lg"
           >
             <Trash2 size={14} />
           </button>
         )}
-        <button onClick={onClose} className="px-4 py-2 text-sm text-gray-600 dark:text-gray-300 hover:underline">
+        <button data-cv-tooltip={labels.nodePanel.cancel} aria-label={labels.nodePanel.cancel} onClick={onClose} className="px-4 py-2 text-sm text-gray-600 dark:text-gray-300 hover:underline">
           {labels.nodePanel.cancel}
         </button>
       </div>

package/src/flows/FlowPalette.tsx

@@ -58,6 +58,7 @@ export function FlowPalette({ onAdd, labels: labelsOverride, actionOptions }: Fl
   return (
     <div ref={containerRef} className="relative">
       <button
+        data-cv-tooltip={labels.palette.title} aria-label={labels.palette.title}
         onClick={() => setOpen((v) => !v)}
         className="inline-flex items-center gap-1.5 rounded-lg bg-blue-600 px-3 py-1.5 text-xs font-medium text-white hover:bg-blue-700"
       >
@@ -68,6 +69,7 @@ export function FlowPalette({ onAdd, labels: labelsOverride, actionOptions }: Fl
         <div className="absolute left-0 top-full mt-1.5 w-64 rounded-xl border border-gray-200 dark:border-gray-700 bg-white dark:bg-gray-800 shadow-lg z-50 py-1">
           <div className="relative">
             <button
+              data-cv-tooltip={labels.palette.question} aria-label={labels.palette.question}
               onMouseEnter={() => setSubmenu('question')}
               onClick={() => setSubmenu(submenu === 'question' ? null : 'question')}
               className="w-full flex items-center justify-between gap-2 px-3 py-2 text-sm text-gray-700 dark:text-gray-200 hover:bg-gray-50 dark:hover:bg-gray-700"
@@ -81,6 +83,7 @@ export function FlowPalette({ onAdd, labels: labelsOverride, actionOptions }: Fl
               <div className="absolute left-full top-0 ml-1 w-56 rounded-xl border border-gray-200 dark:border-gray-700 bg-white dark:bg-gray-800 shadow-lg py-1">
                 {QUESTION_TYPES.map((qt) => (
                   <button
+                    data-cv-tooltip={labels.questionTypeLabels[qt]} aria-label={labels.questionTypeLabels[qt]}
                     key={qt}
                     onClick={() => select({ kind: 'question', questionType: qt })}
                     className="w-full text-left px-3 py-2 text-sm text-gray-700 dark:text-gray-200 hover:bg-gray-50 dark:hover:bg-gray-700"
@@ -93,6 +96,7 @@ export function FlowPalette({ onAdd, labels: labelsOverride, actionOptions }: Fl
           </div>
 
           <button
+            data-cv-tooltip={labels.palette.decision} aria-label={labels.palette.decision}
             onMouseEnter={() => setSubmenu(null)}
             onClick={() => select({ kind: 'decision' })}
             className="w-full flex items-center gap-2 px-3 py-2 text-sm text-gray-700 dark:text-gray-200 hover:bg-gray-50 dark:hover:bg-gray-700"
@@ -104,13 +108,14 @@ export function FlowPalette({ onAdd, labels: labelsOverride, actionOptions }: Fl
             onMouseEnter={() => setSubmenu(null)}
             onClick={() => select({ kind: 'condition' })}
             className="w-full flex items-center gap-2 px-3 py-2 text-sm text-gray-700 dark:text-gray-200 hover:bg-gray-50 dark:hover:bg-gray-700"
-            title={labels.palette.conditionHint}
+            data-cv-tooltip={labels.palette.conditionHint} aria-label={labels.palette.conditionHint}
           >
             <Diamond size={15} className="text-cyan-500" /> {labels.palette.condition}
           </button>
 
           <div className="relative">
             <button
+              data-cv-tooltip={labels.palette.action} aria-label={labels.palette.action}
               onMouseEnter={() => setSubmenu('action')}
               onClick={() => setSubmenu(submenu === 'action' ? null : 'action')}
               className="w-full flex items-center justify-between gap-2 px-3 py-2 text-sm text-gray-700 dark:text-gray-200 hover:bg-gray-50 dark:hover:bg-gray-700"
@@ -124,6 +129,7 @@ export function FlowPalette({ onAdd, labels: labelsOverride, actionOptions }: Fl
               <div className="absolute left-full top-0 ml-1 w-64 rounded-xl border border-gray-200 dark:border-gray-700 bg-white dark:bg-gray-800 shadow-lg py-1">
                 {resolvedActionOptions.map((option) => (
                   <button
+                    data-cv-tooltip={option.label} aria-label={option.label}
                     key={option.actionKind}
                     onClick={() => select({ kind: 'action', actionKind: option.actionKind })}
                     className="w-full text-left px-3 py-2 text-sm text-gray-700 dark:text-gray-200 hover:bg-gray-50 dark:hover:bg-gray-700"

package/src/flows/FlowPortalNode.tsx

@@ -16,7 +16,7 @@ export function FlowPortalNode({ data }: NodeProps) {
   return (
     <button
       type="button"
-      title={labels.crossFlowPortal.tooltip}
+      data-cv-tooltip={labels.crossFlowPortal.tooltip} aria-label={labels.crossFlowPortal.tooltip}
       onClick={onNavigate}
       className="relative flex items-center gap-1.5 rounded-full border-2 border-dashed border-cyan-400 dark:border-cyan-600 bg-cyan-50 dark:bg-cyan-950/40 px-3 py-1.5 text-xs font-medium text-cyan-700 dark:text-cyan-300 hover:bg-cyan-100 dark:hover:bg-cyan-950/70 transition-colors cursor-pointer"
     >

package/src/flows/FlowsWorkspace.tsx

@@ -40,6 +40,7 @@ import {
   type FlowNodeData,
   type GraphIssue,
 } from './flowGraph'
+import { TooltipLayer } from '../Tooltip'
 
 const RF_NODE_TYPES = {
   ...flowNodeTypes,
@@ -966,6 +967,7 @@ export function FlowsWorkspace({
 
   return (
     <div className={`space-y-4 h-full flex flex-col ${className ?? ''}`}>
+      <TooltipLayer />
       <div className="flex items-center justify-between flex-wrap gap-3">
         <div>
           <h2 className="text-2xl font-bold text-gray-900 dark:text-gray-100">{labels.workspace.title}</h2>
@@ -977,6 +979,7 @@ export function FlowsWorkspace({
             <span className="text-sm text-red-600">{saveErrorMessage ?? labels.workspace.saveError}</span>
           )}
           <button
+            data-cv-tooltip={viewMode === 'map' ? labels.flowMap.toggleToDetail : labels.flowMap.toggleToMap} aria-label={viewMode === 'map' ? labels.flowMap.toggleToDetail : labels.flowMap.toggleToMap}
             type="button"
             onClick={() => setViewMode((mode) => (mode === 'map' ? 'detail' : 'map'))}
             className={OUTLINE_BUTTON}
@@ -990,7 +993,7 @@ export function FlowsWorkspace({
                 type="button"
                 onClick={handleOrganize}
                 className={OUTLINE_BUTTON}
-                title={labels.workspace.organizeTooltip}
+                data-cv-tooltip={labels.workspace.organizeTooltip} aria-label={labels.workspace.organizeTooltip}
                 disabled={!primaryGraph}
               >
                 <LayoutGrid size={14} aria-hidden="true" /> {labels.workspace.organize}
@@ -999,12 +1002,13 @@ export function FlowsWorkspace({
                 type="button"
                 onClick={handleDiscardChanges}
                 className={OUTLINE_BUTTON}
-                title={labels.workspace.discardTooltip}
+                data-cv-tooltip={labels.workspace.discardTooltip} aria-label={labels.workspace.discardTooltip}
                 disabled={!isDirty || saveState === 'saving'}
               >
                 <Undo2 size={14} aria-hidden="true" /> {labels.workspace.discardChanges}
               </button>
               <button
+                data-cv-tooltip={labels.workspace.saveGraph} aria-label={labels.workspace.saveGraph}
                 type="button"
                 onClick={() => void handlePublish()}
                 className={PRIMARY_BUTTON}
@@ -1024,6 +1028,7 @@ export function FlowsWorkspace({
             {graphs &&
               Object.values(graphs).map((graph) => (
                 <button
+                  data-cv-tooltip={graph.label} aria-label={graph.label}
                   key={graph.key}
                   type="button"
                   onClick={() => focusFlow(graph.key)}
@@ -1038,6 +1043,7 @@ export function FlowsWorkspace({
               ))}
             {canCreateFlow && (
               <button
+                data-cv-tooltip={labels.flowManager.newFlow} aria-label={labels.flowManager.newFlow}
                 type="button"
                 onClick={() => {
                   setFlowMutationState({ pending: false })
@@ -1059,6 +1065,7 @@ export function FlowsWorkspace({
             )}
             {primaryGraph && canDeleteFlow && (
               <button
+                data-cv-tooltip={labels.flowManager.deleteFlow} aria-label={labels.flowManager.deleteFlow}
                 type="button"
                 onClick={() => {
                   setFlowMutationState({ pending: false })
@@ -1186,10 +1193,11 @@ export function FlowsWorkspace({
             {flowMutationState.error && <p className="text-xs text-red-600">{flowMutationState.error}</p>}
           </div>
           <div className="flex justify-end gap-2 mt-4">
-            <button type="button" className={OUTLINE_BUTTON} onClick={() => setShowCreateDialog(false)}>
+            <button data-cv-tooltip={labels.nodePanel.cancel} aria-label={labels.nodePanel.cancel} type="button" className={OUTLINE_BUTTON} onClick={() => setShowCreateDialog(false)}>
               {labels.nodePanel.cancel}
             </button>
             <button
+              data-cv-tooltip={labels.flowManager.create} aria-label={labels.flowManager.create}
               type="button"
               className={PRIMARY_BUTTON}
               onClick={() => void handleCreateFlow()}
@@ -1208,10 +1216,11 @@ export function FlowsWorkspace({
           </p>
           {flowMutationState.error && <p className="text-xs text-red-600 mt-2">{flowMutationState.error}</p>}
           <div className="flex justify-end gap-2 mt-4">
-            <button type="button" className={OUTLINE_BUTTON} onClick={() => setShowDeleteDialog(false)}>
+            <button data-cv-tooltip={labels.nodePanel.cancel} aria-label={labels.nodePanel.cancel} type="button" className={OUTLINE_BUTTON} onClick={() => setShowDeleteDialog(false)}>
               {labels.nodePanel.cancel}
             </button>
             <button
+              data-cv-tooltip={labels.flowManager.deleteFlow} aria-label={labels.flowManager.deleteFlow}
               type="button"
               className="inline-flex items-center gap-1.5 rounded-lg bg-red-600 px-3 py-1.5 text-xs font-medium text-white hover:bg-red-700 disabled:opacity-40"
               onClick={() => void handleDeleteFlow()}