@etus/ui 0.1.1 → 0.1.3

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

@@ -1,671 +0,0 @@
-# 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)