@etus/ui 0.1.0

package/src/components/data-display/SingleStat/SingleStat.test.tsx

@@ -0,0 +1,223 @@
+import { render, screen } from "@testing-library/react"
+import { axe, toHaveNoViolations } from "jest-axe"
+import { describe, expect, it } from "vitest"
+
+import { SingleStat } from "./SingleStat"
+
+expect.extend(toHaveNoViolations)
+
+describe("SingleStat", () => {
+  describe("Rendering", () => {
+    it("renders value and label in default variant", () => {
+      render(<SingleStat label="Users" value={100} />)
+
+      expect(screen.getByText("100")).toBeInTheDocument()
+      expect(screen.getByText("Users")).toBeInTheDocument()
+    })
+
+    it("renders without label in compact variant", () => {
+      render(<SingleStat label="Users" value={100} variant="compact" />)
+
+      expect(screen.getByText("100")).toBeInTheDocument()
+      expect(screen.queryByText("Users")).not.toBeInTheDocument()
+    })
+
+    it("renders label and value side by side in inline variant", () => {
+      render(<SingleStat label="Users" value={100} variant="inline" />)
+
+      expect(screen.getByText("100")).toBeInTheDocument()
+      expect(screen.getByText("Users")).toBeInTheDocument()
+    })
+
+    it("renders string values correctly", () => {
+      render(<SingleStat label="Uptime" value="99.9%" />)
+
+      expect(screen.getByText("99.9%")).toBeInTheDocument()
+    })
+  })
+
+  describe("Number Formatting", () => {
+    it("formats numbers with locale separators", () => {
+      render(<SingleStat label="Total" value={1234567} />)
+
+      expect(screen.getByText("1,234,567")).toBeInTheDocument()
+    })
+
+    it("handles zero value", () => {
+      render(<SingleStat label="Count" value={0} />)
+
+      expect(screen.getByText("0")).toBeInTheDocument()
+    })
+
+    it("handles negative numbers", () => {
+      render(<SingleStat label="Change" value={-500} />)
+
+      expect(screen.getByText("-500")).toBeInTheDocument()
+    })
+  })
+
+  describe("Prefix and Suffix", () => {
+    it("renders with prefix", () => {
+      const { container } = render(<SingleStat label="Revenue" prefix="$" value={100} />)
+
+      expect(screen.getByText("$")).toBeInTheDocument()
+      expect(screen.getByText("100")).toBeInTheDocument()
+      // Check that the value container includes the prefix
+      const valueContainer = container.querySelector('[data-slot="single-stat-value"]')
+      expect(valueContainer?.textContent).toBe("$100")
+    })
+
+    it("renders with suffix", () => {
+      const { container } = render(<SingleStat label="Progress" suffix="%" value={50} />)
+
+      expect(screen.getByText("%")).toBeInTheDocument()
+      expect(screen.getByText("50")).toBeInTheDocument()
+      // Check that the value container includes the suffix
+      const valueContainer = container.querySelector('[data-slot="single-stat-value"]')
+      expect(valueContainer?.textContent).toBe("50%")
+    })
+
+    it("renders with both prefix and suffix", () => {
+      const { container } = render(<SingleStat label="Amount" prefix="$" suffix="K" value={50} />)
+
+      const valueContainer = container.querySelector('[data-slot="single-stat-value"]')
+      expect(valueContainer?.textContent).toBe("$50K")
+    })
+  })
+
+  describe("Sizes", () => {
+    it.each([
+      ["xs", "text-lg"],
+      ["sm", "text-xl"],
+      ["md", "text-2xl"],
+      ["lg", "text-4xl"],
+      ["xl", "text-6xl"],
+    ] as const)("applies %s size class", (size, expectedClass) => {
+      const { container } = render(
+        <SingleStat label="Test" size={size} value={1} />
+      )
+
+      const valueElement = container.querySelector('[data-slot="single-stat-value"]')
+      expect(valueElement).toHaveClass(expectedClass)
+    })
+  })
+
+  describe("Loading State", () => {
+    it("renders skeleton in default variant when loading", () => {
+      const { container } = render(
+        <SingleStat loading label="Users" value={100} />
+      )
+
+      const skeletons = container.querySelectorAll('[data-slot="skeleton-loader"]')
+      expect(skeletons.length).toBeGreaterThanOrEqual(1)
+    })
+
+    it("renders skeleton in inline variant when loading", () => {
+      const { container } = render(
+        <SingleStat loading label="Users" value={100} variant="inline" />
+      )
+
+      const skeletons = container.querySelectorAll('[data-slot="skeleton-loader"]')
+      expect(skeletons.length).toBeGreaterThanOrEqual(1)
+    })
+
+    it("renders skeleton in compact variant when loading", () => {
+      const { container } = render(
+        <SingleStat loading value={100} variant="compact" />
+      )
+
+      // In compact loading, the Skeleton is wrapped with data-slot="single-stat"
+      const singleStat = container.querySelector('[data-slot="single-stat"]')
+      expect(singleStat).toBeInTheDocument()
+      expect(singleStat).toHaveClass("animate-pulse")
+    })
+
+    it("does not show value when loading", () => {
+      render(<SingleStat loading label="Users" value={100} />)
+
+      expect(screen.queryByText("100")).not.toBeInTheDocument()
+    })
+  })
+
+  describe("Data Attributes", () => {
+    it("has data-slot attribute on root", () => {
+      const { container } = render(<SingleStat label="Users" value={100} />)
+
+      const root = container.querySelector('[data-slot="single-stat"]')
+      expect(root).toBeInTheDocument()
+    })
+
+    it("has data-slot on value element in default variant", () => {
+      const { container } = render(<SingleStat label="Users" value={100} />)
+
+      const value = container.querySelector('[data-slot="single-stat-value"]')
+      expect(value).toBeInTheDocument()
+    })
+
+    it("has data-slot on label element in default variant", () => {
+      const { container } = render(<SingleStat label="Users" value={100} />)
+
+      const label = container.querySelector('[data-slot="single-stat-label"]')
+      expect(label).toBeInTheDocument()
+    })
+  })
+
+  describe("Custom className", () => {
+    it("applies custom className to root", () => {
+      const { container } = render(
+        <SingleStat className="custom-class" label="Users" value={100} />
+      )
+
+      const root = container.querySelector('[data-slot="single-stat"]')
+      expect(root).toHaveClass("custom-class")
+    })
+  })
+
+  describe("Accessibility", () => {
+    it("has no accessibility violations in default variant", async () => {
+      const { container } = render(
+        <SingleStat label="Users" value={100} />
+      )
+
+      const results = await axe(container)
+      expect(results).toHaveNoViolations()
+    })
+
+    it("has no accessibility violations in inline variant", async () => {
+      const { container } = render(
+        <SingleStat label="Users" value={100} variant="inline" />
+      )
+
+      const results = await axe(container)
+      expect(results).toHaveNoViolations()
+    })
+
+    it("has no accessibility violations in compact variant", async () => {
+      const { container } = render(
+        <SingleStat label="Users" value={100} variant="compact" />
+      )
+
+      const results = await axe(container)
+      expect(results).toHaveNoViolations()
+    })
+
+    it("has role group with aria-label in default variant", () => {
+      const { container } = render(
+        <SingleStat label="Users" value={100} />
+      )
+
+      const root = container.querySelector('[data-slot="single-stat"]')
+      expect(root).toHaveAttribute("role", "group")
+      expect(root).toHaveAttribute("aria-label", "Users")
+    })
+
+    it("has accessible label for compact variant with aria-label", () => {
+      render(
+        <SingleStat label="Active Users" prefix="+" value={100} variant="compact" />
+      )
+
+      const stat = screen.getByRole("text")
+      expect(stat).toHaveAttribute("aria-label", "Active Users: +100")
+    })
+  })
+})

package/src/components/data-display/SingleStat/SingleStat.tsx

@@ -0,0 +1,251 @@
+import type { SingleStatProps, SingleStatSize } from "./SingleStat.types"
+
+import { useEffect, useRef, useState } from "react"
+
+import { cn } from "../../../lib/utils"
+import { SkeletonLoader } from "../../primitives/SkeletonLoader"
+
+/**
+ * Size configuration for value typography
+ */
+const sizeClasses: Record<SingleStatSize, string> = {
+  lg: "text-4xl",
+  md: "text-2xl",
+  sm: "text-xl",
+  xl: "text-6xl",
+  xs: "text-lg",
+}
+
+/**
+ * Skeleton height configuration by size
+ */
+const skeletonSizes: Record<SingleStatSize, string> = {
+  lg: "h-10",
+  md: "h-8",
+  sm: "h-7",
+  xl: "h-14",
+  xs: "h-6",
+}
+
+/**
+ * Hook for animated count-up effect
+ */
+function useAnimatedCounter(
+  targetValue: number,
+  duration: number,
+  enabled: boolean
+): number {
+  // When not enabled, just return the target value directly
+  const [count, setCount] = useState(0)
+  const animationFrameRef = useRef<number>(0)
+  const startTimeRef = useRef<null | number>(null)
+
+  useEffect(() => {
+    if (!enabled) {
+      return
+    }
+
+    startTimeRef.current = null
+
+    const animate = (timestamp: number) => {
+      startTimeRef.current ??= timestamp
+      const progress = Math.min((timestamp - startTimeRef.current) / duration, 1)
+
+      // Use easeOutQuad for smoother animation
+      const eased = 1 - (1 - progress) * (1 - progress)
+      setCount(Math.floor(eased * targetValue))
+
+      if (progress < 1) {
+        animationFrameRef.current = requestAnimationFrame(animate)
+      }
+    }
+
+    animationFrameRef.current = requestAnimationFrame(animate)
+
+    return () => {
+      if (animationFrameRef.current) {
+        cancelAnimationFrame(animationFrameRef.current)
+      }
+    }
+  }, [targetValue, duration, enabled])
+
+  // Return target value when not animating, otherwise return animated count
+  return enabled ? count : targetValue
+}
+
+/**
+ * SingleStat - Minimalist single metric display
+ *
+ * A compact component for displaying a single highlighted metric.
+ * Simpler than KPICard, focused only on value and label.
+ * Ideal for inline indicators or space-constrained layouts.
+ *
+ * @example
+ * ```tsx
+ * <SingleStat value={1234} label="Total Users" />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <SingleStat
+ *   value={45231}
+ *   prefix="$"
+ *   label="Revenue"
+ *   size="lg"
+ * />
+ * ```
+ */
+function SingleStat({
+  value,
+  label,
+  variant = "default",
+  size = "md",
+  prefix,
+  suffix,
+  animated = false,
+  animationDuration = 1000,
+  loading = false,
+  className,
+  ...props
+}: SingleStatProps) {
+  // Use animated counter for numeric values
+  const numericValue = typeof value === "number" ? value : Number.NaN
+  const isNumeric = !Number.isNaN(numericValue)
+  const animatedValue = useAnimatedCounter(
+    isNumeric ? numericValue : 0,
+    animationDuration,
+    animated && isNumeric
+  )
+
+  // Format the display value
+  const displayValue = animated && isNumeric
+    ? animatedValue.toLocaleString()
+    : typeof value === "number"
+      ? value.toLocaleString()
+      : value
+
+  // Loading state
+  if (loading) {
+    if (variant === "compact") {
+      return (
+        <SkeletonLoader
+          className={cn(skeletonSizes[size], "w-24", className)}
+          data-slot="single-stat"
+          {...props}
+        />
+      )
+    }
+
+    if (variant === "inline") {
+      return (
+        <div
+          className={cn("flex items-baseline gap-2", className)}
+          data-slot="single-stat"
+          {...props}
+        >
+          <SkeletonLoader className={cn(skeletonSizes[size], "w-20")} />
+          {label && <SkeletonLoader className="h-4 w-16" />}
+        </div>
+      )
+    }
+
+    return (
+      <div
+        className={cn("space-y-1", className)}
+        data-slot="single-stat"
+        {...props}
+      >
+        {label && <SkeletonLoader className="h-4 w-20" />}
+        <SkeletonLoader className={cn(skeletonSizes[size], "w-24")} />
+      </div>
+    )
+  }
+
+  // Compact variant: value only
+  if (variant === "compact") {
+    const ariaValue = typeof displayValue === "string" ? displayValue : String(displayValue)
+    return (
+      <span
+        className={cn(
+          "font-bold tabular-nums text-foreground",
+          sizeClasses[size],
+          className
+        )}
+        aria-label={label ? `${label}: ${prefix ?? ""}${ariaValue}${suffix ?? ""}` : undefined}
+        data-slot="single-stat"
+        role="text"
+        {...props}
+      >
+        {prefix && <span aria-hidden="true">{prefix}</span>}
+        {displayValue}
+        {suffix && <span aria-hidden="true">{suffix}</span>}
+      </span>
+    )
+  }
+
+  // Inline variant: label and value side by side
+  if (variant === "inline") {
+    return (
+      <div
+        aria-label={label}
+        className={cn("flex items-baseline gap-2", className)}
+        data-slot="single-stat"
+        role="group"
+        {...props}
+      >
+        <span
+          className={cn(
+            "font-bold tabular-nums text-foreground",
+            sizeClasses[size]
+          )}
+          data-slot="single-stat-value"
+        >
+          {prefix && <span aria-hidden="true">{prefix}</span>}
+          {displayValue}
+          {suffix && <span aria-hidden="true">{suffix}</span>}
+        </span>
+        {label && (
+          <span
+            className="text-sm font-medium text-muted-foreground"
+            data-slot="single-stat-label"
+          >
+            {label}
+          </span>
+        )}
+      </div>
+    )
+  }
+
+  // Default variant: label above, value below
+  return (
+    <div
+      aria-label={label}
+      className={cn("space-y-1", className)}
+      data-slot="single-stat"
+      role="group"
+      {...props}
+    >
+      {label && (
+        <p
+          className="text-sm font-medium text-muted-foreground"
+          data-slot="single-stat-label"
+        >
+          {label}
+        </p>
+      )}
+      <p
+        className={cn(
+          "font-bold tabular-nums text-foreground",
+          sizeClasses[size]
+        )}
+        data-slot="single-stat-value"
+      >
+        {prefix && <span aria-hidden="true">{prefix}</span>}
+        {displayValue}
+        {suffix && <span aria-hidden="true">{suffix}</span>}
+      </p>
+    </div>
+  )
+}
+
+export { SingleStat }

package/src/components/data-display/SingleStat/SingleStat.types.ts

@@ -0,0 +1,71 @@
+import type { HTMLAttributes } from "react"
+
+/**
+ * SingleStat variant types
+ * - default: Label above, value below
+ * - inline: Label and value side by side
+ * - compact: Value only, no label
+ */
+export type SingleStatVariant = "compact" | "default" | "inline"
+
+/**
+ * SingleStat size types
+ */
+export type SingleStatSize = "lg" | "md" | "sm" | "xl" | "xs"
+
+/**
+ * Props for the SingleStat component
+ */
+export interface SingleStatProps extends Omit<HTMLAttributes<HTMLDivElement>, "children"> {
+  /**
+   * Enable count-up animation
+   * Only works with numeric values
+   * @default false
+   */
+  animated?: boolean
+
+  /**
+   * Animation duration in milliseconds
+   * @default 1000
+   */
+  animationDuration?: number
+
+  /**
+   * Descriptive label
+   * Not shown when variant is "compact"
+   */
+  label?: string
+
+  /**
+   * Show loading skeleton
+   * @default false
+   */
+  loading?: boolean
+
+  /**
+   * Prefix string (e.g., "$", "R$")
+   */
+  prefix?: string
+
+  /**
+   * Value text size
+   * @default "md"
+   */
+  size?: SingleStatSize
+
+  /**
+   * Suffix string (e.g., "%", "ms")
+   */
+  suffix?: string
+
+  /**
+   * The value to display
+   */
+  value: number | string
+
+  /**
+   * Layout variant
+   * @default "default"
+   */
+  variant?: SingleStatVariant
+}

package/src/components/data-display/SingleStat/SingleStat.variants.ts

@@ -0,0 +1,51 @@
+// SingleStat/SingleStat.variants.ts
+import { cva, type VariantProps } from "class-variance-authority"
+
+/**
+ * SingleStat container style variants using CVA
+ *
+ * @see https://cva.style/docs
+ */
+export const singleStatVariants = cva(
+  // Base styles (always applied)
+  "",
+  {
+    variants: {
+      variant: {
+        default: "space-y-1",
+        compact: "",
+        inline: "flex items-baseline gap-2",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+    },
+  }
+)
+
+/**
+ * SingleStat value size configuration
+ */
+export const singleStatSizeClasses = {
+  xs: "text-lg",
+  sm: "text-xl",
+  md: "text-2xl",
+  lg: "text-4xl",
+  xl: "text-6xl",
+} as const
+
+/**
+ * SingleStat skeleton size configuration
+ */
+export const singleStatSkeletonSizes = {
+  xs: "h-6",
+  sm: "h-7",
+  md: "h-8",
+  lg: "h-10",
+  xl: "h-14",
+} as const
+
+export type SingleStatSize = keyof typeof singleStatSizeClasses
+
+// Export variant prop types
+export type SingleStatVariantProps = VariantProps<typeof singleStatVariants>

package/src/components/data-display/SingleStat/index.ts

@@ -0,0 +1,6 @@
+export { SingleStat } from "./SingleStat"
+export type {
+  SingleStatProps,
+  SingleStatSize,
+  SingleStatVariant,
+} from "./SingleStat.types"