xertica-ui 2.4.0 → 2.5.0

package/components/brand/xertica-provider/xertica-provider.mdx

@@ -1,61 +1,61 @@
-import { Meta, Title, Subtitle } from '@storybook/addon-docs/blocks';
-
-<Meta title="System/XerticaProvider" />
-
-<Title>XerticaProvider</Title>
-<Subtitle>The recommended root wrapper for shared Xertica UI services.</Subtitle>
-
----
-
-## Overview
-
-The `XerticaProvider` orchestrates the shared services used by complete applications: theme, brand colors, language, API keys, assistant state, layout, tooltips, Google Maps loading, and toast notifications.
-
-Most components have local fallbacks and can render without it, but app shells should still place it at the root so state is synchronized across layout, assistant, maps, theme, and notifications.
-
-```tsx
-import { XerticaProvider } from 'xertica-ui/brand';
-import 'xertica-ui/style.css';
-
-function App() {
-  return (
-    <XerticaProvider>
-      <YourAppContent />
-    </XerticaProvider>
-  );
-}
-```
-
----
-
-## Props
-
-| Prop | Type | Default | Description |
-|---|---|---|---|
-| `children` | `ReactNode` | **Required** | The application content to be wrapped by all providers. |
-| `googleMapsApiKey` | `string` | - | Initial Google Maps JavaScript API key. |
-| `apiKey` | `string` | - | Initial Gemini / AI service API key forwarded to `ApiKeyProvider`. |
-| `defaultBrandTheme` | `string` | - | Initial brand color theme id forwarded to `BrandColorsProvider`. |
-| `primaryColor` | `string` | - | Hex color override for the primary brand token. |
-| `useCustomTokens` | `boolean` | `false` | Skips runtime brand token injection when the host app owns tokens. |
-| `disableDarkMode` | `boolean` | `false` | Forces light mode and disables dark-mode toggling from the theme provider. |
-
----
-
-## What It Provides
-
-1. **Theme, Language, Brand, and API Key Contexts**: Centralizes app-level preferences and service keys.
-2. **Assistant Context**: Provides shared assistant conversation state.
-3. **Layout Context**: Enables `useLayout()` for synchronized sidebar and assistant state.
-4. **Tooltip Provider**: Standardizes Radix tooltip behavior across the app.
-5. **Google Maps Loader**: Handles asynchronous loading of the Maps API.
-6. **Toast Notifications**: Injects the `Sonner` toaster into the DOM.
-
----
-
-## AI Best Practices
-
-> [!CAUTION]
-> - **Recommended App Wrapper** - Components should render independently when possible, but apps should still use this provider once at the root for synchronized state and shared services.
-> - **Environment Safety** - Never hardcode API keys. Always use environment variables when passing them to the provider.
-> - **Toaster Injection** - The provider automatically injects the `Sonner` toaster. Do not add another `<Toaster />` in your app root unless you specifically need to override it.
+import { Meta, Title, Subtitle } from '@storybook/addon-docs/blocks';
+
+<Meta title="System/XerticaProvider" />
+
+<Title>XerticaProvider</Title>
+<Subtitle>The recommended root wrapper for shared Xertica UI services.</Subtitle>
+
+---
+
+## Overview
+
+The `XerticaProvider` orchestrates the shared services used by complete applications: theme, brand colors, language, API keys, assistant state, layout, tooltips, Google Maps loading, and toast notifications.
+
+Most components have local fallbacks and can render without it, but app shells should still place it at the root so state is synchronized across layout, assistant, maps, theme, and notifications.
+
+```tsx
+import { XerticaProvider } from 'xertica-ui/brand';
+import 'xertica-ui/style.css';
+
+function App() {
+  return (
+    <XerticaProvider>
+      <YourAppContent />
+    </XerticaProvider>
+  );
+}
+```
+
+---
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | **Required** | The application content to be wrapped by all providers. |
+| `googleMapsApiKey` | `string` | - | Initial Google Maps JavaScript API key. |
+| `apiKey` | `string` | - | Initial Gemini / AI service API key forwarded to `ApiKeyProvider`. |
+| `defaultBrandTheme` | `string` | - | Initial brand color theme id forwarded to `BrandColorsProvider`. |
+| `primaryColor` | `string` | - | Hex color override for the primary brand token. |
+| `useCustomTokens` | `boolean` | `false` | Skips runtime brand token injection when the host app owns tokens. |
+| `disableDarkMode` | `boolean` | `false` | Forces light mode and disables dark-mode toggling from the theme provider. |
+
+---
+
+## What It Provides
+
+1. **Theme, Language, Brand, and API Key Contexts**: Centralizes app-level preferences and service keys.
+2. **Assistant Context**: Provides shared assistant conversation state.
+3. **Layout Context**: Enables `useLayout()` for synchronized sidebar and assistant state.
+4. **Tooltip Provider**: Standardizes Radix tooltip behavior across the app.
+5. **Google Maps Loader**: Handles asynchronous loading of the Maps API.
+6. **Toast Notifications**: Injects the `Sonner` toaster into the DOM.
+
+---
+
+## AI Best Practices
+
+> [!CAUTION]
+> - **Recommended App Wrapper** - Components should render independently when possible, but apps should still use this provider once at the root for synchronized state and shared services.
+> - **Environment Safety** - Never hardcode API keys. Always use environment variables when passing them to the provider.
+> - **Toaster Injection** - The provider automatically injects the `Sonner` toaster. Do not add another `<Toaster />` in your app root unless you specifically need to override it.

package/components/index.ts

@@ -1,86 +1,86 @@
-/**
- * Xertica UI Library Entry Point
- *
- * @description
- * This file exports all public components, contexts, and utilities of the Xertica UI library.
- * Consumers should import from the root of the package.
- */
-import '../styles/globals.css';
-
-// Xertica UI Styles should be imported by the consumer
-// ============================================================================
-// Xertica Assistant Exports
-// ============================================================================
-
-export { XerticaAssistant } from './assistant/xertica-assistant/xertica-assistant';
-export { XerticaProvider } from './brand/xertica-provider';
-export type {
-  XerticaAssistantProps,
-  Message,
-  Conversation,
-  Suggestion,
-  SearchResult,
-  SearchSource,
-  SearchCommand,
-  MessageType,
-  AttachmentType,
-  SearchResultType,
-  AssistantMode,
-  AssistantTab,
-} from './assistant/xertica-assistant/xertica-assistant';
-
-// ============================================================================
-// Page Components
-// ============================================================================
-
-export * from './pages';
-
-// UI Components - All available via /components/ui/index.ts
-export * from './ui';
-
-// Block Components - High-level composed patterns
-export * from './blocks';
-
-// Utility Components (used by XerticaAssistant)
-export { CodeBlock } from './assistant/code-block';
-export { MarkdownMessage } from './assistant/markdown-message';
-export { ModernChatInput } from './assistant/modern-chat-input';
-export { FormattedDocument } from './assistant/formatted-document';
-
-// Branding
-export { XerticaLogo } from './brand/xertica-logo';
-export { XerticaXLogo } from './brand/xertica-xlogo';
-export { XerticaOrbe } from './brand/xertica-orbe';
-
-// Utility
-export { ImageWithFallback } from './figma/ImageWithFallback';
-
-// Layout
-export { Sidebar } from './layout/sidebar';
-export { ThemeToggle } from './brand/theme-toggle';
-export { LanguageSelector } from './brand/language-selector';
-
-// State Management & Contexts
-export * from '../contexts/LayoutContext';
-
-// Language / i18n
-export { useLanguage, LanguageProvider, DEFAULT_LANGUAGES } from '../contexts/LanguageContext';
-export type {
-  Language,
-  LanguageDefinition,
-  LanguageProviderProps,
-} from '../contexts/LanguageContext';
-export { default as i18n, registerLanguageResource } from '../i18n';
-
-// Layout & Common Components
-export { Header } from './layout/header';
-export type { HeaderProps, BreadcrumbType as HeaderBreadcrumbType } from './layout/header';
-
-// Media Components
-export { VideoPlayer } from './media/video-player/VideoPlayer';
-export { AudioPlayer } from './media/audio-player/AudioPlayer';
-export { FloatingMediaWrapper } from './media/FloatingMediaWrapper';
-// PodcastPlayer was consolidated into AudioPlayer via colorVariant="primary" prop
-
-// Demo utilities (for templates)
-export { gerarResposta, gerarResposta as generateDemoResponse } from './shared/assistant-utils';
+/**
+ * Xertica UI Library Entry Point
+ *
+ * @description
+ * This file exports all public components, contexts, and utilities of the Xertica UI library.
+ * Consumers should import from the root of the package.
+ */
+import '../styles/globals.css';
+
+// Xertica UI Styles should be imported by the consumer
+// ============================================================================
+// Xertica Assistant Exports
+// ============================================================================
+
+export { XerticaAssistant } from './assistant/xertica-assistant/xertica-assistant';
+export { XerticaProvider } from './brand/xertica-provider';
+export type {
+  XerticaAssistantProps,
+  Message,
+  Conversation,
+  Suggestion,
+  SearchResult,
+  SearchSource,
+  SearchCommand,
+  MessageType,
+  AttachmentType,
+  SearchResultType,
+  AssistantMode,
+  AssistantTab,
+} from './assistant/xertica-assistant/xertica-assistant';
+
+// ============================================================================
+// Page Components
+// ============================================================================
+
+export * from './pages';
+
+// UI Components - All available via /components/ui/index.ts
+export * from './ui';
+
+// Block Components - High-level composed patterns
+export * from './blocks';
+
+// Utility Components (used by XerticaAssistant)
+export { CodeBlock } from './assistant/code-block';
+export { MarkdownMessage } from './assistant/markdown-message';
+export { ModernChatInput } from './assistant/modern-chat-input';
+export { FormattedDocument } from './assistant/formatted-document';
+
+// Branding
+export { XerticaLogo } from './brand/xertica-logo';
+export { XerticaXLogo } from './brand/xertica-xlogo';
+export { XerticaOrbe } from './brand/xertica-orbe';
+
+// Utility
+export { ImageWithFallback } from './figma/ImageWithFallback';
+
+// Layout
+export { Sidebar } from './layout/sidebar';
+export { ThemeToggle } from './brand/theme-toggle';
+export { LanguageSelector } from './brand/language-selector';
+
+// State Management & Contexts
+export * from '../contexts/LayoutContext';
+
+// Language / i18n
+export { useLanguage, LanguageProvider, DEFAULT_LANGUAGES } from '../contexts/LanguageContext';
+export type {
+  Language,
+  LanguageDefinition,
+  LanguageProviderProps,
+} from '../contexts/LanguageContext';
+export { default as i18n, registerLanguageResource } from '../i18n';
+
+// Layout & Common Components
+export { Header } from './layout/header';
+export type { HeaderProps, BreadcrumbType as HeaderBreadcrumbType } from './layout/header';
+
+// Media Components
+export { VideoPlayer } from './media/video-player/VideoPlayer';
+export { AudioPlayer } from './media/audio-player/AudioPlayer';
+export { FloatingMediaWrapper } from './media/FloatingMediaWrapper';
+// PodcastPlayer was consolidated into AudioPlayer via colorVariant="primary" prop
+
+// Demo utilities (for templates)
+export { gerarResposta, gerarResposta as generateDemoResponse } from './shared/assistant-utils';

package/components/layout/sidebar/sidebar.mdx

@@ -76,7 +76,7 @@ The expansion state is automatically persisted in a cookie (`sidebar_state`), en
 The Sidebar should ideally be synchronized with the `useLayout()` hook to ensure the main application container adjusts its padding accordingly.
 
 ```tsx
-import { Sidebar } from 'xertica-ui/layout';
+import { Sidebar } from 'xertica-ui/layout';
 import { useLayout } from 'xertica-ui/hooks';
 
 const { sidebarExpanded, toggleSidebar, sidebarWidth } = useLayout();

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