xertica-ui 2.2.1 → 2.4.0

package/docs/components/route-map.md

@@ -1,124 +1,124 @@
-# RouteMap
-
-## Overview
-
-A specialized Google Maps component that calculates and renders a route between an origin and destination point, with support for intermediate waypoints and multiple travel modes. The route is drawn on the map using the Google Directions Service, and optionally returns the calculated distance and duration.
-
-Use `<Map>` for general-purpose map rendering. Use `<RouteMap>` specifically when you need to display a navigable route.
-
----
-
-## When to Use
-
-- Displaying the route between two locations (delivery tracking, field service, logistics)
-- Showing estimated travel time and distance
-- Multi-stop itinerary visualization
-
-## When NOT to Use
-
-- General-purpose map without route — use `<Map>` instead.
-- Static location marker display — use `<Map markers={...}>` instead.
-
----
-
-## Prerequisites
-
-- A Google Maps JavaScript API key with the **Directions API** enabled.
-- The key must be provided to `<XerticaProvider googleMapsApiKey="YOUR_KEY">`, OR passed directly as the `apiKey` prop.
-
----
-
-## Props
-
-| Prop                | Type                                                 | Default     | Required | Description                                                         |
-| ------------------- | ---------------------------------------------------- | ----------- | -------- | ------------------------------------------------------------------- |
-| `origin`            | `{ lat: number; lng: number }`                       | —           | **Yes**  | Route start point                                                   |
-| `destination`       | `{ lat: number; lng: number }`                       | —           | **Yes**  | Route end point                                                     |
-| `waypoints`         | `{ lat: number; lng: number }[]`                     | `[]`        | No       | Intermediate stops                                                  |
-| `travelMode`        | `'DRIVING' \| 'WALKING' \| 'BICYCLING' \| 'TRANSIT'` | `'DRIVING'` | No       | Mode of transport                                                   |
-| `height`            | `string`                                             | `'450px'`   | No       | CSS height of the map container                                     |
-| `mapId`             | `string`                                             | —           | No       | Google Maps Map ID for custom styling                               |
-| `apiKey`            | `string`                                             | —           | No       | Overrides provider API key                                          |
-| `onRouteCalculated` | `(distance: string, duration: string) => void`       | —           | No       | Called with formatted distance and duration after route is computed |
-| `disableDefaultUI`  | `boolean`                                            | `false`     | No       | Hides all default map UI controls                                   |
-| `zoomControl`       | `boolean`                                            | `true`      | No       | Shows/hides zoom control                                            |
-| `streetViewControl` | `boolean`                                            | `false`     | No       | Shows/hides Street View control                                     |
-| `mapTypeControl`    | `boolean`                                            | `false`     | No       | Shows/hides map type switcher                                       |
-| `fullscreenControl` | `boolean`                                            | `true`      | No       | Shows/hides fullscreen button                                       |
-| `className`         | `string`                                             | —           | No       | Additional CSS classes for the wrapper div                          |
-
----
-
-## Examples
-
-### Basic Route
-
-```tsx
-import { RouteMap } from 'xertica-ui';
-
-<RouteMap
-  origin={{ lat: -12.971, lng: -38.501 }}
-  destination={{ lat: -13.025, lng: -38.478 }}
-  height="400px"
-/>;
-```
-
-### With Waypoints and Distance Callback
-
-```tsx
-const [routeInfo, setRouteInfo] = useState<{ distance: string; duration: string }>();
-
-<RouteMap
-  origin={{ lat: -12.971, lng: -38.501 }}
-  destination={{ lat: -13.025, lng: -38.478 }}
-  waypoints={[{ lat: -12.99, lng: -38.49 }]}
-  travelMode="DRIVING"
-  height="500px"
-  onRouteCalculated={(distance, duration) => setRouteInfo({ distance, duration })}
-/>;
-
-{
-  routeInfo && (
-    <p className="text-sm text-muted-foreground mt-2">
-      {routeInfo.distance} · {routeInfo.duration}
-    </p>
-  );
-}
-```
-
-### Walking Mode
-
-```tsx
-<RouteMap
-  origin={{ lat: -12.971, lng: -38.501 }}
-  destination={{ lat: -12.98, lng: -38.51 }}
-  travelMode="WALKING"
-  height="300px"
-/>
-```
-
----
-
-## Return Values from `onRouteCalculated`
-
-| Parameter  | Format                   | Example                    |
-| ---------- | ------------------------ | -------------------------- |
-| `distance` | `"X.X km"`               | `"12.4 km"`                |
-| `duration` | `"Xh Ymin"` or `"Y min"` | `"1h 23min"` or `"45 min"` |
-
----
-
-## AI Rules
-
-- **Always** set an explicit `height` — without it the map renders with 0 height.
-- `origin` and `destination` use `{ lat, lng }` format — **not** `{ latitude, longitude }`.
-- The API key requires the **Directions API** enabled, in addition to the Maps JavaScript API. Plain Maps API keys will fail route calculation.
-- `onRouteCalculated` receives pre-formatted strings (`"12.4 km"`, `"23 min"`) — not raw numeric values.
-- If `waypoints` is empty, simply omit the prop — do not pass an empty array explicitly.
-
----
-
-## Related Components
-
-- [`Map`](./map.md) — General-purpose map without route
-- [Maps Pattern](../patterns/analytics.md) — Location-based analytics usage
+# RouteMap
+
+## Overview
+
+A specialized Google Maps component that calculates and renders a route between an origin and destination point, with support for intermediate waypoints and multiple travel modes. The route is drawn on the map using the Google Directions Service, and optionally returns the calculated distance and duration.
+
+Use `<Map>` for general-purpose map rendering. Use `<RouteMap>` specifically when you need to display a navigable route.
+
+---
+
+## When to Use
+
+- Displaying the route between two locations (delivery tracking, field service, logistics)
+- Showing estimated travel time and distance
+- Multi-stop itinerary visualization
+
+## When NOT to Use
+
+- General-purpose map without route — use `<Map>` instead.
+- Static location marker display — use `<Map markers={...}>` instead.
+
+---
+
+## Prerequisites
+
+- A Google Maps JavaScript API key with the **Directions API** enabled.
+- The key must be provided to `<XerticaProvider googleMapsApiKey="YOUR_KEY">`, OR passed directly as the `apiKey` prop.
+
+---
+
+## Props
+
+| Prop                | Type                                                 | Default     | Required | Description                                                         |
+| ------------------- | ---------------------------------------------------- | ----------- | -------- | ------------------------------------------------------------------- |
+| `origin`            | `{ lat: number; lng: number }`                       | —           | **Yes**  | Route start point                                                   |
+| `destination`       | `{ lat: number; lng: number }`                       | —           | **Yes**  | Route end point                                                     |
+| `waypoints`         | `{ lat: number; lng: number }[]`                     | `[]`        | No       | Intermediate stops                                                  |
+| `travelMode`        | `'DRIVING' \| 'WALKING' \| 'BICYCLING' \| 'TRANSIT'` | `'DRIVING'` | No       | Mode of transport                                                   |
+| `height`            | `string`                                             | `'450px'`   | No       | CSS height of the map container                                     |
+| `mapId`             | `string`                                             | —           | No       | Google Maps Map ID for custom styling                               |
+| `apiKey`            | `string`                                             | —           | No       | Overrides provider API key                                          |
+| `onRouteCalculated` | `(distance: string, duration: string) => void`       | —           | No       | Called with formatted distance and duration after route is computed |
+| `disableDefaultUI`  | `boolean`                                            | `false`     | No       | Hides all default map UI controls                                   |
+| `zoomControl`       | `boolean`                                            | `true`      | No       | Shows/hides zoom control                                            |
+| `streetViewControl` | `boolean`                                            | `false`     | No       | Shows/hides Street View control                                     |
+| `mapTypeControl`    | `boolean`                                            | `false`     | No       | Shows/hides map type switcher                                       |
+| `fullscreenControl` | `boolean`                                            | `true`      | No       | Shows/hides fullscreen button                                       |
+| `className`         | `string`                                             | —           | No       | Additional CSS classes for the wrapper div                          |
+
+---
+
+## Examples
+
+### Basic Route
+
+```tsx
+import { RouteMap } from 'xertica-ui';
+
+<RouteMap
+  origin={{ lat: -12.971, lng: -38.501 }}
+  destination={{ lat: -13.025, lng: -38.478 }}
+  height="400px"
+/>;
+```
+
+### With Waypoints and Distance Callback
+
+```tsx
+const [routeInfo, setRouteInfo] = useState<{ distance: string; duration: string }>();
+
+<RouteMap
+  origin={{ lat: -12.971, lng: -38.501 }}
+  destination={{ lat: -13.025, lng: -38.478 }}
+  waypoints={[{ lat: -12.99, lng: -38.49 }]}
+  travelMode="DRIVING"
+  height="500px"
+  onRouteCalculated={(distance, duration) => setRouteInfo({ distance, duration })}
+/>;
+
+{
+  routeInfo && (
+    <p className="text-sm text-muted-foreground mt-2">
+      {routeInfo.distance} · {routeInfo.duration}
+    </p>
+  );
+}
+```
+
+### Walking Mode
+
+```tsx
+<RouteMap
+  origin={{ lat: -12.971, lng: -38.501 }}
+  destination={{ lat: -12.98, lng: -38.51 }}
+  travelMode="WALKING"
+  height="300px"
+/>
+```
+
+---
+
+## Return Values from `onRouteCalculated`
+
+| Parameter  | Format                   | Example                    |
+| ---------- | ------------------------ | -------------------------- |
+| `distance` | `"X.X km"`               | `"12.4 km"`                |
+| `duration` | `"Xh Ymin"` or `"Y min"` | `"1h 23min"` or `"45 min"` |
+
+---
+
+## AI Rules
+
+- **Always** set an explicit `height` — without it the map renders with 0 height.
+- `origin` and `destination` use `{ lat, lng }` format — **not** `{ latitude, longitude }`.
+- The API key requires the **Directions API** enabled, in addition to the Maps JavaScript API. Plain Maps API keys will fail route calculation.
+- `onRouteCalculated` receives pre-formatted strings (`"12.4 km"`, `"23 min"`) — not raw numeric values.
+- If `waypoints` is empty, simply omit the prop — do not pass an empty array explicitly.
+
+---
+
+## Related Components
+
+- [`Map`](./map.md) — General-purpose map without route
+- [Maps Pattern](../patterns/analytics.md) — Location-based analytics usage

package/docs/components/scroll-area.md

@@ -1,58 +1,58 @@
-# Scroll Area
-
-## Overview
-
-A cross-browser, themeable scrollable container with custom scrollbar styling. Use instead of native `overflow-y-auto` when the scrollbar needs to match the application's design system (instead of the OS default scrollbar).
-
----
-
-## When to Use
-
-- Fixed-height panels that need vertical scrolling
-- Sidebar content areas, chat message lists, log viewers
-- Any scrollable container where the native scrollbar looks out of place
-
----
-
-## Props
-
-| Prop        | Type                                        | Default   | Description                           |
-| ----------- | ------------------------------------------- | --------- | ------------------------------------- |
-| `className` | `string`                                    | —         | Set height and width of the container |
-| `type`      | `'auto' \| 'always' \| 'scroll' \| 'hover'` | `'hover'` | When the scrollbar is visible         |
-
----
-
-## Examples
-
-### Fixed-Height List
-
-```tsx
-import { ScrollArea } from 'xertica-ui/ui';
-
-<ScrollArea className="h-[300px] w-full rounded-md border p-4">
-  {items.map(item => (
-    <div key={item.id} className="py-2 text-sm">
-      {item.name}
-    </div>
-  ))}
-</ScrollArea>;
-```
-
-### Sidebar Scroll Area
-
-```tsx
-<ScrollArea className="flex-1 px-2">
-  {routes.map(route => (
-    <NavItem key={route.path} route={route} />
-  ))}
-</ScrollArea>
-```
-
----
-
-## AI Rules
-
-- Always set an explicit height via `className="h-[300px]"` or `h-full` — `ScrollArea` requires a bounded height to scroll.
-- Use inside the Sidebar for the scrollable navigation area.
-- Do not use for full-page scrolling — the entire page scroll is managed by the CSS `overflow-y-auto` on the main content container.
+# Scroll Area
+
+## Overview
+
+A cross-browser, themeable scrollable container with custom scrollbar styling. Use instead of native `overflow-y-auto` when the scrollbar needs to match the application's design system (instead of the OS default scrollbar).
+
+---
+
+## When to Use
+
+- Fixed-height panels that need vertical scrolling
+- Sidebar content areas, chat message lists, log viewers
+- Any scrollable container where the native scrollbar looks out of place
+
+---
+
+## Props
+
+| Prop        | Type                                        | Default   | Description                           |
+| ----------- | ------------------------------------------- | --------- | ------------------------------------- |
+| `className` | `string`                                    | —         | Set height and width of the container |
+| `type`      | `'auto' \| 'always' \| 'scroll' \| 'hover'` | `'hover'` | When the scrollbar is visible         |
+
+---
+
+## Examples
+
+### Fixed-Height List
+
+```tsx
+import { ScrollArea } from 'xertica-ui/ui';
+
+<ScrollArea className="h-[300px] w-full rounded-md border p-4">
+  {items.map(item => (
+    <div key={item.id} className="py-2 text-sm">
+      {item.name}
+    </div>
+  ))}
+</ScrollArea>;
+```
+
+### Sidebar Scroll Area
+
+```tsx
+<ScrollArea className="flex-1 px-2">
+  {routes.map(route => (
+    <NavItem key={route.path} route={route} />
+  ))}
+</ScrollArea>
+```
+
+---
+
+## AI Rules
+
+- Always set an explicit height via `className="h-[300px]"` or `h-full` — `ScrollArea` requires a bounded height to scroll.
+- Use inside the Sidebar for the scrollable navigation area.
+- Do not use for full-page scrolling — the entire page scroll is managed by the CSS `overflow-y-auto` on the main content container.

package/docs/components/search.md

@@ -1,87 +1,87 @@
-# Search
-
-## Overview
-
-A pre-built search input with a built-in search icon and clear button. A convenience component built on top of `<Input>` that handles the common search field pattern with a consistent size scale.
-
----
-
-## When to Use
-
-- Search fields in headers, sidebar filters, and CRUD filter rows
-- When a plain `<Input>` + manual icon positioning is redundant
-
----
-
-## Props
-
-| Prop                 | Type                                         | Default | Required | Description                                                         |
-| -------------------- | -------------------------------------------- | ------- | -------- | ------------------------------------------------------------------- |
-| `value`              | `string`                                     | —       | No       | Controlled value                                                    |
-| `onChange`           | `React.ChangeEventHandler<HTMLInputElement>` | —       | No       | Native change handler                                               |
-| `onSearch`           | `(value: string) => void`                    | —       | No       | Called with the string value on every keystroke                     |
-| `onClear`            | `() => void`                                 | —       | No       | Called when the × button is clicked or Escape is pressed            |
-| `placeholder`        | `string`                                     | —       | No       | Input placeholder text                                              |
-| `size`               | `'sm' \| 'md' \| 'lg'`                       | `'md'`  | No       | Height preset — matches the Input/Select size scale (h-8/h-10/h-12) |
-| `containerClassName` | `string`                                     | —       | No       | CSS classes for the outer wrapper div                               |
-| `className`          | `string`                                     | —       | No       | CSS classes for the input element                                   |
-
----
-
-## Examples
-
-### Controlled Search
-
-```tsx
-import { Search } from 'xertica-ui/ui';
-import { useState } from 'react';
-
-const [query, setQuery] = useState('');
-
-<Search
-  value={query}
-  onSearch={setQuery}
-  onClear={() => setQuery('')}
-  placeholder="Search members..."
-  className="w-full max-w-sm"
-/>;
-```
-
-### Size Variants
-
-```tsx
-<Search size="sm" placeholder="Small search" />
-<Search size="md" placeholder="Default search" />
-<Search size="lg" placeholder="Large search" />
-```
-
----
-
-## Alternative: Manual Composition
-
-When `Search` component is not available, use the standard Input pattern:
-
-```tsx
-import { Input } from 'xertica-ui/ui';
-import { Search as SearchIcon } from 'lucide-react';
-
-<div className="relative w-full max-w-sm">
-  <SearchIcon className="absolute left-2.5 top-2.5 size-4 text-muted-foreground" />
-  <Input
-    value={query}
-    onChange={e => setQuery(e.target.value)}
-    placeholder="Search..."
-    className="pl-8"
-  />
-</div>;
-```
-
----
-
-## AI Rules
-
-- **Sizing** — Search defaults to `md` (h-10, 40px), matching Input, SelectTrigger, and Textarea. Use the same `size` across all form elements for consistent alignment.
-- Use `onSearch` for simple string callbacks; use `onChange` when you need the full event object.
-- The clear button (×) only appears when the input has content — it is hidden when empty.
-- Pressing `Escape` also triggers `onClear`.
-- When using the manual composition pattern (Input + icon), always use `relative` on the wrapper + `absolute` on the icon + `pl-8` on the Input.
+# Search
+
+## Overview
+
+A pre-built search input with a built-in search icon and clear button. A convenience component built on top of `<Input>` that handles the common search field pattern with a consistent size scale.
+
+---
+
+## When to Use
+
+- Search fields in headers, sidebar filters, and CRUD filter rows
+- When a plain `<Input>` + manual icon positioning is redundant
+
+---
+
+## Props
+
+| Prop                 | Type                                         | Default | Required | Description                                                         |
+| -------------------- | -------------------------------------------- | ------- | -------- | ------------------------------------------------------------------- |
+| `value`              | `string`                                     | —       | No       | Controlled value                                                    |
+| `onChange`           | `React.ChangeEventHandler<HTMLInputElement>` | —       | No       | Native change handler                                               |
+| `onSearch`           | `(value: string) => void`                    | —       | No       | Called with the string value on every keystroke                     |
+| `onClear`            | `() => void`                                 | —       | No       | Called when the × button is clicked or Escape is pressed            |
+| `placeholder`        | `string`                                     | —       | No       | Input placeholder text                                              |
+| `size`               | `'sm' \| 'md' \| 'lg'`                       | `'md'`  | No       | Height preset — matches the Input/Select size scale (h-8/h-10/h-12) |
+| `containerClassName` | `string`                                     | —       | No       | CSS classes for the outer wrapper div                               |
+| `className`          | `string`                                     | —       | No       | CSS classes for the input element                                   |
+
+---
+
+## Examples
+
+### Controlled Search
+
+```tsx
+import { Search } from 'xertica-ui/ui';
+import { useState } from 'react';
+
+const [query, setQuery] = useState('');
+
+<Search
+  value={query}
+  onSearch={setQuery}
+  onClear={() => setQuery('')}
+  placeholder="Search members..."
+  className="w-full max-w-sm"
+/>;
+```
+
+### Size Variants
+
+```tsx
+<Search size="sm" placeholder="Small search" />
+<Search size="md" placeholder="Default search" />
+<Search size="lg" placeholder="Large search" />
+```
+
+---
+
+## Alternative: Manual Composition
+
+When `Search` component is not available, use the standard Input pattern:
+
+```tsx
+import { Input } from 'xertica-ui/ui';
+import { Search as SearchIcon } from 'lucide-react';
+
+<div className="relative w-full max-w-sm">
+  <SearchIcon className="absolute left-2.5 top-2.5 size-4 text-muted-foreground" />
+  <Input
+    value={query}
+    onChange={e => setQuery(e.target.value)}
+    placeholder="Search..."
+    className="pl-8"
+  />
+</div>;
+```
+
+---
+
+## AI Rules
+
+- **Sizing** — Search defaults to `md` (h-10, 40px), matching Input, SelectTrigger, and Textarea. Use the same `size` across all form elements for consistent alignment.
+- Use `onSearch` for simple string callbacks; use `onChange` when you need the full event object.
+- The clear button (×) only appears when the input has content — it is hidden when empty.
+- Pressing `Escape` also triggers `onClear`.
+- When using the manual composition pattern (Input + icon), always use `relative` on the wrapper + `absolute` on the icon + `pl-8` on the Input.