xertica-ui 2.1.2 → 2.1.4

package/docs/components/assistant.md

@@ -12,6 +12,13 @@ Full-featured AI chat assistant with support for:
 - Three layout modes: `collapsed`, `expanded`, `fullPage`
 - Demo mode (mock AI responses without API key)
 
+The component ships in **two usage patterns**:
+
+| Pattern | When to use |
+|---|---|
+| `<XerticaAssistant />` | Drop-in assistant panel — zero configuration needed |
+| `useAssistant()` | Headless hook — bring your own UI while reusing all state and business logic |
+
 ---
 
 ## Props
@@ -227,6 +234,155 @@ Each assistant capability can be individually toggled via boolean props. All fla
 
 ---
 
+## Headless Hook — `useAssistant()`
+
+Use the headless hook when you need full control over the assistant's UI — custom layout, custom styling, or embedding the assistant logic inside a larger component.
+
+### Import
+
+```tsx
+import { useAssistant } from 'xertica-ui/assistant';
+```
+
+### Hook Props
+
+The hook accepts the same props as `XerticaAssistantProps` (minus purely visual props like `width`, `height`, `className`, `mobileFloating`, `onNavigateSettings`, `onNavigateFullPage`, `userName`, and feature flags).
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `mode` | `AssistantMode` | `'expanded'` | Layout mode |
+| `isExpanded` | `boolean` | `true` | Controlled expansion state |
+| `onToggle` | `() => void` | — | Toggle callback |
+| `defaultTab` | `AssistantTab` | `'chat'` | Initially selected tab |
+| `demoMode` | `boolean` | `true` | Enable demo mode |
+| `customResponses` | `MockResponse[]` | `[]` | Custom mock responses |
+| `initialMessages` | `Message[]` | `[]` | Pre-loaded messages |
+| `savedConversations` | `Conversation[]` | `[]` | Previously saved conversations |
+| `suggestions` | `Suggestion[]` | — | Suggested prompts |
+| `onSendMessage` | `(message: string) => void` | — | Send message callback |
+| `isProcessing` | `boolean` | `false` | Shows typing indicator |
+| `responseGenerator` | `(message: string) => Promise<string \| Partial<Message>>` | — | Custom response generator |
+| `richSuggestions` | `Suggestion[]` | `[]` | Extended suggestions |
+| `onRichAction` | `(actionId: string, actionText: string) => void` | — | Rich suggestion callback |
+| `onEvaluation` | `(messageId: string, type: 'like' \| 'dislike', reason?: string) => void` | — | Evaluation callback |
+
+### Hook Return Value
+
+| Property | Type | Description |
+|---|---|---|
+| `isFullPage` | `boolean` | Whether mode is `'fullPage'` |
+| `isExpanded` | `boolean` | Current expansion state |
+| `isMobile` | `boolean` | Whether viewport is mobile |
+| `abaSelecionada` | `AssistantTab` | Currently selected tab |
+| `setAbaSelecionada` | `(tab: AssistantTab) => void` | Change selected tab |
+| `mensagens` | `Message[]` | Current conversation messages |
+| `setMensagens` | `Dispatch<SetStateAction<Message[]>>` | Update messages |
+| `mensagem` | `string` | Current input value |
+| `setMensagem` | `(value: string) => void` | Update input value |
+| `conversas` | `Conversation[]` | All saved conversations |
+| `conversaAtual` | `string \| null` | ID of the active conversation |
+| `conversasFiltradas` | `Conversation[]` | Conversations filtered by active tab |
+| `copiedId` | `string \| null` | ID of the message currently showing "copied" state |
+| `generatingPodcastId` | `string \| null` | ID of the message generating a podcast |
+| `executingCommand` | `string \| null` | ID of the search command being executed |
+| `savedSearches` | `string[]` | IDs of saved search messages |
+| `editingDocument` | `{ content: string; title: string } \| null` | Document being edited |
+| `setEditingDocument` | `(doc \| null) => void` | Open/close document editor |
+| `showMoreSuggestions` | `boolean` | Whether extended suggestions are visible |
+| `setShowMoreSuggestions` | `(show: boolean) => void` | Toggle extended suggestions |
+| `evaluationState` | `EvaluationState` | State of the feedback dialog |
+| `setEvaluationState` | `Dispatch<...>` | Update evaluation state |
+| `sugestoes` | `Suggestion[]` | Resolved suggestions (prop or defaults) |
+| `messagesEndRef` | `RefObject<HTMLDivElement>` | Attach to the scroll anchor at the bottom of the message list |
+| `fileInputRef` | `RefObject<HTMLInputElement>` | Attach to the hidden file input |
+| `audioInputRef` | `RefObject<HTMLInputElement>` | Attach to the hidden audio input |
+| `handleToggle` | `() => void` | Toggle expansion |
+| `handleExpandWithTab` | `(tab: AssistantTab) => void` | Expand and switch to a specific tab |
+| `handleEnviarMensagem` | `(arg?: string \| ActionType) => Promise<void>` | Send a message |
+| `handleToggleFavorite` | `(messageId: string) => void` | Toggle message favorite |
+| `handleCopyMessage` | `(content: string, messageId: string) => Promise<void>` | Copy message to clipboard |
+| `handleGeneratePodcast` | `(messageId: string, content: string) => Promise<void>` | Generate podcast from message |
+| `handleDownloadDocument` | `(content: string, fileName: string) => void` | Download document as `.md` |
+| `handleDownloadPodcast` | `(audioUrl: string, fileName: string) => void` | Download podcast as `.mp3` |
+| `handleEditDocument` | `(content: string, title: string) => void` | Open document editor |
+| `handleNovaConversa` | `() => void` | Start a new conversation |
+| `handleSelecionarConversa` | `(conversaId: string) => void` | Load a saved conversation |
+| `handleToggleFavoritaConversa` | `(conversaId: string) => void` | Toggle conversation favorite |
+| `handleOpenSearchResult` | `(result: SearchResult) => void` | Open a search result |
+| `handleExecuteSearchCommand` | `(commandId, searchTerm, results, messageId) => Promise<void>` | Execute a search command |
+| `handleRichSuggestionClick` | `(suggestion: Suggestion) => void` | Handle rich suggestion click |
+| `handleEvaluationClick` | `(messageId: string, type: 'like' \| 'dislike') => void` | Handle message evaluation |
+| `openFeedbackDialog` | `(messageId: string, category: string \| null) => void` | Open dislike feedback dialog |
+| `handleSubmitDislike` | `() => void` | Submit dislike feedback |
+
+### Headless Hook Example
+
+```tsx
+import { useAssistant } from 'xertica-ui/assistant';
+
+function MyMinimalAssistant() {
+  const {
+    mensagens,
+    mensagem,
+    setMensagem,
+    handleEnviarMensagem,
+    isExpanded,
+    handleToggle,
+    messagesEndRef,
+  } = useAssistant({ demoMode: true });
+
+  return (
+    <div className="flex flex-col h-full border rounded-lg overflow-hidden">
+      {/* Header */}
+      <div className="flex items-center justify-between p-3 border-b">
+        <span className="font-semibold">AI Assistant</span>
+        <button onClick={handleToggle}>
+          {isExpanded ? 'Collapse' : 'Expand'}
+        </button>
+      </div>
+
+      {/* Messages */}
+      <div className="flex-1 overflow-y-auto p-4 space-y-3">
+        {mensagens.map(msg => (
+          <div
+            key={msg.id}
+            className={msg.type === 'user' ? 'text-right' : 'text-left'}
+          >
+            <span className={`inline-block px-3 py-2 rounded-lg text-sm ${
+              msg.type === 'user'
+                ? 'bg-primary text-primary-foreground'
+                : 'bg-muted'
+            }`}>
+              {msg.content}
+            </span>
+          </div>
+        ))}
+        <div ref={messagesEndRef} />
+      </div>
+
+      {/* Input */}
+      <div className="flex gap-2 p-3 border-t">
+        <input
+          value={mensagem}
+          onChange={e => setMensagem(e.target.value)}
+          onKeyDown={e => e.key === 'Enter' && handleEnviarMensagem()}
+          placeholder="Type a message..."
+          className="flex-1 border rounded px-3 py-2 text-sm"
+        />
+        <button
+          onClick={() => handleEnviarMensagem()}
+          className="px-4 py-2 bg-primary text-primary-foreground rounded text-sm"
+        >
+          Send
+        </button>
+      </div>
+    </div>
+  );
+}
+```
+
+---
+
 ## AI Rules
 
 - Use `demoMode={true}` for development without API key
@@ -236,3 +392,6 @@ Each assistant capability can be individually toggled via boolean props. All fla
 - Feature flags are independent and can be combined freely; all default to `true`
 - When `showHistory` or `showFavorites` is `false`, both the collapsed icon and expanded tab are removed
 - When both `showHistory` and `showFavorites` are `false`, the entire tab navigation bar is hidden (including the Chat tab) — there is no point showing a single tab with no alternatives
+- ALWAYS use `useAssistant()` when building a custom assistant UI — never re-implement message state or response generation manually
+- The `messagesEndRef` from the hook MUST be attached to a div at the bottom of the message list for auto-scroll to work
+- `handleEnviarMensagem()` handles both demo mode responses and `responseGenerator` — do not call `responseGenerator` directly

package/docs/components/audio-player.md

@@ -72,9 +72,55 @@ The `bar` variant automatically detects the state of the **Sidebar** and **AI As
 
 ---
 
+## Headless Hook: `useAudioPlayer`
+
+For advanced use cases where you need a fully custom player UI, use the `useAudioPlayer` headless hook directly:
+
+```tsx
+import { useAudioPlayer } from 'xertica-ui/hooks';
+
+function MyCustomPlayer({ src }: { src: string }) {
+  const {
+    audioRef,
+    containerRef,
+    isPlaying,
+    togglePlay,
+    currentTime,
+    duration,
+    formatTime,
+    onPlay,
+    onPause,
+    onEnded,
+    onTimeUpdate,
+    onLoadedMetadata,
+  } = useAudioPlayer({ src, variant: 'card' });
+
+  return (
+    <div ref={containerRef}>
+      <audio
+        ref={audioRef}
+        src={src}
+        onPlay={onPlay}
+        onPause={onPause}
+        onEnded={onEnded}
+        onTimeUpdate={onTimeUpdate}
+        onLoadedMetadata={onLoadedMetadata}
+      />
+      <button onClick={togglePlay}>{isPlaying ? 'Pause' : 'Play'}</button>
+      <span>{formatTime(currentTime)} / {formatTime(duration)}</span>
+    </div>
+  );
+}
+```
+
+See [`hooks.md`](./hooks.md#useaudioplayer) for the complete `useAudioPlayer` API reference.
+
+---
+
 ## AI Best Practices
 
 > [!IMPORTANT]
 > - **Branding Variants**: Use `colorVariant="primary"` for high-relevance or branded content (like Podcasts). Use the default style for utility audios.
 > - **Manual Floating**: In Card mode, users can click the "Maximize" icon to manually force floating mode.
 > - **Accessibility**: All buttons have appropriate ARIA labels. Always provide a descriptive `title` for each audio track.
+> - **Custom UI**: Use `useAudioPlayer` from `xertica-ui/hooks` only when you need a fully custom player interface. For standard playback, always use `<AudioPlayer>` directly.

package/docs/components/branding.md

@@ -0,0 +1,251 @@
+# 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 } = useLanguage(); // 'pt-BR' | 'en' | 'es'
+}
+```
+
+---
+
+## 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()`.