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

@etus/ui 0.1.1 → 0.1.3

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/navigation/Drawer/README.md DELETED Viewed

@@ -1,723 +0,0 @@
-# Drawer
-## Visão Geral
-O Drawer e um painel deslizante que emerge das bordas da tela, ideal para navegacao secundaria, formularios, detalhes de itens ou acoes contextuais. Utiliza a biblioteca Vaul para animacoes suaves e gestos de arraste nativos em dispositivos touch.
-### Classificacao Atomica
-- **Categoria**: Organisms
-- **Subcategoria**: Navigation / Overlay
-### Casos de Uso Comuns
-- Menus de navegacao mobile
-- Paineis de filtros e configuracoes
-- Detalhes de itens em listas
-- Formularios rapidos (criacao, edicao)
-- Carrinho de compras lateral
-- Paineis de notificacoes
-### Relacao com Outros Componentes
-- **Sheet**: Componente similar, Drawer e mais indicado para mobile
-- **Dialog**: Para conteudo modal centralizado
-- **Sidebar**: Para navegacao persistente em desktop
-- **NavigationMenu**: Pode ser usado dentro do Drawer em mobile
-## Design Specs
-### Subcomponentes
-- **Drawer**: Root que gerencia estado aberto/fechado
-- **DrawerTrigger**: Botao que abre o drawer
-- **DrawerPortal**: Renderiza conteudo em portal
-- **DrawerOverlay**: Backdrop escurecido
-- **DrawerContent**: Container principal do conteudo
-- **DrawerHeader**: Cabecalho com titulo e descricao
-- **DrawerFooter**: Rodape com acoes
-- **DrawerTitle**: Titulo do drawer
-- **DrawerDescription**: Descricao/subtitulo
-- **DrawerClose**: Botao de fechar
-### Variantes de Direcao
-| Direcao  | Descricao           | Classes Principais                             |
-| -------- | ------------------- | ---------------------------------------------- |
-| `top`    | Desliza de cima     | `inset-x-0 top-0 rounded-b-lg border-b`        |
-| `bottom` | Desliza de baixo    | `inset-x-0 bottom-0 rounded-t-lg border-t`     |
-| `left`   | Desliza da esquerda | `inset-y-0 left-0 w-3/4 border-r sm:max-w-sm`  |
-| `right`  | Desliza da direita  | `inset-y-0 right-0 w-3/4 border-l sm:max-w-sm` |
-### Estados
-- **Closed**: Fora da tela, invisivel
-- **Opening**: Animacao de entrada (slide + fade)
-- **Open**: Totalmente visivel e interativo
-- **Closing**: Animacao de saida
-### Tokens de Design
-#### Cores
-- Background: `bg-background`
-- Overlay: `bg-black/50`
-- Drag Handle: `bg-muted`
-- Text: `text-foreground`
-- Description: `text-muted-foreground`
-#### Espacamento
-- Header padding: `p-4`
-- Footer padding: `p-4`
-- Header gap: `gap-0.5` (mobile) / `gap-1.5` (desktop)
-- Footer gap: `gap-2`
-- Drag handle margin: `mt-4`
-#### Tipografia
-- Title: `font-semibold`
-- Description: `text-sm`
-#### Dimensoes
-- Lateral width: `w-3/4` (mobile), `max-w-sm` (desktop)
-- Vertical max-height: `max-h-[80vh]`
-- Drag handle: `h-2 w-[100px] rounded-full`
-#### Motion e Transicoes
-- Overlay fade: `animate-in/out fade-in/out-0`
-- Controlado pelo Vaul via gestos de arraste
-### Padrão de Tokens com Tailwind v4
-O componente Drawer 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
-/* Overlay */
---drawer-overlay-bg
-/* Content */
---drawer-content-bg
---drawer-content-radius
---drawer-content-border
-/* Handle */
---drawer-handle-bg
---drawer-handle-margin-top
---drawer-handle-height
---drawer-handle-width
-/* Header */
---drawer-header-gap
---drawer-header-padding
-/* Footer */
---drawer-footer-gap
---drawer-footer-padding
-```
-#### Sintaxe Tailwind v4
-```tsx
-// ✅ CORRETO - cores precisam do prefixo color:
-bg-[color:var(--drawer-overlay-bg)]
-bg-[color:var(--drawer-content-bg)]
-border-[color:var(--drawer-content-border)]
-bg-[color:var(--drawer-handle-bg)]
-// ✅ CORRETO - dimensões não precisam de prefixo
-rounded-[var(--drawer-content-radius)]
-mt-[var(--drawer-handle-margin-top)]
-h-[var(--drawer-handle-height)]
-w-[var(--drawer-handle-width)]
-gap-[var(--drawer-header-gap)]
-p-[var(--drawer-header-padding)]
-gap-[var(--drawer-footer-gap)]
-p-[var(--drawer-footer-padding)]
-// ❌ INCORRETO - nunca usar hsl() ou omitir color:
-bg-[hsl(var(--drawer-overlay-bg))]
-bg-[var(--drawer-overlay-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
-- **Mobile**: Largura de 75% da tela, suporta gesto de arraste para fechar
-- **Tablet/Desktop**: `max-w-sm` para laterais, mantendo proporcao adequada
-- **Orientacao**: Drawers bottom/top mostram drag handle indicador
-- **Touch**: Gestos nativos de swipe para fechar
-## API
-### Componentes Exportados
-#### Drawer
-Root component que gerencia o estado.
-| Prop                    | Tipo                                     | Padrao     | Descricao                     |
-| ----------------------- | ---------------------------------------- | ---------- | ----------------------------- |
-| `open`                  | `boolean`                                | -          | Estado controlado             |
-| `onOpenChange`          | `(open: boolean) => void`                | -          | Callback de mudanca           |
-| `shouldScaleBackground` | `boolean`                                | `true`     | Escala o background ao abrir  |
-| `direction`             | `"top" \| "bottom" \| "left" \| "right"` | `"bottom"` | Direcao de abertura           |
-| `modal`                 | `boolean`                                | `true`     | Se bloqueia interacao externa |
-#### DrawerTrigger
-Botao que abre o drawer.
-| Prop       | Tipo          | Padrao  | Descricao            |
-| ---------- | ------------- | ------- | -------------------- |
-| `asChild`  | `boolean`     | `false` | Merge props no filho |
-| `...props` | `ButtonProps` | -       | Props de botao       |
-#### DrawerContent
-Container do conteudo.
-| Prop        | Tipo        | Padrao | Descricao          |
-| ----------- | ----------- | ------ | ------------------ |
-| `className` | `string`    | `''`   | Classes adicionais |
-| `children`  | `ReactNode` | -      | Conteudo do drawer |
-#### DrawerHeader
-Container do cabecalho.
-| Prop        | Tipo     | Padrao | Descricao          |
-| ----------- | -------- | ------ | ------------------ |
-| `className` | `string` | `''`   | Classes adicionais |
-#### DrawerFooter
-Container do rodape.
-| Prop        | Tipo     | Padrao | Descricao          |
-| ----------- | -------- | ------ | ------------------ |
-| `className` | `string` | `''`   | Classes adicionais |
-#### DrawerTitle
-Titulo do drawer.
-| Prop        | Tipo     | Padrao | Descricao          |
-| ----------- | -------- | ------ | ------------------ |
-| `className` | `string` | `''`   | Classes adicionais |
-#### DrawerDescription
-Descricao do drawer.
-| Prop        | Tipo     | Padrao | Descricao          |
-| ----------- | -------- | ------ | ------------------ |
-| `className` | `string` | `''`   | Classes adicionais |
-#### DrawerClose
-Botao de fechar.
-| Prop      | Tipo      | Padrao  | Descricao            |
-| --------- | --------- | ------- | -------------------- |
-| `asChild` | `boolean` | `false` | Merge props no filho |
-### Interfaces TypeScript
-```typescript
-import { Drawer as DrawerPrimitive } from "vaul";
-type DrawerProps = React.ComponentProps<typeof DrawerPrimitive.Root>;
-type DrawerContentProps = React.ComponentProps<typeof DrawerPrimitive.Content>;
-type DrawerHeaderProps = React.ComponentProps<"div">;
-type DrawerFooterProps = React.ComponentProps<"div">;
-type DrawerTitleProps = React.ComponentProps<typeof DrawerPrimitive.Title>;
-type DrawerDescriptionProps = React.ComponentProps<
-  typeof DrawerPrimitive.Description
->;
-```
-### Comparacao com Referencias
-| Feature          | ETUS/Vaul | Radix Dialog | MUI Drawer | Chakra | Mantine |
-| ---------------- | --------- | ------------ | ---------- | ------ | ------- |
-| Swipe to Close   | Sim       | Nao          | Parcial    | Nao    | Nao     |
-| Multi-direction  | Sim       | Nao          | Sim        | Nao    | Sim     |
-| Snap Points      | Sim       | Nao          | Nao        | Nao    | Nao     |
-| Scale Background | Sim       | Nao          | Nao        | Nao    | Nao     |
-| Nested Drawers   | Sim       | Sim          | Nao        | Nao    | Nao     |
-## Acessibilidade (A11y)
-### Atributos ARIA
-- `role="dialog"`: No DrawerContent
-- `aria-modal="true"`: Indica modalidade
-- `aria-labelledby`: Referencia o DrawerTitle
-- `aria-describedby`: Referencia o DrawerDescription
-### Navegacao por Teclado
-- `Tab`: Navega entre elementos focaveis dentro do drawer
-- `Shift + Tab`: Navegacao reversa
-- `Escape`: Fecha o drawer
-- Focus trap ativo quando aberto
-### Contraste e Legibilidade
-- Overlay escurecido garante destaque do conteudo
-- Texto segue tokens de cor acessiveis
-- Drag handle visivel com contraste adequado
-### Tecnologias Assistivas
-- Anunciado como "dialog" ao abrir
-- Titulo e descricao lidos automaticamente
-- Focus move para o drawer ao abrir
-- Focus retorna ao trigger ao fechar
-### Conformidade WCAG
-- **Nivel alvo**: WCAG 2.1 AA
-- **Criterios atendidos**:
-  - 1.4.3 Contrast (Minimum)
-  - 2.1.1 Keyboard
-  - 2.1.2 No Keyboard Trap
-  - 2.4.3 Focus Order
-  - 4.1.2 Name, Role, Value
-## Exemplos
-### Uso Basico
-```tsx
-import {
-  Drawer,
-  DrawerTrigger,
-  DrawerContent,
-  DrawerHeader,
-  DrawerTitle,
-  DrawerDescription,
-  DrawerFooter,
-  DrawerClose,
-} from "@etus/ui";
-import { Button } from "@etus/ui";
-function BasicDrawer() {
-  return (
-    <Drawer>
-      <DrawerTrigger asChild>
-        <Button variant="outline">Open Drawer</Button>
-      </DrawerTrigger>
-      <DrawerContent>
-        <DrawerHeader>
-          <DrawerTitle>Drawer Title</DrawerTitle>
-          <DrawerDescription>
-            This is a description of what this drawer does.
-          </DrawerDescription>
-        </DrawerHeader>
-        <div className="p-4">
-          <p>Your content goes here.</p>
-        </div>
-        <DrawerFooter>
-          <Button>Save</Button>
-          <DrawerClose asChild>
-            <Button variant="outline">Cancel</Button>
-          </DrawerClose>
-        </DrawerFooter>
-      </DrawerContent>
-    </Drawer>
-  );
-}
-```
-### Drawer Lateral (Right)
-```tsx
-import {
-  Drawer,
-  DrawerTrigger,
-  DrawerContent,
-  DrawerHeader,
-  DrawerTitle,
-  DrawerClose,
-} from "@etus/ui";
-import { Button } from "@etus/ui";
-import { X } from "lucide-react";
-function RightDrawer() {
-  return (
-    <Drawer direction="right">
-      <DrawerTrigger asChild>
-        <Button>Open Settings</Button>
-      </DrawerTrigger>
-      <DrawerContent>
-        <DrawerHeader className="flex items-center justify-between">
-          <DrawerTitle>Settings</DrawerTitle>
-          <DrawerClose asChild>
-            <Button variant="ghost" size="icon">
-              <X className="h-4 w-4" />
-            </Button>
-          </DrawerClose>
-        </DrawerHeader>
-        <div className="p-4 space-y-4">
-          <div>
-            <label className="text-sm font-medium">Theme</label>
-            <select className="w-full mt-1 p-2 border rounded">
-              <option>Light</option>
-              <option>Dark</option>
-              <option>System</option>
-            </select>
-          </div>
-          <div>
-            <label className="text-sm font-medium">Language</label>
-            <select className="w-full mt-1 p-2 border rounded">
-              <option>English</option>
-              <option>Portuguese</option>
-              <option>Spanish</option>
-            </select>
-          </div>
-        </div>
-      </DrawerContent>
-    </Drawer>
-  );
-}
-```
-### Menu de Navegacao Mobile
-```tsx
-import {
-  Drawer,
-  DrawerTrigger,
-  DrawerContent,
-  DrawerHeader,
-  DrawerTitle,
-  DrawerClose,
-} from "@etus/ui";
-import { Button } from "@etus/ui";
-import { Menu, X, Home, Settings, User, LogOut } from "lucide-react";
-function MobileNavDrawer() {
-  return (
-    <Drawer direction="left">
-      <DrawerTrigger asChild>
-        <Button variant="ghost" size="icon" className="md:hidden">
-          <Menu />
-        </Button>
-      </DrawerTrigger>
-      <DrawerContent>
-        <DrawerHeader className="flex items-center justify-between border-b">
-          <DrawerTitle>Menu</DrawerTitle>
-          <DrawerClose asChild>
-            <Button variant="ghost" size="icon">
-              <X className="h-4 w-4" />
-            </Button>
-          </DrawerClose>
-        </DrawerHeader>
-        <nav className="flex flex-col p-4 space-y-2">
-          <a
-            href="/"
-            className="flex items-center gap-3 p-3 rounded-lg hover:bg-muted"
-          >
-            <Home className="h-5 w-5" />
-            Home
-          </a>
-          <a
-            href="/profile"
-            className="flex items-center gap-3 p-3 rounded-lg hover:bg-muted"
-          >
-            <User className="h-5 w-5" />
-            Profile
-          </a>
-          <a
-            href="/settings"
-            className="flex items-center gap-3 p-3 rounded-lg hover:bg-muted"
-          >
-            <Settings className="h-5 w-5" />
-            Settings
-          </a>
-          <hr className="my-2" />
-          <button className="flex items-center gap-3 p-3 rounded-lg hover:bg-muted text-destructive">
-            <LogOut className="h-5 w-5" />
-            Logout
-          </button>
-        </nav>
-      </DrawerContent>
-    </Drawer>
-  );
-}
-```
-### Drawer Controlado
-```tsx
-import { useState } from "react";
-import {
-  Drawer,
-  DrawerTrigger,
-  DrawerContent,
-  DrawerHeader,
-  DrawerTitle,
-  DrawerFooter,
-} from "@etus/ui";
-import { Button } from "@etus/ui";
-function ControlledDrawer() {
-  const [open, setOpen] = useState(false);
-  const [isSubmitting, setIsSubmitting] = useState(false);
-  const handleSubmit = async () => {
-    setIsSubmitting(true);
-    // Simulate API call
-    await new Promise((resolve) => setTimeout(resolve, 1000));
-    setIsSubmitting(false);
-    setOpen(false);
-  };
-  return (
-    <Drawer open={open} onOpenChange={setOpen}>
-      <DrawerTrigger asChild>
-        <Button>Create New Item</Button>
-      </DrawerTrigger>
-      <DrawerContent>
-        <DrawerHeader>
-          <DrawerTitle>Create Item</DrawerTitle>
-        </DrawerHeader>
-        <div className="p-4">
-          <input
-            type="text"
-            placeholder="Item name"
-            className="w-full p-2 border rounded"
-          />
-        </div>
-        <DrawerFooter>
-          <Button onClick={handleSubmit} disabled={isSubmitting}>
-            {isSubmitting ? "Creating..." : "Create"}
-          </Button>
-          <Button variant="outline" onClick={() => setOpen(false)}>
-            Cancel
-          </Button>
-        </DrawerFooter>
-      </DrawerContent>
-    </Drawer>
-  );
-}
-```
-### Drawer com Formulario
-```tsx
-import {
-  Drawer,
-  DrawerTrigger,
-  DrawerContent,
-  DrawerHeader,
-  DrawerTitle,
-  DrawerDescription,
-  DrawerFooter,
-  DrawerClose,
-} from "@etus/ui";
-import { Button } from "@etus/ui";
-function FormDrawer() {
-  return (
-    <Drawer>
-      <DrawerTrigger asChild>
-        <Button>Edit Profile</Button>
-      </DrawerTrigger>
-      <DrawerContent>
-        <DrawerHeader>
-          <DrawerTitle>Edit Profile</DrawerTitle>
-          <DrawerDescription>
-            Make changes to your profile here.
-          </DrawerDescription>
-        </DrawerHeader>
-        <form className="p-4 space-y-4">
-          <div className="space-y-2">
-            <label htmlFor="name" className="text-sm font-medium">
-              Name
-            </label>
-            <input
-              id="name"
-              type="text"
-              className="w-full p-2 border rounded"
-              placeholder="Your name"
-            />
-          </div>
-          <div className="space-y-2">
-            <label htmlFor="email" className="text-sm font-medium">
-              Email
-            </label>
-            <input
-              id="email"
-              type="email"
-              className="w-full p-2 border rounded"
-              placeholder="your@email.com"
-            />
-          </div>
-          <div className="space-y-2">
-            <label htmlFor="bio" className="text-sm font-medium">
-              Bio
-            </label>
-            <textarea
-              id="bio"
-              className="w-full p-2 border rounded h-24"
-              placeholder="Tell us about yourself"
-            />
-          </div>
-        </form>
-        <DrawerFooter>
-          <Button type="submit">Save Changes</Button>
-          <DrawerClose asChild>
-            <Button variant="outline">Cancel</Button>
-          </DrawerClose>
-        </DrawerFooter>
-      </DrawerContent>
-    </Drawer>
-  );
-}
-```
-## Testes
-### Estrategias de Teste
-#### Testes Unitarios
-- Abertura e fechamento do drawer
-- Renderizacao do conteudo
-- Props de direcao aplicadas corretamente
-- Overlay presente quando aberto
-#### Testes de Integracao
-- Formularios dentro do drawer
-- Interacao com botoes de acao
-- Fechamento por overlay click
-#### Testes de Acessibilidade
-- Focus trap funcionando
-- Escape fecha o drawer
-- ARIA attributes corretos
-### Exemplos de Codigo
-```typescript
-import { describe, it, expect, vi } from "vitest"
-import { render, screen, waitFor } from "@testing-library/react"
-import userEvent from "@testing-library/user-event"
-import {
-  Drawer,
-  DrawerTrigger,
-  DrawerContent,
-  DrawerTitle,
-  DrawerClose,
-} from "./Drawer"
-describe("Drawer", () => {
-  it("opens when trigger is clicked", async () => {
-    render(
-      <Drawer>
-        <DrawerTrigger>Open</DrawerTrigger>
-        <DrawerContent>
-          <DrawerTitle>Test Drawer</DrawerTitle>
-        </DrawerContent>
-      </Drawer>
-    )
-    await userEvent.click(screen.getByText("Open"))
-    await waitFor(() => {
-      expect(screen.getByText("Test Drawer")).toBeVisible()
-    })
-  })
-  it("closes when close button is clicked", async () => {
-    render(
-      <Drawer>
-        <DrawerTrigger>Open</DrawerTrigger>
-        <DrawerContent>
-          <DrawerTitle>Test Drawer</DrawerTitle>
-          <DrawerClose>Close</DrawerClose>
-        </DrawerContent>
-      </Drawer>
-    )
-    await userEvent.click(screen.getByText("Open"))
-    await waitFor(() => {
-      expect(screen.getByText("Test Drawer")).toBeVisible()
-    })
-    await userEvent.click(screen.getByText("Close"))
-    await waitFor(() => {
-      expect(screen.queryByText("Test Drawer")).not.toBeVisible()
-    })
-  })
-  it("closes on Escape key", async () => {
-    render(
-      <Drawer>
-        <DrawerTrigger>Open</DrawerTrigger>
-        <DrawerContent>
-          <DrawerTitle>Test Drawer</DrawerTitle>
-        </DrawerContent>
-      </Drawer>
-    )
-    await userEvent.click(screen.getByText("Open"))
-    await waitFor(() => {
-      expect(screen.getByText("Test Drawer")).toBeVisible()
-    })
-    await userEvent.keyboard("{Escape}")
-    await waitFor(() => {
-      expect(screen.queryByText("Test Drawer")).not.toBeVisible()
-    })
-  })
-  it("calls onOpenChange when state changes", async () => {
-    const onOpenChange = vi.fn()
-    render(
-      <Drawer onOpenChange={onOpenChange}>
-        <DrawerTrigger>Open</DrawerTrigger>
-        <DrawerContent>
-          <DrawerTitle>Test Drawer</DrawerTitle>
-        </DrawerContent>
-      </Drawer>
-    )
-    await userEvent.click(screen.getByText("Open"))
-    expect(onOpenChange).toHaveBeenCalledWith(true)
-  })
-})
-```
----
-## Roadmap / Features Futuras
-- Construido sobre a biblioteca `vaul` para gestos de arraste nativos
-- Requer `"use client"` por usar hooks de estado
-- Overlay e Content renderizados em portal
-- Drag handle automatico para drawers bottom
-## Referências
-- [Vaul Documentation](https://vaul.emilkowal.ski/)
-- [WAI-ARIA Dialog Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/)
-- [Shadcn/ui Drawer](https://ui.shadcn.com/docs/components/drawer)