@hexclave/dashboard-ui-components 1.0.3 → 1.0.6

package/src/components/metric-card.tsx

@@ -0,0 +1,142 @@
+"use client";
+
+import { cn } from "@hexclave/ui";
+import React from "react";
+
+type DesignMetricCardGradient = "blue" | "cyan" | "purple" | "green" | "orange" | "default";
+
+const hoverTintClasses = new Map<DesignMetricCardGradient, string>([
+  ["blue", "group-hover:bg-blue-500/[0.03]"],
+  ["cyan", "group-hover:bg-cyan-500/[0.03]"],
+  ["purple", "group-hover:bg-purple-500/[0.03]"],
+  ["green", "group-hover:bg-emerald-500/[0.03]"],
+  ["orange", "group-hover:bg-orange-500/[0.03]"],
+  ["default", "group-hover:bg-slate-500/[0.02]"],
+]);
+
+export type DesignMetricCardTrend = {
+  value: number,
+  direction: "up" | "down",
+  label?: string,
+};
+
+export type DesignMetricCardProps = {
+  label: string,
+  value: string | number,
+  description?: string,
+  trend?: DesignMetricCardTrend,
+  icon?: React.ElementType,
+  gradient?: DesignMetricCardGradient,
+} & Omit<React.ComponentProps<"div">, "children">;
+
+/**
+ * KPI card for big-number metrics (users, revenue, signups, etc.).
+ * Use this instead of a plain `DesignCard` when the value is the focal point.
+ *
+ * ```tsx
+ * <DesignMetricCard
+ *   label="Total Users"
+ *   value="1,234"
+ *   description="+12% from last month"
+ *   trend={{ direction: "up", value: 12, label: "vs. last period" }}
+ *   icon={UsersIcon}
+ *   gradient="blue"
+ * />
+ * ```
+ *
+ * Notes:
+ * - `label` is the short caption (NOT `title`).
+ * - `value` can be a pre-formatted string ("1,234") or a number — prefer
+ *   strings so you control the format.
+ * - `description` is the subline (NOT `subtitle`).
+ * - `trend.value` is a NUMBER, not a pre-formatted "12%" string. The card
+ *   renders the arrow and formatting.
+ * - `icon` is a component type (e.g. `UsersIcon`), not a rendered node.
+ */
+export function DesignMetricCard({
+  label,
+  value,
+  description,
+  trend,
+  icon: Icon,
+  gradient = "default",
+  className,
+  ...props
+}: DesignMetricCardProps) {
+  const hoverTintClass = hoverTintClasses.get(gradient) ?? "group-hover:bg-slate-500/[0.02]";
+
+  return (
+    <div
+      className={cn(
+        "group relative rounded-2xl bg-white/90 dark:bg-background/60 backdrop-blur-xl transition-all duration-150 hover:transition-none overflow-hidden",
+        "ring-1 ring-black/[0.06] hover:ring-black/[0.1] dark:ring-white/[0.06] dark:hover:ring-white/[0.1]",
+        "shadow-sm hover:shadow-md",
+        className
+      )}
+      {...props}
+    >
+      <div className="absolute inset-0 bg-gradient-to-br from-foreground/[0.04] dark:from-foreground/[0.02] to-transparent pointer-events-none rounded-2xl" />
+      <div
+        className={cn(
+          "absolute inset-0 transition-colors duration-150 group-hover:transition-none pointer-events-none rounded-2xl",
+          hoverTintClass
+        )}
+      />
+      <div className="relative p-5">
+        <div className="flex items-start justify-between gap-3">
+          <div className="flex-1 min-w-0">
+            <div className="flex items-center gap-2">
+              {Icon && (
+                <div className="p-1.5 rounded-lg bg-foreground/[0.06] dark:bg-foreground/[0.04]">
+                  <Icon className="h-3.5 w-3.5 text-foreground/70 dark:text-muted-foreground" />
+                </div>
+              )}
+              <span className="text-xs font-semibold text-muted-foreground uppercase tracking-wider">
+                {label}
+              </span>
+            </div>
+            <div className="mt-3 flex items-baseline gap-2">
+              <span className="text-3xl font-bold tabular-nums text-foreground">
+                {typeof value === "number" ? value.toLocaleString() : value}
+              </span>
+              {trend && (
+                <span
+                  className={cn(
+                    "inline-flex items-center gap-0.5 text-xs font-medium",
+                    trend.direction === "up"
+                      ? "text-emerald-600 dark:text-emerald-400"
+                      : "text-red-600 dark:text-red-400"
+                  )}
+                >
+                  <svg
+                    className={cn("h-3 w-3", trend.direction === "down" && "rotate-180")}
+                    viewBox="0 0 12 12"
+                    fill="none"
+                    xmlns="http://www.w3.org/2000/svg"
+                  >
+                    <path
+                      d="M6 2.5V9.5M6 2.5L3 5.5M6 2.5L9 5.5"
+                      stroke="currentColor"
+                      strokeWidth="1.5"
+                      strokeLinecap="round"
+                      strokeLinejoin="round"
+                    />
+                  </svg>
+                  {trend.value}%
+                  {trend.label && (
+                    <span className="text-muted-foreground ml-0.5">{trend.label}</span>
+                  )}
+                </span>
+              )}
+            </div>
+            {description && (
+              <p className="mt-1 text-xs text-muted-foreground">
+                {description}
+              </p>
+            )}
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/components/pill-toggle.tsx

@@ -0,0 +1,159 @@
+"use client";
+
+import { useState } from "react";
+import { cn, Spinner, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "@hexclave/ui";
+import { TooltipPortal } from "@radix-ui/react-tooltip";
+import { runAsynchronouslyWithAlert } from "@hexclave/shared/dist/utils/promises";
+import { useGlassmorphicDefault } from "./card";
+
+type DesignPillToggleSize = "sm" | "md" | "lg";
+type DesignPillToggleGradient = "blue" | "cyan" | "purple" | "green" | "orange" | "default";
+
+export type DesignPillToggleOption = {
+  id: string,
+  label: string,
+  icon?: React.ElementType,
+};
+
+export type DesignPillToggleProps = {
+  options: DesignPillToggleOption[],
+  selected: string,
+  onSelect: (id: string) => void | Promise<void>,
+  size?: DesignPillToggleSize,
+  glassmorphic?: boolean,
+  gradient?: DesignPillToggleGradient,
+  /** When false, hides labels and shows a tooltip on hover instead. Defaults to true. */
+  showLabels?: boolean,
+  className?: string,
+};
+
+type SizeClass = {
+  button: string,
+  icon: string,
+};
+
+const sizeClasses = new Map<DesignPillToggleSize, SizeClass>([
+  ["sm", { button: "px-3 py-1.5 text-xs", icon: "h-3.5 w-3.5" }],
+  ["md", { button: "px-4 py-2 text-sm", icon: "h-4 w-4" }],
+  ["lg", { button: "px-5 py-2.5 text-sm", icon: "h-4 w-4" }],
+]);
+
+const gradientClasses = new Map<DesignPillToggleGradient, string>([
+  ["blue", "ring-blue-500/20 dark:ring-blue-400/20"],
+  ["cyan", "ring-cyan-500/20 dark:ring-cyan-400/20"],
+  ["purple", "ring-purple-500/20 dark:ring-purple-400/20"],
+  ["green", "ring-emerald-500/20 dark:ring-emerald-400/20"],
+  ["orange", "ring-amber-500/20 dark:ring-amber-400/20"],
+  ["default", "ring-black/[0.12] dark:ring-white/[0.06]"],
+]);
+
+function getMapValueOrThrow<TKey, TValue>(map: Map<TKey, TValue>, key: TKey, mapName: string) {
+  const value = map.get(key);
+  if (!value) {
+    throw new Error(`Missing ${mapName} entry for key "${String(key)}"`);
+  }
+  return value;
+}
+
+export function DesignPillToggle({
+  options,
+  selected,
+  onSelect,
+  size = "md",
+  glassmorphic: glassmorphicProp,
+  gradient = "default",
+  showLabels = true,
+  className,
+}: DesignPillToggleProps) {
+  const glassmorphic = useGlassmorphicDefault(glassmorphicProp);
+  const sizeClass = getMapValueOrThrow(sizeClasses, size, "sizeClasses");
+  const activeRingClass = getMapValueOrThrow(gradientClasses, gradient, "gradientClasses");
+
+  const [loadingOptionId, setLoadingOptionId] = useState<string | null>(null);
+
+  const handleClick = (optionId: string) => {
+    const result = onSelect(optionId);
+    if (result && typeof (result as Promise<void>).then === "function") {
+      setLoadingOptionId(optionId);
+      runAsynchronouslyWithAlert(
+        Promise.resolve(result).finally(() => setLoadingOptionId(null))
+      );
+    }
+  };
+
+  return (
+    <TooltipProvider>
+      <div
+        className={cn(
+          "inline-flex items-center gap-1 p-1 rounded-xl",
+          glassmorphic
+            ? "bg-foreground/[0.04] backdrop-blur-sm"
+            : "bg-black/[0.08] dark:bg-white/[0.04]",
+          className
+        )}
+      >
+        {options.map((option) => {
+          const isActive = selected === option.id;
+          const Icon = option.icon;
+
+          const pill = (
+            <button
+              type="button"
+              key={option.id}
+              onClick={() => handleClick(option.id)}
+              disabled={loadingOptionId !== null}
+              className={cn(
+                "relative flex items-center gap-2 font-medium rounded-lg transition-all duration-150 hover:transition-none",
+                sizeClass.button,
+                isActive
+                  ? cn(
+                    "bg-white dark:bg-background text-foreground shadow-sm ring-1",
+                    glassmorphic
+                      ? "ring-foreground/[0.06] dark:bg-[hsl(240,71%,70%)]/10 dark:text-[hsl(240,71%,90%)] dark:ring-[hsl(240,71%,70%)]/20"
+                      : activeRingClass
+                  )
+                  : cn(
+                    "text-muted-foreground hover:text-foreground",
+                    glassmorphic
+                      ? "hover:bg-background/50"
+                      : "hover:bg-black/[0.06] dark:hover:bg-white/[0.04]"
+                  )
+              )}
+            >
+              {loadingOptionId === option.id && (
+                <Spinner
+                  size={12}
+                  className="absolute left-1/2 top-1/2 -translate-x-1/2 -translate-y-1/2 pointer-events-none"
+                />
+              )}
+              <span className={cn(
+                "flex items-center gap-2",
+                loadingOptionId === option.id && "invisible"
+              )}>
+                {Icon && <Icon className={sizeClass.icon} />}
+                {showLabels && option.label}
+              </span>
+            </button>
+          );
+
+          if (!showLabels) {
+            return (
+              <Tooltip key={option.id} delayDuration={0}>
+                <TooltipTrigger asChild>
+                  {pill}
+                </TooltipTrigger>
+                <TooltipPortal>
+                  <TooltipContent side="top">
+                    {option.label}
+                  </TooltipContent>
+                </TooltipPortal>
+              </Tooltip>
+            );
+          }
+
+          return pill;
+        })}
+      </div>
+    </TooltipProvider>
+  );
+}

package/src/components/progress-bar.tsx

@@ -0,0 +1,82 @@
+"use client";
+
+import { cn } from "@hexclave/ui";
+
+type DesignProgressBarGradient = "blue" | "cyan" | "purple" | "green" | "orange" | "default";
+
+const fillClasses = new Map<DesignProgressBarGradient, string>([
+  ["blue", "bg-blue-500 dark:bg-blue-400"],
+  ["cyan", "bg-cyan-500 dark:bg-cyan-400"],
+  ["purple", "bg-purple-500 dark:bg-purple-400"],
+  ["green", "bg-emerald-500 dark:bg-emerald-400"],
+  ["orange", "bg-amber-500 dark:bg-amber-400"],
+  ["default", "bg-foreground/60"],
+]);
+
+export type DesignProgressBarProps = {
+  value: number,
+  max?: number,
+  gradient?: DesignProgressBarGradient,
+  label?: string,
+  showPercentage?: boolean,
+  size?: "sm" | "md" | "lg",
+  className?: string,
+};
+
+/**
+ * Horizontal progress bar for quota / fill-level indicators. Takes a
+ * `value` and optional `max` (defaults to 100 — pass raw values, the
+ * component computes the percentage). Optional label + percentage display.
+ *
+ * ```tsx
+ * <DesignProgressBar value={usedSeats} max={totalSeats} label="Seats used" showPercentage />
+ * <DesignProgressBar value={75} gradient="green" />
+ * ```
+ */
+export function DesignProgressBar({
+  value,
+  max = 100,
+  gradient = "default",
+  label,
+  showPercentage = false,
+  size = "md",
+  className,
+}: DesignProgressBarProps) {
+  const percentage = max > 0 ? Math.min(Math.max((value / max) * 100, 0), 100) : 0;
+  const fillClass = fillClasses.get(gradient) ?? "bg-foreground/60";
+
+  const trackHeight = size === "sm" ? "h-1.5" : size === "lg" ? "h-3" : "h-2";
+
+  return (
+    <div className={cn("w-full", className)}>
+      {(label || showPercentage) && (
+        <div className="flex items-center justify-between mb-2">
+          {label && (
+            <span className="text-xs font-medium text-muted-foreground">
+              {label}
+            </span>
+          )}
+          {showPercentage && (
+            <span className="text-xs font-medium tabular-nums text-foreground">
+              {Math.round(percentage)}%
+            </span>
+          )}
+        </div>
+      )}
+      <div
+        className={cn(
+          "w-full rounded-full bg-black/[0.06] dark:bg-white/[0.06] overflow-hidden",
+          trackHeight
+        )}
+      >
+        <div
+          className={cn(
+            "h-full rounded-full transition-all duration-300 ease-out",
+            fillClass
+          )}
+          style={{ width: `${percentage}%` }}
+        />
+      </div>
+    </div>
+  );
+}

package/src/components/separator.tsx

@@ -0,0 +1,36 @@
+"use client";
+
+import { cn } from "@hexclave/ui";
+
+export type DesignSeparatorProps = {
+  orientation?: "horizontal" | "vertical",
+} & React.HTMLAttributes<HTMLDivElement>;
+
+/**
+ * Thin divider line. Use `orientation="vertical"` inside a flex row to
+ * separate inline groups, or omit for a horizontal rule between sections.
+ *
+ * ```tsx
+ * <DesignSeparator />
+ * <DesignSeparator orientation="vertical" className="h-6" />
+ * ```
+ */
+export function DesignSeparator({
+  orientation = "horizontal",
+  className,
+  ...props
+}: DesignSeparatorProps) {
+  return (
+    <div
+      role="separator"
+      aria-orientation={orientation}
+      className={cn(
+        orientation === "horizontal"
+          ? "h-[1px] w-full bg-black/[0.08] dark:bg-white/[0.06]"
+          : "w-[1px] h-full bg-black/[0.08] dark:bg-white/[0.06]",
+        className
+      )}
+      {...props}
+    />
+  );
+}

package/src/components/skeleton.tsx

@@ -0,0 +1,30 @@
+"use client";
+
+import { cn } from "@hexclave/ui";
+import type React from "react";
+
+export type DesignSkeletonProps = React.HTMLAttributes<HTMLDivElement>;
+
+/**
+ * Animated placeholder block. Use while data is loading — size it via
+ * `className` to match the content it's standing in for.
+ *
+ * ```tsx
+ * <DesignSkeleton className="h-4 w-[200px]" />
+ * <DesignSkeleton className="h-24 w-full rounded-lg" />
+ * ```
+ *
+ * Rule: always show a skeleton during initial load, not a spinner or
+ * "Loading..." text. Skeletons preserve layout and feel faster.
+ */
+export function DesignSkeleton({ className, ...props }: DesignSkeletonProps) {
+  return (
+    <div
+      className={cn(
+        "animate-pulse rounded-md bg-black/[0.06] dark:bg-white/[0.06]",
+        className
+      )}
+      {...props}
+    />
+  );
+}

package/src/components/table.tsx

@@ -0,0 +1,113 @@
+"use client";
+
+import { forwardRefIfNeeded } from "@hexclave/shared/dist/utils/react";
+import { cn } from "@hexclave/ui";
+import React from "react";
+
+/**
+ * Simple static table — header + rows + cells. Use this for small,
+ * read-only lists (< 20 rows, no interaction). For anything that needs
+ * sorting, filtering, pagination, or virtualization, use `DataGrid` +
+ * `useDataSource` instead.
+ *
+ * ```tsx
+ * <DesignTable>
+ *   <DesignTableHeader>
+ *     <DesignTableRow>
+ *       <DesignTableHead>Name</DesignTableHead>
+ *       <DesignTableHead>Email</DesignTableHead>
+ *     </DesignTableRow>
+ *   </DesignTableHeader>
+ *   <DesignTableBody>
+ *     {rows.map(row => (
+ *       <DesignTableRow key={row.id}>
+ *         <DesignTableCell>{row.name}</DesignTableCell>
+ *         <DesignTableCell>{row.email}</DesignTableCell>
+ *       </DesignTableRow>
+ *     ))}
+ *   </DesignTableBody>
+ * </DesignTable>
+ * ```
+ */
+export const DesignTable = forwardRefIfNeeded<
+  HTMLTableElement,
+  React.HTMLAttributes<HTMLTableElement>
+>(({ className, ...props }, ref) => (
+  <div className="relative w-full overflow-auto">
+    <table
+      ref={ref}
+      className={cn("w-full caption-bottom text-sm", className)}
+      {...props}
+    />
+  </div>
+));
+DesignTable.displayName = "DesignTable";
+
+export const DesignTableHeader = forwardRefIfNeeded<
+  HTMLTableSectionElement,
+  React.HTMLAttributes<HTMLTableSectionElement>
+>(({ className, ...props }, ref) => (
+  <thead
+    ref={ref}
+    className={cn("bg-foreground/[0.02] [&_tr]:border-b [&_tr]:border-black/[0.06] dark:[&_tr]:border-white/[0.06]", className)}
+    {...props}
+  />
+));
+DesignTableHeader.displayName = "DesignTableHeader";
+
+export const DesignTableBody = forwardRefIfNeeded<
+  HTMLTableSectionElement,
+  React.HTMLAttributes<HTMLTableSectionElement>
+>(({ className, ...props }, ref) => (
+  <tbody
+    ref={ref}
+    className={cn("[&_tr:last-child]:border-0", className)}
+    {...props}
+  />
+));
+DesignTableBody.displayName = "DesignTableBody";
+
+export const DesignTableRow = forwardRefIfNeeded<
+  HTMLTableRowElement,
+  React.HTMLAttributes<HTMLTableRowElement>
+>(({ className, ...props }, ref) => (
+  <tr
+    ref={ref}
+    className={cn(
+      "border-b border-black/[0.06] dark:border-white/[0.06] transition-colors duration-150 hover:transition-none hover:bg-foreground/[0.04] data-[state=selected]:bg-foreground/[0.06]",
+      className
+    )}
+    {...props}
+  />
+));
+DesignTableRow.displayName = "DesignTableRow";
+
+export const DesignTableHead = forwardRefIfNeeded<
+  HTMLTableCellElement,
+  React.ThHTMLAttributes<HTMLTableCellElement>
+>(({ className, ...props }, ref) => (
+  <th
+    ref={ref}
+    className={cn(
+      "h-10 px-4 text-left align-middle font-medium text-muted-foreground [&:has([role=checkbox])]:pr-0 [&>[role=checkbox]]:translate-y-[2px]",
+      className
+    )}
+    {...props}
+  />
+));
+DesignTableHead.displayName = "DesignTableHead";
+
+export const DesignTableCell = forwardRefIfNeeded<
+  HTMLTableCellElement,
+  React.TdHTMLAttributes<HTMLTableCellElement>
+>(({ className, ...props }, ref) => (
+  <td
+    ref={ref}
+    className={cn(
+      "p-4 align-middle [&:has([role=checkbox])]:pr-0 [&>[role=checkbox]]:translate-y-[2px]",
+      className
+    )}
+    {...props}
+  />
+));
+DesignTableCell.displayName = "DesignTableCell";