@etus/ui 0.1.0

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

@@ -0,0 +1,700 @@
+# Container
+
+## Visao Geral
+
+O **Container** e o componente de layout fundamental para centralizar e limitar a largura do conteudo. Como elemento de layout, serve como wrapper para secoes de pagina, garantindo consistencia visual e legibilidade em diferentes tamanhos de tela.
+
+### Casos de Uso
+
+- Centralizar conteudo principal de uma pagina
+- Limitar largura maxima para melhor legibilidade
+- Criar layouts responsivos com padding adaptativo
+- Definir areas semanticas (main, section, article)
+- Wrapper para formularios e conteudo focado
+
+### Classificacao
+
+**Categoria:** Layout
+**Dependencias:** `class-variance-authority`
+
+---
+
+## Design Specs
+
+### Largura Maxima (`maxWidth`)
+
+| Variante | Largura | Uso |
+|----------|---------|-----|
+| `sm` | 640px (`max-w-screen-sm`) | Formularios, conteudo focado |
+| `md` | 768px (`max-w-screen-md`) | Artigos, documentacao |
+| `lg` | 1024px (`max-w-screen-lg`) | Paginas de conteudo geral |
+| `xl` | 1280px (`max-w-screen-xl`) | Dashboards, aplicacoes (padrao) |
+| `2xl` | 1536px (`max-w-screen-2xl`) | Aplicacoes wide-screen |
+| `full` | 100% (`max-w-full`) | Sem limite de largura |
+
+### Padding (`padding`)
+
+| Variante | Classes | Uso |
+|----------|---------|-----|
+| `none` | - | Sem padding |
+| `sm` | `px-4` | Padding compacto (16px) |
+| `md` | `px-4 sm:px-6 lg:px-8` | Responsivo (padrao) |
+| `lg` | `px-6 sm:px-8 lg:px-12` | Generoso |
+
+### Centralizacao (`centered`)
+
+| Valor | Classe | Comportamento |
+|-------|--------|---------------|
+| `true` | `mx-auto` | Centraliza horizontalmente (padrao) |
+| `false` | - | Alinhado a esquerda |
+
+### Elementos Suportados (`as`)
+
+| Elemento | Uso |
+|----------|-----|
+| `div` | Container generico (padrao) |
+| `main` | Conteudo principal da pagina |
+| `section` | Secao tematica |
+| `article` | Conteudo independente |
+
+### Tokens Utilizados
+
+```css
+/* Larguras (Tailwind breakpoints) */
+max-w-screen-sm   /* 640px */
+max-w-screen-md   /* 768px */
+max-w-screen-lg   /* 1024px */
+max-w-screen-xl   /* 1280px */
+max-w-screen-2xl  /* 1536px */
+max-w-full        /* 100% */
+
+/* Espacamento */
+px-4              /* 16px */
+px-6              /* 24px */
+px-8              /* 32px */
+px-12             /* 48px */
+
+/* Centralizacao */
+mx-auto           /* margin: 0 auto */
+w-full            /* width: 100% */
+```
+
+### data-slot
+
+```html
+<div data-slot="container">...</div>
+<main data-slot="container">...</main>
+<section data-slot="container">...</section>
+```
+
+---
+
+## API
+
+### Props
+
+| Prop | Tipo | Padrao | Descricao |
+|------|------|--------|-----------|
+| `maxWidth` | `"sm" \| "md" \| "lg" \| "xl" \| "2xl" \| "full"` | `"xl"` | Largura maxima do container |
+| `padding` | `"none" \| "sm" \| "md" \| "lg"` | `"md"` | Padding horizontal responsivo |
+| `centered` | `boolean` | `true` | Centraliza com mx-auto |
+| `as` | `"div" \| "main" \| "section" \| "article"` | `"div"` | Elemento HTML a renderizar |
+| `className` | `string` | - | Classes CSS adicionais |
+| `children` | `ReactNode` | - | Conteudo |
+
+> Herda todas as props de `React.ComponentProps<"div">`
+
+### Callbacks
+
+O Container e um componente puramente de layout, nao possui callbacks especificos. Todos os event handlers nativos do elemento HTML escolhido sao suportados.
+
+### TypeScript
+
+```typescript
+import type { VariantProps } from "class-variance-authority"
+
+// Elementos permitidos
+type ContainerElement = "article" | "div" | "main" | "section"
+
+// Props do componente
+interface ContainerProps
+  extends ComponentProps<"div">,
+    VariantProps<typeof containerVariants> {
+  as?: ContainerElement
+}
+
+// Tipos derivados
+type ContainerMaxWidth = "sm" | "md" | "lg" | "xl" | "2xl" | "full"
+type ContainerPadding = "none" | "sm" | "md" | "lg"
+```
+
+### Comparativo com Design Systems de Referencia
+
+#### Matriz de Features (12 Design Systems)
+
+| Feature | ETUS | Shadcn | MUI | Chakra | Mantine | AntD | NextUI | Headless | Ariakit | Fluent | Carbon | Bootstrap |
+|---------|:----:|:------:|:---:|:------:|:-------:|:----:|:------:|:--------:|:-------:|:------:|:------:|:---------:|
+| **maxWidth variants** | 6 | - | 5 | 6+ | 5 | - | - | - | - | - | - | 5 |
+| **Responsive padding** | ✓ | - | ✓ | ✓ | ✓ | - | - | - | - | ✓ | ✓ | ✓ |
+| **Centered by default** | ✓ | - | ✓ | ✓ | ✓ | - | - | - | - | - | ✓ | ✓ |
+| **Polymorphic (as)** | ✓ | - | ✓ | ✓ | ✓ | - | ✓ | ✓ | ✓ | ✓ | - | - |
+| **Fluid mode** | ✓ | - | ✓ | - | ✓ | - | - | - | - | - | ✓ | ✓ |
+| **Fixed breakpoints** | - | - | ✓ | - | - | - | - | - | - | - | - | ✓ |
+| **disableGutters** | - | - | ✓ | - | - | - | - | - | - | - | - | - |
+| **CVA/cva** | ✓ | ✓ | - | - | - | - | ✓ | - | - | - | - | - |
+| **data-slot** | ✓ | ✓ | - | - | - | - | ✓ | - | - | - | - | - |
+| **Theme customization** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | - | - | ✓ | ✓ | ✓ |
+
+#### Comparativo de Props por Design System
+
+| Prop | ETUS | MUI | Chakra | Mantine | Bootstrap |
+|------|:----:|:---:|:------:|:-------:|:---------:|
+| `maxWidth` | ✓ | ✓ | `maxW` | `size` | - |
+| `padding` | ✓ | `disableGutters` | `px` | `px` | `gx-*` |
+| `centered` | ✓ | automatico | `centerContent` | automatico | `mx-auto` |
+| `as/component` | ✓ | `component` | `as` | `component` | - |
+| `fluid` | `maxWidth="full"` | `maxWidth={false}` | `maxW="100%"` | `fluid` | `container-fluid` |
+| `fixed` | - | `fixed` | - | - | - |
+
+#### Nomenclatura de Tamanhos
+
+| ETUS | MUI | Chakra | Mantine | Bootstrap |
+|------|-----|--------|---------|-----------|
+| `sm` (640px) | `sm` (600px) | `sm` (480px) | `xs` (540px) | `sm` (540px) |
+| `md` (768px) | `md` (900px) | `md` (768px) | `sm` (720px) | `md` (720px) |
+| `lg` (1024px) | `lg` (1200px) | `lg` (992px) | `md` (960px) | `lg` (960px) |
+| `xl` (1280px) | `xl` (1536px) | `xl` (1280px) | `lg` (1140px) | `xl` (1140px) |
+| `2xl` (1536px) | - | `2xl` (1536px) | `xl` (1320px) | `xxl` (1320px) |
+
+---
+
+## Acessibilidade (A11y)
+
+### ARIA Attributes
+
+| Atributo | Uso |
+|----------|-----|
+| `role="main"` | Automatico quando `as="main"` |
+| `role="region"` | Opcional para sections com aria-label |
+| `aria-label` | Descreve secao quando necessario |
+
+### Suporte a Teclado
+
+O Container e um elemento de layout passivo, nao requer interacoes de teclado.
+
+### Focus Management
+
+O Container nao recebe foco diretamente. Elementos focaveis dentro do container seguem a ordem natural do DOM.
+
+### Contraste de Cores
+
+O Container nao possui cores proprias, apenas define layout. Os tokens de cores sao herdados do conteudo filho.
+
+### Screen Readers
+
+- Usar `as="main"` para conteudo principal (landmark)
+- Usar `as="section"` com `aria-label` para secoes
+- Usar `as="article"` para conteudo independente
+
+### Reduced Motion
+
+Nao aplicavel - Container nao possui animacoes.
+
+### Comparativo A11y (12 Design Systems)
+
+| Feature | ETUS | MUI | Chakra | Mantine | Bootstrap | Carbon |
+|---------|:----:|:---:|:------:|:-------:|:---------:|:------:|
+| **Semantic elements** | ✓ | ✓ | ✓ | ✓ | - | ✓ |
+| **Role automatico** | ✓ | - | - | - | - | ✓ |
+| **Landmark support** | ✓ | ✓ | ✓ | ✓ | - | ✓ |
+| **aria-label support** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+
+**Legenda:** ✓ = Suporte completo | ~ = Parcial/Manual | - = Nao suportado
+
+---
+
+## Exemplos
+
+### Uso Basico
+
+```tsx
+import { Container } from "@etus/ui"
+
+function Example() {
+  return (
+    <Container>
+      <h1>Conteudo centralizado</h1>
+      <p>Largura maxima de 1280px com padding responsivo.</p>
+    </Container>
+  )
+}
+```
+
+### Larguras Maximas
+
+```tsx
+// Formulario compacto
+<Container maxWidth="sm">
+  <form>...</form>
+</Container>
+
+// Artigo/Blog
+<Container maxWidth="md">
+  <article>...</article>
+</Container>
+
+// Pagina padrao
+<Container maxWidth="xl">
+  <main>...</main>
+</Container>
+
+// Full width
+<Container maxWidth="full">
+  <div>Sem limite de largura</div>
+</Container>
+```
+
+### Opcoes de Padding
+
+```tsx
+// Sem padding
+<Container padding="none">
+  <div>Edge-to-edge dentro do container</div>
+</Container>
+
+// Padding compacto
+<Container padding="sm">
+  <div>16px de padding horizontal</div>
+</Container>
+
+// Padding responsivo (padrao)
+<Container padding="md">
+  <div>16px mobile, 24px tablet, 32px desktop</div>
+</Container>
+
+// Padding generoso
+<Container padding="lg">
+  <div>24px mobile, 32px tablet, 48px desktop</div>
+</Container>
+```
+
+### Elementos Semanticos
+
+```tsx
+// Conteudo principal da pagina
+<Container as="main">
+  <h1>Titulo da Pagina</h1>
+  <p>Conteudo principal...</p>
+</Container>
+
+// Secao tematica
+<Container as="section" aria-label="Recursos">
+  <h2>Recursos</h2>
+  <p>Descricao dos recursos...</p>
+</Container>
+
+// Artigo independente
+<Container as="article">
+  <h2>Titulo do Artigo</h2>
+  <p>Conteudo do artigo...</p>
+</Container>
+```
+
+### Sem Centralizacao
+
+```tsx
+// Alinhado a esquerda
+<Container centered={false} maxWidth="md">
+  <div>Conteudo alinhado a esquerda</div>
+</Container>
+```
+
+### Responsividade
+
+```tsx
+// Container com width customizado via className
+<Container className="max-w-4xl">
+  <div>Largura customizada</div>
+</Container>
+
+// Container com background
+<Container className="bg-muted rounded-lg py-8">
+  <div>Container com estilo adicional</div>
+</Container>
+```
+
+### Layout de Pagina Completo
+
+```tsx
+function PageLayout() {
+  return (
+    <>
+      {/* Hero full-width */}
+      <Container maxWidth="full" padding="none" as="section">
+        <div className="bg-primary text-primary-foreground py-20">
+          <Container maxWidth="xl">
+            <h1>Hero Section</h1>
+          </Container>
+        </div>
+      </Container>
+
+      {/* Conteudo principal */}
+      <Container as="main" maxWidth="lg" className="py-12">
+        <h2>Conteudo</h2>
+        <p>...</p>
+      </Container>
+
+      {/* Footer full-width */}
+      <Container as="section" maxWidth="full" padding="none">
+        <footer className="bg-muted py-8">
+          <Container maxWidth="xl">
+            <p>Footer content</p>
+          </Container>
+        </footer>
+      </Container>
+    </>
+  )
+}
+```
+
+### Composicao com Card
+
+```tsx
+import { Container, Card, CardContent, CardHeader } from "@etus/ui"
+
+function Dashboard() {
+  return (
+    <Container maxWidth="xl" as="main">
+      <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
+        <Card>
+          <CardHeader>Widget 1</CardHeader>
+          <CardContent>...</CardContent>
+        </Card>
+        <Card>
+          <CardHeader>Widget 2</CardHeader>
+          <CardContent>...</CardContent>
+        </Card>
+        <Card>
+          <CardHeader>Widget 3</CardHeader>
+          <CardContent>...</CardContent>
+        </Card>
+      </div>
+    </Container>
+  )
+}
+```
+
+### Formulario Centralizado
+
+```tsx
+import { Container, Card, CardContent } from "@etus/ui"
+
+function LoginPage() {
+  return (
+    <Container maxWidth="sm" className="py-20">
+      <Card>
+        <CardContent className="p-6">
+          <h1 className="text-2xl font-bold mb-6">Login</h1>
+          <form>
+            {/* campos do formulario */}
+          </form>
+        </CardContent>
+      </Card>
+    </Container>
+  )
+}
+```
+
+---
+
+## Testes
+
+### Testes Unitarios
+
+```tsx
+// Container.test.tsx
+import { render, screen } from "@testing-library/react"
+import { describe, expect, it } from "vitest"
+import { Container } from "./Container"
+
+describe("Container", () => {
+  it("renders children correctly", () => {
+    render(<Container>Container Content</Container>)
+    expect(screen.getByText("Container Content")).toBeInTheDocument()
+  })
+
+  it("applies maxWidth variant classes", () => {
+    render(<Container data-testid="container" maxWidth="lg">Content</Container>)
+    expect(screen.getByTestId("container")).toHaveClass("max-w-screen-lg")
+  })
+
+  it("applies default maxWidth (xl)", () => {
+    render(<Container data-testid="container">Content</Container>)
+    expect(screen.getByTestId("container")).toHaveClass("max-w-screen-xl")
+  })
+
+  it("has data-slot attribute", () => {
+    render(<Container data-testid="container">Content</Container>)
+    expect(screen.getByTestId("container")).toHaveAttribute("data-slot", "container")
+  })
+})
+```
+
+### Testes de Variantes
+
+```tsx
+describe("Container variants", () => {
+  it.each(["sm", "md", "lg", "xl", "2xl"] as const)(
+    "applies %s maxWidth correctly",
+    (size) => {
+      render(<Container data-testid="container" maxWidth={size}>Content</Container>)
+      expect(screen.getByTestId("container")).toHaveClass(`max-w-screen-${size}`)
+    }
+  )
+
+  it("applies full maxWidth", () => {
+    render(<Container data-testid="container" maxWidth="full">Content</Container>)
+    expect(screen.getByTestId("container")).toHaveClass("max-w-full")
+  })
+
+  it("applies centered by default", () => {
+    render(<Container data-testid="container">Content</Container>)
+    expect(screen.getByTestId("container")).toHaveClass("mx-auto")
+  })
+
+  it("removes centering when centered=false", () => {
+    render(<Container data-testid="container" centered={false}>Content</Container>)
+    expect(screen.getByTestId("container")).not.toHaveClass("mx-auto")
+  })
+})
+```
+
+### Testes Polimorficos
+
+```tsx
+describe("Container polymorphic as prop", () => {
+  it("renders as div by default", () => {
+    render(<Container data-testid="container">Content</Container>)
+    expect(screen.getByTestId("container").tagName).toBe("DIV")
+  })
+
+  it("renders as main element", () => {
+    render(<Container as="main" data-testid="container">Content</Container>)
+    expect(screen.getByTestId("container").tagName).toBe("MAIN")
+  })
+
+  it("renders as section element", () => {
+    render(<Container as="section" data-testid="container">Content</Container>)
+    expect(screen.getByTestId("container").tagName).toBe("SECTION")
+  })
+
+  it("renders as article element", () => {
+    render(<Container as="article" data-testid="container">Content</Container>)
+    expect(screen.getByTestId("container").tagName).toBe("ARTICLE")
+  })
+})
+```
+
+### Testes de Acessibilidade
+
+```tsx
+import { axe, toHaveNoViolations } from "jest-axe"
+
+expect.extend(toHaveNoViolations)
+
+describe("Container accessibility", () => {
+  it("has no accessibility violations", async () => {
+    const { container } = render(<Container>Content</Container>)
+    const results = await axe(container)
+    expect(results).toHaveNoViolations()
+  })
+
+  it("has no violations with all maxWidth variants", async () => {
+    const { container } = render(
+      <div>
+        <Container maxWidth="sm">Small</Container>
+        <Container maxWidth="md">Medium</Container>
+        <Container maxWidth="lg">Large</Container>
+        <Container maxWidth="xl">Extra Large</Container>
+        <Container maxWidth="2xl">2XL</Container>
+        <Container maxWidth="full">Full</Container>
+      </div>
+    )
+    const results = await axe(container)
+    expect(results).toHaveNoViolations()
+  })
+
+  it("has no violations when used as main landmark", async () => {
+    const { container } = render(
+      <Container as="main">
+        <h1>Page Title</h1>
+        <p>Page content</p>
+      </Container>
+    )
+    const results = await axe(container)
+    expect(results).toHaveNoViolations()
+  })
+
+  it("has no violations when used as article", async () => {
+    const { container } = render(
+      <Container as="article">
+        <h2>Article Title</h2>
+        <p>Article content</p>
+      </Container>
+    )
+    const results = await axe(container)
+    expect(results).toHaveNoViolations()
+  })
+})
+```
+
+### Testes de Merge de Classes
+
+```tsx
+describe("Container className merge", () => {
+  it("merges custom className with variant classes", () => {
+    render(
+      <Container className="bg-red-500" data-testid="container" maxWidth="lg">
+        Content
+      </Container>
+    )
+    const container = screen.getByTestId("container")
+    expect(container).toHaveClass("bg-red-500", "max-w-screen-lg")
+  })
+
+  it("allows overriding width classes", () => {
+    render(
+      <Container className="max-w-md" data-testid="container" maxWidth="full">
+        Content
+      </Container>
+    )
+    expect(screen.getByTestId("container")).toHaveClass("max-w-md")
+  })
+})
+```
+
+---
+
+## Roadmap / Features Futuras
+
+Baseado na analise comparativa com design systems de referencia, as seguintes features sao candidatas para implementacao futura:
+
+### Prioridade Alta
+
+#### Responsive `maxWidth`
+
+Permitir diferentes maxWidth por breakpoint.
+
+```tsx
+// Proposta de API
+<Container maxWidth={{ base: "full", md: "lg", xl: "2xl" }}>
+  Content
+</Container>
+```
+
+**Referencias:** MUI (fixed), Mantine (via classNames), Bootstrap (breakpoint containers)
+
+### Prioridade Media
+
+#### `disableGutters`
+
+Remover padding mantendo maxWidth.
+
+```tsx
+// Proposta de API
+<Container disableGutters maxWidth="xl">
+  Edge-to-edge content
+</Container>
+
+// Equivalente atual
+<Container padding="none" maxWidth="xl">
+  Edge-to-edge content
+</Container>
+```
+
+**Referencias:** [MUI Container](https://mui.com/material-ui/react-container/) (`disableGutters`)
+
+#### `fixed`
+
+MaxWidth fixo baseado no breakpoint minimo.
+
+```tsx
+// Proposta de API
+<Container fixed>
+  Width jumps at breakpoints instead of fluid
+</Container>
+```
+
+**Referencias:** [MUI Container](https://mui.com/material-ui/api/container/) (`fixed`), Bootstrap (`.container` vs `.container-fluid`)
+
+### Prioridade Baixa
+
+#### Vertical Padding
+
+Adicionar variantes de padding vertical.
+
+```tsx
+// Proposta de API
+<Container paddingY="lg">
+  Content with vertical padding
+</Container>
+```
+
+**Referencias:** Common pattern em varios DS
+
+#### Named Sizes
+
+Aliases semanticos para maxWidth.
+
+```tsx
+// Proposta de API
+<Container size="prose">  {/* 65ch para leitura */}
+  Long-form content
+</Container>
+
+<Container size="dashboard">  {/* xl */}
+  Dashboard content
+</Container>
+```
+
+**Referencias:** [Chakra UI Container](https://chakra-ui.com/docs/components/container) (size tokens), [Mantine Container](https://mantine.dev/core/container/) (custom sizes)
+
+### Decisoes de Design
+
+| Feature | Recomendacao | Justificativa |
+|---------|--------------|---------------|
+| Responsive maxWidth | Avaliar | Complexidade, usar className |
+| `disableGutters` | Evitar | `padding="none"` cobre o caso |
+| `fixed` | Evitar | Raramente necessario |
+| Vertical padding | Evitar | Usar className ou Stack |
+| Named sizes | Avaliar | Pode melhorar DX |
+
+---
+
+## Referencias
+
+### Design Systems Analisados
+
+| Design System | Documentacao Container | GitHub |
+|---------------|------------------------|--------|
+| **MUI** | [Container](https://mui.com/material-ui/react-container/) | [mui/material-ui](https://github.com/mui/material-ui) |
+| **Chakra UI** | [Container](https://chakra-ui.com/docs/components/container) | [chakra-ui/chakra-ui](https://github.com/chakra-ui/chakra-ui) |
+| **Mantine** | [Container](https://mantine.dev/core/container/) | [mantinedev/mantine](https://github.com/mantinedev/mantine) |
+| **Bootstrap** | [Container](https://getbootstrap.com/docs/5.3/layout/containers/) | [twbs/bootstrap](https://github.com/twbs/bootstrap) |
+| **Carbon** | [Grid](https://carbondesignsystem.com/components/grid/usage/) | [carbon-design-system/carbon](https://github.com/carbon-design-system/carbon) |
+| **Fluent UI** | - | [microsoft/fluentui](https://github.com/microsoft/fluentui) |
+| **NextUI** | - | [nextui-org/nextui](https://github.com/nextui-org/nextui) |
+| **Tailwind UI** | [Container](https://tailwindui.com/components/application-ui/layout/containers) | - |
+
+### Especificacoes e Padroes
+
+- [CSS Box Model - MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Box_Model)
+- [CSS Containment - MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Containment)
+- [Responsive Web Design - MDN](https://developer.mozilla.org/en-US/docs/Learn/CSS/CSS_layout/Responsive_Design)
+- [WCAG 2.1 - Reflow](https://www.w3.org/WAI/WCAG21/Understanding/reflow.html)
+
+### Ferramentas Utilizadas
+
+- [CVA - Class Variance Authority](https://cva.style/docs)
+- [Tailwind CSS](https://tailwindcss.com/docs)
+- [Tailwind CSS Breakpoints](https://tailwindcss.com/docs/responsive-design)

package/src/components/layout/Container/index.ts

@@ -0,0 +1,3 @@
+export * from './Container'
+export type * from './Container.types'
+export * from './Container.variants'