@annondeveloper/ui-kit 0.1.0 → 0.2.0

package/src/components/status-pulse.tsx

@@ -1,5 +1,6 @@
 'use client'
 
+import type React from 'react'
 import { motion, useReducedMotion } from 'framer-motion'
 import { cn } from '../utils'
 
@@ -37,7 +38,7 @@ export interface StatusPulseProps {
  * @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) {
+export function StatusPulse({ status, label = true, configMap, className }: StatusPulseProps): React.JSX.Element {
   const reduced = useReducedMotion()
   const map = configMap ?? defaultPulseConfigMap
   const cfg = map[status] ?? map['unknown'] ?? defaultPulseConfigMap['unknown']!

package/src/components/step-wizard.tsx

@@ -0,0 +1,372 @@
+'use client'
+
+import type React from 'react'
+import { useState, useCallback, useEffect, useRef, useMemo } from 'react'
+import { motion, AnimatePresence, useReducedMotion } from 'framer-motion'
+import { Check, ChevronRight, ChevronLeft } from 'lucide-react'
+import type { LucideIcon } from 'lucide-react'
+import { cn } from '../utils'
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Definition of a single wizard step. */
+export interface WizardStep {
+  /** Unique step identifier. */
+  id: string
+  /** Step title displayed in the step indicator. */
+  title: string
+  /** Optional description below the title. */
+  description?: string
+  /** Optional icon for the step indicator. */
+  icon?: LucideIcon
+  /** Step content to render. */
+  content: React.ReactNode
+  /** Validation function called before advancing. Return true to allow, false to block. */
+  validate?: () => boolean | Promise<boolean>
+}
+
+/** Props for the StepWizard component. */
+export interface StepWizardProps {
+  /** Array of steps in order. */
+  steps: WizardStep[]
+  /** Called when the final step is completed. */
+  onComplete: () => void
+  /** Called whenever the active step changes. */
+  onStepChange?: (step: number) => void
+  /** Step indicator layout. Default "horizontal". */
+  orientation?: 'horizontal' | 'vertical'
+  /** Allow skipping forward to any uncompleted step. Default false. */
+  allowSkip?: boolean
+  /** Show a summary/completion state after the last step. Default false. */
+  showSummary?: boolean
+  /** Additional class name for the root container. */
+  className?: string
+}
+
+const SESSION_KEY_PREFIX = 'ui-kit-wizard-'
+
+// ---------------------------------------------------------------------------
+// StepWizard
+// ---------------------------------------------------------------------------
+
+/**
+ * @description A multi-step form wizard with animated slide transitions, per-step validation,
+ * step indicator bar (horizontal or vertical), keyboard navigation, progress percentage,
+ * and auto-save to sessionStorage for resilience to page refresh.
+ */
+export function StepWizard({
+  steps,
+  onComplete,
+  onStepChange,
+  orientation = 'horizontal',
+  allowSkip = false,
+  showSummary = false,
+  className,
+}: StepWizardProps): React.JSX.Element {
+  const prefersReducedMotion = useReducedMotion()
+  const sessionKey = useMemo(() => SESSION_KEY_PREFIX + steps.map(s => s.id).join('-'), [steps])
+
+  // Restore state from sessionStorage
+  const [currentStep, setCurrentStep] = useState(() => {
+    if (typeof window === 'undefined') return 0
+    try {
+      const saved = sessionStorage.getItem(sessionKey)
+      if (saved) {
+        const parsed = JSON.parse(saved) as { step: number; completed: number[] }
+        return Math.min(parsed.step, steps.length - 1)
+      }
+    } catch { /* noop */ }
+    return 0
+  })
+
+  const [completed, setCompleted] = useState<Set<number>>(() => {
+    if (typeof window === 'undefined') return new Set()
+    try {
+      const saved = sessionStorage.getItem(sessionKey)
+      if (saved) {
+        const parsed = JSON.parse(saved) as { step: number; completed: number[] }
+        return new Set(parsed.completed)
+      }
+    } catch { /* noop */ }
+    return new Set()
+  })
+
+  const [isValidating, setIsValidating] = useState(false)
+  const [direction, setDirection] = useState(1) // 1=forward, -1=backward
+  const [isComplete, setIsComplete] = useState(false)
+  const contentRef = useRef<HTMLDivElement>(null)
+
+  // Save state to sessionStorage
+  useEffect(() => {
+    try {
+      sessionStorage.setItem(sessionKey, JSON.stringify({
+        step: currentStep,
+        completed: [...completed],
+      }))
+    } catch { /* noop */ }
+  }, [currentStep, completed, sessionKey])
+
+  const totalSteps = steps.length
+  const progress = totalSteps === 0 ? 100 : Math.round(((completed.size) / totalSteps) * 100)
+
+  const goToStep = useCallback((idx: number) => {
+    setDirection(idx > currentStep ? 1 : -1)
+    setCurrentStep(idx)
+    onStepChange?.(idx)
+  }, [currentStep, onStepChange])
+
+  const handleNext = useCallback(async () => {
+    const step = steps[currentStep]
+    if (step?.validate) {
+      setIsValidating(true)
+      try {
+        const valid = await step.validate()
+        if (!valid) {
+          setIsValidating(false)
+          return
+        }
+      } catch {
+        setIsValidating(false)
+        return
+      }
+      setIsValidating(false)
+    }
+
+    setCompleted(prev => new Set(prev).add(currentStep))
+
+    if (currentStep < totalSteps - 1) {
+      goToStep(currentStep + 1)
+    } else {
+      // Final step completed
+      if (showSummary) {
+        setIsComplete(true)
+      }
+      onComplete()
+      // Clear session storage
+      try { sessionStorage.removeItem(sessionKey) } catch { /* noop */ }
+    }
+  }, [currentStep, steps, totalSteps, goToStep, onComplete, showSummary, sessionKey])
+
+  const handleBack = useCallback(() => {
+    if (currentStep > 0) {
+      goToStep(currentStep - 1)
+    }
+  }, [currentStep, goToStep])
+
+  const handleStepClick = useCallback((idx: number) => {
+    // Can click on completed steps or if allowSkip
+    if (completed.has(idx) || allowSkip || idx < currentStep) {
+      goToStep(idx)
+    }
+  }, [completed, allowSkip, currentStep, goToStep])
+
+  // Keyboard navigation
+  useEffect(() => {
+    const handler = (e: KeyboardEvent) => {
+      if (e.key === 'Enter' && !e.shiftKey && !(e.target instanceof HTMLTextAreaElement)) {
+        handleNext()
+      }
+    }
+    document.addEventListener('keydown', handler)
+    return () => document.removeEventListener('keydown', handler)
+  }, [handleNext])
+
+  const slideVariants = {
+    enter: (dir: number) => ({
+      x: prefersReducedMotion ? 0 : dir > 0 ? 40 : -40,
+      opacity: prefersReducedMotion ? 1 : 0,
+    }),
+    center: { x: 0, opacity: 1 },
+    exit: (dir: number) => ({
+      x: prefersReducedMotion ? 0 : dir > 0 ? -40 : 40,
+      opacity: prefersReducedMotion ? 1 : 0,
+    }),
+  }
+
+  const isHorizontal = orientation === 'horizontal'
+
+  return (
+    <div className={cn('flex flex-col', className)}>
+      {/* Step indicator */}
+      <div className={cn(
+        'mb-6',
+        isHorizontal ? 'flex items-center' : 'flex flex-col gap-1',
+      )}>
+        {steps.map((step, idx) => {
+          const isActive = idx === currentStep
+          const isDone = completed.has(idx) || isComplete
+          const isClickable = isDone || allowSkip || idx < currentStep
+          const Icon = step.icon
+
+          return (
+            <div
+              key={step.id}
+              className={cn(
+                isHorizontal ? 'flex items-center flex-1' : 'flex items-center gap-3',
+              )}
+            >
+              {/* Step circle + label */}
+              <button
+                onClick={() => handleStepClick(idx)}
+                disabled={!isClickable}
+                className={cn(
+                  'flex items-center gap-2 group',
+                  isClickable ? 'cursor-pointer' : 'cursor-default',
+                )}
+              >
+                <div
+                  className={cn(
+                    'flex items-center justify-center rounded-full transition-all',
+                    'h-8 w-8 text-xs font-semibold shrink-0',
+                    isDone
+                      ? 'bg-[hsl(var(--status-ok))] text-[hsl(var(--text-on-brand))]'
+                      : isActive
+                        ? 'bg-[hsl(var(--brand-primary))] text-[hsl(var(--text-on-brand))] ring-4 ring-[hsl(var(--brand-primary)/0.2)]'
+                        : 'bg-[hsl(var(--bg-overlay))] text-[hsl(var(--text-tertiary))]',
+                    isClickable && !isActive && !isDone && 'group-hover:bg-[hsl(var(--bg-elevated))]',
+                  )}
+                >
+                  {isDone ? (
+                    <Check className="h-4 w-4" />
+                  ) : Icon ? (
+                    <Icon className="h-4 w-4" />
+                  ) : (
+                    idx + 1
+                  )}
+                </div>
+
+                <div className={cn(
+                  isHorizontal ? 'hidden sm:block' : 'block',
+                )}>
+                  <div className={cn(
+                    'text-xs font-medium leading-tight',
+                    isActive ? 'text-[hsl(var(--text-primary))]' : 'text-[hsl(var(--text-secondary))]',
+                  )}>
+                    {step.title}
+                  </div>
+                  {step.description && !isHorizontal && (
+                    <div className="text-[10px] text-[hsl(var(--text-tertiary))]">
+                      {step.description}
+                    </div>
+                  )}
+                </div>
+              </button>
+
+              {/* Connector line */}
+              {isHorizontal && idx < totalSteps - 1 && (
+                <div className={cn(
+                  'flex-1 h-0.5 mx-2 rounded-full transition-colors',
+                  completed.has(idx) ? 'bg-[hsl(var(--status-ok))]' : 'bg-[hsl(var(--border-subtle))]',
+                )} />
+              )}
+            </div>
+          )
+        })}
+      </div>
+
+      {/* Progress bar */}
+      <div className="w-full h-1 rounded-full bg-[hsl(var(--bg-overlay))] mb-4 overflow-hidden">
+        <motion.div
+          className="h-full rounded-full bg-[hsl(var(--brand-primary))]"
+          initial={{ width: 0 }}
+          animate={{ width: `${progress}%` }}
+          transition={prefersReducedMotion ? { duration: 0 } : { type: 'spring', stiffness: 300, damping: 30 }}
+        />
+      </div>
+
+      {/* Step content */}
+      <div ref={contentRef} className="relative min-h-[200px]">
+        <AnimatePresence mode="wait" custom={direction}>
+          {isComplete && showSummary ? (
+            <motion.div
+              key="summary"
+              custom={1}
+              variants={slideVariants}
+              initial="enter"
+              animate="center"
+              exit="exit"
+              transition={prefersReducedMotion ? { duration: 0 } : { duration: 0.25 }}
+              className="flex flex-col items-center justify-center py-12 text-center"
+            >
+              <div className="flex items-center justify-center w-16 h-16 rounded-full bg-[hsl(var(--status-ok)/0.15)] mb-4">
+                <Check className="h-8 w-8 text-[hsl(var(--status-ok))]" />
+              </div>
+              <h3 className="text-lg font-semibold text-[hsl(var(--text-primary))] mb-1">
+                All steps completed
+              </h3>
+              <p className="text-sm text-[hsl(var(--text-secondary))]">
+                All {totalSteps} steps have been successfully completed.
+              </p>
+            </motion.div>
+          ) : (
+            <motion.div
+              key={currentStep}
+              custom={direction}
+              variants={slideVariants}
+              initial="enter"
+              animate="center"
+              exit="exit"
+              transition={prefersReducedMotion ? { duration: 0 } : { duration: 0.25 }}
+            >
+              {steps[currentStep]?.content}
+            </motion.div>
+          )}
+        </AnimatePresence>
+      </div>
+
+      {/* Navigation buttons */}
+      {!isComplete && (
+        <div className="flex items-center justify-between mt-6 pt-4 border-t border-[hsl(var(--border-subtle)/0.5)]">
+          <button
+            onClick={handleBack}
+            disabled={currentStep === 0}
+            className={cn(
+              'inline-flex items-center gap-1.5 px-4 py-2 rounded-lg text-sm font-medium transition-colors',
+              'border border-[hsl(var(--border-default))]',
+              'text-[hsl(var(--text-primary))]',
+              'hover:bg-[hsl(var(--bg-overlay))]',
+              'disabled:opacity-40 disabled:pointer-events-none',
+            )}
+          >
+            <ChevronLeft className="h-4 w-4" />
+            Back
+          </button>
+
+          <span className="text-[11px] text-[hsl(var(--text-tertiary))] tabular-nums">
+            Step {currentStep + 1} of {totalSteps}
+          </span>
+
+          <button
+            onClick={handleNext}
+            disabled={isValidating}
+            className={cn(
+              'inline-flex items-center gap-1.5 px-4 py-2 rounded-lg text-sm font-medium transition-colors',
+              'bg-[hsl(var(--brand-primary))] text-[hsl(var(--text-on-brand))]',
+              'hover:bg-[hsl(var(--brand-primary))]/90',
+              'disabled:opacity-70 disabled:cursor-not-allowed',
+            )}
+          >
+            {isValidating ? (
+              <>
+                <div className="h-4 w-4 rounded-full border-2 border-[hsl(var(--text-on-brand))] border-t-transparent animate-spin" />
+                Validating...
+              </>
+            ) : currentStep === totalSteps - 1 ? (
+              <>
+                Complete
+                <Check className="h-4 w-4" />
+              </>
+            ) : (
+              <>
+                Next
+                <ChevronRight className="h-4 w-4" />
+              </>
+            )}
+          </button>
+        </div>
+      )}
+    </div>
+  )
+}

package/src/components/streaming-text.tsx

@@ -0,0 +1,163 @@
+'use client'
+
+import type React from 'react'
+import { useCallback, useEffect, useRef, useState } from 'react'
+import { motion, AnimatePresence, useReducedMotion } from 'framer-motion'
+import { cn } from '../utils'
+import { Copy, Check } from 'lucide-react'
+
+export interface StreamingTextProps {
+  /** The text content — grows as tokens arrive. */
+  text: string
+  /** Whether tokens are still arriving. */
+  isStreaming: boolean
+  /** Cursor blink speed in ms. */
+  speed?: number
+  /** Show a blinking cursor at the end while streaming. */
+  showCursor?: boolean
+  /** Called when isStreaming transitions from true to false. */
+  onComplete?: () => void
+  className?: string
+}
+
+/** Simple inline formatter: **bold** and `code` spans. */
+function formatSegments(text: string): React.ReactNode[] {
+  const segments: React.ReactNode[] = []
+  const regex = /(\*\*(.+?)\*\*|`([^`]+?)`)/g
+  let lastIndex = 0
+  let match: RegExpExecArray | null
+
+  while ((match = regex.exec(text)) !== null) {
+    if (match.index > lastIndex) {
+      segments.push(text.slice(lastIndex, match.index))
+    }
+    if (match[2]) {
+      segments.push(
+        <strong key={match.index} className="font-semibold">
+          {match[2]}
+        </strong>
+      )
+    } else if (match[3]) {
+      segments.push(
+        <code
+          key={match.index}
+          className="rounded px-1 py-0.5 text-[0.875em] bg-[hsl(var(--bg-overlay))] text-[hsl(var(--brand-primary))] font-mono"
+        >
+          {match[3]}
+        </code>
+      )
+    }
+    lastIndex = match.index + match[0].length
+  }
+
+  if (lastIndex < text.length) {
+    segments.push(text.slice(lastIndex))
+  }
+
+  return segments
+}
+
+/**
+ * @description Displays AI/LLM streaming text responses with a blinking cursor,
+ * markdown-like formatting (bold, code), copy button on completion, and auto-scroll.
+ */
+export function StreamingText({
+  text,
+  isStreaming,
+  speed = 500,
+  showCursor = true,
+  onComplete,
+  className,
+}: StreamingTextProps): React.JSX.Element {
+  const reduced = useReducedMotion()
+  const containerRef = useRef<HTMLDivElement>(null)
+  const prevStreamingRef = useRef(isStreaming)
+  const [copied, setCopied] = useState(false)
+
+  useEffect(() => {
+    if (prevStreamingRef.current && !isStreaming) {
+      onComplete?.()
+    }
+    prevStreamingRef.current = isStreaming
+  }, [isStreaming, onComplete])
+
+  useEffect(() => {
+    if (isStreaming && containerRef.current) {
+      const el = containerRef.current
+      el.scrollTop = el.scrollHeight
+    }
+  }, [text, isStreaming])
+
+  const handleCopy = useCallback(() => {
+    void navigator.clipboard.writeText(text).then(() => {
+      setCopied(true)
+      setTimeout(() => setCopied(false), 2000)
+    })
+  }, [text])
+
+  const formatted = formatSegments(text)
+
+  return (
+    <div className={cn('relative', className)}>
+      <div
+        ref={containerRef}
+        className="overflow-y-auto text-[hsl(var(--text-primary))] leading-relaxed whitespace-pre-wrap break-words"
+      >
+        {formatted}
+        {showCursor && isStreaming && (
+          <span
+            className="inline-block w-[2px] h-[1.1em] align-text-bottom ml-0.5 bg-[hsl(var(--brand-primary))]"
+            style={
+              reduced
+                ? { opacity: 1 }
+                : {
+                    animation: `streaming-cursor-blink ${speed}ms step-end infinite`,
+                  }
+            }
+          />
+        )}
+        <AnimatePresence>
+          {showCursor && !isStreaming && text.length > 0 && (
+            <motion.span
+              className="inline-block w-[2px] h-[1.1em] align-text-bottom ml-0.5 bg-[hsl(var(--brand-primary))]"
+              initial={{ opacity: 1 }}
+              exit={{ opacity: 0 }}
+              transition={{ duration: reduced ? 0 : 0.4 }}
+            />
+          )}
+        </AnimatePresence>
+      </div>
+
+      <AnimatePresence>
+        {!isStreaming && text.length > 0 && (
+          <motion.button
+            type="button"
+            initial={{ opacity: 0, scale: 0.8 }}
+            animate={{ opacity: 1, scale: 1 }}
+            exit={{ opacity: 0, scale: 0.8 }}
+            transition={{ duration: reduced ? 0 : 0.2 }}
+            onClick={handleCopy}
+            className={cn(
+              'absolute top-0 right-0 p-1.5 rounded-lg',
+              'text-[hsl(var(--text-tertiary))] hover:text-[hsl(var(--text-primary))]',
+              'bg-[hsl(var(--bg-surface))]/80 hover:bg-[hsl(var(--bg-elevated))]',
+              'transition-colors duration-150 cursor-pointer',
+            )}
+            aria-label={copied ? 'Copied' : 'Copy to clipboard'}
+          >
+            {copied ? <Check className="size-3.5" /> : <Copy className="size-3.5" />}
+          </motion.button>
+        )}
+      </AnimatePresence>
+
+      {showCursor && isStreaming && !reduced && (
+        <style>{`
+          @keyframes streaming-cursor-blink {
+            0%, 100% { opacity: 1; }
+            50% { opacity: 0; }
+          }
+        `}</style>
+      )}
+    </div>
+  )
+}

package/src/components/success-checkmark.tsx

@@ -1,5 +1,6 @@
 'use client'
 
+import type React from 'react'
 import { motion, useReducedMotion } from 'framer-motion'
 
 export interface SuccessCheckmarkProps {
@@ -12,7 +13,7 @@ export interface SuccessCheckmarkProps {
  * @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) {
+export function SuccessCheckmark({ size = 20, className }: SuccessCheckmarkProps): React.JSX.Element {
   const reduced = useReducedMotion()
 
   return (

package/src/components/tabs.tsx

@@ -1,5 +1,6 @@
 'use client'
 
+import type React from 'react'
 import { useCallback, useRef, type KeyboardEvent } from 'react'
 import { motion, useReducedMotion } from 'framer-motion'
 import type { LucideIcon } from 'lucide-react'
@@ -49,7 +50,7 @@ export function Tabs({
   variant = 'underline',
   size = 'md',
   className,
-}: TabsProps) {
+}: TabsProps): React.JSX.Element {
   const prefersReducedMotion = useReducedMotion()
   const tabListRef = useRef<HTMLDivElement>(null)
 

package/src/components/threshold-gauge.tsx

@@ -1,5 +1,6 @@
 'use client'
 
+import type React from 'react'
 import { useEffect, useState } from 'react'
 import { useReducedMotion } from 'framer-motion'
 import { cn, clamp } from '../utils'
@@ -53,7 +54,7 @@ export function ThresholdGauge({
   showValue = true,
   format,
   className,
-}: ThresholdGaugeProps) {
+}: ThresholdGaugeProps): React.JSX.Element {
   const reduced = useReducedMotion()
   const value = clamp(rawValue, 0, 100)
   const warning = thresholds?.warning ?? 70

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

@@ -1,5 +1,6 @@
 'use client'
 
+import type React from 'react'
 import { motion, useReducedMotion } from 'framer-motion'
 import { cn } from '../utils'
 
@@ -40,7 +41,7 @@ export function TimeRangeSelector({
   onChange,
   ranges = defaultRanges,
   className,
-}: TimeRangeSelectorProps) {
+}: TimeRangeSelectorProps): React.JSX.Element {
   const reduced = useReducedMotion()
 
   return (

package/src/components/toast.tsx

@@ -1,5 +1,6 @@
 'use client'
 
+import type React from 'react'
 import { Toaster as SonnerToaster } from 'sonner'
 
 export interface ToasterProps {
@@ -16,7 +17,7 @@ export interface ToasterProps {
  * 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) {
+export function Toaster({ theme = 'dark', position = 'bottom-right', duration = 4000 }: ToasterProps): React.JSX.Element {
   return (
     <SonnerToaster
       theme={theme}

package/src/components/toggle-switch.tsx

@@ -1,5 +1,6 @@
 'use client'
 
+import type React from 'react'
 import { ToggleLeft, ToggleRight } from 'lucide-react'
 import { cn } from '../utils'
 
@@ -23,7 +24,7 @@ export interface ToggleSwitchProps {
  */
 export function ToggleSwitch({
   enabled, onChange, size = 'md', disabled, label, className,
-}: ToggleSwitchProps) {
+}: ToggleSwitchProps): React.JSX.Element {
   const iconSize = size === 'sm' ? 'size-5' : 'size-6'
 
   return (

package/src/components/tooltip.tsx

@@ -1,5 +1,6 @@
 'use client'
 
+import type React from 'react'
 import { type ReactNode } from 'react'
 import * as TooltipPrimitive from '@radix-ui/react-tooltip'
 import { cn } from '../utils'
@@ -28,7 +29,7 @@ export function Tooltip({
   side = 'top',
   delay = 200,
   className,
-}: TooltipProps) {
+}: TooltipProps): React.JSX.Element {
   return (
     <TooltipPrimitive.Provider delayDuration={delay}>
       <TooltipPrimitive.Root>

package/src/components/truncated-text.tsx

@@ -1,5 +1,6 @@
 'use client'
 
+import type React from 'react'
 import { useRef, useState, useEffect } from 'react'
 import * as Tooltip from '@radix-ui/react-tooltip'
 import { Copy, Check } from 'lucide-react'
@@ -16,7 +17,7 @@ export interface TruncatedTextProps {
  * @description A text element that truncates with ellipsis and shows a tooltip with the
  * full text on hover when truncated. Includes a copy-to-clipboard button in the tooltip.
  */
-export function TruncatedText({ text, maxWidth = '100%', className = '' }: TruncatedTextProps) {
+export function TruncatedText({ text, maxWidth = '100%', className = '' }: TruncatedTextProps): React.JSX.Element {
   const ref = useRef<HTMLSpanElement>(null)
   const [isTruncated, setIsTruncated] = useState(false)
   const [copied, setCopied] = useState(false)