@etus/ui 0.1.0

package/src/components/forms/PasswordInput/README.md

@@ -0,0 +1,698 @@
+# PasswordInput
+
+## Visão Geral
+
+O **PasswordInput** é um componente de formulário especializado para entrada de senhas, com toggle de visibilidade integrado. Construído sobre o Input base, oferece uma experiência de usuário segura e acessível para campos de senha.
+
+### Casos de Uso
+
+- Formulários de login e autenticação
+- Cadastro de novos usuários
+- Alteração de senha
+- Confirmação de senha
+- Campos de PIN ou código secreto
+
+### Classificação
+
+**Categoria:** Atom (Forms)
+**Dependências:** `lucide-react`, `class-variance-authority`
+**Relacionamentos:** Estende `TextInput` (usa `inputVariants`)
+
+---
+
+## Design Specs
+
+### Variantes (`variant`)
+
+| Variante | Uso | Tokens |
+|----------|-----|--------|
+| `default` | Uso geral | `border`, `bg-background` |
+| `filled` | Ênfase visual | `bg-muted`, sem borda |
+| `flushed` | Minimalista | Apenas `border-bottom` |
+| `unstyled` | Customização total | Sem estilos base |
+
+### Tamanhos (`size`)
+
+| Tamanho | Altura | Padding | Toggle Size | Uso |
+|---------|--------|---------|-------------|-----|
+| `xs` | `h-7` | `px-2` | `h-5 w-5` | Espaços muito compactos |
+| `sm` | `h-8` | `px-2.5` | `h-6 w-6` | Espaços compactos |
+| `md` | `h-9` | `px-3` | `h-7 w-7` | Uso geral (padrão) |
+| `lg` | `h-10` | `px-3.5` | `h-8 w-8` | Formulários destacados |
+| `xl` | `h-11` | `px-4` | `h-9 w-9` | Áreas de destaque |
+
+### Estados
+
+| Estado | Classes/Atributos | Comportamento |
+|--------|-------------------|---------------|
+| Default | - | Campo de senha mascarado |
+| Visible | `type="text"` | Senha visível, ícone muda |
+| Focus | `focus-visible:ring-[3px]` | Ring de foco |
+| Disabled | `disabled:opacity-50` | 50% opacidade, toggle desabilitado |
+| Invalid | `aria-invalid:ring-destructive/20` | Ring vermelho |
+
+### Tokens Utilizados
+
+```css
+/* Cores */
+--background        /* Fundo do input */
+--border            /* Borda */
+--ring              /* Focus ring */
+--muted-foreground  /* Cor do ícone toggle */
+--foreground        /* Cor do ícone no hover */
+
+/* Espaçamento */
+pr-7 to pr-12       /* Padding right para acomodar toggle */
+
+/* Tipografia */
+text-sm             /* 14px */
+
+/* Bordas */
+rounded-md          /* var(--radius) */
+
+/* Transições */
+transition-colors   /* Transição suave no toggle */
+```
+
+### data-slot
+
+```html
+<div data-slot="password-input-wrapper">
+  <input data-slot="password-input" type="password" />
+  <button data-slot="password-toggle">...</button>
+</div>
+```
+
+---
+
+## API
+
+### Props
+
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `size` | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` | `"md"` | Tamanho visual do input |
+| `variant` | `"default" \| "filled" \| "flushed" \| "unstyled"` | `"default"` | Variante visual |
+| `showToggle` | `boolean` | `true` | Exibir botão de toggle de visibilidade |
+| `showIcon` | `ReactNode` | `<EyeIcon />` | Ícone customizado para "mostrar senha" |
+| `hideIcon` | `ReactNode` | `<EyeOffIcon />` | Ícone customizado para "ocultar senha" |
+| `disabled` | `boolean` | `false` | Desabilita o input e toggle |
+| `className` | `string` | - | Classes CSS adicionais |
+| `ref` | `Ref<HTMLInputElement>` | - | Referência ao elemento input |
+
+> Herda todas as props de `React.ComponentProps<"input">` exceto `type` e `size`
+
+### TypeScript
+
+```typescript
+import type { PasswordInputProps } from "@etus/ui"
+
+// Tipos base importados de TextInput
+type InputSize = "xs" | "sm" | "md" | "lg" | "xl"
+type InputVariant = "default" | "filled" | "flushed" | "unstyled"
+
+interface PasswordInputProps extends Omit<ComponentProps<"input">, "type" | "size"> {
+  size?: InputSize
+  variant?: InputVariant
+  showToggle?: boolean
+  showIcon?: ReactNode
+  hideIcon?: ReactNode
+}
+```
+
+### Comparativo com Design Systems de Referência
+
+#### Matriz de Features (12 Design Systems)
+
+| Feature | ETUS | Shadcn | Chakra | MUI | Mantine | AntD | NextUI | PrimeReact | Fluent | Carbon | Ariakit | React Aria |
+|---------|:----:|:------:|:------:|:---:|:-------:|:----:|:------:|:----------:|:------:|:------:|:-------:|:----------:|
+| **Toggle visibility** | ✓ | - | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | - |
+| **Custom icons** | ✓ | - | ✓ | - | ✓ | - | - | ✓ | - | - | - | - |
+| **Size variants** | 5 | - | 4 | 3 | 5 | 3 | 4 | 3 | 3 | 2 | - | - |
+| **Visual variants** | 4 | - | 4 | 3 | 2 | 2 | 4 | 3 | 2 | 2 | - | - |
+| **Strength indicator** | - | - | - | - | ✓ | - | - | ✓ | - | - | - | - |
+| **Requirements list** | - | - | - | - | ✓ | - | - | - | - | - | - | - |
+| **data-slot** | ✓ | ✓ | - | - | - | - | ✓ | - | - | - | - | - |
+| **CVA variants** | ✓ | ✓ | - | - | - | - | ✓ | - | - | - | - | - |
+| **aria-label auto** | ✓ | - | ✓ | ✓ | ✓ | - | ✓ | ✓ | ✓ | ✓ | - | - |
+
+#### Comparativo de Props por Design System
+
+| Prop | ETUS | Chakra | MUI | Mantine | AntD | NextUI | PrimeReact |
+|------|:----:|:------:|:---:|:-------:|:----:|:------:|:----------:|
+| `showToggle` | ✓ | - | - | - | - | - | ✓ (`toggleMask`) |
+| `showIcon`/`hideIcon` | ✓ | `show`/`hide` | - | `visibilityToggleIcon` | - | - | `showIcon`/`hideIcon` |
+| `size` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - |
+| `variant` | ✓ | ✓ | ✓ | ✓ | - | ✓ | - |
+| `isDisabled` | `disabled` | ✓ | `disabled` | `disabled` | `disabled` | ✓ | `disabled` |
+| `strengthMeter` | - | - | - | ✓ | - | - | ✓ |
+
+#### Análise por Categoria
+
+**Especializados em Password:**
+- **Mantine** - PasswordInput dedicado com strength meter e requirements
+- **PrimeReact** - Password com toggleMask e strength indicator
+- **Chakra UI** - InputGroup + InputRightElement pattern
+
+**Input genérico com type="password":**
+- **Shadcn/ui** - Input padrão, toggle manual
+- **MUI** - TextField + InputAdornment
+- **Ant Design** - Input.Password wrapper
+- **NextUI** - Input com endContent pattern
+
+**Primitivos (máxima flexibilidade):**
+- **React Aria** - useTextField hook
+- **Ariakit** - Form primitives
+
+---
+
+## Acessibilidade (A11y)
+
+### ARIA Attributes
+
+| Atributo | Uso |
+|----------|-----|
+| `aria-label` | Toggle button: "Show password" / "Hide password" |
+| `aria-hidden="true"` | Ícones decorativos |
+| `aria-invalid` | Validação de formulário |
+| `aria-describedby` | Mensagens de erro/ajuda |
+
+### Suporte a Teclado
+
+| Tecla | Ação |
+|-------|------|
+| `Tab` | Move foco para o input |
+| `Tab` (no input) | Pula para próximo elemento (toggle tem tabIndex=-1) |
+| `Enter` | Submete formulário (se em form) |
+| `Click` no toggle | Alterna visibilidade |
+
+### Focus Management
+
+```tsx
+// Toggle button não recebe foco via Tab (tabIndex={-1})
+// Evita interrupção na navegação do formulário
+<button tabIndex={-1} onClick={toggleVisibility}>
+```
+
+### Screen Readers
+
+- Toggle button tem `aria-label` dinâmico
+- Ícones marcados como `aria-hidden="true"`
+- Estado de visibilidade é comunicado via texto do aria-label
+
+### Segurança
+
+- Senha é mascarada por padrão (`type="password"`)
+- Toggle não altera dados, apenas visualização
+- Campos sensíveis devem usar `autocomplete="current-password"` ou `autocomplete="new-password"`
+
+### Comparativo A11y (12 Design Systems)
+
+| Feature | ETUS | React Aria | Chakra | MUI | Mantine | AntD | NextUI | Fluent | Carbon |
+|---------|:----:|:----------:|:------:|:---:|:-------:|:----:|:------:|:------:|:------:|
+| **ARIA label toggle** | ✓ | - | ✓ | ✓ | ✓ | - | ✓ | ✓ | ✓ |
+| **tabIndex=-1 toggle** | ✓ | - | - | - | - | - | - | ✓ | ✓ |
+| **aria-hidden icons** | ✓ | - | ✓ | ✓ | ✓ | - | ✓ | ✓ | ✓ |
+| **Focus visible** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| **autocomplete support** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+
+---
+
+## Exemplos
+
+### Uso Básico
+
+```tsx
+import { PasswordInput } from "@etus/ui"
+
+function Example() {
+  return <PasswordInput placeholder="Enter password" />
+}
+```
+
+### Tamanhos
+
+```tsx
+<PasswordInput size="xs" placeholder="Extra small" />
+<PasswordInput size="sm" placeholder="Small" />
+<PasswordInput size="md" placeholder="Medium (default)" />
+<PasswordInput size="lg" placeholder="Large" />
+<PasswordInput size="xl" placeholder="Extra large" />
+```
+
+### Variantes
+
+```tsx
+<PasswordInput variant="default" placeholder="Default" />
+<PasswordInput variant="filled" placeholder="Filled" />
+<PasswordInput variant="flushed" placeholder="Flushed" />
+<PasswordInput variant="unstyled" placeholder="Unstyled" />
+```
+
+### Sem Toggle
+
+```tsx
+// Para casos onde visibilidade não deve ser permitida
+<PasswordInput showToggle={false} placeholder="PIN code" />
+```
+
+### Com Ícones Customizados
+
+```tsx
+import { Lock, LockOpen } from "lucide-react"
+
+<PasswordInput
+  showIcon={<LockOpen className="size-4" />}
+  hideIcon={<Lock className="size-4" />}
+  placeholder="Custom icons"
+/>
+```
+
+### Estados
+
+```tsx
+// Desabilitado
+<PasswordInput disabled placeholder="Disabled" />
+
+// Com valor inicial
+<PasswordInput defaultValue="secret123" />
+
+// Controlado
+const [password, setPassword] = useState("")
+<PasswordInput
+  value={password}
+  onChange={(e) => setPassword(e.target.value)}
+/>
+```
+
+### Formulário de Login
+
+```tsx
+import { Button, Label, PasswordInput, TextInput } from "@etus/ui"
+
+function LoginForm() {
+  return (
+    <form className="space-y-4">
+      <div className="space-y-2">
+        <Label htmlFor="email">Email</Label>
+        <TextInput
+          id="email"
+          type="email"
+          placeholder="you@example.com"
+          autoComplete="email"
+        />
+      </div>
+      <div className="space-y-2">
+        <Label htmlFor="password">Password</Label>
+        <PasswordInput
+          id="password"
+          placeholder="Enter password"
+          autoComplete="current-password"
+        />
+      </div>
+      <Button type="submit" className="w-full">
+        Sign In
+      </Button>
+    </form>
+  )
+}
+```
+
+### Confirmação de Senha
+
+```tsx
+import { useState } from "react"
+import { Label, PasswordInput } from "@etus/ui"
+
+function PasswordConfirmation() {
+  const [password, setPassword] = useState("")
+  const [confirm, setConfirm] = useState("")
+  const isMatch = password === confirm
+
+  return (
+    <div className="space-y-4">
+      <div className="space-y-2">
+        <Label htmlFor="new-password">New Password</Label>
+        <PasswordInput
+          id="new-password"
+          value={password}
+          onChange={(e) => setPassword(e.target.value)}
+          autoComplete="new-password"
+        />
+      </div>
+      <div className="space-y-2">
+        <Label htmlFor="confirm-password">Confirm Password</Label>
+        <PasswordInput
+          id="confirm-password"
+          value={confirm}
+          onChange={(e) => setConfirm(e.target.value)}
+          autoComplete="new-password"
+          aria-invalid={confirm.length > 0 && !isMatch}
+        />
+        {confirm.length > 0 && !isMatch && (
+          <p className="text-sm text-destructive">Passwords do not match</p>
+        )}
+      </div>
+    </div>
+  )
+}
+```
+
+### Com React Hook Form
+
+```tsx
+import { useForm } from "react-hook-form"
+import { zodResolver } from "@hookform/resolvers/zod"
+import { z } from "zod"
+import { Button, Label, PasswordInput } from "@etus/ui"
+
+const schema = z.object({
+  password: z.string().min(8, "Password must be at least 8 characters"),
+})
+
+function PasswordForm() {
+  const { register, handleSubmit, formState: { errors } } = useForm({
+    resolver: zodResolver(schema),
+  })
+
+  return (
+    <form onSubmit={handleSubmit(console.log)} className="space-y-4">
+      <div className="space-y-2">
+        <Label htmlFor="password">Password</Label>
+        <PasswordInput
+          id="password"
+          {...register("password")}
+          aria-invalid={!!errors.password}
+          aria-describedby="password-error"
+        />
+        {errors.password && (
+          <p id="password-error" className="text-sm text-destructive">
+            {errors.password.message}
+          </p>
+        )}
+      </div>
+      <Button type="submit">Submit</Button>
+    </form>
+  )
+}
+```
+
+### Responsividade
+
+```tsx
+// Tamanho responsivo via className
+<PasswordInput className="h-8 md:h-9 lg:h-10" />
+
+// Full width
+<PasswordInput className="w-full" />
+```
+
+---
+
+## Testes
+
+### Testes Unitários
+
+```tsx
+// PasswordInput.test.tsx
+import { render, screen } from "@testing-library/react"
+import userEvent from "@testing-library/user-event"
+import { describe, expect, it } from "vitest"
+import { PasswordInput } from "./PasswordInput"
+
+describe("PasswordInput", () => {
+  it("renders with password type by default", () => {
+    render(<PasswordInput />)
+    expect(screen.getByRole("textbox", { hidden: true })).toHaveAttribute("type", "password")
+  })
+
+  it("applies size classes", () => {
+    render(<PasswordInput size="lg" />)
+    const input = screen.getByRole("textbox", { hidden: true })
+    expect(input).toHaveClass("h-10")
+  })
+
+  it("has data-slot attributes", () => {
+    render(<PasswordInput />)
+    expect(screen.getByTestId("password-input-wrapper") || document.querySelector('[data-slot="password-input-wrapper"]')).toBeInTheDocument()
+  })
+
+  it("renders toggle button by default", () => {
+    render(<PasswordInput />)
+    expect(screen.getByRole("button", { name: /show password/i })).toBeInTheDocument()
+  })
+
+  it("hides toggle when showToggle is false", () => {
+    render(<PasswordInput showToggle={false} />)
+    expect(screen.queryByRole("button")).not.toBeInTheDocument()
+  })
+})
+```
+
+### Testes de Interação
+
+```tsx
+describe("PasswordInput toggle", () => {
+  it("toggles password visibility on button click", async () => {
+    const user = userEvent.setup()
+    render(<PasswordInput defaultValue="secret" />)
+
+    const input = screen.getByDisplayValue("secret")
+    const toggleBtn = screen.getByRole("button", { name: /show password/i })
+
+    expect(input).toHaveAttribute("type", "password")
+
+    await user.click(toggleBtn)
+    expect(input).toHaveAttribute("type", "text")
+    expect(screen.getByRole("button", { name: /hide password/i })).toBeInTheDocument()
+
+    await user.click(toggleBtn)
+    expect(input).toHaveAttribute("type", "password")
+  })
+
+  it("toggle button has tabIndex -1", () => {
+    render(<PasswordInput />)
+    expect(screen.getByRole("button")).toHaveAttribute("tabIndex", "-1")
+  })
+
+  it("toggle is disabled when input is disabled", () => {
+    render(<PasswordInput disabled />)
+    expect(screen.getByRole("button")).toBeDisabled()
+  })
+})
+```
+
+### Testes de Acessibilidade
+
+```tsx
+import { axe, toHaveNoViolations } from "jest-axe"
+
+expect.extend(toHaveNoViolations)
+
+describe("PasswordInput accessibility", () => {
+  it("has no accessibility violations", async () => {
+    const { container } = render(
+      <label>
+        Password
+        <PasswordInput />
+      </label>
+    )
+    const results = await axe(container)
+    expect(results).toHaveNoViolations()
+  })
+
+  it("toggle button has accessible name", () => {
+    render(<PasswordInput />)
+    expect(screen.getByRole("button")).toHaveAccessibleName()
+  })
+
+  it("icons are hidden from screen readers", () => {
+    render(<PasswordInput />)
+    const icons = document.querySelectorAll("svg")
+    icons.forEach((icon) => {
+      expect(icon).toHaveAttribute("aria-hidden", "true")
+    })
+  })
+})
+```
+
+### Cenários Críticos
+
+```tsx
+describe("PasswordInput edge cases", () => {
+  it("works with custom icons", () => {
+    render(
+      <PasswordInput
+        showIcon={<span data-testid="show">Show</span>}
+        hideIcon={<span data-testid="hide">Hide</span>}
+      />
+    )
+    expect(screen.getByTestId("show")).toBeInTheDocument()
+  })
+
+  it("maintains value when toggling visibility", async () => {
+    const user = userEvent.setup()
+    render(<PasswordInput />)
+
+    const input = screen.getByRole("textbox", { hidden: true })
+    await user.type(input, "mypassword")
+
+    await user.click(screen.getByRole("button"))
+
+    expect(input).toHaveValue("mypassword")
+  })
+
+  it("works with form submission", async () => {
+    const user = userEvent.setup()
+    const handleSubmit = vi.fn((e) => e.preventDefault())
+
+    render(
+      <form onSubmit={handleSubmit}>
+        <PasswordInput name="password" />
+        <button type="submit">Submit</button>
+      </form>
+    )
+
+    await user.type(screen.getByRole("textbox", { hidden: true }), "secret")
+    await user.click(screen.getByRole("button", { name: "Submit" }))
+
+    expect(handleSubmit).toHaveBeenCalled()
+  })
+})
+```
+
+---
+
+## Roadmap / Features Futuras
+
+Baseado na análise comparativa com 14 design systems:
+
+### Prioridade Alta
+
+#### `strengthMeter`
+
+Indicador visual de força da senha.
+
+```tsx
+// Proposta de API
+interface PasswordInputProps {
+  showStrength?: boolean
+  strengthLabels?: string[]
+}
+
+// Uso
+<PasswordInput showStrength />
+```
+
+**Referências:** Mantine, PrimeReact
+
+#### `requirements`
+
+Lista de requisitos da senha com validação visual.
+
+```tsx
+// Proposta de API
+interface PasswordInputProps {
+  requirements?: {
+    label: string
+    validator: (value: string) => boolean
+  }[]
+}
+
+// Uso
+<PasswordInput
+  requirements={[
+    { label: "At least 8 characters", validator: (v) => v.length >= 8 },
+    { label: "Contains number", validator: (v) => /\d/.test(v) },
+  ]}
+/>
+```
+
+**Referências:** Mantine
+
+### Prioridade Média
+
+#### `onVisibilityChange`
+
+Callback quando visibilidade muda.
+
+```tsx
+// Proposta de API
+interface PasswordInputProps {
+  onVisibilityChange?: (visible: boolean) => void
+}
+
+// Uso
+<PasswordInput
+  onVisibilityChange={(visible) => console.log("Password visible:", visible)}
+/>
+```
+
+#### Melhorias de A11y
+
+```tsx
+// aria-describedby automático para requisitos
+// Live region para mudanças de força
+<PasswordInput
+  aria-describedby="password-requirements"
+  showStrength
+/>
+```
+
+### Prioridade Baixa
+
+#### `visibilityTimeout`
+
+Auto-ocultar senha após tempo.
+
+```tsx
+// Proposta de API
+interface PasswordInputProps {
+  visibilityTimeout?: number // ms
+}
+
+// Uso - oculta após 5 segundos
+<PasswordInput visibilityTimeout={5000} />
+```
+
+### Decisões de Design
+
+| Feature | Recomendação | Justificativa |
+|---------|--------------|---------------|
+| `strengthMeter` | ✅ Implementar | Alta demanda, melhora UX |
+| `requirements` | ✅ Implementar | Comum em cadastros |
+| `onVisibilityChange` | ⚠️ Avaliar | Casos de uso específicos |
+| `visibilityTimeout` | ❌ Evitar | Complexidade, edge cases |
+
+---
+
+## Referências
+
+### Design Systems Analisados
+
+| Design System | Documentação | GitHub |
+|---------------|--------------|--------|
+| **Shadcn/ui** | [Input](https://ui.shadcn.com/docs/components/input) | [shadcn-ui/ui](https://github.com/shadcn-ui/ui) |
+| **Chakra UI** | [Input](https://chakra-ui.com/docs/components/input) | [chakra-ui/chakra-ui](https://github.com/chakra-ui/chakra-ui) |
+| **MUI** | [TextField](https://mui.com/material-ui/react-text-field/) | [mui/material-ui](https://github.com/mui/material-ui) |
+| **Mantine** | [PasswordInput](https://mantine.dev/core/password-input/) | [mantinedev/mantine](https://github.com/mantinedev/mantine) |
+| **Ant Design** | [Input.Password](https://ant.design/components/input#inputpassword) | [ant-design/ant-design](https://github.com/ant-design/ant-design) |
+| **NextUI** | [Input](https://nextui.org/docs/components/input) | [nextui-org/nextui](https://github.com/nextui-org/nextui) |
+| **PrimeReact** | [Password](https://primereact.org/password/) | [primefaces/primereact](https://github.com/primefaces/primereact) |
+| **Fluent UI** | [Input](https://react.fluentui.dev/?path=/docs/components-input--default) | [microsoft/fluentui](https://github.com/microsoft/fluentui) |
+| **Carbon** | [PasswordInput](https://carbondesignsystem.com/components/text-input/usage/#password-input) | [carbon-design-system/carbon](https://github.com/carbon-design-system/carbon) |
+| **React Aria** | [useTextField](https://react-spectrum.adobe.com/react-aria/useTextField.html) | [adobe/react-spectrum](https://github.com/adobe/react-spectrum) |
+| **Ariakit** | [Form](https://ariakit.org/components/form) | [ariakit/ariakit](https://github.com/ariakit/ariakit) |
+
+### Especificações e Padrões
+
+- [WAI-ARIA APG - Forms](https://www.w3.org/WAI/ARIA/apg/patterns/forms/)
+- [WCAG 2.1 - Input Assistance](https://www.w3.org/WAI/WCAG21/Understanding/input-assistance)
+- [MDN - Input type="password"](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/password)
+- [HTML Spec - Password State](https://html.spec.whatwg.org/multipage/input.html#password-state-(type=password))
+
+### Ferramentas Utilizadas
+
+- [CVA - Class Variance Authority](https://cva.style/docs)
+- [Tailwind CSS](https://tailwindcss.com/docs)
+- [Lucide Icons](https://lucide.dev/icons/)

package/src/components/forms/PasswordInput/index.ts

@@ -0,0 +1,6 @@
+export * from './PasswordInput'
+export {
+  type PasswordToggleVariantProps,
+  passwordToggleVariants,
+} from './PasswordInput.variants'
+export type { PasswordInputProps } from './PasswordInput.types'