@annondeveloper/ui-kit 0.1.0

package/src/components/skeleton.tsx

@@ -0,0 +1,62 @@
+'use client'
+
+import { cn } from '../utils'
+
+/**
+ * @description A shimmer skeleton loader block. Requires the `skeleton-shimmer` CSS class
+ * from theme.css to animate.
+ */
+export function Skeleton({ className, ...props }: React.HTMLAttributes<HTMLDivElement>) {
+  return (
+    <div
+      className={cn('skeleton-shimmer rounded-md', className)}
+      {...props}
+    />
+  )
+}
+
+export interface SkeletonTextProps {
+  /** Number of text lines to render. */
+  lines?: number
+  className?: string
+}
+
+/**
+ * @description A multi-line skeleton text placeholder. The last line renders shorter
+ * for a natural paragraph appearance.
+ */
+export function SkeletonText({ lines = 1, className }: SkeletonTextProps) {
+  return (
+    <div className={cn('space-y-2', className)}>
+      {Array.from({ length: lines }).map((_, i) => (
+        <Skeleton
+          key={i}
+          className={cn('h-3', i === lines - 1 && lines > 1 ? 'w-4/5' : 'w-full')}
+        />
+      ))}
+    </div>
+  )
+}
+
+/**
+ * @description A card-shaped skeleton placeholder with header area and content bars.
+ */
+export function SkeletonCard({ className }: { className?: string }) {
+  return (
+    <div className={cn('rounded-lg border border-[hsl(var(--border-subtle))] bg-[hsl(var(--bg-surface))] p-4 space-y-3', className)}>
+      <div className="flex items-center gap-3">
+        <Skeleton className="size-8 rounded-md" />
+        <div className="flex-1 space-y-1.5">
+          <Skeleton className="h-3.5 w-32" />
+          <Skeleton className="h-2.5 w-20" />
+        </div>
+        <Skeleton className="h-5 w-14 rounded-full" />
+      </div>
+      <div className="flex gap-3">
+        <Skeleton className="h-2.5 flex-1" />
+        <Skeleton className="h-2.5 flex-1" />
+        <Skeleton className="h-2.5 flex-1" />
+      </div>
+    </div>
+  )
+}

package/src/components/slider.tsx

@@ -0,0 +1,208 @@
+'use client'
+
+import { useCallback, useRef, useState, type KeyboardEvent, type MouseEvent, type TouchEvent } from 'react'
+import { cn } from '../utils'
+
+export interface SliderProps {
+  /** Current value. */
+  value: number
+  /** Callback when value changes. */
+  onChange: (value: number) => void
+  /** Minimum value. */
+  min?: number
+  /** Maximum value. */
+  max?: number
+  /** Step increment. */
+  step?: number
+  /** Optional label displayed above the slider. */
+  label?: string
+  /** Show the current value. */
+  showValue?: boolean
+  /** Additional class name for the root element. */
+  className?: string
+}
+
+/**
+ * @description A custom-styled range slider with keyboard accessibility.
+ * Features a styled track, filled portion, and draggable thumb.
+ * Shows current value on hover/drag via a tooltip above the thumb.
+ */
+export function Slider({
+  value,
+  onChange,
+  min = 0,
+  max = 100,
+  step = 1,
+  label,
+  showValue = false,
+  className,
+}: SliderProps) {
+  const trackRef = useRef<HTMLDivElement>(null)
+  const [isDragging, setIsDragging] = useState(false)
+  const [isHovering, setIsHovering] = useState(false)
+
+  const pct = max === min ? 0 : ((value - min) / (max - min)) * 100
+
+  const clampToStep = useCallback(
+    (raw: number) => {
+      const clamped = Math.min(max, Math.max(min, raw))
+      const stepped = Math.round((clamped - min) / step) * step + min
+      // Avoid floating point issues
+      return Math.min(max, Math.max(min, parseFloat(stepped.toPrecision(10))))
+    },
+    [min, max, step],
+  )
+
+  const getValueFromPosition = useCallback(
+    (clientX: number) => {
+      const track = trackRef.current
+      if (!track) return value
+      const rect = track.getBoundingClientRect()
+      const ratio = Math.max(0, Math.min(1, (clientX - rect.left) / rect.width))
+      return clampToStep(min + ratio * (max - min))
+    },
+    [min, max, value, clampToStep],
+  )
+
+  const handleMouseDown = useCallback(
+    (e: MouseEvent) => {
+      e.preventDefault()
+      setIsDragging(true)
+      onChange(getValueFromPosition(e.clientX))
+
+      const handleMouseMove = (ev: globalThis.MouseEvent) => {
+        onChange(getValueFromPosition(ev.clientX))
+      }
+      const handleMouseUp = () => {
+        setIsDragging(false)
+        document.removeEventListener('mousemove', handleMouseMove)
+        document.removeEventListener('mouseup', handleMouseUp)
+      }
+      document.addEventListener('mousemove', handleMouseMove)
+      document.addEventListener('mouseup', handleMouseUp)
+    },
+    [getValueFromPosition, onChange],
+  )
+
+  const handleTouchStart = useCallback(
+    (e: TouchEvent) => {
+      setIsDragging(true)
+      if (e.touches[0]) {
+        onChange(getValueFromPosition(e.touches[0].clientX))
+      }
+
+      const handleTouchMove = (ev: globalThis.TouchEvent) => {
+        if (ev.touches[0]) {
+          onChange(getValueFromPosition(ev.touches[0].clientX))
+        }
+      }
+      const handleTouchEnd = () => {
+        setIsDragging(false)
+        document.removeEventListener('touchmove', handleTouchMove)
+        document.removeEventListener('touchend', handleTouchEnd)
+      }
+      document.addEventListener('touchmove', handleTouchMove)
+      document.addEventListener('touchend', handleTouchEnd)
+    },
+    [getValueFromPosition, onChange],
+  )
+
+  const handleKeyDown = useCallback(
+    (e: KeyboardEvent) => {
+      let newValue = value
+      if (e.key === 'ArrowRight' || e.key === 'ArrowUp') {
+        e.preventDefault()
+        newValue = clampToStep(value + step)
+      } else if (e.key === 'ArrowLeft' || e.key === 'ArrowDown') {
+        e.preventDefault()
+        newValue = clampToStep(value - step)
+      } else if (e.key === 'Home') {
+        e.preventDefault()
+        newValue = min
+      } else if (e.key === 'End') {
+        e.preventDefault()
+        newValue = max
+      }
+      if (newValue !== value) onChange(newValue)
+    },
+    [value, min, max, step, clampToStep, onChange],
+  )
+
+  const showTooltip = isDragging || isHovering
+
+  return (
+    <div className={cn('w-full', className)}>
+      {/* Label + value row */}
+      {(label || showValue) && (
+        <div className="flex items-center justify-between mb-2">
+          {label && (
+            <span className="text-xs font-medium text-[hsl(var(--text-secondary))]">{label}</span>
+          )}
+          {showValue && (
+            <span className="text-xs font-medium tabular-nums text-[hsl(var(--text-secondary))]">
+              {value}
+            </span>
+          )}
+        </div>
+      )}
+
+      {/* Track */}
+      <div
+        ref={trackRef}
+        role="slider"
+        aria-valuenow={value}
+        aria-valuemin={min}
+        aria-valuemax={max}
+        aria-label={label}
+        tabIndex={0}
+        onMouseDown={handleMouseDown}
+        onTouchStart={handleTouchStart}
+        onKeyDown={handleKeyDown}
+        onMouseEnter={() => setIsHovering(true)}
+        onMouseLeave={() => setIsHovering(false)}
+        className={cn(
+          'relative h-6 w-full cursor-pointer select-none',
+          'focus-visible:outline-none',
+          'group',
+        )}
+      >
+        {/* Track background */}
+        <div className="absolute top-1/2 -translate-y-1/2 w-full h-2 rounded-full bg-[hsl(var(--bg-overlay))]">
+          {/* Filled portion */}
+          <div
+            className="absolute inset-y-0 left-0 rounded-full bg-[hsl(var(--brand-primary))]"
+            style={{ width: `${pct}%` }}
+          />
+        </div>
+
+        {/* Thumb */}
+        <div
+          className={cn(
+            'absolute top-1/2 -translate-y-1/2 -translate-x-1/2',
+            'h-5 w-5 rounded-full',
+            'bg-[hsl(var(--text-on-brand))] border-2 border-[hsl(var(--brand-primary))]',
+            'shadow-md transition-transform duration-100',
+            isDragging && 'scale-110',
+            'group-focus-visible:ring-2 group-focus-visible:ring-[hsl(var(--brand-primary))] group-focus-visible:ring-offset-2 group-focus-visible:ring-offset-[hsl(var(--bg-base))]',
+          )}
+          style={{ left: `${pct}%` }}
+        >
+          {/* Value tooltip */}
+          {showTooltip && (
+            <div
+              className={cn(
+                'absolute -top-8 left-1/2 -translate-x-1/2',
+                'px-2 py-0.5 rounded-md text-xs font-medium tabular-nums',
+                'bg-[hsl(var(--bg-elevated))] text-[hsl(var(--text-primary))]',
+                'border border-[hsl(var(--border-subtle))] shadow-sm',
+                'pointer-events-none whitespace-nowrap',
+              )}
+            >
+              {value}
+            </div>
+          )}
+        </div>
+      </div>
+    </div>
+  )
+}

package/src/components/sparkline.tsx

@@ -0,0 +1,104 @@
+'use client'
+
+import { cn } from '../utils'
+
+export interface SparklineProps {
+  /** Array of numeric values to plot. */
+  data: number[]
+  /** SVG width in pixels. */
+  width?: number
+  /** SVG height in pixels. */
+  height?: number
+  /** Line color — must use hsl(var(--token)) format. */
+  color?: string
+  /** Opacity for the gradient fill below the line (0 to disable). */
+  fillOpacity?: number
+  /** Show dots on first and last data points. */
+  showDots?: boolean
+  className?: string
+}
+
+function buildPoints(data: number[], w: number, h: number, pad: number): string {
+  if (data.length < 2) return ''
+  const min = Math.min(...data)
+  const max = Math.max(...data)
+  const range = max - min || 1
+  const stepX = (w - pad * 2) / (data.length - 1)
+  return data
+    .map((v, i) => {
+      const x = pad + i * stepX
+      const y = pad + (1 - (v - min) / range) * (h - pad * 2)
+      return `${x},${y}`
+    })
+    .join(' ')
+}
+
+/**
+ * @description A tiny inline SVG sparkline chart for embedding in tables, cards,
+ * and metric tiles. Pure SVG with no external dependencies.
+ */
+export function Sparkline({
+  data,
+  width = 80,
+  height = 24,
+  color = 'hsl(var(--brand-primary))',
+  fillOpacity = 0.1,
+  showDots = false,
+  className,
+}: SparklineProps) {
+  if (data.length < 2) return null
+
+  const pad = showDots ? 3 : 1
+  const points = buildPoints(data, width, height, pad)
+  const gradId = `sp-grad-${Math.random().toString(36).slice(2, 8)}`
+
+  const min = Math.min(...data)
+  const max = Math.max(...data)
+  const range = max - min || 1
+  const stepX = (width - pad * 2) / (data.length - 1)
+
+  const firstX = pad
+  const firstY = pad + (1 - (data[0] - min) / range) * (height - pad * 2)
+  const lastX = pad + (data.length - 1) * stepX
+  const lastY = pad + (1 - (data[data.length - 1] - min) / range) * (height - pad * 2)
+
+  const fillPath = fillOpacity > 0
+    ? `M ${firstX},${height} L ${points.split(' ').join(' L ')} L ${lastX},${height} Z`
+    : undefined
+
+  return (
+    <svg
+      width={width}
+      height={height}
+      viewBox={`0 0 ${width} ${height}`}
+      className={cn('shrink-0', className)}
+      aria-hidden="true"
+    >
+      {fillOpacity > 0 && (
+        <defs>
+          <linearGradient id={gradId} x1="0" y1="0" x2="0" y2="1">
+            <stop offset="0%" stopColor={color} stopOpacity={fillOpacity} />
+            <stop offset="100%" stopColor={color} stopOpacity={0} />
+          </linearGradient>
+        </defs>
+      )}
+      {fillPath && (
+        <path d={fillPath} fill={`url(#${gradId})`} />
+      )}
+      <polyline
+        points={points}
+        fill="none"
+        stroke={color}
+        strokeWidth={1.5}
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+      {showDots && (
+        <>
+          <circle cx={firstX} cy={firstY} r={2} fill={color} />
+          <circle cx={lastX} cy={lastY} r={2} fill={color} />
+        </>
+      )}
+    </svg>
+  )
+}

package/src/components/status-badge.stories.tsx

@@ -0,0 +1,84 @@
+import type { Meta, StoryObj } from '@storybook/react'
+import { StatusBadge } from './status-badge'
+
+const meta: Meta<typeof StatusBadge> = {
+  title: 'Components/StatusBadge',
+  component: StatusBadge,
+  tags: ['autodocs'],
+  argTypes: {
+    status: {
+      control: 'select',
+      options: ['ok', 'active', 'warning', 'critical', 'unknown', 'maintenance', 'stale', 'inactive', 'decommissioned', 'pending'],
+    },
+    size: { control: 'select', options: ['sm', 'md'] },
+    pulse: { control: 'boolean' },
+  },
+}
+export default meta
+type Story = StoryObj<typeof StatusBadge>
+
+export const Default: Story = {
+  args: { status: 'ok' },
+}
+
+export const Critical: Story = {
+  args: { status: 'critical' },
+}
+
+export const Warning: Story = {
+  args: { status: 'warning' },
+}
+
+export const WithPulse: Story = {
+  args: { status: 'critical', pulse: true },
+}
+
+export const SmallSize: Story = {
+  args: { status: 'active', size: 'sm' },
+}
+
+export const CustomLabel: Story = {
+  args: { status: 'ok', label: 'Healthy' },
+}
+
+export const AllStatuses: Story = {
+  render: () => (
+    <div style={{ display: 'flex', gap: '0.5rem', flexWrap: 'wrap' }}>
+      {['ok', 'active', 'warning', 'critical', 'unknown', 'maintenance', 'stale', 'inactive', 'decommissioned', 'pending'].map(s => (
+        <StatusBadge key={s} status={s} />
+      ))}
+    </div>
+  ),
+}
+
+export const CustomStatusMap: Story = {
+  render: () => {
+    const customMap = {
+      running: {
+        label: 'Running',
+        dot: 'bg-[hsl(142,71%,45%)]',
+        text: 'text-[hsl(142,71%,45%)]',
+        bg: 'bg-[hsl(142,71%,45%)]/10',
+      },
+      stopped: {
+        label: 'Stopped',
+        dot: 'bg-[hsl(0,84%,60%)]',
+        text: 'text-[hsl(0,84%,60%)]',
+        bg: 'bg-[hsl(0,84%,60%)]/10',
+      },
+      migrating: {
+        label: 'Migrating',
+        dot: 'bg-[hsl(258,80%,65%)]',
+        text: 'text-[hsl(258,80%,65%)]',
+        bg: 'bg-[hsl(258,80%,65%)]/10',
+      },
+    }
+    return (
+      <div style={{ display: 'flex', gap: '0.5rem' }}>
+        <StatusBadge status="running" statusMap={customMap} />
+        <StatusBadge status="stopped" statusMap={customMap} />
+        <StatusBadge status="migrating" statusMap={customMap} />
+      </div>
+    )
+  },
+}

package/src/components/status-badge.tsx

@@ -0,0 +1,71 @@
+'use client'
+
+import { cn } from '../utils'
+
+/** Configuration for a single status entry in a StatusBadge. */
+export interface StatusConfig {
+  /** Display label. */
+  label: string
+  /** CSS class for the status dot. */
+  dot: string
+  /** CSS class for the text color. */
+  text: string
+  /** CSS class for the background color. */
+  bg: string
+}
+
+/** A sensible default status map covering common statuses. */
+export const defaultStatusMap: Record<string, StatusConfig> = {
+  ok:             { label: 'OK',             dot: 'bg-[hsl(var(--status-ok))]',          text: 'text-[hsl(var(--status-ok))]',          bg: 'bg-[hsl(var(--status-ok))]/10' },
+  active:         { label: 'Active',         dot: 'bg-[hsl(var(--status-ok))]',          text: 'text-[hsl(var(--status-ok))]',          bg: 'bg-[hsl(var(--status-ok))]/10' },
+  warning:        { label: 'Warning',        dot: 'bg-[hsl(var(--status-warning))]',     text: 'text-[hsl(var(--status-warning))]',     bg: 'bg-[hsl(var(--status-warning))]/10' },
+  critical:       { label: 'Critical',       dot: 'bg-[hsl(var(--status-critical))]',    text: 'text-[hsl(var(--status-critical))]',    bg: 'bg-[hsl(var(--status-critical))]/10' },
+  unknown:        { label: 'Unknown',        dot: 'bg-[hsl(var(--status-unknown))]',     text: 'text-[hsl(var(--status-unknown))]',     bg: 'bg-[hsl(var(--status-unknown))]/10' },
+  maintenance:    { label: 'Maintenance',    dot: 'bg-[hsl(var(--status-maintenance))]', text: 'text-[hsl(var(--status-maintenance))]', bg: 'bg-[hsl(var(--status-maintenance))]/10' },
+  stale:          { label: 'Stale',          dot: 'bg-[hsl(var(--status-warning))]',     text: 'text-[hsl(var(--status-warning))]',     bg: 'bg-[hsl(var(--status-warning))]/10' },
+  inactive:       { label: 'Inactive',       dot: 'bg-[hsl(var(--text-tertiary))]',      text: 'text-[hsl(var(--text-tertiary))]',      bg: 'bg-[hsl(var(--text-tertiary))]/10' },
+  decommissioned: { label: 'Decommissioned', dot: 'bg-[hsl(var(--text-disabled))]',      text: 'text-[hsl(var(--text-disabled))]',      bg: 'bg-[hsl(var(--text-disabled))]/10' },
+  pending:        { label: 'Pending',        dot: 'bg-[hsl(var(--status-warning))]',     text: 'text-[hsl(var(--status-warning))]',     bg: 'bg-[hsl(var(--status-warning))]/10' },
+}
+
+export interface StatusBadgeProps {
+  /** Status key to look up in the status map. */
+  status: string
+  /** Override display label. */
+  label?: string
+  /** Size variant. */
+  size?: 'sm' | 'md'
+  /** Show a CSS pulse animation on the dot. */
+  pulse?: boolean
+  /** Custom status map. Falls back to defaultStatusMap. */
+  statusMap?: Record<string, StatusConfig>
+  className?: string
+}
+
+/**
+ * @description A status badge with colored dot indicator and label.
+ * Accepts a configurable statusMap to define custom status values and their appearance.
+ * Falls back to a built-in default map if none is provided.
+ */
+export function StatusBadge({
+  status, label, size = 'md', pulse = false, statusMap, className,
+}: StatusBadgeProps) {
+  const map = statusMap ?? defaultStatusMap
+  const fallback = map['unknown'] ?? defaultStatusMap['unknown']!
+  const config = map[status] ?? fallback
+
+  return (
+    <span
+      className={cn(
+        'inline-flex items-center gap-1.5 rounded-full font-medium',
+        size === 'sm' ? 'px-1.5 py-0.5 text-[0.6875rem]' : 'px-2 py-1 text-[0.75rem]',
+        config.text,
+        config.bg,
+        className,
+      )}
+    >
+      <span className={cn('rounded-full shrink-0', size === 'sm' ? 'size-1.5' : 'size-2', config.dot, pulse && 'animate-pulse')} />
+      {label ?? config.label}
+    </span>
+  )
+}

package/src/components/status-pulse.stories.tsx

@@ -0,0 +1,56 @@
+import type { Meta, StoryObj } from '@storybook/react'
+import { StatusPulse } from './status-pulse'
+
+const meta: Meta<typeof StatusPulse> = {
+  title: 'Components/StatusPulse',
+  component: StatusPulse,
+  tags: ['autodocs'],
+  argTypes: {
+    status: { control: 'select', options: ['online', 'degraded', 'offline', 'unknown'] },
+    label: { control: 'boolean' },
+  },
+}
+export default meta
+type Story = StoryObj<typeof StatusPulse>
+
+export const Online: Story = {
+  args: { status: 'online' },
+}
+
+export const Degraded: Story = {
+  args: { status: 'degraded' },
+}
+
+export const Offline: Story = {
+  args: { status: 'offline' },
+}
+
+export const Unknown: Story = {
+  args: { status: 'unknown' },
+}
+
+export const WithoutLabel: Story = {
+  args: { status: 'online', label: false },
+}
+
+export const AllStates: Story = {
+  render: () => (
+    <div style={{ display: 'flex', gap: '1.5rem', alignItems: 'center' }}>
+      <StatusPulse status="online" />
+      <StatusPulse status="degraded" />
+      <StatusPulse status="offline" />
+      <StatusPulse status="unknown" />
+    </div>
+  ),
+}
+
+export const DotOnly: Story = {
+  render: () => (
+    <div style={{ display: 'flex', gap: '1rem', alignItems: 'center' }}>
+      <StatusPulse status="online" label={false} />
+      <StatusPulse status="degraded" label={false} />
+      <StatusPulse status="offline" label={false} />
+      <StatusPulse status="unknown" label={false} />
+    </div>
+  ),
+}

package/src/components/status-pulse.tsx

@@ -0,0 +1,78 @@
+'use client'
+
+import { motion, useReducedMotion } from 'framer-motion'
+import { cn } from '../utils'
+
+/** Configuration for a single status in StatusPulse. */
+export interface PulseConfig {
+  /** CSS class for the solid dot. */
+  dot: string
+  /** CSS class for the pulse ring. */
+  ring: string
+  /** Whether to show the pulse ring animation. */
+  pulse: boolean
+  /** Use faster animation (e.g. for degraded states). */
+  fast: boolean
+}
+
+/** Default pulse configuration map for common statuses. */
+export const defaultPulseConfigMap: Record<string, PulseConfig> = {
+  online:   { dot: 'bg-[hsl(var(--status-ok))]',       ring: 'bg-[hsl(var(--status-ok))]',       pulse: true,  fast: false },
+  degraded: { dot: 'bg-[hsl(var(--status-warning))]',   ring: 'bg-[hsl(var(--status-warning))]',   pulse: true,  fast: true  },
+  offline:  { dot: 'bg-[hsl(var(--status-critical))]',  ring: 'bg-[hsl(var(--status-critical))]',  pulse: false, fast: false },
+  unknown:  { dot: 'bg-[hsl(var(--text-tertiary))]',    ring: 'bg-[hsl(var(--text-tertiary))]',    pulse: false, fast: false },
+}
+
+export interface StatusPulseProps {
+  /** Status key to look up in the config map. */
+  status: string
+  /** Whether to show the status label text. */
+  label?: boolean
+  /** Custom pulse configuration map. Falls back to defaultPulseConfigMap. */
+  configMap?: Record<string, PulseConfig>
+  className?: string
+}
+
+/**
+ * @description An animated status indicator dot with optional pulse ring and label.
+ * Accepts a configurable map to define custom statuses. Respects prefers-reduced-motion.
+ */
+export function StatusPulse({ status, label = true, configMap, className }: StatusPulseProps) {
+  const reduced = useReducedMotion()
+  const map = configMap ?? defaultPulseConfigMap
+  const cfg = map[status] ?? map['unknown'] ?? defaultPulseConfigMap['unknown']!
+
+  return (
+    <div className={cn('flex items-center gap-2', className)}>
+      <div className="relative flex size-2.5 shrink-0">
+        {/* Pulse ring -- CSS animation only */}
+        {cfg.pulse && !reduced && (
+          <span
+            className={cn(
+              'absolute inline-flex size-full rounded-full opacity-75 animate-pulse-ring',
+              cfg.ring,
+              cfg.fast && '[animation-duration:1s]',
+            )}
+          />
+        )}
+        {/* Solid dot */}
+        <motion.span
+          className={cn('relative inline-flex size-2.5 rounded-full', cfg.dot)}
+          animate={{ scale: 1 }}
+          whileHover={{ scale: reduced ? 1 : 1.3 }}
+          transition={{ type: 'spring', stiffness: 400, damping: 15 }}
+        />
+      </div>
+      {label && (
+        <motion.span
+          key={status}
+          initial={reduced ? {} : { opacity: 0 }}
+          animate={{ opacity: 1 }}
+          className="text-xs font-medium capitalize text-[hsl(var(--text-secondary))]"
+        >
+          {status}
+        </motion.span>
+      )}
+    </div>
+  )
+}