xertica-ui 1.9.3 → 1.9.5

package/CHANGELOG.md

@@ -7,6 +7,33 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [1.10.0] — 2026-05-08
+
+### Added
+
+- **Semantic Variants** — Added `success`, `info`, and `warning` variants to components that lacked them:
+  - **Button** — now supports 9 variants: `default`, `secondary`, `outline`, `ghost`, `destructive`, `link`, `success`, `info`, `warning`.
+  - **Progress** — new `variant` prop (`default`, `success`, `info`, `warning`, `destructive`) colors both the track and the indicator.
+  - **NotificationBadge** — added `secondary`, `outline`, `success`, `info`, `warning`; standardized `default` to primary color for consistency with Badge and Button.
+  - **TimelineDot** — added `info` and `outline` variants; replaced hardcoded `rgb()` values with semantic CSS tokens (`bg-success`, `bg-warning`).
+- **DialogBody** — new sub-component for the Dialog. When used, `DialogHeader` and `DialogFooter` stay pinned while `DialogBody` scrolls independently. Exported from `xertica-ui`.
+- **Dialog height management** — `DialogContent` now has `max-h-[calc(100dvh-2rem)] overflow-hidden`. The close button (×) is pinned and never scrolls with content. `size="full"` fills the full viewport height.
+- **Header `breadcrumbSlot`** — new prop accepting any `ReactNode` rendered immediately after the breadcrumb/title area (badges, buttons, status chips, etc.).
+- **Sidebar default variant groups** — `variant="default"` now renders `navigationGroups` with labeled group headers. Each `RouteConfig` supports a `children` field (sub-routes shown in a contextual `DropdownMenu` via a `ChevronRight` button at the end of the item).
+
+### Fixed
+
+- **Search double clear icon** — `type="search"` caused browsers to inject a native clear button on top of the custom × icon. Changed to `type="text"`.
+- **CSS `@source` path** — CLI template `src/styles/index.css` had `../node_modules/xertica-ui` (one level short); corrected to `../../node_modules/xertica-ui/components`.
+- **`theme-map.css` incomplete** — `--color-success`, `--color-info`, `--color-warning` and their `foreground` variants were missing, preventing `bg-success`, `text-info`, etc. from being generated in the compiled library CSS.
+
+### Changed
+
+- **Storybook argTypes** — Multiple components had controls missing from the Storybook panel: Badge (`success`/`info`/`warning` options), Select (`size`), Avatar (`size`), Rating (`readonly` casing), Timeline (`dotVariant`), Dialog (`size` available in all stories). All corrected.
+- **LLM documentation** (`llms-full.txt`) — Updated Badge, Button, Dialog, Header, NotificationBadge, Progress, Search, Sidebar, and Timeline sections to reflect current APIs.
+
+---
+
 ## [1.9.0] — 2026-05-05
 
 ### Added

package/components/assistant/xertica-assistant/xertica-assistant.tsx

@@ -211,11 +211,11 @@ export interface Message {
  */
 export interface Conversation {
   id: string;
-  titulo: string;
-  ultimaMensagem?: string;
+  title: string;
+  lastMessage?: string;
   timestamp: string;
-  favorita: boolean;
-  mensagens: Message[];
+  isFavorite: boolean;
+  messages: Message[];
 }
 
 /**
@@ -223,7 +223,7 @@ export interface Conversation {
  */
 export interface Suggestion {
   id: string;
-  texto: string;
+  text: string;
   icon?: React.ReactNode;
 }
 
@@ -550,10 +550,10 @@ export function XerticaAssistant({
   // ============================================================================
 
   const defaultSuggestions: Suggestion[] = [
-    { id: '1', texto: 'Me ajude a criar um documento profissional' },
-    { id: '2', texto: 'Buscar nos meus arquivos por "relatório"' },
-    { id: '3', texto: 'Resuma as conversas importantes desta semana' },
-    { id: '4', texto: 'Crie um podcast sobre o último projeto' },
+    { id: '1', text: 'Me ajude a criar um documento profissional' },
+    { id: '2', text: 'Buscar nos meus arquivos por "relatório"' },
+    { id: '3', text: 'Resuma as conversas importantes desta semana' },
+    { id: '4', text: 'Crie um podcast sobre o último projeto' },
   ];
 
   const sugestoes = propSuggestions ?? defaultSuggestions;
@@ -765,7 +765,7 @@ export function XerticaAssistant({
   const handleSelecionarConversa = (conversaId: string) => {
     const conversa = conversas.find(c => c.id === conversaId);
     if (conversa) {
-      setMensagens(conversa.mensagens);
+      setMensagens(conversa.messages);
       setConversaAtual(conversaId);
       setAbaSelecionada('chat');
     }
@@ -774,7 +774,7 @@ export function XerticaAssistant({
   const handleToggleFavoritaConversa = (conversaId: string) => {
     setConversas(prev =>
       prev.map(conv =>
-        conv.id === conversaId ? { ...conv, favorita: !conv.favorita } : conv
+        conv.id === conversaId ? { ...conv, isFavorite: !conv.isFavorite } : conv
       )
     );
   };
@@ -803,10 +803,10 @@ export function XerticaAssistant({
 
   const handleRichSuggestionClick = (suggestion: Suggestion) => {
     if (onRichAction) {
-      onRichAction(suggestion.id, suggestion.texto);
+      onRichAction(suggestion.id, suggestion.text);
     } else {
       // Fallback: send as message
-      handleEnviarMensagem(suggestion.texto);
+      handleEnviarMensagem(suggestion.text);
     }
     setShowMoreSuggestions(false);
   };
@@ -853,7 +853,7 @@ export function XerticaAssistant({
 
   const conversasFiltradas = conversas.filter(conversa => {
     if (abaSelecionada === 'favoritos') {
-      return conversa.favorita;
+      return conversa.isFavorite;
     }
     return true;
   });
@@ -1197,10 +1197,10 @@ export function XerticaAssistant({
                           {sugestoes.map((sugestao) => (
                             <button
                               key={sugestao.id}
-                              onClick={() => handleEnviarMensagem(sugestao.texto)}
+                              onClick={() => handleEnviarMensagem(sugestao.text)}
                               className="w-full p-3 text-left rounded-[var(--radius-card)] bg-muted text-foreground transition-colors duration-200 hover:bg-muted/80"
                             >
-                              {sugestao.texto}
+                              {sugestao.text}
                             </button>
                           ))}
 
@@ -1226,7 +1226,7 @@ export function XerticaAssistant({
                                     <div className="flex items-center gap-2">
                                       {sugestao.id.includes('chart') && <BarChart3 className="w-4 h-4 text-primary" />}
                                       {sugestao.id.includes('table') && <TableIcon className="w-4 h-4 text-primary" />}
-                                      <span className="font-medium">{sugestao.texto}</span>
+                                      <span className="font-medium">{sugestao.text}</span>
                                     </div>
                                   </button>
                                 ))
@@ -1767,7 +1767,7 @@ export function XerticaAssistant({
                             >
                               <div className="flex items-start justify-between mb-1">
                                 <h4 className="text-sm font-medium text-foreground truncate flex-1">
-                                  {conversa.titulo}
+                                  {conversa.title}
                                 </h4>
                                 <Button
                                   variant="ghost"
@@ -1781,14 +1781,14 @@ export function XerticaAssistant({
                                   <Heart
                                     className={cn(
                                       "w-3 h-3",
-                                      conversa.favorita ? "text-destructive fill-current" : "text-muted-foreground"
+                                      conversa.isFavorite ? "text-destructive fill-current" : "text-muted-foreground"
                                     )}
                                   />
                                 </Button>
                               </div>
-                              {conversa.ultimaMensagem && (
+                              {conversa.lastMessage && (
                                 <p className="text-sm text-muted-foreground truncate mb-1">
-                                  {conversa.ultimaMensagem}
+                                  {conversa.lastMessage}
                                 </p>
                               )}
                               <p className="text-sm text-muted-foreground">

package/components/brand/branding/branding.mdx

@@ -22,6 +22,6 @@ The standard Xertica.ai logo, available in multiple color variants to suit diffe
 ## AI Best Practices
 
 > [!IMPORTANT]
-> - **Variants** — Use the `white` variant on dark backgrounds and the `dark` or `brand` variant on light backgrounds. Use `theme` for automatic adjustment.
+> - **Variants** — Use `default` on light/neutral backgrounds, `white` on dark or colored backgrounds, and `theme` to inherit the surrounding text color. There is no `brand` or `dark` variant.
 > - **Scaling** — Always specify a height (`h-*`) and use `w-auto` to maintain the correct aspect ratio.
 > - **Icon Usage** — Use `XerticaXLogo` for favicon-like placements, profile avatars, or collapsed sidebars where horizontal space is limited.

package/components/brand/branding/branding.stories.tsx

@@ -19,12 +19,12 @@ export const Logos: StoryObj = {
         <h3 className="text-lg font-semibold text-muted-foreground border-b pb-2">Full Logo</h3>
         <div className="flex flex-wrap gap-8 items-center bg-muted/20 p-8 rounded-xl">
           <div className="space-y-2 text-center">
-            <XerticaLogo variant="brand" className="h-10 w-auto" />
-            <span className="text-xs text-muted-foreground">Brand</span>
+            <XerticaLogo variant="default" className="h-10 w-auto" />
+            <span className="text-xs text-muted-foreground">Default</span>
           </div>
           <div className="space-y-2 text-center">
-            <XerticaLogo variant="dark" className="h-10 w-auto" />
-            <span className="text-xs text-muted-foreground">Dark</span>
+            <XerticaLogo variant="theme" className="h-10 w-auto" />
+            <span className="text-xs text-muted-foreground">Theme</span>
           </div>
           <div className="space-y-2 text-center bg-slate-900 p-4 rounded-lg">
             <XerticaLogo variant="white" className="h-10 w-auto" />

package/components/brand/xertica-logo/XerticaLogo.stories.tsx

@@ -0,0 +1,82 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { XerticaLogo } from './XerticaLogo';
+import React from 'react';
+
+const meta: Meta<typeof XerticaLogo> = {
+  title: 'Brand/XerticaLogo',
+  component: XerticaLogo,
+  parameters: {
+    layout: 'centered',
+  },
+  argTypes: {
+    variant: {
+      control: 'select',
+      options: ['default', 'white', 'theme'],
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof XerticaLogo>;
+
+export const Default: Story = {
+  args: {
+    variant: 'default',
+    className: 'h-10 w-auto',
+  },
+};
+
+export const White: Story = {
+  args: {
+    variant: 'white',
+    className: 'h-10 w-auto',
+  },
+  decorators: [
+    (Story) => (
+      <div className="bg-slate-900 p-8 rounded-xl">
+        <Story />
+      </div>
+    ),
+  ],
+};
+
+export const Theme: Story = {
+  args: {
+    variant: 'theme',
+    className: 'h-10 w-auto text-blue-600',
+  },
+};
+
+export const AllVariants: Story = {
+  render: () => (
+    <div className="space-y-8 p-6">
+      <div className="space-y-2">
+        <p className="text-xs text-muted-foreground font-mono">variant="default"</p>
+        <XerticaLogo variant="default" className="h-10 w-auto" />
+      </div>
+      <div className="space-y-2 bg-slate-900 p-6 rounded-xl">
+        <p className="text-xs text-slate-400 font-mono">variant="white"</p>
+        <XerticaLogo variant="white" className="h-10 w-auto" />
+      </div>
+      <div className="space-y-2">
+        <p className="text-xs text-muted-foreground font-mono">variant="theme" (text-blue-600)</p>
+        <XerticaLogo variant="theme" className="h-10 w-auto text-blue-600" />
+      </div>
+      <div className="space-y-2">
+        <p className="text-xs text-muted-foreground font-mono">color="#e11d48" (direct override)</p>
+        <XerticaLogo color="#e11d48" className="h-10 w-auto" />
+      </div>
+    </div>
+  ),
+};
+
+export const Sizes: Story = {
+  render: () => (
+    <div className="flex flex-col gap-6 p-6 items-start">
+      <XerticaLogo className="h-6 w-auto" />
+      <XerticaLogo className="h-8 w-auto" />
+      <XerticaLogo className="h-10 w-auto" />
+      <XerticaLogo className="h-14 w-auto" />
+    </div>
+  ),
+};

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

@@ -0,0 +1,56 @@
+import { Meta, Title, Subtitle, Description } from '@storybook/addon-docs/blocks';
+
+<Meta title="Brand/XerticaLogo" />
+
+<Title>XerticaLogo</Title>
+<Subtitle>Full Xertica.ai wordmark (X-symbol + text) as a responsive SVG.</Subtitle>
+
+---
+
+## Overview
+
+`XerticaLogo` renders the complete Xertica brand identity — the X symbol alongside the wordmark text. It adapts to different backgrounds through its `variant` prop and supports a direct `color` override for edge cases.
+
+```tsx
+import { XerticaLogo } from 'xertica-ui';
+
+<XerticaLogo className="h-8 w-auto" />
+```
+
+---
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `variant` | `'default' \| 'white' \| 'theme'` | `'default'` | Color variant. `default` uses `var(--primary)`, `white` forces white fill, `theme` inherits `currentColor`. |
+| `color` | `string` | — | Direct color override (CSS color value). Overrides `variant`. |
+| `className` | `string` | `'w-auto h-8'` | Additional CSS classes applied to the SVG element. |
+
+---
+
+## Variants
+
+```tsx
+// Light background — primary brand color
+<XerticaLogo variant="default" className="h-8 w-auto" />
+
+// Dark background — white fill
+<XerticaLogo variant="white" className="h-8 w-auto" />
+
+// Inherits text color from parent (useful on colored backgrounds)
+<XerticaLogo variant="theme" className="h-8 w-auto" />
+
+// Direct color override
+<XerticaLogo color="#1D4ED8" className="h-8 w-auto" />
+```
+
+---
+
+## AI Best Practices
+
+> [!IMPORTANT]
+> - **Variant selection** — Use `default` on light/neutral backgrounds, `white` on dark or colored backgrounds, and `theme` when the logo should inherit the surrounding text color.
+> - **Sizing** — Always set a height (`h-*`) and use `w-auto` to preserve the correct aspect ratio. Never set both width and height to fixed values.
+> - **Icon-only contexts** — Use `XerticaXLogo` instead of `XerticaLogo` in compact spaces such as collapsed sidebars, favicons, or avatars.
+> - **No `dark` or `brand` variants** — These are not valid. Use `default` for brand-color rendering.

package/components/brand/xertica-logo/xertica-logo.test.tsx

@@ -20,7 +20,7 @@ describe('XerticaLogo', () => {
     // Verification depends on implementation (e.g. fill color)
     expect(container.querySelector('svg')).toBeInTheDocument();
     
-    rerender(<XerticaLogo variant="brand" />);
+    rerender(<XerticaLogo variant="theme" />);
     expect(container.querySelector('svg')).toBeInTheDocument();
   });
 });

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

@@ -31,11 +31,12 @@ interface XerticaProviderProps {
  * This component aggregates all necessary context providers. It should be placed at the 
  * root of your application, ideally inside the App component.
  */
-export function XerticaProvider({ 
-    children
+export function XerticaProvider({
+    children,
+    googleMapsApiKey,
 }: XerticaProviderProps) {
     return (
-        <GoogleMapsLoaderProvider>
+        <GoogleMapsLoaderProvider apiKey={googleMapsApiKey}>
             <LayoutProvider>
                 <TooltipProvider>
                     {children}

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

@@ -32,9 +32,13 @@ function App() {
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `children` | `ReactNode` | **Required** | The application content |
-
-> **Note**: As of version 1.6+, brand colors, API keys, and language state are managed independently or via CSS tokens to increase modularity and performance.
+| `children` | `ReactNode` | **Required** | The application content to be wrapped by all providers. |
+| `googleMapsApiKey` | `string` | — | Google Maps JavaScript API key. Passed to `GoogleMapsLoaderProvider` to enable map components (`SimpleMap`, `MapShowcase`, etc.). |
+| `apiKey` | `string` | — | Gemini / AI service API key for AI-powered features. Accepted by the provider but not yet wired to a default context — pass explicitly to AI components that require it. |
+| `defaultBrandTheme` | `string` | — | Initial theme name (e.g., `'default'`, `'dark'`). Intended for future theme-switching support. |
+| `primaryColor` | `string` | — | Hex color override for the primary brand token. When set, updates `--primary` at runtime. |
+| `useCustomTokens` | `boolean` | `false` | When `true`, skips injecting the library's default CSS token set, relying entirely on the host application's tokens. |
+| `disableDarkMode` | `boolean` | `false` | When `true`, prevents the library from applying dark-mode class or media-query overrides. |
 
 ---
 

package/components/brand/xertica-xlogo/XerticaXLogo.stories.tsx

@@ -0,0 +1,79 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { XerticaXLogo } from './XerticaXLogo';
+import React from 'react';
+
+const meta: Meta<typeof XerticaXLogo> = {
+  title: 'Brand/XerticaXLogo',
+  component: XerticaXLogo,
+  parameters: {
+    layout: 'centered',
+  },
+  argTypes: {
+    variant: {
+      control: 'select',
+      options: ['default', 'white', 'theme'],
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof XerticaXLogo>;
+
+export const Default: Story = {
+  args: {
+    variant: 'default',
+    className: 'h-12 w-12',
+  },
+};
+
+export const White: Story = {
+  args: {
+    variant: 'white',
+    className: 'h-12 w-12',
+  },
+  decorators: [
+    (Story) => (
+      <div className="bg-slate-900 p-8 rounded-xl">
+        <Story />
+      </div>
+    ),
+  ],
+};
+
+export const Theme: Story = {
+  args: {
+    variant: 'theme',
+    className: 'h-12 w-12 text-blue-600',
+  },
+};
+
+export const AllVariants: Story = {
+  render: () => (
+    <div className="flex flex-wrap gap-10 p-6 items-end">
+      <div className="space-y-2 text-center">
+        <XerticaXLogo variant="default" className="h-12 w-12" />
+        <p className="text-xs text-muted-foreground">default</p>
+      </div>
+      <div className="space-y-2 text-center bg-slate-900 p-4 rounded-xl">
+        <XerticaXLogo variant="white" className="h-12 w-12" />
+        <p className="text-xs text-slate-400">white</p>
+      </div>
+      <div className="space-y-2 text-center">
+        <XerticaXLogo variant="theme" className="h-12 w-12 text-blue-600" />
+        <p className="text-xs text-muted-foreground">theme</p>
+      </div>
+      <div className="space-y-2 text-center">
+        <XerticaXLogo color="#e11d48" className="h-12 w-12" />
+        <p className="text-xs text-muted-foreground">color override</p>
+      </div>
+    </div>
+  ),
+};
+
+export const CollapsedSidebarSlot: Story = {
+  render: () => (
+    <div className="flex items-center justify-center w-20 h-16 bg-sidebar border-r border-border">
+      <XerticaXLogo className="h-7 w-7" />
+    </div>
+  ),
+};

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

@@ -0,0 +1,55 @@
+import { Meta, Title, Subtitle } from '@storybook/addon-docs/blocks';
+
+<Meta title="Brand/XerticaXLogo" />
+
+<Title>XerticaXLogo</Title>
+<Subtitle>Compact X-symbol mark for favicons, avatars, and collapsed sidebar slots.</Subtitle>
+
+---
+
+## Overview
+
+`XerticaXLogo` renders only the X-symbol portion of the Xertica identity. It shares the same prop API as `XerticaLogo` and is the preferred choice wherever horizontal space is constrained.
+
+```tsx
+import { XerticaXLogo } from 'xertica-ui';
+
+<XerticaXLogo className="h-8 w-8" />
+```
+
+---
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `variant` | `'default' \| 'white' \| 'theme'` | `'default'` | Color variant. `default` uses `var(--primary)`, `white` forces white fill, `theme` inherits `currentColor`. |
+| `color` | `string` | — | Direct color override. Overrides `variant`. |
+| `className` | `string` | `'w-auto h-8'` | Additional CSS classes applied to the SVG element. |
+
+---
+
+## Usage Examples
+
+```tsx
+// Default — primary color
+<XerticaXLogo className="h-10 w-10" />
+
+// On a dark background
+<XerticaXLogo variant="white" className="h-10 w-10" />
+
+// Inherits current text color
+<XerticaXLogo variant="theme" className="h-10 w-10 text-blue-600" />
+
+// Collapsed sidebar icon slot
+<XerticaXLogo className="h-6 w-6 shrink-0" />
+```
+
+---
+
+## AI Best Practices
+
+> [!IMPORTANT]
+> - **Square sizing** — Unlike the full logo, set both width and height to the same value (e.g., `h-10 w-10`) since the X symbol has a near-square aspect ratio (viewBox `0 0 258 282`).
+> - **Favicon** — Export as a PNG at 32×32 and 192×192 for web manifest icons; do not use the SVG component directly in `<link rel="icon">`.
+> - **Collapsed sidebar** — Replace the full `XerticaLogo` with `XerticaXLogo` when `sidebarExpanded === false` to avoid clipping.

package/components/layout/header/header.stories.tsx

@@ -1,8 +1,10 @@
 import type { Meta, StoryObj } from '@storybook/react';
 import { Header } from './header';
 import { BrowserRouter, Link } from 'react-router-dom';
-import { Home, Bell, Mail, User, Settings, LogOut, Users, FileText, FolderOpen } from 'lucide-react';
+import { Home, Bell, Mail, User, Settings, LogOut, Users, FileText, FolderOpen, RefreshCw } from 'lucide-react';
 import React from 'react';
+import { Badge } from '../../ui/badge';
+import { Button } from '../../ui/button';
 
 const meta: Meta<typeof Header> = {
   title: 'Layout/Header',
@@ -144,6 +146,32 @@ export const CustomUserMenu: Story = {
   }
 };
 
+/**
+ * Breadcrumb slot: custom element rendered right after the breadcrumb area.
+ * Accepts any React node — badges, buttons, status chips, etc.
+ */
+export const WithBreadcrumbSlot: Story = {
+  args: {
+    breadcrumbs: [
+      { label: 'Home', href: '/', icon: <Home className="size-4" /> },
+      { label: 'Deployments' },
+    ],
+    breadcrumbSlot: (
+      <div className="flex items-center gap-2">
+        <Badge variant="warning">Beta</Badge>
+        <Button variant="outline" size="sm">
+          <RefreshCw className="size-3.5" />
+          Sync
+        </Button>
+      </div>
+    ),
+    user: {
+      name: 'Pedro Duarte',
+      email: 'pedro@example.com',
+    },
+  },
+};
+
 /**
  * SPA Navigation: uses `renderLink` with React Router's `Link` component
  * to prevent full-page reloads when navigating breadcrumbs.

package/components/layout/header/header.tsx

@@ -94,6 +94,19 @@ export interface HeaderProps {
     showLogout?: boolean;
     /** Click handler for logout */
     onLogoutClick?: () => void;
+    /**
+     * Custom element rendered immediately after the breadcrumb / title area.
+     * Accepts any React node — badges, buttons, status chips, etc.
+     *
+     * @example
+     * ```tsx
+     * <Header
+     *   breadcrumbs={[...]}
+     *   breadcrumbSlot={<Badge variant="warning">Beta</Badge>}
+     * />
+     * ```
+     */
+    breadcrumbSlot?: React.ReactNode;
     /**
      * Custom link renderer for breadcrumb navigation.
      * Use this to integrate with client-side routers (e.g., React Router, Next.js Link)
@@ -147,6 +160,7 @@ export function Header({
     showLogout,
     onLogoutClick,
     renderLink,
+    breadcrumbSlot,
 }: HeaderProps) {
     const { sidebarExpanded, toggleSidebar } = useLayout();
 
@@ -209,6 +223,12 @@ export function Header({
                             </BreadcrumbList>
                         </Breadcrumb>
                     )}
+                    {/* Breadcrumb slot */}
+                    {breadcrumbSlot && (
+                        <div className="flex items-center shrink-0">
+                            {breadcrumbSlot}
+                        </div>
+                    )}
                 </div>
 
                 {/* User controls */}