@etus/ui 0.1.0

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

@@ -0,0 +1,670 @@
+# Navbar
+
+## Visão Geral
+
+O Navbar e um componente de navegacao horizontal principal que combina branding, links de navegacao, busca e acoes do usuario. E essencial para aplicacoes web, fornecendo orientacao e acesso rapido as principais areas do sistema.
+
+### Classificacao Atomica
+- **Categoria**: Organisms
+- **Subcategoria**: Navigation
+
+### Casos de Uso Comuns
+- Navegacao principal de sites e aplicacoes
+- Headers de dashboards
+- Barras de navegacao de e-commerce
+- Navigation de portais corporativos
+- Headers de documentacao
+
+### Relacao com Outros Componentes
+- **Header**: Navbar pode ser parte do Header ou sinonimo
+- **NavigationMenu**: Menu de navegacao com mega-menus
+- **DropdownMenu**: Para menus de usuario
+- **Sidebar**: Navegacao complementar lateral
+- **Breadcrumb**: Navegacao secundaria
+
+## Design Specs
+
+### Estrutura Sugerida
+
+```
++------------------------------------------------------------------+
+| [Logo/Brand]  [Nav Items...]  [Search]  [Notifications] [User]   |
++------------------------------------------------------------------+
+```
+
+### Variantes
+
+| Variante | Descricao | Uso |
+|----------|-----------|-----|
+| `default` | Navbar padrao | Maioria das aplicacoes |
+| `transparent` | Sem background | Hero sections |
+| `bordered` | Com border inferior | Separacao clara |
+| `floating` | Com margem e sombra | Visual moderno |
+
+### Tamanhos
+
+| Tamanho | Altura | Uso |
+|---------|--------|-----|
+| `sm` | `h-12` (48px) | Interfaces compactas |
+| `md` | `h-14` (56px) | Padrao |
+| `lg` | `h-16` (64px) | Dashboards, portais |
+
+### Estados
+
+- **Default**: Estado normal
+- **Scrolled**: Pode adicionar sombra/blur
+- **Mobile Menu Open**: Overlay com menu
+- **Collapsed**: Em scroll com animacao
+
+### Tokens de Design
+
+#### Cores
+- Background: `bg-background` ou `bg-background/95 backdrop-blur`
+- Text: `text-foreground`
+- Muted: `text-muted-foreground`
+- Border: `border-border`
+- Active link: `text-primary`
+
+#### Espacamento
+- Padding: `px-4 md:px-6 lg:px-8`
+- Gap entre items: `gap-4 md:gap-6`
+- Container: `max-w-7xl mx-auto`
+
+#### Tipografia
+- Brand: `text-lg font-bold` ou `text-xl font-semibold`
+- Nav links: `text-sm font-medium`
+- Active: `font-semibold text-primary`
+
+#### Z-Index
+- Navbar: `z-50`
+- Mobile menu: `z-50`
+
+### Consideracoes de Responsividade
+- **Mobile (< 768px)**: Menu hamburguer, logo centralizado ou esquerda
+- **Tablet (768px-1024px)**: Links principais, restante em menu
+- **Desktop (> 1024px)**: Navegacao completa
+
+## API
+
+### Props Sugeridas
+
+```typescript
+interface NavbarProps extends React.ComponentProps<"nav"> {
+  /** Variante visual */
+  variant?: "default" | "transparent" | "bordered" | "floating"
+  /** Tamanho/altura */
+  size?: "sm" | "md" | "lg"
+  /** Se deve ser fixo */
+  sticky?: boolean
+  /** Se deve esconder no scroll down */
+  hideOnScroll?: boolean
+  /** Container com max-width */
+  contained?: boolean
+}
+```
+
+### Subcomponentes Sugeridos
+
+#### NavbarBrand
+Area para logo/marca.
+
+```typescript
+interface NavbarBrandProps extends React.ComponentProps<"div"> {
+  href?: string
+}
+```
+
+#### NavbarContent
+Container para grupos de conteudo.
+
+```typescript
+interface NavbarContentProps extends React.ComponentProps<"div"> {
+  justify?: "start" | "center" | "end"
+}
+```
+
+#### NavbarItem
+Item individual de navegacao.
+
+```typescript
+interface NavbarItemProps extends React.ComponentProps<"div"> {
+  isActive?: boolean
+}
+```
+
+#### NavbarLink
+Link de navegacao.
+
+```typescript
+interface NavbarLinkProps extends React.ComponentProps<"a"> {
+  isActive?: boolean
+  asChild?: boolean
+}
+```
+
+#### NavbarMenuToggle
+Botao para menu mobile.
+
+```typescript
+interface NavbarMenuToggleProps extends React.ComponentProps<"button"> {
+  isOpen?: boolean
+  srLabel?: string
+}
+```
+
+#### NavbarMenu
+Container do menu mobile.
+
+```typescript
+interface NavbarMenuProps extends React.ComponentProps<"div"> {
+  isOpen?: boolean
+}
+```
+
+### Interfaces TypeScript
+
+```typescript
+import type { ComponentProps, ReactNode } from "react"
+
+export interface NavbarProps extends ComponentProps<"nav"> {
+  variant?: "default" | "transparent" | "bordered" | "floating"
+  size?: "sm" | "md" | "lg"
+  sticky?: boolean
+  hideOnScroll?: boolean
+  contained?: boolean
+  children: ReactNode
+}
+
+export interface NavbarBrandProps extends ComponentProps<"div"> {
+  href?: string
+  children: ReactNode
+}
+
+export interface NavbarContentProps extends ComponentProps<"div"> {
+  justify?: "start" | "center" | "end"
+}
+
+export interface NavbarItemProps extends ComponentProps<"div"> {
+  isActive?: boolean
+}
+
+export interface NavbarLinkProps extends ComponentProps<"a"> {
+  isActive?: boolean
+  asChild?: boolean
+}
+```
+
+### Comparacao com Referencias
+
+| Feature | ETUS | NextUI | Chakra | MUI | Mantine |
+|---------|------|--------|--------|-----|---------|
+| Variants | Sim | Sim | Nao | Nao | Nao |
+| Sticky | Sim | Sim | Sim | Sim | Sim |
+| Hide on Scroll | Sim | Sim | Nao | Sim | Nao |
+| Blur Background | Sim | Sim | Sim | Sim | Sim |
+| Mobile Menu | Sim | Sim | Sim | Sim | Sim |
+| Collapse Animation | Sim | Sim | Nao | Nao | Nao |
+
+## Acessibilidade (A11y)
+
+### Atributos ARIA
+- `role="navigation"`: Implicito em `<nav>`
+- `aria-label`: Para identificar a navegacao
+- `aria-current="page"`: Link ativo
+- `aria-expanded`: Menu mobile toggle
+
+### Navegacao por Teclado
+- `Tab`: Navega entre links
+- `Enter`: Ativa link ou toggle
+- `Escape`: Fecha menu mobile
+- Skip link para pular navegacao
+
+### Contraste e Legibilidade
+- Contraste WCAG AA
+- Focus ring visivel
+- Links ativos claramente distinguiveis
+
+### Tecnologias Assistivas
+- Navegacao principal anunciada
+- Links anunciados corretamente
+- Estado de menu mobile comunicado
+
+### Conformidade WCAG
+- **Nivel alvo**: WCAG 2.1 AA
+- **Criterios**:
+  - 1.3.1 Info and Relationships
+  - 2.1.1 Keyboard
+  - 2.4.1 Bypass Blocks
+  - 2.4.5 Multiple Ways
+
+## Exemplos
+
+### Navbar Basico
+
+```tsx
+import { Navbar, NavbarBrand, NavbarContent, NavbarLink } from "@etus/ui"
+
+function BasicNavbar() {
+  return (
+    <Navbar>
+      <NavbarBrand href="/">
+        <span className="text-xl font-bold">ETUS</span>
+      </NavbarBrand>
+      <NavbarContent>
+        <NavbarLink href="/products">Products</NavbarLink>
+        <NavbarLink href="/pricing">Pricing</NavbarLink>
+        <NavbarLink href="/about">About</NavbarLink>
+        <NavbarLink href="/contact">Contact</NavbarLink>
+      </NavbarContent>
+    </Navbar>
+  )
+}
+```
+
+### Navbar Completo com Mobile
+
+```tsx
+import { useState } from "react"
+import {
+  Navbar,
+  NavbarBrand,
+  NavbarContent,
+  NavbarLink,
+  NavbarItem,
+  NavbarMenuToggle,
+  NavbarMenu,
+} from "@etus/ui"
+import { Button } from "@etus/ui"
+import { Search, Bell, User } from "lucide-react"
+
+function CompleteNavbar() {
+  const [isMenuOpen, setIsMenuOpen] = useState(false)
+
+  const links = [
+    { href: "/features", label: "Features" },
+    { href: "/pricing", label: "Pricing" },
+    { href: "/docs", label: "Docs" },
+    { href: "/blog", label: "Blog" },
+  ]
+
+  return (
+    <Navbar sticky>
+      {/* Brand */}
+      <NavbarBrand href="/">
+        <img src="/logo.svg" alt="ETUS" className="h-8" />
+      </NavbarBrand>
+
+      {/* Desktop Links */}
+      <NavbarContent className="hidden md:flex" justify="center">
+        {links.map((link) => (
+          <NavbarLink key={link.href} href={link.href}>
+            {link.label}
+          </NavbarLink>
+        ))}
+      </NavbarContent>
+
+      {/* Actions */}
+      <NavbarContent justify="end">
+        <NavbarItem className="hidden lg:flex">
+          <Button variant="ghost" size="icon">
+            <Search className="h-5 w-5" />
+          </Button>
+        </NavbarItem>
+        <NavbarItem className="hidden md:flex">
+          <Button variant="ghost" size="icon">
+            <Bell className="h-5 w-5" />
+          </Button>
+        </NavbarItem>
+        <NavbarItem>
+          <Button variant="ghost" size="icon">
+            <User className="h-5 w-5" />
+          </Button>
+        </NavbarItem>
+        <NavbarMenuToggle
+          className="md:hidden"
+          isOpen={isMenuOpen}
+          onClick={() => setIsMenuOpen(!isMenuOpen)}
+        />
+      </NavbarContent>
+
+      {/* Mobile Menu */}
+      <NavbarMenu isOpen={isMenuOpen}>
+        <div className="flex flex-col gap-2 p-4">
+          {links.map((link) => (
+            <NavbarLink
+              key={link.href}
+              href={link.href}
+              className="text-lg"
+              onClick={() => setIsMenuOpen(false)}
+            >
+              {link.label}
+            </NavbarLink>
+          ))}
+          <hr className="my-4" />
+          <Button className="w-full">Sign In</Button>
+        </div>
+      </NavbarMenu>
+    </Navbar>
+  )
+}
+```
+
+### Navbar com Busca Expansivel
+
+```tsx
+import { useState } from "react"
+import {
+  Navbar,
+  NavbarBrand,
+  NavbarContent,
+  NavbarLink,
+  NavbarItem,
+} from "@etus/ui"
+import { Input } from "@etus/ui"
+import { Search, X } from "lucide-react"
+
+function NavbarWithSearch() {
+  const [searchOpen, setSearchOpen] = useState(false)
+  const [searchQuery, setSearchQuery] = useState("")
+
+  return (
+    <Navbar>
+      <NavbarBrand href="/">
+        <span className="text-xl font-bold">App</span>
+      </NavbarBrand>
+
+      {!searchOpen && (
+        <NavbarContent className="hidden md:flex">
+          <NavbarLink href="/explore">Explore</NavbarLink>
+          <NavbarLink href="/trending">Trending</NavbarLink>
+          <NavbarLink href="/categories">Categories</NavbarLink>
+        </NavbarContent>
+      )}
+
+      <NavbarContent justify="end">
+        {searchOpen ? (
+          <div className="flex items-center gap-2 flex-1 max-w-md">
+            <div className="relative flex-1">
+              <Search className="absolute left-3 top-1/2 -translate-y-1/2 h-4 w-4 text-muted-foreground" />
+              <Input
+                autoFocus
+                placeholder="Search..."
+                value={searchQuery}
+                onChange={(e) => setSearchQuery(e.target.value)}
+                className="pl-9"
+              />
+            </div>
+            <Button
+              variant="ghost"
+              size="icon"
+              onClick={() => {
+                setSearchOpen(false)
+                setSearchQuery("")
+              }}
+            >
+              <X className="h-5 w-5" />
+            </Button>
+          </div>
+        ) : (
+          <Button
+            variant="ghost"
+            size="icon"
+            onClick={() => setSearchOpen(true)}
+          >
+            <Search className="h-5 w-5" />
+          </Button>
+        )}
+      </NavbarContent>
+    </Navbar>
+  )
+}
+```
+
+### Navbar de Dashboard
+
+```tsx
+import {
+  Navbar,
+  NavbarBrand,
+  NavbarContent,
+  NavbarItem,
+} from "@etus/ui"
+import { Button } from "@etus/ui"
+import { Input } from "@etus/ui"
+import {
+  DropdownMenu,
+  DropdownMenuTrigger,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuSeparator,
+} from "@etus/ui"
+import { Search, Bell, Settings, User, LogOut, ChevronDown } from "lucide-react"
+
+function DashboardNavbar() {
+  return (
+    <Navbar size="md" className="border-b">
+      <NavbarBrand href="/dashboard">
+        <span className="text-lg font-semibold">Dashboard</span>
+      </NavbarBrand>
+
+      <NavbarContent className="flex-1 max-w-xl mx-8">
+        <div className="relative w-full">
+          <Search className="absolute left-3 top-1/2 -translate-y-1/2 h-4 w-4 text-muted-foreground" />
+          <Input
+            placeholder="Search anything..."
+            className="pl-9 w-full"
+          />
+          <kbd className="absolute right-3 top-1/2 -translate-y-1/2 pointer-events-none hidden sm:inline-flex h-5 select-none items-center gap-1 rounded border bg-muted px-1.5 font-mono text-[10px] font-medium text-muted-foreground">
+            <span className="text-xs">Cmd</span>K
+          </kbd>
+        </div>
+      </NavbarContent>
+
+      <NavbarContent justify="end">
+        <NavbarItem>
+          <Button variant="ghost" size="icon" className="relative">
+            <Bell className="h-5 w-5" />
+            <span className="absolute top-1 right-1 h-2 w-2 rounded-full bg-destructive" />
+          </Button>
+        </NavbarItem>
+        <NavbarItem>
+          <Button variant="ghost" size="icon">
+            <Settings className="h-5 w-5" />
+          </Button>
+        </NavbarItem>
+        <NavbarItem>
+          <DropdownMenu>
+            <DropdownMenuTrigger asChild>
+              <Button variant="ghost" className="gap-2">
+                <div className="h-8 w-8 rounded-full bg-muted flex items-center justify-center">
+                  <User className="h-4 w-4" />
+                </div>
+                <span className="hidden md:inline">John Doe</span>
+                <ChevronDown className="h-4 w-4" />
+              </Button>
+            </DropdownMenuTrigger>
+            <DropdownMenuContent align="end">
+              <DropdownMenuItem>
+                <User className="mr-2 h-4 w-4" />
+                Profile
+              </DropdownMenuItem>
+              <DropdownMenuItem>
+                <Settings className="mr-2 h-4 w-4" />
+                Settings
+              </DropdownMenuItem>
+              <DropdownMenuSeparator />
+              <DropdownMenuItem variant="destructive">
+                <LogOut className="mr-2 h-4 w-4" />
+                Logout
+              </DropdownMenuItem>
+            </DropdownMenuContent>
+          </DropdownMenu>
+        </NavbarItem>
+      </NavbarContent>
+    </Navbar>
+  )
+}
+```
+
+### Navbar com Hide on Scroll
+
+```tsx
+import { useState, useEffect } from "react"
+import { Navbar, NavbarBrand, NavbarContent, NavbarLink } from "@etus/ui"
+import { cn } from "@etus/ui"
+
+function HideOnScrollNavbar() {
+  const [isVisible, setIsVisible] = useState(true)
+  const [lastScrollY, setLastScrollY] = useState(0)
+
+  useEffect(() => {
+    const handleScroll = () => {
+      const currentScrollY = window.scrollY
+
+      if (currentScrollY > lastScrollY && currentScrollY > 100) {
+        setIsVisible(false)
+      } else {
+        setIsVisible(true)
+      }
+
+      setLastScrollY(currentScrollY)
+    }
+
+    window.addEventListener("scroll", handleScroll, { passive: true })
+    return () => window.removeEventListener("scroll", handleScroll)
+  }, [lastScrollY])
+
+  return (
+    <Navbar
+      sticky
+      className={cn(
+        "transition-transform duration-300",
+        !isVisible && "-translate-y-full"
+      )}
+    >
+      <NavbarBrand href="/">Brand</NavbarBrand>
+      <NavbarContent>
+        <NavbarLink href="/home">Home</NavbarLink>
+        <NavbarLink href="/about">About</NavbarLink>
+        <NavbarLink href="/contact">Contact</NavbarLink>
+      </NavbarContent>
+    </Navbar>
+  )
+}
+```
+
+## Testes
+
+### Estrategias de Teste
+
+#### Testes Unitarios
+- Renderizacao de subcomponentes
+- Aplicacao de variantes
+- Props funcionando
+
+#### Testes de Integracao
+- Menu mobile abre/fecha
+- Navegacao entre paginas
+- Busca funcionando
+
+#### Testes de Acessibilidade
+- Landmark de navegacao
+- Keyboard navigation
+- Mobile menu acessivel
+
+### Exemplos de Codigo
+
+```typescript
+import { describe, it, expect } from "vitest"
+import { render, screen } from "@testing-library/react"
+import userEvent from "@testing-library/user-event"
+import {
+  Navbar,
+  NavbarBrand,
+  NavbarContent,
+  NavbarLink,
+  NavbarMenuToggle,
+  NavbarMenu,
+} from "./Navbar"
+
+describe("Navbar", () => {
+  it("renders navigation landmark", () => {
+    render(
+      <Navbar>
+        <NavbarBrand>Brand</NavbarBrand>
+      </Navbar>
+    )
+
+    expect(screen.getByRole("navigation")).toBeInTheDocument()
+  })
+
+  it("renders links correctly", () => {
+    render(
+      <Navbar>
+        <NavbarContent>
+          <NavbarLink href="/home">Home</NavbarLink>
+          <NavbarLink href="/about">About</NavbarLink>
+        </NavbarContent>
+      </Navbar>
+    )
+
+    expect(screen.getByText("Home")).toBeInTheDocument()
+    expect(screen.getByText("About")).toBeInTheDocument()
+  })
+
+  it("toggles mobile menu", async () => {
+    const TestComponent = () => {
+      const [isOpen, setIsOpen] = useState(false)
+      return (
+        <Navbar>
+          <NavbarMenuToggle
+            isOpen={isOpen}
+            onClick={() => setIsOpen(!isOpen)}
+            aria-label="Toggle menu"
+          />
+          <NavbarMenu isOpen={isOpen}>
+            <span>Menu Content</span>
+          </NavbarMenu>
+        </Navbar>
+      )
+    }
+
+    render(<TestComponent />)
+
+    expect(screen.queryByText("Menu Content")).not.toBeVisible()
+
+    await userEvent.click(screen.getByLabelText("Toggle menu"))
+
+    expect(screen.getByText("Menu Content")).toBeVisible()
+  })
+
+  it("marks active link with aria-current", () => {
+    render(
+      <Navbar>
+        <NavbarContent>
+          <NavbarLink href="/home" isActive>
+            Home
+          </NavbarLink>
+        </NavbarContent>
+      </Navbar>
+    )
+
+    expect(screen.getByText("Home")).toHaveAttribute("aria-current", "page")
+  })
+})
+```
+
+---
+
+## Roadmap / Features Futuras
+
+- Usar elemento semantico `<nav>`
+- Considerar skip link para acessibilidade
+- backdrop-filter para efeito de blur
+- Transition para hide on scroll suave
+
+## Referências
+
+- [MDN: nav element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/nav)
+- [NextUI Navbar](https://nextui.org/docs/components/navbar)
+- [WAI-ARIA Navigation](https://www.w3.org/WAI/ARIA/apg/patterns/menubar/examples/menubar-navigation/)

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

@@ -0,0 +1,20 @@
+export * from './Navbar'
+export {
+  navbarBrandVariants,
+  navbarContainerVariants,
+  navbarContentVariants,
+  navbarItemVariants,
+  navbarLinkVariants,
+  navbarMenuToggleVariants,
+  navbarMenuVariants,
+  navbarVariants,
+} from './Navbar.variants'
+export type {
+  NavbarBrandProps,
+  NavbarContentProps,
+  NavbarItemProps,
+  NavbarLinkProps,
+  NavbarMenuProps,
+  NavbarMenuToggleProps,
+  NavbarProps,
+} from './Navbar.types'