npm - @etus/ui - Versions diffs - 0.1.0 → 0.1.2 - Mend

@etus/ui 0.1.0 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1080) hide show

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

@@ -1,700 +0,0 @@
-# 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 DELETED Viewed

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