@etus/ui 0.1.1 → 0.1.2

package/src/components/navigation/Breadcrumb/README.md

@@ -1,608 +0,0 @@
-# Breadcrumb
-
-## Visão Geral
-
-O componente Breadcrumb exibe a hierarquia de navegacao do usuario dentro da aplicacao, permitindo navegacao rapida para niveis anteriores. E um padrao de navegacao secundaria essencial para aplicacoes com estruturas profundas de paginas.
-
-### Classificacao Atomica
-- **Categoria**: Molecules
-- **Subcategoria**: Navigation
-
-### Casos de Uso Comuns
-- Navegacao em dashboards administrativos com multiplos niveis
-- E-commerce com categorias e subcategorias de produtos
-- Sistemas de gerenciamento de arquivos e pastas
-- Documentacao tecnica com secoes aninhadas
-- Portais corporativos com estrutura hierarquica
-
-### Relacao com Outros Componentes
-- **Link**: BreadcrumbLink utiliza semantica de ancora para navegacao
-- **DropdownMenu**: Pode ser combinado com BreadcrumbEllipsis para mostrar itens ocultos
-- **NavigationMenu**: Complementa a navegacao principal como indicador de contexto
-
-## Design Specs
-
-### Variantes
-
-O Breadcrumb do ETUS e composto por subcomponentes que formam a estrutura completa:
-
-- **Breadcrumb**: Container `<nav>` com `aria-label="breadcrumb"`
-- **BreadcrumbList**: Lista ordenada `<ol>` com os itens
-- **BreadcrumbItem**: Item `<li>` individual
-- **BreadcrumbLink**: Link clicavel para navegacao
-- **BreadcrumbPage**: Pagina atual (nao clicavel)
-- **BreadcrumbSeparator**: Separador visual entre itens
-- **BreadcrumbEllipsis**: Indicador de itens ocultos
-
-### Tamanhos
-
-O componente utiliza tamanho padrao baseado em `text-sm`:
-- **Default**: `text-sm` (14px) com `gap-1.5` entre itens (mobile) ou `gap-2.5` (desktop)
-
-### Estados
-
-- **Default**: Texto em `text-muted-foreground` para links
-- **Hover**: Transicao para `text-foreground` nos links
-- **Current Page**: `text-foreground font-normal` com `aria-current="page"`
-- **Disabled**: Via `aria-disabled="true"` na pagina atual
-
-### Tokens de Design
-
-#### Cores
-- Text (links): `text-muted-foreground`
-- Text (hover): `text-foreground`
-- Text (current): `text-foreground`
-- Separator/Ellipsis: Herda cor do contexto
-
-#### Espacamento
-- Gap entre itens: `gap-1.5` (mobile), `gap-2.5` (desktop via `sm:`)
-- Gap interno do item: `gap-1.5`
-
-#### Tipografia
-- Font Size: `text-sm` (14px)
-- Font Weight: `font-normal`
-
-#### Icones
-- Separator icon: `ChevronRight` em `size-3.5`
-- Ellipsis icon: `MoreHorizontal` em `size-4`
-- Ellipsis container: `size-9` (36px)
-
-### Consideracoes de Responsividade
-- **Mobile (< 640px)**: Gap reduzido de `gap-1.5`, considera truncar com ellipsis
-- **Tablet/Desktop (>= 640px)**: Gap aumentado para `gap-2.5`
-- Texto usa `break-words` e `flex-wrap` para quebra natural
-
-## API
-
-### Componentes Exportados
-
-#### Breadcrumb
-Container principal do breadcrumb.
-
-| Prop | Tipo | Padrao | Descricao |
-|------|------|--------|-----------|
-| `...props` | `React.ComponentProps<"nav">` | - | Props nativas do elemento nav |
-
-#### BreadcrumbList
-Lista ordenada que contem os itens.
-
-| Prop | Tipo | Padrao | Descricao |
-|------|------|--------|-----------|
-| `className` | `string` | `''` | Classes Tailwind adicionais |
-| `...props` | `React.ComponentProps<"ol">` | - | Props nativas do elemento ol |
-
-#### BreadcrumbItem
-Item individual do breadcrumb.
-
-| Prop | Tipo | Padrao | Descricao |
-|------|------|--------|-----------|
-| `className` | `string` | `''` | Classes Tailwind adicionais |
-| `...props` | `React.ComponentProps<"li">` | - | Props nativas do elemento li |
-
-#### BreadcrumbLink
-Link navegavel dentro do breadcrumb.
-
-| Prop | Tipo | Padrao | Descricao |
-|------|------|--------|-----------|
-| `asChild` | `boolean` | `false` | Renderiza como elemento filho (composicao) |
-| `className` | `string` | `''` | Classes Tailwind adicionais |
-| `...props` | `React.ComponentProps<"a">` | - | Props nativas do elemento a |
-
-#### BreadcrumbPage
-Indica a pagina atual (ultimo item).
-
-| Prop | Tipo | Padrao | Descricao |
-|------|------|--------|-----------|
-| `className` | `string` | `''` | Classes Tailwind adicionais |
-| `...props` | `React.ComponentProps<"span">` | - | Props nativas do elemento span |
-
-#### BreadcrumbSeparator
-Separador visual entre itens.
-
-| Prop | Tipo | Padrao | Descricao |
-|------|------|--------|-----------|
-| `children` | `ReactNode` | `<ChevronRight />` | Icone ou conteudo customizado |
-| `className` | `string` | `''` | Classes Tailwind adicionais |
-| `...props` | `React.ComponentProps<"li">` | - | Props nativas do elemento li |
-
-#### BreadcrumbEllipsis
-Indicador de itens ocultos.
-
-| Prop | Tipo | Padrao | Descricao |
-|------|------|--------|-----------|
-| `className` | `string` | `''` | Classes Tailwind adicionais |
-| `...props` | `React.ComponentProps<"span">` | - | Props nativas do elemento span |
-
-### Interfaces TypeScript
-
-```typescript
-import * as React from "react"
-
-// BreadcrumbLink Props
-interface BreadcrumbLinkProps extends React.ComponentProps<"a"> {
-  asChild?: boolean
-}
-
-// BreadcrumbSeparator Props
-interface BreadcrumbSeparatorProps extends React.ComponentProps<"li"> {
-  children?: React.ReactNode
-}
-
-// BreadcrumbLabel/Item Props com inset (para submenus)
-interface BreadcrumbItemWithInset extends React.ComponentProps<"li"> {
-  inset?: boolean
-}
-```
-
-### Comparacao com Referencias
-
-| Feature | ETUS | Shadcn/ui | Radix | MUI | Chakra |
-|---------|------|-----------|-------|-----|--------|
-| Compound Components | Sim | Sim | N/A | Sim | Sim |
-| asChild Pattern | Sim | Sim | N/A | Nao | Nao |
-| Separator Customizavel | Sim | Sim | N/A | Sim | Sim |
-| Ellipsis Built-in | Sim | Sim | N/A | Nao | Nao |
-| aria-current | Sim | Sim | N/A | Sim | Sim |
-
-## Acessibilidade (A11y)
-
-### Atributos ARIA
-- `aria-label="breadcrumb"`: No elemento `<nav>` para identificacao
-- `aria-current="page"`: Na pagina atual (BreadcrumbPage)
-- `aria-disabled="true"`: Na pagina atual para indicar nao-interatividade
-- `aria-hidden="true"`: Nos separadores e ellipsis
-- `role="presentation"`: Nos separadores para remover semantica de lista
-- `role="link"`: Na BreadcrumbPage para manter semantica
-
-### Navegacao por Teclado
-- `Tab`: Navega entre os links do breadcrumb
-- `Shift + Tab`: Navega em direcao reversa
-- `Enter`: Ativa o link focado
-- `Space`: Ativa o link focado (comportamento padrao de links)
-
-### Contraste e Legibilidade
-- Ratio de contraste minimo: WCAG AA (4.5:1 para texto)
-- `text-muted-foreground` e `text-foreground` seguem tokens acessiveis
-- Transicao de hover fornece feedback visual claro
-
-### Tecnologias Assistivas
-- Screen readers anunciam "breadcrumb navigation" ao entrar no componente
-- Cada link e anunciado com seu texto
-- Pagina atual e anunciada como "current page"
-- Separadores e ellipsis sao ocultados de screen readers
-
-### Conformidade WCAG
-- **Nivel alvo**: WCAG 2.1 AA
-- **Criterios atendidos**:
-  - 1.3.1 Info and Relationships (Level A)
-  - 2.4.4 Link Purpose (Level A)
-  - 2.4.8 Location (Level AAA)
-  - 4.1.2 Name, Role, Value (Level A)
-
-## Exemplos
-
-### Uso Basico
-
-```tsx
-import {
-  Breadcrumb,
-  BreadcrumbList,
-  BreadcrumbItem,
-  BreadcrumbLink,
-  BreadcrumbPage,
-  BreadcrumbSeparator,
-} from "@etus/ui"
-
-function BasicBreadcrumb() {
-  return (
-    <Breadcrumb>
-      <BreadcrumbList>
-        <BreadcrumbItem>
-          <BreadcrumbLink href="/">Home</BreadcrumbLink>
-        </BreadcrumbItem>
-        <BreadcrumbSeparator />
-        <BreadcrumbItem>
-          <BreadcrumbLink href="/products">Products</BreadcrumbLink>
-        </BreadcrumbItem>
-        <BreadcrumbSeparator />
-        <BreadcrumbItem>
-          <BreadcrumbPage>Current Product</BreadcrumbPage>
-        </BreadcrumbItem>
-      </BreadcrumbList>
-    </Breadcrumb>
-  )
-}
-```
-
-### Com React Router / Next.js Link
-
-```tsx
-import { Link } from "react-router-dom" // ou next/link
-import {
-  Breadcrumb,
-  BreadcrumbList,
-  BreadcrumbItem,
-  BreadcrumbLink,
-  BreadcrumbPage,
-  BreadcrumbSeparator,
-} from "@etus/ui"
-
-function RouterBreadcrumb() {
-  return (
-    <Breadcrumb>
-      <BreadcrumbList>
-        <BreadcrumbItem>
-          <BreadcrumbLink asChild>
-            <Link to="/">Home</Link>
-          </BreadcrumbLink>
-        </BreadcrumbItem>
-        <BreadcrumbSeparator />
-        <BreadcrumbItem>
-          <BreadcrumbLink asChild>
-            <Link to="/dashboard">Dashboard</Link>
-          </BreadcrumbLink>
-        </BreadcrumbItem>
-        <BreadcrumbSeparator />
-        <BreadcrumbItem>
-          <BreadcrumbPage>Settings</BreadcrumbPage>
-        </BreadcrumbItem>
-      </BreadcrumbList>
-    </Breadcrumb>
-  )
-}
-```
-
-### Com Ellipsis para Paths Longos
-
-```tsx
-import {
-  Breadcrumb,
-  BreadcrumbList,
-  BreadcrumbItem,
-  BreadcrumbLink,
-  BreadcrumbPage,
-  BreadcrumbSeparator,
-  BreadcrumbEllipsis,
-} from "@etus/ui"
-import {
-  DropdownMenu,
-  DropdownMenuContent,
-  DropdownMenuItem,
-  DropdownMenuTrigger,
-} from "@etus/ui"
-
-function EllipsisBreadcrumb() {
-  return (
-    <Breadcrumb>
-      <BreadcrumbList>
-        <BreadcrumbItem>
-          <BreadcrumbLink href="/">Home</BreadcrumbLink>
-        </BreadcrumbItem>
-        <BreadcrumbSeparator />
-        <BreadcrumbItem>
-          <DropdownMenu>
-            <DropdownMenuTrigger asChild>
-              <BreadcrumbEllipsis />
-            </DropdownMenuTrigger>
-            <DropdownMenuContent align="start">
-              <DropdownMenuItem>
-                <a href="/level-1">Level 1</a>
-              </DropdownMenuItem>
-              <DropdownMenuItem>
-                <a href="/level-2">Level 2</a>
-              </DropdownMenuItem>
-              <DropdownMenuItem>
-                <a href="/level-3">Level 3</a>
-              </DropdownMenuItem>
-            </DropdownMenuContent>
-          </DropdownMenu>
-        </BreadcrumbItem>
-        <BreadcrumbSeparator />
-        <BreadcrumbItem>
-          <BreadcrumbLink href="/parent">Parent</BreadcrumbLink>
-        </BreadcrumbItem>
-        <BreadcrumbSeparator />
-        <BreadcrumbItem>
-          <BreadcrumbPage>Current</BreadcrumbPage>
-        </BreadcrumbItem>
-      </BreadcrumbList>
-    </Breadcrumb>
-  )
-}
-```
-
-### Separador Customizado
-
-```tsx
-import { Slash } from "lucide-react"
-import {
-  Breadcrumb,
-  BreadcrumbList,
-  BreadcrumbItem,
-  BreadcrumbLink,
-  BreadcrumbPage,
-  BreadcrumbSeparator,
-} from "@etus/ui"
-
-function CustomSeparatorBreadcrumb() {
-  return (
-    <Breadcrumb>
-      <BreadcrumbList>
-        <BreadcrumbItem>
-          <BreadcrumbLink href="/">Home</BreadcrumbLink>
-        </BreadcrumbItem>
-        <BreadcrumbSeparator>
-          <Slash className="size-4" />
-        </BreadcrumbSeparator>
-        <BreadcrumbItem>
-          <BreadcrumbLink href="/docs">Docs</BreadcrumbLink>
-        </BreadcrumbItem>
-        <BreadcrumbSeparator>
-          <Slash className="size-4" />
-        </BreadcrumbSeparator>
-        <BreadcrumbItem>
-          <BreadcrumbPage>Components</BreadcrumbPage>
-        </BreadcrumbItem>
-      </BreadcrumbList>
-    </Breadcrumb>
-  )
-}
-```
-
-### Breadcrumb Dinamico
-
-```tsx
-import { useLocation } from "react-router-dom"
-import {
-  Breadcrumb,
-  BreadcrumbList,
-  BreadcrumbItem,
-  BreadcrumbLink,
-  BreadcrumbPage,
-  BreadcrumbSeparator,
-} from "@etus/ui"
-
-function DynamicBreadcrumb() {
-  const location = useLocation()
-  const pathnames = location.pathname.split("/").filter((x) => x)
-
-  return (
-    <Breadcrumb>
-      <BreadcrumbList>
-        <BreadcrumbItem>
-          <BreadcrumbLink href="/">Home</BreadcrumbLink>
-        </BreadcrumbItem>
-        {pathnames.map((name, index) => {
-          const routeTo = `/${pathnames.slice(0, index + 1).join("/")}`
-          const isLast = index === pathnames.length - 1
-
-          return (
-            <React.Fragment key={name}>
-              <BreadcrumbSeparator />
-              <BreadcrumbItem>
-                {isLast ? (
-                  <BreadcrumbPage>{name}</BreadcrumbPage>
-                ) : (
-                  <BreadcrumbLink href={routeTo}>{name}</BreadcrumbLink>
-                )}
-              </BreadcrumbItem>
-            </React.Fragment>
-          )
-        })}
-      </BreadcrumbList>
-    </Breadcrumb>
-  )
-}
-```
-
-### Com Icones
-
-```tsx
-import { Home, Folder, File } from "lucide-react"
-import {
-  Breadcrumb,
-  BreadcrumbList,
-  BreadcrumbItem,
-  BreadcrumbLink,
-  BreadcrumbPage,
-  BreadcrumbSeparator,
-} from "@etus/ui"
-
-function IconBreadcrumb() {
-  return (
-    <Breadcrumb>
-      <BreadcrumbList>
-        <BreadcrumbItem>
-          <BreadcrumbLink href="/" className="flex items-center gap-1.5">
-            <Home className="size-4" />
-            <span>Home</span>
-          </BreadcrumbLink>
-        </BreadcrumbItem>
-        <BreadcrumbSeparator />
-        <BreadcrumbItem>
-          <BreadcrumbLink href="/files" className="flex items-center gap-1.5">
-            <Folder className="size-4" />
-            <span>Files</span>
-          </BreadcrumbLink>
-        </BreadcrumbItem>
-        <BreadcrumbSeparator />
-        <BreadcrumbItem>
-          <BreadcrumbPage className="flex items-center gap-1.5">
-            <File className="size-4" />
-            <span>Document.pdf</span>
-          </BreadcrumbPage>
-        </BreadcrumbItem>
-      </BreadcrumbList>
-    </Breadcrumb>
-  )
-}
-```
-
-## Testes
-
-### Estrategias de Teste
-
-#### Testes Unitarios
-- Renderizacao de todos os subcomponentes
-- Aplicacao correta de classes CSS
-- Funcionalidade do asChild pattern
-- Renderizacao condicional de separadores
-
-#### Testes de Integracao
-- Navegacao com React Router/Next.js
-- Interacao com DropdownMenu no ellipsis
-- Breadcrumb dinamico baseado em URL
-
-#### Testes de Acessibilidade
-- Presenca de aria-label no nav
-- aria-current na pagina atual
-- Ocultacao de separadores para screen readers
-- Navegacao por teclado
-
-### Exemplos de Codigo
-
-```typescript
-import { describe, it, expect } from "vitest"
-import { render, screen } from "@testing-library/react"
-import {
-  Breadcrumb,
-  BreadcrumbList,
-  BreadcrumbItem,
-  BreadcrumbLink,
-  BreadcrumbPage,
-  BreadcrumbSeparator,
-} from "./Breadcrumb"
-
-describe("Breadcrumb", () => {
-  it("renders with correct aria-label", () => {
-    render(
-      <Breadcrumb>
-        <BreadcrumbList>
-          <BreadcrumbItem>
-            <BreadcrumbLink href="/">Home</BreadcrumbLink>
-          </BreadcrumbItem>
-        </BreadcrumbList>
-      </Breadcrumb>
-    )
-
-    expect(screen.getByRole("navigation")).toHaveAttribute(
-      "aria-label",
-      "breadcrumb"
-    )
-  })
-
-  it("marks current page with aria-current", () => {
-    render(
-      <Breadcrumb>
-        <BreadcrumbList>
-          <BreadcrumbItem>
-            <BreadcrumbPage>Current</BreadcrumbPage>
-          </BreadcrumbItem>
-        </BreadcrumbList>
-      </Breadcrumb>
-    )
-
-    expect(screen.getByText("Current")).toHaveAttribute(
-      "aria-current",
-      "page"
-    )
-  })
-
-  it("hides separators from screen readers", () => {
-    render(
-      <Breadcrumb>
-        <BreadcrumbList>
-          <BreadcrumbItem>
-            <BreadcrumbLink href="/">Home</BreadcrumbLink>
-          </BreadcrumbItem>
-          <BreadcrumbSeparator data-testid="separator" />
-          <BreadcrumbItem>
-            <BreadcrumbPage>Current</BreadcrumbPage>
-          </BreadcrumbItem>
-        </BreadcrumbList>
-      </Breadcrumb>
-    )
-
-    expect(screen.getByTestId("separator")).toHaveAttribute(
-      "aria-hidden",
-      "true"
-    )
-  })
-
-  it("applies custom className", () => {
-    render(
-      <Breadcrumb className="custom-class">
-        <BreadcrumbList>
-          <BreadcrumbItem>
-            <BreadcrumbPage>Test</BreadcrumbPage>
-          </BreadcrumbItem>
-        </BreadcrumbList>
-      </Breadcrumb>
-    )
-
-    expect(screen.getByRole("navigation")).toHaveClass("custom-class")
-  })
-})
-```
-
-### Testes de Acessibilidade com axe-core
-
-```typescript
-import { axe, toHaveNoViolations } from "jest-axe"
-
-expect.extend(toHaveNoViolations)
-
-it("has no accessibility violations", async () => {
-  const { container } = render(
-    <Breadcrumb>
-      <BreadcrumbList>
-        <BreadcrumbItem>
-          <BreadcrumbLink href="/">Home</BreadcrumbLink>
-        </BreadcrumbItem>
-        <BreadcrumbSeparator />
-        <BreadcrumbItem>
-          <BreadcrumbPage>Current</BreadcrumbPage>
-        </BreadcrumbItem>
-      </BreadcrumbList>
-    </Breadcrumb>
-  )
-
-  const results = await axe(container)
-  expect(results).toHaveNoViolations()
-})
-```
-
----
-
-## Roadmap / Features Futuras
-
-- Construido sobre elementos HTML semanticos (`<nav>`, `<ol>`, `<li>`)
-- Utiliza `@radix-ui/react-slot` para o pattern asChild
-- Icones via `lucide-react` (ChevronRight, MoreHorizontal)
-- Totalmente compativel com Server Components (sem "use client")
-
-## Referências
-
-- [WAI-ARIA Breadcrumb Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/breadcrumb/)
-- [Shadcn/ui Breadcrumb](https://ui.shadcn.com/docs/components/breadcrumb)
-- [MDN: aria-current](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-current)

package/src/components/navigation/Breadcrumb/index.ts

@@ -1,24 +0,0 @@
-export * from './Breadcrumb'
-export {
-  type BreadcrumbEllipsisVariantProps,
-  breadcrumbEllipsisVariants,
-  type BreadcrumbItemVariantProps,
-  breadcrumbItemVariants,
-  type BreadcrumbLinkVariantProps,
-  breadcrumbLinkVariants,
-  type BreadcrumbListVariantProps,
-  breadcrumbListVariants,
-  type BreadcrumbPageVariantProps,
-  breadcrumbPageVariants,
-  type BreadcrumbSeparatorVariantProps,
-  breadcrumbSeparatorVariants,
-} from './Breadcrumb.variants'
-export type {
-  BreadcrumbEllipsisProps,
-  BreadcrumbItemProps,
-  BreadcrumbLinkProps,
-  BreadcrumbListProps,
-  BreadcrumbPageProps,
-  BreadcrumbProps,
-  BreadcrumbSeparatorProps,
-} from './Breadcrumb.types'