@etus/ui 0.1.0

package/src/components/layout/ResponsiveContainer/README.md

@@ -0,0 +1,267 @@
+# ResponsiveContainer
+
+## Visão Geral
+
+O **ResponsiveContainer** é um componente de layout que gerencia responsividade automática baseada em breakpoints, ajustando layout, visibilidade e comportamento de componentes filhos. É ideal para criar interfaces que se adaptam perfeitamente a diferentes tamanhos de tela, desde mobile até desktop.
+
+### Casos de Uso
+
+- Layouts responsivos gerais
+- Navegação adaptativa (mobile menu vs desktop)
+- Grids que se reconfiguram por tamanho
+- Mostrar/esconder conteúdo por breakpoint
+- Layouts que adaptam coluna vs linha
+- Gerenciamento de espaçamento responsivo
+
+### Classificação
+
+**Categoria:** Layout
+**Dependências:** React, Tailwind CSS, Container Queries
+
+---
+
+## Design Specs
+
+### Variantes (`variant`)
+
+| Variante | Uso | Tokens |
+|----------|-----|--------|
+| `default` | Container responsivo padrão | `w-full mx-auto` |
+| `fluid` | Sem limite de largura | `w-full` |
+| `constrained` | Largura máxima limitada | `max-w-7xl` |
+
+### Tamanhos Suportados
+
+| Breakpoint | Largura | Uso |
+|-----------|---------|-----|
+| `xs` | 320px | Celular pequeno |
+| `sm` | 640px | Celular |
+| `md` | 768px | Tablet |
+| `lg` | 1024px | Desktop |
+| `xl` | 1280px | Desktop grande |
+| `2xl` | 1536px | Ultra-wide |
+
+### Estados
+
+| Estado | Classes/Atributos | Comportamento |
+|--------|-------------------|---------------|
+| Mobile | `md:hidden` | Esconde conteúdo em desktop |
+| Tablet | `hidden md:block lg:hidden` | Visível apenas em tablet |
+| Desktop | `hidden lg:block` | Visível apenas em desktop |
+| Print | `print:block` | Visível ao imprimir |
+
+### Tokens Utilizados
+
+```css
+/* Larguras */
+w-full
+max-w-4xl
+max-w-6xl
+max-w-7xl
+
+/* Espaçamento */
+mx-auto
+px-4
+md:px-6
+lg:px-8
+
+/* Tipografia */
+text-sm
+md:text-base
+
+/* Responsividade */
+flex-col
+md:flex-row
+```
+
+### data-slot
+
+```html
+<div data-slot="responsive-container">
+  <div data-slot="container-content">...</div>
+</div>
+```
+
+---
+
+## API
+
+### Props
+
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `variant` | `"default" \| "fluid" \| "constrained"` | `"default"` | Estilo visual |
+| `maxWidth` | `"sm" \| "md" \| "lg" \| "xl" \| "2xl"` | `"lg"` | Largura máxima |
+| `padding` | `boolean` | `true` | Adiciona padding responsivo |
+| `breakpoint` | `"sm" \| "md" \| "lg"` | `"md"` | Breakpoint para layout |
+| `className` | `string` | - | Classes CSS adicionais |
+| `children` | `ReactNode` | - | Conteúdo |
+| `ref` | `Ref<HTMLDivElement>` | - | Referência ao elemento DOM |
+
+> Herda todas as props de `React.ComponentProps<"div">`
+
+### TypeScript
+
+```typescript
+import { type VariantProps } from "class-variance-authority"
+
+type ResponsiveContainerProps = React.ComponentProps<"div"> &
+  VariantProps<typeof responsiveContainerVariants> & {
+    maxWidth?: "sm" | "md" | "lg" | "xl" | "2xl"
+    padding?: boolean
+    breakpoint?: "sm" | "md" | "lg"
+  }
+```
+
+---
+
+## Acessibilidade (A11y)
+
+### Considerações
+
+- Ordem de leitura deve ser lógica em mobile e desktop
+- Usar `display: none` com `aria-hidden` se conteúdo não for acessível
+- Testar navegação por teclado em todos os breakpoints
+- Garantir contraste em todos os tamanhos de tela
+
+### Screen Readers
+
+Conteúdo escondido via `display: none` é naturalmente ocultado de screen readers. Se conteúdo diferente é exibido por breakpoint, testá-lo com leitores de tela.
+
+---
+
+## Exemplos
+
+### Layout Responsivo Básico
+
+```tsx
+import { ResponsiveContainer } from "@etus/ui"
+
+function Example() {
+  return (
+    <ResponsiveContainer>
+      <h1>Conteúdo responsivo</h1>
+      <p>Este container se adapta a diferentes tamanhos</p>
+    </ResponsiveContainer>
+  )
+}
+```
+
+### Com Diferentes Conteúdos por Tamanho
+
+```tsx
+import { ResponsiveContainer } from "@etus/ui"
+
+function Example() {
+  return (
+    <ResponsiveContainer>
+      {/* Mobile */}
+      <div className="md:hidden">
+        <MobileMenu />
+      </div>
+
+      {/* Desktop */}
+      <div className="hidden md:block">
+        <DesktopMenu />
+      </div>
+    </ResponsiveContainer>
+  )
+}
+```
+
+### Com Padding Responsivo
+
+```tsx
+import { ResponsiveContainer } from "@etus/ui"
+
+function Example() {
+  return (
+    <ResponsiveContainer padding maxWidth="lg">
+      <article>Artigo com padding responsivo</article>
+    </ResponsiveContainer>
+  )
+}
+```
+
+---
+
+## Testes
+
+### Testes Unitários
+
+```tsx
+import { render } from "@testing-library/react"
+import { describe, expect, it } from "vitest"
+import { ResponsiveContainer } from "./ResponsiveContainer"
+
+describe("ResponsiveContainer", () => {
+  it("renders children correctly", () => {
+    const { getByText } = render(
+      <ResponsiveContainer>Conteúdo</ResponsiveContainer>
+    )
+    expect(getByText("Conteúdo")).toBeInTheDocument()
+  })
+
+  it("applies max-width correctly", () => {
+    const { container } = render(
+      <ResponsiveContainer maxWidth="lg" />
+    )
+    expect(container.firstChild).toHaveClass("max-w-4xl")
+  })
+
+  it("has data-slot attribute", () => {
+    const { container } = render(<ResponsiveContainer />)
+    expect(
+      container.querySelector("[data-slot='responsive-container']")
+    ).toBeInTheDocument()
+  })
+})
+```
+
+---
+
+## Roadmap / Features Futuras
+
+### Prioridade Alta
+
+- [ ] Container queries (ao invés de media queries)
+- [ ] Presets de layout comuns
+- [ ] Detecção de viewport e adaptive rendering
+- [ ] Temas responsivos
+
+### Prioridade Média
+
+- [ ] Hooks para obter breakpoint atual
+- [ ] Diferentes padding por breakpoint
+- [ ] Gutter/gap responsivo
+- [ ] Layouts com safe area (notch, etc)
+
+### Prioridade Baixa
+
+- [ ] Suporte para modo paisagem
+- [ ] Otimizações de performance
+- [ ] Fallbacks para navegadores antigos
+- [ ] Integração com media query listeners
+
+---
+
+## Referências
+
+### Design Systems Analisados
+
+| Design System | Documentação | GitHub |
+|---------------|--------------|--------|
+| **Shadcn/ui** | [Container](https://tailwindcss.com/docs/container) | [shadcn-ui/ui](https://github.com/shadcn-ui/ui) |
+| **Chakra UI** | [Box Responsive](https://chakra-ui.com/docs/styled-system/responsive-styles) | [chakra-ui/chakra-ui](https://github.com/chakra-ui/chakra-ui) |
+| **Tailwind CSS** | [Responsive Design](https://tailwindcss.com/docs/responsive-design) | [tailwindlabs/tailwindcss](https://github.com/tailwindlabs/tailwindcss) |
+
+### Especificações e Padrões
+
+- [CSS Container Queries](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Container_Queries)
+- [CSS Media Queries](https://developer.mozilla.org/en-US/docs/Web/CSS/Media_Queries)
+- [WCAG 2.1 - Responsive Design](https://www.w3.org/WAI/WCAG21/quickref/)
+
+### Ferramentas Utilizadas
+
+- [Tailwind CSS](https://tailwindcss.com/docs)
+- [CVA - Class Variance Authority](https://cva.style/docs)

package/src/components/layout/ResponsiveContainer/ResponsiveContainer.test.tsx

@@ -0,0 +1,386 @@
+// ResponsiveContainer/ResponsiveContainer.test.tsx
+import { render, screen } from "@testing-library/react"
+import { axe, toHaveNoViolations } from "jest-axe"
+import { describe, expect, it } from "vitest"
+
+import { ResponsiveContainer } from "./ResponsiveContainer"
+
+expect.extend(toHaveNoViolations)
+
+// ============================================
+// RENDERING TESTS
+// ============================================
+describe("ResponsiveContainer", () => {
+  describe("Rendering", () => {
+    it("renders children correctly", () => {
+      render(<ResponsiveContainer>Container Content</ResponsiveContainer>)
+      expect(screen.getByText("Container Content")).toBeInTheDocument()
+    })
+
+    it("renders with custom className", () => {
+      render(
+        <ResponsiveContainer className="custom-class">Content</ResponsiveContainer>
+      )
+      expect(screen.getByText("Content")).toHaveClass("custom-class")
+    })
+
+    it("has data-slot attribute", () => {
+      render(
+        <ResponsiveContainer data-testid="container">Content</ResponsiveContainer>
+      )
+      expect(screen.getByTestId("container")).toHaveAttribute(
+        "data-slot",
+        "responsive-container"
+      )
+    })
+
+    it("passes through data-* attributes", () => {
+      render(
+        <ResponsiveContainer data-custom="value" data-testid="test-container">
+          Content
+        </ResponsiveContainer>
+      )
+      expect(screen.getByTestId("test-container")).toHaveAttribute(
+        "data-custom",
+        "value"
+      )
+    })
+  })
+
+  // ============================================
+  // POLYMORPHIC "AS" PROP TESTS
+  // ============================================
+  describe("Polymorphic as prop", () => {
+    it("renders as div by default", () => {
+      render(
+        <ResponsiveContainer data-testid="container">Content</ResponsiveContainer>
+      )
+      expect(screen.getByTestId("container").tagName).toBe("DIV")
+    })
+
+    it("renders as main element", () => {
+      render(
+        <ResponsiveContainer as="main" data-testid="container">
+          Content
+        </ResponsiveContainer>
+      )
+      expect(screen.getByTestId("container").tagName).toBe("MAIN")
+    })
+
+    it("renders as section element", () => {
+      render(
+        <ResponsiveContainer as="section" data-testid="container">
+          Content
+        </ResponsiveContainer>
+      )
+      expect(screen.getByTestId("container").tagName).toBe("SECTION")
+    })
+
+    it("renders as article element", () => {
+      render(
+        <ResponsiveContainer as="article" data-testid="container">
+          Content
+        </ResponsiveContainer>
+      )
+      expect(screen.getByTestId("container").tagName).toBe("ARTICLE")
+    })
+
+    it("renders as aside element", () => {
+      render(
+        <ResponsiveContainer as="aside" data-testid="container">
+          Content
+        </ResponsiveContainer>
+      )
+      expect(screen.getByTestId("container").tagName).toBe("ASIDE")
+    })
+  })
+
+  // ============================================
+  // VARIANT STYLE TESTS
+  // ============================================
+  describe("Variant Styles", () => {
+    it("applies default variant with mx-auto", () => {
+      render(
+        <ResponsiveContainer data-testid="container" variant="default">
+          Content
+        </ResponsiveContainer>
+      )
+      expect(screen.getByTestId("container")).toHaveClass("mx-auto")
+    })
+
+    it("applies fluid variant without centering", () => {
+      render(
+        <ResponsiveContainer data-testid="container" variant="fluid">
+          Content
+        </ResponsiveContainer>
+      )
+      const container = screen.getByTestId("container")
+      expect(container).toHaveClass("max-w-none")
+    })
+
+    it("applies constrained variant with mx-auto", () => {
+      render(
+        <ResponsiveContainer data-testid="container" variant="constrained">
+          Content
+        </ResponsiveContainer>
+      )
+      const container = screen.getByTestId("container")
+      expect(container).toHaveClass("mx-auto")
+    })
+  })
+
+  // ============================================
+  // MAX WIDTH VARIANT TESTS
+  // ============================================
+  describe("MaxWidth Variants", () => {
+    it("applies sm maxWidth", () => {
+      render(
+        <ResponsiveContainer data-testid="container" maxWidth="sm">
+          Content
+        </ResponsiveContainer>
+      )
+      expect(screen.getByTestId("container")).toHaveClass("max-w-4xl")
+    })
+
+    it("applies md maxWidth", () => {
+      render(
+        <ResponsiveContainer data-testid="container" maxWidth="md">
+          Content
+        </ResponsiveContainer>
+      )
+      expect(screen.getByTestId("container")).toHaveClass("max-w-5xl")
+    })
+
+    it("applies lg maxWidth (default)", () => {
+      render(
+        <ResponsiveContainer data-testid="container">Content</ResponsiveContainer>
+      )
+      expect(screen.getByTestId("container")).toHaveClass("max-w-6xl")
+    })
+
+    it("applies xl maxWidth", () => {
+      render(
+        <ResponsiveContainer data-testid="container" maxWidth="xl">
+          Content
+        </ResponsiveContainer>
+      )
+      expect(screen.getByTestId("container")).toHaveClass("max-w-7xl")
+    })
+
+    it("applies 2xl maxWidth", () => {
+      render(
+        <ResponsiveContainer data-testid="container" maxWidth="2xl">
+          Content
+        </ResponsiveContainer>
+      )
+      expect(screen.getByTestId("container")).toHaveClass("max-w-screen-2xl")
+    })
+  })
+
+  // ============================================
+  // PADDING VARIANT TESTS
+  // ============================================
+  describe("Padding Variants", () => {
+    it("applies responsive padding by default (padding=true)", () => {
+      render(
+        <ResponsiveContainer data-testid="container">Content</ResponsiveContainer>
+      )
+      expect(screen.getByTestId("container")).toHaveClass("px-4")
+    })
+
+    it("does not apply padding when padding=false", () => {
+      render(
+        <ResponsiveContainer data-testid="container" padding={false}>
+          Content
+        </ResponsiveContainer>
+      )
+      const container = screen.getByTestId("container")
+      expect(container).not.toHaveClass("px-4")
+      expect(container).not.toHaveClass("px-6")
+      expect(container).not.toHaveClass("px-8")
+    })
+  })
+
+  // ============================================
+  // BREAKPOINT VARIANT TESTS
+  // ============================================
+  describe("Breakpoint Variants", () => {
+    it("applies no breakpoint by default", () => {
+      render(
+        <ResponsiveContainer data-testid="container">Content</ResponsiveContainer>
+      )
+      const container = screen.getByTestId("container")
+      expect(container).not.toHaveClass("flex")
+      expect(container).not.toHaveClass("flex-col")
+    })
+
+    it("applies sm breakpoint flex layout", () => {
+      render(
+        <ResponsiveContainer breakpoint="sm" data-testid="container">
+          Content
+        </ResponsiveContainer>
+      )
+      const container = screen.getByTestId("container")
+      expect(container).toHaveClass("flex", "flex-col")
+    })
+
+    it("applies md breakpoint flex layout", () => {
+      render(
+        <ResponsiveContainer breakpoint="md" data-testid="container">
+          Content
+        </ResponsiveContainer>
+      )
+      const container = screen.getByTestId("container")
+      expect(container).toHaveClass("flex", "flex-col")
+    })
+
+    it("applies lg breakpoint flex layout", () => {
+      render(
+        <ResponsiveContainer breakpoint="lg" data-testid="container">
+          Content
+        </ResponsiveContainer>
+      )
+      const container = screen.getByTestId("container")
+      expect(container).toHaveClass("flex", "flex-col")
+    })
+
+    it("no flex layout when breakpoint=none", () => {
+      render(
+        <ResponsiveContainer breakpoint="none" data-testid="container">
+          Content
+        </ResponsiveContainer>
+      )
+      const container = screen.getByTestId("container")
+      expect(container).not.toHaveClass("flex")
+    })
+  })
+
+  // ============================================
+  // COMPOUND VARIANTS TESTS
+  // ============================================
+  describe("Compound Variants", () => {
+    it("fluid variant ignores maxWidth and applies max-w-none", () => {
+      render(
+        <ResponsiveContainer
+          data-testid="container"
+          maxWidth="sm"
+          variant="fluid"
+        >
+          Content
+        </ResponsiveContainer>
+      )
+      const container = screen.getByTestId("container")
+      expect(container).toHaveClass("max-w-none")
+    })
+
+    it("constrained variant respects maxWidth prop", () => {
+      render(
+        <ResponsiveContainer
+          data-testid="container"
+          maxWidth="sm"
+          variant="constrained"
+        >
+          Content
+        </ResponsiveContainer>
+      )
+      const container = screen.getByTestId("container")
+      // maxWidth prop still applies with constrained variant
+      expect(container).toHaveClass("max-w-4xl")
+      expect(container).toHaveClass("mx-auto")
+    })
+  })
+
+  // ============================================
+  // CLASSNAME MERGE TESTS
+  // ============================================
+  describe("ClassName Merge", () => {
+    it("merges custom className with variant classes", () => {
+      render(
+        <ResponsiveContainer
+          className="bg-blue-500"
+          data-testid="container"
+          maxWidth="lg"
+        >
+          Content
+        </ResponsiveContainer>
+      )
+      const container = screen.getByTestId("container")
+      expect(container).toHaveClass("bg-blue-500", "max-w-6xl")
+    })
+
+    it("allows adding additional flex utilities", () => {
+      render(
+        <ResponsiveContainer
+          breakpoint="md"
+          className="gap-4"
+          data-testid="container"
+        >
+          Content
+        </ResponsiveContainer>
+      )
+      const container = screen.getByTestId("container")
+      expect(container).toHaveClass("flex", "gap-4")
+    })
+  })
+
+  // ============================================
+  // ACCESSIBILITY TESTS
+  // ============================================
+  describe("Accessibility", () => {
+    it("has no accessibility violations", async () => {
+      const { container } = render(
+        <ResponsiveContainer>Content</ResponsiveContainer>
+      )
+      const results = await axe(container)
+      expect(results).toHaveNoViolations()
+    })
+
+    it("has no violations with all variant combinations", async () => {
+      const { container } = render(
+        <div>
+          <ResponsiveContainer variant="default">Default</ResponsiveContainer>
+          <ResponsiveContainer variant="fluid">Fluid</ResponsiveContainer>
+          <ResponsiveContainer variant="constrained">
+            Constrained
+          </ResponsiveContainer>
+        </div>
+      )
+      const results = await axe(container)
+      expect(results).toHaveNoViolations()
+    })
+
+    it("has no violations when used as main landmark", async () => {
+      const { container } = render(
+        <ResponsiveContainer as="main">
+          <h1>Page Title</h1>
+          <p>Page content</p>
+        </ResponsiveContainer>
+      )
+      const results = await axe(container)
+      expect(results).toHaveNoViolations()
+    })
+
+    it("has no violations with breakpoint responsive layout", async () => {
+      const { container } = render(
+        <ResponsiveContainer as="section" breakpoint="md">
+          <aside>Sidebar</aside>
+          <main>Main content</main>
+        </ResponsiveContainer>
+      )
+      const results = await axe(container)
+      expect(results).toHaveNoViolations()
+    })
+  })
+
+  // ============================================
+  // BASE CLASS TESTS
+  // ============================================
+  describe("Base Classes", () => {
+    it("always has w-full class", () => {
+      render(
+        <ResponsiveContainer data-testid="container">Content</ResponsiveContainer>
+      )
+      expect(screen.getByTestId("container")).toHaveClass("w-full")
+    })
+  })
+})

package/src/components/layout/ResponsiveContainer/ResponsiveContainer.tsx

@@ -0,0 +1,54 @@
+import type { ResponsiveContainerProps } from "./ResponsiveContainer.types"
+
+import * as React from "react"
+
+import { cn } from "../../../lib/utils"
+import { responsiveContainerVariants } from "./ResponsiveContainer.variants"
+
+/**
+ * ResponsiveContainer
+ *
+ * A layout component that manages responsive behavior across breakpoints,
+ * adjusting layout, width constraints, and padding automatically.
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * <ResponsiveContainer>
+ *   <Content />
+ * </ResponsiveContainer>
+ *
+ * // With responsive layout direction
+ * <ResponsiveContainer breakpoint="md">
+ *   <Sidebar />
+ *   <MainContent />
+ * </ResponsiveContainer>
+ *
+ * // Constrained width without padding
+ * <ResponsiveContainer variant="constrained" padding={false}>
+ *   <Article />
+ * </ResponsiveContainer>
+ * ```
+ */
+function ResponsiveContainer({
+  as: Component = "div",
+  variant,
+  maxWidth,
+  padding,
+  breakpoint,
+  className,
+  ...props
+}: ResponsiveContainerProps) {
+  return (
+    <Component
+      className={cn(
+        responsiveContainerVariants({ variant, maxWidth, padding, breakpoint }),
+        className
+      )}
+      data-slot="responsive-container"
+      {...props}
+    />
+  )
+}
+
+export { ResponsiveContainer }