xertica-ui 2.2.1 → 2.3.0

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

@@ -1,107 +1,107 @@
-# 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.
+# 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/input-otp.md

@@ -1,95 +1,95 @@
-# InputOTP
-
-## Overview
-
-A one-time password / PIN code input that renders a segmented grid of individual character slots. Designed for MFA flows, email verification codes, and any numeric code entry.
-
----
-
-## When to Use
-
-- 2FA / MFA authentication code entry
-- Email or phone verification
-- PIN code inputs
-
----
-
-## Anatomy
-
-```
-<InputOTP maxLength={6}>
-  <InputOTPGroup>
-    <InputOTPSlot index={0} />
-    <InputOTPSlot index={1} />
-    <InputOTPSlot index={2} />
-  </InputOTPGroup>
-  <InputOTPSeparator />
-  <InputOTPGroup>
-    <InputOTPSlot index={3} />
-    <InputOTPSlot index={4} />
-    <InputOTPSlot index={5} />
-  </InputOTPGroup>
-</InputOTP>
-```
-
----
-
-## Props
-
-### InputOTP
-
-| Prop        | Type                      | Required | Description                      |
-| ----------- | ------------------------- | -------- | -------------------------------- |
-| `maxLength` | `number`                  | **Yes**  | Total number of characters       |
-| `value`     | `string`                  | No       | Controlled value                 |
-| `onChange`  | `(value: string) => void` | No       | Change handler                   |
-| `pattern`   | `string`                  | No       | Allowed characters regex pattern |
-
-### InputOTPSlot
-
-| Prop    | Type                   | Required | Default | Description                                   |
-| ------- | ---------------------- | -------- | ------- | --------------------------------------------- |
-| `index` | `number`               | **Yes**  | —       | Position of this slot (0-indexed)             |
-| `size`  | `'sm' \| 'md' \| 'lg'` | No       | `'md'`  | Size variant controlling the slot dimensions. |
-
----
-
-## Examples
-
-### 6-Digit Code
-
-```tsx
-import { InputOTP, InputOTPGroup, InputOTPSeparator, InputOTPSlot } from 'xertica-ui/ui';
-import { useState } from 'react';
-
-const [code, setCode] = useState('');
-
-<div className="space-y-4">
-  <InputOTP maxLength={6} value={code} onChange={setCode}>
-    <InputOTPGroup>
-      <InputOTPSlot index={0} />
-      <InputOTPSlot index={1} />
-      <InputOTPSlot index={2} />
-    </InputOTPGroup>
-    <InputOTPSeparator />
-    <InputOTPGroup>
-      <InputOTPSlot index={3} />
-      <InputOTPSlot index={4} />
-      <InputOTPSlot index={5} />
-    </InputOTPGroup>
-  </InputOTP>
-  <Button onClick={() => verify(code)} disabled={code.length < 6}>
-    Verify
-  </Button>
-</div>;
-```
-
----
-
-## AI Rules
-
-- `maxLength` must match the total number of `InputOTPSlot` elements.
-- **Sizing** — Each `InputOTPSlot` supports `sm`, `md`, and `lg`. Use the same size for all slots in the group.
-- Each `InputOTPSlot` requires its zero-indexed `index` prop.
-- For numeric-only codes, set `pattern="[0-9]*"` on `InputOTP`.
-- Disable the verify button when `value.length < maxLength`.
+# InputOTP
+
+## Overview
+
+A one-time password / PIN code input that renders a segmented grid of individual character slots. Designed for MFA flows, email verification codes, and any numeric code entry.
+
+---
+
+## When to Use
+
+- 2FA / MFA authentication code entry
+- Email or phone verification
+- PIN code inputs
+
+---
+
+## Anatomy
+
+```
+<InputOTP maxLength={6}>
+  <InputOTPGroup>
+    <InputOTPSlot index={0} />
+    <InputOTPSlot index={1} />
+    <InputOTPSlot index={2} />
+  </InputOTPGroup>
+  <InputOTPSeparator />
+  <InputOTPGroup>
+    <InputOTPSlot index={3} />
+    <InputOTPSlot index={4} />
+    <InputOTPSlot index={5} />
+  </InputOTPGroup>
+</InputOTP>
+```
+
+---
+
+## Props
+
+### InputOTP
+
+| Prop        | Type                      | Required | Description                      |
+| ----------- | ------------------------- | -------- | -------------------------------- |
+| `maxLength` | `number`                  | **Yes**  | Total number of characters       |
+| `value`     | `string`                  | No       | Controlled value                 |
+| `onChange`  | `(value: string) => void` | No       | Change handler                   |
+| `pattern`   | `string`                  | No       | Allowed characters regex pattern |
+
+### InputOTPSlot
+
+| Prop    | Type                   | Required | Default | Description                                   |
+| ------- | ---------------------- | -------- | ------- | --------------------------------------------- |
+| `index` | `number`               | **Yes**  | —       | Position of this slot (0-indexed)             |
+| `size`  | `'sm' \| 'md' \| 'lg'` | No       | `'md'`  | Size variant controlling the slot dimensions. |
+
+---
+
+## Examples
+
+### 6-Digit Code
+
+```tsx
+import { InputOTP, InputOTPGroup, InputOTPSeparator, InputOTPSlot } from 'xertica-ui/ui';
+import { useState } from 'react';
+
+const [code, setCode] = useState('');
+
+<div className="space-y-4">
+  <InputOTP maxLength={6} value={code} onChange={setCode}>
+    <InputOTPGroup>
+      <InputOTPSlot index={0} />
+      <InputOTPSlot index={1} />
+      <InputOTPSlot index={2} />
+    </InputOTPGroup>
+    <InputOTPSeparator />
+    <InputOTPGroup>
+      <InputOTPSlot index={3} />
+      <InputOTPSlot index={4} />
+      <InputOTPSlot index={5} />
+    </InputOTPGroup>
+  </InputOTP>
+  <Button onClick={() => verify(code)} disabled={code.length < 6}>
+    Verify
+  </Button>
+</div>;
+```
+
+---
+
+## AI Rules
+
+- `maxLength` must match the total number of `InputOTPSlot` elements.
+- **Sizing** — Each `InputOTPSlot` supports `sm`, `md`, and `lg`. Use the same size for all slots in the group.
+- Each `InputOTPSlot` requires its zero-indexed `index` prop.
+- For numeric-only codes, set `pattern="[0-9]*"` on `InputOTP`.
+- Disable the verify button when `value.length < maxLength`.

package/docs/components/input.md

@@ -1,130 +1,130 @@
-# Input
-
-## Overview
-
-The standard text field component. Use it for all single-line text inputs: names, emails, search queries, codes. Integrates seamlessly with `react-hook-form` via the `{...field}` spread pattern.
-
----
-
-## When to Use
-
-- Single-line text input in forms
-- Search bars (pair with the `relative`/absolute icon pattern)
-- Inline editing fields
-
-## When NOT to Use
-
-- Multi-line text entry — use `<Textarea>` instead.
-- Numeric ranges — use `<Slider>` instead.
-- Date selection — use `<Calendar>` instead.
-- Never use native `<input>` — always use `<Input>` from `xertica-ui`.
-
----
-
-## Props
-
-All native `<input>` HTML attributes are forwarded.
-
-| Prop          | Type                   | Default  | Description                                                       |
-| ------------- | ---------------------- | -------- | ----------------------------------------------------------------- |
-| `type`        | `string`               | `'text'` | Input type: `text`, `email`, `password`, `number`, `search`, etc. |
-| `size`        | `'sm' \| 'md' \| 'lg'` | `'md'`   | Size variant controlling height, padding, and font size.          |
-| `placeholder` | `string`               | —        | Placeholder text                                                  |
-| `disabled`    | `boolean`              | `false`  | Disables interaction                                              |
-| `className`   | `string`               | —        | Additional CSS classes                                            |
-
-### Standardized Sizing Scale
-
-All form input components (`Input`, `SelectTrigger`, `Textarea`, `Search`) share the same sizing scale:
-
-| Size | Height        | Padding     | Font        |
-| ---- | ------------- | ----------- | ----------- |
-| `sm` | `h-8` (32px)  | `px-2 py-1` | `text-sm`   |
-| `md` | `h-10` (40px) | `px-3 py-2` | `text-base` |
-| `lg` | `h-12` (48px) | `px-4 py-3` | `text-base` |
-
-This ensures all form elements align perfectly when placed side-by-side in grid layouts.
-
----
-
-## Examples
-
-### Basic Text Input
-
-```tsx
-import { Input } from 'xertica-ui/ui';
-
-<Input placeholder="Enter your name" />;
-```
-
-### With Label (standalone)
-
-```tsx
-import { Input, Label } from 'xertica-ui/ui';
-
-<div className="grid gap-2">
-  <Label htmlFor="email">Email</Label>
-  <Input id="email" type="email" placeholder="you@example.com" />
-</div>;
-```
-
-### Search Input with Icon
-
-```tsx
-import { Search } from 'lucide-react';
-
-<div className="relative w-full max-w-sm">
-  <Search className="absolute left-2.5 top-2.5 size-4 text-muted-foreground" />
-  <Input placeholder="Search..." className="pl-8" />
-</div>;
-```
-
-### Inside react-hook-form
-
-```tsx
-<FormField
-  control={form.control}
-  name="email"
-  render={({ field }) => (
-    <FormItem>
-      <FormLabel>Email</FormLabel>
-      <FormControl>
-        <Input type="email" placeholder="you@example.com" {...field} />
-      </FormControl>
-      <FormMessage />
-    </FormItem>
-  )}
-/>
-```
-
----
-
-## Accessibility
-
-- Always pair with a `<Label>` component. Use the `htmlFor` prop on the label and `id` on the input to link them.
-- If a visual label is not possible (e.g., search bars), **you must provide an `aria-label`** prop:
-  ```tsx
-  <Input aria-label="Search items" placeholder="Search..." />
-  ```
-- Use the `disabled` prop to indicate non-interactive fields correctly to assistive technologies.
-- Maintain a minimum 1.5:1 contrast for placeholder text (handled by design system defaults).
-
----
-
-## AI Rules
-
-- **Never** use native `<input>` — always use `<Input>` from `xertica-ui`.
-- **Sizing** — The default size is `md` (h-10, 40px). Use the same `size` prop across `Input`, `SelectTrigger`, `Textarea`, and `Search` to ensure consistent alignment.
-- **Accessibility Requirement**: Always provide a `<Label>` or an explicit `aria-label`. Placeholder text is NOT an accessible name.
-- When in a form with `react-hook-form`, **always spread `{...field}`** on the `<Input>` inside `<FormControl>`.
-- Search inputs always use the `relative` + `absolute icon` + `pl-8` pattern — never place the icon outside the input container.
-- Do not add `border`, `rounded`, or `bg-` classes to override the input style — it already inherits from the design system tokens.
-
----
-
-## Related Components
-
-- [`Textarea`](./textarea.md) — Multi-line text input
-- [`Form`](./form.md) — Form integration context
-- [`Label`](./label.md) — Always pair with a Label for accessibility
-- [`Search`](./search.md) — Pre-built search input component
+# Input
+
+## Overview
+
+The standard text field component. Use it for all single-line text inputs: names, emails, search queries, codes. Integrates seamlessly with `react-hook-form` via the `{...field}` spread pattern.
+
+---
+
+## When to Use
+
+- Single-line text input in forms
+- Search bars (pair with the `relative`/absolute icon pattern)
+- Inline editing fields
+
+## When NOT to Use
+
+- Multi-line text entry — use `<Textarea>` instead.
+- Numeric ranges — use `<Slider>` instead.
+- Date selection — use `<Calendar>` instead.
+- Never use native `<input>` — always use `<Input>` from `xertica-ui`.
+
+---
+
+## Props
+
+All native `<input>` HTML attributes are forwarded.
+
+| Prop          | Type                   | Default  | Description                                                       |
+| ------------- | ---------------------- | -------- | ----------------------------------------------------------------- |
+| `type`        | `string`               | `'text'` | Input type: `text`, `email`, `password`, `number`, `search`, etc. |
+| `size`        | `'sm' \| 'md' \| 'lg'` | `'md'`   | Size variant controlling height, padding, and font size.          |
+| `placeholder` | `string`               | —        | Placeholder text                                                  |
+| `disabled`    | `boolean`              | `false`  | Disables interaction                                              |
+| `className`   | `string`               | —        | Additional CSS classes                                            |
+
+### Standardized Sizing Scale
+
+All form input components (`Input`, `SelectTrigger`, `Textarea`, `Search`) share the same sizing scale:
+
+| Size | Height        | Padding     | Font        |
+| ---- | ------------- | ----------- | ----------- |
+| `sm` | `h-8` (32px)  | `px-2 py-1` | `text-sm`   |
+| `md` | `h-10` (40px) | `px-3 py-2` | `text-base` |
+| `lg` | `h-12` (48px) | `px-4 py-3` | `text-base` |
+
+This ensures all form elements align perfectly when placed side-by-side in grid layouts.
+
+---
+
+## Examples
+
+### Basic Text Input
+
+```tsx
+import { Input } from 'xertica-ui/ui';
+
+<Input placeholder="Enter your name" />;
+```
+
+### With Label (standalone)
+
+```tsx
+import { Input, Label } from 'xertica-ui/ui';
+
+<div className="grid gap-2">
+  <Label htmlFor="email">Email</Label>
+  <Input id="email" type="email" placeholder="you@example.com" />
+</div>;
+```
+
+### Search Input with Icon
+
+```tsx
+import { Search } from 'lucide-react';
+
+<div className="relative w-full max-w-sm">
+  <Search className="absolute left-2.5 top-2.5 size-4 text-muted-foreground" />
+  <Input placeholder="Search..." className="pl-8" />
+</div>;
+```
+
+### Inside react-hook-form
+
+```tsx
+<FormField
+  control={form.control}
+  name="email"
+  render={({ field }) => (
+    <FormItem>
+      <FormLabel>Email</FormLabel>
+      <FormControl>
+        <Input type="email" placeholder="you@example.com" {...field} />
+      </FormControl>
+      <FormMessage />
+    </FormItem>
+  )}
+/>
+```
+
+---
+
+## Accessibility
+
+- Always pair with a `<Label>` component. Use the `htmlFor` prop on the label and `id` on the input to link them.
+- If a visual label is not possible (e.g., search bars), **you must provide an `aria-label`** prop:
+  ```tsx
+  <Input aria-label="Search items" placeholder="Search..." />
+  ```
+- Use the `disabled` prop to indicate non-interactive fields correctly to assistive technologies.
+- Maintain a minimum 1.5:1 contrast for placeholder text (handled by design system defaults).
+
+---
+
+## AI Rules
+
+- **Never** use native `<input>` — always use `<Input>` from `xertica-ui`.
+- **Sizing** — The default size is `md` (h-10, 40px). Use the same `size` prop across `Input`, `SelectTrigger`, `Textarea`, and `Search` to ensure consistent alignment.
+- **Accessibility Requirement**: Always provide a `<Label>` or an explicit `aria-label`. Placeholder text is NOT an accessible name.
+- When in a form with `react-hook-form`, **always spread `{...field}`** on the `<Input>` inside `<FormControl>`.
+- Search inputs always use the `relative` + `absolute icon` + `pl-8` pattern — never place the icon outside the input container.
+- Do not add `border`, `rounded`, or `bg-` classes to override the input style — it already inherits from the design system tokens.
+
+---
+
+## Related Components
+
+- [`Textarea`](./textarea.md) — Multi-line text input
+- [`Form`](./form.md) — Form integration context
+- [`Label`](./label.md) — Always pair with a Label for accessibility
+- [`Search`](./search.md) — Pre-built search input component