xertica-ui 1.9.0 → 1.9.1

package/README.md

@@ -1,184 +1,184 @@
-# Xertica UI
-
-> **Enterprise-grade React design system** built on Tailwind CSS v4, Radix UI, and Lucide Icons — with a robust AI-first documentation layer for precise LLM-driven composition and autonomous agent interaction.
-
-[![npm version](https://img.shields.io/npm/v/xertica-ui)](https://www.npmjs.com/package/xertica-ui)
-[![license](https://img.shields.io/badge/license-proprietary-red)](./LICENSE)
-
----
-
-## 🤖 AI-First Single Source of Truth
-
-Xertica UI is specifically designed to be consumed by AI Agents (LLMs, code assistants, autonomous agents). We provide dedicated entry points for AI context:
-
-| File | Purpose |
-|---|---|
-| [`llms.txt`](./llms.txt) | Standard index for AI crawlers and context-aware agents. |
-| [`llms-full.txt`](./llms-full.txt) | **Complete documentation** of all 96 components in a single file for large-context LLMs. |
-| `docs/llms.md` | Master index for agents to navigate the documentation folder. |
-
----
-
-## 🚀 Quick Start — CLI (Recommended)
-
-Scaffold a full application with pre-configured routing, layout, and components:
-
-```bash
-npx xertica-ui@latest init my-app
-cd my-app
-npm run dev
-```
-
-The CLI scaffolds a complete Vite + React + TypeScript project with Portuguese UI localization and English AI-ready documentation.
-
----
-
-## 📦 Installation as a Library
-
-To add Xertica UI to an existing React project:
-
-```bash
-npm install xertica-ui
-```
-
-**1. Import the stylesheet** in your entry file (`main.tsx` or `App.tsx`):
-
-```tsx
-import 'xertica-ui/style.css';
-```
-
-**2. Wrap your app** with `XerticaProvider`:
-
-```tsx
-import { XerticaProvider } from 'xertica-ui';
-
-function App() {
-  return (
-    <XerticaProvider>
-      <YourApp />
-    </XerticaProvider>
-  );
-}
-```
-
----
-
-## 🛠️ The Layout System
-
-Xertica UI features an autonomous layout system managed by `LayoutContext`.
-
-### Mandatory Page Structure
-Every page **must** use the `<PageHeader>` component for its title and primary actions. Never use raw `h1` or `div` for headers.
-
-```tsx
-import { PageHeader, PageHeaderHeading, Button } from 'xertica-ui';
-
-export function MyPage() {
-  return (
-    <>
-      <PageHeader>
-        <PageHeaderHeading>Dashboard</PageHeaderHeading>
-        <Button>Action</Button>
-      </PageHeader>
-      <div className="p-6">
-        {/* Page Content */}
-      </div>
-    </>
-  );
-}
-```
-
-### `useLayout()` Hook
-Access the sidebar state, width, and toggle functions anywhere in the component tree:
-```tsx
-const { sidebarWidth, isSidebarOpen, toggleSidebar } = useLayout();
-```
-
----
-
-## 🧩 Component Catalog (96 Components)
-
-### Layout & Navigation
-`Header` · `Sidebar` · `PageHeader` · `Breadcrumb` · `NavigationMenu` · `Tabs` · `Pagination` · `Accordion` · `Collapsible`
-
-### Core Surfaces
-`Card` · `Separator` · `ScrollArea` · `AspectRatio` · `Resizable` · `Skeleton` · `Empty`
-
-### Forms & Inputs
-`Form` · `Input` · `Textarea` · `RichTextEditor` · `Label` · `Checkbox` · `RadioGroup` · `Switch` · `Select` · `Slider` · `Calendar` · `InputOTP` · `FileUpload` · `Search`
-
-### Actions & Data
-`Button` · `Toggle` · `ToggleGroup` · `Rating` · `Table` · `Badge` · `Avatar` · `Progress` · `StatsCard` · `Timeline` · `Stepper` · `TreeView` · `NotificationBadge` · `Chart`
-
-### Overlays & Feedback
-`Dialog` · `AlertDialog` · `Sheet` · `Drawer` · `Popover` · `HoverCard` · `Tooltip` · `Alert` · `Sonner (Toast)` · `Command`
-
----
-
-## 🌟 Specialized Modules
-
-### 🤖 AI Assistant
-Integrated AI chat panel with workspace support.
-- `XerticaAssistant` · `MarkdownMessage` · `CodeBlock` · `AssistantChart`
-
-### 🗺️ Maps & Geolocation
-First-class Google Maps integration.
-- `Map` · `RouteMap` · `SimpleMap` · `GoogleMapsLoader`
-
-### 🎙️ Media
-- `AudioPlayer` · `VideoPlayer` · `FloatingMediaWrapper`
-
----
-
-## 🎨 Design Tokens
-
-Xertica UI uses semantic CSS tokens. **Never use raw colors or generic Tailwind color classes**:
-
-```
-Background:     bg-background          text-foreground
-Card surface:   bg-card                text-card-foreground
-Muted area:     bg-muted               text-muted-foreground
-Primary action: bg-primary             text-primary-foreground
-Destructive:    bg-destructive         text-destructive-foreground
-Border:         border-border
-```
-
----
-
-## 🌍 Localization
-
-- **UI Components**: Fully localized in **Portuguese (pt-BR)** for end-users.
-- **Documentation/Code**: Strictly maintained in **English** for AI Agent compatibility and global developer standard.
-
----
-
-## 💻 Tech Stack
-
-| Technology | Version |
-|---|---|
-| React | 18.3 |
-| TypeScript | 5.7 |
-| Tailwind CSS | 4.0 |
-| Vite | 6.0 |
-| Radix UI | Latest |
-| Lucide React | 0.469+ |
-| Vitest | 4.1 |
-
----
-
-## 📜 Scripts
-
-| Command | Description |
-|---|---|
-| `npm run dev` | Start development server |
-| `npm run build` | Production bundle |
-| `npm run storybook` | Launch component library documentation |
-| `npm run test` | Run unit tests via Vitest |
-| `npm run type-check` | TypeScript validation |
-
----
-
-## ⚖️ License
-
-Proprietary — Xertica AI Team.
-
+# Xertica UI
+
+> **Enterprise-grade React design system** built on Tailwind CSS v4, Radix UI, and Lucide Icons — with a robust AI-first documentation layer for precise LLM-driven composition and autonomous agent interaction.
+
+[![npm version](https://img.shields.io/npm/v/xertica-ui)](https://www.npmjs.com/package/xertica-ui)
+[![license](https://img.shields.io/badge/license-proprietary-red)](./LICENSE)
+
+---
+
+## 🤖 AI-First Single Source of Truth
+
+Xertica UI is specifically designed to be consumed by AI Agents (LLMs, code assistants, autonomous agents). We provide dedicated entry points for AI context:
+
+| File | Purpose |
+|---|---|
+| [`llms.txt`](./llms.txt) | Standard index for AI crawlers and context-aware agents. |
+| [`llms-full.txt`](./llms-full.txt) | **Complete documentation** of all 96 components in a single file for large-context LLMs. |
+| `docs/llms.md` | Master index for agents to navigate the documentation folder. |
+
+---
+
+## 🚀 Quick Start — CLI (Recommended)
+
+Scaffold a full application with pre-configured routing, layout, and components:
+
+```bash
+npx xertica-ui@latest init my-app
+cd my-app
+npm run dev
+```
+
+The CLI scaffolds a complete Vite + React + TypeScript project with Portuguese UI localization and English AI-ready documentation.
+
+---
+
+## 📦 Installation as a Library
+
+To add Xertica UI to an existing React project:
+
+```bash
+npm install xertica-ui
+```
+
+**1. Import the stylesheet** in your entry file (`main.tsx` or `App.tsx`):
+
+```tsx
+import 'xertica-ui/style.css';
+```
+
+**2. Wrap your app** with `XerticaProvider`:
+
+```tsx
+import { XerticaProvider } from 'xertica-ui';
+
+function App() {
+  return (
+    <XerticaProvider>
+      <YourApp />
+    </XerticaProvider>
+  );
+}
+```
+
+---
+
+## 🛠️ The Layout System
+
+Xertica UI features an autonomous layout system managed by `LayoutContext`.
+
+### Mandatory Page Structure
+Every page **must** use the `<PageHeader>` component for its title and primary actions. Never use raw `h1` or `div` for headers.
+
+```tsx
+import { PageHeader, PageHeaderHeading, Button } from 'xertica-ui';
+
+export function MyPage() {
+  return (
+    <>
+      <PageHeader>
+        <PageHeaderHeading>Dashboard</PageHeaderHeading>
+        <Button>Action</Button>
+      </PageHeader>
+      <div className="p-6">
+        {/* Page Content */}
+      </div>
+    </>
+  );
+}
+```
+
+### `useLayout()` Hook
+Access the sidebar state, width, and toggle functions anywhere in the component tree:
+```tsx
+const { sidebarWidth, isSidebarOpen, toggleSidebar } = useLayout();
+```
+
+---
+
+## 🧩 Component Catalog (96 Components)
+
+### Layout & Navigation
+`Header` · `Sidebar` · `PageHeader` · `Breadcrumb` · `NavigationMenu` · `Tabs` · `Pagination` · `Accordion` · `Collapsible`
+
+### Core Surfaces
+`Card` · `Separator` · `ScrollArea` · `AspectRatio` · `Resizable` · `Skeleton` · `Empty`
+
+### Forms & Inputs
+`Form` · `Input` · `Textarea` · `RichTextEditor` · `Label` · `Checkbox` · `RadioGroup` · `Switch` · `Select` · `Slider` · `Calendar` · `InputOTP` · `FileUpload` · `Search`
+
+### Actions & Data
+`Button` · `Toggle` · `ToggleGroup` · `Rating` · `Table` · `Badge` · `Avatar` · `Progress` · `StatsCard` · `Timeline` · `Stepper` · `TreeView` · `NotificationBadge` · `Chart`
+
+### Overlays & Feedback
+`Dialog` · `AlertDialog` · `Sheet` · `Drawer` · `Popover` · `HoverCard` · `Tooltip` · `Alert` · `Sonner (Toast)` · `Command`
+
+---
+
+## 🌟 Specialized Modules
+
+### 🤖 AI Assistant
+Integrated AI chat panel with workspace support.
+- `XerticaAssistant` · `MarkdownMessage` · `CodeBlock` · `AssistantChart`
+
+### 🗺️ Maps & Geolocation
+First-class Google Maps integration.
+- `Map` · `RouteMap` · `SimpleMap` · `GoogleMapsLoader`
+
+### 🎙️ Media
+- `AudioPlayer` · `VideoPlayer` · `FloatingMediaWrapper`
+
+---
+
+## 🎨 Design Tokens
+
+Xertica UI uses semantic CSS tokens. **Never use raw colors or generic Tailwind color classes**:
+
+```
+Background:     bg-background          text-foreground
+Card surface:   bg-card                text-card-foreground
+Muted area:     bg-muted               text-muted-foreground
+Primary action: bg-primary             text-primary-foreground
+Destructive:    bg-destructive         text-destructive-foreground
+Border:         border-border
+```
+
+---
+
+## 🌍 Localization
+
+- **UI Components**: Fully localized in **Portuguese (pt-BR)** for end-users.
+- **Documentation/Code**: Strictly maintained in **English** for AI Agent compatibility and global developer standard.
+
+---
+
+## 💻 Tech Stack
+
+| Technology | Version |
+|---|---|
+| React | 18.3 |
+| TypeScript | 5.7 |
+| Tailwind CSS | 4.0 |
+| Vite | 6.0 |
+| Radix UI | Latest |
+| Lucide React | 0.469+ |
+| Vitest | 4.1 |
+
+---
+
+## 📜 Scripts
+
+| Command | Description |
+|---|---|
+| `npm run dev` | Start development server |
+| `npm run build` | Production bundle |
+| `npm run storybook` | Launch component library documentation |
+| `npm run test` | Run unit tests via Vitest |
+| `npm run type-check` | TypeScript validation |
+
+---
+
+## ⚖️ License
+
+Proprietary — Xertica AI Team.
+

package/components/assistant/modern-chat-input/modern-chat-input.mdx

@@ -1,71 +1,71 @@
-import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
-import * as ModernChatInputStories from './modern-chat-input.stories';
-
-<Meta of={ModernChatInputStories} />
-
-<Title />
-<Subtitle>An advanced, high-performance chat input for the Xertica Assistant.</Subtitle>
-
-<Description />
-
-<Primary />
-
----
-
-## Usage Patterns
-
-### Standard Floating Input
-Optimized for chat interfaces with multi-line support, voice recording, and action chips.
-
-<Canvas>
-  <ModernChatInputStories.Default />
-</Canvas>
-
-### Full-Page Variant
-Adjusts maximum width and alignment for use in standalone chat pages.
-
-<Canvas>
-  <ModernChatInputStories.FullPage />
-</Canvas>
-
----
-
-## Feature Flags
-
-Each input capability can be individually toggled via boolean props.
-All flags default to `true` for full backward compatibility.
-
-| Prop | Controls | Default |
-|---|---|---|
-| `enableAudioInput` | Voice recording button | `true` |
-| `enableFileAttachment` | File attachment (paperclip) button | `true` |
-| `enableDocumentCreation` | "Create document" menu item | `true` |
-| `enablePodcastGeneration` | "Generate podcast" menu item | `true` |
-| `enableSearch` | "Search" menu item | `true` |
-
-> [!NOTE]
-> When all three action types (`enableDocumentCreation`, `enablePodcastGeneration`, `enableSearch`) are set to `false`, the "+" menu button is completely hidden.
-
-### Text Only
-All action buttons disabled — only the text input and send button remain.
-
-<Canvas>
-  <ModernChatInputStories.TextOnly />
-</Canvas>
-
-### Selective Actions
-Only document creation and search are enabled for a focused workflow.
-
-<Canvas>
-  <ModernChatInputStories.SelectiveActions />
-</Canvas>
-
----
-
-## AI Best Practices
-
-> [!IMPORTANT]
-> - **Action Workflow** — Handle the `onSubmit` callback's optional `action` parameter to distinguish between standard text messages and intent-driven generations (Documents, Podcasts, Search).
-> - **State Sync** — Always maintain the `value` in a parent state and update it via `onChange` and `onVoiceRecording` to ensure consistent data binding.
-> - **Dynamic Sizing** — The input automatically expands up to 100px based on content; ensure the parent container can accommodate these height changes without layout shift.
-> - **Feature Flags** — Pass flags like `enableSearch={false}` or `enableAudioInput={false}` to tailor input capabilities per use-case. Flags are independent and can be combined freely.
+import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
+import * as ModernChatInputStories from './modern-chat-input.stories';
+
+<Meta of={ModernChatInputStories} />
+
+<Title />
+<Subtitle>An advanced, high-performance chat input for the Xertica Assistant.</Subtitle>
+
+<Description />
+
+<Primary />
+
+---
+
+## Usage Patterns
+
+### Standard Floating Input
+Optimized for chat interfaces with multi-line support, voice recording, and action chips.
+
+<Canvas>
+  <ModernChatInputStories.Default />
+</Canvas>
+
+### Full-Page Variant
+Adjusts maximum width and alignment for use in standalone chat pages.
+
+<Canvas>
+  <ModernChatInputStories.FullPage />
+</Canvas>
+
+---
+
+## Feature Flags
+
+Each input capability can be individually toggled via boolean props.
+All flags default to `true` for full backward compatibility.
+
+| Prop | Controls | Default |
+|---|---|---|
+| `enableAudioInput` | Voice recording button | `true` |
+| `enableFileAttachment` | File attachment (paperclip) button | `true` |
+| `enableDocumentCreation` | "Create document" menu item | `true` |
+| `enablePodcastGeneration` | "Generate podcast" menu item | `true` |
+| `enableSearch` | "Search" menu item | `true` |
+
+> [!NOTE]
+> When all three action types (`enableDocumentCreation`, `enablePodcastGeneration`, `enableSearch`) are set to `false`, the "+" menu button is completely hidden.
+
+### Text Only
+All action buttons disabled — only the text input and send button remain.
+
+<Canvas>
+  <ModernChatInputStories.TextOnly />
+</Canvas>
+
+### Selective Actions
+Only document creation and search are enabled for a focused workflow.
+
+<Canvas>
+  <ModernChatInputStories.SelectiveActions />
+</Canvas>
+
+---
+
+## AI Best Practices
+
+> [!IMPORTANT]
+> - **Action Workflow** — Handle the `onSubmit` callback's optional `action` parameter to distinguish between standard text messages and intent-driven generations (Documents, Podcasts, Search).
+> - **State Sync** — Always maintain the `value` in a parent state and update it via `onChange` and `onVoiceRecording` to ensure consistent data binding.
+> - **Dynamic Sizing** — The input automatically expands up to 100px based on content; ensure the parent container can accommodate these height changes without layout shift.
+> - **Feature Flags** — Pass flags like `enableSearch={false}` or `enableAudioInput={false}` to tailor input capabilities per use-case. Flags are independent and can be combined freely.