xertica-ui 2.2.1 → 2.4.0

package/docs/components/menubar.md

@@ -1,89 +1,89 @@
-# Menubar
-
-## Overview
-
-An application-style horizontal menu bar with multiple dropdown menus — similar to the menu bars in desktop applications (File, Edit, View…). Less common in web apps but useful for power-user tools and editors.
-
----
-
-## When to Use
-
-- Rich text editors, code editors, or complex tools
-- Applications targeting power users who expect desktop application conventions
-
-## When NOT to Use
-
-- Standard management dashboards — use `<Sidebar>` for navigation.
-- Single-level navigation — use `<NavigationMenu>` or `<Tabs>`.
-
----
-
-## Anatomy
-
-```
-<Menubar>
-  <MenubarMenu>
-    <MenubarTrigger>File</MenubarTrigger>
-    <MenubarContent>
-      <MenubarItem>New</MenubarItem>
-      <MenubarItem>Open</MenubarItem>
-      <MenubarSeparator />
-      <MenubarItem>Export</MenubarItem>
-    </MenubarContent>
-  </MenubarMenu>
-</Menubar>
-```
-
----
-
-## Examples
-
-```tsx
-import {
-  Menubar,
-  MenubarContent,
-  MenubarItem,
-  MenubarMenu,
-  MenubarSeparator,
-  MenubarShortcut,
-  MenubarTrigger,
-} from 'xertica-ui/ui';
-
-<Menubar>
-  <MenubarMenu>
-    <MenubarTrigger>File</MenubarTrigger>
-    <MenubarContent>
-      <MenubarItem>
-        New Tab <MenubarShortcut>⌘T</MenubarShortcut>
-      </MenubarItem>
-      <MenubarItem>
-        New Window <MenubarShortcut>⌘N</MenubarShortcut>
-      </MenubarItem>
-      <MenubarSeparator />
-      <MenubarItem>Export...</MenubarItem>
-    </MenubarContent>
-  </MenubarMenu>
-  <MenubarMenu>
-    <MenubarTrigger>Edit</MenubarTrigger>
-    <MenubarContent>
-      <MenubarItem>
-        Cut <MenubarShortcut>⌘X</MenubarShortcut>
-      </MenubarItem>
-      <MenubarItem>
-        Copy <MenubarShortcut>⌘C</MenubarShortcut>
-      </MenubarItem>
-      <MenubarItem>
-        Paste <MenubarShortcut>⌘V</MenubarShortcut>
-      </MenubarItem>
-    </MenubarContent>
-  </MenubarMenu>
-</Menubar>;
-```
-
----
-
-## AI Rules
-
-- Use `<MenubarShortcut>` for keyboard shortcut labels — always inside the item, right-aligned.
-- Destructive items use `className="text-destructive"`.
-- `Menubar` is rarely used in management dashboards — `Sidebar` + `DropdownMenu` are the standard substitutes.
+# Menubar
+
+## Overview
+
+An application-style horizontal menu bar with multiple dropdown menus — similar to the menu bars in desktop applications (File, Edit, View…). Less common in web apps but useful for power-user tools and editors.
+
+---
+
+## When to Use
+
+- Rich text editors, code editors, or complex tools
+- Applications targeting power users who expect desktop application conventions
+
+## When NOT to Use
+
+- Standard management dashboards — use `<Sidebar>` for navigation.
+- Single-level navigation — use `<NavigationMenu>` or `<Tabs>`.
+
+---
+
+## Anatomy
+
+```
+<Menubar>
+  <MenubarMenu>
+    <MenubarTrigger>File</MenubarTrigger>
+    <MenubarContent>
+      <MenubarItem>New</MenubarItem>
+      <MenubarItem>Open</MenubarItem>
+      <MenubarSeparator />
+      <MenubarItem>Export</MenubarItem>
+    </MenubarContent>
+  </MenubarMenu>
+</Menubar>
+```
+
+---
+
+## Examples
+
+```tsx
+import {
+  Menubar,
+  MenubarContent,
+  MenubarItem,
+  MenubarMenu,
+  MenubarSeparator,
+  MenubarShortcut,
+  MenubarTrigger,
+} from 'xertica-ui/ui';
+
+<Menubar>
+  <MenubarMenu>
+    <MenubarTrigger>File</MenubarTrigger>
+    <MenubarContent>
+      <MenubarItem>
+        New Tab <MenubarShortcut>⌘T</MenubarShortcut>
+      </MenubarItem>
+      <MenubarItem>
+        New Window <MenubarShortcut>⌘N</MenubarShortcut>
+      </MenubarItem>
+      <MenubarSeparator />
+      <MenubarItem>Export...</MenubarItem>
+    </MenubarContent>
+  </MenubarMenu>
+  <MenubarMenu>
+    <MenubarTrigger>Edit</MenubarTrigger>
+    <MenubarContent>
+      <MenubarItem>
+        Cut <MenubarShortcut>⌘X</MenubarShortcut>
+      </MenubarItem>
+      <MenubarItem>
+        Copy <MenubarShortcut>⌘C</MenubarShortcut>
+      </MenubarItem>
+      <MenubarItem>
+        Paste <MenubarShortcut>⌘V</MenubarShortcut>
+      </MenubarItem>
+    </MenubarContent>
+  </MenubarMenu>
+</Menubar>;
+```
+
+---
+
+## AI Rules
+
+- Use `<MenubarShortcut>` for keyboard shortcut labels — always inside the item, right-aligned.
+- Destructive items use `className="text-destructive"`.
+- `Menubar` is rarely used in management dashboards — `Sidebar` + `DropdownMenu` are the standard substitutes.

package/docs/components/modern-chat-input.md

@@ -1,164 +1,164 @@
-# ModernChatInput
-
-An advanced floating chat input with rich action chips, voice recording simulation, and file attachment support. Used as the primary input interface inside `XerticaAssistant`.
-
----
-
-## Import
-
-```tsx
-import { ModernChatInput } from 'xertica-ui/assistant';
-```
-
----
-
-## Basic Usage
-
-```tsx
-const [message, setMessage] = useState('');
-
-<ModernChatInput
-  value={message}
-  onChange={setMessage}
-  onSubmit={() => {
-    console.log('Sending:', message);
-    setMessage('');
-  }}
-/>;
-```
-
----
-
-## Props
-
-| Prop                      | Type                            | Default                               | Description                                                 |
-| ------------------------- | ------------------------------- | ------------------------------------- | ----------------------------------------------------------- |
-| `value`                   | `string`                        | _(required)_                          | Current input text value                                    |
-| `onChange`                | `(value: string) => void`       | _(required)_                          | Callback fired on every keystroke                           |
-| `onSubmit`                | `(action?: ActionType) => void` | _(required)_                          | Callback fired when user submits (Enter key or send button) |
-| `placeholder`             | `string`                        | `'Mande uma mensagem para o Xertica'` | Input placeholder text                                      |
-| `disabled`                | `boolean`                       | `false`                               | Disables the input and all action buttons                   |
-| `onFileUpload`            | `() => void`                    | —                                     | Callback for the file attachment button                     |
-| `onAudioUpload`           | `() => void`                    | —                                     | Callback for the audio upload button                        |
-| `onVoiceRecording`        | `(transcript: string) => void`  | —                                     | Callback fired when voice recording finishes                |
-| `isFullPage`              | `boolean`                       | `false`                               | Adjusts layout for full-page assistant view                 |
-| `enableAudioInput`        | `boolean`                       | `true`                                | Shows/hides the voice recording button                      |
-| `enableFileAttachment`    | `boolean`                       | `true`                                | Shows/hides the file attachment button                      |
-| `enableDocumentCreation`  | `boolean`                       | `true`                                | Shows/hides the "Create document" action chip               |
-| `enablePodcastGeneration` | `boolean`                       | `true`                                | Shows/hides the "Generate podcast" action chip              |
-| `enableSearch`            | `boolean`                       | `true`                                | Shows/hides the "Search" action chip                        |
-
----
-
-## `ActionType`
-
-The `onSubmit` callback receives an optional `ActionType` parameter indicating which special action was triggered:
-
-```tsx
-type ActionType = 'document' | 'podcast' | 'search' | null;
-```
-
-| Value        | Trigger                  | Description                           |
-| ------------ | ------------------------ | ------------------------------------- |
-| `null`       | Enter key or send button | Standard text message                 |
-| `'document'` | "Create document" chip   | Triggers document generation workflow |
-| `'podcast'`  | "Generate podcast" chip  | Triggers audio podcast generation     |
-| `'search'`   | "Search" chip            | Triggers knowledge base search        |
-
-### Handling Actions
-
-```tsx
-<ModernChatInput
-  value={message}
-  onChange={setMessage}
-  onSubmit={action => {
-    if (action === 'document') {
-      // trigger document generation
-    } else if (action === 'podcast') {
-      // trigger podcast generation
-    } else if (action === 'search') {
-      // trigger search
-    } else {
-      // send regular message
-    }
-    setMessage('');
-  }}
-/>
-```
-
----
-
-## Features
-
-### Auto-Resizing Textarea
-
-The input grows vertically as the user types, up to a maximum height of 100px. Beyond that, it becomes scrollable.
-
-### Action Chips
-
-A `+` button opens a popover with quick-action chips:
-
-- **Document** (`FileText` icon) — triggers `onSubmit('document')`
-- **Podcast** (`Radio` icon) — triggers `onSubmit('podcast')`
-- **Search** (`Search` icon) — triggers `onSubmit('search')`
-
-Each chip can be individually disabled via props.
-
-### Voice Recording (Simulated)
-
-When `enableAudioInput={true}`, a microphone button is shown. Clicking it:
-
-1. Shows a recording indicator with a pulsing animation
-2. After 3 seconds, calls `onVoiceRecording` with a simulated transcript string
-3. Returns to idle state
-
-> **Note**: Voice recording is simulated — it does not use the browser's MediaRecorder API. The transcript returned is a placeholder string for UI demonstration purposes.
-
-### Keyboard Shortcuts
-
-- **Enter** — submits the message
-- **Shift+Enter** — inserts a newline (multi-line input)
-
----
-
-## Usage with XerticaAssistant
-
-`ModernChatInput` is used internally by `XerticaAssistant`. You typically do not need to use it directly unless building a custom chat interface:
-
-```tsx
-import { ModernChatInput } from 'xertica-ui/assistant';
-import { useAssistant } from 'xertica-ui/assistant'; // internal hook
-
-function CustomChatInterface() {
-  const [message, setMessage] = useState('');
-
-  const handleSubmit = (action?: ActionType) => {
-    // handle message or action
-    setMessage('');
-  };
-
-  return (
-    <div className="flex flex-col h-screen">
-      <div className="flex-1 overflow-y-auto">{/* messages */}</div>
-      <ModernChatInput
-        value={message}
-        onChange={setMessage}
-        onSubmit={handleSubmit}
-        isFullPage={true}
-      />
-    </div>
-  );
-}
-```
-
----
-
-## AI Rules
-
-> [!IMPORTANT]
->
-> - **Controlled component**: Always provide both `value` and `onChange`. This is a controlled input — do not use it uncontrolled.
-> - **Clear after submit**: Call `setMessage('')` (or equivalent) inside `onSubmit` to reset the input after sending.
-> - **`isFullPage` for page layouts**: Set `isFullPage={true}` when using the input in a full-page assistant view (not the sidebar panel). This adjusts padding and max-width.
-> - **Voice recording is simulated**: Do not rely on `onVoiceRecording` for real speech-to-text. Integrate a real STT service and pass the transcript via `onChange` instead.
-> - **Disable unused actions**: If your application does not support document generation or podcasts, set `enableDocumentCreation={false}` and `enablePodcastGeneration={false}` to avoid confusing users.
+# ModernChatInput
+
+An advanced floating chat input with rich action chips, voice recording simulation, and file attachment support. Used as the primary input interface inside `XerticaAssistant`.
+
+---
+
+## Import
+
+```tsx
+import { ModernChatInput } from 'xertica-ui/assistant';
+```
+
+---
+
+## Basic Usage
+
+```tsx
+const [message, setMessage] = useState('');
+
+<ModernChatInput
+  value={message}
+  onChange={setMessage}
+  onSubmit={() => {
+    console.log('Sending:', message);
+    setMessage('');
+  }}
+/>;
+```
+
+---
+
+## Props
+
+| Prop                      | Type                            | Default                               | Description                                                 |
+| ------------------------- | ------------------------------- | ------------------------------------- | ----------------------------------------------------------- |
+| `value`                   | `string`                        | _(required)_                          | Current input text value                                    |
+| `onChange`                | `(value: string) => void`       | _(required)_                          | Callback fired on every keystroke                           |
+| `onSubmit`                | `(action?: ActionType) => void` | _(required)_                          | Callback fired when user submits (Enter key or send button) |
+| `placeholder`             | `string`                        | `'Mande uma mensagem para o Xertica'` | Input placeholder text                                      |
+| `disabled`                | `boolean`                       | `false`                               | Disables the input and all action buttons                   |
+| `onFileUpload`            | `() => void`                    | —                                     | Callback for the file attachment button                     |
+| `onAudioUpload`           | `() => void`                    | —                                     | Callback for the audio upload button                        |
+| `onVoiceRecording`        | `(transcript: string) => void`  | —                                     | Callback fired when voice recording finishes                |
+| `isFullPage`              | `boolean`                       | `false`                               | Adjusts layout for full-page assistant view                 |
+| `enableAudioInput`        | `boolean`                       | `true`                                | Shows/hides the voice recording button                      |
+| `enableFileAttachment`    | `boolean`                       | `true`                                | Shows/hides the file attachment button                      |
+| `enableDocumentCreation`  | `boolean`                       | `true`                                | Shows/hides the "Create document" action chip               |
+| `enablePodcastGeneration` | `boolean`                       | `true`                                | Shows/hides the "Generate podcast" action chip              |
+| `enableSearch`            | `boolean`                       | `true`                                | Shows/hides the "Search" action chip                        |
+
+---
+
+## `ActionType`
+
+The `onSubmit` callback receives an optional `ActionType` parameter indicating which special action was triggered:
+
+```tsx
+type ActionType = 'document' | 'podcast' | 'search' | null;
+```
+
+| Value        | Trigger                  | Description                           |
+| ------------ | ------------------------ | ------------------------------------- |
+| `null`       | Enter key or send button | Standard text message                 |
+| `'document'` | "Create document" chip   | Triggers document generation workflow |
+| `'podcast'`  | "Generate podcast" chip  | Triggers audio podcast generation     |
+| `'search'`   | "Search" chip            | Triggers knowledge base search        |
+
+### Handling Actions
+
+```tsx
+<ModernChatInput
+  value={message}
+  onChange={setMessage}
+  onSubmit={action => {
+    if (action === 'document') {
+      // trigger document generation
+    } else if (action === 'podcast') {
+      // trigger podcast generation
+    } else if (action === 'search') {
+      // trigger search
+    } else {
+      // send regular message
+    }
+    setMessage('');
+  }}
+/>
+```
+
+---
+
+## Features
+
+### Auto-Resizing Textarea
+
+The input grows vertically as the user types, up to a maximum height of 100px. Beyond that, it becomes scrollable.
+
+### Action Chips
+
+A `+` button opens a popover with quick-action chips:
+
+- **Document** (`FileText` icon) — triggers `onSubmit('document')`
+- **Podcast** (`Radio` icon) — triggers `onSubmit('podcast')`
+- **Search** (`Search` icon) — triggers `onSubmit('search')`
+
+Each chip can be individually disabled via props.
+
+### Voice Recording (Simulated)
+
+When `enableAudioInput={true}`, a microphone button is shown. Clicking it:
+
+1. Shows a recording indicator with a pulsing animation
+2. After 3 seconds, calls `onVoiceRecording` with a simulated transcript string
+3. Returns to idle state
+
+> **Note**: Voice recording is simulated — it does not use the browser's MediaRecorder API. The transcript returned is a placeholder string for UI demonstration purposes.
+
+### Keyboard Shortcuts
+
+- **Enter** — submits the message
+- **Shift+Enter** — inserts a newline (multi-line input)
+
+---
+
+## Usage with XerticaAssistant
+
+`ModernChatInput` is used internally by `XerticaAssistant`. You typically do not need to use it directly unless building a custom chat interface:
+
+```tsx
+import { ModernChatInput } from 'xertica-ui/assistant';
+import { useAssistant } from 'xertica-ui/assistant'; // internal hook
+
+function CustomChatInterface() {
+  const [message, setMessage] = useState('');
+
+  const handleSubmit = (action?: ActionType) => {
+    // handle message or action
+    setMessage('');
+  };
+
+  return (
+    <div className="flex flex-col h-screen">
+      <div className="flex-1 overflow-y-auto">{/* messages */}</div>
+      <ModernChatInput
+        value={message}
+        onChange={setMessage}
+        onSubmit={handleSubmit}
+        isFullPage={true}
+      />
+    </div>
+  );
+}
+```
+
+---
+
+## AI Rules
+
+> [!IMPORTANT]
+>
+> - **Controlled component**: Always provide both `value` and `onChange`. This is a controlled input — do not use it uncontrolled.
+> - **Clear after submit**: Call `setMessage('')` (or equivalent) inside `onSubmit` to reset the input after sending.
+> - **`isFullPage` for page layouts**: Set `isFullPage={true}` when using the input in a full-page assistant view (not the sidebar panel). This adjusts padding and max-width.
+> - **Voice recording is simulated**: Do not rely on `onVoiceRecording` for real speech-to-text. Integrate a real STT service and pass the transcript via `onChange` instead.
+> - **Disable unused actions**: If your application does not support document generation or podcasts, set `enableDocumentCreation={false}` and `enablePodcastGeneration={false}` to avoid confusing users.