xertica-ui 2.5.2 → 2.6.0

package/components/ui/stats-card/stats-card.tsx

@@ -1,109 +1,109 @@
-import * as React from 'react';
-import { TrendingUp, TrendingDown, Minus } from 'lucide-react';
-import { cn } from '../../shared/utils';
-import { Card, CardContent } from '../card';
-
-interface StatsCardProps extends React.HTMLAttributes<HTMLDivElement> {
-  title: string;
-  value: string | number;
-  description?: string;
-  trend?: {
-    value: number;
-    label?: string;
-  };
-  icon?: React.ReactNode;
-  /**
-   * Tailwind class for the icon text/foreground color.
-   * @default "text-muted-foreground"
-   */
-  iconColor?: string;
-  /**
-   * Tailwind class for the icon background color.
-   * @default "bg-muted"
-   */
-  iconBg?: string;
-}
-
-/**
- * KPI metric card for dashboard overview pages.
- *
- * @description
- * Standardized layout for displaying a metric title, a large value, an
- * optional icon, and an optional trend indicator with automatic up/down/neutral
- * icon and color. Built on top of `<Card>`.
- *
- * @ai-rules
- * 1. Provide the `icon` as a Lucide React element with `className="size-5"`.
- * 2. `trend.value` is a raw number (e.g., `20.1` for +20.1%) — the component
- *    displays `Math.abs(value)%` automatically. Do NOT pre-format as string.
- * 3. `value` IS a pre-formatted display string: `"$45,231"`, `"3.6%"`, etc.
- * 4. `trend.label` takes precedence over `description` for below-value text.
- */
-const StatsCard = React.forwardRef<HTMLDivElement, StatsCardProps>(
-  ({ className, title, value, description, trend, icon, iconColor, iconBg, ...props }, ref) => {
-    const getTrendIcon = () => {
-      if (!trend) return null;
-
-      if (trend.value > 0) {
-        return <TrendingUp className="h-4 w-4 text-success" />;
-      } else if (trend.value < 0) {
-        return <TrendingDown className="h-4 w-4 text-destructive" />;
-      } else {
-        return <Minus className="h-4 w-4 text-muted-foreground" />;
-      }
-    };
-
-    const getTrendColor = () => {
-      if (!trend) return '';
-
-      if (trend.value > 0) {
-        return 'text-success';
-      } else if (trend.value < 0) {
-        return 'text-destructive';
-      } else {
-        return 'text-muted-foreground';
-      }
-    };
-
-    return (
-      <Card ref={ref} className={cn('', className)} {...props}>
-        <CardContent className="p-4 sm:p-6">
-          <div className="flex items-start justify-between gap-3">
-            <div className="flex-1 min-w-0">
-              <p className="text-muted-foreground mb-1 text-sm">{title}</p>
-              <div className="flex flex-wrap items-baseline gap-2">
-                <h3 className="text-foreground text-xl sm:text-2xl">{value}</h3>
-                {trend && (
-                  <div className={cn('flex items-center gap-1 text-sm', getTrendColor())}>
-                    {getTrendIcon()}
-                    <span>{Math.abs(trend.value)}%</span>
-                  </div>
-                )}
-              </div>
-              {(description || trend?.label) && (
-                <p className="text-muted-foreground mt-1 text-xs sm:text-sm">
-                  {trend?.label || description}
-                </p>
-              )}
-            </div>
-            {icon && (
-              <div
-                className={cn(
-                  'rounded-[var(--radius)] p-2 sm:p-3 flex-shrink-0',
-                  iconBg || 'bg-muted',
-                  iconColor || 'text-muted-foreground'
-                )}
-              >
-                {icon}
-              </div>
-            )}
-          </div>
-        </CardContent>
-      </Card>
-    );
-  }
-);
-StatsCard.displayName = 'StatsCard';
-
-export { StatsCard };
-export type { StatsCardProps };
+import * as React from 'react';
+import { TrendingUp, TrendingDown, Minus } from 'lucide-react';
+import { cn } from '../../shared/utils';
+import { Card, CardContent } from '../card';
+
+interface StatsCardProps extends React.HTMLAttributes<HTMLDivElement> {
+  title: string;
+  value: string | number;
+  description?: string;
+  trend?: {
+    value: number;
+    label?: string;
+  };
+  icon?: React.ReactNode;
+  /**
+   * Tailwind class for the icon text/foreground color.
+   * @default "text-muted-foreground"
+   */
+  iconColor?: string;
+  /**
+   * Tailwind class for the icon background color.
+   * @default "bg-muted"
+   */
+  iconBg?: string;
+}
+
+/**
+ * KPI metric card for dashboard overview pages.
+ *
+ * @description
+ * Standardized layout for displaying a metric title, a large value, an
+ * optional icon, and an optional trend indicator with automatic up/down/neutral
+ * icon and color. Built on top of `<Card>`.
+ *
+ * @ai-rules
+ * 1. Provide the `icon` as a Lucide React element with `className="size-5"`.
+ * 2. `trend.value` is a raw number (e.g., `20.1` for +20.1%) — the component
+ *    displays `Math.abs(value)%` automatically. Do NOT pre-format as string.
+ * 3. `value` IS a pre-formatted display string: `"$45,231"`, `"3.6%"`, etc.
+ * 4. `trend.label` takes precedence over `description` for below-value text.
+ */
+const StatsCard = React.forwardRef<HTMLDivElement, StatsCardProps>(
+  ({ className, title, value, description, trend, icon, iconColor, iconBg, ...props }, ref) => {
+    const getTrendIcon = () => {
+      if (!trend) return null;
+
+      if (trend.value > 0) {
+        return <TrendingUp className="h-4 w-4 text-success" />;
+      } else if (trend.value < 0) {
+        return <TrendingDown className="h-4 w-4 text-destructive" />;
+      } else {
+        return <Minus className="h-4 w-4 text-muted-foreground" />;
+      }
+    };
+
+    const getTrendColor = () => {
+      if (!trend) return '';
+
+      if (trend.value > 0) {
+        return 'text-success';
+      } else if (trend.value < 0) {
+        return 'text-destructive';
+      } else {
+        return 'text-muted-foreground';
+      }
+    };
+
+    return (
+      <Card ref={ref} className={cn('', className)} {...props}>
+        <CardContent className="p-4 sm:p-6">
+          <div className="flex items-start justify-between gap-3">
+            <div className="flex-1 min-w-0">
+              <p className="text-muted-foreground mb-1 text-sm">{title}</p>
+              <div className="flex flex-wrap items-baseline gap-2">
+                <h3 className="text-foreground text-xl sm:text-2xl">{value}</h3>
+                {trend && (
+                  <div className={cn('flex items-center gap-1 text-sm', getTrendColor())}>
+                    {getTrendIcon()}
+                    <span>{Math.abs(trend.value)}%</span>
+                  </div>
+                )}
+              </div>
+              {(description || trend?.label) && (
+                <p className="text-muted-foreground mt-1 text-xs sm:text-sm">
+                  {trend?.label || description}
+                </p>
+              )}
+            </div>
+            {icon && (
+              <div
+                className={cn(
+                  'rounded-[var(--radius)] p-2 sm:p-3 flex-shrink-0',
+                  iconBg || 'bg-muted',
+                  iconColor || 'text-muted-foreground'
+                )}
+              >
+                {icon}
+              </div>
+            )}
+          </div>
+        </CardContent>
+      </Card>
+    );
+  }
+);
+StatsCard.displayName = 'StatsCard';
+
+export { StatsCard };
+export type { StatsCardProps };

package/components/ui/stepper/stepper.mdx

@@ -1,26 +1,26 @@
-import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
-import * as StepperStories from './stepper.stories';
-
-<Meta of={StepperStories} />
-
-<Title />
-<Subtitle>A multi-step progress indicator for sequential user flows.</Subtitle>
-
-<Description />
-
-<Primary />
-
----
-
-## Variations
-
-<Stories />
-
----
-
-## AI Best Practices
-
-> [!IMPORTANT]
-> - **1-Indexed Steps** — Both `currentStep` and the individual `step` props must be 1-indexed (e.g., start from 1, not 0).
-> - **Consistent Ordering** — Ensure the `step` prop on each child matches its visual and logical position in the sequence.
-> - **Navigation Logic** — Place "Previous" and "Next" buttons below the stepper, and disable the "Previous" button when on the first step.
+import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
+import * as StepperStories from './stepper.stories';
+
+<Meta of={StepperStories} />
+
+<Title />
+<Subtitle>A multi-step progress indicator for sequential user flows.</Subtitle>
+
+<Description />
+
+<Primary />
+
+---
+
+## Variations
+
+<Stories />
+
+---
+
+## AI Best Practices
+
+> [!IMPORTANT]
+> - **1-Indexed Steps** — Both `currentStep` and the individual `step` props must be 1-indexed (e.g., start from 1, not 0).
+> - **Consistent Ordering** — Ensure the `step` prop on each child matches its visual and logical position in the sequence.
+> - **Navigation Logic** — Place "Previous" and "Next" buttons below the stepper, and disable the "Previous" button when on the first step.

package/components/ui/switch/switch.mdx

@@ -1,25 +1,25 @@
-import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
-import * as SwitchStories from './switch.stories';
-
-<Meta of={SwitchStories} />
-
-<Title />
-<Subtitle>A control that allows users to toggle between on and off states.</Subtitle>
-
-<Description />
-
-<Primary />
-
----
-
-## Variations
-
-<Stories />
-
----
-
-## AI Best Practices
-
-> [!IMPORTANT]
-> - **Immediate Action** — Use Switch for settings that take effect immediately without a "Save" button. For multi-option forms, consider `Checkbox`.
-> - **Accessibility** — Always pair with a `Label` linked via `id` and `htmlFor`.
+import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
+import * as SwitchStories from './switch.stories';
+
+<Meta of={SwitchStories} />
+
+<Title />
+<Subtitle>A control that allows users to toggle between on and off states.</Subtitle>
+
+<Description />
+
+<Primary />
+
+---
+
+## Variations
+
+<Stories />
+
+---
+
+## AI Best Practices
+
+> [!IMPORTANT]
+> - **Immediate Action** — Use Switch for settings that take effect immediately without a "Save" button. For multi-option forms, consider `Checkbox`.
+> - **Accessibility** — Always pair with a `Label` linked via `id` and `htmlFor`.

package/components/ui/table/table.mdx

@@ -1,27 +1,27 @@
-import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
-import * as TableStories from './table.stories';
-
-<Meta of={TableStories} />
-
-<Title />
-<Subtitle>Structured tabular data display for report and listing views.</Subtitle>
-
-<Description />
-
-<Primary />
-
----
-
-## Variations
-
-<Stories />
-
----
-
-## AI Best Practices
-
-> [!IMPORTANT]
-> - **Status Badges** — Always use `Badge` for status columns, never plain text.
-> - **Alignment** — Numeric and action columns should be right-aligned (`text-right`).
-> - **Row Actions** — Consolidate multiple row actions into a `DropdownMenu` to preserve horizontal space.
-> - **Responsive Hiding** — Use `hidden md:table-cell` to hide secondary columns on mobile.
+import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
+import * as TableStories from './table.stories';
+
+<Meta of={TableStories} />
+
+<Title />
+<Subtitle>Structured tabular data display for report and listing views.</Subtitle>
+
+<Description />
+
+<Primary />
+
+---
+
+## Variations
+
+<Stories />
+
+---
+
+## AI Best Practices
+
+> [!IMPORTANT]
+> - **Status Badges** — Always use `Badge` for status columns, never plain text.
+> - **Alignment** — Numeric and action columns should be right-aligned (`text-right`).
+> - **Row Actions** — Consolidate multiple row actions into a `DropdownMenu` to preserve horizontal space.
+> - **Responsive Hiding** — Use `hidden md:table-cell` to hide secondary columns on mobile.

package/components/ui/tabs/tabs.mdx

@@ -1,26 +1,26 @@
-import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
-import * as TabsStories from './tabs.stories';
-
-<Meta of={TabsStories} />
-
-<Title />
-<Subtitle>A content switcher for logically related views.</Subtitle>
-
-<Description />
-
-<Primary />
-
----
-
-## Variations
-
-<Stories />
-
----
-
-## AI Best Practices
-
-> [!IMPORTANT]
-> - **Value Matching** — Ensure `TabsTrigger` value matches the corresponding `TabsContent` value.
-> - **Spacing** — Add top margin (`mt-4` or `mt-6`) to `TabsContent` to separate it from the triggers.
-> - **Correct Component** — Use `Tabs` for in-page view switching. For global site navigation, use `Sidebar` or `NavigationMenu`.
+import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
+import * as TabsStories from './tabs.stories';
+
+<Meta of={TabsStories} />
+
+<Title />
+<Subtitle>A content switcher for logically related views.</Subtitle>
+
+<Description />
+
+<Primary />
+
+---
+
+## Variations
+
+<Stories />
+
+---
+
+## AI Best Practices
+
+> [!IMPORTANT]
+> - **Value Matching** — Ensure `TabsTrigger` value matches the corresponding `TabsContent` value.
+> - **Spacing** — Add top margin (`mt-4` or `mt-6`) to `TabsContent` to separate it from the triggers.
+> - **Correct Component** — Use `Tabs` for in-page view switching. For global site navigation, use `Sidebar` or `NavigationMenu`.

package/components/ui/textarea/textarea.mdx

@@ -1,25 +1,25 @@
-import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
-import * as TextareaStories from './textarea.stories';
-
-<Meta of={TextareaStories} />
-
-<Title />
-<Subtitle>A multi-line text input for longer descriptive content.</Subtitle>
-
-<Description />
-
-<Primary />
-
----
-
-## Variations
-
-<Stories />
-
----
-
-## AI Best Practices
-
-> [!IMPORTANT]
-> - **Scroll Area** — Textareas will automatically show a scrollbar if the content exceeds the fixed height.
-> - **Labels** — Link to a `Label` via `id` and `htmlFor`.
+import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
+import * as TextareaStories from './textarea.stories';
+
+<Meta of={TextareaStories} />
+
+<Title />
+<Subtitle>A multi-line text input for longer descriptive content.</Subtitle>
+
+<Description />
+
+<Primary />
+
+---
+
+## Variations
+
+<Stories />
+
+---
+
+## AI Best Practices
+
+> [!IMPORTANT]
+> - **Scroll Area** — Textareas will automatically show a scrollbar if the content exceeds the fixed height.
+> - **Labels** — Link to a `Label` via `id` and `htmlFor`.

package/components/ui/timeline/timeline.mdx

@@ -1,26 +1,26 @@
-import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
-import * as TimelineStories from './timeline.stories';
-
-<Meta of={TimelineStories} />
-
-<Title />
-<Subtitle>A vertical chronological record of events or activities.</Subtitle>
-
-<Description />
-
-<Primary />
-
----
-
-## Variations
-
-<Stories />
-
----
-
-## AI Best Practices
-
-> [!IMPORTANT]
-> - **Pre-formatted Timestamps** — Use display-ready strings for the `timestamp` field; the component does not perform date formatting.
-> - **Semantic Variants** — Leverage the `variant` prop (`success`, `warning`, `destructive`) to automatically theme the event icons.
-> - **Container Sizing** — For long history feeds, wrap the `Timeline` in a `ScrollArea` component to maintain layout stability.
+import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
+import * as TimelineStories from './timeline.stories';
+
+<Meta of={TimelineStories} />
+
+<Title />
+<Subtitle>A vertical chronological record of events or activities.</Subtitle>
+
+<Description />
+
+<Primary />
+
+---
+
+## Variations
+
+<Stories />
+
+---
+
+## AI Best Practices
+
+> [!IMPORTANT]
+> - **Pre-formatted Timestamps** — Use display-ready strings for the `timestamp` field; the component does not perform date formatting.
+> - **Semantic Variants** — Leverage the `variant` prop (`success`, `warning`, `destructive`) to automatically theme the event icons.
+> - **Container Sizing** — For long history feeds, wrap the `Timeline` in a `ScrollArea` component to maintain layout stability.

package/components/ui/toggle/toggle.mdx

@@ -1,26 +1,26 @@
-import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
-import * as ToggleStories from './toggle.stories';
-
-<Meta of={ToggleStories} />
-
-<Title />
-<Subtitle>A two-state button that can be toggled on or off.</Subtitle>
-
-<Description />
-
-<Primary />
-
----
-
-## Variations
-
-<Stories />
-
----
-
-## AI Best Practices
-
-> [!IMPORTANT]
-> - **ARIA Labelling** — Always provide an `aria-label` for icon-only toggles to ensure accessibility.
-> - **Semantic Choice** — Use `Toggle` for toolbar-style interactions. For user preferences or configuration settings, use `Switch` or `Checkbox`.
-> - **State Management** — Use `pressed` and `onPressedChange` for controlled components.
+import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
+import * as ToggleStories from './toggle.stories';
+
+<Meta of={ToggleStories} />
+
+<Title />
+<Subtitle>A two-state button that can be toggled on or off.</Subtitle>
+
+<Description />
+
+<Primary />
+
+---
+
+## Variations
+
+<Stories />
+
+---
+
+## AI Best Practices
+
+> [!IMPORTANT]
+> - **ARIA Labelling** — Always provide an `aria-label` for icon-only toggles to ensure accessibility.
+> - **Semantic Choice** — Use `Toggle` for toolbar-style interactions. For user preferences or configuration settings, use `Switch` or `Checkbox`.
+> - **State Management** — Use `pressed` and `onPressedChange` for controlled components.

package/components/ui/toggle-group/toggle-group.mdx

@@ -1,26 +1,26 @@
-import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
-import * as ToggleGroupStories from './toggle-group.stories';
-
-<Meta of={ToggleGroupStories} />
-
-<Title />
-<Subtitle>A synchronized set of toggle buttons with single or multiple selection.</Subtitle>
-
-<Description />
-
-<Primary />
-
----
-
-## Variations
-
-<Stories />
-
----
-
-## AI Best Practices
-
-> [!IMPORTANT]
-> - **Selection Mode** — Explicitly define the `type` prop as either `single` or `multiple` based on the semantic requirement of the group.
-> - **Accessibility** — Ensure every `ToggleGroupItem` has an `aria-label` when only an icon is displayed.
-> - **Default Values** — Use `defaultValue` or `value` to ensure the group has a pre-selected state if required.
+import { Meta, Title, Subtitle, Description, Primary, Controls, Stories, Canvas } from '@storybook/addon-docs/blocks';
+import * as ToggleGroupStories from './toggle-group.stories';
+
+<Meta of={ToggleGroupStories} />
+
+<Title />
+<Subtitle>A synchronized set of toggle buttons with single or multiple selection.</Subtitle>
+
+<Description />
+
+<Primary />
+
+---
+
+## Variations
+
+<Stories />
+
+---
+
+## AI Best Practices
+
+> [!IMPORTANT]
+> - **Selection Mode** — Explicitly define the `type` prop as either `single` or `multiple` based on the semantic requirement of the group.
+> - **Accessibility** — Ensure every `ToggleGroupItem` has an `aria-label` when only an icon is displayed.
+> - **Default Values** — Use `defaultValue` or `value` to ensure the group has a pre-selected state if required.