@farm-investimentos/front-mfe-components 15.14.3 → 15.14.5

package/src/components/Tooltip/docs/README.md

@@ -0,0 +1,304 @@
+# Tooltip Component
+
+Componente de tooltip simples e eficiente para Vue 2.7, com suporte a 6 posições, controle via v-model e comportamento otimizado para modais.
+
+## 🎯 Características
+
+-   ✅ **6 posições**: `top-left`, `top-center`, `top-right`, `bottom-left`, `bottom-center`, `bottom-right`
+-   ✅ **Vue 2.7 compatível** com Composition API
+-   ✅ **v-model support** para tooltips controlados
+-   ✅ **Seta inteligente** que aponta para o centro do ativador
+-   ✅ **Scroll detection** automático em modais
+-   ✅ **Position fixed** para evitar problemas de overflow
+-   ✅ **Cleanup automático** de event listeners
+
+## 📦 Instalação
+
+```typescript
+import Tooltip from '@/components/Tooltip';
+
+export default {
+	components: { Tooltip },
+};
+```
+
+## 🚀 Uso Básico
+
+### Tooltip Simples
+
+```vue
+<farm-tooltip placement="top-center">
+  <template v-slot:activator>
+    <farm-icon size="sm" color="gray">help-circle</farm-icon>
+  </template>
+  Este é um tooltip simples
+</farm-tooltip>
+```
+
+### Tooltip com Título
+
+```vue
+<farm-tooltip placement="top-left">
+  <template v-slot:activator>
+    <farm-icon size="sm" color="gray">help-circle</farm-icon>
+  </template>
+  <template v-slot:title>Informação Importante</template>
+  Conteúdo do tooltip com título
+</farm-tooltip>
+```
+
+### Tooltip Fluido
+
+```vue
+<farm-tooltip placement="top-center" :fluid="true">
+  <template v-slot:activator>
+    <farm-icon size="sm" color="gray">help-circle</farm-icon>
+  </template>
+  Este tooltip tem largura baseada no conteúdo e se adapta automaticamente
+</farm-tooltip>
+```
+
+### Tooltip com Posição Legacy
+
+```vue
+<farm-tooltip position="top-left">
+  <template v-slot:activator>
+    <farm-icon size="sm" color="gray">help-circle</farm-icon>
+  </template>
+  Tooltip usando a prop position (legacy)
+</farm-tooltip>
+```
+
+### Tooltip Controlado (v-model)
+
+```vue
+<template>
+	<farm-tooltip v-model="showTooltip" placement="top-right">
+		<template v-slot:activator>
+			<farm-icon @click="showTooltip = !showTooltip" size="md" color="blue"
+				>help-circle</farm-icon
+			>
+		</template>
+		<template v-slot:title>Tooltip Controlado</template>
+		Este tooltip é controlado por v-model
+	</farm-tooltip>
+</template>
+
+<script>
+export default {
+	data() {
+		return {
+			showTooltip: false,
+		};
+	},
+};
+</script>
+```
+
+## 📋 Props
+
+| Prop        | Tipo               | Padrão         | Descrição                       |
+| ----------- | ------------------ | -------------- | ------------------------------- |
+| `value`     | `Boolean`          | `undefined`    | Controla visibilidade (v-model) |
+| `trigger`   | `TooltipTrigger`   | `'hover'`      | Como o tooltip é ativado        |
+| `placement` | `TooltipPlacement` | `'top-center'` | Posição do tooltip              |
+| `offset`    | `Number`           | `8`            | Distância do ativador (px)      |
+| `variant`   | `TooltipVariant`   | `'dark'`       | Variante visual do tooltip      |
+| `size`      | `TooltipSize`      | `'md'`         | Tamanho do tooltip              |
+| `maxWidth`  | `String \| Number` | `undefined`    | Largura máxima                  |
+| `delay`     | `Number \| Array`  | `[100, 50]`    | Delay para show/hide            |
+| `disabled`  | `Boolean`          | `false`        | Desabilita o tooltip            |
+| `fluid`     | `Boolean`          | `false`        | Largura baseada no conteúdo     |
+| `position`  | `String`           | `undefined`    | Posição alternativa (legacy)    |
+
+## 🎨 Posições Disponíveis
+
+```typescript
+type TooltipPlacement =
+	| 'top-left' // Seta no canto esquerdo, aponta para centro do ativador
+	| 'top-center' // Seta no centro, aponta para centro do ativador
+	| 'top-right' // Seta no canto direito, aponta para centro do ativador
+	| 'bottom-left' // Seta no canto esquerdo, aponta para centro do ativador
+	| 'bottom-center' // Seta no centro, aponta para centro do ativador
+	| 'bottom-right'; // Seta no canto direito, aponta para centro do ativador
+```
+
+## 🎭 Slots
+
+| Slot        | Descrição                                  |
+| ----------- | ------------------------------------------ |
+| `activator` | Elemento que ativa o tooltip (obrigatório) |
+| `title`     | Título do tooltip (opcional)               |
+| `default`   | Conteúdo principal do tooltip              |
+
+## 📡 Events
+
+| Event   | Payload   | Descrição                                  |
+| ------- | --------- | ------------------------------------------ |
+| `input` | `boolean` | Emitido quando visibilidade muda (v-model) |
+| `show`  | -         | Emitido quando tooltip aparece             |
+| `hide`  | -         | Emitido quando tooltip esconde             |
+
+## 🏗️ Arquitetura
+
+### Estrutura de Arquivos
+
+```
+src/components/Tooltip/
+├── Tooltip.vue          # Componente principal
+├── Tooltip.scss         # Estilos
+├── Tooltip.stories.js   # Stories do Storybook
+├── index.ts            # Exports
+├── utils/
+│   └── tooltip.utils.ts # Utilitários de posicionamento
+├── types/
+│   └── tooltip.types.ts # Tipos TypeScript
+└── docs/
+    └── README.md        # Esta documentação
+```
+
+### Componentes Principais
+
+#### `Tooltip.vue`
+
+-   **Lógica principal** com Composition API
+-   **Event handlers** para show/hide
+-   **Scroll detection** automático
+-   **Position calculation** via utils
+-   **Cleanup** automático de listeners
+
+#### `tooltip.utils.ts`
+
+-   **`calculateTooltipPosition`** - Calcula posição baseada no ativador
+-   **`moveToBody`** - Move tooltip para body (portal effect)
+-   **`moveToContainer`** - Move tooltip de volta ao container
+
+## 🎯 Casos de Uso
+
+### Em Modais com Scroll
+
+O tooltip detecta automaticamente scroll em modais e atualiza sua posição:
+
+```vue
+<farm-modal v-model="showModal">
+  <template v-slot:content>
+    <div style="height: 400px; overflow-y: auto;">
+      <farm-tooltip placement="top-left">
+        <template v-slot:activator>
+          <farm-icon size="sm" color="gray">help-circle</farm-icon>
+        </template>
+        Tooltip que se move com scroll
+      </farm-tooltip>
+    </div>
+  </template>
+</farm-modal>
+```
+
+### Múltiplos Tooltips
+
+```vue
+<div style="display: flex; gap: 20px;">
+  <farm-tooltip placement="top-left">
+    <template v-slot:activator>
+      <farm-icon size="sm" color="gray">help-circle</farm-icon>
+    </template>
+    Tooltip 1
+  </farm-tooltip>
+  
+  <farm-tooltip placement="top-center">
+    <template v-slot:activator>
+      <farm-icon size="sm" color="gray">help-circle</farm-icon>
+    </template>
+    Tooltip 2
+  </farm-tooltip>
+</div>
+```
+
+## 🔧 Customização
+
+### Estilos CSS
+
+O tooltip usa classes CSS que podem ser customizadas:
+
+```scss
+.tooltip-popup {
+	background-color: #333333;
+	color: #f5f5f5;
+	border-radius: 5px;
+	font-family: 'Manrope', sans-serif;
+	font-size: 12px;
+	font-weight: 500;
+	padding: 16px;
+	position: fixed;
+	z-index: 9999;
+
+	&--visible {
+		opacity: 1;
+		visibility: visible;
+	}
+
+	.tooltip-header {
+		display: flex;
+		justify-content: space-between;
+		align-items: center;
+		margin-bottom: 8px;
+	}
+
+	.tooltip-title {
+		font-weight: 600;
+		font-size: 13px;
+		margin-right: 16px;
+	}
+
+	.tooltip-close {
+		cursor: pointer;
+		font-size: 16px;
+	}
+}
+```
+
+### Posicionamento da Seta
+
+A seta é posicionada automaticamente para apontar para o centro do ativador:
+
+-   **`left/right`**: Seta a 24px da borda, aponta para centro do ativador
+-   **`center`**: Seta no centro do tooltip, aponta para centro do ativador
+
+## 🐛 Troubleshooting
+
+### Tooltip não aparece
+
+-   Verifique se o `activator` slot está definido
+-   Confirme que o elemento ativador está visível
+-   Verifique se não há `z-index` conflitantes
+
+### Tooltip não se move com scroll
+
+-   O tooltip detecta scroll automaticamente
+-   Se não funcionar, verifique se o elemento com scroll tem `overflow-y: auto/scroll`
+-   O tooltip se esconde automaticamente se o ativador sair da viewport
+
+### Seta mal posicionada
+
+-   A seta sempre aponta para o centro do ativador
+-   Para `left/right`, a seta fica a 18px da borda
+-   Para `center`, a seta fica no centro do tooltip
+
+## 📚 Exemplos no Storybook
+
+Acesse `http://localhost:6006` e navegue para **Display/Tooltip** para ver exemplos interativos:
+
+-   **Primary** - Tooltip básico
+-   **AllPositions** - Todas as 6 posições
+-   **ControlledTooltip** - Tooltip com v-model
+-   **FluidTooltip** - Tooltip com largura fluida
+-   **WithModal** - Tooltip em modal com scroll
+-   **MultipleTooltips** - Múltiplos tooltips
+
+## 🤝 Contribuição
+
+1. Mantenha a simplicidade do componente
+2. Teste em modais com scroll
+3. Verifique se a seta aponta corretamente
+4. Use os stories para testar mudanças
+5. Atualize esta documentação se necessário

package/src/components/Tooltip/docs/SPECIFICATION.md

@@ -0,0 +1,374 @@
+# Tooltip Component - Especificação Técnica
+
+## 📋 Visão Geral
+
+O componente `Tooltip` é uma implementação simples e eficiente de tooltip para Vue 2.7, projetado para ser fácil de usar e manter, com foco em performance e compatibilidade.
+
+## 🎯 Objetivos de Design
+
+### Simplicidade
+
+-   **Lógica direta**: Sem cálculos complexos desnecessários
+-   **API simples**: Props e slots intuitivos
+-   **Manutenibilidade**: Código limpo e bem estruturado
+
+### Performance
+
+-   **Event listeners otimizados**: Uso de `passive: true`
+-   **Cleanup automático**: Remoção de listeners no unmount
+-   **Position fixed**: Evita reflows desnecessários
+
+### Compatibilidade
+
+-   **Vue 2.7**: Suporte completo com Composition API
+-   **Modais**: Funciona perfeitamente em contextos com scroll
+-   **Retrocompatibilidade**: Mantém props antigas quando possível
+
+## 🏗️ Arquitetura
+
+### Estrutura de Componentes
+
+```
+Tooltip.vue (Principal)
+├── Template
+│   ├── Container (position: relative)
+│   ├── Activator (slot)
+│   └── Tooltip Content (position: fixed)
+│       ├── Header (title + close button)
+│       ├── Content (default slot)
+│       └── Arrow (CSS-based)
+├── Script (Composition API)
+│   ├── Props & Emits
+│   ├── Refs & State
+│   ├── Computed Properties
+│   ├── Event Handlers
+│   ├── Scroll Detection
+│   └── Lifecycle Hooks
+└── Styles (SCSS)
+    ├── Base styles
+    ├── States (visible/hidden)
+    └── Arrow positioning
+```
+
+### Fluxo de Dados
+
+```
+User Interaction → Event Handler → State Update → DOM Update → Position Calculation
+     ↓
+Scroll Detection → Position Update → Viewport Check → Auto Hide (if needed)
+```
+
+## 🔧 Implementação Técnica
+
+### Props Interface
+
+```typescript
+interface TooltipProps {
+	// Visibility control (Vue 2.7 style)
+	value?: boolean; // v-model
+	trigger?: TooltipTrigger; // 'hover' | 'click' | 'manual'
+
+	// Posicionamento
+	placement?: TooltipPlacement; // 6 posições disponíveis
+	offset?: number; // Distância do ativador
+
+	// Aparência
+	variant?: TooltipVariant; // 'dark' | 'light'
+	size?: TooltipSize; // 'sm' | 'md' | 'lg'
+	fluid?: boolean; // Largura baseada no conteúdo
+	maxWidth?: string | number; // Largura máxima
+
+	// Comportamento
+	delay?: number | [number, number]; // Delay para show/hide
+	disabled?: boolean; // Desabilita o tooltip
+
+	// Legacy (mantido para compatibilidade)
+	position?: string; // Posição alternativa
+}
+```
+
+### State Management
+
+```typescript
+// Refs principais
+const isVisible = ref(false);
+const containerRef = ref<HTMLElement | null>(null);
+const activatorRef = ref<HTMLElement | null>(null);
+const tooltipRef = ref<HTMLElement | null>(null);
+
+// Computed properties
+const isControlled = computed(() => props.value !== undefined);
+const hasTitle = computed(() => !!slots.title);
+const showCloseButton = computed(() => isControlled.value && hasTitle.value);
+```
+
+### Event Handling
+
+#### Show/Hide Logic
+
+```typescript
+const show = () => {
+	if (props.disabled || isControlled.value) return;
+
+	isVisible.value = true;
+	emit('show');
+
+	nextTick(() => {
+		if (tooltipRef.value && activatorRef.value) {
+			moveToBody(tooltipRef.value);
+			updatePosition();
+			addScrollListener();
+		}
+	});
+};
+
+const hide = () => {
+	if (props.disabled || isControlled.value) return;
+
+	isVisible.value = false;
+	emit('hide');
+	removeScrollListener();
+};
+```
+
+#### Scroll Detection
+
+```typescript
+const addScrollListener = () => {
+	window.addEventListener('scroll', updatePosition, { passive: true });
+
+	const scrollableElements = document.querySelectorAll(
+		'.farm-modal, .modal-content, [style*="overflow-y: auto"], [style*="overflow-y: scroll"]'
+	);
+	scrollableElements.forEach(element => {
+		element.addEventListener('scroll', updatePosition, { passive: true });
+	});
+};
+```
+
+### Position Calculation
+
+#### Utils Function
+
+```typescript
+export function calculateTooltipPosition(
+	activatorRect: TooltipRect,
+	tooltipRect: TooltipRect,
+	placement: string,
+	offset: number = 8
+): TooltipPosition {
+	const [verticalPos, horizontalAlign] = placement.split('-');
+
+	let left = 0;
+	let top = 0;
+
+	// Posição vertical
+	if (verticalPos === 'top') {
+		top = activatorRect.top - tooltipRect.height - offset;
+	} else {
+		top = activatorRect.bottom + offset;
+	}
+
+	// Posição horizontal com seta inteligente
+	switch (horizontalAlign) {
+		case 'left':
+			left = activatorRect.left + activatorRect.width / 2 - 18;
+			break;
+		case 'right':
+			left = activatorRect.left + activatorRect.width / 2 - (tooltipRect.width - 18);
+			break;
+		case 'center':
+		default:
+			left = activatorRect.left + activatorRect.width / 2 - tooltipRect.width / 2;
+			break;
+	}
+
+	return { left, top };
+}
+```
+
+## 🎨 Sistema de Posicionamento
+
+### 6 Posições Suportadas
+
+| Posição         | Seta             | Comportamento                  |
+| --------------- | ---------------- | ------------------------------ |
+| `top-left`      | 24px da esquerda | Aponta para centro do ativador |
+| `top-center`    | Centro           | Aponta para centro do ativador |
+| `top-right`     | 24px da direita  | Aponta para centro do ativador |
+| `bottom-left`   | 24px da esquerda | Aponta para centro do ativador |
+| `bottom-center` | Centro           | Aponta para centro do ativador |
+| `bottom-right`  | 24px da direita  | Aponta para centro do ativador |
+
+### Lógica da Seta
+
+```typescript
+const ARROW_OFFSET = 24;
+
+const arrowStyles = computed(() => {
+	const [verticalPos, horizontalAlign] = normalizedPlacement.value.split('-');
+
+	const styles: Record<string, string> = {
+		position: 'absolute',
+		width: '0',
+		height: '0',
+		borderStyle: 'solid',
+		zIndex: '10000',
+	};
+
+	if (verticalPos === 'top') {
+		styles.bottom = '-6px';
+		styles.borderWidth = '6px 6px 0 6px';
+		styles.borderColor = '#333333 transparent transparent transparent';
+	} else {
+		styles.top = '-6px';
+		styles.borderWidth = '0 6px 6px 6px';
+		styles.borderColor = 'transparent transparent #333333 transparent';
+	}
+
+	if (horizontalAlign === 'left') {
+		styles.left = `${ARROW_OFFSET}px`;
+	} else if (horizontalAlign === 'right') {
+		styles.right = `${ARROW_OFFSET}px`;
+	} else {
+		styles.left = '50%';
+		styles.transform = 'translateX(-50%)';
+	}
+
+	return styles;
+});
+```
+
+## 🔄 Portal Effect
+
+### DOM Manipulation
+
+```typescript
+export function moveToBody(element: HTMLElement): void {
+	if (element.parentNode !== document.body) {
+		document.body.appendChild(element);
+	}
+}
+
+export function moveToContainer(element: HTMLElement, container: HTMLElement): void {
+	if (element.parentNode === document.body) {
+		container.appendChild(element);
+	}
+}
+```
+
+### Por que Portal?
+
+-   **Evita overflow**: Tooltip não fica cortado por containers
+-   **Z-index**: Sempre fica acima de outros elementos
+-   **Scroll**: Não é afetado por scroll do container pai
+
+## 🎯 Casos de Uso Específicos
+
+### Modal com Scroll
+
+```vue
+<farm-modal v-model="showModal">
+  <template v-slot:content>
+    <div style="height: 400px; overflow-y: auto;">
+      <farm-tooltip placement="top-left">
+        <template v-slot:activator>
+          <farm-icon size="sm" color="gray">help-circle</farm-icon>
+        </template>
+        Tooltip que se move com scroll
+      </farm-tooltip>
+    </div>
+  </template>
+</farm-modal>
+```
+
+**Comportamento:**
+
+1. Tooltip detecta scroll no modal
+2. Atualiza posição automaticamente
+3. Esconde se ativador sair da viewport
+4. Remove listeners quando esconde
+
+### Tooltip Controlado
+
+```vue
+<farm-tooltip v-model="showTooltip" placement="top-right">
+  <template v-slot:activator>
+    <farm-icon @click="showTooltip = !showTooltip">help-circle</farm-icon>
+  </template>
+  <template v-slot:title>Tooltip Controlado</template>
+  Conteúdo do tooltip
+</farm-tooltip>
+```
+
+**Comportamento:**
+
+1. Visibilidade controlada por v-model
+2. Botão de fechar aparece automaticamente
+3. Eventos `show`/`hide` emitidos
+4. Cleanup automático de listeners
+
+## 🧪 Testes
+
+### Cenários de Teste
+
+1. **Posicionamento**
+
+    - [ ] Todas as 6 posições funcionam
+    - [ ] Seta aponta para centro do ativador
+    - [ ] Tooltip não sai da viewport
+
+2. **Interação**
+
+    - [ ] Hover show/hide funciona
+    - [ ] v-model funciona corretamente
+    - [ ] Botão de fechar funciona
+
+3. **Scroll**
+
+    - [ ] Tooltip se move com scroll
+    - [ ] Tooltip esconde quando ativador sai da viewport
+    - [ ] Listeners são removidos corretamente
+
+4. **Modal**
+    - [ ] Funciona em modal com scroll
+    - [ ] Posição atualiza corretamente
+    - [ ] Não interfere com outros elementos
+
+### Como Testar
+
+```bash
+# Executar testes
+npm run test:unit -- Tooltip
+
+# Executar Storybook
+npm run storybook
+
+# Testar manualmente
+# 1. Acesse http://localhost:6006
+# 2. Navegue para Display/Tooltip
+# 3. Teste todos os stories
+# 4. Especialmente o "WithModal"
+```
+
+## 🔮 Roadmap
+
+### Melhorias Futuras
+
+-   [ ] **Auto-flip**: Inverter posição se não couber na viewport
+-   [ ] **Animations**: Transições suaves
+-   [ ] **Themes**: Suporte a temas diferentes
+-   [ ] **Accessibility**: Melhor suporte a acessibilidade
+
+### Limitações Atuais
+
+-   **Vue 2.7**: Não usa Teleport nativo (não disponível)
+-   **Manual DOM**: Manipulação manual para portal effect
+-   **Fixed positioning**: Sempre usa position: fixed
+
+## 📚 Referências
+
+-   [Vue 2.7 Composition API](https://v2.vuejs.org/v2/guide/composition-api.html)
+-   [CSS Position Fixed](https://developer.mozilla.org/en-US/docs/Web/CSS/position)
+-   [DOM Event Listeners](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener)
+-   [Bounding Client Rect](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect)

package/src/components/Tooltip/index.ts

@@ -3,3 +3,19 @@ import Tooltip from './Tooltip.vue';
 export default Tooltip;
 
 export { Tooltip };
+
+// Export types for external use
+export type {
+	TooltipPlacement,
+	TooltipTrigger,
+	TooltipVariant,
+	TooltipSize,
+	TooltipProps,
+	TooltipEvents,
+	Position,
+} from './types/tooltip.types';
+
+// Export utilities
+export { calculateTooltipPosition, moveToBody, moveToContainer } from './utils/tooltip.utils';
+
+export type { TooltipPosition, TooltipRect } from './utils/tooltip.utils';