xertica-ui 2.2.1 → 2.4.0

package/docs/components/form.md

@@ -1,177 +1,177 @@
-# Form
-
-## Overview
-
-`Form` is the integration layer between `react-hook-form` and Xertica UI components. It provides a context-aware set of wrappers (`FormField`, `FormItem`, `FormLabel`, `FormControl`, `FormMessage`, `FormDescription`) that automatically connect to form state, display validation errors, and manage ARIA attributes.
-
----
-
-## When to Use
-
-- Any data-entry form that requires validation.
-- Always used with `react-hook-form` + `zod`.
-
-## When NOT to Use
-
-- Simple one-field forms without validation — use a plain `<Input>` with `onChange` state.
-- Server-side rendered read-only data — display with `<Card>` and typography.
-
----
-
-## Required Dependencies
-
-```bash
-npm install react-hook-form zod @hookform/resolvers
-```
-
----
-
-## Anatomy
-
-```tsx
-<Form {...form}>
-  {' '}
-  ← Spreads RHF context
-  <form onSubmit={form.handleSubmit(onSubmit)}>
-    <FormField
-      control={form.control}
-      name="fieldName"
-      render={({ field }) => (
-        <FormItem>
-          <FormLabel>Label</FormLabel>
-          <FormControl>
-            <Input {...field} /> ← Spread field props here
-          </FormControl>
-          <FormDescription>Helper text</FormDescription>
-          <FormMessage /> ← Auto error from zod
-        </FormItem>
-      )}
-    />
-    <Button type="submit">Submit</Button>
-  </form>
-</Form>
-```
-
----
-
-## Sub-Components
-
-| Component         | Description                                                              |
-| ----------------- | ------------------------------------------------------------------------ |
-| `Form`            | Wraps the form with react-hook-form context. Spread `{...form}` on it.   |
-| `FormField`       | Connects a single field to form state via `control` and `name`.          |
-| `FormItem`        | Layout wrapper for label + control + message.                            |
-| `FormLabel`       | Accessible label, automatically linked to the control's `id`.            |
-| `FormControl`     | Wrapper that applies `aria-invalid` and `aria-describedby` to the child. |
-| `FormDescription` | Helper text shown below the control.                                     |
-| `FormMessage`     | Renders the zod validation error for this field. Auto-hides when valid.  |
-
----
-
-## Props
-
-### FormField
-
-| Prop      | Type                       | Required | Description                           |
-| --------- | -------------------------- | -------- | ------------------------------------- |
-| `control` | `Control`                  | **Yes**  | `form.control` from `useForm()`       |
-| `name`    | `string`                   | **Yes**  | Field name, must match schema key     |
-| `render`  | `({ field }) => ReactNode` | **Yes**  | Render function receiving field props |
-
----
-
-## Examples
-
-### Complete Validated Form
-
-```tsx
-import { zodResolver } from '@hookform/resolvers/zod';
-import { useForm } from 'react-hook-form';
-import * as z from 'zod';
-import {
-  Form,
-  FormField,
-  FormItem,
-  FormLabel,
-  FormControl,
-  FormMessage,
-  Input,
-  Button,
-  Card,
-  CardContent,
-  CardFooter,
-  CardHeader,
-  CardTitle,
-} from 'xertica-ui/ui';
-
-const schema = z.object({
-  name: z.string().min(2, 'Name must be at least 2 characters'),
-  email: z.string().email('Invalid email'),
-});
-
-export function MyForm() {
-  const form = useForm({ resolver: zodResolver(schema), defaultValues: { name: '', email: '' } });
-
-  return (
-    <Card>
-      <CardHeader>
-        <CardTitle>Create User</CardTitle>
-      </CardHeader>
-      <Form {...form}>
-        <form onSubmit={form.handleSubmit(data => console.log(data))}>
-          <CardContent className="grid gap-4">
-            <FormField
-              control={form.control}
-              name="name"
-              render={({ field }) => (
-                <FormItem>
-                  <FormLabel>Full Name</FormLabel>
-                  <FormControl>
-                    <Input placeholder="John Doe" {...field} />
-                  </FormControl>
-                  <FormMessage />
-                </FormItem>
-              )}
-            />
-            <FormField
-              control={form.control}
-              name="email"
-              render={({ field }) => (
-                <FormItem>
-                  <FormLabel>Email</FormLabel>
-                  <FormControl>
-                    <Input type="email" placeholder="john@example.com" {...field} />
-                  </FormControl>
-                  <FormMessage />
-                </FormItem>
-              )}
-            />
-          </CardContent>
-          <CardFooter className="justify-end">
-            <Button type="submit">Create</Button>
-          </CardFooter>
-        </form>
-      </Form>
-    </Card>
-  );
-}
-```
-
----
-
-## AI Rules
-
-- **Never implement manual validation state** (`useState` + if blocks). Use `zod` + `react-hook-form`.
-- **Never render error `<span>` or `<p>` manually** — `<FormMessage />` handles this automatically.
-- The `{...field}` spread goes on the **inner input component** (`<Input>`, `<Textarea>`, etc.), not on `<FormControl>`.
-- For `<Select>` fields, use `onValueChange={field.onChange}` and `defaultValue={field.value}` — do not spread `{...field}` on `<Select>`.
-- For `<Checkbox>` fields, use `checked={field.value}` and `onCheckedChange={field.onChange}`.
-- `<FormControl>` must be the **direct parent** of the input component — wrapping it further breaks the ARIA linking.
-
----
-
-## Related Components
-
-- [`Input`](./input.md), [`Textarea`](./textarea.md), [`Select`](./select.md), [`Checkbox`](./checkbox.md), [`Switch`](./switch.md)
-- [`Dialog`](./dialog.md) — Common container for forms
-- [Form Pattern](../patterns/form.md) — Complete real-world usage example
+# Form
+
+## Overview
+
+`Form` is the integration layer between `react-hook-form` and Xertica UI components. It provides a context-aware set of wrappers (`FormField`, `FormItem`, `FormLabel`, `FormControl`, `FormMessage`, `FormDescription`) that automatically connect to form state, display validation errors, and manage ARIA attributes.
+
+---
+
+## When to Use
+
+- Any data-entry form that requires validation.
+- Always used with `react-hook-form` + `zod`.
+
+## When NOT to Use
+
+- Simple one-field forms without validation — use a plain `<Input>` with `onChange` state.
+- Server-side rendered read-only data — display with `<Card>` and typography.
+
+---
+
+## Required Dependencies
+
+```bash
+npm install react-hook-form zod @hookform/resolvers
+```
+
+---
+
+## Anatomy
+
+```tsx
+<Form {...form}>
+  {' '}
+  ← Spreads RHF context
+  <form onSubmit={form.handleSubmit(onSubmit)}>
+    <FormField
+      control={form.control}
+      name="fieldName"
+      render={({ field }) => (
+        <FormItem>
+          <FormLabel>Label</FormLabel>
+          <FormControl>
+            <Input {...field} /> ← Spread field props here
+          </FormControl>
+          <FormDescription>Helper text</FormDescription>
+          <FormMessage /> ← Auto error from zod
+        </FormItem>
+      )}
+    />
+    <Button type="submit">Submit</Button>
+  </form>
+</Form>
+```
+
+---
+
+## Sub-Components
+
+| Component         | Description                                                              |
+| ----------------- | ------------------------------------------------------------------------ |
+| `Form`            | Wraps the form with react-hook-form context. Spread `{...form}` on it.   |
+| `FormField`       | Connects a single field to form state via `control` and `name`.          |
+| `FormItem`        | Layout wrapper for label + control + message.                            |
+| `FormLabel`       | Accessible label, automatically linked to the control's `id`.            |
+| `FormControl`     | Wrapper that applies `aria-invalid` and `aria-describedby` to the child. |
+| `FormDescription` | Helper text shown below the control.                                     |
+| `FormMessage`     | Renders the zod validation error for this field. Auto-hides when valid.  |
+
+---
+
+## Props
+
+### FormField
+
+| Prop      | Type                       | Required | Description                           |
+| --------- | -------------------------- | -------- | ------------------------------------- |
+| `control` | `Control`                  | **Yes**  | `form.control` from `useForm()`       |
+| `name`    | `string`                   | **Yes**  | Field name, must match schema key     |
+| `render`  | `({ field }) => ReactNode` | **Yes**  | Render function receiving field props |
+
+---
+
+## Examples
+
+### Complete Validated Form
+
+```tsx
+import { zodResolver } from '@hookform/resolvers/zod';
+import { useForm } from 'react-hook-form';
+import * as z from 'zod';
+import {
+  Form,
+  FormField,
+  FormItem,
+  FormLabel,
+  FormControl,
+  FormMessage,
+  Input,
+  Button,
+  Card,
+  CardContent,
+  CardFooter,
+  CardHeader,
+  CardTitle,
+} from 'xertica-ui/ui';
+
+const schema = z.object({
+  name: z.string().min(2, 'Name must be at least 2 characters'),
+  email: z.string().email('Invalid email'),
+});
+
+export function MyForm() {
+  const form = useForm({ resolver: zodResolver(schema), defaultValues: { name: '', email: '' } });
+
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>Create User</CardTitle>
+      </CardHeader>
+      <Form {...form}>
+        <form onSubmit={form.handleSubmit(data => console.log(data))}>
+          <CardContent className="grid gap-4">
+            <FormField
+              control={form.control}
+              name="name"
+              render={({ field }) => (
+                <FormItem>
+                  <FormLabel>Full Name</FormLabel>
+                  <FormControl>
+                    <Input placeholder="John Doe" {...field} />
+                  </FormControl>
+                  <FormMessage />
+                </FormItem>
+              )}
+            />
+            <FormField
+              control={form.control}
+              name="email"
+              render={({ field }) => (
+                <FormItem>
+                  <FormLabel>Email</FormLabel>
+                  <FormControl>
+                    <Input type="email" placeholder="john@example.com" {...field} />
+                  </FormControl>
+                  <FormMessage />
+                </FormItem>
+              )}
+            />
+          </CardContent>
+          <CardFooter className="justify-end">
+            <Button type="submit">Create</Button>
+          </CardFooter>
+        </form>
+      </Form>
+    </Card>
+  );
+}
+```
+
+---
+
+## AI Rules
+
+- **Never implement manual validation state** (`useState` + if blocks). Use `zod` + `react-hook-form`.
+- **Never render error `<span>` or `<p>` manually** — `<FormMessage />` handles this automatically.
+- The `{...field}` spread goes on the **inner input component** (`<Input>`, `<Textarea>`, etc.), not on `<FormControl>`.
+- For `<Select>` fields, use `onValueChange={field.onChange}` and `defaultValue={field.value}` — do not spread `{...field}` on `<Select>`.
+- For `<Checkbox>` fields, use `checked={field.value}` and `onCheckedChange={field.onChange}`.
+- `<FormControl>` must be the **direct parent** of the input component — wrapping it further breaks the ARIA linking.
+
+---
+
+## Related Components
+
+- [`Input`](./input.md), [`Textarea`](./textarea.md), [`Select`](./select.md), [`Checkbox`](./checkbox.md), [`Switch`](./switch.md)
+- [`Dialog`](./dialog.md) — Common container for forms
+- [Form Pattern](../patterns/form.md) — Complete real-world usage example

package/docs/components/formatted-document.md

@@ -1,105 +1,105 @@
-# 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.
+# 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/google-maps-loader.md

@@ -1,44 +1,44 @@
-# GoogleMapsLoader
-
-The utility provider and hook responsible for the lazy-loading and initialization of the Google Maps JavaScript API. It is automatically managed by the `XerticaProvider`.
-
----
-
-## Hook Usage
-
-If you need to check the loading status or access the raw maps library in a custom component:
-
-```tsx
-import { useGoogleMapsLoader } from 'xertica-ui';
-
-function MyCustomMap() {
-  const { isLoaded, loadError } = useGoogleMapsLoader();
-
-  if (loadError) return <div>Error loading maps</div>;
-  if (!isLoaded) return <div>Loading maps...</div>;
-
-  return <div>Maps API is ready!</div>;
-}
-```
-
----
-
-## Integration
-
-The loader is part of the `XerticaProvider` ecosystem. You do not need to wrap your components in it manually unless you are building a sub-application that doesn't use the full library provider.
-
-```tsx
-<XerticaProvider>
-   {/* GoogleMapsLoader is already here */}
-   <Map ... />
-</XerticaProvider>
-```
-
----
-
-## AI Rules
-
-> [!IMPORTANT]
->
-> - **Conditional Rendering**: Always check `isLoaded` before attempting to render any component that requires `window.google`.
-> - **Singleton**: Never instantiate multiple loaders. The `XerticaProvider` ensures only one instance manages the script injection.
+# GoogleMapsLoader
+
+The utility provider and hook responsible for the lazy-loading and initialization of the Google Maps JavaScript API. It is automatically managed by the `XerticaProvider`.
+
+---
+
+## Hook Usage
+
+If you need to check the loading status or access the raw maps library in a custom component:
+
+```tsx
+import { useGoogleMapsLoader } from 'xertica-ui';
+
+function MyCustomMap() {
+  const { isLoaded, loadError } = useGoogleMapsLoader();
+
+  if (loadError) return <div>Error loading maps</div>;
+  if (!isLoaded) return <div>Loading maps...</div>;
+
+  return <div>Maps API is ready!</div>;
+}
+```
+
+---
+
+## Integration
+
+The loader is part of the `XerticaProvider` ecosystem. You do not need to wrap your components in it manually unless you are building a sub-application that doesn't use the full library provider.
+
+```tsx
+<XerticaProvider>
+   {/* GoogleMapsLoader is already here */}
+   <Map ... />
+</XerticaProvider>
+```
+
+---
+
+## AI Rules
+
+> [!IMPORTANT]
+>
+> - **Conditional Rendering**: Always check `isLoaded` before attempting to render any component that requires `window.google`.
+> - **Singleton**: Never instantiate multiple loaders. The `XerticaProvider` ensures only one instance manages the script injection.