npm - @etus/ui - Versions diffs - 0.1.1 → 0.1.2 - Mend

@etus/ui 0.1.1 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1080) hide show

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

@@ -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 DELETED Viewed

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