@darksnow-ui/page-structure

Um componente React modular e inteligente para estruturação de páginas com layout flexível, responsivo e altamente customizável.

Instalação

npm install @darksnow-ui/page-structure
# ou
pnpm add @darksnow-ui/page-structure

Uso Básico

import { PageStructure } from "@darksnow-ui/page-structure"

function App() {
  return (
    <PageStructure
      header={<Header />}
      footer={<Footer />}
      asideLeft={<Sidebar />}
    >
      <h1>Conteúdo Principal</h1>
      <p>Seu conteúdo aqui...</p>
    </PageStructure>
  )
}

Props

Conteúdo e Seções

| Prop | Tipo | Descrição | | ------------ | ----------- | ------------------------------------------ | | children | ReactNode | Conteúdo principal da página (obrigatório) | | header | ReactNode | Componente do cabeçalho | | footer | ReactNode | Componente do rodapé | | asideLeft | ReactNode | Sidebar esquerda | | asideRight | ReactNode | Sidebar direita |

Classes CSS Customizadas

| Prop | Tipo | Descrição | | --------------------- | -------- | ---------------------------------- | | className | string | Classes para o container principal | | contentClassName | string | Classes para a área de conteúdo | | headerClassName | string | Classes para o header | | footerClassName | string | Classes para o footer | | asideLeftClassName | string | Classes para sidebar esquerda | | asideRightClassName | string | Classes para sidebar direita |

Controle de Layout

| Prop | Tipo | Default | Descrição | | ---------- | ------------------------------------------------- | -------- | --------------------------- | | maxWidth | 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl' \| 'full' | 'full' | Largura máxima do conteúdo | | padding | 'none' \| 'sm' \| 'md' \| 'lg' | 'md' | Espaçamento interno | | gap | 'none' \| 'sm' \| 'md' \| 'lg' | 'md' | Espaçamento entre elementos |

Responsividade

| Prop | Tipo | Default | Descrição | | ------------------ | --------------------------------- | --------- | ----------------------------------------- | | hideAsideLeftOn | 'sm' \| 'md' \| 'lg' \| 'never' | 'never' | Esconde sidebar esquerda em telas menores | | hideAsideRightOn | 'sm' \| 'md' \| 'lg' \| 'never' | 'never' | Esconde sidebar direita em telas menores |

Elementos Fixos (Sticky)

| Prop | Tipo | Default | Descrição | | ------------------ | --------- | ------- | --------------------- | | stickyHeader | boolean | false | Header fixo no topo | | stickyFooter | boolean | false | Footer fixo no rodapé | | stickyAsideLeft | boolean | false | Sidebar esquerda fixa | | stickyAsideRight | boolean | false | Sidebar direita fixa |

Estilos Inline

| Prop | Tipo | Descrição | | -------------- | --------------- | ------------------------------- | | style | CSSProperties | Estilos inline para o container | | contentStyle | CSSProperties | Estilos inline para o conteúdo |

Exemplos Avançados

Layout com Sidebar Colapsável em Mobile

<PageStructure
  header={<Header />}
  asideLeft={<MobileFriendlySidebar />}
  hideAsideLeftOn="md"
  gap="lg"
  padding="lg"
>
  <Content />
</PageStructure>

Dashboard com Sidebars Fixas

<PageStructure
  header={<DashboardHeader />}
  asideLeft={<Navigation />}
  asideRight={<ActivityFeed />}
  stickyHeader
  stickyAsideLeft
  stickyAsideRight
  maxWidth="2xl"
>
  <DashboardContent />
</PageStructure>

Página de Artigo com Largura Limitada

<PageStructure
  header={<MinimalHeader />}
  footer={<ArticleFooter />}
  maxWidth="md"
  padding="lg"
  className="bg-white"
>
  <article>
    <h1>Título do Artigo</h1>
    <p>Conteúdo...</p>
  </article>
</PageStructure>

Layout Complexo com Customização Total

<PageStructure
  header={<Header />}
  footer={<Footer />}
  asideLeft={<Sidebar />}
  asideRight={<Widgets />}
  // Layout
  maxWidth="xl"
  padding="md"
  gap="lg"
  // Responsividade
  hideAsideRightOn="lg"
  hideAsideLeftOn="md"
  // Sticky elements
  stickyHeader
  stickyAsideLeft
  // Classes customizadas
  className="min-h-screen"
  contentClassName="bg-white rounded-lg shadow"
  headerClassName="backdrop-blur"
  asideLeftClassName="w-64"
  asideRightClassName="w-80"
  // Estilos inline
  style={{ backgroundColor: "var(--color-bg)" }}
  contentStyle={{ minHeight: "80vh" }}
>
  <MainContent />
</PageStructure>

Classes CSS Disponíveis

O componente usa classes semânticas que podem ser estilizadas via CSS:

• .page-structure - Container principal
• .page-header - Área do header
• .page-layout - Container do layout (sidebars + content)
• .page-content - Área de conteúdo principal
• .page-aside-left - Sidebar esquerda
• .page-aside-right - Sidebar direita
• .page-footer - Área do footer

Integração com Sistema de Cores

O componente usa automaticamente as variáveis CSS do sistema de cores DarkSnow:

• Backgrounds: bg-bg, bg-surface
• Borders: border-border
• Texto: text-content

Breakpoints Responsivos

• sm: 640px
• md: 768px
• lg: 1024px
• xl: 1280px
• 2xl: 1536px

Changelog

v1.0.0 (26/05/2025)

• Versão inicial com suporte completo a layouts flexíveis
• Props para controle de responsividade
• Elementos sticky
• Customização via classes e estilos
• Integração com sistema de cores DarkSnow
• Suporte a TypeScript com tipos exportados

Melhorias Implementadas

1. Props Tipadas: Interface completa com TypeScript
2. Responsividade Inteligente: Controle fino sobre quando esconder sidebars
3. Elementos Sticky: Headers e sidebars fixos opcionais
4. Customização Flexível: Classes CSS para cada seção
5. Tamanhos Pré-definidos: Sistema de maxWidth, padding e gap
6. Semântica HTML: Uso correto de <header>, <main>, <aside>, <footer>
7. Performance: Renderização condicional de elementos opcionais
8. Integração com Tailwind: Classes utilitárias com merge inteligente

Roadmap

• [ ] Animações de transição para sidebars colapsáveis
• [ ] Suporte a temas via CSS variables
• [ ] Modo de impressão otimizado
• [ ] Slots nomeados para maior flexibilidade
• [ ] Versão headless (sem estilos)