xertica-ui 2.2.1 → 2.4.0

package/docs/components/hover-card.md

@@ -1,86 +1,86 @@
-# HoverCard
-
-## Overview
-
-A floating content panel that appears when hovering over a trigger element — designed for previewing additional information without navigating away. Unlike `Tooltip` (short text hints), `HoverCard` can contain rich content: user profiles, link previews, image thumbnails.
-
----
-
-## When to Use
-
-- Author profile previews in comment threads or author lists
-- Link previews (URL cards)
-- Contextual information about a referenced entity
-
-## When NOT to Use
-
-- Short labels or hints — use `<Tooltip>` instead.
-- Interactive controls — use `<Popover>` instead.
-
----
-
-## Anatomy
-
-```
-<HoverCard>
-  <HoverCardTrigger asChild>
-    <Button variant="link">@username</Button>
-  </HoverCardTrigger>
-  <HoverCardContent>
-    {/* Rich preview content */}
-  </HoverCardContent>
-</HoverCard>
-```
-
----
-
-## Examples
-
-### User Profile Preview
-
-```tsx
-import {
-  HoverCard,
-  HoverCardContent,
-  HoverCardTrigger,
-  Avatar,
-  AvatarFallback,
-  AvatarImage,
-  Button,
-} from 'xertica-ui/ui';
-
-<HoverCard>
-  <HoverCardTrigger asChild>
-    <Button variant="link" className="p-0 h-auto">
-      @ariel
-    </Button>
-  </HoverCardTrigger>
-  <HoverCardContent className="w-80">
-    <div className="flex gap-4">
-      <Avatar>
-        <AvatarImage src="https://github.com/ariel.png" />
-        <AvatarFallback>AS</AvatarFallback>
-      </Avatar>
-      <div className="space-y-1">
-        <h4 className="text-sm font-semibold">Ariel Santos</h4>
-        <p className="text-sm text-muted-foreground">Design system architect at Xertica AI.</p>
-      </div>
-    </div>
-  </HoverCardContent>
-</HoverCard>;
-```
-
----
-
-## AI Rules
-
-- `HoverCard` opens on hover — never render interactive controls that require clicking inside it (use `Popover` for those).
-- Use `asChild` on `<HoverCardTrigger>` when the trigger is a styled element.
-- Set `className="w-80"` on `<HoverCardContent>` for rich content panels — the default is too narrow.
-
----
-
-## Related Components
-
-- [`Tooltip`](./tooltip.md) — For short text hints
-- [`Popover`](./popover.md) — For interactive floating panels
+# HoverCard
+
+## Overview
+
+A floating content panel that appears when hovering over a trigger element — designed for previewing additional information without navigating away. Unlike `Tooltip` (short text hints), `HoverCard` can contain rich content: user profiles, link previews, image thumbnails.
+
+---
+
+## When to Use
+
+- Author profile previews in comment threads or author lists
+- Link previews (URL cards)
+- Contextual information about a referenced entity
+
+## When NOT to Use
+
+- Short labels or hints — use `<Tooltip>` instead.
+- Interactive controls — use `<Popover>` instead.
+
+---
+
+## Anatomy
+
+```
+<HoverCard>
+  <HoverCardTrigger asChild>
+    <Button variant="link">@username</Button>
+  </HoverCardTrigger>
+  <HoverCardContent>
+    {/* Rich preview content */}
+  </HoverCardContent>
+</HoverCard>
+```
+
+---
+
+## Examples
+
+### User Profile Preview
+
+```tsx
+import {
+  HoverCard,
+  HoverCardContent,
+  HoverCardTrigger,
+  Avatar,
+  AvatarFallback,
+  AvatarImage,
+  Button,
+} from 'xertica-ui/ui';
+
+<HoverCard>
+  <HoverCardTrigger asChild>
+    <Button variant="link" className="p-0 h-auto">
+      @ariel
+    </Button>
+  </HoverCardTrigger>
+  <HoverCardContent className="w-80">
+    <div className="flex gap-4">
+      <Avatar>
+        <AvatarImage src="https://github.com/ariel.png" />
+        <AvatarFallback>AS</AvatarFallback>
+      </Avatar>
+      <div className="space-y-1">
+        <h4 className="text-sm font-semibold">Ariel Santos</h4>
+        <p className="text-sm text-muted-foreground">Design system architect at Xertica AI.</p>
+      </div>
+    </div>
+  </HoverCardContent>
+</HoverCard>;
+```
+
+---
+
+## AI Rules
+
+- `HoverCard` opens on hover — never render interactive controls that require clicking inside it (use `Popover` for those).
+- Use `asChild` on `<HoverCardTrigger>` when the trigger is a styled element.
+- Set `className="w-80"` on `<HoverCardContent>` for rich content panels — the default is too narrow.
+
+---
+
+## Related Components
+
+- [`Tooltip`](./tooltip.md) — For short text hints
+- [`Popover`](./popover.md) — For interactive floating panels

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`.