xertica-ui 2.2.1 → 2.4.0

package/docs/components/use-mobile.md

@@ -1,96 +1,96 @@
-# useMobile / useIsMobile
-
-## Overview
-
-Two hooks that detect whether the current viewport is a mobile-width screen. Useful for conditionally rendering mobile-specific layouts, swapping components (e.g., `Drawer` vs `Sheet`), or hiding/showing content based on screen size.
-
----
-
-## When to Use
-
-- Conditionally render mobile vs desktop UI variants in the same component
-- Swap between `<Drawer>` (mobile) and `<Sheet>` (desktop) panels
-- Show simplified tables or cards on small screens
-
-## When NOT to Use
-
-- For simple layout differences — prefer Tailwind responsive classes (`hidden md:flex`) instead.
-- As a replacement for CSS media queries — use these hooks only when the component tree needs to branch in React logic.
-
----
-
-## Hooks
-
-### `useMobile()`
-
-```typescript
-function useMobile(): boolean;
-```
-
-Returns `true` when the viewport width is below the mobile breakpoint (`768px` / `md`). Returns `false` on desktop.
-
-### `useIsMobile()`
-
-An alias for `useMobile()` — functionally identical. Use either one based on naming preference.
-
----
-
-## Examples
-
-### Conditional Sheet vs Drawer
-
-```tsx
-import { useMobile, Sheet, SheetContent, Drawer, DrawerContent } from 'xertica-ui/ui';
-
-function FilterPanel({ open, onClose }) {
-  const isMobile = useMobile();
-
-  if (isMobile) {
-    return (
-      <Drawer open={open} onOpenChange={onClose}>
-        <DrawerContent>{/* Filter controls */}</DrawerContent>
-      </Drawer>
-    );
-  }
-
-  return (
-    <Sheet open={open} onOpenChange={onClose}>
-      <SheetContent side="right">{/* Filter controls */}</SheetContent>
-    </Sheet>
-  );
-}
-```
-
-### Conditional Column Display
-
-```tsx
-const isMobile = useMobile();
-
-<Table>
-  <TableHeader>
-    <TableRow>
-      <TableHead>Name</TableHead>
-      <TableHead>Email</TableHead>
-      {!isMobile && <TableHead>Role</TableHead>}
-      {!isMobile && <TableHead>Created At</TableHead>}
-      <TableHead>Actions</TableHead>
-    </TableRow>
-  </TableHeader>
-</Table>;
-```
-
----
-
-## AI Rules
-
-- Prefer Tailwind responsive classes (`className="hidden md:table-cell"`) over this hook for simple CSS-based visibility — reserve these hooks for cases where the React component tree needs to be different.
-- The breakpoint is `768px` (`md` in Tailwind). Anything below renders as mobile.
-- Both `useMobile` and `useIsMobile` are identical — do not use both in the same component.
-- These hooks are reactive — they update automatically when the window is resized.
-
----
-
-## Related Components
-
-- [`Sheet`](./sheet.md) — Desktop side panel
-- [`Drawer`](./drawer.md) — Mobile bottom panel
+# useMobile / useIsMobile
+
+## Overview
+
+Two hooks that detect whether the current viewport is a mobile-width screen. Useful for conditionally rendering mobile-specific layouts, swapping components (e.g., `Drawer` vs `Sheet`), or hiding/showing content based on screen size.
+
+---
+
+## When to Use
+
+- Conditionally render mobile vs desktop UI variants in the same component
+- Swap between `<Drawer>` (mobile) and `<Sheet>` (desktop) panels
+- Show simplified tables or cards on small screens
+
+## When NOT to Use
+
+- For simple layout differences — prefer Tailwind responsive classes (`hidden md:flex`) instead.
+- As a replacement for CSS media queries — use these hooks only when the component tree needs to branch in React logic.
+
+---
+
+## Hooks
+
+### `useMobile()`
+
+```typescript
+function useMobile(): boolean;
+```
+
+Returns `true` when the viewport width is below the mobile breakpoint (`768px` / `md`). Returns `false` on desktop.
+
+### `useIsMobile()`
+
+An alias for `useMobile()` — functionally identical. Use either one based on naming preference.
+
+---
+
+## Examples
+
+### Conditional Sheet vs Drawer
+
+```tsx
+import { useMobile, Sheet, SheetContent, Drawer, DrawerContent } from 'xertica-ui/ui';
+
+function FilterPanel({ open, onClose }) {
+  const isMobile = useMobile();
+
+  if (isMobile) {
+    return (
+      <Drawer open={open} onOpenChange={onClose}>
+        <DrawerContent>{/* Filter controls */}</DrawerContent>
+      </Drawer>
+    );
+  }
+
+  return (
+    <Sheet open={open} onOpenChange={onClose}>
+      <SheetContent side="right">{/* Filter controls */}</SheetContent>
+    </Sheet>
+  );
+}
+```
+
+### Conditional Column Display
+
+```tsx
+const isMobile = useMobile();
+
+<Table>
+  <TableHeader>
+    <TableRow>
+      <TableHead>Name</TableHead>
+      <TableHead>Email</TableHead>
+      {!isMobile && <TableHead>Role</TableHead>}
+      {!isMobile && <TableHead>Created At</TableHead>}
+      <TableHead>Actions</TableHead>
+    </TableRow>
+  </TableHeader>
+</Table>;
+```
+
+---
+
+## AI Rules
+
+- Prefer Tailwind responsive classes (`className="hidden md:table-cell"`) over this hook for simple CSS-based visibility — reserve these hooks for cases where the React component tree needs to be different.
+- The breakpoint is `768px` (`md` in Tailwind). Anything below renders as mobile.
+- Both `useMobile` and `useIsMobile` are identical — do not use both in the same component.
+- These hooks are reactive — they update automatically when the window is resized.
+
+---
+
+## Related Components
+
+- [`Sheet`](./sheet.md) — Desktop side panel
+- [`Drawer`](./drawer.md) — Mobile bottom panel

package/docs/components/video-player.md

@@ -1,68 +1,68 @@
-# VideoPlayer
-
-A feature-rich video player component with floating mode support, custom controls, and automatic state management.
-
----
-
-## Overview
-
-The `VideoPlayer` is a comprehensive video playback solution designed to deliver a seamless viewing experience across the platform. It features custom playback controls, automatic floating behavior when scrolled out of view, and full integration with the Xertica UI design system.
-
----
-
-## Features
-
-- **Custom Playback Controls**: Play/Pause, Progress Bar, Volume, Mute, Picture-in-Picture, and Fullscreen.
-- **Auto-Floating Mode**: Automatically transforms into a floating window when scrolled out of view.
-- **Intelligent Controls Visibility**: Controls hide after 2.5s of inactivity during playback.
-- **Responsive Design**: Adapts perfectly to mobile and desktop viewports.
-
----
-
-## Props
-
-| Prop              | Type      | Default | Description                                                  |
-| ----------------- | --------- | ------- | ------------------------------------------------------------ |
-| `src`             | `string`  | —       | The source URL of the video.                                 |
-| `poster`          | `string`  | —       | URL of an image to be shown before the video starts playing. |
-| `title`           | `string`  | —       | Title of the video content.                                  |
-| `autoPlay`        | `boolean` | `false` | Whether the video should start playing automatically.        |
-| `enableAutoFloat` | `boolean` | `true`  | Whether the video should float when scrolled out of view.    |
-
----
-
-## Examples
-
-### Basic Video Player
-
-```tsx
-import { VideoPlayer } from 'xertica-ui/media';
-
-<VideoPlayer src="https://example.com/video.mp4" title="My Video" />;
-```
-
-### Video with Poster Image
-
-```tsx
-<VideoPlayer
-  src="https://example.com/video.mp4"
-  poster="https://example.com/poster.jpg"
-  title="Featured Video"
-/>
-```
-
----
-
-## AI Rules
-
-> [!TIP]
->
-> - **Auto-Float** — The floating behavior is ideal for long-form content where users may want to continue watching while scrolling through other content.
-> - **Posters** — Always provide a `poster` image for better UX, especially for videos that may take time to load.
-
----
-
-## Related Components
-
-- [`FloatingMediaWrapper`](./floating-media-wrapper.md) — The underlying wrapper for floating behavior.
-- [`AudioPlayer`](./audio-player.md) — For audio playback.
+# VideoPlayer
+
+A feature-rich video player component with floating mode support, custom controls, and automatic state management.
+
+---
+
+## Overview
+
+The `VideoPlayer` is a comprehensive video playback solution designed to deliver a seamless viewing experience across the platform. It features custom playback controls, automatic floating behavior when scrolled out of view, and full integration with the Xertica UI design system.
+
+---
+
+## Features
+
+- **Custom Playback Controls**: Play/Pause, Progress Bar, Volume, Mute, Picture-in-Picture, and Fullscreen.
+- **Auto-Floating Mode**: Automatically transforms into a floating window when scrolled out of view.
+- **Intelligent Controls Visibility**: Controls hide after 2.5s of inactivity during playback.
+- **Responsive Design**: Adapts perfectly to mobile and desktop viewports.
+
+---
+
+## Props
+
+| Prop              | Type      | Default | Description                                                  |
+| ----------------- | --------- | ------- | ------------------------------------------------------------ |
+| `src`             | `string`  | —       | The source URL of the video.                                 |
+| `poster`          | `string`  | —       | URL of an image to be shown before the video starts playing. |
+| `title`           | `string`  | —       | Title of the video content.                                  |
+| `autoPlay`        | `boolean` | `false` | Whether the video should start playing automatically.        |
+| `enableAutoFloat` | `boolean` | `true`  | Whether the video should float when scrolled out of view.    |
+
+---
+
+## Examples
+
+### Basic Video Player
+
+```tsx
+import { VideoPlayer } from 'xertica-ui/media';
+
+<VideoPlayer src="https://example.com/video.mp4" title="My Video" />;
+```
+
+### Video with Poster Image
+
+```tsx
+<VideoPlayer
+  src="https://example.com/video.mp4"
+  poster="https://example.com/poster.jpg"
+  title="Featured Video"
+/>
+```
+
+---
+
+## AI Rules
+
+> [!TIP]
+>
+> - **Auto-Float** — The floating behavior is ideal for long-form content where users may want to continue watching while scrolling through other content.
+> - **Posters** — Always provide a `poster` image for better UX, especially for videos that may take time to load.
+
+---
+
+## Related Components
+
+- [`FloatingMediaWrapper`](./floating-media-wrapper.md) — The underlying wrapper for floating behavior.
+- [`AudioPlayer`](./audio-player.md) — For audio playback.

package/docs/components/xertica-logo.md

@@ -1,36 +1,36 @@
-# XerticaLogo
-
-The official full horizontal logotype for Xertica. It is a vector-based SVG component that ensures brand consistency across all application headers and splash screens.
-
----
-
-## Import
-
-```tsx
-import { XerticaLogo } from 'xertica-ui/brand';
-```
-
----
-
-## Usage
-
-```tsx
-<XerticaLogo className="h-8 w-auto text-primary" />
-```
-
----
-
-## Props
-
-| Prop        | Type     | Default | Description                                   |
-| ----------- | -------- | ------- | --------------------------------------------- |
-| `className` | `string` | —       | Standard CSS classes for sizing and coloring. |
-
----
-
-## AI Rules
-
-> [!IMPORTANT]
->
-> - **Sizing**: Use responsive height utilities (e.g., `h-6 md:h-8`) rather than fixed pixel widths to maintain aspect ratio.
-> - **Coloring**: The logo uses `currentColor`. Apply `text-primary` or `text-foreground` to the component to control its color.
+# XerticaLogo
+
+The official full horizontal logotype for Xertica. It is a vector-based SVG component that ensures brand consistency across all application headers and splash screens.
+
+---
+
+## Import
+
+```tsx
+import { XerticaLogo } from 'xertica-ui/brand';
+```
+
+---
+
+## Usage
+
+```tsx
+<XerticaLogo className="h-8 w-auto text-primary" />
+```
+
+---
+
+## Props
+
+| Prop        | Type     | Default | Description                                   |
+| ----------- | -------- | ------- | --------------------------------------------- |
+| `className` | `string` | —       | Standard CSS classes for sizing and coloring. |
+
+---
+
+## AI Rules
+
+> [!IMPORTANT]
+>
+> - **Sizing**: Use responsive height utilities (e.g., `h-6 md:h-8`) rather than fixed pixel widths to maintain aspect ratio.
+> - **Coloring**: The logo uses `currentColor`. Apply `text-primary` or `text-foreground` to the component to control its color.

package/docs/components/xertica-orbe.md

@@ -1,35 +1,35 @@
-# XerticaOrbe
-
-An animated, decorative brand element representing the Xertica "Orbe". It features CSS-based pulse and rotation animations to provide a premium, dynamic feel to hero sections and loading screens.
-
----
-
-## Import
-
-```tsx
-import { XerticaOrbe } from 'xertica-ui/brand';
-```
-
----
-
-## Usage
-
-```tsx
-<XerticaOrbe className="size-32" />
-```
-
----
-
-## Props
-
-| Prop        | Type     | Default | Description                      |
-| ----------- | -------- | ------- | -------------------------------- |
-| `className` | `string` | —       | Standard CSS classes for sizing. |
-
----
-
-## AI Rules
-
-> [!IMPORTANT]
->
-> - **Usage Context**: Do not use the Orbe as a primary logo. It is a secondary decorative element intended for splash screens, deep backgrounds, or "AI is thinking" states.
+# XerticaOrbe
+
+An animated, decorative brand element representing the Xertica "Orbe". It features CSS-based pulse and rotation animations to provide a premium, dynamic feel to hero sections and loading screens.
+
+---
+
+## Import
+
+```tsx
+import { XerticaOrbe } from 'xertica-ui/brand';
+```
+
+---
+
+## Usage
+
+```tsx
+<XerticaOrbe className="size-32" />
+```
+
+---
+
+## Props
+
+| Prop        | Type     | Default | Description                      |
+| ----------- | -------- | ------- | -------------------------------- |
+| `className` | `string` | —       | Standard CSS classes for sizing. |
+
+---
+
+## AI Rules
+
+> [!IMPORTANT]
+>
+> - **Usage Context**: Do not use the Orbe as a primary logo. It is a secondary decorative element intended for splash screens, deep backgrounds, or "AI is thinking" states.

package/docs/components/xertica-provider.md

@@ -1,65 +1,65 @@
-# 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.
+# 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.