@etus/ui 0.1.0

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

@@ -0,0 +1,129 @@
+import { render, screen } from "@testing-library/react"
+import { describe, expect, it } from "vitest"
+
+import { GaugeChart } from "./GaugeChart"
+
+describe("GaugeChart", () => {
+  it("renders value correctly", () => {
+    render(<GaugeChart label="Score" value={75} />)
+
+    expect(screen.getByText("75")).toBeInTheDocument()
+    expect(screen.getByText("Score")).toBeInTheDocument()
+  })
+
+  it("renders with unit", () => {
+    render(<GaugeChart unit="%" value={50} />)
+
+    expect(screen.getByText("50")).toBeInTheDocument()
+    expect(screen.getByText("%")).toBeInTheDocument()
+  })
+
+  it("has correct ARIA attributes", () => {
+    render(<GaugeChart max={100} min={0} value={50} />)
+
+    const meter = screen.getByRole("meter")
+    expect(meter).toHaveAttribute("aria-valuenow", "50")
+    expect(meter).toHaveAttribute("aria-valuemin", "0")
+    expect(meter).toHaveAttribute("aria-valuemax", "100")
+  })
+
+  it("has descriptive aria-label with label", () => {
+    render(<GaugeChart label="Performance" unit="%" value={75} />)
+
+    const meter = screen.getByRole("meter")
+    expect(meter).toHaveAttribute("aria-label", "Performance: 75%")
+  })
+
+  it("clamps value to min/max range", () => {
+    render(<GaugeChart max={100} min={0} value={150} />)
+
+    const meter = screen.getByRole("meter")
+    expect(meter).toHaveAttribute("aria-valuenow", "100")
+  })
+
+  it("clamps value below min", () => {
+    render(<GaugeChart max={100} min={0} value={-50} />)
+
+    const meter = screen.getByRole("meter")
+    expect(meter).toHaveAttribute("aria-valuenow", "0")
+  })
+
+  it("shows min/max labels when showLabels is true", () => {
+    render(<GaugeChart max={100} min={0} showLabels={true} value={50} />)
+
+    expect(screen.getByText("0")).toBeInTheDocument()
+    expect(screen.getByText("100")).toBeInTheDocument()
+  })
+
+  it("hides value when showValue is false", () => {
+    render(<GaugeChart showValue={false} value={75} />)
+
+    expect(screen.queryByText("75")).not.toBeInTheDocument()
+  })
+
+  it("renders with custom className", () => {
+    render(<GaugeChart className="custom-class" value={50} />)
+
+    const meter = screen.getByRole("meter")
+    expect(meter).toHaveClass("custom-class")
+  })
+
+  it("renders semicircle variant by default", () => {
+    const { container } = render(<GaugeChart value={50} />)
+
+    // Check SVG exists
+    const svg = container.querySelector("svg")
+    expect(svg).toBeInTheDocument()
+  })
+
+  it("renders three-quarters variant", () => {
+    const { container } = render(<GaugeChart value={50} variant="three-quarters" />)
+
+    const svg = container.querySelector("svg")
+    expect(svg).toBeInTheDocument()
+  })
+
+  it("renders full variant", () => {
+    const { container } = render(<GaugeChart value={50} variant="full" />)
+
+    const svg = container.querySelector("svg")
+    expect(svg).toBeInTheDocument()
+  })
+
+  it("renders with zones", () => {
+    const zones = [
+      { color: "var(--destructive)", max: 30, min: 0 },
+      { color: "var(--warning)", max: 60, min: 30 },
+      { color: "var(--success)", max: 100, min: 60 },
+    ]
+
+    const { container } = render(<GaugeChart value={75} zones={zones} />)
+
+    // Should render zone paths
+    const paths = container.querySelectorAll("path")
+    expect(paths.length).toBeGreaterThan(0)
+  })
+
+  it("renders different sizes", () => {
+    const { rerender, container } = render(<GaugeChart size="sm" value={50} />)
+    let svg = container.querySelector("svg")
+    expect(svg).toHaveAttribute("width", "120")
+
+    rerender(<GaugeChart size="md" value={50} />)
+    svg = container.querySelector("svg")
+    expect(svg).toHaveAttribute("width", "180")
+
+    rerender(<GaugeChart size="lg" value={50} />)
+    svg = container.querySelector("svg")
+    expect(svg).toHaveAttribute("width", "240")
+  })
+
+  it("supports negative min values (NPS scale)", () => {
+    render(<GaugeChart label="NPS" max={100} min={-100} value={42} />)
+
+    const meter = screen.getByRole("meter")
+    expect(meter).toHaveAttribute("aria-valuenow", "42")
+    expect(meter).toHaveAttribute("aria-valuemin", "-100")
+    expect(meter).toHaveAttribute("aria-valuemax", "100")
+  })
+})

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

@@ -0,0 +1,332 @@
+import type { GaugeChartProps, GaugeSize, GaugeVariant, GaugeZone } from "./GaugeChart.types"
+
+import { cva, type VariantProps } from "class-variance-authority"
+import * as React from "react"
+
+import { cn } from "../../../lib/utils"
+
+const gaugeChartVariants = cva("relative inline-flex items-center justify-center", {
+  variants: {
+    size: {
+      lg: "",
+      md: "",
+      sm: "",
+    },
+  },
+  defaultVariants: {
+    size: "md",
+  },
+})
+
+/** Size configurations for the gauge */
+const SIZE_CONFIG: Record<GaugeSize, { fontSize: { label: string; minMax: string; value: string }; strokeWidth: number; width: number }> = {
+  lg: { fontSize: { label: "text-base", minMax: "text-sm", value: "text-3xl" }, strokeWidth: 16, width: 240 },
+  md: { fontSize: { label: "text-sm", minMax: "text-xs", value: "text-2xl" }, strokeWidth: 12, width: 180 },
+  sm: { fontSize: { label: "text-xs", minMax: "text-[10px]", value: "text-lg" }, strokeWidth: 8, width: 120 },
+}
+
+/** Variant configurations for arc angles */
+const VARIANT_CONFIG: Record<GaugeVariant, { endAngle: number; rotation: number; startAngle: number }> = {
+  full: { endAngle: 450, rotation: 0, startAngle: 90 },
+  semicircle: { endAngle: 0, rotation: 0, startAngle: 180 },
+  "three-quarters": { endAngle: -45, rotation: 0, startAngle: 225 },
+}
+
+/** CSS variable for primary color */
+const PRIMARY_COLOR_VAR = "var(--primary)"
+/** CSS variable for muted color */
+const MUTED_COLOR_VAR = "var(--muted)"
+
+/**
+ * Calculate SVG arc path
+ */
+function describeArc(
+  cx: number,
+  cy: number,
+  radius: number,
+  startAngle: number,
+  endAngle: number
+): string {
+  const start = polarToCartesian(cx, cy, radius, endAngle)
+  const end = polarToCartesian(cx, cy, radius, startAngle)
+  const largeArcFlag = endAngle - startAngle <= 180 ? "0" : "1"
+
+  return [
+    "M", String(start.x), String(start.y),
+    "A", String(radius), String(radius), "0", largeArcFlag, "0", String(end.x), String(end.y),
+  ].join(" ")
+}
+
+/**
+ * Convert polar coordinates to cartesian
+ */
+function polarToCartesian(
+  cx: number,
+  cy: number,
+  radius: number,
+  angleInDegrees: number
+): { x: number; y: number } {
+  const angleInRadians = ((angleInDegrees - 90) * Math.PI) / 180
+  return {
+    x: cx + radius * Math.cos(angleInRadians),
+    y: cy + radius * Math.sin(angleInRadians),
+  }
+}
+
+/**
+ * Get the color for a given value based on zones
+ */
+function getZoneColor(value: number, zones: GaugeZone[] | undefined): string {
+  if (!zones?.length) {
+    return PRIMARY_COLOR_VAR
+  }
+
+  for (const zone of zones) {
+    if (value >= zone.min && value < zone.max) {
+      return zone.color
+    }
+  }
+
+  // Check if value equals the max of the last zone
+  const lastZone = zones.at(-1)
+  if (lastZone && value >= lastZone.min && value <= lastZone.max) {
+    return lastZone.color
+  }
+
+  return PRIMARY_COLOR_VAR
+}
+
+/**
+ * GaugeChart - A speedometer-style gauge for displaying values on a scale
+ * @example
+ * <GaugeChart label="Score" unit="%" value={75} />
+ * @example
+ * <GaugeChart
+ *   max={100}
+ *   min={-100}
+ *   value={42}
+ *   zones={[
+ *     { color: "var(--destructive)", max: 0, min: -100 },
+ *     { color: "var(--warning)", max: 50, min: 0 },
+ *     { color: "var(--success)", max: 100, min: 50 },
+ *   ]}
+ * />
+ */
+function GaugeChart({
+  animated = true,
+  className,
+  label,
+  max = 100,
+  min = 0,
+  showLabels = true,
+  showValue = true,
+  size = "md",
+  unit,
+  value,
+  variant = "semicircle",
+  zones,
+}: GaugeChartProps) {
+  // Clamp value to min/max range
+  const clampedValue = Math.min(Math.max(value, min), max)
+
+  // Calculate percentage
+  const percentage = ((clampedValue - min) / (max - min)) * 100
+
+  // Get configuration
+  const sizeConfig = SIZE_CONFIG[size]
+  const variantConfig = VARIANT_CONFIG[variant]
+
+  // SVG dimensions
+  const width = sizeConfig.width
+  const height = variant === "semicircle"
+    ? width / 2 + sizeConfig.strokeWidth * 2
+    : variant === "three-quarters"
+      ? width * 0.75 + sizeConfig.strokeWidth
+      : width
+
+  const cx = width / 2
+  const cy = variant === "semicircle"
+    ? width / 2
+    : variant === "three-quarters"
+      ? width * 0.5
+      : width / 2
+
+  const radius = (width - sizeConfig.strokeWidth * 2) / 2
+
+  // Calculate arc angles
+  const { endAngle, startAngle } = variantConfig
+  const totalAngle = Math.abs(startAngle - endAngle)
+  const valueAngle = startAngle - (percentage / 100) * totalAngle
+
+  // Arc paths
+  const backgroundPath = describeArc(cx, cy, radius, startAngle, endAngle)
+  const valuePath = percentage > 0
+    ? describeArc(cx, cy, radius, startAngle, valueAngle)
+    : ""
+
+  // Get color based on zones
+  const fillColor = getZoneColor(clampedValue, zones)
+
+  // Calculate arc length for animation
+  const circumference = 2 * Math.PI * radius
+  const arcLength = (totalAngle / 360) * circumference
+  const valueArcLength = (percentage / 100) * arcLength
+
+  // ARIA label
+  const ariaLabel = label
+    ? `${label}: ${String(clampedValue)}${unit ?? ""}`
+    : `Value: ${String(clampedValue)}${unit ?? ""}`
+
+  // Calculate label positions for min/max
+  const minLabelPos = polarToCartesian(cx, cy, radius + sizeConfig.strokeWidth + 8, startAngle)
+  const maxLabelPos = polarToCartesian(cx, cy, radius + sizeConfig.strokeWidth + 8, endAngle)
+
+  // Common text class name
+  const mutedTextClass = "fill-muted-foreground"
+
+  return (
+    <div
+      aria-label={ariaLabel}
+      aria-valuemax={max}
+      aria-valuemin={min}
+      aria-valuenow={clampedValue}
+      className={cn(gaugeChartVariants({ size }), className)}
+      role="meter"
+    >
+      <svg
+        className="overflow-visible"
+        height={height}
+        viewBox={`0 0 ${String(width)} ${String(height)}`}
+        width={width}
+      >
+        {/* Zone backgrounds if zones are provided */}
+        {zones?.length ? (
+          zones.map((zone) => {
+            const zoneStartPercent = ((zone.min - min) / (max - min)) * 100
+            const zoneEndPercent = ((zone.max - min) / (max - min)) * 100
+            const zoneStartAngle = startAngle - (zoneStartPercent / 100) * totalAngle
+            const zoneEndAngle = startAngle - (zoneEndPercent / 100) * totalAngle
+            const zonePath = describeArc(cx, cy, radius, zoneStartAngle, zoneEndAngle)
+
+            return (
+              <path
+                key={`zone-${String(zone.min)}-${String(zone.max)}`}
+                d={zonePath}
+                fill="none"
+                opacity={0.2}
+                stroke={zone.color}
+                strokeLinecap="round"
+                strokeWidth={sizeConfig.strokeWidth}
+              />
+            )
+          })
+        ) : (
+          /* Default track background */
+          <path
+            d={backgroundPath}
+            fill="none"
+            stroke={MUTED_COLOR_VAR}
+            strokeLinecap="round"
+            strokeWidth={sizeConfig.strokeWidth}
+          />
+        )}
+
+        {/* Value arc */}
+        {valuePath && (
+          <path
+            style={animated ? {
+              strokeDasharray: `${String(valueArcLength)} ${String(arcLength)}`,
+              strokeDashoffset: 0,
+            } : undefined}
+            className={cn(animated && "transition-all duration-500 ease-out")}
+            d={valuePath}
+            fill="none"
+            stroke={fillColor}
+            strokeLinecap="round"
+            strokeWidth={sizeConfig.strokeWidth}
+          />
+        )}
+
+        {/* Center content */}
+        <g className="pointer-events-none">
+          {showValue && (
+            <text
+              className={cn("fill-foreground font-bold", sizeConfig.fontSize.value)}
+              dominantBaseline={variant === "semicircle" ? "auto" : "central"}
+              textAnchor="middle"
+              x={cx}
+              y={variant === "semicircle" ? cy - 8 : cy}
+            >
+              {clampedValue}
+              {unit && (
+                <tspan className="text-muted-foreground font-normal" fontSize="0.6em">
+                  {unit}
+                </tspan>
+              )}
+            </text>
+          )}
+
+          {label && (
+            <text
+              className={cn(mutedTextClass, sizeConfig.fontSize.label)}
+              dominantBaseline={variant === "semicircle" ? "hanging" : "central"}
+              textAnchor="middle"
+              x={cx}
+              y={variant === "semicircle" ? cy + (showValue ? 8 : 0) : cy + (showValue ? 20 : 0)}
+            >
+              {label}
+            </text>
+          )}
+        </g>
+
+        {/* Min/Max labels */}
+        {showLabels && variant === "semicircle" && (
+          <>
+            <text
+              className={cn(mutedTextClass, sizeConfig.fontSize.minMax)}
+              textAnchor="start"
+              x={sizeConfig.strokeWidth}
+              y={cy + sizeConfig.strokeWidth + 12}
+            >
+              {min}
+            </text>
+            <text
+              className={cn(mutedTextClass, sizeConfig.fontSize.minMax)}
+              textAnchor="end"
+              x={width - sizeConfig.strokeWidth}
+              y={cy + sizeConfig.strokeWidth + 12}
+            >
+              {max}
+            </text>
+          </>
+        )}
+
+        {showLabels && variant === "three-quarters" && (
+          <>
+            <text
+              className={cn(mutedTextClass, sizeConfig.fontSize.minMax)}
+              dominantBaseline="middle"
+              textAnchor="end"
+              x={minLabelPos.x}
+              y={minLabelPos.y}
+            >
+              {min}
+            </text>
+            <text
+              className={cn(mutedTextClass, sizeConfig.fontSize.minMax)}
+              dominantBaseline="middle"
+              textAnchor="start"
+              x={maxLabelPos.x}
+              y={maxLabelPos.y}
+            >
+              {max}
+            </text>
+          </>
+        )}
+      </svg>
+    </div>
+  )
+}
+
+export { GaugeChart, gaugeChartVariants }
+export type { VariantProps as GaugeChartVariantProps }

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

@@ -0,0 +1,53 @@
+/**
+ * Zone configuration for GaugeChart color segments
+ */
+export interface GaugeZone {
+  /** Color for this zone - CSS variable or hex color */
+  color: string
+  /** Optional label for the zone */
+  label?: string
+  /** Maximum value for this zone (exclusive, except for last zone) */
+  max: number
+  /** Minimum value for this zone (inclusive) */
+  min: number
+}
+
+/**
+ * Available gauge chart variants
+ */
+export type GaugeVariant = "full" | "semicircle" | "three-quarters"
+
+/**
+ * Available gauge chart sizes
+ */
+export type GaugeSize = "lg" | "md" | "sm"
+
+/**
+ * Props for the GaugeChart component
+ */
+export interface GaugeChartProps {
+  /** Enable value transition animations */
+  animated?: boolean
+  /** Additional CSS classes */
+  className?: string
+  /** Central label text */
+  label?: string
+  /** Maximum value of the gauge scale */
+  max?: number
+  /** Minimum value of the gauge scale */
+  min?: number
+  /** Show min/max labels */
+  showLabels?: boolean
+  /** Show the numeric value */
+  showValue?: boolean
+  /** Component size */
+  size?: GaugeSize
+  /** Unit suffix (%, km/h, etc) */
+  unit?: string
+  /** Current value to display (required) */
+  value: number
+  /** Gauge format variant */
+  variant?: GaugeVariant
+  /** Color zones for the gauge */
+  zones?: GaugeZone[]
+}

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

@@ -0,0 +1,56 @@
+// GaugeChart/GaugeChart.variants.ts
+import { cva, type VariantProps } from "class-variance-authority"
+
+/**
+ * GaugeChart style variants using CVA
+ *
+ * @see https://cva.style/docs
+ */
+export const gaugeChartVariants = cva("relative inline-flex items-center justify-center", {
+  variants: {
+    size: {
+      lg: "",
+      md: "",
+      sm: "",
+    },
+  },
+  defaultVariants: {
+    size: "md",
+  },
+})
+
+/**
+ * Size configurations for the gauge
+ */
+export const gaugeSizeConfig = {
+  lg: {
+    fontSize: { label: "text-base", minMax: "text-sm", value: "text-3xl" },
+    strokeWidth: 16,
+    width: 240,
+  },
+  md: {
+    fontSize: { label: "text-sm", minMax: "text-xs", value: "text-2xl" },
+    strokeWidth: 12,
+    width: 180,
+  },
+  sm: {
+    fontSize: { label: "text-xs", minMax: "text-[10px]", value: "text-lg" },
+    strokeWidth: 8,
+    width: 120,
+  },
+} as const
+
+/**
+ * Variant configurations for arc angles
+ */
+export const gaugeVariantConfig = {
+  full: { endAngle: 450, rotation: 0, startAngle: 90 },
+  semicircle: { endAngle: 0, rotation: 0, startAngle: 180 },
+  "three-quarters": { endAngle: -45, rotation: 0, startAngle: 225 },
+} as const
+
+export type GaugeSize = keyof typeof gaugeSizeConfig
+export type GaugeVariant = keyof typeof gaugeVariantConfig
+
+// Export variant prop types
+export type GaugeChartVariantProps = VariantProps<typeof gaugeChartVariants>