@hilum/ui 3.8.5 → 3.10.0

package/src/components/stat-card.tsx

@@ -1,16 +1,39 @@
 import * as React from "react";
 import { TrendingUp, TrendingDown, Minus, Plus } from "lucide-react";
 import { cn } from "../lib/utils";
+import { Skeleton } from "./skeleton";
+
+type StatTrendTone = "positive" | "negative" | "neutral";
+
+interface StatCardTrend {
+  value: string;
+  direction: "up" | "down" | "neutral";
+  /**
+   * Whether the change is good or bad. Defaults to up → positive,
+   * down → negative. Set explicitly for metrics where "up" is bad
+   * (refunds, churn, response time).
+   */
+  tone?: StatTrendTone;
+  /** Screen-reader / caption context, e.g. "vs last 30 days". */
+  label?: string;
+}
 
 interface StatCardProps {
   label?: string;
   title?: string;
-  value?: string | number;
-  variant?: "default" | "responsive";
-  trend?: {
-    value: string;
-    direction: "up" | "down" | "neutral";
-  };
+  value?: React.ReactNode;
+  /**
+   * `default` — bordered card. `responsive` — flat on mobile, card from `sm`.
+   * `plain` — no surface; use inside an existing Card or a divided StatGrid.
+   */
+  variant?: "default" | "responsive" | "plain";
+  trend?: StatCardTrend;
+  /** Secondary line under the value (e.g. "32 orders", "Last 30 days"). */
+  description?: React.ReactNode;
+  /** Render skeletons for the value and trend. */
+  loading?: boolean;
+  /** Make the whole card a link (e.g. drill into the orders list). */
+  href?: string;
   icon?: React.ReactNode;
   children?: React.ReactNode;
   actionButtons?: React.ReactNode;
@@ -22,6 +45,11 @@ interface StatCardProps {
 
 interface StatCardGridProps {
   children: React.ReactNode;
+  /**
+   * Column count at the widest breakpoint. Always 2 columns on mobile (1 for
+   * `columns={1}`), stepping up through `sm`/`lg`. Default: 6-slot dashboard grid.
+   */
+  columns?: 1 | 2 | 3 | 4 | 5 | 6;
   maxSlots?: number;
   onAddCard?: () => void;
   className?: string;
@@ -40,6 +68,9 @@ function StatCard({
   value,
   variant = "default",
   trend,
+  description,
+  loading = false,
+  href,
   icon,
   children,
   actionButtons,
@@ -49,11 +80,10 @@ function StatCard({
   valueClassName,
 }: StatCardProps) {
   const displayLabel = title ?? label;
-  const trendColor = {
-    up: "text-muted-foreground bg-brand-secondary/30 rounded-full px-2 py-0.5 w-fit",
-    down: "text-destructive",
-    neutral: "text-muted-foreground",
-  };
+  const trendTone: StatTrendTone | undefined = trend
+    ? (trend.tone ??
+      (trend.direction === "up" ? "positive" : trend.direction === "down" ? "negative" : "neutral"))
+    : undefined;
 
   const TrendIcon = {
     up: TrendingUp,
@@ -61,19 +91,14 @@ function StatCard({
     neutral: Minus,
   };
   const surfaceClass =
-    variant === "responsive"
-      ? "min-w-0 border-border bg-transparent p-4 sm:rounded-xl sm:border sm:bg-card sm:p-5 sm:shadow-natural"
-      : "min-w-0 rounded-xl border border-border bg-card p-4 shadow-natural sm:p-5";
+    variant === "plain"
+      ? "min-w-0 p-4 sm:p-5"
+      : variant === "responsive"
+        ? "min-w-0 border-border bg-transparent p-4 sm:rounded-xl sm:border sm:bg-card sm:p-5 sm:shadow-natural"
+        : "min-w-0 rounded-xl border border-border bg-card p-4 shadow-natural sm:p-5";
 
-  return (
-    <div
-      className={cn(
-        surfaceClass,
-        containerClassName,
-        className,
-      )}
-      data-slot="stat-card"
-    >
+  const body = (
+    <>
       <div className="flex items-start justify-between gap-3">
         {displayLabel && (
           <p className={cn("label min-w-0 text-muted-foreground", titleClassName)}>
@@ -87,23 +112,65 @@ function StatCard({
         )}
         {actionButtons && <div className="flex shrink-0 items-center gap-2">{actionButtons}</div>}
       </div>
-      {value !== undefined ? (
-        <p className={cn("heading-xl mt-2 tabular-nums text-foreground", valueClassName)}>
+      {loading ? (
+        <Skeleton className="mt-3 h-7 w-24" />
+      ) : value !== undefined ? (
+        <p className={cn("heading-xl mt-2 truncate tabular-nums text-foreground", valueClassName)}>
           {value}
         </p>
       ) : children ? (
         <div className="mt-2">{children}</div>
       ) : null}
-      {trend &&
-        (() => {
-          const Icon = TrendIcon[trend.direction];
-          return (
-            <div className={cn("mt-2 flex items-center gap-1", trendColor[trend.direction])}>
-              <Icon size={12} />
-              <span className="caption tabular-nums font-medium">{trend.value}</span>
-            </div>
-          );
-        })()}
+      {(description || (trend && !loading)) && (
+        <div className="mt-2 flex min-w-0 flex-wrap items-center gap-x-2 gap-y-1">
+          {trend &&
+            !loading &&
+            (() => {
+              const Icon = TrendIcon[trend.direction];
+              return (
+                <span
+                  data-tone={trendTone}
+                  className={cn(
+                    "inline-flex w-fit items-center gap-1 rounded-full px-2 py-0.5",
+                    trendTone === "positive" && "bg-success/40 text-foreground",
+                    trendTone === "negative" && "bg-destructive/10 text-destructive",
+                    trendTone === "neutral" && "bg-muted text-muted-foreground",
+                  )}
+                >
+                  <Icon size={12} aria-hidden="true" />
+                  <span className="caption tabular-nums font-medium">{trend.value}</span>
+                  {trend.label && <span className="sr-only">{trend.label}</span>}
+                </span>
+              );
+            })()}
+          {description && (
+            <span className="caption min-w-0 truncate text-muted-foreground">{description}</span>
+          )}
+        </div>
+      )}
+    </>
+  );
+
+  const classes = cn(surfaceClass, containerClassName, className);
+
+  if (href) {
+    return (
+      <a
+        href={href}
+        className={cn(
+          classes,
+          "block transition-colors hover:bg-muted focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+        )}
+        data-slot="stat-card"
+      >
+        {body}
+      </a>
+    );
+  }
+
+  return (
+    <div className={classes} data-slot="stat-card" aria-busy={loading || undefined}>
+      {body}
     </div>
   );
 }
@@ -117,7 +184,7 @@ function StatCardSlot({ onAddCard, className, label = "Add card" }: StatCardSlot
       className={cn(
         "flex min-h-28 w-full min-w-0 items-center justify-center rounded-xl border border-dashed border-border bg-card p-4 text-muted-foreground shadow-natural",
         "transition-[background-color,border-color,color,scale] duration-150 hover:border-ground-300 hover:bg-muted hover:text-foreground active:scale-[0.96]",
-        "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-brand-primary/30",
+        "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
         className,
       )}
       onClick={onAddCard}
@@ -132,8 +199,18 @@ function StatCardSlot({ onAddCard, className, label = "Add card" }: StatCardSlot
 
 StatCardSlot.displayName = "StatCardSlot";
 
+const GRID_COLUMNS: Record<NonNullable<StatCardGridProps["columns"]>, string> = {
+  1: "grid-cols-1",
+  2: "grid-cols-2",
+  3: "grid-cols-2 lg:grid-cols-3",
+  4: "grid-cols-2 lg:grid-cols-4",
+  5: "grid-cols-2 sm:grid-cols-3 lg:grid-cols-5",
+  6: "grid-cols-2 sm:grid-cols-3 lg:grid-cols-4 xl:grid-cols-6",
+};
+
 function StatCardGrid({
   children,
+  columns = 6,
   maxSlots = 6,
   onAddCard,
   className,
@@ -145,7 +222,8 @@ function StatCardGrid({
   return (
     <div
       className={cn(
-        "grid min-w-0 grid-cols-2 items-stretch gap-2 sm:grid-cols-3 lg:grid-cols-4 xl:grid-cols-6",
+        "grid min-w-0 items-stretch gap-2 sm:gap-3 [&>*>[data-slot=stat-card]]:h-full",
+        GRID_COLUMNS[columns],
         className,
       )}
       data-slot="stat-card-grid"
@@ -166,11 +244,17 @@ function StatCardGrid({
 
 StatCardGrid.displayName = "StatCardGrid";
 
+/** Alias — `StatGrid` reads better next to `StatCard` in new code. */
+const StatGrid = StatCardGrid;
+
 export {
   StatCard,
   StatCardGrid,
   StatCardSlot,
+  StatGrid,
   type StatCardProps,
+  type StatCardTrend,
+  type StatTrendTone,
   type StatCardGridProps,
   type StatCardSlotProps,
 };

package/src/components/status-badge.tsx

@@ -1,75 +1,131 @@
 "use client";
 
 import * as React from "react";
-import { Badge } from "./badge";
+import { Badge, STATUS_TONE_BADGE, type StatusTone } from "./badge";
 import { cn } from "../lib/utils";
 
 type StatusBadgeVariant = NonNullable<React.ComponentProps<typeof Badge>["variant"]>;
 type StatusBadgeIcon = React.ComponentType<{ className?: string }>;
 
-interface StatusBadgeProps extends Omit<
-  React.ComponentProps<typeof Badge>,
-  "children" | "variant"
-> {
-  status?: string | null;
-  label?: React.ReactNode;
-  variant?: StatusBadgeVariant;
-  variantMap?: Record<string, StatusBadgeVariant>;
-  labelMap?: Record<string, React.ReactNode>;
-  icon?: StatusBadgeIcon;
-  iconMap?: Record<string, StatusBadgeIcon>;
-  iconClassName?: string;
-  showDot?: boolean;
-  dotClassName?: string;
-}
-
-const DEFAULT_STATUS_VARIANT: Record<string, StatusBadgeVariant> = {
+const DEFAULT_STATUS_TONE: Record<string, StatusTone> = {
+  // success
   active: "success",
   approved: "success",
+  authorized: "success",
+  captured: "success",
   complete: "success",
   completed: "success",
   confirmed: "success",
+  connected: "success",
   delivered: "success",
   enabled: "success",
+  fulfilled: "success",
   healthy: "success",
+  live: "success",
   optimized: "success",
   paid: "success",
   published: "success",
   resolved: "success",
+  succeeded: "success",
+  success: "success",
   translated: "success",
   verified: "success",
-
+  // info
+  in_progress: "info",
+  in_transit: "info",
+  info: "info",
+  invited: "info",
+  new: "info",
+  open: "info",
+  out_for_delivery: "info",
+  processing: "info",
+  scheduled: "info",
+  shipped: "info",
+  trial: "info",
+  trialing: "info",
+  // attention
+  action_required: "attention",
+  attention: "attention",
+  flagged: "attention",
+  held_for_review: "attention",
+  on_hold: "attention",
+  partially_fulfilled: "attention",
+  partially_paid: "attention",
+  requires_action: "attention",
+  return_requested: "attention",
+  unfulfilled: "attention",
+  // warning
   degraded: "warning",
-  flagged: "warning",
-  held_for_review: "warning",
+  expiring: "warning",
+  overdue: "warning",
+  past_due: "warning",
   pending: "warning",
-  processing: "warning",
   retrying: "warning",
-  scheduled: "warning",
-  trial: "warning",
   warning: "warning",
-
-  archived: "secondary",
-  disabled: "secondary",
-  draft: "secondary",
-  inactive: "secondary",
-  missing: "secondary",
-  neutral: "secondary",
-  skipped: "secondary",
-
-  blocked: "destructive",
-  cancelled: "destructive",
-  critical: "destructive",
-  dead_letter: "destructive",
-  deleted: "destructive",
-  error: "destructive",
-  failed: "destructive",
-  rejected: "destructive",
-  suspended: "destructive",
-  unpaid: "destructive",
-  outdated: "destructive",
+  // critical
+  blocked: "critical",
+  canceled: "critical",
+  cancelled: "critical",
+  chargeback: "critical",
+  critical: "critical",
+  dead_letter: "critical",
+  declined: "critical",
+  deleted: "critical",
+  disputed: "critical",
+  error: "critical",
+  expired: "critical",
+  failed: "critical",
+  outdated: "critical",
+  rejected: "critical",
+  suspended: "critical",
+  unpaid: "critical",
+  voided: "critical",
+  // neutral
+  archived: "neutral",
+  closed: "neutral",
+  disabled: "neutral",
+  draft: "neutral",
+  inactive: "neutral",
+  missing: "neutral",
+  neutral: "neutral",
+  partially_refunded: "neutral",
+  refunded: "neutral",
+  restocked: "neutral",
+  returned: "neutral",
+  skipped: "neutral",
+  unknown: "neutral",
 };
 
+interface StatusBadgeProps extends Omit<
+  React.ComponentProps<typeof Badge>,
+  "children" | "variant"
+> {
+  status?: string | null;
+  label?: React.ReactNode;
+  /**
+   * Semantic tone. Wins over `variant` and the built-in status map. Prefer
+   * `tone` / `toneMap` over raw `variant` so colours stay consistent.
+   */
+  tone?: StatusTone;
+  /** Per-app status → tone overrides, merged over the built-in convention. */
+  toneMap?: Record<string, StatusTone>;
+  variant?: StatusBadgeVariant;
+  variantMap?: Record<string, StatusBadgeVariant>;
+  labelMap?: Record<string, React.ReactNode>;
+  icon?: StatusBadgeIcon;
+  iconMap?: Record<string, StatusBadgeIcon>;
+  iconClassName?: string;
+  showDot?: boolean;
+  dotClassName?: string;
+}
+
+const DEFAULT_STATUS_VARIANT: Record<string, StatusBadgeVariant> = Object.fromEntries(
+  Object.entries(DEFAULT_STATUS_TONE).map(([status, tone]) => [
+    status,
+    STATUS_TONE_BADGE[tone].variant,
+  ]),
+);
+
 const DEFAULT_DOT_CLASS: Record<StatusBadgeVariant, string> = {
   default: "bg-background",
   solid: "bg-background",
@@ -82,6 +138,15 @@ const DEFAULT_DOT_CLASS: Record<StatusBadgeVariant, string> = {
   destructive: "bg-destructive",
 };
 
+const TONE_DOT_CLASS: Record<StatusTone, string> = {
+  success: "bg-emerald-500",
+  info: "bg-blue-500",
+  attention: "bg-orange-500",
+  warning: "bg-amber-500",
+  critical: "bg-destructive",
+  neutral: "bg-muted-foreground",
+};
+
 function normalizeStatus(status?: string | null) {
   return String(status ?? "unknown")
     .trim()
@@ -100,6 +165,16 @@ function statusLabel(status?: string | null) {
     .join(" ");
 }
 
+/**
+ * Resolve a status string to its semantic tone. Unknown statuses resolve to
+ * `neutral`. Status strings are normalised ("Partially Fulfilled",
+ * "partially-fulfilled" and "PARTIALLY_FULFILLED" are equivalent).
+ */
+function statusToneFor(status?: string | null, toneMap?: Record<string, StatusTone>): StatusTone {
+  const normalized = normalizeStatus(status);
+  return toneMap?.[normalized] ?? DEFAULT_STATUS_TONE[normalized] ?? "neutral";
+}
+
 function statusBadgeVariantFor(
   status?: string | null,
   variantMap?: Record<string, StatusBadgeVariant>,
@@ -111,6 +186,8 @@ function statusBadgeVariantFor(
 function StatusBadge({
   status,
   label,
+  tone,
+  toneMap,
   variant,
   variantMap,
   labelMap,
@@ -123,13 +200,25 @@ function StatusBadge({
   ...props
 }: StatusBadgeProps) {
   const normalized = normalizeStatus(status);
-  const resolvedVariant = variant ?? statusBadgeVariantFor(normalized, variantMap);
+  // Precedence: tone > toneMap > variant > variantMap > built-in tone map.
+  const resolvedTone: StatusTone | undefined =
+    tone ??
+    toneMap?.[normalized] ??
+    (variant === undefined && variantMap?.[normalized] === undefined
+      ? DEFAULT_STATUS_TONE[normalized]
+      : undefined);
+  const toneBadge = resolvedTone ? STATUS_TONE_BADGE[resolvedTone] : undefined;
+  const resolvedVariant =
+    toneBadge?.variant ?? variant ?? statusBadgeVariantFor(normalized, variantMap);
+  const resolvedColor = toneBadge?.color ?? props.color;
   const resolvedLabel = label ?? labelMap?.[normalized] ?? statusLabel(normalized);
   const Icon = icon ?? iconMap?.[normalized];
 
   return (
     <Badge
       variant={resolvedVariant}
+      {...(resolvedColor ? { color: resolvedColor } : {})}
+      data-tone={resolvedTone}
       className={cn("max-w-full whitespace-nowrap", (showDot || Icon) && "pl-2", className)}
       {...props}
     >
@@ -137,7 +226,7 @@ function StatusBadge({
         <span
           className={cn(
             "size-1.5 shrink-0 rounded-full",
-            DEFAULT_DOT_CLASS[resolvedVariant],
+            resolvedTone ? TONE_DOT_CLASS[resolvedTone] : DEFAULT_DOT_CLASS[resolvedVariant],
             dotClassName,
           )}
           aria-hidden="true"
@@ -151,5 +240,11 @@ function StatusBadge({
 
 StatusBadge.displayName = "StatusBadge";
 
-export { StatusBadge, statusBadgeVariantFor, statusLabel };
+export {
+  StatusBadge,
+  statusBadgeVariantFor,
+  statusLabel,
+  statusToneFor,
+  DEFAULT_STATUS_TONE,
+};
 export type { StatusBadgeProps, StatusBadgeVariant };

package/src/components/status-tile.tsx

@@ -1,6 +1,7 @@
 import * as React from "react";
 import { cn } from "../lib/utils";
 import { StatusBadge, type StatusBadgeVariant } from "./status-badge";
+import type { StatusTone } from "./badge";
 
 interface StatusTileGridProps extends React.HTMLAttributes<HTMLDivElement> {
   columns?: 2 | 3 | 4;
@@ -13,6 +14,10 @@ interface StatusTileProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "ti
   meta?: React.ReactNode;
   icon?: React.ComponentType<{ className?: string }>;
   labelMap?: Record<string, React.ReactNode>;
+  /** Semantic tone override for the badge. */
+  tone?: StatusTone;
+  /** Per-app status → tone overrides. */
+  toneMap?: Record<string, StatusTone>;
   variantMap?: Record<string, StatusBadgeVariant>;
   iconMap?: Record<string, React.ComponentType<{ className?: string }>>;
 }
@@ -44,6 +49,8 @@ function StatusTile({
   meta,
   icon: Icon,
   labelMap,
+  tone,
+  toneMap,
   variantMap,
   iconMap,
   className,
@@ -66,6 +73,8 @@ function StatusTile({
         <StatusBadge
           status={status}
           {...(labelMap ? { labelMap } : {})}
+          {...(tone ? { tone } : {})}
+          {...(toneMap ? { toneMap } : {})}
           {...(variantMap ? { variantMap } : {})}
           {...(iconMap ? { iconMap } : {})}
           className="shrink-0"

package/src/components/switch.tsx

@@ -163,6 +163,7 @@ const Switch = forwardRef<HTMLDivElement, SwitchProps>(
     }, [checked, setChecked, motionX, thumbTransition]);
 
     return (
+      // eslint-disable-next-line jsx-a11y/click-events-have-key-events, jsx-a11y/no-static-element-interactions -- pointer/drag convenience on the row; the switch button inside is the keyboard-accessible control
       <div
         ref={ref}
         className={cn(
@@ -196,18 +197,18 @@ const Switch = forwardRef<HTMLDivElement, SwitchProps>(
           className={cn(
             "relative shrink-0 rounded-full outline-none cursor-pointer",
             "transition-colors duration-80",
-            "focus-visible:ring-1 focus-visible:ring-[#6B97FF] focus-visible:ring-offset-2 focus-visible:ring-offset-background",
+            "focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background",
           )}
           style={{
             width: TRACK_WIDTH,
             height: TRACK_HEIGHT,
             backgroundColor: checked
               ? hovered
-                ? "#5C89F2"
-                : "#6B97FF"
+                ? "color-mix(in oklab, var(--primary), var(--foreground) 12%)"
+                : "var(--primary)"
               : hovered
-                ? "color-mix(in oklab, var(--accent), rgb(var(--overlay)) 10%)"
-                : "var(--accent)",
+                ? "color-mix(in oklab, var(--foreground) 22%, transparent)"
+                : "color-mix(in oklab, var(--foreground) 15%, transparent)",
           }}
           onClick={(e) => e.stopPropagation()}
         >

package/src/components/tabs-subtle.tsx

@@ -19,6 +19,7 @@ import { spring } from "../lib/springs";
 import { fontWeights } from "../lib/font-weight";
 import { useShape } from "../lib/shape-context";
 import { useProximityHover } from "../hooks/use-proximity-hover";
+import { scrollStripItemIntoView, useHorizontalOverflowMask } from "../lib/scroll-fade";
 
 interface TabsSubtleContextValue {
   registerTab: (index: number, element: HTMLElement | null) => void;
@@ -55,11 +56,16 @@ const TabsSubtle = forwardRef<HTMLDivElement, TabsSubtleProps>(
       idPrefix: idPrefixProp,
       activeLabel = false,
       className,
+      style,
       ...props
     },
     ref,
   ) => {
     const containerRef = useRef<HTMLDivElement>(null);
+    const maskStyle = useHorizontalOverflowMask(containerRef);
+    useEffect(() => {
+      scrollStripItemIntoView(containerRef.current, selectedIndex);
+    }, [selectedIndex]);
     const isMouseInside = useRef(false);
     const generatedId = useId();
     const shape = useShape();
@@ -127,6 +133,7 @@ const TabsSubtle = forwardRef<HTMLDivElement, TabsSubtleProps>(
       <TabsSubtleContext.Provider
         value={{ registerTab, hoveredIndex, selectedIndex, onSelect, idPrefix, activeLabel }}
       >
+        {/* eslint-disable-next-line jsx-a11y/interactive-supports-focus -- roving tabindex per WAI-ARIA APG: the tabs are focusable, the tablist container is not */}
         <div
           ref={(node) => {
             (containerRef as React.MutableRefObject<HTMLDivElement | null>).current = node;
@@ -173,9 +180,10 @@ const TabsSubtle = forwardRef<HTMLDivElement, TabsSubtleProps>(
             }
           }}
           className={cn(
-            "relative flex items-center gap-0.5 select-none overflow-x-auto max-w-full scrollbar-hide -my-1 py-1",
+            "relative flex items-center gap-0.5 select-none overflow-x-auto max-w-full overscroll-x-contain [scrollbar-width:none] [&::-webkit-scrollbar]:hidden -my-1 py-1 [&>[role=tab]]:shrink-0",
             className,
           )}
+          style={maskStyle ? { ...maskStyle, ...style } : style}
           role="tablist"
           {...props}
         >
@@ -242,7 +250,7 @@ const TabsSubtle = forwardRef<HTMLDivElement, TabsSubtleProps>(
             {focusRect && (
               <motion.div
                 className={cn(
-                  "absolute pointer-events-none z-20 border border-[#6B97FF]",
+                  "absolute pointer-events-none z-20 border-2 border-ring",
                   shape.focusRing,
                 )}
                 initial={false}