@annondeveloper/ui-kit 0.1.0

package/src/components/metric-card.tsx

@@ -0,0 +1,141 @@
+'use client'
+
+import { type ElementType } from 'react'
+import { motion, useReducedMotion } from 'framer-motion'
+import { TrendingUp, TrendingDown } from 'lucide-react'
+import { cn } from '../utils'
+import { AnimatedCounter } from './animated-counter'
+import { Sparkline } from './sparkline'
+
+export interface MetricCardProps {
+  /** Metric display label. */
+  label: string
+  /** Current numeric value. */
+  value: number
+  /** Custom formatter for the displayed value (e.g. fmtBytes, fmtBps). */
+  format?: (n: number) => string
+  /** Previous value for trend calculation. */
+  previousValue?: number
+  /** Interpret trend direction for coloring. */
+  trendDirection?: 'up-good' | 'up-bad' | 'down-good' | 'down-bad'
+  /** Lucide icon component to display. */
+  icon?: ElementType
+  /** Status determines left border accent color. */
+  status?: 'ok' | 'warning' | 'critical'
+  /** Recent values to render an inline sparkline. */
+  sparklineData?: number[]
+  className?: string
+}
+
+const statusBorder: Record<string, string> = {
+  ok: 'border-l-[hsl(var(--status-ok))]',
+  warning: 'border-l-[hsl(var(--status-warning))]',
+  critical: 'border-l-[hsl(var(--status-critical))]',
+}
+
+const trendColors: Record<string, string> = {
+  good: 'text-[hsl(var(--status-ok))]',
+  bad: 'text-[hsl(var(--status-critical))]',
+}
+
+/**
+ * @description A dashboard stat tile showing a metric value with animated counter,
+ * trend indicator, optional sparkline, and status-colored left border.
+ * Designed for monitoring dashboards and overview panels.
+ */
+export function MetricCard({
+  label,
+  value,
+  format,
+  previousValue,
+  trendDirection,
+  icon: Icon,
+  status,
+  sparklineData,
+  className,
+}: MetricCardProps) {
+  const reduced = useReducedMotion()
+
+  // Trend calculation
+  let trendPct: number | null = null
+  let trendUp = false
+  let trendColorKey: 'good' | 'bad' | null = null
+
+  if (previousValue != null && previousValue !== 0) {
+    trendPct = ((value - previousValue) / Math.abs(previousValue)) * 100
+    trendUp = trendPct >= 0
+
+    if (trendDirection) {
+      const isUp = trendPct >= 0
+      if (trendDirection === 'up-good') trendColorKey = isUp ? 'good' : 'bad'
+      else if (trendDirection === 'up-bad') trendColorKey = isUp ? 'bad' : 'good'
+      else if (trendDirection === 'down-good') trendColorKey = isUp ? 'bad' : 'good'
+      else if (trendDirection === 'down-bad') trendColorKey = isUp ? 'good' : 'bad'
+    }
+  }
+
+  return (
+    <motion.div
+      initial={reduced ? false : { opacity: 0, y: 8 }}
+      animate={{ opacity: 1, y: 0 }}
+      transition={{ duration: 0.2, ease: 'easeOut' }}
+      className={cn(
+        'relative rounded-2xl border border-[hsl(var(--border-subtle))] bg-[hsl(var(--bg-surface))]',
+        'p-5 shadow-sm border-l-[3px]',
+        status ? statusBorder[status] : 'border-l-[hsl(var(--border-subtle))]',
+        className,
+      )}
+    >
+      <div className="flex items-start justify-between gap-3">
+        <div className="min-w-0 flex-1">
+          <div className="flex items-center gap-2 mb-1">
+            {Icon && (
+              <Icon className="size-4 shrink-0 text-[hsl(var(--text-tertiary))]" />
+            )}
+            <span className="text-[0.75rem] font-medium text-[hsl(var(--text-secondary))] truncate">
+              {label}
+            </span>
+          </div>
+
+          <div className="flex items-baseline gap-2">
+            <span className="text-2xl font-semibold text-[hsl(var(--text-primary))] tabular-nums">
+              <AnimatedCounter value={value} format={format} />
+            </span>
+
+            {trendPct != null && (
+              <span
+                className={cn(
+                  'inline-flex items-center gap-0.5 text-[0.6875rem] font-medium tabular-nums',
+                  trendColorKey ? trendColors[trendColorKey] : 'text-[hsl(var(--text-tertiary))]',
+                )}
+              >
+                {trendUp ? (
+                  <TrendingUp className="size-3" />
+                ) : (
+                  <TrendingDown className="size-3" />
+                )}
+                {Math.abs(trendPct).toFixed(1)}%
+              </span>
+            )}
+          </div>
+        </div>
+
+        {sparklineData && sparklineData.length >= 2 && (
+          <Sparkline
+            data={sparklineData}
+            width={72}
+            height={28}
+            color={
+              status === 'critical'
+                ? 'hsl(var(--status-critical))'
+                : status === 'warning'
+                  ? 'hsl(var(--status-warning))'
+                  : 'hsl(var(--brand-primary))'
+            }
+            fillOpacity={0.15}
+          />
+        )}
+      </div>
+    </motion.div>
+  )
+}

package/src/components/pipeline-stage.tsx

@@ -0,0 +1,134 @@
+'use client'
+
+import { type ElementType } from 'react'
+import { motion, useReducedMotion } from 'framer-motion'
+import { ChevronRight } from 'lucide-react'
+import { cn } from '../utils'
+
+export interface StageInfo {
+  /** Stage display name. */
+  name: string
+  /** Current stage status. */
+  status: 'active' | 'idle' | 'error' | 'disabled'
+  /** Optional metric to display inside the stage box. */
+  metric?: { label: string; value: string }
+  /** Lucide icon component for the stage. */
+  icon?: ElementType
+}
+
+export interface PipelineStageProps {
+  /** Ordered array of processing stages. */
+  stages: StageInfo[]
+  /** Callback when a stage is clicked. */
+  onStageClick?: (stage: StageInfo, index: number) => void
+  className?: string
+}
+
+const statusDot: Record<string, string> = {
+  active: 'bg-[hsl(var(--status-ok))]',
+  idle: 'bg-[hsl(var(--text-tertiary))]',
+  error: 'bg-[hsl(var(--status-critical))]',
+  disabled: 'bg-[hsl(var(--text-disabled))]',
+}
+
+const statusBorder: Record<string, string> = {
+  active: 'border-[hsl(var(--status-ok))]/30',
+  idle: 'border-[hsl(var(--border-default))]',
+  error: 'border-[hsl(var(--status-critical))]/30',
+  disabled: 'border-[hsl(var(--border-subtle))]',
+}
+
+const statusBg: Record<string, string> = {
+  active: 'bg-[hsl(var(--bg-surface))]',
+  idle: 'bg-[hsl(var(--bg-surface))]',
+  error: 'bg-[hsl(var(--status-critical))]/5',
+  disabled: 'bg-[hsl(var(--bg-elevated))]',
+}
+
+/**
+ * @description A horizontal data pipeline visualization showing processing stages
+ * connected by animated chevron arrows. Each stage displays name, status dot,
+ * optional icon, and optional metric. Designed for data pipeline monitoring views.
+ */
+export function PipelineStage({
+  stages,
+  onStageClick,
+  className,
+}: PipelineStageProps) {
+  const reduced = useReducedMotion()
+
+  return (
+    <div className={cn('flex items-center gap-0 overflow-x-auto', className)}>
+      {stages.map((stage, i) => {
+        const Icon = stage.icon
+        const isDisabled = stage.status === 'disabled'
+
+        return (
+          <div key={`${stage.name}-${i}`} className="flex items-center shrink-0">
+            {/* Arrow connector */}
+            {i > 0 && (
+              <motion.div
+                initial={reduced ? false : { opacity: 0, x: -4 }}
+                animate={{ opacity: 1, x: 0 }}
+                transition={{ duration: 0.15, delay: reduced ? 0 : i * 0.05 }}
+                className="px-1"
+              >
+                <ChevronRight className="size-4 text-[hsl(var(--text-tertiary))]" />
+              </motion.div>
+            )}
+
+            {/* Stage box */}
+            <motion.button
+              type="button"
+              initial={reduced ? false : { opacity: 0, y: 6 }}
+              animate={{ opacity: 1, y: 0 }}
+              transition={{ duration: 0.2, delay: reduced ? 0 : i * 0.06 }}
+              onClick={() => onStageClick?.(stage, i)}
+              disabled={isDisabled && !onStageClick}
+              className={cn(
+                'flex flex-col items-start gap-1.5 px-4 py-3 rounded-xl border',
+                'transition-all min-w-[120px]',
+                statusBorder[stage.status],
+                statusBg[stage.status],
+                onStageClick && !isDisabled && 'cursor-pointer hover:bg-[hsl(var(--bg-elevated))]',
+                isDisabled && 'opacity-50',
+              )}
+            >
+              {/* Header row: icon + name + status dot */}
+              <div className="flex items-center gap-2 w-full">
+                {Icon && (
+                  <Icon className={cn('size-3.5 shrink-0', isDisabled ? 'text-[hsl(var(--text-disabled))]' : 'text-[hsl(var(--text-secondary))]')} />
+                )}
+                <span className={cn(
+                  'text-[0.8125rem] font-medium truncate',
+                  isDisabled ? 'text-[hsl(var(--text-disabled))]' : 'text-[hsl(var(--text-primary))]',
+                )}>
+                  {stage.name}
+                </span>
+                <span
+                  className={cn(
+                    'size-2 rounded-full shrink-0 ml-auto',
+                    statusDot[stage.status],
+                    stage.status === 'active' && 'animate-pulse',
+                  )}
+                />
+              </div>
+
+              {/* Metric */}
+              {stage.metric && (
+                <div className="flex items-baseline gap-1">
+                  <span className="text-[0.875rem] font-semibold text-[hsl(var(--text-primary))] tabular-nums">
+                    {stage.metric.value}
+                  </span>
+                  <span className="text-[0.625rem] text-[hsl(var(--text-tertiary))]">
+                    {stage.metric.label}
+                  </span>
+                </div>
+              )}
+            </motion.button>
+          </div>
+        )
+      })}
+    </div>
+  )
+}

package/src/components/popover.tsx

@@ -0,0 +1,72 @@
+'use client'
+
+import { type ReactNode } from 'react'
+import * as PopoverPrimitive from '@radix-ui/react-popover'
+import { motion, AnimatePresence, useReducedMotion } from 'framer-motion'
+import { cn } from '../utils'
+
+export interface PopoverProps {
+  /** Trigger element that opens the popover. */
+  trigger: ReactNode
+  /** Popover content. */
+  children: ReactNode
+  /** Side of the trigger to display the popover. */
+  side?: 'top' | 'right' | 'bottom' | 'left'
+  /** Alignment of the popover relative to the trigger. */
+  align?: 'start' | 'center' | 'end'
+  /** Additional class name for the content container. */
+  className?: string
+}
+
+const contentVariants = {
+  hidden: { opacity: 0, scale: 0.96, y: -2 },
+  visible: { opacity: 1, scale: 1, y: 0 },
+  exit: { opacity: 0, scale: 0.96, y: -2 },
+}
+
+/**
+ * @description A popover wrapper built on Radix Popover with Framer Motion entry animation.
+ * Closes on outside click. Includes an arrow pointer.
+ */
+export function Popover({ trigger, children, side = 'bottom', align = 'center', className }: PopoverProps) {
+  const prefersReducedMotion = useReducedMotion()
+
+  return (
+    <PopoverPrimitive.Root>
+      <PopoverPrimitive.Trigger asChild>{trigger}</PopoverPrimitive.Trigger>
+
+      <AnimatePresence>
+        <PopoverPrimitive.Portal>
+          <PopoverPrimitive.Content
+            side={side}
+            align={align}
+            sideOffset={8}
+            asChild
+          >
+            <motion.div
+              initial="hidden"
+              animate="visible"
+              exit="exit"
+              variants={contentVariants}
+              transition={prefersReducedMotion ? { duration: 0 } : { duration: 0.15, ease: [0.16, 1, 0.3, 1] }}
+              className={cn(
+                'z-50 rounded-xl p-4',
+                'border border-[hsl(var(--border-default))]',
+                'bg-[hsl(var(--bg-elevated))] shadow-xl',
+                'focus:outline-none',
+                className,
+              )}
+            >
+              {children}
+              <PopoverPrimitive.Arrow
+                className="fill-[hsl(var(--bg-elevated))]"
+                width={12}
+                height={6}
+              />
+            </motion.div>
+          </PopoverPrimitive.Content>
+        </PopoverPrimitive.Portal>
+      </AnimatePresence>
+    </PopoverPrimitive.Root>
+  )
+}

package/src/components/port-status-grid.tsx

@@ -0,0 +1,102 @@
+'use client'
+
+import { motion, useReducedMotion } from 'framer-motion'
+import { cn } from '../utils'
+
+export interface PortStatus {
+  /** Unique port identifier. */
+  id: string
+  /** Display label (e.g. "Gi1/0/1"). */
+  label: string
+  /** Port operational status. */
+  status: 'up' | 'down' | 'disabled' | 'error'
+  /** Link speed display string (e.g. "10G", "1G"). */
+  speed?: string
+  /** Port utilization 0-100 percentage. */
+  utilization?: number
+}
+
+export interface PortStatusGridProps {
+  /** Array of port status objects. */
+  ports: PortStatus[]
+  /** Number of columns. Defaults to auto-fit. */
+  columns?: number
+  /** Dot/rectangle size. */
+  size?: 'sm' | 'md'
+  /** Callback when a port is clicked. */
+  onPortClick?: (port: PortStatus) => void
+  className?: string
+}
+
+const statusColor: Record<string, string> = {
+  up: 'bg-[hsl(var(--status-ok))]',
+  down: 'bg-[hsl(var(--status-critical))]',
+  disabled: 'bg-[hsl(var(--text-disabled))]',
+  error: 'bg-[hsl(var(--status-warning))]',
+}
+
+const statusHover: Record<string, string> = {
+  up: 'hover:ring-[hsl(var(--status-ok))]/40',
+  down: 'hover:ring-[hsl(var(--status-critical))]/40',
+  disabled: 'hover:ring-[hsl(var(--text-disabled))]/40',
+  error: 'hover:ring-[hsl(var(--status-warning))]/40',
+}
+
+const sizeClasses = {
+  sm: 'size-3 rounded-[2px]',
+  md: 'size-5 rounded-[3px]',
+}
+
+/**
+ * @description A grid of small colored indicators representing network ports or
+ * interfaces. Each port is colored by operational status with hover tooltips showing
+ * label, speed, and utilization. Designed for switch/router faceplate visualizations.
+ */
+export function PortStatusGrid({
+  ports,
+  columns,
+  size = 'sm',
+  onPortClick,
+  className,
+}: PortStatusGridProps) {
+  const reduced = useReducedMotion()
+
+  const gridStyle = columns
+    ? { gridTemplateColumns: `repeat(${columns}, minmax(0, 1fr))` }
+    : { gridTemplateColumns: `repeat(auto-fill, minmax(${size === 'sm' ? '12px' : '20px'}, 1fr))` }
+
+  return (
+    <div
+      className={cn('grid gap-1', className)}
+      style={gridStyle}
+      role="grid"
+      aria-label="Port status grid"
+    >
+      {ports.map((port, i) => {
+        const tooltipParts = [port.label]
+        if (port.speed) tooltipParts.push(port.speed)
+        if (port.utilization != null) tooltipParts.push(`${port.utilization.toFixed(0)}%`)
+        tooltipParts.push(port.status)
+
+        return (
+          <motion.button
+            key={port.id}
+            type="button"
+            initial={reduced ? false : { opacity: 0, scale: 0.5 }}
+            animate={{ opacity: 1, scale: 1 }}
+            transition={{ duration: 0.1, delay: reduced ? 0 : Math.min(i * 0.008, 0.4) }}
+            onClick={() => onPortClick?.(port)}
+            title={tooltipParts.join(' \u00b7 ')}
+            aria-label={`${port.label}: ${port.status}`}
+            className={cn(
+              'transition-all cursor-pointer ring-0 hover:ring-2',
+              sizeClasses[size],
+              statusColor[port.status] ?? statusColor.disabled,
+              statusHover[port.status] ?? statusHover.disabled,
+            )}
+          />
+        )
+      })}
+    </div>
+  )
+}

package/src/components/progress.tsx

@@ -0,0 +1,128 @@
+'use client'
+
+import { motion, useReducedMotion } from 'framer-motion'
+import { cn } from '../utils'
+
+export interface ProgressProps {
+  /** Current progress value (0-100 by default). */
+  value: number
+  /** Maximum value. */
+  max?: number
+  /** Optional label displayed above the bar. */
+  label?: string
+  /** Show the current percentage value. */
+  showValue?: boolean
+  /** Color variant. */
+  variant?: 'default' | 'success' | 'warning' | 'danger'
+  /** Height preset. */
+  size?: 'sm' | 'md' | 'lg'
+  /** Animate the fill width on value changes. */
+  animated?: boolean
+  /** Show an indeterminate shimmer animation (ignores value). */
+  indeterminate?: boolean
+  /** Additional class name for the root element. */
+  className?: string
+}
+
+const variantColors: Record<NonNullable<ProgressProps['variant']>, string> = {
+  default: 'bg-[hsl(var(--brand-primary))]',
+  success: 'bg-[hsl(var(--status-ok))]',
+  warning: 'bg-[hsl(var(--status-warning))]',
+  danger: 'bg-[hsl(var(--status-critical))]',
+}
+
+const sizeClasses: Record<NonNullable<ProgressProps['size']>, string> = {
+  sm: 'h-1.5',
+  md: 'h-2.5',
+  lg: 'h-4',
+}
+
+/**
+ * @description A progress bar with optional label, animated fill, and indeterminate mode.
+ * Supports multiple color variants and size presets.
+ */
+export function Progress({
+  value,
+  max = 100,
+  label,
+  showValue = false,
+  variant = 'default',
+  size = 'md',
+  animated = true,
+  indeterminate = false,
+  className,
+}: ProgressProps) {
+  const prefersReducedMotion = useReducedMotion()
+  const pct = Math.min(100, Math.max(0, (value / max) * 100))
+
+  return (
+    <div className={cn('w-full', className)}>
+      {/* Label + value row */}
+      {(label || showValue) && (
+        <div className="flex items-center justify-between mb-1.5">
+          {label && (
+            <span className="text-xs font-medium text-[hsl(var(--text-secondary))]">{label}</span>
+          )}
+          {showValue && !indeterminate && (
+            <span className="text-xs font-medium tabular-nums text-[hsl(var(--text-secondary))]">
+              {Math.round(pct)}%
+            </span>
+          )}
+        </div>
+      )}
+
+      {/* Track */}
+      <div
+        role="progressbar"
+        aria-valuenow={indeterminate ? undefined : pct}
+        aria-valuemin={0}
+        aria-valuemax={100}
+        aria-label={label}
+        className={cn(
+          'w-full overflow-hidden rounded-full bg-[hsl(var(--bg-overlay))]',
+          sizeClasses[size],
+        )}
+      >
+        {indeterminate ? (
+          <div
+            className={cn(
+              'h-full w-1/3 rounded-full',
+              variantColors[variant],
+              prefersReducedMotion ? '' : 'animate-shimmer',
+            )}
+            style={
+              prefersReducedMotion
+                ? { width: '33%' }
+                : {
+                    animation: 'indeterminate-slide 1.5s ease-in-out infinite',
+                  }
+            }
+          />
+        ) : animated && !prefersReducedMotion ? (
+          <motion.div
+            className={cn('h-full rounded-full', variantColors[variant])}
+            initial={{ width: 0 }}
+            animate={{ width: `${pct}%` }}
+            transition={{ type: 'spring', stiffness: 100, damping: 20 }}
+          />
+        ) : (
+          <div
+            className={cn('h-full rounded-full transition-[width] duration-300', variantColors[variant])}
+            style={{ width: `${pct}%` }}
+          />
+        )}
+      </div>
+
+      {/* Indeterminate keyframes injected as inline style */}
+      {indeterminate && !prefersReducedMotion && (
+        <style>{`
+          @keyframes indeterminate-slide {
+            0%   { transform: translateX(-100%); }
+            50%  { transform: translateX(200%); }
+            100% { transform: translateX(-100%); }
+          }
+        `}</style>
+      )}
+    </div>
+  )
+}