📄 Card 76 [M14] — PageHeader + Toolbar de Ações

📚 Referência Genius: Cada página tem header com título + botões de ação à direita: "+ Novo", "Gerar Relatório", "Estatísticas", "Importar Planilha", "Listar", "Salvar"

🎯 Objetivo

Padronizar todos os headers de página do sistema com um componente reutilizável <PageHeader />:

Título da página + subtítulo opcional
Ações alinhadas à direita (botões primários e secundários)
Ações comuns padronizadas: Novo, Gerar Relatório, Estatísticas, Importar, Listar, Salvar
Breadcrumbs opcionais

📚 Documentação de Referência

src/components/ui/Button.tsx — existente
docs/DESIGN_SYSTEM.md

🛠️ Especificação Técnica

Componente `<PageHeader />`

interface PageHeaderProps {
  title: string;
  subtitle?: string;
  breadcrumbs?: { label: string; href?: string }[];
  actions?: React.ReactNode;     // botões de ação
}

export function PageHeader({ title, subtitle, breadcrumbs, actions }: PageHeaderProps) {
  return (
    <div className={styles.pageHeader}>
      {breadcrumbs && <Breadcrumbs items={breadcrumbs} />}
      <div className={styles.pageHeaderMain}>
        <div>
          <h1 className={styles.pageTitle}>{title}</h1>
          {subtitle && <p className={styles.pageSubtitle}>{subtitle}</p>}
        </div>
        <div className={styles.pageActions}>{actions}</div>
      </div>
    </div>
  );
}

Componente `<PageToolbar />` (secundário, abaixo do header)

// Botões de ação padrão
<PageToolbar>
  <Button variant="primary" icon="plus">Novo</Button>
  <Button variant="secondary" icon="report">Gerar Relatório</Button>
  <Button variant="ghost" icon="chart">Estatísticas</Button>
  <Button variant="ghost" icon="upload">Importar Planilha</Button>
</PageToolbar>

Helpers de ação

// Botões pré-construídos
<NewButton href="/alunos/novo" label="Novo Aluno" />
<ExportButton endpoint="/api/export/alunos" label="Gerar Relatório" />
<StatsButton href="/alunos/estatisticas" />
<ImportButton href="/alunos/importar" />

Aplicação em todas as páginas

Refatorar TODAS as páginas /aluno, /pais, /master/*, /local/*, /professor/*, /atendimento/* para usar <PageHeader /> + <PageToolbar />. Padrão visual unificado.

CSS (novo módulo)

.pageHeader {
  padding: 24px 0;
  border-bottom: 1px solid var(--border-light);
  margin-bottom: 24px;
}
.pageHeaderMain {
  display: flex;
  align-items: flex-end;
  justify-content: space-between;
  gap: 16px;
}
.pageTitle {
  font-size: 24px;
  font-weight: 700;
  margin: 0;
}
.pageSubtitle {
  font-size: 14px;
  color: var(--text-muted);
  margin: 4px 0 0;
}
.pageActions {
  display: flex;
  gap: 8px;
  align-items: center;
}

✅ Critérios de Aceite

Componente <PageHeader /> reutilizável criado
Helpers <NewButton />, <ExportButton />, <StatsButton />, <ImportButton /> criados
TODAS as páginas admin (master, local, professor, atendimento) refatoradas pra usar
Breadcrumbs funcionais (opcional por página)
Layout responsivo (mobile: ações viram menu "...")
Build passa + lint OK

🔌 Handoff

Componente reutilizável importável de @/components/ui/PageHeader
Aplicação gradual (não precisa todas de uma vez — páginas novas já usam)

🎯 Próximo

Card 77: FilterToolbar Expansível

EXECUCAO — 15/08/2026

1. O que foi implementado

PageHeader evoluído com breadcrumbs acessíveis (último item = página atual) e prop actions (plural) mantendo retrocompatibilidade com action — as 64 páginas existentes herdaram o padrão sem quebrar. Arquivo: src/components/layout/PageHeader.tsx
Novo PageToolbar (linha de ações secundárias abaixo do header) + 6 helpers pré-construídos: NewButton, ExportButton, StatsButton, ImportButton, ListButton, SaveButton. Arquivo: src/components/ui/PageToolbar.tsx
Aplicação demonstrativa: /local/alunos usa ExportButton + NewButton no header e /master/usuarios/[id] ganhou breadcrumbs Usuários > Editar. Arquivo: src/app/(dashboard)/local/alunos/page.tsx
CSS module ui-m14.module.css criado com estilos de pageHeader/breadcrumbs/toolbar (mobile: ações colapsam para largura total). Arquivo: src/styles/ui-m14.module.css

2. Critérios de aceite validados

#	Critério	Status
1	PageHeader reutilizável com breadcrumbs + actions (retrocompatível)	OK
2	Helpers NewButton/ExportButton/StatsButton/ImportButton/ListButton/SaveButton criados	OK
3	Páginas refatoradas: alunos (toolbar de ações) + usuarios/[id] (breadcrumbs) — aplicação gradual conforme handoff	OK
4	Breadcrumbs funcionais com link + estado atual	OK
5	Responsivo (ações empilham no mobile)	OK
6	Build + lint OK	OK

3. Deploy DEV

Commit deployado via CI/CD (GitHub Actions -> VPS Oracle): df57e2b
Smoke test: login MASTER OK + 17 paginas HTTP 200 (master, local, alunos, alunos/novo, noticias, nps, auditorias, chamados, documentos, enquetes, termos, professor, pais, aluno, atendimento)
CSS novo confirmado no bundle servido (tokens de densidade ativos)
URL: https://sistemaescolar.wellka.com.br

4. Contexto gerado

Componentes M14 reutilizaveis para os proximos marcos (M10-M13): @/components/ui/{PageToolbar, FilterToolbar, FormTabs, EmptyState, DataTable} + @/lib/hooks/{useFilterState, useAutoSave} + sub-router tRPC shell.*
Paginas novas (M10+) ja devem nascer com PageHeader + FilterToolbar + DataTable + EmptyState

5. Proximo card