@etus/ui 0.1.1 → 0.1.3

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

@@ -1,700 +0,0 @@
-# Popover
-
-## Visão Geral
-
-O componente **Popover** exibe conteudo flutuante e rico ancorado a um elemento trigger. Diferente do Tooltip que mostra texto simples, o Popover suporta conteudo interativo como formularios, menus e acoes. E ideal para interfaces que precisam de contexto adicional sem navegacao.
-
-### Classificacao Atomica
-
-- **Categoria**: Molecules
-- **Subcategoria**: Feedback / Overlay
-
-### Casos de Uso Comuns
-
-- Formularios de edicao rapida
-- Seletores de cor, data, emoji
-- Menus de configuracao compactos
-- Previa de informacoes detalhadas
-- Confirmacoes inline
-- Filtros e opcoes avancadas
-
-### Relacao com Outros Componentes
-
-- **Tooltip**: Para dicas simples sem interacao
-- **DropdownMenu**: Para listas de acoes
-- **HoverCard**: Para preview on hover
-- **Dialog**: Para conteudo mais complexo
-- **Sheet**: Para paineis laterais
-
-## Design Specs
-
-### Anatomia
-
-- **Popover**: Componente raiz que gerencia estado
-- **PopoverTrigger**: Elemento que dispara a abertura
-- **PopoverContent**: Container do conteudo flutuante
-- **PopoverAnchor**: Ancora alternativa para posicionamento
-
-### Posicionamento
-
-- **Sides**: `top`, `right`, `bottom`, `left`
-- **Alignment**: `start`, `center`, `end`
-- Auto-flip quando nao cabe na viewport
-- Offset configuravel do trigger
-
-### Estados
-
-- **Closed**: Popover oculto
-- **Open**: Popover visivel
-- **Hover** (opcional): Pode abrir on hover
-
-### Tokens de Design
-
-#### Cores
-
-- Background: `bg-popover`
-- Text: `text-popover-foreground`
-- Border: `border`
-- Shadow: `shadow-md`
-
-#### Espacamento
-
-- Content Padding: `p-4`
-- Side Offset: `sideOffset={4}` (4px)
-- Width: `w-72` (288px) por padrao
-
-#### Bordas e Arredondamento
-
-- Border Radius: `rounded-md`
-- Border Width: `border` (1px)
-
-#### Motion e Transicoes
-
-- Animacoes por lado:
-  - Bottom: `slide-in-from-top-2`
-  - Top: `slide-in-from-bottom-2`
-  - Left: `slide-in-from-right-2`
-  - Right: `slide-in-from-left-2`
-- Fade: `fade-in-0`, `fade-out-0`
-- Zoom: `zoom-in-95`, `zoom-out-95`
-
-### Padrão de Tokens com Tailwind v4
-
-O componente Popover 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
-/* Root */
---popover-bg
---popover-fg
---popover-border
---popover-radius
-
-/* Content */
---popover-content-background
---popover-content-foreground
---popover-content-border-width
---popover-content-radius
---popover-content-padding
---popover-content-width
---popover-content-shadow
---popover-content-z-index
-```
-
-#### Sintaxe Tailwind v4
-
-```tsx
-// ✅ CORRETO - cores precisam do prefixo color:
-bg-[color:var(--popover-bg)]
-bg-[color:var(--popover-content-background)]
-text-[color:var(--popover-fg)]
-text-[color:var(--popover-content-foreground)]
-border-[color:var(--popover-border)]
-
-// ✅ CORRETO - dimensões não precisam de prefixo
-rounded-[var(--popover-radius)]
-rounded-[var(--popover-content-radius)]
-p-[var(--popover-content-padding)]
-w-[var(--popover-content-width)]
-border-[length:var(--popover-content-border-width)]
-z-[var(--popover-content-z-index)]
-
-// ❌ INCORRETO - nunca usar hsl() ou omitir color:
-bg-[hsl(var(--popover-bg))]
-bg-[var(--popover-bg)]
-```
-
-#### 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
-
-- Adapta posicao automaticamente
-- Pode precisar de largura responsiva em mobile
-- Considerar usar Sheet/Modal em telas pequenas
-
-## API
-
-### Props
-
-#### Popover (Root)
-
-| Prop           | Tipo                      | Padrao  | Descricao               |
-| -------------- | ------------------------- | ------- | ----------------------- |
-| `open`         | `boolean`                 | -       | Estado controlado       |
-| `onOpenChange` | `(open: boolean) => void` | -       | Callback de mudanca     |
-| `defaultOpen`  | `boolean`                 | `false` | Estado inicial          |
-| `modal`        | `boolean`                 | `false` | Modo modal (focus trap) |
-
-#### PopoverTrigger
-
-| Prop      | Tipo      | Padrao  | Descricao            |
-| --------- | --------- | ------- | -------------------- |
-| `asChild` | `boolean` | `false` | Renderiza como filho |
-
-#### PopoverContent
-
-| Prop                   | Tipo                                     | Padrao      | Descricao                |
-| ---------------------- | ---------------------------------------- | ----------- | ------------------------ |
-| `side`                 | `'top' \| 'right' \| 'bottom' \| 'left'` | `'bottom'`  | Lado de posicionamento   |
-| `sideOffset`           | `number`                                 | `4`         | 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       |
-| `sticky`               | `'partial' \| 'always'`                  | `'partial'` | Comportamento sticky     |
-| `hideWhenDetached`     | `boolean`                                | `false`     | Oculta se desancorado    |
-| `onEscapeKeyDown`      | `(e) => void`                            | -           | Handler Escape           |
-| `onPointerDownOutside` | `(e) => void`                            | -           | Handler clique fora      |
-| `onFocusOutside`       | `(e) => void`                            | -           | Handler focus fora       |
-| `onInteractOutside`    | `(e) => void`                            | -           | Handler interacao fora   |
-
-#### PopoverAnchor
-
-| Prop      | Tipo      | Padrao  | Descricao            |
-| --------- | --------- | ------- | -------------------- |
-| `asChild` | `boolean` | `false` | Renderiza como filho |
-
-### Interfaces TypeScript
-
-```typescript
-import * as PopoverPrimitive from "@radix-ui/react-popover";
-
-// Popover Root
-type PopoverProps = React.ComponentProps<typeof PopoverPrimitive.Root>;
-
-// PopoverTrigger
-type PopoverTriggerProps = React.ComponentProps<
-  typeof PopoverPrimitive.Trigger
->;
-
-// PopoverContent
-interface PopoverContentProps extends React.ComponentProps<
-  typeof PopoverPrimitive.Content
-> {
-  // Herda todas as props do Radix
-}
-
-// PopoverAnchor
-type PopoverAnchorProps = React.ComponentProps<typeof PopoverPrimitive.Anchor>;
-```
-
-### Comparacao com Referencias
-
-| Design System | Focus Trap | Arrow    | Portal | Positioning       |
-| ------------- | ---------- | -------- | ------ | ----------------- |
-| **ETUS**      | Opcional   | Nao      | Sim    | Radix/Floating UI |
-| Radix UI      | Opcional   | Opcional | Sim    | Floating UI       |
-| Chakra UI     | Opcional   | Sim      | Sim    | Popper.js         |
-| MUI           | Opcional   | Opcional | Sim    | Popper.js         |
-| Headless UI   | Opcional   | Manual   | Sim    | Floating UI       |
-
-## Acessibilidade (A11y)
-
-### Atributos ARIA
-
-- `aria-haspopup="dialog"`: No trigger
-- `aria-expanded`: Estado aberto/fechado
-- `aria-controls`: Referencia ao popover
-- `role="dialog"`: No content (quando modal)
-
-### Navegacao por Teclado
-
-- `Enter/Space`: Abre/fecha popover (no trigger)
-- `Escape`: Fecha o popover
-- `Tab`: Navega dentro do popover
-- Focus trap quando `modal={true}`
-
-### Focus Management
-
-- Focus move para popover ao abrir
-- Focus retorna ao trigger ao fechar
-- Primeiro elemento focavel recebe focus
-
-### Tecnologias Assistivas
-
-- Conteudo anunciado ao abrir
-- Trigger indica estado expandido
-- Navegacao preservada dentro do popover
-
-### Conformidade WCAG
-
-- Nivel alvo: WCAG 2.1 AA
-- 4.1.2 Name, Role, Value
-
-## Exemplos
-
-### Uso Basico
-
-```tsx
-import { Popover, PopoverContent, PopoverTrigger } from "@etus/ui";
-
-function BasicPopover() {
-  return (
-    <Popover>
-      <PopoverTrigger asChild>
-        <Button variant="outline">Abrir Popover</Button>
-      </PopoverTrigger>
-      <PopoverContent>
-        <p>Conteudo do popover aqui.</p>
-      </PopoverContent>
-    </Popover>
-  );
-}
-```
-
-### Com Formulario
-
-```tsx
-import { Popover, PopoverContent, PopoverTrigger } from "@etus/ui";
-import { Button, Input, Label } from "@etus/ui";
-
-function PopoverWithForm() {
-  return (
-    <Popover>
-      <PopoverTrigger asChild>
-        <Button variant="outline">Editar</Button>
-      </PopoverTrigger>
-      <PopoverContent className="w-80">
-        <div className="grid gap-4">
-          <div className="space-y-2">
-            <h4 className="font-medium leading-none">Dimensoes</h4>
-            <p className="text-sm text-muted-foreground">
-              Configure as dimensoes da camada.
-            </p>
-          </div>
-          <div className="grid gap-2">
-            <div className="grid grid-cols-3 items-center gap-4">
-              <Label htmlFor="width">Largura</Label>
-              <Input
-                id="width"
-                defaultValue="100%"
-                className="col-span-2 h-8"
-              />
-            </div>
-            <div className="grid grid-cols-3 items-center gap-4">
-              <Label htmlFor="height">Altura</Label>
-              <Input
-                id="height"
-                defaultValue="25px"
-                className="col-span-2 h-8"
-              />
-            </div>
-          </div>
-        </div>
-      </PopoverContent>
-    </Popover>
-  );
-}
-```
-
-### Posicionamento
-
-```tsx
-import { Popover, PopoverContent, PopoverTrigger } from "@etus/ui";
-
-function PopoverPositions() {
-  return (
-    <div className="flex gap-4">
-      <Popover>
-        <PopoverTrigger asChild>
-          <Button variant="outline">Top</Button>
-        </PopoverTrigger>
-        <PopoverContent side="top">Popover no topo</PopoverContent>
-      </Popover>
-
-      <Popover>
-        <PopoverTrigger asChild>
-          <Button variant="outline">Right</Button>
-        </PopoverTrigger>
-        <PopoverContent side="right">Popover a direita</PopoverContent>
-      </Popover>
-
-      <Popover>
-        <PopoverTrigger asChild>
-          <Button variant="outline">Bottom</Button>
-        </PopoverTrigger>
-        <PopoverContent side="bottom">Popover embaixo</PopoverContent>
-      </Popover>
-
-      <Popover>
-        <PopoverTrigger asChild>
-          <Button variant="outline">Left</Button>
-        </PopoverTrigger>
-        <PopoverContent side="left">Popover a esquerda</PopoverContent>
-      </Popover>
-    </div>
-  );
-}
-```
-
-### Alinhamento
-
-```tsx
-import { Popover, PopoverContent, PopoverTrigger } from "@etus/ui";
-
-function PopoverAlignment() {
-  return (
-    <div className="flex gap-4">
-      <Popover>
-        <PopoverTrigger asChild>
-          <Button variant="outline">Start</Button>
-        </PopoverTrigger>
-        <PopoverContent align="start">Alinhado ao inicio</PopoverContent>
-      </Popover>
-
-      <Popover>
-        <PopoverTrigger asChild>
-          <Button variant="outline">Center</Button>
-        </PopoverTrigger>
-        <PopoverContent align="center">Alinhado ao centro</PopoverContent>
-      </Popover>
-
-      <Popover>
-        <PopoverTrigger asChild>
-          <Button variant="outline">End</Button>
-        </PopoverTrigger>
-        <PopoverContent align="end">Alinhado ao fim</PopoverContent>
-      </Popover>
-    </div>
-  );
-}
-```
-
-### Controlado Externamente
-
-```tsx
-import { useState } from "react";
-import { Popover, PopoverContent, PopoverTrigger } from "@etus/ui";
-
-function ControlledPopover() {
-  const [open, setOpen] = useState(false);
-
-  return (
-    <>
-      <Button onClick={() => setOpen(true)}>Abrir via botao externo</Button>
-
-      <Popover open={open} onOpenChange={setOpen}>
-        <PopoverTrigger asChild>
-          <Button variant="outline">Trigger</Button>
-        </PopoverTrigger>
-        <PopoverContent>
-          <p>Popover controlado externamente</p>
-          <Button onClick={() => setOpen(false)}>Fechar</Button>
-        </PopoverContent>
-      </Popover>
-    </>
-  );
-}
-```
-
-### Com Ancora Separada
-
-```tsx
-import {
-  Popover,
-  PopoverContent,
-  PopoverTrigger,
-  PopoverAnchor,
-} from "@etus/ui";
-
-function PopoverWithAnchor() {
-  return (
-    <Popover>
-      <PopoverAnchor asChild>
-        <div className="p-4 border rounded">
-          Ancora aqui (popover ancorado neste elemento)
-        </div>
-      </PopoverAnchor>
-
-      <PopoverTrigger asChild>
-        <Button className="mt-4">Abrir</Button>
-      </PopoverTrigger>
-
-      <PopoverContent>
-        Este popover esta ancorado no div acima, nao no trigger.
-      </PopoverContent>
-    </Popover>
-  );
-}
-```
-
-### Seletor de Cor
-
-```tsx
-import { useState } from "react";
-import { Popover, PopoverContent, PopoverTrigger } from "@etus/ui";
-
-const colors = [
-  "#ef4444",
-  "#f97316",
-  "#eab308",
-  "#22c55e",
-  "#14b8a6",
-  "#3b82f6",
-  "#8b5cf6",
-  "#ec4899",
-];
-
-function ColorPickerPopover() {
-  const [color, setColor] = useState("#3b82f6");
-
-  return (
-    <Popover>
-      <PopoverTrigger asChild>
-        <button
-          className="size-10 rounded-md border"
-          style={{ backgroundColor: color }}
-          aria-label={`Cor selecionada: ${color}`}
-        />
-      </PopoverTrigger>
-      <PopoverContent className="w-auto">
-        <div className="grid grid-cols-4 gap-2">
-          {colors.map((c) => (
-            <button
-              key={c}
-              className="size-8 rounded-md border-2 transition-all hover:scale-110"
-              style={{
-                backgroundColor: c,
-                borderColor: c === color ? "white" : "transparent",
-              }}
-              onClick={() => setColor(c)}
-              aria-label={`Selecionar cor ${c}`}
-            />
-          ))}
-        </div>
-      </PopoverContent>
-    </Popover>
-  );
-}
-```
-
-### Confirmacao Inline
-
-```tsx
-import { useState } from "react";
-import { Popover, PopoverContent, PopoverTrigger } from "@etus/ui";
-import { Button } from "@etus/ui";
-import { TrashIcon } from "lucide-react";
-
-function DeleteConfirmPopover({ onDelete }) {
-  const [open, setOpen] = useState(false);
-
-  const handleDelete = () => {
-    onDelete();
-    setOpen(false);
-  };
-
-  return (
-    <Popover open={open} onOpenChange={setOpen}>
-      <PopoverTrigger asChild>
-        <Button variant="ghost" size="icon">
-          <TrashIcon className="size-4" />
-        </Button>
-      </PopoverTrigger>
-      <PopoverContent className="w-auto">
-        <div className="space-y-2">
-          <p className="text-sm">Excluir este item?</p>
-          <div className="flex gap-2">
-            <Button size="sm" variant="outline" onClick={() => setOpen(false)}>
-              Cancelar
-            </Button>
-            <Button size="sm" variant="destructive" onClick={handleDelete}>
-              Excluir
-            </Button>
-          </div>
-        </div>
-      </PopoverContent>
-    </Popover>
-  );
-}
-```
-
-### Com Largura Customizada
-
-```tsx
-import { Popover, PopoverContent, PopoverTrigger } from "@etus/ui";
-
-function WidePopover() {
-  return (
-    <Popover>
-      <PopoverTrigger asChild>
-        <Button variant="outline">Popover Largo</Button>
-      </PopoverTrigger>
-      <PopoverContent className="w-96">
-        <div className="grid grid-cols-2 gap-4">
-          <div>Coluna 1</div>
-          <div>Coluna 2</div>
-        </div>
-      </PopoverContent>
-    </Popover>
-  );
-}
-```
-
-## Testes
-
-### Estrategias de Teste
-
-#### Testes Unitarios
-
-- Abre ao clicar no trigger
-- Fecha com Escape
-- Fecha ao clicar fora
-- Posicionamento correto
-
-#### Testes de Integracao
-
-- Formularios funcionam dentro
-- Focus management
-- Eventos de callback
-
-### Exemplos de Codigo
-
-```typescript
-import { describe, it, expect, vi } from 'vitest'
-import { render, screen } from '@testing-library/react'
-import userEvent from '@testing-library/user-event'
-import {
-  Popover,
-  PopoverContent,
-  PopoverTrigger,
-} from './Popover'
-
-describe('Popover', () => {
-  it('opens when trigger is clicked', async () => {
-    const user = userEvent.setup()
-
-    render(
-      <Popover>
-        <PopoverTrigger>Open</PopoverTrigger>
-        <PopoverContent>Content</PopoverContent>
-      </Popover>
-    )
-
-    expect(screen.queryByText('Content')).not.toBeInTheDocument()
-
-    await user.click(screen.getByText('Open'))
-
-    expect(screen.getByText('Content')).toBeInTheDocument()
-  })
-
-  it('closes when Escape is pressed', async () => {
-    const user = userEvent.setup()
-
-    render(
-      <Popover defaultOpen>
-        <PopoverTrigger>Open</PopoverTrigger>
-        <PopoverContent>Content</PopoverContent>
-      </Popover>
-    )
-
-    expect(screen.getByText('Content')).toBeInTheDocument()
-
-    await user.keyboard('{Escape}')
-
-    expect(screen.queryByText('Content')).not.toBeInTheDocument()
-  })
-
-  it('closes when clicking outside', async () => {
-    const user = userEvent.setup()
-
-    render(
-      <div>
-        <Popover defaultOpen>
-          <PopoverTrigger>Open</PopoverTrigger>
-          <PopoverContent>Content</PopoverContent>
-        </Popover>
-        <button>Outside</button>
-      </div>
-    )
-
-    expect(screen.getByText('Content')).toBeInTheDocument()
-
-    await user.click(screen.getByText('Outside'))
-
-    expect(screen.queryByText('Content')).not.toBeInTheDocument()
-  })
-
-  it('calls onOpenChange when state changes', async () => {
-    const user = userEvent.setup()
-    const onOpenChange = vi.fn()
-
-    render(
-      <Popover onOpenChange={onOpenChange}>
-        <PopoverTrigger>Open</PopoverTrigger>
-        <PopoverContent>Content</PopoverContent>
-      </Popover>
-    )
-
-    await user.click(screen.getByText('Open'))
-    expect(onOpenChange).toHaveBeenCalledWith(true)
-
-    await user.keyboard('{Escape}')
-    expect(onOpenChange).toHaveBeenCalledWith(false)
-  })
-
-  it('applies side prop correctly', () => {
-    render(
-      <Popover defaultOpen>
-        <PopoverTrigger>Open</PopoverTrigger>
-        <PopoverContent side="top">Content</PopoverContent>
-      </Popover>
-    )
-
-    const content = screen.getByText('Content')
-    expect(content).toHaveAttribute('data-side', 'top')
-  })
-
-  it('applies align prop correctly', () => {
-    render(
-      <Popover defaultOpen>
-        <PopoverTrigger>Open</PopoverTrigger>
-        <PopoverContent align="start">Content</PopoverContent>
-      </Popover>
-    )
-
-    const content = screen.getByText('Content')
-    expect(content).toHaveAttribute('data-align', 'start')
-  })
-})
-```
-
----
-
-## Roadmap / Features Futuras
-
-- Baseado em Radix UI Popover
-- Portal rendering para z-index correto
-- Posicionamento via Floating UI
-- Auto-flip para evitar overflow
-- Transform origin dinamico para animacoes
-
-## Referências
-
-- [Radix UI Popover](https://www.radix-ui.com/primitives/docs/components/popover)
-- [Floating UI](https://floating-ui.com/)
-- [WAI-ARIA Tooltip Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/)
-- [Shadcn/ui Popover](https://ui.shadcn.com/docs/components/popover)

package/src/components/feedback/Popover/index.ts

@@ -1,2 +0,0 @@
-export type * from './Popover.types'
-export * from './Popover'