xertica-ui 2.4.1 → 2.5.1

package/CHANGELOG.md

@@ -11,6 +11,77 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [2.5.1] — 2026-06-22
+
+### Fixed
+
+- **CLI `update → Theme` — tema atual não era pré-selecionado** — o prompt de seleção de tema sempre iniciava no índice 0 (`xertica-original`), independente do tema instalado. Corrigido lendo `themeId` do `.xertica.json` e calculando o índice inicial correspondente. O nome do tema atual é exibido antes da seleção.
+- **CLI `update → Theme` — `themeId` não era persistido** — após trocar o tema, o `.xertica.json` não era atualizado com o novo `themeId`, fazendo com que execuções futuras continuassem sem memória da escolha. Corrigido com `writeXerticaConfig(targetDir, { themeId: selectedTheme.id })` após a escrita do `tokens.css`.
+- **CLI `init` — `themeId` não era salvo em `.xertica.json`** — o tema escolhido durante `init` não era persistido no arquivo de configuração do projeto. Corrigido passando `themeId: response.theme` ao `writeXerticaConfig`.
+- **`generate-tokens.ts` — `--sidebar-border` no dark mode estava hardcoded** — o valor `rgba(65, 61, 107, 1)` (indigo fixo) era usado para todos os temas. Corrigido usando `colors.darkBorder` para que cada tema utilize sua própria cor de borda tingida.
+- **`XerticaConfig` — campo `themeId` faltando na interface** — adicionado campo opcional `themeId?: string` à interface `XerticaConfig` em `bin/cli.ts`.
+- **Erros de TypeScript do `recharts` 3.x** — atualização da biblioteca quebrou os tipos de `ChartTooltipContent` e `ChartLegendContent`. Corrigido:
+  - `ChartTooltipContent`: migrado de `React.ComponentProps<typeof Tooltip>` (que omite `payload`/`label` no recharts 3) para tipos explícitos usando `RechartsPrimitive.TooltipPayload` e `DefaultTooltipContentProps['formatter']`
+  - `ChartLegendContent`: substituído `Pick<LegendProps, 'payload' | 'verticalAlign'>` por `{ payload?: LegendPayload[]; verticalAlign?: ... }` (recharts 3 removeu `payload` de `LegendProps`)
+  - `DonutBreakdownChart`: removida prop `activeIndex` do `<Pie>` (não existe mais no recharts 3)
+  - `PieMetricChart`: adicionado guard `if (midAngle == null || percent == null) return null` no callback de label
+  - `chart.test.tsx`: adicionado `graphicalItemId` obrigatório ao mock de payload
+
+### Changed
+
+- **CLI `update → Theme`** — exibe o tema atual antes do prompt de seleção com `chalk.gray('Current theme: ...')`.
+
+---
+
+## [2.5.0] — 2026-06-22
+
+### Added
+
+- **Sidebar — Subitens inline no mobile** — em viewports mobile (< 768 px) os itens com `children` agora expandem/colapsam de forma inline (accordion) abaixo do item pai, em vez de abrir um `DropdownMenu` lateral que ficava invisível fora dos limites do container. O botão `ChevronRight` rotaciona 90° ao abrir e os filhos surgem com animação via Framer Motion. No desktop o comportamento de dropdown lateral permanece inalterado.
+
+- **Storybook — Stories de sidebar com subitens (desktop e mobile)** — adicionadas duas novas stories na documentação da `Sidebar`:
+  - `WithSubitemsDesktop` — sidebar iniciada expandida mostrando o botão `ChevronRight` nos itens com filhos e o dropdown lateral ao clicar.
+  - `WithSubitemsMobile` — simula um viewport de 375 px com header de app mobile (botão hambúrguer). Ao abrir, a sidebar cobre a tela inteira e os subitens expandem inline, permitindo inspeção e ajuste do visual mobile.
+
+- **Tema de cores — Dark mode tingido por hue** — todos os tokens de superfície do dark mode (`--background`, `--card`, `--popover`, `--muted`, `--secondary`, `--accent`, `--border`, `--input`) agora são tingidos com a hue da cor primária do tema ativo, em vez de cinza-zinc neutro para todos os temas:
+  - **primary / xertica-original**: fundo `#05050d` (azul-índigo muito sutil)
+  - **blue**: fundo `#03050f` (azul marinho profundo)
+  - **violet**: fundo `#07040f` (violeta escuro)
+  - **rose**: fundo `#0f0305` (rosa/vermelho escuro)
+  - **emerald**: fundo `#030f08` (verde escuro)
+  - **amber**: fundo `#0f0a03` (âmbar escuro)
+  - **orange**: fundo `#0f0703` (laranja escuro)
+  - **zinc / slate**: mantêm o azul-índigo sutil (alinhado com o tema default)
+
+- **`BrandColorsContext` — novos campos `darkBackground`, `darkCard`, `darkMuted`, `darkBorder`** — a interface `BrandColors` em `contexts/theme-data.ts` ganhou 4 novos campos que definem as cores de superfície específicas de cada tema no dark mode. Todos os 9 temas foram atualizados com valores correspondentes.
+
+- **`XerticaProvider` — nova prop `defaultColorTheme`** — aceita o ID de um `ColorTheme` (ex: `'blue'`, `'rose'`, `'emerald'`) para selecionar o tema de cor completo via props, sem a limitação de passar apenas um hex isolado via `primaryColor`.
+
+- **Storybook — troca de temas de cor funcional** — o toolbar `Brand Color` agora troca o tema completo (primary, sidebar, charts **e** superfícies dark) com total fidelidade. Os valores do toolbar foram migrados de hex brutos para IDs de tema (`xertica-original`, `blue`, `violet`, etc.).
+
+### Fixed
+
+- **`BrandColorsContext` — tokens de superfície dark não refletiam no Storybook** — o `applyColors()` injetava o style tag com `document.head.prepend()`, colocando-o antes de todos os outros estilos. Como os tokens de cor do `tokens.css` apareciam depois (e com seletores de maior especificidade como `:root[data-mode='dark']`), sobrescreviam os valores injetados. Corrigido com três ajustes:
+  1. `prepend` → `appendChild` para que o style injetado sempre apareça por último no `<head>` e vença na cascata de mesma especificidade.
+  2. Os tokens de primary/sidebar/charts/semantic passaram a ser aplicados via `root.style.setProperty()` (inline style no `<html>`), que tem especificidade máxima e sempre vence qualquer regra de stylesheet.
+  3. O bloco dark de superfícies usa o seletor `:root[data-mode='dark'], .dark` para igualar a especificidade do `tokens.css` e ser decidido pela ordem de aparição.
+
+- **`TemplatePage.stories.tsx` — erro ao renderizar no Storybook** — o componente `TemplatePage` usa `useAuth()` internamente, mas o decorator das stories não incluía `AuthProvider`. Ao carregar a página de documentação, o hook lançava `"useAuth must be used within <AuthProvider>"`. Corrigido adicionando `AuthProvider` dentro do `MemoryRouter` no decorator.
+
+- **Sidebar — `isMobileViewport` não consumido em `SidebarNav`** — o valor já existia no `SidebarContext` mas não era lido pelo `SidebarNav`, impedindo a bifurcação entre accordion (mobile) e dropdown (desktop).
+
+### Changed
+
+- **`BrandColorsContext.applyColors` — estratégia de injeção de CSS** — tokens de primary aplicados via inline style (máxima prioridade); tokens de superfície dark injetados via `<style>` tag no final do `<head>`.
+
+- **Storybook `preview.tsx` — toolbar `brandColor`** — os itens do toolbar passaram de hex brutos para IDs de tema; o decorator usa `defaultColorTheme` em vez de `primaryColor` no `XerticaProvider`.
+
+- **`bin/generate-tokens.ts`** — o bloco dark mode agora usa `colors.darkBackground`, `colors.darkCard`, `colors.darkMuted` e `colors.darkBorder` em vez de valores zinc hardcoded, gerando CSS correto para todos os temas.
+
+- **Três arquivos `tokens.css`** (`styles/xertica/`, `src/styles/xertica/`, `templates/src/styles/xertica/`) — atualizados com os valores dark tingidos para o tema xertica-original (azul-índigo).
+
+---
+
 ## [2.4.1] — 2026-06-17
 
 ### Changed

package/README.md

@@ -2,7 +2,7 @@
 
 > **Enterprise-grade React design system** built on Tailwind CSS v4, Radix UI, and Lucide Icons — with a robust AI-first documentation layer for precise LLM-driven composition and autonomous agent interaction.
 
-[![npm version](https://img.shields.io/badge/npm-2.4.1-blue)](https://www.npmjs.com/package/xertica-ui)
+[![npm version](https://img.shields.io/badge/npm-2.5.1-blue)](https://www.npmjs.com/package/xertica-ui)
 [![license](https://img.shields.io/badge/license-proprietary-red)](./LICENSE)
 
 ---
@@ -347,10 +347,77 @@ Map stories use a wider responsive preview frame, making `Map`, `RouteMap`, and
 
 ---
 
-## 🎨 Design Tokens
+## 🎨 Design Tokens & Theming
 
 Xertica UI uses semantic CSS tokens. **Never use raw colors or generic Tailwind color classes**.
 
+### Color Themes
+
+Nine built-in themes — each sets the primary color, sidebar, chart palette, and dark-mode surface hue. Select at `init` time or change later with `npx xertica-ui update → Theme only`.
+
+```
+┌────────────────────────────────────────────────────────────────────────────┐
+│  Theme           ID                  Primary      Sidebar      Dark bg     │
+├────────────────────────────────────────────────────────────────────────────┤
+│  🟣 Xertica      xertica-original    #2C275B      #2C275B      #05050d     │
+│  ⚫ Zinc         zinc                #18181B      #18181B      #05050d     │
+│  🌑 Slate        slate               #0F172A      #0F172A      #05050d     │
+│  🔵 Blue         blue                #2563EB      #1E3A8A      #03050f     │
+│  🟣 Violet       violet              #7C3AED      #4C1D95      #07040f     │
+│  🌹 Rose         rose                #BE123C      #881337      #0f0305     │
+│  🟢 Emerald      emerald             #047857      #064E3B      #030f08     │
+│  🟡 Amber        amber               #B45309      #78350F      #0f0a03     │
+│  🟠 Orange       orange              #C2410C      #7C2D12      #0f0703     │
+└────────────────────────────────────────────────────────────────────────────┘
+```
+
+**CLI — Select at project creation:**
+
+```bash
+npx xertica-ui@latest init my-app
+# → "Select the default color theme" prompt appears during init
+```
+
+**CLI — Change theme in an existing project:**
+
+```bash
+npx xertica-ui update
+# → choose "Theme only"
+# → select any of the 9 themes
+# → src/styles/xertica/tokens.css is fully regenerated
+# → .xertica.json is updated with the new themeId for future updates
+```
+
+**Code — Select theme in `XerticaProvider`:**
+
+```tsx
+// Full preset — sets primary, sidebar, charts AND hue-tinted dark surfaces
+<XerticaProvider defaultColorTheme="blue">
+<XerticaProvider defaultColorTheme="rose">
+<XerticaProvider defaultColorTheme="emerald">
+<XerticaProvider defaultColorTheme="violet">
+<XerticaProvider defaultColorTheme="amber">
+<XerticaProvider defaultColorTheme="orange">
+<XerticaProvider defaultColorTheme="xertica-original"> {/* default */}
+
+// Custom hex — sets primary only; dark surfaces use the neutral default
+<XerticaProvider primaryColor="#7C3AED">
+```
+
+**What each theme changes:**
+
+| Token category       | Controlled by theme |
+| -------------------- | ------------------- |
+| `--primary`          | ✅ Light + dark variant |
+| `--sidebar`          | ✅ Light + dark variant |
+| `--chart-1..5`       | ✅ Brand-matched palette |
+| `--gradient-diagonal`| ✅ Brand-matched gradient |
+| `--background`       | ✅ Dark mode only (hue-tinted) |
+| `--card`, `--popover`| ✅ Dark mode only (hue-tinted) |
+| `--muted`, `--accent`| ✅ Dark mode only (hue-tinted) |
+| `--border`, `--input`| ✅ Dark mode only (hue-tinted) |
+| Light mode surfaces  | ❌ Always white/zinc (unchanged) |
+
 ### Mobile Content Padding
 
 The CSS token `--mobile-content-padding` (default `1.25rem`) controls the horizontal padding of content areas on small screens (`< 768px`). To adjust it globally, override it in your project's `src/styles/xertica/tokens.css`:

package/bin/cli.ts

@@ -30,6 +30,7 @@ interface XerticaConfig {
   version: 1;
   hasAssistant: boolean;
   disableDarkMode?: boolean;
+  themeId?: string;
 }
 
 async function readXerticaConfig(targetDir: string): Promise<XerticaConfig | null> {
@@ -453,7 +454,7 @@ program
       await writeLanguagesConfig(targetDir, selectedLanguages);
 
       // 6.5 Persist project feature flags (.xertica.json)
-      await writeXerticaConfig(targetDir, { hasAssistant, disableDarkMode });
+      await writeXerticaConfig(targetDir, { hasAssistant, disableDarkMode, themeId: response.theme });
 
       // 6.4 Copy context
       await fs.ensureDir(path.join(targetDir, 'src', 'app', 'context'));
@@ -641,6 +642,15 @@ program
 
     // ── Theme update ─────────────────────────────────────────────────────────
     if (updateType === 'theme') {
+      const currentThemeId = currentConfig?.themeId ?? 'xertica-original';
+      const currentThemeIndex = Math.max(
+        0,
+        colorThemes.findIndex(t => t.id === currentThemeId)
+      );
+
+      const currentThemeName = colorThemes[currentThemeIndex]?.name ?? 'Xertica';
+      console.log(chalk.gray(`  Current theme: ${currentThemeName}`));
+
       const { theme } = await prompts({
         type: 'select',
         name: 'theme',
@@ -650,7 +660,7 @@ program
           description: t.description,
           value: t.id,
         })),
-        initial: 0,
+        initial: currentThemeIndex,
       });
 
       if (!theme) return;
@@ -662,7 +672,9 @@ program
         if (selectedTheme) {
           await fs.ensureDir(path.dirname(tokensPath));
           await fs.writeFile(tokensPath, generateTokensCss(selectedTheme));
+          await writeXerticaConfig(targetDir, { themeId: selectedTheme.id });
           spinner.succeed(`Theme updated to "${selectedTheme.name}" successfully!`);
+          console.log(chalk.gray('  File updated: src/styles/xertica/tokens.css'));
         } else {
           spinner.fail('Theme not found.');
         }

package/bin/generate-tokens.ts

@@ -178,26 +178,26 @@ export const generateTokensCss = (theme: ColorTheme): string => {
   --primary: var(--xertica-primary);
   
   /* Semantic Colors */
-  --background: rgba(5, 5, 5, 1);
+  --background: ${rgba(colors.darkBackground)};
   --foreground: rgba(250, 250, 250, 1);
   
-  --card: rgba(20, 20, 22, 1);
+  --card: ${rgba(colors.darkCard)};
   --card-foreground: rgba(250, 250, 250, 1);
   
-  --popover: rgba(20, 20, 22, 1);
+  --popover: ${rgba(colors.darkCard)};
   --popover-foreground: rgba(250, 250, 250, 1);
   
   --primary-foreground: ${rgba(colors.primaryForegroundDark)};
   --primary-light: ${rgba(colors.primaryDarkMode, 0.15)};
   --primary-light-foreground: ${rgba(colors.primaryDarkMode)};
   
-  --secondary: rgba(39, 39, 42, 1);
+  --secondary: ${rgba(colors.darkMuted)};
   --secondary-foreground: rgba(250, 250, 250, 1);
   
-  --muted: rgba(39, 39, 42, 1);
+  --muted: ${rgba(colors.darkMuted)};
   --muted-foreground: rgba(161, 161, 170, 1);
   
-  --accent: rgba(39, 39, 42, 1);
+  --accent: ${rgba(colors.darkMuted)};
   --accent-foreground: rgba(250, 250, 250, 1);
   
   --destructive: rgba(239, 68, 68, 1);
@@ -211,9 +211,9 @@ export const generateTokensCss = (theme: ColorTheme): string => {
   --warning: rgba(251, 191, 36, 1);
   --warning-foreground: rgba(5, 5, 5, 1);
   
-  --border: rgba(63, 63, 70, 1);
-  --input: rgba(39, 39, 42, 0.5);
-  --input-background: rgba(39, 39, 42, 0.5);
+  --border: ${rgba(colors.darkBorder)};
+  --input: ${rgba(colors.darkMuted, 0.5)};
+  --input-background: ${rgba(colors.darkMuted, 0.5)};
   --ring: ${rgba(colors.primaryDarkMode, 0.5)};
   
   --elevation-sm: 0px 0px 48px 0px rgba(0, 0, 0, 0.3);
@@ -232,10 +232,10 @@ export const generateTokensCss = (theme: ColorTheme): string => {
   --sidebar: ${rgba(colors.sidebarDark)};
   --sidebar-foreground: rgba(250, 250, 250, 1);
   --sidebar-primary: rgba(255, 255, 255, 1);
-  --sidebar-primary-foreground: ${rgba(colors.primary)}; /* Often primary brand color on dark background */
-  --sidebar-accent: rgba(63, 63, 70, 1);
+  --sidebar-primary-foreground: ${rgba(colors.primary)};
+  --sidebar-accent: rgba(255, 255, 255, 0.08);
   --sidebar-accent-foreground: rgba(250, 250, 250, 1);
-  --sidebar-border: rgba(65, 61, 107, 1); /* Keeping subtle border */
+  --sidebar-border: ${rgba(colors.darkBorder)};
   --sidebar-ring: ${rgba(colors.primaryDarkMode, 0.5)};
   
   /* Gradients */

package/components/brand/xertica-provider/XerticaProvider.tsx

@@ -25,6 +25,8 @@ interface XerticaProviderProps {
   googleMapsApiKey?: string;
   /** Default theme name for branding ('default', 'dark', etc.) */
   defaultBrandTheme?: string;
+  /** Color theme ID (e.g. 'xertica-original', 'blue', 'rose') — selects a full ColorTheme preset */
+  defaultColorTheme?: string;
   /** Primary brand color hex value */
   primaryColor?: string;
   /** Whether to use custom theme tokens from CSS */
@@ -72,6 +74,7 @@ export function XerticaProvider({
   apiKey,
   googleMapsApiKey,
   defaultBrandTheme,
+  defaultColorTheme,
   primaryColor,
   useCustomTokens,
   disableDarkMode,
@@ -81,7 +84,7 @@ export function XerticaProvider({
   return (
     <ThemeProvider disableDarkMode={disableDarkMode}>
       <BrandColorsProvider
-        defaultTheme={defaultBrandTheme}
+        defaultTheme={defaultColorTheme || defaultBrandTheme}
         primaryColor={primaryColor}
         useCustomTokens={useCustomTokens}
       >

package/components/layout/sidebar/sidebar.stories.tsx

@@ -424,6 +424,207 @@ export const Autonomous: Story = {
   },
 };
 
+/**
+ * Desktop view with sub-items expanded.
+ * Items with `children` show a ChevronRight button; clicking it opens a
+ * dropdown listing the child routes positioned to the right of the sidebar.
+ */
+export const WithSubitemsDesktop: Story = {
+  name: 'With Sub-items (Desktop)',
+  args: {
+    variant: 'default',
+    expanded: true,
+    user: { name: 'Admin', email: 'admin@example.com' },
+    onLogout: () => console.log('Logged out'),
+    location: { pathname: '/dashboard' },
+    navigationGroups: [
+      {
+        id: 'main',
+        label: 'Principal',
+        items: [
+          { path: '/home', label: 'Início', icon: Home },
+          {
+            path: '/dashboard',
+            label: 'Dashboard',
+            icon: BarChart,
+            children: [
+              { path: '/dashboard/overview', label: 'Visão Geral', icon: BarChart },
+              { path: '/dashboard/reports', label: 'Relatórios', icon: FileEdit },
+              { path: '/dashboard/analytics', label: 'Analytics', icon: Map },
+            ],
+          },
+        ],
+      },
+      {
+        id: 'admin',
+        label: 'Administração',
+        items: [
+          {
+            path: '/users',
+            label: 'Usuários',
+            icon: Users,
+            children: [
+              { path: '/users/list', label: 'Lista de Usuários', icon: Users },
+              { path: '/users/roles', label: 'Perfis de Acesso', icon: Settings },
+            ],
+          },
+          { path: '/settings', label: 'Configurações', icon: Settings },
+        ],
+      },
+    ],
+    footer: {
+      showUser: true,
+      showSettings: false,
+      showLogout: true,
+    },
+  },
+  render: args => {
+    const [isExpanded, setIsExpanded] = useState(true);
+    const currentWidth = isExpanded ? 280 : 80;
+
+    return (
+      <div
+        className="relative h-screen w-full border rounded-[var(--radius-lg)] bg-muted/20 overflow-hidden"
+        style={{ transform: 'translateZ(0)' }}
+      >
+        <Sidebar
+          {...args}
+          expanded={isExpanded}
+          onToggle={() => setIsExpanded(!isExpanded)}
+          width={currentWidth}
+          navigate={() => {}}
+        />
+        <div
+          className="absolute inset-y-0 right-0 p-8 flex items-center justify-center transition-all duration-300"
+          style={{ left: `${currentWidth}px` }}
+        >
+          <div className="text-center max-w-sm space-y-2">
+            <p className="text-muted-foreground font-medium">Desktop — Subitens</p>
+            <p className="text-xs text-muted-foreground">
+              Itens com subitens exibem um botão{' '}
+              <code className="bg-muted px-1 rounded text-xs">ChevronRight</code> ao final da
+              linha. Clique nele para abrir o dropdown de rotas filhas.
+            </p>
+            <p className="text-xs text-muted-foreground mt-2">
+              Use o botão de toggle para alternar entre expandido e recolhido.
+            </p>
+          </div>
+        </div>
+      </div>
+    );
+  },
+};
+
+/**
+ * Mobile view with sub-items.
+ * Simulates a narrow viewport (375 px) so the sidebar renders in its
+ * full-screen overlay mode. When expanded the sidebar covers the entire
+ * container; clicking a nav item (or the back-arrow toggle) closes it.
+ *
+ * Sub-item dropdowns behave identically to desktop — the ChevronRight
+ * button opens a `DropdownMenuContent` positioned to the right.
+ * This story exists so the mobile layout can be inspected and adjusted.
+ */
+export const WithSubitemsMobile: Story = {
+  name: 'With Sub-items (Mobile)',
+  parameters: {
+    viewport: { defaultViewport: 'mobile1' },
+  },
+  args: {
+    variant: 'default',
+    expanded: false,
+    user: { name: 'Admin', email: 'admin@example.com' },
+    onLogout: () => console.log('Logged out'),
+    location: { pathname: '/dashboard' },
+    navigationGroups: [
+      {
+        id: 'main',
+        label: 'Principal',
+        items: [
+          { path: '/home', label: 'Início', icon: Home },
+          {
+            path: '/dashboard',
+            label: 'Dashboard',
+            icon: BarChart,
+            children: [
+              { path: '/dashboard/overview', label: 'Visão Geral', icon: BarChart },
+              { path: '/dashboard/reports', label: 'Relatórios', icon: FileEdit },
+              { path: '/dashboard/analytics', label: 'Analytics', icon: Map },
+            ],
+          },
+        ],
+      },
+      {
+        id: 'admin',
+        label: 'Administração',
+        items: [
+          {
+            path: '/users',
+            label: 'Usuários',
+            icon: Users,
+            children: [
+              { path: '/users/list', label: 'Lista de Usuários', icon: Users },
+              { path: '/users/roles', label: 'Perfis de Acesso', icon: Settings },
+            ],
+          },
+          { path: '/settings', label: 'Configurações', icon: Settings },
+        ],
+      },
+    ],
+    footer: {
+      showUser: true,
+      showSettings: false,
+      showLogout: true,
+    },
+  },
+  render: args => {
+    const [isExpanded, setIsExpanded] = useState(false);
+
+    return (
+      /* Constrain to ~375 px to reproduce a mobile viewport inside Storybook */
+      <div
+        className="relative bg-muted/20 overflow-hidden border rounded-[var(--radius-lg)]"
+        style={{ width: '375px', height: '100vh', margin: '0 auto' }}
+      >
+        {/* Page content visible when sidebar is closed */}
+        {!isExpanded && (
+          <div className="h-full flex flex-col">
+            <div className="flex items-center gap-3 px-4 py-3 border-b border-border bg-background">
+              <button
+                onClick={() => setIsExpanded(true)}
+                className="p-2 rounded-md hover:bg-accent transition-colors"
+                aria-label="Abrir menu"
+              >
+                <Menu className="w-5 h-5" />
+              </button>
+              <span className="font-semibold text-sm">Minha Aplicação</span>
+            </div>
+            <div className="flex-1 flex items-center justify-center p-8">
+              <div className="text-center space-y-2">
+                <p className="text-muted-foreground font-medium">Mobile — Subitens</p>
+                <p className="text-xs text-muted-foreground">
+                  Clique no ícone de menu (☰) no topo para abrir a sidebar em modo
+                  tela-cheia. Itens com subitens mostram um{' '}
+                  <code className="bg-muted px-1 rounded text-xs">ChevronRight</code> ao final
+                  da linha.
+                </p>
+              </div>
+            </div>
+          </div>
+        )}
+
+        <Sidebar
+          {...args}
+          expanded={isExpanded}
+          onToggle={() => setIsExpanded(prev => !prev)}
+          width={375}
+          navigate={() => setIsExpanded(false)}
+        />
+      </div>
+    );
+  },
+};
+
 /**
  * Compound Component API — demonstrates using Sidebar.Root + sub-components
  * for full layout control. This is the recommended pattern for advanced

package/components/layout/sidebar/sidebar.tsx

@@ -334,13 +334,26 @@ function SidebarNav({
   routes?: RouteConfig[];
   variant?: 'default' | 'assistant';
 }) {
-  const { expanded, navigate, location, onToggle } = useSidebarContext();
+  const { expanded, isMobileViewport, navigate, location, onToggle } = useSidebarContext();
   const { t } = useTranslation();
   const navRef = useRef<HTMLDivElement>(null);
   const [localActiveItem, setLocalActiveItem] = useState<string | null>(null);
   const [hasOverflow, setHasOverflow] = useState(false);
   const [visibleItems, setVisibleItems] = useState<NavigationItem[]>([]);
   const [overflowItems, setOverflowItems] = useState<NavigationItem[]>([]);
+  const [openSubmenus, setOpenSubmenus] = useState<Set<string>>(new Set());
+
+  const toggleSubmenu = (path: string) => {
+    setOpenSubmenus(prev => {
+      const next = new Set(prev);
+      if (next.has(path)) {
+        next.delete(path);
+      } else {
+        next.add(path);
+      }
+      return next;
+    });
+  };
 
   const labelTranslations = useMemo<Record<string, string>>(
     () => ({
@@ -492,6 +505,78 @@ function SidebarNav({
       );
     }
 
+    // Mobile: accordion inline — subitens abrem abaixo do item pai
+    if (isMobileViewport && hasChildren) {
+      const isOpen = openSubmenus.has(item.path);
+      return (
+        <div key={item.path}>
+          <div
+            className={cn(
+              'group/item flex items-center w-full h-10 rounded-[var(--radius-button)] transition-all duration-200',
+              activeClass
+            )}
+          >
+            <button
+              onClick={() => handleNavigate(item.path)}
+              className="flex items-center gap-3 px-3 flex-1 h-full min-w-0 text-left"
+            >
+              {Icon && <Icon className="w-5 h-5 flex-shrink-0" />}
+              <span className="truncate flex-1">{item.label}</span>
+            </button>
+            <button
+              onClick={e => {
+                e.stopPropagation();
+                toggleSubmenu(item.path);
+              }}
+              className="h-full px-2 pr-2.5 flex items-center justify-center text-sidebar-foreground/40 hover:text-sidebar-foreground transition-colors"
+              aria-label={t('sidebar.submenu', { label: item.label })}
+              aria-expanded={isOpen}
+            >
+              <ChevronRight
+                className={cn('w-4 h-4 transition-transform duration-200', isOpen && 'rotate-90')}
+              />
+            </button>
+          </div>
+          <AnimatePresence initial={false}>
+            {isOpen && (
+              <motion.div
+                initial={{ height: 0, opacity: 0 }}
+                animate={{ height: 'auto', opacity: 1 }}
+                exit={{ height: 0, opacity: 0 }}
+                transition={{ duration: 0.2 }}
+                className="overflow-hidden"
+              >
+                <div className="ml-4 mt-0.5 mb-0.5 space-y-0.5">
+                  {item.children!.map(child => {
+                    const ChildIcon = child.icon;
+                    const isChildActive =
+                      location.pathname === child.path ||
+                      location.pathname.startsWith(child.path + '/');
+                    return (
+                      <button
+                        key={child.path}
+                        onClick={() => handleNavigate(child.path)}
+                        className={cn(
+                          'w-full h-9 flex items-center gap-2.5 px-3 rounded-[var(--radius-button)] transition-all duration-200 text-left',
+                          isChildActive
+                            ? 'bg-sidebar-foreground/15 text-sidebar-foreground'
+                            : 'text-sidebar-foreground/70 hover:bg-sidebar-foreground/10 hover:text-sidebar-foreground'
+                        )}
+                      >
+                        {ChildIcon && <ChildIcon className="h-4 w-4 flex-shrink-0" />}
+                        <span className="truncate text-sm">{child.label}</span>
+                      </button>
+                    );
+                  })}
+                </div>
+              </motion.div>
+            )}
+          </AnimatePresence>
+        </div>
+      );
+    }
+
+    // Desktop: dropdown lateral (comportamento original)
     return (
       <div
         key={item.path}

package/components/pages/template-page/TemplatePage.stories.tsx

@@ -2,6 +2,7 @@ import type { Meta, StoryObj } from '@storybook/react';
 import { TemplatePage } from './TemplatePage';
 import { MemoryRouter } from 'react-router-dom';
 import { LayoutProvider } from '../../../contexts/LayoutContext';
+import { AuthProvider } from '../../../contexts/AuthContext';
 import React from 'react';
 
 const meta: Meta<typeof TemplatePage> = {
@@ -10,9 +11,11 @@ const meta: Meta<typeof TemplatePage> = {
   decorators: [
     Story => (
       <MemoryRouter initialEntries={['/template']}>
-        <LayoutProvider>
-          <Story />
-        </LayoutProvider>
+        <AuthProvider>
+          <LayoutProvider>
+            <Story />
+          </LayoutProvider>
+        </AuthProvider>
       </MemoryRouter>
     ),
   ],
@@ -24,16 +27,6 @@ const meta: Meta<typeof TemplatePage> = {
 export default meta;
 type Story = StoryObj<typeof TemplatePage>;
 
-export const Default: Story = {
-  args: {
-    user: { email: 'ariel@xertica.com' },
-    onLogout: () => {},
-  },
-};
+export const Default: Story = {};
 
-export const NoUser: Story = {
-  args: {
-    user: null,
-    onLogout: () => {},
-  },
-};
+export const NoUser: Story = {};

package/components/ui/chart/chart.test.tsx

@@ -56,7 +56,7 @@ describe('Chart Components', () => {
   });
 
   it('renders ChartTooltipContent correctly', () => {
-    const payload = [{ name: 'item1', value: 10, fill: '#000', dataKey: 'label1' }];
+    const payload = [{ name: 'item1', value: 10, fill: '#000', dataKey: 'label1', graphicalItemId: 'item1' }];
 
     // Test the content component directly since Tooltip is tricky
     render(