@etus/ui 0.1.0

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

@@ -0,0 +1,729 @@
+# SearchInput
+
+## Visao Geral
+
+O **SearchInput** e um componente de entrada especializado para busca, com icone de pesquisa integrado e botao de limpar opcional. Construido sobre o componente TextInput, oferece uma experiencia de busca otimizada com suporte a modos controlado e nao-controlado.
+
+### Casos de Uso
+
+- Busca global em aplicacoes
+- Filtros de listagens e tabelas
+- Busca em menus e dropdowns
+- Pesquisa em campos de selecao
+- Navegacao por pesquisa
+
+### Classificacao
+
+**Categoria:** Molecule
+**Dependencias:** `lucide-react`, `class-variance-authority`, `TextInput`
+
+---
+
+## Design Specs
+
+### Variantes (`variant`)
+
+| Variante | Uso | Tokens |
+|----------|-----|--------|
+| `default` | Uso padrao | `border`, `bg-background` |
+| `filled` | Fundo preenchido | `bg-muted` |
+| `flushed` | Apenas borda inferior | `border-b` |
+| `unstyled` | Sem estilos | Sem estilos visuais |
+
+### Tamanhos (`size`)
+
+| Tamanho | Altura | Padding Icon | Uso |
+|---------|--------|--------------|-----|
+| `xs` | Compacto | `pl-7` / `pr-7` | Espacos muito compactos |
+| `sm` | `h-8` (32px) | `pl-9` / `pr-9` | Espacos compactos, tabelas |
+| `md` | `h-9` (36px) | `pl-10` / `pr-10` | Uso geral |
+| `lg` | `h-10` (40px) | `pl-11` / `pr-11` | CTAs, acoes principais |
+| `xl` | Grande | `pl-12` / `pr-12` | Destaques |
+
+### Estados
+
+| Estado | Classes/Atributos | Comportamento |
+|--------|-------------------|---------------|
+| Default | - | Aparencia base |
+| Hover | `hover:border-input` | Borda mais visivel |
+| Focus | `focus-visible:ring-[3px]` | Ring de 3px com `ring-ring/50` |
+| Disabled | `disabled:opacity-50` | 50% opacidade, sem pointer events |
+| Com Valor | Botao clear visivel | Mostra icone X |
+| Vazio | Apenas icone de busca | Esconde botao clear |
+
+### Tokens Utilizados
+
+```css
+/* Cores */
+--muted-foreground    /* Cor do icone de busca */
+--foreground          /* Cor do icone hover */
+--ring                /* Focus ring */
+--background          /* Fundo default */
+--border              /* Borda default */
+
+/* Espacamento */
+pl-10                 /* Padding left para icone (md) */
+pr-10                 /* Padding right para clear (md) */
+
+/* Tipografia */
+text-sm               /* 14px */
+
+/* Bordas */
+rounded-md            /* var(--radius) */
+
+/* Transicoes */
+transition-colors     /* Cores do clear button */
+```
+
+### data-slot
+
+```html
+<div data-slot="search-input-wrapper">
+  <span data-slot="search-icon">...</span>
+  <input data-slot="search-input" type="search" />
+  <button data-slot="clear-button">...</button>
+</div>
+```
+
+---
+
+## API
+
+### Props
+
+| Prop | Tipo | Padrao | Descricao |
+|------|------|--------|-----------|
+| `size` | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` | `"md"` | Tamanho visual do input |
+| `variant` | `"default" \| "filled" \| "flushed" \| "unstyled"` | `"default"` | Estilo visual |
+| `showClearButton` | `boolean` | `true` | Mostra botao de limpar quando ha valor |
+| `onClear` | `() => void` | - | Callback quando botao clear e clicado |
+| `searchIcon` | `ReactNode` | `<SearchIcon />` | Icone customizado de busca |
+| `clearIcon` | `ReactNode` | `<XIcon />` | Icone customizado do botao clear |
+| `className` | `string` | - | Classes CSS adicionais |
+| `disabled` | `boolean` | `false` | Desabilita o input |
+| `value` | `string` | - | Valor controlado |
+| `defaultValue` | `string` | - | Valor inicial nao-controlado |
+| `onChange` | `(e: ChangeEvent) => void` | - | Callback de mudanca |
+| `placeholder` | `string` | - | Texto placeholder |
+
+> Herda todas as props de `React.ComponentProps<"input">` exceto `type` e `size`
+
+### Callbacks
+
+| Callback | Tipo | Descricao |
+|----------|------|-----------|
+| `onChange` | `(event: ChangeEvent<HTMLInputElement>) => void` | Disparado ao digitar |
+| `onClear` | `() => void` | Disparado ao clicar no botao limpar |
+| `onFocus` | `(event: FocusEvent) => void` | Disparado ao receber foco |
+| `onBlur` | `(event: FocusEvent) => void` | Disparado ao perder foco |
+| `onKeyDown` | `(event: KeyboardEvent) => void` | Disparado ao pressionar tecla |
+
+### TypeScript
+
+```typescript
+import type { SearchInputProps } from "@etus/ui"
+import type { InputSize, InputVariant } from "@etus/ui"
+
+// SearchInputProps inclui:
+interface SearchInputProps extends Omit<ComponentProps<"input">, "type" | "size"> {
+  size?: InputSize
+  variant?: InputVariant
+  showClearButton?: boolean
+  onClear?: () => void
+  searchIcon?: ReactNode
+  clearIcon?: ReactNode
+}
+
+// Tipos derivados
+type InputSize = "xs" | "sm" | "md" | "lg" | "xl"
+type InputVariant = "default" | "filled" | "flushed" | "unstyled"
+```
+
+### Comparativo com Design Systems de Referencia
+
+#### Matriz de Features (12 Design Systems)
+
+| Feature | ETUS | Shadcn | Radix | Chakra | MUI | Mantine | AntD | NextUI | Headless | Ariakit | Fluent | Carbon |
+|---------|:----:|:------:|:-----:|:------:|:---:|:-------:|:----:|:------:|:--------:|:-------:|:------:|:------:|
+| **Search Input** | ✓ | - | - | ✓ | ✓ | ✓ | ✓ | ✓ | - | - | ✓ | ✓ |
+| **Clear Button** | ✓ | - | - | ✓ | ✓ | ✓ | ✓ | ✓ | - | - | ✓ | ✓ |
+| **Custom Icons** | ✓ | - | - | ✓ | ✓ | ✓ | ✓ | ✓ | - | - | ✓ | ✓ |
+| **Controlled** | ✓ | - | - | ✓ | ✓ | ✓ | ✓ | ✓ | - | - | ✓ | ✓ |
+| **Uncontrolled** | ✓ | - | - | ✓ | ✓ | ✓ | ✓ | ✓ | - | - | ✓ | ✓ |
+| **Loading State** | - | - | - | - | ✓ | ✓ | ✓ | ✓ | - | - | ✓ | ✓ |
+| **Debounce** | - | - | - | - | - | - | ✓ | - | - | - | - | - |
+| **Voice Search** | - | - | - | - | - | - | - | - | - | - | - | - |
+
+#### Comparativo de Props por Design System
+
+| Prop | ETUS | Chakra | MUI | Mantine | AntD | NextUI | Fluent |
+|------|:----:|:------:|:---:|:-------:|:----:|:------:|:------:|
+| `size` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| `variant` | ✓ | ✓ | ✓ | ✓ | - | ✓ | `appearance` |
+| `disabled` | ✓ | `isDisabled` | ✓ | ✓ | ✓ | `isDisabled` | ✓ |
+| `clearButton` | ✓ | - | ✓ | ✓ | `allowClear` | `isClearable` | ✓ |
+| `onClear` | ✓ | - | `onClear` | `onClear` | `onClear` | `onClear` | ✓ |
+| `searchIcon` | ✓ | `leftElement` | `startAdornment` | `leftSection` | `prefix` | `startContent` | - |
+| `clearIcon` | ✓ | `rightElement` | `endAdornment` | `rightSection` | `suffix` | `endContent` | - |
+| `placeholder` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+
+---
+
+## Acessibilidade (A11y)
+
+### ARIA Attributes
+
+| Atributo | Uso |
+|----------|-----|
+| `type="search"` | Semantica correta para busca |
+| `aria-label` | Quando nao ha label visivel |
+| `aria-describedby` | Link para texto de ajuda |
+| `aria-disabled` | Quando `disabled={true}` |
+
+### Suporte a Teclado
+
+| Tecla | Acao |
+|-------|------|
+| `Tab` | Move foco para/do input |
+| `Escape` | Limpa o campo (comportamento nativo) |
+| `Enter` | Submete formulario (se em form) |
+
+### Focus Management
+
+```tsx
+// Focus visible no input
+focus-visible:border-ring
+focus-visible:ring-ring/50
+focus-visible:ring-[3px]
+
+// Focus visible no clear button
+focus-visible:outline-none
+focus-visible:ring-2
+focus-visible:ring-ring
+focus-visible:ring-offset-2
+```
+
+### Contraste de Cores
+
+Todos os pares de cores seguem WCAG 2.1 AA (minimo 4.5:1):
+
+| Elemento | Foreground | Background | Ratio |
+|----------|------------|------------|-------|
+| Search Icon | `--muted-foreground` | Transparente | >= 4.5:1 |
+| Clear Button | `--muted-foreground` | Transparente | >= 4.5:1 |
+| Clear Hover | `--foreground` | Transparente | >= 4.5:1 |
+| Placeholder | `--muted-foreground` | `--background` | >= 4.5:1 |
+
+### Screen Readers
+
+- Usar `aria-label` para descrever o proposito da busca
+- O botao clear tem `aria-label="Clear search"` automatico
+- Icones decorativos marcados com `aria-hidden="true"`
+
+### Clear Button Accessibility
+
+```tsx
+<button
+  type="button"
+  aria-label="Clear search"
+  tabIndex={-1}  // Nao recebe foco por Tab
+>
+```
+
+---
+
+## Exemplos
+
+### Uso Basico
+
+```tsx
+import { SearchInput } from "@etus/ui"
+
+function Example() {
+  return <SearchInput placeholder="Search..." />
+}
+```
+
+### Controlado
+
+```tsx
+import { useState } from "react"
+import { SearchInput } from "@etus/ui"
+
+function ControlledSearch() {
+  const [query, setQuery] = useState("")
+
+  return (
+    <SearchInput
+      value={query}
+      onChange={(e) => setQuery(e.target.value)}
+      onClear={() => setQuery("")}
+      placeholder="Search products..."
+    />
+  )
+}
+```
+
+### Nao-Controlado
+
+```tsx
+import { SearchInput } from "@etus/ui"
+
+function UncontrolledSearch() {
+  return (
+    <SearchInput
+      defaultValue="initial search"
+      placeholder="Search..."
+    />
+  )
+}
+```
+
+### Tamanhos
+
+```tsx
+<SearchInput size="xs" placeholder="Extra Small" />
+<SearchInput size="sm" placeholder="Small" />
+<SearchInput size="md" placeholder="Medium (default)" />
+<SearchInput size="lg" placeholder="Large" />
+<SearchInput size="xl" placeholder="Extra Large" />
+```
+
+### Variantes
+
+```tsx
+<SearchInput variant="default" placeholder="Default" />
+<SearchInput variant="filled" placeholder="Filled" />
+<SearchInput variant="flushed" placeholder="Flushed" />
+<SearchInput variant="unstyled" placeholder="Unstyled" />
+```
+
+### Sem Botao Clear
+
+```tsx
+<SearchInput
+  showClearButton={false}
+  placeholder="No clear button"
+/>
+```
+
+### Com Icones Customizados
+
+```tsx
+import { MagnifyingGlass, Close } from "@phosphor-icons/react"
+
+function CustomIcons() {
+  return (
+    <SearchInput
+      searchIcon={<MagnifyingGlass className="size-4" />}
+      clearIcon={<Close className="size-4" />}
+      placeholder="Custom icons..."
+    />
+  )
+}
+```
+
+### Desabilitado
+
+```tsx
+<SearchInput
+  disabled
+  placeholder="Disabled search"
+/>
+```
+
+### Com Debounce
+
+```tsx
+import { useState, useDeferredValue } from "react"
+import { SearchInput } from "@etus/ui"
+
+function DebouncedSearch() {
+  const [query, setQuery] = useState("")
+  const deferredQuery = useDeferredValue(query)
+
+  // Use deferredQuery para busca
+  return (
+    <SearchInput
+      value={query}
+      onChange={(e) => setQuery(e.target.value)}
+      onClear={() => setQuery("")}
+      placeholder="Search with debounce..."
+    />
+  )
+}
+```
+
+### Em Formulario
+
+```tsx
+import { SearchInput } from "@etus/ui"
+
+function SearchForm() {
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault()
+    const formData = new FormData(e.target as HTMLFormElement)
+    console.log("Search:", formData.get("search"))
+  }
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <SearchInput
+        name="search"
+        placeholder="Press Enter to search..."
+      />
+    </form>
+  )
+}
+```
+
+### Com Loading (composicao)
+
+```tsx
+import { SearchInput } from "@etus/ui"
+import { Loader2 } from "lucide-react"
+
+function SearchWithLoading({ isLoading }: { isLoading: boolean }) {
+  return (
+    <div className="relative">
+      <SearchInput placeholder="Search..." />
+      {isLoading && (
+        <Loader2 className="absolute right-10 top-1/2 -translate-y-1/2 size-4 animate-spin" />
+      )}
+    </div>
+  )
+}
+```
+
+---
+
+## Testes
+
+### Testes Unitarios
+
+```tsx
+// SearchInput.test.tsx
+import { render, screen } from "@testing-library/react"
+import userEvent from "@testing-library/user-event"
+import { describe, expect, it, vi } from "vitest"
+import { SearchInput } from "./SearchInput"
+
+describe("SearchInput", () => {
+  it("renders with placeholder", () => {
+    render(<SearchInput placeholder="Search..." />)
+    expect(screen.getByPlaceholderText("Search...")).toBeInTheDocument()
+  })
+
+  it("renders search icon", () => {
+    render(<SearchInput placeholder="Search..." />)
+    expect(screen.getByRole("textbox")).toBeInTheDocument()
+  })
+
+  it("applies size classes", () => {
+    render(<SearchInput size="lg" placeholder="Search..." />)
+    const wrapper = screen.getByRole("textbox").parentElement
+    expect(wrapper).toHaveClass("relative")
+  })
+
+  it("has correct type attribute", () => {
+    render(<SearchInput placeholder="Search..." />)
+    expect(screen.getByRole("searchbox")).toHaveAttribute("type", "search")
+  })
+
+  it("has data-slot attribute", () => {
+    render(<SearchInput placeholder="Search..." />)
+    expect(screen.getByRole("searchbox")).toHaveAttribute("data-slot", "search-input")
+  })
+})
+```
+
+### Testes de Interacao
+
+```tsx
+describe("SearchInput interactions", () => {
+  it("calls onChange when typing", async () => {
+    const user = userEvent.setup()
+    const handleChange = vi.fn()
+
+    render(<SearchInput onChange={handleChange} placeholder="Search..." />)
+    await user.type(screen.getByRole("searchbox"), "test")
+
+    expect(handleChange).toHaveBeenCalledTimes(4)
+  })
+
+  it("shows clear button when has value", async () => {
+    const user = userEvent.setup()
+
+    render(<SearchInput placeholder="Search..." />)
+    await user.type(screen.getByRole("searchbox"), "test")
+
+    expect(screen.getByRole("button", { name: "Clear search" })).toBeInTheDocument()
+  })
+
+  it("hides clear button when empty", () => {
+    render(<SearchInput placeholder="Search..." />)
+    expect(screen.queryByRole("button", { name: "Clear search" })).not.toBeInTheDocument()
+  })
+
+  it("calls onClear when clear button clicked", async () => {
+    const user = userEvent.setup()
+    const handleClear = vi.fn()
+
+    render(
+      <SearchInput
+        value="test"
+        onChange={() => {}}
+        onClear={handleClear}
+        placeholder="Search..."
+      />
+    )
+
+    await user.click(screen.getByRole("button", { name: "Clear search" }))
+    expect(handleClear).toHaveBeenCalledOnce()
+  })
+
+  it("clears value in uncontrolled mode", async () => {
+    const user = userEvent.setup()
+
+    render(<SearchInput defaultValue="test" placeholder="Search..." />)
+    await user.click(screen.getByRole("button", { name: "Clear search" }))
+
+    expect(screen.getByRole("searchbox")).toHaveValue("")
+  })
+})
+```
+
+### Testes de Acessibilidade
+
+```tsx
+import { axe, toHaveNoViolations } from "jest-axe"
+
+expect.extend(toHaveNoViolations)
+
+describe("SearchInput accessibility", () => {
+  it("has no accessibility violations", async () => {
+    const { container } = render(
+      <label>
+        Search
+        <SearchInput placeholder="Search..." />
+      </label>
+    )
+    const results = await axe(container)
+    expect(results).toHaveNoViolations()
+  })
+
+  it("is focusable", async () => {
+    render(<SearchInput placeholder="Search..." />)
+    const input = screen.getByRole("searchbox")
+    input.focus()
+    expect(input).toHaveFocus()
+  })
+
+  it("is not focusable when disabled", () => {
+    render(<SearchInput disabled placeholder="Search..." />)
+    expect(screen.getByRole("searchbox")).toBeDisabled()
+  })
+
+  it("clear button has aria-label", async () => {
+    const user = userEvent.setup()
+    render(<SearchInput placeholder="Search..." />)
+    await user.type(screen.getByRole("searchbox"), "test")
+
+    expect(screen.getByRole("button")).toHaveAttribute("aria-label", "Clear search")
+  })
+})
+```
+
+### Testes de Modo Controlado/Nao-Controlado
+
+```tsx
+describe("SearchInput controlled vs uncontrolled", () => {
+  it("works as controlled component", async () => {
+    const user = userEvent.setup()
+    const ControlledWrapper = () => {
+      const [value, setValue] = useState("")
+      return (
+        <SearchInput
+          value={value}
+          onChange={(e) => setValue(e.target.value)}
+          placeholder="Search..."
+        />
+      )
+    }
+
+    render(<ControlledWrapper />)
+    await user.type(screen.getByRole("searchbox"), "test")
+    expect(screen.getByRole("searchbox")).toHaveValue("test")
+  })
+
+  it("works as uncontrolled component", async () => {
+    const user = userEvent.setup()
+    render(<SearchInput defaultValue="initial" placeholder="Search..." />)
+
+    expect(screen.getByRole("searchbox")).toHaveValue("initial")
+    await user.clear(screen.getByRole("searchbox"))
+    await user.type(screen.getByRole("searchbox"), "new value")
+    expect(screen.getByRole("searchbox")).toHaveValue("new value")
+  })
+})
+```
+
+---
+
+## Roadmap / Features Futuras
+
+Baseado na analise comparativa com 14 design systems, as seguintes features sao candidatas para implementacao futura:
+
+### Implementado
+
+#### Clear Button
+
+Botao para limpar o valor do input.
+
+```tsx
+// API implementada
+<SearchInput showClearButton onClear={() => setValue("")} />
+```
+
+#### Custom Icons
+
+Icones customizaveis para busca e clear.
+
+```tsx
+// API implementada
+<SearchInput
+  searchIcon={<CustomSearch />}
+  clearIcon={<CustomClose />}
+/>
+```
+
+### Prioridade Alta
+
+#### `loading`
+
+Estado de carregamento durante busca.
+
+```tsx
+// Proposta de API
+interface SearchInputProps {
+  loading?: boolean
+  loadingPosition?: "left" | "right"
+}
+
+// Uso
+<SearchInput loading placeholder="Searching..." />
+```
+
+**Referencias:** MUI, Mantine, AntD
+
+### Prioridade Media
+
+#### `debounce`
+
+Debounce built-in para busca.
+
+```tsx
+// Proposta de API
+interface SearchInputProps {
+  debounce?: number // ms
+  onSearch?: (value: string) => void
+}
+
+// Uso
+<SearchInput
+  debounce={300}
+  onSearch={(value) => fetchResults(value)}
+/>
+```
+
+**Referencias:** AntD (`Search.onSearch`)
+
+#### `onSearch`
+
+Callback dedicado para busca (Enter ou botao).
+
+```tsx
+// Proposta de API
+interface SearchInputProps {
+  onSearch?: (value: string) => void
+  enterButton?: boolean | ReactNode
+}
+
+// Uso
+<SearchInput
+  onSearch={(value) => console.log("Search:", value)}
+  enterButton="Go"
+/>
+```
+
+**Referencias:** AntD (`Input.Search`)
+
+### Prioridade Baixa
+
+#### `suggestions`
+
+Autocomplete/sugestoes integradas.
+
+```tsx
+// Proposta de API
+<SearchInput
+  suggestions={["Option 1", "Option 2"]}
+  onSuggestionSelect={(value) => setValue(value)}
+/>
+```
+
+**Referencias:** MUI (Autocomplete), AntD (AutoComplete)
+
+#### `voice`
+
+Entrada por voz.
+
+```tsx
+// Proposta de API
+<SearchInput
+  voice
+  onVoiceResult={(transcript) => setValue(transcript)}
+/>
+```
+
+**Referencias:** Poucos DS implementam
+
+### Decisoes de Design
+
+| Feature | Recomendacao | Justificativa |
+|---------|--------------|---------------|
+| `loading` | Implementar | UX melhor durante busca async |
+| `debounce` | Avaliar | Pode ser feito com hooks externos |
+| `onSearch` | Implementar | API mais intuitiva |
+| `suggestions` | Usar Combobox | Componente separado mais flexivel |
+| `voice` | Evitar | Complexidade alta, baixo uso |
+
+---
+
+## Referencias
+
+### Design Systems Analisados
+
+| Design System | Documentacao Search | 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** | [TextInput](https://mantine.dev/core/text-input/) | [mantinedev/mantine](https://github.com/mantinedev/mantine) |
+| **Ant Design** | [Input.Search](https://ant.design/components/input#components-input-demo-search-input) | [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) |
+| **Fluent UI** | [SearchBox](https://react.fluentui.dev/?path=/docs/components-searchbox--default) | [microsoft/fluentui](https://github.com/microsoft/fluentui) |
+| **Carbon** | [Search](https://carbondesignsystem.com/components/search/usage/) | [carbon-design-system/carbon](https://github.com/carbon-design-system/carbon) |
+
+### Especificacoes e Padroes
+
+- [WAI-ARIA APG - Combobox Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/)
+- [WCAG 2.1 Success Criteria](https://www.w3.org/WAI/WCAG21/quickref/)
+- [MDN - Input type="search"](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/search)
+- [HTML Spec - Input Search](https://html.spec.whatwg.org/multipage/input.html#text-(type=text)-state-and-search-state-(type=search))
+
+### Ferramentas Utilizadas
+
+- [CVA - Class Variance Authority](https://cva.style/docs)
+- [Tailwind CSS](https://tailwindcss.com/docs)
+- [Lucide Icons](https://lucide.dev/icons/)