@farm-investimentos/front-mfe-components-vue3 1.3.0 → 1.4.0

package/src/components/Tooltip/__tests__/Tooltip.spec.js

@@ -1,21 +1,204 @@
-import { shallowMount } from '@vue/test-utils';
+import { nextTick } from 'vue';
 
-import Tooltip from '../Tooltip';
+import { mount } from '@vue/test-utils';
+
+import Tooltip from '../Tooltip.vue';
 
 describe('Tooltip component', () => {
 	let wrapper;
 
-	beforeEach(() => {
-		wrapper = shallowMount(Tooltip, {});
+	afterEach(() => {
+		if (wrapper) {
+			wrapper.unmount();
+		}
 	});
 
-	test('Created hook', () => {
-		expect(wrapper).toBeDefined();
-	});
+	const createWrapper = (props = {}, slots = {}) => {
+		const finalProps = {
+			delay: 0,
+			...props,
+		};
+
+		if (!Object.prototype.hasOwnProperty.call(props, 'modelValue')) {
+			delete finalProps.modelValue;
+		}
+
+		return mount(Tooltip, {
+			props: finalProps,
+			slots: {
+				activator: '<button>Hover me</button>',
+				default: 'Tooltip content',
+				...slots,
+			},
+		});
+	};
 
-	describe('mount component', () => {
+	describe('basic functionality', () => {
 		it('renders correctly', () => {
-			expect(wrapper.element).toBeDefined();
+			wrapper = createWrapper();
+			expect(wrapper.find('.tooltip-container').exists()).toBe(true);
+			expect(wrapper.find('.tooltip-activator').exists()).toBe(true);
+		});
+	});
+
+	describe('props', () => {
+		it('applies correct placement class', async () => {
+			wrapper = createWrapper({ placement: 'bottom-center', modelValue: true });
+			await nextTick();
+
+			expect(wrapper.find('.tooltip-popup--bottom-center').exists()).toBe(true);
+		});
+
+		it('applies correct variant class', async () => {
+			wrapper = createWrapper({ variant: 'dark', modelValue: true });
+			await nextTick();
+
+			expect(wrapper.find('.tooltip-popup--dark').exists()).toBe(true);
+		});
+
+		it('applies correct size class', async () => {
+			wrapper = createWrapper({ size: 'lg', modelValue: true });
+			await nextTick();
+
+			expect(wrapper.find('.tooltip-popup--lg').exists()).toBe(true);
+		});
+
+		it('respects disabled prop', () => {
+			wrapper = createWrapper({ disabled: true });
+			expect(wrapper.props('disabled')).toBe(true);
+		});
+	});
+
+	describe('controlled mode', () => {
+		it('shows tooltip when modelValue is true', async () => {
+			wrapper = createWrapper({ modelValue: true });
+			await nextTick();
+
+			expect(wrapper.vm.isVisible).toBe(true);
+		});
+
+		it('does not show tooltip when modelValue is false', async () => {
+			wrapper = createWrapper({ modelValue: false });
+			await nextTick();
+
+			expect(wrapper.vm.isVisible).toBe(false);
+		});
+
+		it('shows close button when controlled and has title', async () => {
+			wrapper = createWrapper({ modelValue: true }, { title: '<span>Title</span>' });
+			await nextTick();
+
+			expect(wrapper.find('.tooltip-close').exists()).toBe(true);
+		});
+
+		it('emits update:modelValue when close button is clicked', async () => {
+			wrapper = createWrapper({ modelValue: true }, { title: '<span>Title</span>' });
+			await nextTick();
+
+			await wrapper.find('.tooltip-close').trigger('click');
+
+			expect(wrapper.emitted('update:modelValue')).toBeTruthy();
+			expect(wrapper.emitted('update:modelValue')[0]).toEqual([false]);
+		});
+	});
+
+	describe('slots', () => {
+		it('renders activator slot content', () => {
+			wrapper = createWrapper(
+				{},
+				{
+					activator: '<span class="custom-activator">Custom</span>',
+				}
+			);
+
+			expect(wrapper.find('.custom-activator').exists()).toBe(true);
+			expect(wrapper.find('.custom-activator').text()).toBe('Custom');
+		});
+
+		it('renders title slot when provided', async () => {
+			wrapper = createWrapper(
+				{ modelValue: true },
+				{ title: '<span class="custom-title">Custom Title</span>' }
+			);
+			await nextTick();
+
+			expect(wrapper.find('.tooltip-title').exists()).toBe(true);
+			expect(wrapper.find('.custom-title').exists()).toBe(true);
+		});
+
+		it('renders default slot content', async () => {
+			wrapper = createWrapper({ modelValue: true });
+			await nextTick();
+
+			expect(wrapper.find('.tooltip-content').text()).toContain('Tooltip content');
+		});
+	});
+
+	describe('computed properties', () => {
+		it('calculates tooltip classes correctly', async () => {
+			wrapper = createWrapper({
+				modelValue: true,
+				variant: 'dark',
+				size: 'lg',
+				placement: 'top-center',
+			});
+			await nextTick();
+
+			const classes = wrapper.vm.tooltipClasses;
+			expect(classes['tooltip-popup']).toBe(true);
+			expect(classes['tooltip-popup--visible']).toBe(true);
+			expect(classes['tooltip-popup--dark']).toBe(true);
+			expect(classes['tooltip-popup--lg']).toBe(true);
+			expect(classes['tooltip-popup--top-center']).toBe(true);
+		});
+
+		it('calculates arrow styles correctly', () => {
+			wrapper = createWrapper({ placement: 'top-center' });
+
+			const styles = wrapper.vm.arrowStyles;
+			expect(styles.left).toBe('50%');
+			expect(styles.transform).toBe('translateX(-50%)');
+			expect(styles.bottom).toBe('-6px');
+		});
+
+		it('calculates controlled state correctly', () => {
+			const uncontrolledWrapper = createWrapper();
+			expect(uncontrolledWrapper.vm.isControlled).toBe(false);
+
+			const controlledWrapper = createWrapper({ modelValue: true });
+			expect(controlledWrapper.vm.isControlled).toBe(true);
+
+			uncontrolledWrapper.unmount();
+			controlledWrapper.unmount();
+		});
+	});
+
+	describe('props validation', () => {
+		it('accepts valid placement values', () => {
+			const placements = [
+				'top-left',
+				'top-center',
+				'top-right',
+				'bottom-left',
+				'bottom-center',
+				'bottom-right',
+			];
+
+			placements.forEach(placement => {
+				wrapper = createWrapper({ placement, modelValue: true });
+				expect(wrapper.find(`.tooltip-popup--${placement}`).exists()).toBe(true);
+				wrapper.unmount();
+			});
+		});
+
+		it('accepts valid size values', () => {
+			const sizes = ['sm', 'md', 'lg'];
+
+			sizes.forEach(size => {
+				wrapper = createWrapper({ size, modelValue: true });
+				expect(wrapper.find(`.tooltip-popup--${size}`).exists()).toBe(true);
+				wrapper.unmount();
+			});
 		});
 	});
 });

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

@@ -0,0 +1,287 @@
+# 🎯 Tooltip Component
+
+## Visão Geral
+
+O componente Tooltip fornece informações contextuais ao usuário através de uma pequena caixa flutuante que aparece ao interagir com um elemento. Ideal para exibir textos explicativos, dicas ou informações adicionais sem poluir a interface.
+
+## 🚀 Features
+
+### Posicionamento Inteligente
+- 6 posições pré-definidas com detecção automática de colisão
+- Reposicionamento automático quando próximo às bordas da viewport
+- Seta indicadora que sempre aponta para o centro do elemento ativador
+
+### Modos de Ativação
+- **Hover**: Aparece ao passar o mouse (padrão)
+- **Click**: Ativado por clique
+- **Manual**: Controle total via v-model
+
+### Comportamento Responsivo
+- Z-index dinâmico que detecta modais e se ajusta automaticamente
+- Scroll listeners para manter posicionamento correto
+- Suporte a elementos scrolláveis dentro de modais
+
+### Performance
+- Lazy rendering - só renderiza quando visível
+- Cache inteligente para detecção de modais
+- Event listeners otimizados com passive: true
+
+## 📦 Instalação e Importação
+
+```javascript
+import { Tooltip } from '@farm-investimentos/front-mfe-components-vue3';
+```
+
+## 🎨 API
+
+### Props
+
+| Prop | Tipo | Padrão | Descrição |
+|------|------|---------|-----------|
+| `modelValue` | `boolean` | `undefined` | Controle de visibilidade (v-model) |
+| `trigger` | `'hover' \| 'click' \| 'manual'` | `'hover'` | Modo de ativação |
+| `placement` | `TooltipPlacement` | `'top-center'` | Posição do tooltip |
+| `offset` | `number` | `8` | Distância do elemento ativador (px) |
+| `variant` | `'dark'` | `'dark'` | Tema visual (apenas dark disponível) |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Tamanho do tooltip |
+| `maxWidth` | `string \| number` | `undefined` | Largura máxima customizada |
+| `delay` | `number \| [number, number]` | `[100, 50]` | Delay para mostrar/esconder (ms) |
+| `disabled` | `boolean` | `false` | Desabilita o tooltip |
+| `fluid` | `boolean` | `false` | Largura fluida (max 300px) |
+
+### Eventos
+
+| Evento | Payload | Descrição |
+|--------|---------|-----------|
+| `update:modelValue` | `boolean` | Emitido ao mudar visibilidade |
+| `show` | - | Emitido ao mostrar |
+| `hide` | - | Emitido ao esconder |
+
+### Slots
+
+| Slot | Props | Descrição |
+|------|-------|-----------|
+| `activator` | - | Elemento que ativa o tooltip |
+| `default` | - | Conteúdo principal |
+| `title` | - | Título opcional (só aparece em modo controlado) |
+
+## 💡 Exemplos de Uso
+
+### Básico
+```vue
+<Tooltip>
+  <template #activator>
+    <button>Hover me</button>
+  </template>
+  Informação adicional sobre este botão
+</Tooltip>
+```
+
+### Posicionamento Customizado
+```vue
+<Tooltip placement="bottom-right" :offset="12">
+  <template #activator>
+    <IconHelp />
+  </template>
+  Ajuda contextual posicionada à direita
+</Tooltip>
+```
+
+### Modo Controlado com Título
+```vue
+<template>
+  <Tooltip v-model="showHelp">
+    <template #activator>
+      <button @click="showHelp = !showHelp">
+        Toggle Help
+      </button>
+    </template>
+    <template #title>
+      Informações Importantes
+    </template>
+    <ul>
+      <li>Primeiro ponto</li>
+      <li>Segundo ponto</li>
+      <li>Terceiro ponto</li>
+    </ul>
+  </Tooltip>
+</template>
+
+<script setup>
+import { ref } from 'vue';
+const showHelp = ref(false);
+</script>
+```
+
+### Tooltip Fluido para Conteúdo Longo
+```vue
+<Tooltip :fluid="true">
+  <template #activator>
+    <span>Ver descrição completa</span>
+  </template>
+  Este é um texto mais longo que se adapta automaticamente
+  à largura do conteúdo, expandindo até o máximo de 300px
+  antes de quebrar em múltiplas linhas.
+</Tooltip>
+```
+
+### Diferentes Tamanhos
+```vue
+<div class="flex gap-4">
+  <Tooltip size="sm">
+    <template #activator>
+      <Badge>SM</Badge>
+    </template>
+    Tooltip pequeno
+  </Tooltip>
+  
+  <Tooltip size="md">
+    <template #activator>
+      <Badge>MD</Badge>
+    </template>
+    Tooltip médio (padrão)
+  </Tooltip>
+  
+  <Tooltip size="lg">
+    <template #activator>
+      <Badge>LG</Badge>
+    </template>
+    Tooltip grande com mais espaçamento
+  </Tooltip>
+</div>
+```
+
+### Com Delay Customizado
+```vue
+<Tooltip :delay="[500, 0]">
+  <template #activator>
+    <button>Hover com delay</button>
+  </template>
+  Aparece após 500ms, desaparece instantaneamente
+</Tooltip>
+```
+
+## 🎯 Casos de Uso Comuns
+
+### 1. Ícones de Ajuda
+```vue
+<label>
+  CPF
+  <Tooltip placement="top-right">
+    <template #activator>
+      <IconQuestion class="ml-1 text-gray-400" />
+    </template>
+    Digite apenas números, sem pontos ou traços
+  </Tooltip>
+</label>
+```
+
+### 2. Botões com Ações Desabilitadas
+```vue
+<Tooltip :disabled="canDelete">
+  <template #activator>
+    <button :disabled="!canDelete" @click="handleDelete">
+      Excluir
+    </button>
+  </template>
+  Você não tem permissão para excluir este item
+</Tooltip>
+```
+
+### 3. Truncate com Preview Completo
+```vue
+<Tooltip>
+  <template #activator>
+    <p class="truncate max-w-xs">
+      {{ longText }}
+    </p>
+  </template>
+  {{ longText }}
+</Tooltip>
+```
+
+### 4. Status com Detalhes
+```vue
+<Tooltip placement="bottom-center">
+  <template #activator>
+    <StatusBadge :status="order.status" />
+  </template>
+  <div>
+    <p><strong>Status:</strong> {{ order.status }}</p>
+    <p><strong>Atualizado:</strong> {{ order.updatedAt }}</p>
+    <p><strong>Por:</strong> {{ order.updatedBy }}</p>
+  </div>
+</Tooltip>
+```
+
+## ⚡ Performance e Boas Práticas
+
+### Do's ✅
+- Use tooltips para informações secundárias e não-críticas
+- Mantenha o conteúdo conciso e direto
+- Use o placement adequado para não cobrir elementos importantes
+- Para conteúdo complexo, considere usar um Popover ou Modal
+
+### Don'ts ❌
+- Não use tooltips para informações essenciais
+- Evite tooltips em elementos mobile/touch
+- Não coloque formulários ou ações dentro de tooltips
+- Evite tooltips aninhados
+
+## 🔧 Troubleshooting
+
+### Tooltip aparece atrás de outros elementos
+O componente já calcula automaticamente o z-index baseado em modais presentes. Se ainda houver problemas, verifique se o elemento pai não tem `overflow: hidden`.
+
+### Tooltip não aparece
+1. Verifique se `disabled` não está `true`
+2. Em modo controlado, certifique-se que `modelValue` está sendo atualizado
+3. Verifique se o slot `activator` tem apenas um elemento raiz
+
+### Posicionamento incorreto
+O tooltip se reposiciona automaticamente ao detectar scroll ou resize. Se o problema persistir:
+1. Verifique se o elemento activator não está com `position: fixed`
+2. Certifique-se que o container pai não tem transforms 3D
+
+## 🎨 Customização
+
+### CSS Variables
+```css
+.tooltip-popup {
+  --tooltip-bg: #333333;
+  --tooltip-color: #f5f5f5;
+  --tooltip-radius: 5px;
+  --tooltip-font-size: 12px;
+  --tooltip-padding: 16px;
+}
+```
+
+### Classes para Styling
+```css
+.tooltip-popup--visible { /* Quando visível */ }
+.tooltip-popup--sm { /* Tamanho pequeno */ }
+.tooltip-popup--md { /* Tamanho médio */ }
+.tooltip-popup--lg { /* Tamanho grande */ }
+.tooltip-popup--has-title { /* Quando tem título */ }
+```
+
+## 📊 Especificações Técnicas
+
+### Posições Suportadas
+- `top-left`: Acima e alinhado à esquerda
+- `top-center`: Acima e centralizado
+- `top-right`: Acima e alinhado à direita
+- `bottom-left`: Abaixo e alinhado à esquerda
+- `bottom-center`: Abaixo e centralizado
+- `bottom-right`: Abaixo e alinhado à direita
+
+### Comportamento da Seta
+- Sempre aponta para o centro do elemento ativador
+- Ajusta-se dinamicamente quando o tooltip é reposicionado
+- Mantém margem mínima de 12px das bordas
+
+### Detecção de Colisão
+- Viewport boundaries detection
+- Automatic repositioning
+- Scroll containers support
+- Modal-aware positioning

package/src/components/Tooltip/index.ts

@@ -1,5 +1,20 @@
 import Tooltip from './Tooltip.vue';
-
-export default Tooltip;
+import type {
+	TooltipProps,
+	TooltipEmits,
+	TooltipPlacement,
+	TooltipTrigger,
+	TooltipVariant,
+	TooltipSize,
+} from './types';
 
 export { Tooltip };
+export type {
+	TooltipProps,
+	TooltipEmits,
+	TooltipPlacement,
+	TooltipTrigger,
+	TooltipVariant,
+	TooltipSize,
+};
+export default Tooltip;

package/src/components/Tooltip/types.ts

@@ -0,0 +1,51 @@
+export type TooltipPlacement =
+	| 'top-left'
+	| 'top-center'
+	| 'top-right'
+	| 'bottom-left'
+	| 'bottom-center'
+	| 'bottom-right';
+
+export type TooltipTrigger = 'hover' | 'click' | 'manual';
+
+export type TooltipVariant = 'dark' | 'light';
+
+export type TooltipSize = 'sm' | 'md' | 'lg';
+
+export interface TooltipProps {
+	// Visibility control (Vue 3 style)
+	modelValue?: boolean; // v-model
+	trigger?: TooltipTrigger;
+
+	// Placement (all 6 positions are supported)
+	placement?: TooltipPlacement;
+	offset?: number;
+
+	// Aparência
+	variant?: TooltipVariant;
+	size?: TooltipSize;
+	maxWidth?: string | number;
+
+	// Comportamento
+	delay?: number | [number, number]; // [show, hide]
+	disabled?: boolean;
+	fluid?: boolean;
+	position?: string;
+}
+
+export interface TooltipEmits {
+	'update:modelValue': [value: boolean]; // Vue 3 v-model
+	show: [];
+	hide: [];
+}
+
+export interface Position {
+	x: number;
+	y: number;
+}
+
+export interface TooltipState {
+	isVisible: boolean;
+	position: Position;
+	actualPlacement: TooltipPlacement;
+}