xertica-ui 2.3.0 → 2.4.0

package/docs/components/branding.md

@@ -1,252 +1,252 @@
-# Branding — Xertica UI
-
-The branding system in Xertica UI provides tools for applying, customizing, and switching the visual identity of an application — including color themes, logos, language, and dark/light mode.
-
----
-
-## Brand Components Overview
-
-| Component          | Import             | Purpose                                                 |
-| ------------------ | ------------------ | ------------------------------------------------------- |
-| `XerticaProvider`  | `xertica-ui/brand` | Root provider for all brand, theme, and layout contexts |
-| `ThemeToggle`      | `xertica-ui/brand` | Self-contained dark/light mode switcher                 |
-| `LanguageSelector` | `xertica-ui/brand` | Standalone language dropdown (pt-BR / en / es)          |
-| `XerticaLogo`      | `xertica-ui/brand` | Full horizontal Xertica logotype SVG                    |
-| `XerticaXLogo`     | `xertica-ui/brand` | Compact X-mark logo variant                             |
-| `XerticaOrbe`      | `xertica-ui/brand` | Animated orb brand mark                                 |
-
----
-
-## Color Theme System
-
-### How It Works
-
-Xertica UI uses CSS custom properties (design tokens) for all colors. The theme is applied by injecting token values at `:root` and `.dark`. Tailwind v4 maps these tokens via `@theme inline`.
-
-```
-tokens.css → :root { --primary: ...; --background: ...; }
-           → .dark { --primary: ...; --background: ...; }
-           → @theme inline { --color-primary: var(--primary); }
-           → Tailwind utilities: bg-primary, text-foreground, etc.
-```
-
-### Available Theme Presets
-
-The CLI (`npx xertica-ui@latest init` or `npx xertica-ui@latest update-theme`) offers multiple color presets. Each preset defines a complete set of tokens for both light and dark modes.
-
-### Customizing Colors Programmatically
-
-Use `useBrandColors` to read and modify brand colors at runtime:
-
-```tsx
-import { useBrandColors } from 'xertica-ui/hooks';
-
-function BrandCustomizer() {
-  const { colors, setBrandColor } = useBrandColors();
-
-  return (
-    <div className="space-y-2">
-      <label>Primary Color</label>
-      <input
-        type="color"
-        value={colors.primary}
-        onChange={e => setBrandColor('primary', e.target.value)}
-      />
-    </div>
-  );
-}
-```
-
-Changes are applied immediately as CSS variables on `:root`.
-
----
-
-## Dark / Light Mode
-
-### `ThemeToggle`
-
-A self-contained button that toggles between light and dark mode. Does not require any context provider — it reads and writes `document.documentElement.classList` directly.
-
-```tsx
-import { ThemeToggle } from 'xertica-ui/brand';
-
-// Place in Header actions or Sidebar footer
-<ThemeToggle size="sm" />;
-```
-
-**Props:**
-
-| Prop        | Type                   | Default | Description            |
-| ----------- | ---------------------- | ------- | ---------------------- |
-| `size`      | `'sm' \| 'md' \| 'lg'` | `'md'`  | Button size            |
-| `className` | `string`               | —       | Additional CSS classes |
-
-### `useTheme` Hook
-
-For programmatic theme control:
-
-```tsx
-import { useTheme } from 'xertica-ui/hooks';
-
-function ThemeController() {
-  const { theme, setTheme, toggleTheme } = useTheme();
-  return <button onClick={toggleTheme}>Mode: {theme}</button>;
-}
-```
-
-> **Note**: `useTheme` requires `<XerticaProvider>` in the tree. `ThemeToggle` works without any provider.
-
----
-
-## Language Selector
-
-### `LanguageSelector`
-
-A standalone dropdown for switching the UI language preference.
-
-```tsx
-import { LanguageSelector } from 'xertica-ui/brand';
-
-// Typically placed in PageHeader or Sidebar footer
-<LanguageSelector />;
-```
-
-The selected language is persisted in `localStorage` under `xertica_language`. Access the current value via `useLanguage()`:
-
-```tsx
-import { useLanguage } from 'xertica-ui/hooks';
-
-function MyComponent() {
-  const { language, availableLanguages, isMonolingual } = useLanguage();
-  // language is `string` (e.g. 'pt-BR', 'en', 'fr') — the set is runtime-configurable
-}
-```
-
-The set of available languages is configured at runtime via the `availableLanguages` prop on `<XerticaProvider>` (defaults to `pt-BR`, `en`, `es`). See [`docs/i18n.md`](../i18n.md) for the full extension API. When only one language is configured, the `LanguageSelector` auto-hides.
-
----
-
-## Logo Components
-
-### `XerticaLogo`
-
-Full horizontal logotype. Use in the Sidebar header or login page.
-
-```tsx
-import { XerticaLogo } from 'xertica-ui/brand';
-
-<XerticaLogo className="h-8" />;
-```
-
-### `XerticaXLogo`
-
-Compact X-mark variant. Use when space is limited (collapsed sidebar, favicon-like contexts).
-
-```tsx
-import { XerticaXLogo } from 'xertica-ui/brand';
-
-<XerticaXLogo className="w-8 h-8" />;
-```
-
-### `XerticaOrbe`
-
-Animated orb brand mark. Use as a decorative element or loading indicator.
-
-```tsx
-import { XerticaOrbe } from 'xertica-ui/brand';
-
-<XerticaOrbe size={64} />;
-```
-
----
-
-## `XerticaProvider`
-
-The root provider that initializes all brand, theme, layout, and service contexts. Must wrap the entire application once.
-
-```tsx
-import { XerticaProvider } from 'xertica-ui/brand';
-import 'xertica-ui/style.css';
-
-ReactDOM.createRoot(document.getElementById('root')!).render(
-  <React.StrictMode>
-    <XerticaProvider>
-      <App />
-    </XerticaProvider>
-  </React.StrictMode>
-);
-```
-
-`XerticaProvider` initializes:
-
-- `ThemeProvider` — dark/light mode
-- `LanguageProvider` — language preference
-- `BrandColorsProvider` — brand color tokens
-- `LayoutProvider` — sidebar and assistant state
-- `AssistenteProvider` — AI assistant context
-- `ApiKeyProvider` — API key management
-- `GoogleMapsLoaderProvider` — lazy Maps API loading
-- `TooltipProvider` — Radix tooltip context
-- `Toaster` — Sonner toast notifications
-
-**Props:**
-
-| Prop                  | Type        | Default      | Description                                 |
-| --------------------- | ----------- | ------------ | ------------------------------------------- |
-| `children`            | `ReactNode` | _(required)_ | Application content                         |
-| `googleMapsApiKey`    | `string`    | —            | Google Maps API key (activates Maps loader) |
-| `initialApiKey`       | `string`    | —            | Pre-set Xertica API key                     |
-| `initialGeminiApiKey` | `string`    | —            | Pre-set Gemini API key                      |
-
----
-
-## CSS Token Structure
-
-The complete token set is defined in `tokens.css` (generated by the CLI). Key token groups:
-
-```css
-:root {
-  /* Colors */
-  --background: 0 0% 100%;
-  --foreground: 222.2 84% 4.9%;
-  --primary: 221.2 83.2% 53.3%;
-  --primary-foreground: 210 40% 98%;
-  --secondary: 210 40% 96.1%;
-  --muted: 210 40% 96.1%;
-  --muted-foreground: 215.4 16.3% 46.9%;
-  --accent: 210 40% 96.1%;
-  --destructive: 0 84.2% 60.2%;
-  --border: 214.3 31.8% 91.4%;
-  --input: 214.3 31.8% 91.4%;
-  --ring: 221.2 83.2% 53.3%;
-  --card: 0 0% 100%;
-  --card-foreground: 222.2 84% 4.9%;
-
-  /* Chart colors */
-  --chart-1: 221.2 83.2% 53.3%;
-  --chart-2: 142.1 76.2% 36.3%;
-  --chart-3: 47.9 95.8% 53.1%;
-  --chart-4: 280.1 65.3% 60%;
-  --chart-5: 24.6 95% 53.1%;
-
-  /* Sidebar */
-  --sidebar: 222.2 84% 4.9%;
-  --sidebar-foreground: 210 40% 98%;
-
-  /* Shape */
-  --radius: 0.5rem;
-  --radius-button: 0.375rem;
-}
-```
-
----
-
-## AI Rules
-
-> [!IMPORTANT]
->
-> - **`XerticaProvider` is required once**: Place it at the root of your application. Never nest multiple `XerticaProvider` instances.
-> - **Never use raw hex/rgb colors**: All colors must use semantic tokens (`bg-primary`, `text-destructive`, `border-border`). Raw values like `#3b82f6` or `rgb(59, 130, 246)` are forbidden.
-> - **`ThemeToggle` is self-contained**: It does not need `useTheme` or any context. Use it directly in any component without provider requirements.
-> - **Logo sizing via `className`**: Size logo components using Tailwind height/width classes (`h-8`, `w-8`). Do not use `width`/`height` HTML attributes.
-> - **Language is preference only**: `LanguageSelector` stores a preference. The library UI renders in Portuguese regardless. Implement your own i18n logic using the `language` value from `useLanguage()`.
+# Branding — Xertica UI
+
+The branding system in Xertica UI provides tools for applying, customizing, and switching the visual identity of an application — including color themes, logos, language, and dark/light mode.
+
+---
+
+## Brand Components Overview
+
+| Component          | Import             | Purpose                                                 |
+| ------------------ | ------------------ | ------------------------------------------------------- |
+| `XerticaProvider`  | `xertica-ui/brand` | Root provider for all brand, theme, and layout contexts |
+| `ThemeToggle`      | `xertica-ui/brand` | Self-contained dark/light mode switcher                 |
+| `LanguageSelector` | `xertica-ui/brand` | Standalone language dropdown (pt-BR / en / es)          |
+| `XerticaLogo`      | `xertica-ui/brand` | Full horizontal Xertica logotype SVG                    |
+| `XerticaXLogo`     | `xertica-ui/brand` | Compact X-mark logo variant                             |
+| `XerticaOrbe`      | `xertica-ui/brand` | Animated orb brand mark                                 |
+
+---
+
+## Color Theme System
+
+### How It Works
+
+Xertica UI uses CSS custom properties (design tokens) for all colors. The theme is applied by injecting token values at `:root` and `.dark`. Tailwind v4 maps these tokens via `@theme inline`.
+
+```
+tokens.css → :root { --primary: ...; --background: ...; }
+           → .dark { --primary: ...; --background: ...; }
+           → @theme inline { --color-primary: var(--primary); }
+           → Tailwind utilities: bg-primary, text-foreground, etc.
+```
+
+### Available Theme Presets
+
+The CLI (`npx xertica-ui@latest init` or `npx xertica-ui@latest update-theme`) offers multiple color presets. Each preset defines a complete set of tokens for both light and dark modes.
+
+### Customizing Colors Programmatically
+
+Use `useBrandColors` to read and modify brand colors at runtime:
+
+```tsx
+import { useBrandColors } from 'xertica-ui/hooks';
+
+function BrandCustomizer() {
+  const { colors, setBrandColor } = useBrandColors();
+
+  return (
+    <div className="space-y-2">
+      <label>Primary Color</label>
+      <input
+        type="color"
+        value={colors.primary}
+        onChange={e => setBrandColor('primary', e.target.value)}
+      />
+    </div>
+  );
+}
+```
+
+Changes are applied immediately as CSS variables on `:root`.
+
+---
+
+## Dark / Light Mode
+
+### `ThemeToggle`
+
+A self-contained button that toggles between light and dark mode. Does not require any context provider — it reads and writes `document.documentElement.classList` directly.
+
+```tsx
+import { ThemeToggle } from 'xertica-ui/brand';
+
+// Place in Header actions or Sidebar footer
+<ThemeToggle size="sm" />;
+```
+
+**Props:**
+
+| Prop        | Type                   | Default | Description            |
+| ----------- | ---------------------- | ------- | ---------------------- |
+| `size`      | `'sm' \| 'md' \| 'lg'` | `'md'`  | Button size            |
+| `className` | `string`               | —       | Additional CSS classes |
+
+### `useTheme` Hook
+
+For programmatic theme control:
+
+```tsx
+import { useTheme } from 'xertica-ui/hooks';
+
+function ThemeController() {
+  const { theme, setTheme, toggleTheme } = useTheme();
+  return <button onClick={toggleTheme}>Mode: {theme}</button>;
+}
+```
+
+> **Note**: `useTheme` requires `<XerticaProvider>` in the tree. `ThemeToggle` works without any provider.
+
+---
+
+## Language Selector
+
+### `LanguageSelector`
+
+A standalone dropdown for switching the UI language preference.
+
+```tsx
+import { LanguageSelector } from 'xertica-ui/brand';
+
+// Typically placed in PageHeader or Sidebar footer
+<LanguageSelector />;
+```
+
+The selected language is persisted in `localStorage` under `xertica_language`. Access the current value via `useLanguage()`:
+
+```tsx
+import { useLanguage } from 'xertica-ui/hooks';
+
+function MyComponent() {
+  const { language, availableLanguages, isMonolingual } = useLanguage();
+  // language is `string` (e.g. 'pt-BR', 'en', 'fr') — the set is runtime-configurable
+}
+```
+
+The set of available languages is configured at runtime via the `availableLanguages` prop on `<XerticaProvider>` (defaults to `pt-BR`, `en`, `es`). See [`docs/i18n.md`](../i18n.md) for the full extension API. When only one language is configured, the `LanguageSelector` auto-hides.
+
+---
+
+## Logo Components
+
+### `XerticaLogo`
+
+Full horizontal logotype. Use in the Sidebar header or login page.
+
+```tsx
+import { XerticaLogo } from 'xertica-ui/brand';
+
+<XerticaLogo className="h-8" />;
+```
+
+### `XerticaXLogo`
+
+Compact X-mark variant. Use when space is limited (collapsed sidebar, favicon-like contexts).
+
+```tsx
+import { XerticaXLogo } from 'xertica-ui/brand';
+
+<XerticaXLogo className="w-8 h-8" />;
+```
+
+### `XerticaOrbe`
+
+Animated orb brand mark. Use as a decorative element or loading indicator.
+
+```tsx
+import { XerticaOrbe } from 'xertica-ui/brand';
+
+<XerticaOrbe size={64} />;
+```
+
+---
+
+## `XerticaProvider`
+
+The root provider that initializes all brand, theme, layout, and service contexts. Must wrap the entire application once.
+
+```tsx
+import { XerticaProvider } from 'xertica-ui/brand';
+import 'xertica-ui/style.css';
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <XerticaProvider>
+      <App />
+    </XerticaProvider>
+  </React.StrictMode>
+);
+```
+
+`XerticaProvider` initializes:
+
+- `ThemeProvider` — dark/light mode
+- `LanguageProvider` — language preference
+- `BrandColorsProvider` — brand color tokens
+- `LayoutProvider` — sidebar and assistant state
+- `AssistenteProvider` — AI assistant context
+- `ApiKeyProvider` — API key management
+- `GoogleMapsLoaderProvider` — lazy Maps API loading
+- `TooltipProvider` — Radix tooltip context
+- `Toaster` — Sonner toast notifications
+
+**Props:**
+
+| Prop                  | Type        | Default      | Description                                 |
+| --------------------- | ----------- | ------------ | ------------------------------------------- |
+| `children`            | `ReactNode` | _(required)_ | Application content                         |
+| `googleMapsApiKey`    | `string`    | —            | Google Maps API key (activates Maps loader) |
+| `initialApiKey`       | `string`    | —            | Pre-set Xertica API key                     |
+| `initialGeminiApiKey` | `string`    | —            | Pre-set Gemini API key                      |
+
+---
+
+## CSS Token Structure
+
+The complete token set is defined in `tokens.css` (generated by the CLI). Key token groups:
+
+```css
+:root {
+  /* Colors */
+  --background: 0 0% 100%;
+  --foreground: 222.2 84% 4.9%;
+  --primary: 221.2 83.2% 53.3%;
+  --primary-foreground: 210 40% 98%;
+  --secondary: 210 40% 96.1%;
+  --muted: 210 40% 96.1%;
+  --muted-foreground: 215.4 16.3% 46.9%;
+  --accent: 210 40% 96.1%;
+  --destructive: 0 84.2% 60.2%;
+  --border: 214.3 31.8% 91.4%;
+  --input: 214.3 31.8% 91.4%;
+  --ring: 221.2 83.2% 53.3%;
+  --card: 0 0% 100%;
+  --card-foreground: 222.2 84% 4.9%;
+
+  /* Chart colors */
+  --chart-1: 221.2 83.2% 53.3%;
+  --chart-2: 142.1 76.2% 36.3%;
+  --chart-3: 47.9 95.8% 53.1%;
+  --chart-4: 280.1 65.3% 60%;
+  --chart-5: 24.6 95% 53.1%;
+
+  /* Sidebar */
+  --sidebar: 222.2 84% 4.9%;
+  --sidebar-foreground: 210 40% 98%;
+
+  /* Shape */
+  --radius: 0.5rem;
+  --radius-button: 0.375rem;
+}
+```
+
+---
+
+## AI Rules
+
+> [!IMPORTANT]
+>
+> - **`XerticaProvider` is required once**: Place it at the root of your application. Never nest multiple `XerticaProvider` instances.
+> - **Never use raw hex/rgb colors**: All colors must use semantic tokens (`bg-primary`, `text-destructive`, `border-border`). Raw values like `#3b82f6` or `rgb(59, 130, 246)` are forbidden.
+> - **`ThemeToggle` is self-contained**: It does not need `useTheme` or any context. Use it directly in any component without provider requirements.
+> - **Logo sizing via `className`**: Size logo components using Tailwind height/width classes (`h-8`, `w-8`). Do not use `width`/`height` HTML attributes.
+> - **Language is preference only**: `LanguageSelector` stores a preference. The library UI renders in Portuguese regardless. Implement your own i18n logic using the `language` value from `useLanguage()`.