xertica-ui 2.2.1 → 2.4.0

package/docs/components/map-layers.md

@@ -1,138 +1,138 @@
-# 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.
+# 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/map.md

@@ -1,84 +1,84 @@
-# Map
-
-## Overview
-
-`Map` renders an interactive Google Map with advanced markers, optional rich info windows, circles, polygons, and native overlay layers. It uses the built-in Xertica Google Maps loader and renders a safe configuration state when no API key is available.
-
----
-
-## Import
-
-```tsx
-import {
-  Map,
-  GoogleMapsLoaderProvider,
-  useGoogleMapsLoader,
-  useMapLayers,
-  GOOGLE_MAPS_ID,
-  GOOGLE_MAPS_LIBRARIES,
-  type MapLayersConfig,
-} from 'xertica-ui/ui';
-```
-
----
-
-## Prerequisites
-
-- Import `xertica-ui/style.css` once at the app root.
-- Provide a Google Maps JavaScript API key through `apiKey`, `VITE_GOOGLE_MAPS_API_KEY`, storage, or `<XerticaProvider googleMapsApiKey="...">`.
-- If no key is configured, the component renders a non-crashing setup prompt.
-
----
-
-## Props
-
-| Prop        | Type                             | Default   | Description                                               |
-| ----------- | -------------------------------- | --------- | --------------------------------------------------------- |
-| `center`    | `{ lat: number; lng: number }`   | Sao Paulo | Initial map center coordinates.                           |
-| `zoom`      | `number`                         | `12`      | Initial zoom level.                                       |
-| `markers`   | `MapMarker[]`                    | `[]`      | Markers to display.                                       |
-| `circle`    | `object`                         | -         | Optional circle overlay.                                  |
-| `polygon`   | `object`                         | -         | Optional polygon overlay.                                 |
-| `layers`    | `MapLayersConfig`                | `{}`      | Native layer toggles for traffic, transit, and bicycling. |
-| `height`    | `string`                         | `"400px"` | Container height.                                         |
-| `apiKey`    | `string`                         | -         | Per-component Google Maps API key override.               |
-| `onMapLoad` | `(map: google.maps.Map) => void` | -         | Receives the underlying map instance.                     |
-
----
-
-## Public Utilities
-
-`useMapLayers(map, layers)` is public for advanced integrations that already own a `google.maps.Map` instance.
-
-`GOOGLE_MAPS_ID` and `GOOGLE_MAPS_LIBRARIES` are public constants for integrations that need to inspect or align with the built-in loader.
-
----
-
-## Example
-
-```tsx
-import { Map } from 'xertica-ui/ui';
-
-<Map
-  center={{ lat: -23.5505, lng: -46.6333 }}
-  zoom={12}
-  height="420px"
-  markers={[
-    {
-      position: { lat: -23.5505, lng: -46.6333 },
-      title: 'Xertica',
-      info: 'Main office',
-    },
-  ]}
-  layers={{ traffic: true }}
-/>;
-```
-
----
-
-## AI Rules
-
-- Always set visible height through `height` or layout constraints.
-- Do not install another Google Maps script loader; use `GoogleMapsLoaderProvider` or `XerticaProvider`.
-- Use `{ lat, lng }` coordinates, never `{ latitude, longitude }`.
-- For standalone usage, pass `apiKey` directly or rely on `VITE_GOOGLE_MAPS_API_KEY`.
+# Map
+
+## Overview
+
+`Map` renders an interactive Google Map with advanced markers, optional rich info windows, circles, polygons, and native overlay layers. It uses the built-in Xertica Google Maps loader and renders a safe configuration state when no API key is available.
+
+---
+
+## Import
+
+```tsx
+import {
+  Map,
+  GoogleMapsLoaderProvider,
+  useGoogleMapsLoader,
+  useMapLayers,
+  GOOGLE_MAPS_ID,
+  GOOGLE_MAPS_LIBRARIES,
+  type MapLayersConfig,
+} from 'xertica-ui/ui';
+```
+
+---
+
+## Prerequisites
+
+- Import `xertica-ui/style.css` once at the app root.
+- Provide a Google Maps JavaScript API key through `apiKey`, `VITE_GOOGLE_MAPS_API_KEY`, storage, or `<XerticaProvider googleMapsApiKey="...">`.
+- If no key is configured, the component renders a non-crashing setup prompt.
+
+---
+
+## Props
+
+| Prop        | Type                             | Default   | Description                                               |
+| ----------- | -------------------------------- | --------- | --------------------------------------------------------- |
+| `center`    | `{ lat: number; lng: number }`   | Sao Paulo | Initial map center coordinates.                           |
+| `zoom`      | `number`                         | `12`      | Initial zoom level.                                       |
+| `markers`   | `MapMarker[]`                    | `[]`      | Markers to display.                                       |
+| `circle`    | `object`                         | -         | Optional circle overlay.                                  |
+| `polygon`   | `object`                         | -         | Optional polygon overlay.                                 |
+| `layers`    | `MapLayersConfig`                | `{}`      | Native layer toggles for traffic, transit, and bicycling. |
+| `height`    | `string`                         | `"400px"` | Container height.                                         |
+| `apiKey`    | `string`                         | -         | Per-component Google Maps API key override.               |
+| `onMapLoad` | `(map: google.maps.Map) => void` | -         | Receives the underlying map instance.                     |
+
+---
+
+## Public Utilities
+
+`useMapLayers(map, layers)` is public for advanced integrations that already own a `google.maps.Map` instance.
+
+`GOOGLE_MAPS_ID` and `GOOGLE_MAPS_LIBRARIES` are public constants for integrations that need to inspect or align with the built-in loader.
+
+---
+
+## Example
+
+```tsx
+import { Map } from 'xertica-ui/ui';
+
+<Map
+  center={{ lat: -23.5505, lng: -46.6333 }}
+  zoom={12}
+  height="420px"
+  markers={[
+    {
+      position: { lat: -23.5505, lng: -46.6333 },
+      title: 'Xertica',
+      info: 'Main office',
+    },
+  ]}
+  layers={{ traffic: true }}
+/>;
+```
+
+---
+
+## AI Rules
+
+- Always set visible height through `height` or layout constraints.
+- Do not install another Google Maps script loader; use `GoogleMapsLoaderProvider` or `XerticaProvider`.
+- Use `{ lat, lng }` coordinates, never `{ latitude, longitude }`.
+- For standalone usage, pass `apiKey` directly or rely on `VITE_GOOGLE_MAPS_API_KEY`.

package/docs/components/markdown-message.md

@@ -1,47 +1,47 @@
-# MarkdownMessage
-
-The primary renderer for AI-generated text content within the Xertica Assistant. It converts raw Markdown into themed React components with support for syntax highlighting, lists, and tables.
-
----
-
-## Import
-
-```tsx
-import { MarkdownMessage } from 'xertica-ui/assistant';
-```
-
----
-
-## Usage
-
-```tsx
-<MarkdownMessage content="# Hello\nThis is **bold** text and [a link](https://xertica.com)." />
-```
-
----
-
-## Props
-
-| Prop        | Type     | Default      | Description                             |
-| ----------- | -------- | ------------ | --------------------------------------- |
-| `content`   | `string` | _(required)_ | The raw markdown string to render.      |
-| `className` | `string` | —            | Optional CSS classes for the container. |
-
----
-
-## Features
-
-- **Syntax Highlighting**: Automatically uses `CodeBlock` for triple-backtick code segments.
-- **Themed Typography**: Maps Markdown headers (`h1`-`h4`), blockquotes, and lists to the Xertica UI design system tokens.
-- **GFM Tables**: Renders GitHub Flavored Markdown tables (`| col | col |`) as styled `<table>` elements using design system tokens (`border-border`, `hover:bg-muted/50`, `rounded-[var(--radius)]`). Wraps in `overflow-x-auto` for responsive behavior. Cell content supports inline formatting (bold, italic, code).
-- **Link Safety**: Automatically adds `target="_blank"` and `rel="noopener noreferrer"` to external links.
-- **Scroll Optimized**: Designed to be used inside the messaging list of the `XerticaAssistant`.
-
----
-
-## AI Rules
-
-> [!IMPORTANT]
->
-> - **Streaming Support**: This component can be updated incrementally as a stream of text arrives from an LLM.
-> - **Escape HTML**: Ensure the content passed here is sanitized or comes from a trusted AI source, as it renders HTML-like structures via markdown.
+# MarkdownMessage
+
+The primary renderer for AI-generated text content within the Xertica Assistant. It converts raw Markdown into themed React components with support for syntax highlighting, lists, and tables.
+
+---
+
+## Import
+
+```tsx
+import { MarkdownMessage } from 'xertica-ui/assistant';
+```
+
+---
+
+## Usage
+
+```tsx
+<MarkdownMessage content="# Hello\nThis is **bold** text and [a link](https://xertica.com)." />
+```
+
+---
+
+## Props
+
+| Prop        | Type     | Default      | Description                             |
+| ----------- | -------- | ------------ | --------------------------------------- |
+| `content`   | `string` | _(required)_ | The raw markdown string to render.      |
+| `className` | `string` | —            | Optional CSS classes for the container. |
+
+---
+
+## Features
+
+- **Syntax Highlighting**: Automatically uses `CodeBlock` for triple-backtick code segments.
+- **Themed Typography**: Maps Markdown headers (`h1`-`h4`), blockquotes, and lists to the Xertica UI design system tokens.
+- **GFM Tables**: Renders GitHub Flavored Markdown tables (`| col | col |`) as styled `<table>` elements using design system tokens (`border-border`, `hover:bg-muted/50`, `rounded-[var(--radius)]`). Wraps in `overflow-x-auto` for responsive behavior. Cell content supports inline formatting (bold, italic, code).
+- **Link Safety**: Automatically adds `target="_blank"` and `rel="noopener noreferrer"` to external links.
+- **Scroll Optimized**: Designed to be used inside the messaging list of the `XerticaAssistant`.
+
+---
+
+## AI Rules
+
+> [!IMPORTANT]
+>
+> - **Streaming Support**: This component can be updated incrementally as a stream of text arrives from an LLM.
+> - **Escape HTML**: Ensure the content passed here is sanitized or comes from a trusted AI source, as it renders HTML-like structures via markdown.