# XerticaProvider

The recommended root wrapper for Xertica UI applications. Most components can render independently with local fallbacks, but the provider centralizes app-wide state, theming, maps, tooltips, assistant state, API keys, and notifications.

---

## Import

```tsx
import { XerticaProvider } from 'xertica-ui/brand';
```

---

## Usage

```tsx
import { XerticaProvider } from 'xertica-ui/brand';
import 'xertica-ui/style.css';

function Root() {
  return (
    <XerticaProvider>
      <App />
    </XerticaProvider>
  );
}
```

---

## Props

| Prop                | Type        | Default      | Description                                                                |
| ------------------- | ----------- | ------------ | -------------------------------------------------------------------------- |
| `children`          | `ReactNode` | _(required)_ | The entrypoint of your application.                                        |
| `apiKey`            | `string`    | -            | Initial Gemini/AI key forwarded to `ApiKeyProvider`.                       |
| `googleMapsApiKey`  | `string`    | -            | Initial Google Maps JavaScript API key.                                    |
| `defaultBrandTheme` | `string`    | -            | Initial brand color theme id.                                              |
| `primaryColor`      | `string`    | -            | Primary brand color override.                                              |
| `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. |

---

## Included Services

- **ThemeProvider**: Manages light/dark mode with browser-safe storage.
- **BrandColorsProvider**: Applies runtime brand colors when custom tokens are not used.
- **LanguageProvider**: Stores the selected UI language.
- **ApiKeyProvider**: Stores AI and Google Maps API keys.
- **AssistenteProvider**: Provides shared assistant conversation state.
- **LayoutContext**: Manages `sidebarWidth` and expanded states globally.
- **TooltipProvider**: Enables Radix-based tooltips with consistent delays.
- **GoogleMapsLoader**: Manages the lifecycle of the Google Maps JS SDK.
- **Sonner Toaster**: Injects a high-performance toast notification system.

---

## AI Rules

> [!IMPORTANT]
>
> - **CSS Requirement**: Always remind users to import `xertica-ui/style.css` alongside the provider to avoid unstyled content.
> - **Independence Contract**: UI, layout, media, and assistant components should render without this provider when possible. Use the provider at the app root for synchronized state and shared services.