xertica-ui 2.2.1 → 2.4.0

package/docs/components/navigation-menu.md

@@ -1,83 +1,83 @@
-# Navigation Menu
-
-## Overview
-
-A horizontal navigation bar designed for top-level application sections. Supports dropdown sub-menus with rich content panels. Use it as a secondary top navigation when the primary navigation is in the `<Sidebar>`. Built on Radix UI NavigationMenu.
-
----
-
-## When to Use
-
-- Horizontal navigation between top-level sections in a webapp or marketing site
-- When combined with the Sidebar for secondary navigation categories
-
-## When NOT to Use
-
-- Primary app navigation — use `<Sidebar>` for that.
-- Simple links — use plain `<a>` or `<Button>` with `asChild`.
-
----
-
-## Anatomy
-
-```
-<NavigationMenu>
-  <NavigationMenuList>
-    <NavigationMenuItem>
-      <NavigationMenuTrigger>Getting Started</NavigationMenuTrigger>
-      <NavigationMenuContent>
-        {/* Rich dropdown content */}
-      </NavigationMenuContent>
-    </NavigationMenuItem>
-    <NavigationMenuItem>
-      <NavigationMenuLink href="/docs">Docs</NavigationMenuLink>
-    </NavigationMenuItem>
-  </NavigationMenuList>
-</NavigationMenu>
-```
-
----
-
-## Examples
-
-```tsx
-import {
-  NavigationMenu,
-  NavigationMenuContent,
-  NavigationMenuItem,
-  NavigationMenuLink,
-  NavigationMenuList,
-  NavigationMenuTrigger,
-} from 'xertica-ui/ui';
-
-<NavigationMenu>
-  <NavigationMenuList>
-    <NavigationMenuItem>
-      <NavigationMenuTrigger>Products</NavigationMenuTrigger>
-      <NavigationMenuContent>
-        <div className="grid gap-3 p-4 w-[300px]">
-          <div className="space-y-1">
-            <h4 className="text-sm font-medium">Analytics</h4>
-            <p className="text-xs text-muted-foreground">Real-time data insights</p>
-          </div>
-          <div className="space-y-1">
-            <h4 className="text-sm font-medium">AI Assistant</h4>
-            <p className="text-xs text-muted-foreground">Integrated AI workflows</p>
-          </div>
-        </div>
-      </NavigationMenuContent>
-    </NavigationMenuItem>
-    <NavigationMenuItem>
-      <NavigationMenuLink href="/pricing">Pricing</NavigationMenuLink>
-    </NavigationMenuItem>
-  </NavigationMenuList>
-</NavigationMenu>;
-```
-
----
-
-## AI Rules
-
-- `NavigationMenu` is for **horizontal marketing/secondary navigation** — not for dashboard left-rail navigation (use `Sidebar`).
-- `NavigationMenuContent` renders in a portal — ensure `XerticaProvider` wraps the app.
-- Use `NavigationMenuLink` for simple links; use `NavigationMenuTrigger` + `NavigationMenuContent` for dropdown sub-menus.
+# Navigation Menu
+
+## Overview
+
+A horizontal navigation bar designed for top-level application sections. Supports dropdown sub-menus with rich content panels. Use it as a secondary top navigation when the primary navigation is in the `<Sidebar>`. Built on Radix UI NavigationMenu.
+
+---
+
+## When to Use
+
+- Horizontal navigation between top-level sections in a webapp or marketing site
+- When combined with the Sidebar for secondary navigation categories
+
+## When NOT to Use
+
+- Primary app navigation — use `<Sidebar>` for that.
+- Simple links — use plain `<a>` or `<Button>` with `asChild`.
+
+---
+
+## Anatomy
+
+```
+<NavigationMenu>
+  <NavigationMenuList>
+    <NavigationMenuItem>
+      <NavigationMenuTrigger>Getting Started</NavigationMenuTrigger>
+      <NavigationMenuContent>
+        {/* Rich dropdown content */}
+      </NavigationMenuContent>
+    </NavigationMenuItem>
+    <NavigationMenuItem>
+      <NavigationMenuLink href="/docs">Docs</NavigationMenuLink>
+    </NavigationMenuItem>
+  </NavigationMenuList>
+</NavigationMenu>
+```
+
+---
+
+## Examples
+
+```tsx
+import {
+  NavigationMenu,
+  NavigationMenuContent,
+  NavigationMenuItem,
+  NavigationMenuLink,
+  NavigationMenuList,
+  NavigationMenuTrigger,
+} from 'xertica-ui/ui';
+
+<NavigationMenu>
+  <NavigationMenuList>
+    <NavigationMenuItem>
+      <NavigationMenuTrigger>Products</NavigationMenuTrigger>
+      <NavigationMenuContent>
+        <div className="grid gap-3 p-4 w-[300px]">
+          <div className="space-y-1">
+            <h4 className="text-sm font-medium">Analytics</h4>
+            <p className="text-xs text-muted-foreground">Real-time data insights</p>
+          </div>
+          <div className="space-y-1">
+            <h4 className="text-sm font-medium">AI Assistant</h4>
+            <p className="text-xs text-muted-foreground">Integrated AI workflows</p>
+          </div>
+        </div>
+      </NavigationMenuContent>
+    </NavigationMenuItem>
+    <NavigationMenuItem>
+      <NavigationMenuLink href="/pricing">Pricing</NavigationMenuLink>
+    </NavigationMenuItem>
+  </NavigationMenuList>
+</NavigationMenu>;
+```
+
+---
+
+## AI Rules
+
+- `NavigationMenu` is for **horizontal marketing/secondary navigation** — not for dashboard left-rail navigation (use `Sidebar`).
+- `NavigationMenuContent` renders in a portal — ensure `XerticaProvider` wraps the app.
+- Use `NavigationMenuLink` for simple links; use `NavigationMenuTrigger` + `NavigationMenuContent` for dropdown sub-menus.

package/docs/components/notification-badge.md

@@ -1,78 +1,78 @@
-# Notification Badge
-
-## Overview
-
-A small overlay indicator that appears on top of another element (typically an icon button) to communicate an unread count or attention cue. Appears as a colored dot (attention) or a numbered badge (count).
-
----
-
-## When to Use
-
-- Notification bell icons in the header with unread count
-- Navigation items with pending action counts
-- Tab indicators with item counts
-
----
-
-## Props
-
-| Prop        | Type                                                                                         | Default         | Required | Description                                             |
-| ----------- | -------------------------------------------------------------------------------------------- | --------------- | -------- | ------------------------------------------------------- |
-| `count`     | `number`                                                                                     | `0`             | No       | Number to display                                       |
-| `max`       | `number`                                                                                     | `99`            | No       | Maximum count to display (shows `{max}+` when exceeded) |
-| `dot`       | `boolean`                                                                                    | `false`         | No       | Renders a dot indicator instead of a count badge        |
-| `showZero`  | `boolean`                                                                                    | `false`         | No       | Show the badge even when count is 0                     |
-| `variant`   | `'default' \| 'secondary' \| 'destructive' \| 'outline' \| 'success' \| 'info' \| 'warning'` | `'destructive'` | No       | Color variant                                           |
-| `className` | `string`                                                                                     | —               | No       | Additional classes                                      |
-
----
-
-## Examples
-
-### Notification Bell with Count
-
-```tsx
-import { NotificationBadge, Button } from 'xertica-ui/ui';
-import { Bell } from 'lucide-react';
-
-<NotificationBadge count={3} variant="destructive">
-  <Button variant="ghost" size="icon" aria-label="Notifications">
-    <Bell className="size-4" />
-  </Button>
-</NotificationBadge>;
-```
-
-### Dot Indicator
-
-```tsx
-import { Mail } from 'lucide-react';
-
-<NotificationBadge dot variant="success">
-  <Button variant="ghost" size="icon" aria-label="Messages">
-    <Mail className="size-4" />
-  </Button>
-</NotificationBadge>;
-```
-
-### Status Variants
-
-```tsx
-<NotificationBadge count={5} variant="info">...</NotificationBadge>
-<NotificationBadge count={2} variant="warning">...</NotificationBadge>
-<NotificationBadge count={1} variant="success">...</NotificationBadge>
-```
-
----
-
-## AI Rules
-
-- Always wrap the target element as a child — the badge positions itself automatically in the top-right corner.
-- When count is `0`, prefer not rendering the badge at all rather than showing `0` (use `showZero` to override).
-- Maximum display value defaults to `99` — showing `99+` instead of large numbers.
-- For standalone status labels (not overlays), use `<Badge>` instead.
-
----
-
-## Related Components
-
-- [`Badge`](./badge.md) — For standalone inline status labels
+# Notification Badge
+
+## Overview
+
+A small overlay indicator that appears on top of another element (typically an icon button) to communicate an unread count or attention cue. Appears as a colored dot (attention) or a numbered badge (count).
+
+---
+
+## When to Use
+
+- Notification bell icons in the header with unread count
+- Navigation items with pending action counts
+- Tab indicators with item counts
+
+---
+
+## Props
+
+| Prop        | Type                                                                                         | Default         | Required | Description                                             |
+| ----------- | -------------------------------------------------------------------------------------------- | --------------- | -------- | ------------------------------------------------------- |
+| `count`     | `number`                                                                                     | `0`             | No       | Number to display                                       |
+| `max`       | `number`                                                                                     | `99`            | No       | Maximum count to display (shows `{max}+` when exceeded) |
+| `dot`       | `boolean`                                                                                    | `false`         | No       | Renders a dot indicator instead of a count badge        |
+| `showZero`  | `boolean`                                                                                    | `false`         | No       | Show the badge even when count is 0                     |
+| `variant`   | `'default' \| 'secondary' \| 'destructive' \| 'outline' \| 'success' \| 'info' \| 'warning'` | `'destructive'` | No       | Color variant                                           |
+| `className` | `string`                                                                                     | —               | No       | Additional classes                                      |
+
+---
+
+## Examples
+
+### Notification Bell with Count
+
+```tsx
+import { NotificationBadge, Button } from 'xertica-ui/ui';
+import { Bell } from 'lucide-react';
+
+<NotificationBadge count={3} variant="destructive">
+  <Button variant="ghost" size="icon" aria-label="Notifications">
+    <Bell className="size-4" />
+  </Button>
+</NotificationBadge>;
+```
+
+### Dot Indicator
+
+```tsx
+import { Mail } from 'lucide-react';
+
+<NotificationBadge dot variant="success">
+  <Button variant="ghost" size="icon" aria-label="Messages">
+    <Mail className="size-4" />
+  </Button>
+</NotificationBadge>;
+```
+
+### Status Variants
+
+```tsx
+<NotificationBadge count={5} variant="info">...</NotificationBadge>
+<NotificationBadge count={2} variant="warning">...</NotificationBadge>
+<NotificationBadge count={1} variant="success">...</NotificationBadge>
+```
+
+---
+
+## AI Rules
+
+- Always wrap the target element as a child — the badge positions itself automatically in the top-right corner.
+- When count is `0`, prefer not rendering the badge at all rather than showing `0` (use `showZero` to override).
+- Maximum display value defaults to `99` — showing `99+` instead of large numbers.
+- For standalone status labels (not overlays), use `<Badge>` instead.
+
+---
+
+## Related Components
+
+- [`Badge`](./badge.md) — For standalone inline status labels

package/docs/components/page-header.md

@@ -1,93 +1,93 @@
-# PageHeader
-
-## Overview
-
-The `PageHeader` is a content-level component used to provide immediate context for a specific page or section. It focuses on the page title, subtitle, back navigation, and primary local actions (like "Create" or "Edit").
-
-**Important:** This is NOT the global Top Bar. For the global application header with profile and system breadcrumbs, use the [`Header`](./header.md) component.
-
----
-
-## Key Features
-
-- **Primary Heading**: Standardized `h1` styling with optional subtitle.
-- **Back Navigation**: Built-in back button with support for standard links (`backHref`) or programmatic handlers (`onBack`).
-- **Local Actions**: Dedicated area on the right for primary page controls (Buttons, Dropdowns, etc.).
-- **Typography Primitives**: Exports `PageHeaderHeading` and `PageHeaderDescription` for building custom header layouts.
-
----
-
-## When to Use
-
-- Use at the top of the **content area** of every main page.
-- Perfect for detail pages, forms, or any view that requires a clear title and a "Back" button.
-
----
-
-## Props
-
-| Prop        | Type              | Default | Required | Description                                                             |
-| ----------- | ----------------- | ------- | -------- | ----------------------------------------------------------------------- |
-| `title`     | `string`          | —       | **Yes**  | The primary H1 title for the page.                                      |
-| `subtitle`  | `string`          | —       | No       | Secondary description or context text.                                  |
-| `backHref`  | `string`          | —       | No       | Relative URL for the back button. If provided, renders as an `<a>` tag. |
-| `onBack`    | `() => void`      | —       | No       | Click handler for the back button.                                      |
-| `actions`   | `React.ReactNode` | —       | No       | Buttons or controls to render on the right side.                        |
-| `className` | `string`          | —       | No       | Additional CSS classes for the container.                               |
-
----
-
-## Examples
-
-### Standard Usage
-
-```tsx
-import { PageHeader, Button } from 'xertica-ui/ui';
-import { Plus } from 'lucide-react';
-
-<PageHeader
-  title="Users"
-  subtitle="Manage and invite members to your workspace."
-  actions={
-    <Button size="sm">
-      <Plus className="mr-2 size-4" /> Add User
-    </Button>
-  }
-/>;
-```
-
-### With Back Navigation
-
-```tsx
-import { PageHeader } from 'xertica-ui/ui';
-
-<PageHeader title="Edit Profile" backHref="/settings" />;
-```
-
-### Custom Typography
-
-```tsx
-import { PageHeaderHeading, PageHeaderDescription } from 'xertica-ui/ui';
-
-<section>
-  <PageHeaderHeading>Analytics Overview</PageHeaderHeading>
-  <PageHeaderDescription>Detailed metrics for your current project.</PageHeaderDescription>
-</section>;
-```
-
----
-
-## AI Rules
-
-- **SEO** — Always provide a meaningful `title`. This component renders the page's primary `h1`.
-- **Navigation** — If the page is a sub-view, always provide `backHref` or `onBack` to maintain intuitive UX.
-- **Hierarchy** — Place the `PageHeader` immediately after the global `Header` within the main content container.
-- **Actions** — Keep the number of `actions` limited (ideally 1-3 buttons) to prevent crowding on mobile.
-
----
-
-## Related Components
-
-- [`Header`](./header.md) — The global application toolbar.
-- [`Button`](./button.md) — Commonly used within the `actions` prop.
-- [`Breadcrumb`](./breadcrumb.md) — Should be used in the global `Header`, not here.
+# PageHeader
+
+## Overview
+
+The `PageHeader` is a content-level component used to provide immediate context for a specific page or section. It focuses on the page title, subtitle, back navigation, and primary local actions (like "Create" or "Edit").
+
+**Important:** This is NOT the global Top Bar. For the global application header with profile and system breadcrumbs, use the [`Header`](./header.md) component.
+
+---
+
+## Key Features
+
+- **Primary Heading**: Standardized `h1` styling with optional subtitle.
+- **Back Navigation**: Built-in back button with support for standard links (`backHref`) or programmatic handlers (`onBack`).
+- **Local Actions**: Dedicated area on the right for primary page controls (Buttons, Dropdowns, etc.).
+- **Typography Primitives**: Exports `PageHeaderHeading` and `PageHeaderDescription` for building custom header layouts.
+
+---
+
+## When to Use
+
+- Use at the top of the **content area** of every main page.
+- Perfect for detail pages, forms, or any view that requires a clear title and a "Back" button.
+
+---
+
+## Props
+
+| Prop        | Type              | Default | Required | Description                                                             |
+| ----------- | ----------------- | ------- | -------- | ----------------------------------------------------------------------- |
+| `title`     | `string`          | —       | **Yes**  | The primary H1 title for the page.                                      |
+| `subtitle`  | `string`          | —       | No       | Secondary description or context text.                                  |
+| `backHref`  | `string`          | —       | No       | Relative URL for the back button. If provided, renders as an `<a>` tag. |
+| `onBack`    | `() => void`      | —       | No       | Click handler for the back button.                                      |
+| `actions`   | `React.ReactNode` | —       | No       | Buttons or controls to render on the right side.                        |
+| `className` | `string`          | —       | No       | Additional CSS classes for the container.                               |
+
+---
+
+## Examples
+
+### Standard Usage
+
+```tsx
+import { PageHeader, Button } from 'xertica-ui/ui';
+import { Plus } from 'lucide-react';
+
+<PageHeader
+  title="Users"
+  subtitle="Manage and invite members to your workspace."
+  actions={
+    <Button size="sm">
+      <Plus className="mr-2 size-4" /> Add User
+    </Button>
+  }
+/>;
+```
+
+### With Back Navigation
+
+```tsx
+import { PageHeader } from 'xertica-ui/ui';
+
+<PageHeader title="Edit Profile" backHref="/settings" />;
+```
+
+### Custom Typography
+
+```tsx
+import { PageHeaderHeading, PageHeaderDescription } from 'xertica-ui/ui';
+
+<section>
+  <PageHeaderHeading>Analytics Overview</PageHeaderHeading>
+  <PageHeaderDescription>Detailed metrics for your current project.</PageHeaderDescription>
+</section>;
+```
+
+---
+
+## AI Rules
+
+- **SEO** — Always provide a meaningful `title`. This component renders the page's primary `h1`.
+- **Navigation** — If the page is a sub-view, always provide `backHref` or `onBack` to maintain intuitive UX.
+- **Hierarchy** — Place the `PageHeader` immediately after the global `Header` within the main content container.
+- **Actions** — Keep the number of `actions` limited (ideally 1-3 buttons) to prevent crowding on mobile.
+
+---
+
+## Related Components
+
+- [`Header`](./header.md) — The global application toolbar.
+- [`Button`](./button.md) — Commonly used within the `actions` prop.
+- [`Breadcrumb`](./breadcrumb.md) — Should be used in the global `Header`, not here.