xertica-ui 2.1.2 → 2.1.4

package/docs/components/file-upload.md

@@ -4,6 +4,19 @@
 
 A drag-and-drop file input component that accepts one or multiple files. Renders a dropzone area with visual feedback on drag, displays selected file names, and validates against allowed MIME types and file size limits.
 
+The package also exports a **headless `useFileUpload` hook** for building fully custom drop-zone UIs while reusing all the validation and drag-state logic.
+
+---
+
+## Exports
+
+| Export | Description |
+|---|---|
+| `FileUpload` | Ready-to-use drag-and-drop file input component |
+| `useFileUpload` | Headless hook — all logic, no UI |
+| `UseFileUploadProps` | TypeScript props type for the hook |
+| `UseFileUploadReturn` | TypeScript return type for the hook |
+
 ---
 
 ## When to Use
@@ -15,7 +28,7 @@ A drag-and-drop file input component that accepts one or multiple files. Renders
 
 ---
 
-## Props
+## `FileUpload` Component Props
 
 | Prop | Type | Default | Required | Description |
 |---|---|---|---|---|
@@ -75,9 +88,113 @@ import { FileUpload } from 'xertica-ui/ui';
 
 ---
 
+## `useFileUpload` Hook
+
+A headless hook that encapsulates all file upload logic — drag state, file validation, error messaging, and the hidden input ref — without rendering any UI. Use it when the `<FileUpload>` component's visual design doesn't fit your needs.
+
+### Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `maxFiles` | `number` | `1` | Maximum number of files allowed |
+| `maxSize` | `number` | `5242880` (5MB) | Maximum file size in bytes |
+| `onFilesChange` | `(files: File[]) => void` | — | Called with the accepted file list whenever it changes |
+| `onError` | `(rejected: File[], reason: 'size' \| 'count') => void` | — | Called when files are rejected |
+| `disabled` | `boolean` | `false` | Whether the upload area is disabled |
+
+### Return Value
+
+| Property | Type | Description |
+|---|---|---|
+| `files` | `File[]` | Currently accepted files |
+| `dragActive` | `boolean` | Whether a drag is active over the drop zone |
+| `errorMessage` | `string \| null` | Inline error message, or `null` |
+| `inputRef` | `RefObject<HTMLInputElement>` | Attach to the hidden `<input type="file">` |
+| `handleFiles` | `(files: FileList \| null) => void` | Process a `FileList` from any source |
+| `handleDrag` | `(e: DragEvent) => void` | Attach to `onDragEnter`, `onDragOver`, `onDragLeave` |
+| `handleDrop` | `(e: DragEvent) => void` | Attach to `onDrop` |
+| `handleChange` | `(e: ChangeEvent<HTMLInputElement>) => void` | Attach to the hidden input's `onChange` |
+| `removeFile` | `(index: number) => void` | Remove a file by its index |
+| `openFileDialog` | `() => void` | Programmatically open the native file picker |
+
+### Custom Drop Zone Example
+
+```tsx
+import { useFileUpload } from 'xertica-ui/ui';
+import { UploadCloud } from 'lucide-react';
+
+function CustomDropZone() {
+  const {
+    files,
+    dragActive,
+    errorMessage,
+    inputRef,
+    handleDrag,
+    handleDrop,
+    handleChange,
+    removeFile,
+    openFileDialog,
+  } = useFileUpload({
+    maxFiles: 3,
+    maxSize: 10 * 1024 * 1024, // 10MB
+    onFilesChange: (files) => console.log('Files:', files),
+  });
+
+  return (
+    <div className="space-y-3">
+      <div
+        onDragEnter={handleDrag}
+        onDragOver={handleDrag}
+        onDragLeave={handleDrag}
+        onDrop={handleDrop}
+        onClick={openFileDialog}
+        className={cn(
+          "flex flex-col items-center justify-center rounded-xl border-2 border-dashed p-10 cursor-pointer transition-colors",
+          dragActive ? "border-primary bg-primary/5" : "border-border hover:border-primary/50"
+        )}
+      >
+        <UploadCloud className="size-8 text-muted-foreground mb-2" />
+        <p className="text-sm text-muted-foreground">
+          Drop files here or <span className="text-primary font-medium">browse</span>
+        </p>
+        <input
+          ref={inputRef}
+          type="file"
+          multiple
+          className="hidden"
+          onChange={handleChange}
+        />
+      </div>
+
+      {errorMessage && (
+        <p className="text-sm text-destructive">{errorMessage}</p>
+      )}
+
+      {files.length > 0 && (
+        <ul className="space-y-1">
+          {files.map((file, i) => (
+            <li key={i} className="flex items-center justify-between text-sm">
+              <span>{file.name}</span>
+              <Button size="sm" variant="ghost" onClick={() => removeFile(i)}>
+                Remove
+              </Button>
+            </li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+}
+```
+
+---
+
 ## AI Rules
 
-- Do not use native `<input type="file">` — always use `<FileUpload>` from `xertica-ui`.
+- Do not use native `<input type="file">` — always use `<FileUpload>` or `useFileUpload` from `xertica-ui`.
 - `maxSize` is in bytes — calculate using `MB * 1024 * 1024`.
 - In forms, use `onFilesChange` to call `field.onChange` — not `{...field}`.
 - For avatar uploads, use `accept="image/*"` and `multiple={false}`.
+- When using `useFileUpload`, attach `handleDrag` to **all three** drag events: `onDragEnter`, `onDragOver`, and `onDragLeave`.
+- Always attach `inputRef` to a hidden `<input type="file">` element — `openFileDialog()` requires it.
+- `removeFile(index)` removes by array index, not by file name.

package/docs/components/formatted-document.md

@@ -0,0 +1,113 @@
+# FormattedDocument
+
+A lightweight Markdown-to-HTML renderer with a collapsible preview. Designed for displaying AI-generated documents, reports, and structured text inside the assistant panel.
+
+---
+
+## Import
+
+```tsx
+import { FormattedDocument } from 'xertica-ui/assistant';
+```
+
+---
+
+## Basic Usage
+
+```tsx
+<FormattedDocument
+  content="# Report\n\nThis is a **bold** statement.\n\n- Item one\n- Item two"
+/>
+```
+
+---
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `content` | `string` | _(required)_ | Raw Markdown string to render |
+| `maxPreviewLength` | `number` | `500` | Character count shown before the "See more" toggle appears |
+| `className` | `string` | `''` | Additional CSS classes for the outer container |
+
+---
+
+## Supported Markdown Syntax
+
+| Syntax | Output |
+|---|---|
+| `# Heading 1` | `<h1>` — `text-xl font-medium` |
+| `## Heading 2` | `<h2>` — `text-lg font-medium` |
+| `### Heading 3` | `<h3>` — `text-base font-medium` |
+| `**bold**` | `<strong>` — `font-medium text-foreground` |
+| `*italic*` | `<em>` — `italic` |
+| `- item` / `* item` | Unordered list (`<ul>`) |
+| `1. item` | Ordered list (`<ol>`) |
+| `- [ ] task` | Unchecked checkbox (disabled) |
+| `- [x] task` | Checked checkbox (disabled) |
+| `---` | Horizontal rule (`<hr>`) |
+| `\n\n` | Paragraph break |
+
+> **Note**: This is a simplified renderer. It does not support tables, links, images, inline code, or fenced code blocks. For full Markdown rendering with code highlighting, use `MarkdownMessage` instead.
+
+---
+
+## Collapsible Preview
+
+When the `content` string exceeds `maxPreviewLength` characters, the component renders a truncated preview with a "Ver mais" (See more) button. Clicking it expands the full content. A "Ver menos" (See less) button collapses it again.
+
+```tsx
+// Long document — will show preview with toggle
+<FormattedDocument
+  content={longAiGeneratedText}
+  maxPreviewLength={300}
+/>
+```
+
+---
+
+## Comparison: `FormattedDocument` vs `MarkdownMessage`
+
+| Feature | `FormattedDocument` | `MarkdownMessage` |
+|---|---|---|
+| Headers | ✅ | ✅ |
+| Bold / Italic | ✅ | ✅ |
+| Lists | ✅ | ✅ |
+| Checkboxes | ✅ | ❌ |
+| Code blocks | ❌ | ✅ (via `CodeBlock`) |
+| Tables | ❌ | ✅ |
+| Links | ❌ | ✅ |
+| Collapsible preview | ✅ | ❌ |
+| Best for | AI documents, reports | AI chat messages |
+
+---
+
+## Usage in AI Context
+
+`FormattedDocument` is used by `XerticaAssistant` when the AI returns a document-type response (triggered by the "Create document" action in `ModernChatInput`). The document is also editable via the `RichTextEditor` panel.
+
+```tsx
+import { FormattedDocument } from 'xertica-ui/assistant';
+
+function DocumentViewer({ aiOutput }: { aiOutput: string }) {
+  return (
+    <div className="p-4 bg-card rounded-lg border border-border">
+      <FormattedDocument
+        content={aiOutput}
+        maxPreviewLength={800}
+        className="text-sm"
+      />
+    </div>
+  );
+}
+```
+
+---
+
+## AI Rules
+
+> [!IMPORTANT]
+> - **Use for AI-generated documents, not chat messages**: For chat message rendering, use `MarkdownMessage`. `FormattedDocument` is optimized for longer structured content (reports, summaries, plans).
+> - **No code block support**: If the AI response contains fenced code blocks (` ``` `), use `MarkdownMessage` or `CodeBlock` instead — `FormattedDocument` will render them as plain text.
+> - **Checkboxes are read-only**: The rendered checkboxes have `disabled` attribute. They are for display only. For interactive task lists, build a custom component.
+> - **`maxPreviewLength` is character-based**: It counts raw Markdown characters, not rendered text length. Set it higher than you think you need to avoid cutting off mid-sentence.

package/docs/components/hooks.md

@@ -0,0 +1,430 @@
+# Hooks — Xertica UI
+
+Xertica UI exposes a set of React hooks via the `xertica-ui/hooks` subpath. These hooks provide access to global contexts (theme, language, layout, assistant, API keys, brand colors) and utility behaviors (audio player, keyboard shortcuts, mobile detection).
+
+---
+
+## Import
+
+```tsx
+import {
+  useTheme,
+  useLanguage,
+  useBrandColors,
+  useAssistente,
+  useApiKey,
+  useLayout,
+  useAudioPlayer,
+  useLayoutShortcuts,
+  useIsMobile,
+} from 'xertica-ui/hooks';
+```
+
+All hooks are also available from the root barrel:
+
+```tsx
+import { useTheme, useLayout } from 'xertica-ui';
+```
+
+---
+
+## `useTheme`
+
+Accesses and controls the current color theme (light/dark).
+
+**Source**: `contexts/ThemeContext.tsx`
+
+### Return Value
+
+| Property | Type | Description |
+|---|---|---|
+| `theme` | `'light' \| 'dark' \| 'system'` | Current active theme |
+| `setTheme` | `(theme: Theme) => void` | Sets the theme explicitly |
+| `toggleTheme` | `() => void` | Toggles between light and dark |
+
+### Usage
+
+```tsx
+import { useTheme } from 'xertica-ui/hooks';
+
+function ThemeButton() {
+  const { theme, toggleTheme } = useTheme();
+  return (
+    <button onClick={toggleTheme}>
+      Current: {theme}
+    </button>
+  );
+}
+```
+
+> **Note**: `useTheme` must be used inside `<XerticaProvider>` (which includes `ThemeProvider`). For a self-contained toggle that does not require context, use the `<ThemeToggle>` component instead.
+
+---
+
+## `useLanguage`
+
+Accesses and controls the current UI language preference.
+
+**Source**: `contexts/LanguageContext.tsx`
+
+### Return Value
+
+| Property | Type | Description |
+|---|---|---|
+| `language` | `'pt-BR' \| 'en' \| 'es'` | Current language code |
+| `setLanguage` | `(language: Language) => void` | Changes the language |
+
+### Usage
+
+```tsx
+import { useLanguage } from 'xertica-ui/hooks';
+
+function LanguageDisplay() {
+  const { language, setLanguage } = useLanguage();
+  return (
+    <select value={language} onChange={e => setLanguage(e.target.value as any)}>
+      <option value="pt-BR">Português</option>
+      <option value="en">English</option>
+      <option value="es">Español</option>
+    </select>
+  );
+}
+```
+
+> **Note**: The language preference is persisted in `localStorage` under the key `xertica_language`. The library UI currently renders in Portuguese regardless of this setting — the selector is provided for consumer applications to implement their own i18n logic.
+
+---
+
+## `useBrandColors`
+
+Accesses and modifies the brand color palette applied as CSS custom properties.
+
+**Source**: `contexts/BrandColorsContext.tsx`
+
+### Return Value
+
+| Property | Type | Description |
+|---|---|---|
+| `colors` | `BrandColors` | Current brand color values |
+| `setBrandColor` | `(key: keyof BrandColors, value: string) => void` | Updates a single brand color |
+| `currentTheme` | `string` | Name of the active color theme preset |
+
+### Usage
+
+```tsx
+import { useBrandColors } from 'xertica-ui/hooks';
+
+function BrandCustomizer() {
+  const { colors, setBrandColor } = useBrandColors();
+  return (
+    <input
+      type="color"
+      value={colors.primary}
+      onChange={e => setBrandColor('primary', e.target.value)}
+    />
+  );
+}
+```
+
+> **Note**: Color changes are applied immediately as CSS variables on `:root`. They persist across re-renders but are not saved to `localStorage` by default.
+
+---
+
+## `useAssistente`
+
+Accesses the global AI Assistant context — conversation list, current conversation, and navigation helpers.
+
+**Source**: `contexts/AssistenteContext.tsx`
+
+### Return Value
+
+| Property | Type | Description |
+|---|---|---|
+| `conversas` | `Conversa[]` | List of all conversations |
+| `conversaAtual` | `string \| null` | ID of the currently active conversation |
+| `setConversaAtual` | `(id: string \| null) => void` | Selects a conversation |
+| `sugestoes` | `Sugestao[]` | Quick-reply suggestions for the welcome screen |
+| `setSugestoes` | `(s: Sugestao[]) => void` | Replaces the suggestion list |
+
+### Usage
+
+```tsx
+import { useAssistente } from 'xertica-ui/hooks';
+
+function ConversationCount() {
+  const { conversas } = useAssistente();
+  return <span>{conversas.length} conversations</span>;
+}
+```
+
+> **Note**: This hook must be used inside `<XerticaProvider>` (which includes `AssistenteProvider`). It is primarily used internally by `XerticaAssistant`.
+
+---
+
+## `useApiKey`
+
+Accesses and manages API keys for Xertica services, Gemini AI, and Google Maps.
+
+**Source**: `contexts/ApiKeyContext.tsx`
+
+### Return Value
+
+| Property | Type | Description |
+|---|---|---|
+| `apiKey` | `string` | Xertica platform API key |
+| `setApiKey` | `(key: string) => void` | Updates the Xertica API key |
+| `geminiApiKey` | `string` | Google Gemini API key |
+| `setGeminiApiKey` | `(key: string) => void` | Updates the Gemini API key |
+| `isApiKeyValid` | `boolean` | Whether the Xertica API key is non-empty |
+| `googleMapsApiKey` | `string` | Google Maps API key |
+| `setGoogleMapsApiKey` | `(key: string) => void` | Updates the Maps API key |
+| `isGoogleMapsKeyValid` | `boolean` | Whether the Maps key is non-empty |
+| `reloadMapsApi` | `() => Promise<void>` | Reloads the Maps script after key change |
+
+### Usage
+
+```tsx
+import { useApiKey } from 'xertica-ui/hooks';
+
+function ApiKeySettings() {
+  const { geminiApiKey, setGeminiApiKey, isApiKeyValid } = useApiKey();
+  return (
+    <input
+      type="password"
+      value={geminiApiKey}
+      onChange={e => setGeminiApiKey(e.target.value)}
+      placeholder="Enter Gemini API key"
+    />
+  );
+}
+```
+
+> **Note**: API keys are persisted in `localStorage`. The `XerticaAssistant` component reads `geminiApiKey` automatically when `mode="real"`.
+
+---
+
+## `useLayout`
+
+Accesses and controls the global layout state — sidebar expansion, assistant panel, and width values.
+
+**Source**: `contexts/LayoutContext.tsx`
+
+### Return Value
+
+| Property | Type | Description |
+|---|---|---|
+| `sidebarExpanded` | `boolean` | Whether the sidebar is expanded |
+| `sidebarWidth` | `number` | Current sidebar width in pixels |
+| `setSidebarWidth` | `(width: number) => void` | Updates the sidebar width |
+| `toggleSidebar` | `() => void` | Toggles sidebar expanded state |
+| `assistenteExpanded` | `boolean` | Whether the AI assistant panel is open |
+| `toggleAssistente` | `() => void` | Toggles the assistant panel |
+| `toggleAssistenteWithTab` | `(tab: string) => void` | Opens the assistant on a specific tab |
+
+### Usage
+
+```tsx
+import { useLayout } from 'xertica-ui/hooks';
+
+function ContentArea() {
+  const { sidebarExpanded, sidebarWidth } = useLayout();
+  return (
+    <main style={{ marginLeft: sidebarWidth }}>
+      {/* content */}
+    </main>
+  );
+}
+```
+
+> **See also**: `docs/layout.md` for the complete layout system reference.
+
+---
+
+## `useAudioPlayer`
+
+Headless hook that encapsulates all state and side effects for audio playback. Use this to build a fully custom audio player UI while reusing the library's playback logic.
+
+**Source**: `components/media/audio-player/use-audio-player.ts`
+
+### Props (`UseAudioPlayerProps`)
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `src` | `string` | — | Audio file URL |
+| `autoPlay` | `boolean` | `false` | Start playing on mount |
+| `initialTime` | `number` | `0` | Initial seek position in seconds |
+| `initialDuration` | `number` | — | Pre-known duration (loaded from metadata if omitted) |
+| `variant` | `'card' \| 'bar'` | `'card'` | Layout variant (affects floating behavior) |
+| `isOpen` | `boolean` | `true` | Whether the bar variant is visible |
+| `enableAutoFloat` | `boolean` | `true` | Auto-float when scrolled out of view (card only) |
+| `onCloseFloating` | `() => void` | — | Called when user closes the floating player |
+
+### Return Value (`UseAudioPlayerReturn`)
+
+**Refs**
+
+| Property | Type | Description |
+|---|---|---|
+| `audioRef` | `RefObject<HTMLAudioElement>` | Attach to `<audio>` element |
+| `containerRef` | `RefObject<HTMLDivElement>` | Attach to the player container for scroll detection |
+
+**Playback State**
+
+| Property | Type | Description |
+|---|---|---|
+| `isPlaying` | `boolean` | Whether audio is currently playing |
+| `currentTime` | `number` | Current playback position in seconds |
+| `duration` | `number` | Total duration in seconds |
+| `volume` | `number` | Volume level (0–1) |
+| `isMuted` | `boolean` | Whether audio is muted |
+| `playbackSpeed` | `number` | Current playback speed (0.5, 1, 1.5, 2) |
+
+**UI State**
+
+| Property | Type | Description |
+|---|---|---|
+| `isFloating` | `boolean` | Whether the player is in floating mode |
+| `isManualFloating` | `boolean` | Whether floating was triggered manually |
+| `isVisible` | `boolean` | Whether the container is in the viewport |
+| `isMobile` | `boolean` | Whether the viewport is mobile-sized |
+| `enableAutoFloatLocal` | `boolean` | Current auto-float setting |
+
+**Layout Context**
+
+| Property | Type | Description |
+|---|---|---|
+| `sidebarExpanded` | `boolean` | Sidebar state (for bar positioning) |
+| `sidebarWidth` | `number` | Sidebar width in pixels |
+| `assistenteExpanded` | `boolean` | Assistant panel state |
+
+**Handlers**
+
+| Property | Type | Description |
+|---|---|---|
+| `togglePlay` | `() => void` | Play/pause toggle |
+| `toggleMute` | `() => void` | Mute/unmute toggle |
+| `handleSeek` | `(value: number[]) => void` | Seek to position (Slider-compatible) |
+| `handleVolumeChange` | `(value: number[]) => void` | Change volume (Slider-compatible) |
+| `handleSetFloating` | `(floating: boolean) => void` | Set floating state |
+| `handleEnableManualFloat` | `() => void` | Trigger manual float |
+| `setPlaybackSpeed` | `(speed: number) => void` | Change playback speed |
+| `resetAudio` | `() => void` | Reset to beginning |
+
+**Audio Element Event Handlers**
+
+| Property | Type | Description |
+|---|---|---|
+| `onPlay` | `() => void` | Attach to `<audio onPlay>` |
+| `onPause` | `() => void` | Attach to `<audio onPause>` |
+| `onEnded` | `() => void` | Attach to `<audio onEnded>` |
+| `onTimeUpdate` | `(e) => void` | Attach to `<audio onTimeUpdate>` |
+| `onLoadedMetadata` | `(e) => void` | Attach to `<audio onLoadedMetadata>` |
+
+**Utilities**
+
+| Property | Type | Description |
+|---|---|---|
+| `formatTime` | `(time: number) => string` | Formats seconds as `MM:SS` |
+
+### Usage
+
+```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 });
+
+  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>
+  );
+}
+```
+
+> **Note**: For most use cases, use the `<AudioPlayer>` component directly. Use `useAudioPlayer` only when you need a fully custom player UI.
+
+---
+
+## `useLayoutShortcuts`
+
+Registers global keyboard shortcuts for layout control. Must be called **once** in the root layout component.
+
+**Source**: `components/hooks/use-layout-shortcuts.ts`
+
+### Registered Shortcuts
+
+| Shortcut | Action |
+|---|---|
+| `Ctrl+B` / `Cmd+B` | Toggle sidebar |
+
+### Usage
+
+```tsx
+import { useLayoutShortcuts } from 'xertica-ui/hooks';
+
+function AppLayout({ children }: { children: React.ReactNode }) {
+  useLayoutShortcuts(); // registers Ctrl+B for sidebar toggle
+  return <div>{children}</div>;
+}
+```
+
+> **Important**: Call this hook only once in your application. Calling it in multiple components will register duplicate event listeners.
+
+---
+
+## `useIsMobile` / `useMobile`
+
+Detects whether the current viewport is mobile-sized (< 768px).
+
+**Source**: `components/shared/use-mobile.ts`
+
+### Return Value
+
+Returns `boolean` — `true` if the viewport width is below the mobile breakpoint.
+
+### Usage
+
+```tsx
+import { useIsMobile } from 'xertica-ui/hooks';
+
+function ResponsiveComponent() {
+  const isMobile = useIsMobile();
+  return isMobile ? <MobileView /> : <DesktopView />;
+}
+```
+
+> **Note**: Both `useIsMobile` and `useMobile` are exported and are identical. `useIsMobile` is the preferred name. See [`use-mobile.md`](./use-mobile.md) for the full reference.
+
+---
+
+## AI Rules
+
+> [!IMPORTANT]
+> - **Always use hooks inside providers**: All context hooks (`useTheme`, `useLanguage`, `useBrandColors`, `useAssistente`, `useApiKey`, `useLayout`) require `<XerticaProvider>` in the component tree. Calling them outside a provider throws an error.
+> - **`useLayoutShortcuts` is singleton**: Call it exactly once in your root layout component, never in page-level or feature components.
+> - **Prefer `<AudioPlayer>` over `useAudioPlayer`**: The headless hook is for advanced custom UIs only. For standard playback, use the component.
+> - **`useLayout` for sidebar state**: Never manage sidebar width or expansion state manually. Always read from `useLayout()`.