@esperanca-ui/componentes 2.8.2 → 2.11.0

package/COMPONENTS.md

@@ -31,6 +31,95 @@ export function Example() {
 }
 ```
 
+## Shell Utilities Publicas
+
+O pacote publico tambem entrega classes `esp-shell-*` para o layout base de aplicacoes com `Sidebar`, `PageHeader` e area principal.
+
+Classes disponiveis:
+
+- `esp-shell`: wrapper horizontal principal
+- `esp-shell-main`: coluna principal ao lado da sidebar
+- `esp-shell-header`: padding lateral padrao para `PageHeader`
+- `esp-shell-actions`: alinhamento padrao das acoes do topo
+- `esp-shell-content`: area principal abaixo do header
+- `esp-shell-container`: container centralizado com largura maxima
+- `esp-shell-density-compact`: reduz o espacamento geral do shell
+- `esp-shell-density-comfortable`: densidade equilibrada para dashboard
+- `esp-shell-density-spacious`: aumenta o respiro geral do shell
+
+Exemplo:
+
+```tsx
+import { Background, Button, PageHeader, Sidebar } from '@esperanca-ui/componentes';
+import '@esperanca-ui/componentes/style.css';
+import { FiBell, FiHome, FiPlus, FiSearch, FiSettings, FiUsers } from 'react-icons/fi';
+
+const sections = [
+  {
+    heading: 'Workspace',
+    items: [
+      { label: 'Dashboard', icon: <FiHome />, path: '/dashboard' },
+      { label: 'Members', icon: <FiUsers />, path: '/members' },
+      { label: 'Settings', icon: <FiSettings />, path: '/settings' },
+    ],
+  },
+];
+
+export function WorkspaceShell() {
+  return (
+    <Background pattern="dots">
+      <div className="esp-shell esp-shell-density-comfortable">
+        <Sidebar
+          surface="glass"
+          pinned
+          brandText="Ops Hub"
+          userName="Ana Costa"
+          userEmail="ana@example.com"
+          sections={sections}
+          activePath="/dashboard"
+        />
+
+        <div className="esp-shell-main">
+          <PageHeader
+            sticky
+            title=""
+            className="esp-shell-header"
+            actions={
+              <div className="esp-shell-actions">
+                <Button variant="ghost" size="sm" className="esp-quick-action esp-quick-action-expand" aria-label="Buscar">
+                  <FiSearch />
+                  <span className="esp-quick-action-text">Buscar</span>
+                </Button>
+                <Button variant="ghost" size="sm" className="esp-quick-action esp-quick-action-expand" aria-label="Novo projeto">
+                  <FiPlus />
+                  <span className="esp-quick-action-text">Novo projeto</span>
+                </Button>
+                <Button variant="ghost" size="sm" className="esp-quick-action esp-quick-action-expand esp-quick-action-soft" aria-label="Notificacoes">
+                  <FiBell />
+                  <span className="esp-quick-action-text">Notificacoes</span>
+                </Button>
+              </div>
+            }
+          />
+
+          <main className="esp-shell-content">
+            <div className="esp-shell-container">
+              {/* conteudo da pagina */}
+            </div>
+          </main>
+        </div>
+      </div>
+    </Background>
+  );
+}
+```
+
+Se o app for mais denso, principalmente com tabela, agenda ou lista operacional, prefira:
+
+```tsx
+<div className="esp-shell esp-shell-density-compact">...</div>
+```
+
 ## Quick Actions Publicas
 
 O pacote publico tambem entrega classes `esp-*` para acoes rapidas de topo usando `Button`.
@@ -44,7 +133,7 @@ Classes disponiveis:
 - `esp-quick-action-glass`: variacao translúcida
 - `esp-quick-action-text`: texto que participa da expansao no hover
 
-Essas classes cuidam do visual do botao. O alinhamento do grupo no topo continua sendo responsabilidade do layout da aplicacao.
+Essas classes cuidam do visual do botao. Para o layout do topo, prefira usar as classes publicas `esp-shell-actions` e `esp-shell-header`.
 
 Exemplo:
 
@@ -77,11 +166,14 @@ export function TopQuickActions() {
 
 - `Background` entrega a superficie e os patterns. Blobs borrados, cards glass e outros adornos dos exemplos continuam sendo estilos da aplicacao consumidora.
 - `PageHeader` aceita qualquer `actions`, mas o layout do grupo de acoes continua sendo responsabilidade do app.
+- `Tabs` foi pensado para dois niveis: navegacao contextual (`Resumo`, `Timeline`, `Gantt`, `Calendario`) e troca de modo (`Dia`, `Semana`, `Mes`).
 - `Sidebar` agora expõe `surface="default" | "soft" | "glass"` como API publica para definir a superficie do menu lateral.
+- No desktop, o `Sidebar` se comporta como lateral fixa real; a docs aplica um override local so para manter os previews contidos na vitrine.
 - `TaskStatusBadge` e `TaskPriorityBadge` foram pensados como blocos base para agenda, cards de tarefa, timeline e Gantt.
 - Ambos aceitam presets prontos e tambem `name` + `colors` para cenarios customizados sem criar outro componente.
 - `TaskCard` e um wrapper de alto nivel sobre `Card`, herdando as mesmas variantes (`elevated`, `outlined`, `filled`, `glass`) e props visuais como `interactive`, `glassOpacity` e `glassBlur`.
 - `TaskCalendar` usa o mesmo contrato visual do `Card` e agora suporta `month`, `week` e `day`. No mes as tarefas ficam pequenas como badges; em semana e dia o padrao vira card com mais contexto.
+- `GanttChart` fecha a visao horizontal de planejamento e usa `groups` como primeiro nivel. Assim, o mesmo componente serve para agrupar por projeto ou por responsavel.
 
 ## Componentes Publicos
 
@@ -100,6 +192,7 @@ export function TopQuickActions() {
 | `Loading` | `import { Loading } from '@esperanca-ui/componentes'` | `<Loading variant="spinner" />` |
 | `Modal` | `import { Modal } from '@esperanca-ui/componentes'` | `<Modal isOpen={open} onClose={...}>...</Modal>` |
 | `PageHeader` | `import { PageHeader } from '@esperanca-ui/componentes'` | `<PageHeader title="Clientes" />` |
+| `Tabs` | `import { Tabs } from '@esperanca-ui/componentes'` | `<Tabs items={items} variant="underline" />` |
 | `Portal` | `import { Portal } from '@esperanca-ui/componentes'` | `<Portal><div>Overlay</div></Portal>` |
 | `Radio` | `import { Radio } from '@esperanca-ui/componentes'` | `<Radio label="Opcao A" />` |
 | `RadioGroup` | `import { RadioGroup } from '@esperanca-ui/componentes'` | `<RadioGroup name="status" options={[...]} />` |
@@ -108,6 +201,7 @@ export function TopQuickActions() {
 | `TaskPriorityBadge` | `import { TaskPriorityBadge } from '@esperanca-ui/componentes'` | `<TaskPriorityBadge priority="high" />` |
 | `TaskCard` | `import { TaskCard } from '@esperanca-ui/componentes'` | `<TaskCard title="Revisar agenda" status="in_progress" />` |
 | `TaskCalendar` | `import { TaskCalendar } from '@esperanca-ui/componentes'` | `<TaskCalendar tasks={tasks} defaultDate="2026-03-01" showViewSwitcher />` |
+| `GanttChart` | `import { GanttChart } from '@esperanca-ui/componentes'` | `<GanttChart groups={groups} defaultView="month" />` |
 | `DataTable` | `import { DataTable } from '@esperanca-ui/componentes'` | `<DataTable columns={columns} data={data} />` |
 | `Textarea` | `import { Textarea } from '@esperanca-ui/componentes'` | `<Textarea label="Descricao" />` |
 | `ThemeProvider` | `import { ThemeProvider } from '@esperanca-ui/componentes'` | `<ThemeProvider defaultTheme="system"><App /></ThemeProvider>` |