xertica-ui 2.5.2 → 2.6.0

package/components/brand/language-selector/language-selector.mdx

@@ -1,126 +1,126 @@
-import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
-import * as LanguageSelectorStories from './language-selector.stories';
-
-<Meta of={LanguageSelectorStories} />
-
-<Title />
-<Subtitle>A self-contained dropdown for switching the application language, wired to LanguageContext and i18next.</Subtitle>
-
-<Description />
-
-<Primary />
-
----
-
-## Usage
-
-```tsx
-import { LanguageSelector } from 'xertica-ui/brand';
-
-<LanguageSelector />
-```
-
-The component reads the current language from `LanguageContext` and changes it via `setLanguage()` — which persists to `localStorage`, calls `i18n.changeLanguage()`, and invalidates the React Query cache so that mock/API responses also refresh in the new language.
-
-### Minimal variant (short label only)
-
-```tsx
-<LanguageSelector variant="minimal" showIcon={false} />
-```
-
-### Force-visible in a monolingual app
-
-By default, the selector renders `null` when only one language is configured. Pass `showWhenMonolingual` to render anyway:
-
-```tsx
-<LanguageSelector showWhenMonolingual />
-```
-
----
-
-## Props
-
-| Prop | Type | Default | Description |
-|---|---|---|---|
-| `variant` | `'default' \| 'minimal'` | `'default'` | `minimal` uses the short label (e.g. `PT`, `EN`) instead of the full name |
-| `showIcon` | `boolean` | `true` | Show the globe icon next to the label |
-| `showLabel` | `boolean` | `false` | Reserved for future use — currently no visual effect |
-| `className` | `string` | `''` | Additional CSS classes applied to the trigger button |
-| `showWhenMonolingual` | `boolean` | `false` | Render the selector even when only one language is configured (would otherwise auto-hide) |
-
-> The component does **not** accept `initialLanguage` or `onLanguageChange`. Language state lives in `LanguageContext` — read or change it via `useLanguage()`.
-
----
-
-## Supported Languages
-
-By default, the selector exposes the three languages that ship with the library:
-
-| Code | Full label | Short label |
-|---|---|---|
-| `pt-BR` | Português (BR) | PT |
-| `en` | English | EN |
-| `es` | Español | ES |
-
-**The list is fully runtime-configurable.** Pass `availableLanguages` on `<XerticaProvider>` (or `<LanguageProvider>`) to add, remove, or restrict the languages shown.
-
-### Add a new language
-
-```tsx
-import { XerticaProvider, DEFAULT_LANGUAGES } from 'xertica-ui';
-import fr from './locales/fr.json';
-
-<XerticaProvider
-  availableLanguages={[
-    ...DEFAULT_LANGUAGES,
-    { code: 'fr', label: 'Français', shortLabel: 'FR', resources: fr },
-  ]}
->
-  <LanguageSelector />
-  {/* French now appears in the dropdown; its strings are auto-registered with i18next */}
-</XerticaProvider>
-```
-
-### Monolingual app (no selector visible)
-
-```tsx
-<XerticaProvider availableLanguages={[{ code: 'en', label: 'English' }]}>
-  <LanguageSelector />
-  {/* Renders nothing — there is nothing to switch to */}
-</XerticaProvider>
-```
-
-### Programmatic access
-
-```tsx
-import { useLanguage } from 'xertica-ui';
-
-function MyComponent() {
-  const { language, setLanguage, availableLanguages, isMonolingual } = useLanguage();
-  // ...
-}
-```
-
----
-
-## Behavior
-
-- **Reads** `language`, `availableLanguages`, and `isMonolingual` from `useLanguage()`
-- **Persists** the selected language to `localStorage` under the key `xertica_language`
-- **Notifies** `i18next` via `i18n.changeLanguage()` — all components using `useTranslation()` re-render immediately
-- **Invalidates** the React Query cache so mock/API responses translated via `i18n.t()` are refetched in the new language
-- **Auto-hides** when `isMonolingual === true` (single-language apps)
-- **Labels**: known codes (`pt-BR`, `en`, `es`) use translated labels from `assistant.languageSelector.*`. Custom codes fall back to the `label` passed in the `LanguageDefinition`.
-- **Short labels**: when `variant="minimal"`, uses the `shortLabel` from the `LanguageDefinition`, or `code.slice(0, 2).toUpperCase()` as fallback
-
----
-
-## AI Rules
-
-> [!IMPORTANT]
-> - **Placement**: Typically inside `Header` actions (`showLanguageSelector` prop) or the `Sidebar` footer.
-> - **`<LanguageProvider>` is required**: `LanguageSelector` calls `useLanguage()` and throws when rendered outside a `LanguageProvider`. `<XerticaProvider>` provides it automatically.
-> - **Do NOT pass `initialLanguage` or `onLanguageChange`** — these props were removed. Use `useLanguage()` to read or change the language programmatically.
-> - **Do NOT conditionally render this component** for monolingual apps — it self-hides via `isMonolingual`. Use `showWhenMonolingual` only if you explicitly need it visible.
-> - **One instance per layout shell** — multiple selectors create UX confusion. Place a single instance in `Header` or `Sidebar`.
-> - **To support a new language**, pass it via `availableLanguages` on `<XerticaProvider>` — do not modify `LanguageSelector.tsx` or `LanguageContext.tsx`.
+import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
+import * as LanguageSelectorStories from './language-selector.stories';
+
+<Meta of={LanguageSelectorStories} />
+
+<Title />
+<Subtitle>A self-contained dropdown for switching the application language, wired to LanguageContext and i18next.</Subtitle>
+
+<Description />
+
+<Primary />
+
+---
+
+## Usage
+
+```tsx
+import { LanguageSelector } from 'xertica-ui/brand';
+
+<LanguageSelector />
+```
+
+The component reads the current language from `LanguageContext` and changes it via `setLanguage()` — which persists to `localStorage`, calls `i18n.changeLanguage()`, and invalidates the React Query cache so that mock/API responses also refresh in the new language.
+
+### Minimal variant (short label only)
+
+```tsx
+<LanguageSelector variant="minimal" showIcon={false} />
+```
+
+### Force-visible in a monolingual app
+
+By default, the selector renders `null` when only one language is configured. Pass `showWhenMonolingual` to render anyway:
+
+```tsx
+<LanguageSelector showWhenMonolingual />
+```
+
+---
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `variant` | `'default' \| 'minimal'` | `'default'` | `minimal` uses the short label (e.g. `PT`, `EN`) instead of the full name |
+| `showIcon` | `boolean` | `true` | Show the globe icon next to the label |
+| `showLabel` | `boolean` | `false` | Reserved for future use — currently no visual effect |
+| `className` | `string` | `''` | Additional CSS classes applied to the trigger button |
+| `showWhenMonolingual` | `boolean` | `false` | Render the selector even when only one language is configured (would otherwise auto-hide) |
+
+> The component does **not** accept `initialLanguage` or `onLanguageChange`. Language state lives in `LanguageContext` — read or change it via `useLanguage()`.
+
+---
+
+## Supported Languages
+
+By default, the selector exposes the three languages that ship with the library:
+
+| Code | Full label | Short label |
+|---|---|---|
+| `pt-BR` | Português (BR) | PT |
+| `en` | English | EN |
+| `es` | Español | ES |
+
+**The list is fully runtime-configurable.** Pass `availableLanguages` on `<XerticaProvider>` (or `<LanguageProvider>`) to add, remove, or restrict the languages shown.
+
+### Add a new language
+
+```tsx
+import { XerticaProvider, DEFAULT_LANGUAGES } from 'xertica-ui';
+import fr from './locales/fr.json';
+
+<XerticaProvider
+  availableLanguages={[
+    ...DEFAULT_LANGUAGES,
+    { code: 'fr', label: 'Français', shortLabel: 'FR', resources: fr },
+  ]}
+>
+  <LanguageSelector />
+  {/* French now appears in the dropdown; its strings are auto-registered with i18next */}
+</XerticaProvider>
+```
+
+### Monolingual app (no selector visible)
+
+```tsx
+<XerticaProvider availableLanguages={[{ code: 'en', label: 'English' }]}>
+  <LanguageSelector />
+  {/* Renders nothing — there is nothing to switch to */}
+</XerticaProvider>
+```
+
+### Programmatic access
+
+```tsx
+import { useLanguage } from 'xertica-ui';
+
+function MyComponent() {
+  const { language, setLanguage, availableLanguages, isMonolingual } = useLanguage();
+  // ...
+}
+```
+
+---
+
+## Behavior
+
+- **Reads** `language`, `availableLanguages`, and `isMonolingual` from `useLanguage()`
+- **Persists** the selected language to `localStorage` under the key `xertica_language`
+- **Notifies** `i18next` via `i18n.changeLanguage()` — all components using `useTranslation()` re-render immediately
+- **Invalidates** the React Query cache so mock/API responses translated via `i18n.t()` are refetched in the new language
+- **Auto-hides** when `isMonolingual === true` (single-language apps)
+- **Labels**: known codes (`pt-BR`, `en`, `es`) use translated labels from `assistant.languageSelector.*`. Custom codes fall back to the `label` passed in the `LanguageDefinition`.
+- **Short labels**: when `variant="minimal"`, uses the `shortLabel` from the `LanguageDefinition`, or `code.slice(0, 2).toUpperCase()` as fallback
+
+---
+
+## AI Rules
+
+> [!IMPORTANT]
+> - **Placement**: Typically inside `Header` actions (`showLanguageSelector` prop) or the `Sidebar` footer.
+> - **`<LanguageProvider>` is required**: `LanguageSelector` calls `useLanguage()` and throws when rendered outside a `LanguageProvider`. `<XerticaProvider>` provides it automatically.
+> - **Do NOT pass `initialLanguage` or `onLanguageChange`** — these props were removed. Use `useLanguage()` to read or change the language programmatically.
+> - **Do NOT conditionally render this component** for monolingual apps — it self-hides via `isMonolingual`. Use `showWhenMonolingual` only if you explicitly need it visible.
+> - **One instance per layout shell** — multiple selectors create UX confusion. Place a single instance in `Header` or `Sidebar`.
+> - **To support a new language**, pass it via `availableLanguages` on `<XerticaProvider>` — do not modify `LanguageSelector.tsx` or `LanguageContext.tsx`.

package/components/brand/theme-toggle/theme-toggle.mdx

@@ -1,47 +1,47 @@
-import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
-import * as ThemeToggleStories from './theme-toggle.stories';
-
-<Meta of={ThemeToggleStories} />
-
-<Title />
-<Subtitle>Light/dark mode switcher that operates directly on the document root class.</Subtitle>
-
-<Description />
-
-<Primary />
-
----
-
-## Usage
-
-```tsx
-import { ThemeToggle } from 'xertica-ui/brand';
-
-<ThemeToggle />
-```
-
-### With Label
-
-```tsx
-<ThemeToggle showLabel size="md" variant="outline" />
-```
-
-## Props
-
-| Prop | Type | Default | Description |
-|---|---|---|---|
-| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Button size |
-| `variant` | `'default' \| 'outline' \| 'ghost'` | `'ghost'` | Button visual variant |
-| `showLabel` | `boolean` | `false` | Show a text label next to the icon |
-| `className` | `string` | `''` | Extra CSS classes |
-
-## Behavior
-
-`ThemeToggle` reads and writes the `dark` class on `document.documentElement` directly. It does **not** depend on any context provider — it is fully self-contained and safe to use anywhere in the tree.
-
-## AI Rules
-
-> [!IMPORTANT]
-> - **Placement**: Typically placed in the `Sidebar` footer or the `Header` actions area.
-> - **Do not use raw JS** — never toggle dark mode manually. Always use this component or `ThemeToggle`.
-> - **One instance only** per layout — placing multiple toggles causes conflicting state.
+import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
+import * as ThemeToggleStories from './theme-toggle.stories';
+
+<Meta of={ThemeToggleStories} />
+
+<Title />
+<Subtitle>Light/dark mode switcher that operates directly on the document root class.</Subtitle>
+
+<Description />
+
+<Primary />
+
+---
+
+## Usage
+
+```tsx
+import { ThemeToggle } from 'xertica-ui/brand';
+
+<ThemeToggle />
+```
+
+### With Label
+
+```tsx
+<ThemeToggle showLabel size="md" variant="outline" />
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Button size |
+| `variant` | `'default' \| 'outline' \| 'ghost'` | `'ghost'` | Button visual variant |
+| `showLabel` | `boolean` | `false` | Show a text label next to the icon |
+| `className` | `string` | `''` | Extra CSS classes |
+
+## Behavior
+
+`ThemeToggle` reads and writes the `dark` class on `document.documentElement` directly. It does **not** depend on any context provider — it is fully self-contained and safe to use anywhere in the tree.
+
+## AI Rules
+
+> [!IMPORTANT]
+> - **Placement**: Typically placed in the `Sidebar` footer or the `Header` actions area.
+> - **Do not use raw JS** — never toggle dark mode manually. Always use this component or `ThemeToggle`.
+> - **One instance only** per layout — placing multiple toggles causes conflicting state.

package/components/brand/theme-toggle/theme-toggle.test.tsx

@@ -1,5 +1,6 @@
 /** @vitest-environment jsdom */
-import { render, screen, fireEvent } from '@testing-library/react';
+import { screen, fireEvent } from '@testing-library/react';
+import { renderWithProviders as render } from '../../../test/render';
 import { describe, it, expect, beforeEach } from 'vitest';
 import { ThemeToggle } from './ThemeToggle';
 import React from 'react';
@@ -7,6 +8,7 @@ import React from 'react';
 describe('ThemeToggle', () => {
   beforeEach(() => {
     document.documentElement.classList.remove('dark');
+    window.localStorage.clear();
   });
 
   it('toggles theme when clicked', () => {
@@ -26,7 +28,9 @@ describe('ThemeToggle', () => {
   });
 
   it('detects initial dark theme', () => {
-    document.documentElement.classList.add('dark');
+    // ThemeProvider resolves its initial theme from localStorage (storageKey
+    // 'xertica-theme'), not from a pre-existing class on <html>.
+    window.localStorage.setItem('xertica-theme', 'dark');
     render(<ThemeToggle />);
     // Check aria-label or specific icon
     expect(screen.getByLabelText('Mudar para tema claro')).toBeInTheDocument();

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

@@ -1,56 +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/brand';
-
-<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.
+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/brand';
+
+<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-orbe/xertica-orbe.mdx

@@ -1,38 +1,38 @@
-import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
-import * as XerticaOrbeStories from './xertica-orbe.stories';
-
-<Meta of={XerticaOrbeStories} />
-
-<Title />
-<Subtitle>The iconic animated "core" of the Xertica AI assistant.</Subtitle>
-
-<Description />
-
-<Primary />
-
----
-
-## Usage Patterns
-
-### Hero Visualization
-Large-scale orbe for splash screens or empty state illustrations.
-
-<Canvas>
-  <XerticaOrbeStories.Default />
-</Canvas>
-
-### Status Indicator
-Compact version used in toolbars or chat headers to represent assistant presence.
-
-<Canvas>
-  <XerticaOrbeStories.Compact />
-</Canvas>
-
----
-
-## AI Best Practices
-
-> [!IMPORTANT]
-> - **Performance** — The animation is powered by Lottie. The component dynamically loads the `bodymovin` library from a CDN on mount to keep the bundle small.
-> - **Interactivity** — The orbe reacts to `mouseenter` and `mouseleave` events by accelerating its spin speed, providing a subtle interactive cue.
-> - **Placement** — Should typically be used in context with the AI assistant or brand-heavy marketing pages.
+import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
+import * as XerticaOrbeStories from './xertica-orbe.stories';
+
+<Meta of={XerticaOrbeStories} />
+
+<Title />
+<Subtitle>The iconic animated "core" of the Xertica AI assistant.</Subtitle>
+
+<Description />
+
+<Primary />
+
+---
+
+## Usage Patterns
+
+### Hero Visualization
+Large-scale orbe for splash screens or empty state illustrations.
+
+<Canvas>
+  <XerticaOrbeStories.Default />
+</Canvas>
+
+### Status Indicator
+Compact version used in toolbars or chat headers to represent assistant presence.
+
+<Canvas>
+  <XerticaOrbeStories.Compact />
+</Canvas>
+
+---
+
+## AI Best Practices
+
+> [!IMPORTANT]
+> - **Performance** — The animation is powered by Lottie. The component dynamically loads the `bodymovin` library from a CDN on mount to keep the bundle small.
+> - **Interactivity** — The orbe reacts to `mouseenter` and `mouseleave` events by accelerating its spin speed, providing a subtle interactive cue.
+> - **Placement** — Should typically be used in context with the AI assistant or brand-heavy marketing pages.