xertica-ui 2.1.2 → 2.1.4

package/docs/components/image-with-fallback.md

@@ -0,0 +1,106 @@
+# ImageWithFallback
+
+A drop-in replacement for the native `<img>` element that gracefully handles broken or missing image URLs by displaying a placeholder SVG instead of a broken image icon.
+
+---
+
+## Import
+
+```tsx
+import { ImageWithFallback } from 'xertica-ui';
+// or from the figma subpath (internal)
+import { ImageWithFallback } from 'xertica-ui/ui';
+```
+
+---
+
+## Basic Usage
+
+```tsx
+<ImageWithFallback
+  src="https://example.com/photo.jpg"
+  alt="User profile photo"
+  className="w-32 h-32 rounded-lg object-cover"
+/>
+```
+
+---
+
+## Props
+
+`ImageWithFallback` accepts all standard HTML `<img>` attributes:
+
+| Prop | Type | Description |
+|---|---|---|
+| `src` | `string` | Image URL. If this fails to load, the fallback placeholder is shown. |
+| `alt` | `string` | Accessible alternative text (required for accessibility) |
+| `className` | `string` | CSS classes applied to both the `<img>` and the fallback container |
+| `style` | `CSSProperties` | Inline styles applied to both states |
+| `...rest` | `ImgHTMLAttributes` | All other standard `<img>` attributes (`width`, `height`, `loading`, etc.) |
+
+---
+
+## Behavior
+
+1. **Normal state**: Renders a standard `<img>` element with the provided `src`.
+2. **Error state**: When the image fails to load (`onError` fires), the component switches to a fallback `<div>` containing a centered placeholder SVG (a simple broken-image icon).
+3. **Fallback container**: The fallback `<div>` uses `bg-gray-100` and inherits the same `className` and `style` as the original image, so it maintains the same dimensions and shape.
+4. **Original URL preserved**: The fallback `<img>` stores the original URL in `data-original-url` for debugging purposes.
+
+---
+
+## Usage Examples
+
+### Hero Image with Fallback
+
+```tsx
+<ImageWithFallback
+  src={article.heroImageUrl}
+  alt={article.title}
+  className="w-full h-48 object-cover rounded-t-lg"
+/>
+```
+
+### User Avatar with Fallback
+
+```tsx
+<ImageWithFallback
+  src={user.avatarUrl}
+  alt={`${user.name} avatar`}
+  className="w-10 h-10 rounded-full object-cover"
+/>
+```
+
+> **Note**: For user avatars, prefer the `<Avatar>` component which has built-in fallback support via `<AvatarFallback>` (shows initials). Use `ImageWithFallback` for non-avatar images.
+
+### Lazy Loading
+
+```tsx
+<ImageWithFallback
+  src={product.imageUrl}
+  alt={product.name}
+  loading="lazy"
+  className="w-full aspect-square object-contain"
+/>
+```
+
+---
+
+## Comparison: `ImageWithFallback` vs `Avatar`
+
+| Feature | `ImageWithFallback` | `Avatar` |
+|---|---|---|
+| Fallback type | SVG placeholder icon | Text initials |
+| Use case | General images, hero images, thumbnails | User profile pictures |
+| Shape | Any (controlled by `className`) | Circle (default) |
+| Import | `xertica-ui/ui` | `xertica-ui/ui` |
+
+---
+
+## AI Rules
+
+> [!IMPORTANT]
+> - **Always provide `alt`**: The `alt` attribute is required for accessibility. Never omit it. Use an empty string (`alt=""`) only for purely decorative images.
+> - **Use for external images**: Use `ImageWithFallback` whenever the image URL comes from an external source (API, user upload, CMS) that may be unavailable. For static local assets, a regular `<img>` is acceptable.
+> - **Do not use for avatars**: For user profile pictures, use the `<Avatar>` + `<AvatarFallback>` pattern instead — it shows initials which is more informative than a broken-image icon.
+> - **Maintain dimensions in fallback**: The fallback container inherits `className` and `style`, so always set explicit dimensions (via Tailwind classes like `w-32 h-32` or inline styles) to prevent layout shift when the fallback renders.

package/docs/components/map-layers.md

@@ -0,0 +1,140 @@
+# MapLayers / useMapLayers
+
+A hook for managing Google Maps native overlay layers (traffic, transit, bicycling) on a map instance. Used internally by the `Map` component via its `layers` prop.
+
+---
+
+## Import
+
+```tsx
+import { useMapLayers } from 'xertica-ui/ui';
+// or
+import { useMapLayers, MapLayersConfig } from 'xertica-ui';
+```
+
+---
+
+## `useMapLayers`
+
+A React hook that attaches and detaches Google Maps overlay layers reactively based on a configuration object.
+
+### Signature
+
+```tsx
+function useMapLayers(
+  map: google.maps.Map | null,
+  layers: MapLayersConfig
+): void
+```
+
+### Parameters
+
+| Parameter | Type | Description |
+|---|---|---|
+| `map` | `google.maps.Map \| null` | The Google Maps instance to attach layers to. Pass `null` to skip (layers are not rendered). |
+| `layers` | `MapLayersConfig` | Configuration object specifying which layers to display |
+
+### `MapLayersConfig`
+
+```tsx
+interface MapLayersConfig {
+  traffic?: boolean;   // Real-time traffic overlay
+  transit?: boolean;   // Public transit routes overlay
+  bicycling?: boolean; // Bicycle route overlay
+}
+```
+
+---
+
+## Available Layers
+
+| Layer | Key | Description |
+|---|---|---|
+| Traffic | `traffic` | Real-time traffic conditions with color-coded road segments |
+| Transit | `transit` | Public transit routes (bus, metro, train) |
+| Bicycling | `bicycling` | Dedicated bicycle lanes and paths |
+
+---
+
+## Usage
+
+### Standalone Hook
+
+```tsx
+import { useMapLayers } from 'xertica-ui/ui';
+
+function MapWithLayers() {
+  const [mapInstance, setMapInstance] = useState<google.maps.Map | null>(null);
+  const [showTraffic, setShowTraffic] = useState(false);
+  const [showTransit, setShowTransit] = useState(false);
+
+  useMapLayers(mapInstance, {
+    traffic: showTraffic,
+    transit: showTransit,
+  });
+
+  return (
+    <div>
+      <label>
+        <input
+          type="checkbox"
+          checked={showTraffic}
+          onChange={e => setShowTraffic(e.target.checked)}
+        />
+        Traffic
+      </label>
+      {/* map container */}
+    </div>
+  );
+}
+```
+
+### Via `Map` Component (Recommended)
+
+The `Map` component accepts a `layers` prop that internally uses `useMapLayers`:
+
+```tsx
+import { Map } from 'xertica-ui/ui';
+
+<Map
+  center={{ lat: -23.5505, lng: -46.6333 }}
+  zoom={12}
+  layers={{
+    traffic: true,
+    transit: false,
+    bicycling: false,
+  }}
+/>
+```
+
+---
+
+## Behavior
+
+- **Reactive**: Layers are added or removed automatically when the `layers` config changes.
+- **Cleanup**: Each layer is removed from the map on component unmount (via `useEffect` cleanup).
+- **Null-safe**: If `map` is `null`, the hook does nothing. This is safe to use before the map instance is ready.
+- **Singleton layers**: Each layer type is created once and reused (stored in refs). Toggling a layer on/off does not create new instances.
+
+---
+
+## Prerequisites
+
+The Google Maps JavaScript API must be loaded before using this hook. Use `GoogleMapsLoader` or `XerticaProvider` with a `googleMapsApiKey`:
+
+```tsx
+import { XerticaProvider } from 'xertica-ui/brand';
+
+<XerticaProvider googleMapsApiKey="YOUR_API_KEY">
+  <App />
+</XerticaProvider>
+```
+
+---
+
+## AI Rules
+
+> [!IMPORTANT]
+> - **Use via `Map` component when possible**: The `Map` component's `layers` prop is the recommended way to enable overlays. Use `useMapLayers` directly only when building a custom map integration.
+> - **Requires Google Maps API**: This hook uses `google.maps.TrafficLayer`, `google.maps.TransitLayer`, and `google.maps.BicyclingLayer`. These are only available after the Maps JavaScript API is loaded.
+> - **Pass `null` safely**: If the map instance is not yet available, pass `null` as the first argument. The hook will skip all operations until a valid map is provided.

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

@@ -0,0 +1,163 @@
+# 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.