@annondeveloper/ui-kit 0.1.0

package/src/components/success-checkmark.stories.tsx

@@ -0,0 +1,67 @@
+import type { Meta, StoryObj } from '@storybook/react'
+import { useState } from 'react'
+import { SuccessCheckmark } from './success-checkmark'
+import { Button } from './button'
+
+const meta: Meta<typeof SuccessCheckmark> = {
+  title: 'Components/SuccessCheckmark',
+  component: SuccessCheckmark,
+  tags: ['autodocs'],
+  argTypes: {
+    size: { control: { type: 'range', min: 16, max: 120, step: 4 } },
+  },
+}
+export default meta
+type Story = StoryObj<typeof SuccessCheckmark>
+
+export const Default: Story = {
+  args: { size: 20 },
+}
+
+export const Large: Story = {
+  args: { size: 64 },
+}
+
+export const ExtraLarge: Story = {
+  args: { size: 96 },
+}
+
+export const WithMessage: Story = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', gap: '0.75rem' }}>
+      <SuccessCheckmark size={48} />
+      <span style={{ fontSize: '1rem', fontWeight: 600, color: 'hsl(210 40% 95%)' }}>
+        Device added successfully
+      </span>
+      <span style={{ fontSize: '0.75rem', color: 'hsl(210 20% 70%)' }}>
+        SNMP collection will begin within 60 seconds.
+      </span>
+    </div>
+  ),
+}
+
+export const ReplayAnimation: Story = {
+  render: () => {
+    const [key, setKey] = useState(0)
+    return (
+      <div style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', gap: '1rem' }}>
+        <SuccessCheckmark key={key} size={48} />
+        <Button size="sm" variant="secondary" onClick={() => setKey(k => k + 1)}>
+          Replay Animation
+        </Button>
+      </div>
+    )
+  },
+}
+
+export const Sizes: Story = {
+  render: () => (
+    <div style={{ display: 'flex', gap: '1.5rem', alignItems: 'center' }}>
+      <SuccessCheckmark size={16} />
+      <SuccessCheckmark size={20} />
+      <SuccessCheckmark size={32} />
+      <SuccessCheckmark size={48} />
+      <SuccessCheckmark size={64} />
+    </div>
+  ),
+}

package/src/components/success-checkmark.tsx

@@ -0,0 +1,53 @@
+'use client'
+
+import { motion, useReducedMotion } from 'framer-motion'
+
+export interface SuccessCheckmarkProps {
+  /** Size of the SVG in pixels. */
+  size?: number
+  className?: string
+}
+
+/**
+ * @description An animated success checkmark SVG with circle and path draw animations.
+ * Uses Framer Motion spring physics. Respects prefers-reduced-motion.
+ */
+export function SuccessCheckmark({ size = 20, className }: SuccessCheckmarkProps) {
+  const reduced = useReducedMotion()
+
+  return (
+    <motion.svg
+      width={size}
+      height={size}
+      viewBox="0 0 20 20"
+      fill="none"
+      className={className}
+      initial={reduced ? false : { scale: 0, opacity: 0 }}
+      animate={{ scale: 1, opacity: 1 }}
+      transition={{ type: 'spring', stiffness: 300, damping: 20 }}
+    >
+      <motion.circle
+        cx="10"
+        cy="10"
+        r="9"
+        stroke="hsl(var(--status-ok))"
+        strokeWidth="1.5"
+        fill="none"
+        initial={reduced ? false : { pathLength: 0 }}
+        animate={{ pathLength: 1 }}
+        transition={{ duration: 0.4, ease: 'easeOut' }}
+      />
+      <motion.path
+        d="M6 10l2.5 2.5L14 7.5"
+        stroke="hsl(var(--status-ok))"
+        strokeWidth="1.5"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        fill="none"
+        initial={reduced ? false : { pathLength: 0 }}
+        animate={{ pathLength: 1 }}
+        transition={{ duration: 0.3, delay: 0.2, ease: 'easeOut' }}
+      />
+    </motion.svg>
+  )
+}

package/src/components/tabs.tsx

@@ -0,0 +1,177 @@
+'use client'
+
+import { useCallback, useRef, type KeyboardEvent } from 'react'
+import { motion, useReducedMotion } from 'framer-motion'
+import type { LucideIcon } from 'lucide-react'
+import { cn } from '../utils'
+
+/** A single tab definition. */
+export interface Tab {
+  /** Unique value for this tab. */
+  value: string
+  /** Display label. */
+  label: string
+  /** Optional icon component. */
+  icon?: LucideIcon
+  /** Whether this tab is disabled. */
+  disabled?: boolean
+}
+
+export interface TabsProps {
+  /** Array of tab definitions. */
+  tabs: Tab[]
+  /** Currently selected tab value. */
+  value: string
+  /** Callback when a tab is selected. */
+  onChange: (value: string) => void
+  /** Visual variant. */
+  variant?: 'underline' | 'pills' | 'enclosed'
+  /** Size preset. */
+  size?: 'sm' | 'md'
+  /** Additional class name for the root element. */
+  className?: string
+}
+
+const sizeClasses = {
+  sm: 'text-xs px-3 py-1.5 gap-1.5',
+  md: 'text-sm px-4 py-2 gap-2',
+} as const
+
+/**
+ * @description Accessible tabbed interface with three visual variants.
+ * Uses Framer Motion layoutId for animated indicator sliding between tabs.
+ * Supports keyboard navigation (arrow keys) and ARIA roles.
+ */
+export function Tabs({
+  tabs,
+  value,
+  onChange,
+  variant = 'underline',
+  size = 'md',
+  className,
+}: TabsProps) {
+  const prefersReducedMotion = useReducedMotion()
+  const tabListRef = useRef<HTMLDivElement>(null)
+
+  const enabledTabs = tabs.filter((t) => !t.disabled)
+
+  const handleKeyDown = useCallback(
+    (e: KeyboardEvent<HTMLDivElement>) => {
+      const currentIdx = enabledTabs.findIndex((t) => t.value === value)
+      if (currentIdx === -1) return
+
+      let nextIdx: number | null = null
+
+      if (e.key === 'ArrowRight' || e.key === 'ArrowDown') {
+        e.preventDefault()
+        nextIdx = (currentIdx + 1) % enabledTabs.length
+      } else if (e.key === 'ArrowLeft' || e.key === 'ArrowUp') {
+        e.preventDefault()
+        nextIdx = (currentIdx - 1 + enabledTabs.length) % enabledTabs.length
+      } else if (e.key === 'Home') {
+        e.preventDefault()
+        nextIdx = 0
+      } else if (e.key === 'End') {
+        e.preventDefault()
+        nextIdx = enabledTabs.length - 1
+      }
+
+      if (nextIdx !== null) {
+        onChange(enabledTabs[nextIdx].value)
+        const buttons = tabListRef.current?.querySelectorAll<HTMLButtonElement>('[role="tab"]:not([disabled])')
+        buttons?.[nextIdx]?.focus()
+      }
+    },
+    [enabledTabs, value, onChange],
+  )
+
+  const listCls = cn(
+    'inline-flex items-center',
+    variant === 'underline' && 'border-b border-[hsl(var(--border-subtle))] gap-0',
+    variant === 'pills' && 'gap-1 p-1 rounded-xl bg-[hsl(var(--bg-surface))]',
+    variant === 'enclosed' && 'gap-0 border-b border-[hsl(var(--border-subtle))]',
+    className,
+  )
+
+  const layoutId = `tabs-indicator-${variant}`
+
+  return (
+    <div
+      ref={tabListRef}
+      role="tablist"
+      aria-orientation="horizontal"
+      onKeyDown={handleKeyDown}
+      className={listCls}
+    >
+      {tabs.map((tab) => {
+        const isActive = tab.value === value
+        const Icon = tab.icon
+
+        const buttonCls = cn(
+          'relative inline-flex items-center justify-center font-medium transition-colors duration-150',
+          'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[hsl(var(--brand-primary))] focus-visible:ring-offset-1 focus-visible:ring-offset-[hsl(var(--bg-base))]',
+          'disabled:pointer-events-none disabled:opacity-40',
+          'cursor-pointer select-none whitespace-nowrap',
+          sizeClasses[size],
+          // variant-specific active/inactive
+          variant === 'underline' && [
+            isActive
+              ? 'text-[hsl(var(--text-primary))]'
+              : 'text-[hsl(var(--text-tertiary))] hover:text-[hsl(var(--text-secondary))]',
+          ],
+          variant === 'pills' && [
+            isActive
+              ? 'text-[hsl(var(--text-primary))]'
+              : 'text-[hsl(var(--text-tertiary))] hover:text-[hsl(var(--text-secondary))] hover:bg-[hsl(var(--bg-elevated)/0.5)]',
+            'rounded-lg',
+          ],
+          variant === 'enclosed' && [
+            isActive
+              ? 'text-[hsl(var(--text-primary))] bg-[hsl(var(--bg-elevated))]'
+              : 'text-[hsl(var(--text-tertiary))] hover:text-[hsl(var(--text-secondary))]',
+            'rounded-t-lg',
+          ],
+        )
+
+        return (
+          <button
+            key={tab.value}
+            role="tab"
+            aria-selected={isActive}
+            aria-controls={`tabpanel-${tab.value}`}
+            tabIndex={isActive ? 0 : -1}
+            disabled={tab.disabled}
+            onClick={() => onChange(tab.value)}
+            className={buttonCls}
+          >
+            {Icon && <Icon className={size === 'sm' ? 'h-3.5 w-3.5' : 'h-4 w-4'} />}
+            {tab.label}
+
+            {/* Animated indicator */}
+            {isActive && variant === 'underline' && (
+              <motion.div
+                layoutId={layoutId}
+                className="absolute bottom-0 left-0 right-0 h-0.5 bg-[hsl(var(--brand-primary))] rounded-full"
+                transition={prefersReducedMotion ? { duration: 0 } : { type: 'spring', stiffness: 500, damping: 35 }}
+              />
+            )}
+            {isActive && variant === 'pills' && (
+              <motion.div
+                layoutId={layoutId}
+                className="absolute inset-0 rounded-lg bg-[hsl(var(--bg-elevated))] -z-10"
+                transition={prefersReducedMotion ? { duration: 0 } : { type: 'spring', stiffness: 500, damping: 35 }}
+              />
+            )}
+            {isActive && variant === 'enclosed' && (
+              <motion.div
+                layoutId={layoutId}
+                className="absolute bottom-0 left-0 right-0 h-0.5 bg-[hsl(var(--brand-primary))] rounded-full"
+                transition={prefersReducedMotion ? { duration: 0 } : { type: 'spring', stiffness: 500, damping: 35 }}
+              />
+            )}
+          </button>
+        )
+      })}
+    </div>
+  )
+}

package/src/components/threshold-gauge.tsx

@@ -0,0 +1,149 @@
+'use client'
+
+import { useEffect, useState } from 'react'
+import { useReducedMotion } from 'framer-motion'
+import { cn, clamp } from '../utils'
+
+export interface ThresholdGaugeProps {
+  /** Gauge value from 0 to 100. */
+  value: number
+  /** Label displayed below the gauge. */
+  label?: string
+  /** Warning and critical thresholds. */
+  thresholds?: { warning: number; critical: number }
+  /** Gauge diameter in pixels. */
+  size?: number
+  /** Show the numeric value in the center. */
+  showValue?: boolean
+  /** Custom formatter for the center value. */
+  format?: (n: number) => string
+  className?: string
+}
+
+const ARC_START = 135 // degrees, bottom-left
+const ARC_SWEEP = 270 // degrees, total arc span
+
+function polarToCartesian(cx: number, cy: number, r: number, angleDeg: number) {
+  const rad = ((angleDeg - 90) * Math.PI) / 180
+  return { x: cx + r * Math.cos(rad), y: cy + r * Math.sin(rad) }
+}
+
+function describeArc(cx: number, cy: number, r: number, startAngle: number, endAngle: number): string {
+  const start = polarToCartesian(cx, cy, r, endAngle)
+  const end = polarToCartesian(cx, cy, r, startAngle)
+  const largeArc = endAngle - startAngle > 180 ? 1 : 0
+  return `M ${start.x} ${start.y} A ${r} ${r} 0 ${largeArc} 0 ${end.x} ${end.y}`
+}
+
+function getArcColor(pct: number, warning: number, critical: number): string {
+  if (pct >= critical) return 'hsl(var(--util-high))'
+  if (pct >= warning) return 'hsl(var(--util-medium))'
+  return 'hsl(var(--util-low))'
+}
+
+/**
+ * @description A semicircular SVG gauge with color-coded threshold zones
+ * (green/yellow/red). Animates the arc on mount. Displays value in center.
+ */
+export function ThresholdGauge({
+  value: rawValue,
+  label,
+  thresholds,
+  size = 120,
+  showValue = true,
+  format,
+  className,
+}: ThresholdGaugeProps) {
+  const reduced = useReducedMotion()
+  const value = clamp(rawValue, 0, 100)
+  const warning = thresholds?.warning ?? 70
+  const critical = thresholds?.critical ?? 90
+
+  const [animatedValue, setAnimatedValue] = useState(reduced ? value : 0)
+
+  useEffect(() => {
+    if (reduced) {
+      setAnimatedValue(value)
+      return
+    }
+    const start = performance.now()
+    const from = 0
+    const dur = 600
+    let raf: number
+
+    function tick(now: number) {
+      const progress = Math.min((now - start) / dur, 1)
+      const eased = 1 - Math.pow(1 - progress, 3) // ease-out cubic
+      setAnimatedValue(from + (value - from) * eased)
+      if (progress < 1) raf = requestAnimationFrame(tick)
+    }
+    raf = requestAnimationFrame(tick)
+    return () => cancelAnimationFrame(raf)
+  }, [value, reduced])
+
+  const cx = size / 2
+  const cy = size / 2
+  const r = (size - 16) / 2
+  const strokeWidth = Math.max(6, size * 0.08)
+
+  // Background zone arcs
+  const warnAngle = ARC_START + (warning / 100) * ARC_SWEEP
+  const critAngle = ARC_START + (critical / 100) * ARC_SWEEP
+  const endAngle = ARC_START + ARC_SWEEP
+
+  const greenArc = describeArc(cx, cy, r, ARC_START, warnAngle)
+  const yellowArc = describeArc(cx, cy, r, warnAngle, critAngle)
+  const redArc = describeArc(cx, cy, r, critAngle, endAngle)
+
+  // Value arc
+  const valueAngle = ARC_START + (animatedValue / 100) * ARC_SWEEP
+  const valueArc = animatedValue > 0.5
+    ? describeArc(cx, cy, r, ARC_START, valueAngle)
+    : ''
+
+  const displayText = format ? format(value) : `${Math.round(value)}%`
+
+  return (
+    <div className={cn('inline-flex flex-col items-center', className)}>
+      <svg width={size} height={size * 0.75} viewBox={`0 0 ${size} ${size * 0.75}`} aria-hidden="true">
+        {/* Background zones */}
+        <path d={greenArc} fill="none" stroke="hsl(var(--util-low))" strokeWidth={strokeWidth} strokeLinecap="round" opacity={0.2} />
+        <path d={yellowArc} fill="none" stroke="hsl(var(--util-medium))" strokeWidth={strokeWidth} strokeLinecap="round" opacity={0.2} />
+        <path d={redArc} fill="none" stroke="hsl(var(--util-high))" strokeWidth={strokeWidth} strokeLinecap="round" opacity={0.2} />
+
+        {/* Value arc */}
+        {valueArc && (
+          <path
+            d={valueArc}
+            fill="none"
+            stroke={getArcColor(animatedValue, warning, critical)}
+            strokeWidth={strokeWidth}
+            strokeLinecap="round"
+          />
+        )}
+
+        {/* Center value */}
+        {showValue && (
+          <text
+            x={cx}
+            y={cy - 2}
+            textAnchor="middle"
+            dominantBaseline="central"
+            fill="hsl(var(--text-primary))"
+            fontSize={size * 0.2}
+            fontWeight={600}
+            fontFamily="inherit"
+            className="tabular-nums"
+          >
+            {displayText}
+          </text>
+        )}
+      </svg>
+      {label && (
+        <span className="text-[0.75rem] font-medium text-[hsl(var(--text-secondary))] mt-1">
+          {label}
+        </span>
+      )}
+    </div>
+  )
+}

package/src/components/time-range-selector.tsx

@@ -0,0 +1,86 @@
+'use client'
+
+import { motion, useReducedMotion } from 'framer-motion'
+import { cn } from '../utils'
+
+export interface TimeRange {
+  /** Display label (e.g. "1h", "24h"). */
+  label: string
+  /** Unique value identifier. */
+  value: string
+  /** Duration in seconds represented by this range. */
+  seconds: number
+}
+
+export interface TimeRangeSelectorProps {
+  /** Currently selected range value. */
+  value: string
+  /** Callback when a range is selected. */
+  onChange: (value: string, range: TimeRange) => void
+  /** Custom range options. Defaults to 1h, 6h, 24h, 7d, 30d. */
+  ranges?: TimeRange[]
+  className?: string
+}
+
+const defaultRanges: TimeRange[] = [
+  { label: '1h', value: '1h', seconds: 3600 },
+  { label: '6h', value: '6h', seconds: 21600 },
+  { label: '24h', value: '24h', seconds: 86400 },
+  { label: '7d', value: '7d', seconds: 604800 },
+  { label: '30d', value: '30d', seconds: 2592000 },
+]
+
+/**
+ * @description A compact horizontal pill-group time range selector for dashboards.
+ * Active selection is highlighted with a sliding indicator using the brand color.
+ * Common in monitoring dashboards for controlling chart time windows.
+ */
+export function TimeRangeSelector({
+  value,
+  onChange,
+  ranges = defaultRanges,
+  className,
+}: TimeRangeSelectorProps) {
+  const reduced = useReducedMotion()
+
+  return (
+    <div
+      className={cn(
+        'inline-flex items-center rounded-lg bg-[hsl(var(--bg-elevated))] p-0.5',
+        'border border-[hsl(var(--border-subtle))]',
+        className,
+      )}
+      role="radiogroup"
+      aria-label="Time range"
+    >
+      {ranges.map(range => {
+        const isActive = range.value === value
+        return (
+          <button
+            key={range.value}
+            type="button"
+            role="radio"
+            aria-checked={isActive}
+            onClick={() => onChange(range.value, range)}
+            className={cn(
+              'relative px-3 py-1 text-[0.75rem] font-medium rounded-md cursor-pointer',
+              'transition-colors duration-150',
+              isActive
+                ? 'text-[hsl(var(--text-on-brand))]'
+                : 'text-[hsl(var(--text-secondary))] hover:text-[hsl(var(--text-primary))]',
+            )}
+          >
+            {isActive && (
+              <motion.span
+                layoutId="time-range-active"
+                className="absolute inset-0 rounded-md bg-[hsl(var(--brand-primary))]"
+                transition={reduced ? { duration: 0 } : { type: 'spring', stiffness: 400, damping: 30 }}
+              />
+            )}
+            <span className="relative z-10">{range.label}</span>
+          </button>
+        )
+      })}
+    </div>
+  )
+}

package/src/components/toast.stories.tsx

@@ -0,0 +1,70 @@
+import type { Meta, StoryObj } from '@storybook/react'
+import { Toaster, toast } from './toast'
+import { Button } from './button'
+
+const meta: Meta<typeof Toaster> = {
+  title: 'Components/Toast',
+  component: Toaster,
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <div>
+        <Story />
+        <Toaster />
+      </div>
+    ),
+  ],
+}
+export default meta
+type Story = StoryObj<typeof Toaster>
+
+export const Success: Story = {
+  render: () => (
+    <Button onClick={() => toast.success('Entity saved successfully')}>
+      Show Success Toast
+    </Button>
+  ),
+}
+
+export const Error: Story = {
+  render: () => (
+    <Button variant="danger" onClick={() => toast.error('Failed to connect to device')}>
+      Show Error Toast
+    </Button>
+  ),
+}
+
+export const Info: Story = {
+  render: () => (
+    <Button variant="secondary" onClick={() => toast.info('Discovery scan started')}>
+      Show Info Toast
+    </Button>
+  ),
+}
+
+export const Warning: Story = {
+  render: () => (
+    <Button variant="outline" onClick={() => toast.warning('Collector response time is slow')}>
+      Show Warning Toast
+    </Button>
+  ),
+}
+
+export const WithDescription: Story = {
+  render: () => (
+    <Button onClick={() => toast.success('Credential saved', { description: 'SNMPv3 credential "datacenter-ro" is now available for discovery.' })}>
+      Toast with Description
+    </Button>
+  ),
+}
+
+export const AllTypes: Story = {
+  render: () => (
+    <div style={{ display: 'flex', gap: '0.5rem', flexWrap: 'wrap' }}>
+      <Button size="sm" onClick={() => toast.success('Success message')}>Success</Button>
+      <Button size="sm" variant="danger" onClick={() => toast.error('Error message')}>Error</Button>
+      <Button size="sm" variant="outline" onClick={() => toast.warning('Warning message')}>Warning</Button>
+      <Button size="sm" variant="secondary" onClick={() => toast.info('Info message')}>Info</Button>
+    </div>
+  ),
+}

package/src/components/toast.tsx

@@ -0,0 +1,48 @@
+'use client'
+
+import { Toaster as SonnerToaster } from 'sonner'
+
+export interface ToasterProps {
+  /** Theme mode. Controls Sonner's internal theming. */
+  theme?: 'dark' | 'light'
+  /** Toast position on screen. */
+  position?: 'top-left' | 'top-right' | 'top-center' | 'bottom-left' | 'bottom-right' | 'bottom-center'
+  /** Auto-dismiss duration in milliseconds. */
+  duration?: number
+}
+
+/**
+ * @description A pre-themed Sonner toast container. Accepts theme as a prop
+ * instead of reading from a hook, making it portable across applications.
+ * Import this Toaster once in your app layout, then use `toast()` from sonner anywhere.
+ */
+export function Toaster({ theme = 'dark', position = 'bottom-right', duration = 4000 }: ToasterProps) {
+  return (
+    <SonnerToaster
+      theme={theme}
+      position={position}
+      richColors
+      duration={duration}
+      gap={8}
+      toastOptions={{
+        style: {
+          background:   'hsl(var(--bg-elevated))',
+          color:        'hsl(var(--text-primary))',
+          border:       '1px solid hsl(var(--border-default))',
+          borderRadius: '0.75rem',
+          boxShadow:    '0 8px 32px hsl(0 0% 0% / 0.25)',
+          fontSize:     '0.875rem',
+        },
+        classNames: {
+          success: 'toast-success',
+          error:   'toast-error',
+          warning: 'toast-warning',
+          info:    'toast-info',
+        },
+      }}
+    />
+  )
+}
+
+// Re-export toast function for convenient imports
+export { toast } from 'sonner'