@etus/ui 0.1.0

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

@@ -0,0 +1,671 @@
+# Tooltip
+
+## Visão Geral
+
+O componente **Tooltip** exibe informacoes contextuais curtas quando o usuario passa o mouse ou foca em um elemento. Ideal para fornecer dicas, explicacoes de icones ou informacoes adicionais sem poluir a interface.
+
+### Classificacao Atomica
+
+- **Categoria**: Atoms
+- **Subcategoria**: Feedback / Overlay
+
+### Casos de Uso Comuns
+
+- Explicar icones e botoes de acao
+- Mostrar texto completo de conteudo truncado
+- Fornecer atalhos de teclado
+- Exibir datas completas ou detalhes
+- Dicas de uso para funcionalidades
+
+### Relacao com Outros Componentes
+
+- **Popover**: Para conteudo interativo mais rico
+- **HoverCard**: Para previews mais elaborados
+- **Label**: Para rotulos permanentes
+- **IconButton**: Frequentemente usa Tooltip
+
+## Design Specs
+
+### Posicionamento
+
+- **Sides**: `top` (padrao), `right`, `bottom`, `left`
+- Auto-flip quando nao cabe
+- Arrow/seta apontando para o trigger
+
+### Estados
+
+- **Hidden**: Tooltip nao visivel
+- **Visible**: Tooltip exibido
+- **Delayed**: Aguardando delay
+
+### Tokens de Design
+
+#### Cores
+
+- Background: `bg-foreground`
+- Text: `text-background`
+- Arrow: `fill-foreground`
+
+#### Espacamento
+
+- Padding: `px-3 py-1.5`
+- Side Offset: `sideOffset={0}` (colado no trigger)
+- Arrow Size: `size-2.5`
+
+#### Tipografia
+
+- Font Size: `text-xs`
+- Text Balance: `text-balance`
+
+#### Bordas e Arredondamento
+
+- Border Radius: `rounded-md`
+- Arrow Radius: `rounded-[2px]`
+
+#### Motion e Transicoes
+
+- Fade: `fade-in-0`, `fade-out-0`
+- Zoom: `zoom-in-95`, `zoom-out-95`
+- Slide por side:
+  - Top: `slide-in-from-bottom-2`
+  - Bottom: `slide-in-from-top-2`
+  - Left: `slide-in-from-right-2`
+  - Right: `slide-in-from-left-2`
+
+### Padrão de Tokens com Tailwind v4
+
+O componente Tooltip utiliza tokens de design definidos em `@etus/tokens`. No Tailwind v4, variáveis CSS que contêm cores OKLCH precisam do prefixo `color:` para serem interpretadas corretamente.
+
+#### Tokens Disponíveis
+
+```css
+/* Content */
+--tooltip-content-background
+--tooltip-content-foreground
+--tooltip-content-padding-y
+--tooltip-content-padding-x
+--tooltip-content-radius
+--tooltip-content-text-size
+--tooltip-content-z-index
+
+/* Arrow */
+--tooltip-arrow-size
+--tooltip-arrow-radius
+```
+
+#### Sintaxe Tailwind v4
+
+```tsx
+// ✅ CORRETO - cores precisam do prefixo color:
+bg-[color:var(--tooltip-content-background)]
+text-[color:var(--tooltip-content-foreground)]
+fill-[color:var(--tooltip-content-background)]
+
+// ✅ CORRETO - dimensões não precisam de prefixo
+py-[var(--tooltip-content-padding-y)]
+px-[var(--tooltip-content-padding-x)]
+rounded-[var(--tooltip-content-radius)]
+text-[length:var(--tooltip-content-text-size)]
+z-[var(--tooltip-content-z-index)]
+size-[var(--tooltip-arrow-size)]
+
+// ❌ INCORRETO - nunca usar hsl() ou omitir color:
+bg-[hsl(var(--tooltip-content-background))]
+bg-[var(--tooltip-content-background)]
+```
+
+#### Por que usar `color:`?
+
+O Tailwind v4 usa Lightning CSS que requer type hints para valores ambíguos. Cores OKLCH como `oklch(81.06% 0.2032 150.12)` precisam do prefixo `color:` para serem corretamente interpretadas como cores e não como valores genéricos.
+
+### Consideracoes de Responsividade
+
+- Tooltip e touch-friendly (pode abrir on long-press)
+- Posicao adapta para caber na viewport
+- Considerar alternativas em mobile (labels explicitos)
+
+## API
+
+### Props
+
+#### TooltipProvider
+
+| Prop                      | Tipo      | Padrao  | Descricao                   |
+| ------------------------- | --------- | ------- | --------------------------- |
+| `delayDuration`           | `number`  | `0`     | Delay antes de abrir (ms)   |
+| `skipDelayDuration`       | `number`  | `300`   | Delay entre tooltips        |
+| `disableHoverableContent` | `boolean` | `false` | Desabilita hover no content |
+
+#### Tooltip (Root)
+
+| Prop            | Tipo                      | Padrao  | Descricao           |
+| --------------- | ------------------------- | ------- | ------------------- |
+| `open`          | `boolean`                 | -       | Estado controlado   |
+| `onOpenChange`  | `(open: boolean) => void` | -       | Callback de mudanca |
+| `defaultOpen`   | `boolean`                 | `false` | Estado inicial      |
+| `delayDuration` | `number`                  | -       | Override do delay   |
+
+#### TooltipTrigger
+
+| Prop      | Tipo      | Padrao  | Descricao            |
+| --------- | --------- | ------- | -------------------- |
+| `asChild` | `boolean` | `false` | Renderiza como filho |
+
+#### TooltipContent
+
+| Prop               | Tipo                                     | Padrao     | Descricao                |
+| ------------------ | ---------------------------------------- | ---------- | ------------------------ |
+| `side`             | `'top' \| 'right' \| 'bottom' \| 'left'` | `'top'`    | Lado de posicionamento   |
+| `sideOffset`       | `number`                                 | `0`        | Distancia do trigger     |
+| `align`            | `'start' \| 'center' \| 'end'`           | `'center'` | Alinhamento              |
+| `alignOffset`      | `number`                                 | `0`        | Offset de alinhamento    |
+| `avoidCollisions`  | `boolean`                                | `true`     | Evita colisao com bordas |
+| `collisionPadding` | `number`                                 | -          | Padding de colisao       |
+
+### Interfaces TypeScript
+
+```typescript
+import * as TooltipPrimitive from "@radix-ui/react-tooltip";
+
+// TooltipProvider
+interface TooltipProviderProps extends React.ComponentProps<
+  typeof TooltipPrimitive.Provider
+> {
+  delayDuration?: number;
+}
+
+// Tooltip Root
+type TooltipProps = React.ComponentProps<typeof TooltipPrimitive.Root>;
+
+// TooltipTrigger
+type TooltipTriggerProps = React.ComponentProps<
+  typeof TooltipPrimitive.Trigger
+>;
+
+// TooltipContent
+interface TooltipContentProps extends React.ComponentProps<
+  typeof TooltipPrimitive.Content
+> {
+  // Herda todas as props do Radix
+}
+```
+
+### Comparacao com Referencias
+
+| Design System | Arrow    | Delay Config | Provider        |
+| ------------- | -------- | ------------ | --------------- |
+| **ETUS**      | Sim      | Sim          | Sim (integrado) |
+| Radix UI      | Opcional | Sim          | Sim             |
+| Chakra UI     | Sim      | Sim          | Nao             |
+| MUI           | Sim      | Sim          | Nao             |
+| Headless UI   | Manual   | Nao          | Nao             |
+
+## Acessibilidade (A11y)
+
+### Atributos ARIA
+
+- `role="tooltip"`: No conteudo
+- `aria-describedby`: Referencia no trigger
+- Conteudo associado automaticamente
+
+### Navegacao por Teclado
+
+- `Tab`: Focus no trigger mostra tooltip
+- `Escape`: Fecha tooltip
+- Tooltip fecha ao perder focus
+
+### Touch Devices
+
+- Pode abrir com long-press
+- Fecha ao tocar fora
+- Considerar labels explicitos em mobile
+
+### Tecnologias Assistivas
+
+- Screen readers anunciam o conteudo do tooltip
+- Associacao automatica via aria-describedby
+
+### Conformidade WCAG
+
+- 1.4.13 Content on Hover or Focus
+- Tooltip permanece visivel enquanto hover/focus
+
+## Exemplos
+
+### Uso Basico
+
+```tsx
+import { Tooltip, TooltipContent, TooltipTrigger } from "@etus/ui";
+
+function BasicTooltip() {
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <Button variant="outline">Passe o mouse</Button>
+      </TooltipTrigger>
+      <TooltipContent>
+        <p>Conteudo do tooltip</p>
+      </TooltipContent>
+    </Tooltip>
+  );
+}
+```
+
+### Em Icones
+
+```tsx
+import { Tooltip, TooltipContent, TooltipTrigger } from "@etus/ui";
+import { TrashIcon, EditIcon, CopyIcon } from "lucide-react";
+
+function IconTooltips() {
+  return (
+    <div className="flex gap-2">
+      <Tooltip>
+        <TooltipTrigger asChild>
+          <Button variant="ghost" size="icon">
+            <EditIcon className="size-4" />
+          </Button>
+        </TooltipTrigger>
+        <TooltipContent>Editar</TooltipContent>
+      </Tooltip>
+
+      <Tooltip>
+        <TooltipTrigger asChild>
+          <Button variant="ghost" size="icon">
+            <CopyIcon className="size-4" />
+          </Button>
+        </TooltipTrigger>
+        <TooltipContent>Copiar</TooltipContent>
+      </Tooltip>
+
+      <Tooltip>
+        <TooltipTrigger asChild>
+          <Button variant="ghost" size="icon">
+            <TrashIcon className="size-4" />
+          </Button>
+        </TooltipTrigger>
+        <TooltipContent>Excluir</TooltipContent>
+      </Tooltip>
+    </div>
+  );
+}
+```
+
+### Posicionamento
+
+```tsx
+import { Tooltip, TooltipContent, TooltipTrigger } from "@etus/ui";
+
+function TooltipPositions() {
+  return (
+    <div className="flex gap-4">
+      <Tooltip>
+        <TooltipTrigger asChild>
+          <Button variant="outline">Top</Button>
+        </TooltipTrigger>
+        <TooltipContent side="top">Tooltip no topo</TooltipContent>
+      </Tooltip>
+
+      <Tooltip>
+        <TooltipTrigger asChild>
+          <Button variant="outline">Right</Button>
+        </TooltipTrigger>
+        <TooltipContent side="right">Tooltip a direita</TooltipContent>
+      </Tooltip>
+
+      <Tooltip>
+        <TooltipTrigger asChild>
+          <Button variant="outline">Bottom</Button>
+        </TooltipTrigger>
+        <TooltipContent side="bottom">Tooltip embaixo</TooltipContent>
+      </Tooltip>
+
+      <Tooltip>
+        <TooltipTrigger asChild>
+          <Button variant="outline">Left</Button>
+        </TooltipTrigger>
+        <TooltipContent side="left">Tooltip a esquerda</TooltipContent>
+      </Tooltip>
+    </div>
+  );
+}
+```
+
+### Com Atalho de Teclado
+
+```tsx
+import { Tooltip, TooltipContent, TooltipTrigger } from "@etus/ui";
+import { Kbd } from "@etus/ui";
+
+function TooltipWithShortcut() {
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <Button variant="outline">
+          <SaveIcon className="size-4 mr-2" />
+          Salvar
+        </Button>
+      </TooltipTrigger>
+      <TooltipContent>
+        <div className="flex items-center gap-2">
+          <span>Salvar documento</span>
+          <Kbd>Cmd + S</Kbd>
+        </div>
+      </TooltipContent>
+    </Tooltip>
+  );
+}
+```
+
+### Com Delay
+
+```tsx
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+  TooltipProvider,
+} from "@etus/ui";
+
+function DelayedTooltips() {
+  return (
+    <TooltipProvider delayDuration={500}>
+      <Tooltip>
+        <TooltipTrigger asChild>
+          <Button variant="outline">Delay de 500ms</Button>
+        </TooltipTrigger>
+        <TooltipContent>Este tooltip tem delay</TooltipContent>
+      </Tooltip>
+    </TooltipProvider>
+  );
+}
+```
+
+### Controlado
+
+```tsx
+import { useState } from "react";
+import { Tooltip, TooltipContent, TooltipTrigger } from "@etus/ui";
+
+function ControlledTooltip() {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <>
+      <Button onClick={() => setOpen(!open)}>Toggle Tooltip</Button>
+
+      <Tooltip open={open} onOpenChange={setOpen}>
+        <TooltipTrigger asChild>
+          <Button variant="outline">Alvo do Tooltip</Button>
+        </TooltipTrigger>
+        <TooltipContent>Tooltip controlado externamente</TooltipContent>
+      </Tooltip>
+    </>
+  );
+}
+```
+
+### Texto Truncado
+
+```tsx
+import { Tooltip, TooltipContent, TooltipTrigger } from "@etus/ui";
+
+function TruncatedTextTooltip() {
+  const longText = "Este e um texto muito longo que sera truncado na interface";
+
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <span className="block w-40 truncate cursor-default">{longText}</span>
+      </TooltipTrigger>
+      <TooltipContent>{longText}</TooltipContent>
+    </Tooltip>
+  );
+}
+```
+
+### Multiplos Tooltips
+
+```tsx
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+  TooltipProvider,
+} from "@etus/ui";
+
+function MultipleTooltips() {
+  const items = [
+    { icon: HomeIcon, label: "Inicio" },
+    { icon: SearchIcon, label: "Buscar" },
+    { icon: SettingsIcon, label: "Configuracoes" },
+    { icon: UserIcon, label: "Perfil" },
+  ];
+
+  return (
+    <TooltipProvider>
+      <div className="flex gap-1">
+        {items.map((item, i) => (
+          <Tooltip key={i}>
+            <TooltipTrigger asChild>
+              <Button variant="ghost" size="icon">
+                <item.icon className="size-4" />
+              </Button>
+            </TooltipTrigger>
+            <TooltipContent>{item.label}</TooltipContent>
+          </Tooltip>
+        ))}
+      </div>
+    </TooltipProvider>
+  );
+}
+```
+
+### Com Formatacao
+
+```tsx
+import { Tooltip, TooltipContent, TooltipTrigger } from "@etus/ui";
+
+function FormattedTooltip() {
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <span className="text-muted-foreground cursor-help underline decoration-dotted">
+          Ha 5 minutos
+        </span>
+      </TooltipTrigger>
+      <TooltipContent>
+        <div className="text-center">
+          <div className="font-medium">22 de dezembro de 2024</div>
+          <div className="text-muted-foreground text-xs">14:35:22</div>
+        </div>
+      </TooltipContent>
+    </Tooltip>
+  );
+}
+```
+
+### Desabilitado Condicionalmente
+
+```tsx
+import { Tooltip, TooltipContent, TooltipTrigger } from "@etus/ui";
+
+function ConditionalTooltip({ showTooltip, children, content }) {
+  if (!showTooltip) {
+    return children;
+  }
+
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild>{children}</TooltipTrigger>
+      <TooltipContent>{content}</TooltipContent>
+    </Tooltip>
+  );
+}
+
+// Uso
+function App() {
+  return (
+    <ConditionalTooltip showTooltip={isDesktop} content="Clique para editar">
+      <Button>Editar</Button>
+    </ConditionalTooltip>
+  );
+}
+```
+
+## Testes
+
+### Estrategias de Teste
+
+#### Testes Unitarios
+
+- Tooltip aparece on hover
+- Tooltip aparece on focus
+- Fecha ao mover mouse
+- Posicionamento correto
+
+### Exemplos de Codigo
+
+```typescript
+import { describe, it, expect } from 'vitest'
+import { render, screen, waitFor } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+  TooltipProvider,
+} from './Tooltip'
+
+describe('Tooltip', () => {
+  it('shows on hover', async () => {
+    const user = userEvent.setup()
+
+    render(
+      <TooltipProvider>
+        <Tooltip>
+          <TooltipTrigger>Trigger</TooltipTrigger>
+          <TooltipContent>Content</TooltipContent>
+        </Tooltip>
+      </TooltipProvider>
+    )
+
+    expect(screen.queryByText('Content')).not.toBeInTheDocument()
+
+    await user.hover(screen.getByText('Trigger'))
+
+    await waitFor(() => {
+      expect(screen.getByText('Content')).toBeInTheDocument()
+    })
+  })
+
+  it('shows on focus', async () => {
+    const user = userEvent.setup()
+
+    render(
+      <TooltipProvider>
+        <Tooltip>
+          <TooltipTrigger asChild>
+            <button>Trigger</button>
+          </TooltipTrigger>
+          <TooltipContent>Content</TooltipContent>
+        </Tooltip>
+      </TooltipProvider>
+    )
+
+    await user.tab()
+
+    await waitFor(() => {
+      expect(screen.getByText('Content')).toBeInTheDocument()
+    })
+  })
+
+  it('hides when mouse leaves', async () => {
+    const user = userEvent.setup()
+
+    render(
+      <TooltipProvider>
+        <Tooltip>
+          <TooltipTrigger>Trigger</TooltipTrigger>
+          <TooltipContent>Content</TooltipContent>
+        </Tooltip>
+      </TooltipProvider>
+    )
+
+    await user.hover(screen.getByText('Trigger'))
+
+    await waitFor(() => {
+      expect(screen.getByText('Content')).toBeInTheDocument()
+    })
+
+    await user.unhover(screen.getByText('Trigger'))
+
+    await waitFor(() => {
+      expect(screen.queryByText('Content')).not.toBeInTheDocument()
+    })
+  })
+
+  it('applies side prop correctly', async () => {
+    const user = userEvent.setup()
+
+    render(
+      <TooltipProvider>
+        <Tooltip>
+          <TooltipTrigger>Trigger</TooltipTrigger>
+          <TooltipContent side="right">Content</TooltipContent>
+        </Tooltip>
+      </TooltipProvider>
+    )
+
+    await user.hover(screen.getByText('Trigger'))
+
+    await waitFor(() => {
+      const content = screen.getByText('Content')
+      expect(content).toHaveAttribute('data-side', 'right')
+    })
+  })
+
+  it('respects delay duration', async () => {
+    const user = userEvent.setup()
+
+    render(
+      <TooltipProvider delayDuration={500}>
+        <Tooltip>
+          <TooltipTrigger>Trigger</TooltipTrigger>
+          <TooltipContent>Content</TooltipContent>
+        </Tooltip>
+      </TooltipProvider>
+    )
+
+    await user.hover(screen.getByText('Trigger'))
+
+    // Nao deve aparecer imediatamente
+    expect(screen.queryByText('Content')).not.toBeInTheDocument()
+
+    // Deve aparecer apos o delay
+    await waitFor(
+      () => {
+        expect(screen.getByText('Content')).toBeInTheDocument()
+      },
+      { timeout: 600 }
+    )
+  })
+})
+```
+
+---
+
+## Roadmap / Features Futuras
+
+- Baseado em Radix UI Tooltip
+- Provider integrado no componente Tooltip
+- Arrow customizado com rotacao e traducao
+- Transform origin dinamico para animacoes
+- Delay padrao de 0ms para resposta imediata
+
+## Referências
+
+- [Radix UI Tooltip](https://www.radix-ui.com/primitives/docs/components/tooltip)
+- [WAI-ARIA Tooltip Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/)
+- [Shadcn/ui Tooltip](https://ui.shadcn.com/docs/components/tooltip)
+- [WCAG 1.4.13 Content on Hover or Focus](https://www.w3.org/WAI/WCAG21/Understanding/content-on-hover-or-focus.html)