@etus/ui 0.1.0

package/src/components/data-display/Item/README.md

@@ -0,0 +1,759 @@
+# Item
+
+## Visão Geral
+
+O Item e um sistema de componentes compound para exibicao de itens em listas, feeds e colecoes. Fornece uma estrutura flexivel com areas para media, conteudo, acoes e metadados, seguindo padroes consistentes de layout e espacamento.
+
+### Classificacao Atomica
+- **Categoria**: Molecules
+- **Subcategoria**: Data Display / Lists
+
+### Casos de Uso Comuns
+- Listas de contatos ou usuarios
+- Itens de menu ou navegacao
+- Cards de notificacao
+- Linhas de resultados de busca
+- Itens de configuracao
+- Feed de atividades
+- Historico de transacoes
+
+### Relacao com Outros Componentes
+- **List**: Container para multiplos Items
+- **Feed**: Usa Item para items de atividade
+- **Card**: Alternativa mais elaborada
+- **Table**: Para dados tabulares estruturados
+- **Avatar**: Frequentemente usado em ItemMedia
+
+## Design Specs
+
+### Componentes do Sistema
+
+1. **Item**: Container principal do item
+2. **ItemGroup**: Container para agrupar multiplos items
+3. **ItemSeparator**: Divisor entre items
+4. **ItemMedia**: Area para icone, avatar ou imagem
+5. **ItemContent**: Container para titulo e descricao
+6. **ItemTitle**: Titulo principal
+7. **ItemDescription**: Texto descritivo secundario
+8. **ItemActions**: Area para botoes e acoes
+9. **ItemHeader**: Cabecalho do item (largura total)
+10. **ItemFooter**: Rodape do item (largura total)
+
+### Variantes do Item
+
+| Variante | Classes | Uso |
+|----------|---------|-----|
+| `default` | `bg-transparent` | Padrao, sem fundo |
+| `outline` | `border-border` | Com borda visivel |
+| `muted` | `bg-muted/50` | Fundo sutil |
+
+### Tamanhos do Item
+
+| Tamanho | Classes | Uso |
+|---------|---------|-----|
+| `default` | `p-4 gap-4` | Espacamento padrao |
+| `sm` | `py-3 px-4 gap-2.5` | Espacamento compacto |
+
+### Variantes do ItemMedia
+
+| Variante | Classes | Uso |
+|----------|---------|-----|
+| `default` | `bg-transparent` | Icones diretos |
+| `icon` | `size-8 border rounded-sm bg-muted` | Container para icone |
+| `image` | `size-10 rounded-sm overflow-hidden` | Imagens/avatares |
+
+### Estados
+
+- **Default**: Estilo base
+- **Hover**: `hover:bg-accent/50` para links
+- **Focus**: `focus-visible:ring-[3px] focus-visible:ring-ring/50`
+- **Interactive**: Quando `asChild` com link
+
+### Tokens de Design
+
+#### Cores
+- Background (muted): `bg-muted/50`
+- Border: `border-border`
+- Title: `text-foreground` (via font-medium)
+- Description: `text-muted-foreground`
+- Icon Container: `bg-muted`
+- Links: `text-primary` no hover
+
+#### Espacamento
+- Default Padding: `p-4`
+- Default Gap: `gap-4`
+- Small Padding: `py-3 px-4`
+- Small Gap: `gap-2.5`
+- Content Gap: `gap-1`
+- Actions Gap: `gap-2`
+
+#### Tipografia
+- Title: `text-sm font-medium leading-snug`
+- Description: `text-sm font-normal leading-normal`
+- Description clamp: `line-clamp-2`
+
+#### Bordas e Arredondamento
+- Container: `rounded-md`
+- Icon Container: `rounded-sm`
+- Image Container: `rounded-sm`
+
+#### Motion e Transicoes
+- Transition: `transition-colors duration-100`
+
+### Consideracoes de Responsividade
+
+- **Mobile**: Items de largura total
+- **Tablet**: Pode usar grid de 2 colunas
+- **Desktop**: Grid de 2-3 colunas ou lista
+- **Container Queries**: Use `@container` para ajustar layout
+
+## API
+
+### Item
+
+| Prop | Tipo | Padrao | Descricao |
+|------|------|--------|-----------|
+| `variant` | `"default" \| "outline" \| "muted"` | `"default"` | Estilo visual |
+| `size` | `"default" \| "sm"` | `"default"` | Tamanho/espacamento |
+| `asChild` | `boolean` | `false` | Renderiza como filho (slot) |
+| `className` | `string` | `""` | Classes Tailwind |
+
+### ItemGroup
+
+| Prop | Tipo | Padrao | Descricao |
+|------|------|--------|-----------|
+| `className` | `string` | `""` | Classes Tailwind |
+
+### ItemSeparator
+
+| Prop | Tipo | Padrao | Descricao |
+|------|------|--------|-----------|
+| `className` | `string` | `""` | Classes Tailwind |
+
+### ItemMedia
+
+| Prop | Tipo | Padrao | Descricao |
+|------|------|--------|-----------|
+| `variant` | `"default" \| "icon" \| "image"` | `"default"` | Estilo do container |
+| `className` | `string` | `""` | Classes Tailwind |
+
+### ItemContent
+
+| Prop | Tipo | Padrao | Descricao |
+|------|------|--------|-----------|
+| `className` | `string` | `""` | Classes Tailwind |
+
+### ItemTitle
+
+| Prop | Tipo | Padrao | Descricao |
+|------|------|--------|-----------|
+| `className` | `string` | `""` | Classes Tailwind |
+
+### ItemDescription
+
+| Prop | Tipo | Padrao | Descricao |
+|------|------|--------|-----------|
+| `className` | `string` | `""` | Classes Tailwind |
+
+### ItemActions
+
+| Prop | Tipo | Padrao | Descricao |
+|------|------|--------|-----------|
+| `className` | `string` | `""` | Classes Tailwind |
+
+### ItemHeader / ItemFooter
+
+| Prop | Tipo | Padrao | Descricao |
+|------|------|--------|-----------|
+| `className` | `string` | `""` | Classes Tailwind |
+
+### Interfaces TypeScript
+
+```typescript
+import { type VariantProps } from "class-variance-authority"
+
+// Item Variants
+const itemVariants = cva(
+  "group/item flex items-center border border-transparent text-sm rounded-md transition-colors ...",
+  {
+    variants: {
+      variant: {
+        default: "bg-transparent",
+        outline: "border-border",
+        muted: "bg-muted/50",
+      },
+      size: {
+        default: "p-4 gap-4",
+        sm: "py-3 px-4 gap-2.5",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+      size: "default",
+    },
+  }
+)
+
+// Item Props
+interface ItemProps
+  extends React.ComponentProps<"div">,
+    VariantProps<typeof itemVariants> {
+  asChild?: boolean
+}
+
+// ItemMedia Variants
+const itemMediaVariants = cva(
+  "flex shrink-0 items-center justify-center gap-2 ...",
+  {
+    variants: {
+      variant: {
+        default: "bg-transparent",
+        icon: "size-8 border rounded-sm bg-muted [&_svg:not([class*='size-'])]:size-4",
+        image: "size-10 rounded-sm overflow-hidden [&_img]:size-full [&_img]:object-cover",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+    },
+  }
+)
+
+// ItemMedia Props
+interface ItemMediaProps
+  extends React.ComponentProps<"div">,
+    VariantProps<typeof itemMediaVariants> {}
+```
+
+### Comparacao com Referencias
+
+| Feature | ETUS | MUI ListItem | Chakra | Ant List.Item |
+|---------|------|--------------|--------|---------------|
+| Compound | Sim | Sim | Parcial | Sim |
+| Variantes | Sim | Nao | Nao | Nao |
+| Media Area | Sim | Sim | Sim | Sim |
+| asChild | Sim | Nao | Nao | Nao |
+| Actions | Sim | Sim | Sim | Sim |
+| Header/Footer | Sim | Nao | Nao | Nao |
+
+## Acessibilidade (A11y)
+
+### Atributos ARIA
+
+- `ItemGroup` tem `role="list"`
+- Items individuais sao reconhecidos como list items
+- Quando `asChild` com link, herda semantica do link
+
+### Navegacao por Teclado
+
+| Tecla | Acao |
+|-------|------|
+| `Tab` | Navega entre items interativos |
+| `Enter` | Ativa link/acao do item |
+| `Space` | Ativa checkbox/toggle se houver |
+
+### Contraste e Legibilidade
+
+- Titulo com contraste de 4.5:1
+- Descricao com contraste de 4.5:1
+- Focus ring visivel
+
+### Tecnologias Assistivas
+
+- Screen readers anunciam estrutura de lista
+- Items com links sao navegaveis
+- Descricoes sao associadas ao item
+
+### Conformidade WCAG
+
+- **1.3.1** Info e Relacionamentos: Estrutura semantica correta
+- **2.4.4** Objetivo do link: Links descritivos
+- **2.4.7** Foco visivel: Focus ring claro
+
+## Exemplos
+
+### Uso Basico
+
+```tsx
+import {
+  Item,
+  ItemMedia,
+  ItemContent,
+  ItemTitle,
+  ItemDescription
+} from '@etus/ui'
+import { User } from 'lucide-react'
+
+function BasicItem() {
+  return (
+    <Item>
+      <ItemMedia variant="icon">
+        <User />
+      </ItemMedia>
+      <ItemContent>
+        <ItemTitle>John Doe</ItemTitle>
+        <ItemDescription>
+          Software Engineer at ETUS
+        </ItemDescription>
+      </ItemContent>
+    </Item>
+  )
+}
+```
+
+### Lista de Items
+
+```tsx
+import {
+  ItemGroup,
+  Item,
+  ItemMedia,
+  ItemContent,
+  ItemTitle,
+  ItemDescription,
+  ItemSeparator
+} from '@etus/ui'
+import { User, Mail, Phone } from 'lucide-react'
+
+function ItemList() {
+  return (
+    <ItemGroup>
+      <Item>
+        <ItemMedia variant="icon">
+          <User />
+        </ItemMedia>
+        <ItemContent>
+          <ItemTitle>Profile</ItemTitle>
+          <ItemDescription>Manage your profile settings</ItemDescription>
+        </ItemContent>
+      </Item>
+      <ItemSeparator />
+      <Item>
+        <ItemMedia variant="icon">
+          <Mail />
+        </ItemMedia>
+        <ItemContent>
+          <ItemTitle>Email</ItemTitle>
+          <ItemDescription>Update email preferences</ItemDescription>
+        </ItemContent>
+      </Item>
+      <ItemSeparator />
+      <Item>
+        <ItemMedia variant="icon">
+          <Phone />
+        </ItemMedia>
+        <ItemContent>
+          <ItemTitle>Phone</ItemTitle>
+          <ItemDescription>Add or change phone number</ItemDescription>
+        </ItemContent>
+      </Item>
+    </ItemGroup>
+  )
+}
+```
+
+### Com Avatar
+
+```tsx
+import {
+  Item,
+  ItemMedia,
+  ItemContent,
+  ItemTitle,
+  ItemDescription
+} from '@etus/ui'
+import { Avatar, AvatarImage, AvatarFallback } from '@etus/ui'
+
+function AvatarItem() {
+  return (
+    <Item>
+      <ItemMedia variant="image">
+        <Avatar>
+          <AvatarImage src="/avatar.jpg" />
+          <AvatarFallback>JD</AvatarFallback>
+        </Avatar>
+      </ItemMedia>
+      <ItemContent>
+        <ItemTitle>Jane Doe</ItemTitle>
+        <ItemDescription>Online 2 minutes ago</ItemDescription>
+      </ItemContent>
+    </Item>
+  )
+}
+```
+
+### Com Acoes
+
+```tsx
+import {
+  Item,
+  ItemMedia,
+  ItemContent,
+  ItemTitle,
+  ItemDescription,
+  ItemActions
+} from '@etus/ui'
+import { Button } from '@etus/ui'
+import { FileText, Download, Trash2 } from 'lucide-react'
+
+function ItemWithActions() {
+  return (
+    <Item variant="outline">
+      <ItemMedia variant="icon">
+        <FileText />
+      </ItemMedia>
+      <ItemContent>
+        <ItemTitle>document.pdf</ItemTitle>
+        <ItemDescription>2.4 MB - Uploaded yesterday</ItemDescription>
+      </ItemContent>
+      <ItemActions>
+        <Button variant="ghost" size="icon">
+          <Download className="size-4" />
+        </Button>
+        <Button variant="ghost" size="icon">
+          <Trash2 className="size-4" />
+        </Button>
+      </ItemActions>
+    </Item>
+  )
+}
+```
+
+### Como Link
+
+```tsx
+import {
+  Item,
+  ItemMedia,
+  ItemContent,
+  ItemTitle,
+  ItemDescription
+} from '@etus/ui'
+import { Settings } from 'lucide-react'
+import { Link } from 'react-router-dom'
+
+function LinkItem() {
+  return (
+    <Item asChild>
+      <Link to="/settings">
+        <ItemMedia variant="icon">
+          <Settings />
+        </ItemMedia>
+        <ItemContent>
+          <ItemTitle>Settings</ItemTitle>
+          <ItemDescription>Manage your preferences</ItemDescription>
+        </ItemContent>
+      </Link>
+    </Item>
+  )
+}
+```
+
+### Com Header e Footer
+
+```tsx
+import {
+  Item,
+  ItemMedia,
+  ItemContent,
+  ItemTitle,
+  ItemDescription,
+  ItemHeader,
+  ItemFooter
+} from '@etus/ui'
+import { Badge } from '@etus/ui'
+import { Clock, Package } from 'lucide-react'
+
+function ItemWithHeaderFooter() {
+  return (
+    <Item variant="outline">
+      <ItemHeader>
+        <div className="flex items-center gap-2 text-xs text-muted-foreground">
+          <Clock className="size-3" />
+          <span>2 hours ago</span>
+        </div>
+        <Badge variant="secondary">New</Badge>
+      </ItemHeader>
+
+      <ItemMedia variant="icon">
+        <Package />
+      </ItemMedia>
+      <ItemContent>
+        <ItemTitle>Order #12345</ItemTitle>
+        <ItemDescription>
+          Your order has been shipped and is on its way
+        </ItemDescription>
+      </ItemContent>
+
+      <ItemFooter>
+        <span className="text-xs text-muted-foreground">
+          Estimated delivery: Dec 25
+        </span>
+        <a href="#" className="text-xs text-primary">
+          Track order
+        </a>
+      </ItemFooter>
+    </Item>
+  )
+}
+```
+
+### Variante Compacta
+
+```tsx
+import {
+  ItemGroup,
+  Item,
+  ItemMedia,
+  ItemContent,
+  ItemTitle,
+  ItemSeparator
+} from '@etus/ui'
+import { Check, X, Clock } from 'lucide-react'
+
+function CompactItems() {
+  return (
+    <ItemGroup>
+      <Item size="sm">
+        <ItemMedia>
+          <Check className="size-4 text-green-500" />
+        </ItemMedia>
+        <ItemContent>
+          <ItemTitle>Task completed</ItemTitle>
+        </ItemContent>
+      </Item>
+      <ItemSeparator />
+      <Item size="sm">
+        <ItemMedia>
+          <Clock className="size-4 text-yellow-500" />
+        </ItemMedia>
+        <ItemContent>
+          <ItemTitle>Task in progress</ItemTitle>
+        </ItemContent>
+      </Item>
+      <ItemSeparator />
+      <Item size="sm">
+        <ItemMedia>
+          <X className="size-4 text-red-500" />
+        </ItemMedia>
+        <ItemContent>
+          <ItemTitle>Task failed</ItemTitle>
+        </ItemContent>
+      </Item>
+    </ItemGroup>
+  )
+}
+```
+
+### Notificacao Item
+
+```tsx
+import {
+  Item,
+  ItemMedia,
+  ItemContent,
+  ItemTitle,
+  ItemDescription,
+  ItemActions
+} from '@etus/ui'
+import { Button } from '@etus/ui'
+import { Bell, X } from 'lucide-react'
+
+function NotificationItem({ notification, onDismiss }) {
+  return (
+    <Item variant="muted">
+      <ItemMedia variant="icon">
+        <Bell />
+      </ItemMedia>
+      <ItemContent>
+        <ItemTitle>{notification.title}</ItemTitle>
+        <ItemDescription>{notification.message}</ItemDescription>
+      </ItemContent>
+      <ItemActions>
+        <Button
+          variant="ghost"
+          size="icon"
+          onClick={() => onDismiss(notification.id)}
+        >
+          <X className="size-4" />
+        </Button>
+      </ItemActions>
+    </Item>
+  )
+}
+```
+
+### Com Multiplo Conteudo
+
+```tsx
+import {
+  Item,
+  ItemMedia,
+  ItemContent,
+  ItemTitle,
+  ItemDescription
+} from '@etus/ui'
+import { Avatar, AvatarImage, AvatarFallback } from '@etus/ui'
+
+function MultiContentItem() {
+  return (
+    <Item>
+      <ItemMedia variant="image">
+        <Avatar>
+          <AvatarImage src="/user.jpg" />
+          <AvatarFallback>U</AvatarFallback>
+        </Avatar>
+      </ItemMedia>
+      <ItemContent>
+        <ItemTitle>Primary Content</ItemTitle>
+        <ItemDescription>Main description text</ItemDescription>
+      </ItemContent>
+      <ItemContent className="text-right">
+        <ItemTitle className="text-sm text-muted-foreground">
+          R$ 1.234,00
+        </ItemTitle>
+        <ItemDescription>+12.5%</ItemDescription>
+      </ItemContent>
+    </Item>
+  )
+}
+```
+
+## Testes
+
+### Estrategias de Teste
+
+#### Testes Unitarios
+- Renderizacao de todos os sub-componentes
+- Variantes aplicadas corretamente
+- asChild funcionando
+
+#### Testes de Integracao
+- Item completo com todos os elementos
+- Lista de items com separadores
+- Navegacao em items clicaveis
+
+#### Testes de Acessibilidade
+- Role list no ItemGroup
+- Links navegaveis
+- Focus visible
+
+### Exemplos de Codigo
+
+```typescript
+import { describe, it, expect } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import {
+  Item,
+  ItemGroup,
+  ItemMedia,
+  ItemContent,
+  ItemTitle,
+  ItemDescription,
+  ItemActions,
+  ItemSeparator
+} from './Item'
+import { User } from 'lucide-react'
+
+describe('Item', () => {
+  it('renders all sub-components', () => {
+    render(
+      <Item>
+        <ItemMedia variant="icon">
+          <User data-testid="icon" />
+        </ItemMedia>
+        <ItemContent>
+          <ItemTitle>Title</ItemTitle>
+          <ItemDescription>Description</ItemDescription>
+        </ItemContent>
+        <ItemActions>
+          <button>Action</button>
+        </ItemActions>
+      </Item>
+    )
+
+    expect(screen.getByTestId('icon')).toBeInTheDocument()
+    expect(screen.getByText('Title')).toBeInTheDocument()
+    expect(screen.getByText('Description')).toBeInTheDocument()
+    expect(screen.getByText('Action')).toBeInTheDocument()
+  })
+
+  it('applies variant classes', () => {
+    const { container } = render(
+      <Item variant="outline">
+        <ItemTitle>Test</ItemTitle>
+      </Item>
+    )
+
+    const item = container.querySelector('[data-slot="item"]')
+    expect(item).toHaveAttribute('data-variant', 'outline')
+  })
+
+  it('applies size classes', () => {
+    const { container } = render(
+      <Item size="sm">
+        <ItemTitle>Test</ItemTitle>
+      </Item>
+    )
+
+    const item = container.querySelector('[data-slot="item"]')
+    expect(item).toHaveAttribute('data-size', 'sm')
+  })
+
+  it('renders as child element when asChild', () => {
+    render(
+      <Item asChild>
+        <a href="/test">
+          <ItemTitle>Link Item</ItemTitle>
+        </a>
+      </Item>
+    )
+
+    expect(screen.getByRole('link')).toHaveAttribute('href', '/test')
+  })
+
+  it('renders ItemGroup with list role', () => {
+    render(
+      <ItemGroup>
+        <Item>
+          <ItemTitle>Item 1</ItemTitle>
+        </Item>
+      </ItemGroup>
+    )
+
+    expect(screen.getByRole('list')).toBeInTheDocument()
+  })
+
+  it('renders separators', () => {
+    const { container } = render(
+      <ItemGroup>
+        <Item><ItemTitle>1</ItemTitle></Item>
+        <ItemSeparator />
+        <Item><ItemTitle>2</ItemTitle></Item>
+      </ItemGroup>
+    )
+
+    expect(
+      container.querySelector('[data-slot="item-separator"]')
+    ).toBeInTheDocument()
+  })
+})
+```
+
+---
+
+## Roadmap / Features Futuras
+
+- Usa compound components para maxima flexibilidade
+- CVA para variantes de Item e ItemMedia
+- Slot (Radix) para asChild
+- `data-slot` para identificacao de partes
+- Grupos com `group/item` e `group/item-group` para estilos contextuais
+- Auto-alinhamento de media quando ha descricao
+
+## Referências
+
+- [Shadcn UI - Nao tem Item nativo]
+- [MUI ListItem](https://mui.com/material-ui/react-list/)
+- [Chakra UI List](https://chakra-ui.com/docs/components/list)
+- [Ant Design List](https://ant.design/components/list)
+- [Carbon Structured List](https://carbondesignsystem.com/components/structured-list/usage/)