@annondeveloper/ui-kit 0.1.0 → 0.2.0

package/src/components/live-feed.tsx

@@ -0,0 +1,220 @@
+'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 { Pause, Play, ChevronUp } from 'lucide-react'
+
+export interface FeedItem {
+  id: string
+  content: React.ReactNode
+  timestamp: string | Date
+  type?: 'info' | 'success' | 'warning' | 'error'
+}
+
+export interface LiveFeedProps {
+  /** Array of feed items, newest first. */
+  items: FeedItem[]
+  /** Maximum visible items before oldest are faded out. */
+  maxVisible?: number
+  /** Show relative timestamps beside each item. */
+  showTimestamps?: boolean
+  /** Auto-scroll to newest items. */
+  autoScroll?: boolean
+  /** Callback when an item is clicked. */
+  onItemClick?: (item: FeedItem) => void
+  /** Message shown when items array is empty. */
+  emptyMessage?: string
+  className?: string
+}
+
+const TYPE_BORDER: Record<string, string> = {
+  info: 'border-l-[hsl(var(--brand-secondary))]',
+  success: 'border-l-[hsl(var(--status-ok))]',
+  warning: 'border-l-[hsl(var(--status-warning))]',
+  error: 'border-l-[hsl(var(--status-critical))]',
+}
+
+function relativeTime(ts: string | Date): string {
+  const diff = (Date.now() - new Date(ts).getTime()) / 1000
+  if (diff < 5) return 'now'
+  if (diff < 60) return `${Math.floor(diff)}s ago`
+  if (diff < 3600) return `${Math.floor(diff / 60)}m ago`
+  if (diff < 86400) return `${Math.floor(diff / 3600)}h ago`
+  return `${Math.floor(diff / 86400)}d ago`
+}
+
+/**
+ * @description A real-time event feed with animated item entry, auto-scroll,
+ * pause/resume controls, type-colored borders, and relative timestamps.
+ */
+export function LiveFeed({
+  items,
+  maxVisible = 50,
+  showTimestamps = true,
+  autoScroll: autoScrollProp = true,
+  onItemClick,
+  emptyMessage = 'No events yet',
+  className,
+}: LiveFeedProps): React.JSX.Element {
+  const reduced = useReducedMotion()
+  const scrollRef = useRef<HTMLDivElement>(null)
+  const [paused, setPaused] = useState(false)
+  const [userScrolled, setUserScrolled] = useState(false)
+  const [newCount, setNewCount] = useState(0)
+  const prevCountRef = useRef(items.length)
+
+  // Track new items arriving while scrolled away
+  useEffect(() => {
+    const diff = items.length - prevCountRef.current
+    if (diff > 0 && (paused || userScrolled)) {
+      setNewCount((c) => c + diff)
+    }
+    prevCountRef.current = items.length
+  }, [items.length, paused, userScrolled])
+
+  // Auto-scroll
+  useEffect(() => {
+    if (autoScrollProp && !paused && !userScrolled && scrollRef.current) {
+      scrollRef.current.scrollTop = 0
+    }
+  }, [items, autoScrollProp, paused, userScrolled])
+
+  const handleScroll = useCallback(() => {
+    if (!scrollRef.current) return
+    const { scrollTop } = scrollRef.current
+    // scrollTop is 0 at top (newest), positive when scrolled down (older)
+    setUserScrolled(scrollTop > 40)
+  }, [])
+
+  const scrollToTop = useCallback(() => {
+    if (scrollRef.current) {
+      scrollRef.current.scrollTop = 0
+    }
+    setUserScrolled(false)
+    setNewCount(0)
+  }, [])
+
+  const togglePause = useCallback(() => {
+    setPaused((p) => {
+      if (p) {
+        setNewCount(0)
+        setUserScrolled(false)
+      }
+      return !p
+    })
+  }, [])
+
+  // Relative timestamp updater
+  const [, setTick] = useState(0)
+  useEffect(() => {
+    if (!showTimestamps) return
+    const id = setInterval(() => setTick((t) => t + 1), 10_000)
+    return () => clearInterval(id)
+  }, [showTimestamps])
+
+  const visibleItems = items.slice(0, maxVisible)
+
+  return (
+    <div className={cn('relative flex flex-col', className)}>
+      {/* Controls bar */}
+      <div className="flex items-center justify-between px-3 py-2 border-b border-[hsl(var(--border-subtle))]">
+        <span className="text-xs font-medium text-[hsl(var(--text-secondary))]">
+          {items.length} events
+        </span>
+        <button
+          type="button"
+          onClick={togglePause}
+          className={cn(
+            'inline-flex items-center gap-1 px-2 py-1 rounded-md text-xs font-medium cursor-pointer',
+            'text-[hsl(var(--text-secondary))] hover:text-[hsl(var(--text-primary))]',
+            'hover:bg-[hsl(var(--bg-overlay))] transition-colors duration-150',
+          )}
+          aria-label={paused ? 'Resume auto-scroll' : 'Pause auto-scroll'}
+        >
+          {paused ? <Play className="size-3" /> : <Pause className="size-3" />}
+          {paused ? 'Resume' : 'Pause'}
+        </button>
+      </div>
+
+      {/* Feed container */}
+      <div
+        ref={scrollRef}
+        onScroll={handleScroll}
+        className="flex-1 overflow-y-auto"
+      >
+        {visibleItems.length === 0 ? (
+          <div className="flex items-center justify-center py-12 text-sm text-[hsl(var(--text-tertiary))]">
+            {emptyMessage}
+          </div>
+        ) : (
+          <AnimatePresence initial={false}>
+            {visibleItems.map((item) => (
+              <motion.div
+                key={item.id}
+                layout={!reduced}
+                initial={reduced ? undefined : { opacity: 0, y: -12, height: 0 }}
+                animate={{ opacity: 1, y: 0, height: 'auto' }}
+                exit={reduced ? undefined : { opacity: 0, height: 0 }}
+                transition={{ duration: reduced ? 0 : 0.2 }}
+              >
+                <div
+                  role={onItemClick ? 'button' : undefined}
+                  tabIndex={onItemClick ? 0 : undefined}
+                  onClick={onItemClick ? () => onItemClick(item) : undefined}
+                  onKeyDown={
+                    onItemClick
+                      ? (e) => { if (e.key === 'Enter' || e.key === ' ') onItemClick(item) }
+                      : undefined
+                  }
+                  className={cn(
+                    'flex items-start gap-3 px-3 py-2.5 border-l-2',
+                    'border-b border-b-[hsl(var(--border-subtle))]',
+                    TYPE_BORDER[item.type ?? 'info'],
+                    onItemClick && 'cursor-pointer hover:bg-[hsl(var(--bg-surface))] transition-colors duration-100',
+                  )}
+                >
+                  <div className="flex-1 min-w-0 text-sm text-[hsl(var(--text-primary))]">
+                    {item.content}
+                  </div>
+                  {showTimestamps && (
+                    <span
+                      className="shrink-0 text-[10px] tabular-nums text-[hsl(var(--text-tertiary))] mt-0.5"
+                      title={new Date(item.timestamp).toISOString()}
+                    >
+                      {relativeTime(item.timestamp)}
+                    </span>
+                  )}
+                </div>
+              </motion.div>
+            ))}
+          </AnimatePresence>
+        )}
+      </div>
+
+      {/* "N new items" floating badge */}
+      <AnimatePresence>
+        {newCount > 0 && (userScrolled || paused) && (
+          <motion.button
+            type="button"
+            initial={reduced ? undefined : { opacity: 0, y: 8 }}
+            animate={{ opacity: 1, y: 0 }}
+            exit={reduced ? undefined : { opacity: 0, y: 8 }}
+            transition={{ duration: reduced ? 0 : 0.15 }}
+            onClick={scrollToTop}
+            className={cn(
+              'absolute top-12 left-1/2 -translate-x-1/2 z-10',
+              'inline-flex items-center gap-1 px-3 py-1.5 rounded-full',
+              'bg-[hsl(var(--brand-primary))] text-white text-xs font-medium',
+              'shadow-lg cursor-pointer hover:brightness-110 transition-[filter] duration-100',
+            )}
+          >
+            <ChevronUp className="size-3" />
+            {newCount} new {newCount === 1 ? 'item' : 'items'}
+          </motion.button>
+        )}
+      </AnimatePresence>
+    </div>
+  )
+}

package/src/components/log-viewer.tsx

@@ -1,5 +1,6 @@
 'use client'
 
+import type React from 'react'
 import { useCallback, useEffect, useRef, useState } from 'react'
 import { motion, AnimatePresence, useReducedMotion } from 'framer-motion'
 import { ArrowDown, Search } from 'lucide-react'
@@ -78,7 +79,7 @@ export function LogViewer({
   showLevel = true,
   onEntryClick,
   className,
-}: LogViewerProps) {
+}: LogViewerProps): React.JSX.Element {
   const reduced = useReducedMotion()
   const containerRef = useRef<HTMLDivElement>(null)
   const [isAtBottom, setIsAtBottom] = useState(true)

package/src/components/metric-card.tsx

@@ -1,5 +1,6 @@
 'use client'
 
+import type React from 'react'
 import { type ElementType } from 'react'
 import { motion, useReducedMotion } from 'framer-motion'
 import { TrendingUp, TrendingDown } from 'lucide-react'
@@ -53,7 +54,7 @@ export function MetricCard({
   status,
   sparklineData,
   className,
-}: MetricCardProps) {
+}: MetricCardProps): React.JSX.Element {
   const reduced = useReducedMotion()
 
   // Trend calculation

package/src/components/notification-stack.tsx

@@ -0,0 +1,226 @@
+'use client'
+
+import type React from 'react'
+import { useEffect, useRef, useCallback, useState } from 'react'
+import { motion, AnimatePresence, useReducedMotion } from 'framer-motion'
+import { cn } from '../utils'
+import {
+  Info, CheckCircle2, AlertTriangle, XCircle, X,
+} from 'lucide-react'
+
+export interface Notification {
+  id: string
+  title: string
+  message?: string
+  type: 'info' | 'success' | 'warning' | 'error'
+  action?: { label: string; onClick: () => void }
+  /** Whether the notification can be dismissed. */
+  dismissible?: boolean
+  /** Auto-dismiss after this many ms. 0 = persistent. */
+  duration?: number
+  timestamp?: Date
+}
+
+export interface NotificationStackProps {
+  notifications: Notification[]
+  /** Callback to dismiss a notification by id. */
+  onDismiss: (id: string) => void
+  /** Screen corner positioning. */
+  position?: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left'
+  /** Max visible cards before stacking remainder. */
+  maxVisible?: number
+  className?: string
+}
+
+const TYPE_ICON: Record<Notification['type'], React.FC<{ className?: string }>> = {
+  info: Info,
+  success: CheckCircle2,
+  warning: AlertTriangle,
+  error: XCircle,
+}
+
+const TYPE_COLOR: Record<Notification['type'], string> = {
+  info: 'border-l-[hsl(var(--brand-secondary))]',
+  success: 'border-l-[hsl(var(--status-ok))]',
+  warning: 'border-l-[hsl(var(--status-warning))]',
+  error: 'border-l-[hsl(var(--status-critical))]',
+}
+
+const TYPE_ICON_COLOR: Record<Notification['type'], string> = {
+  info: 'text-[hsl(var(--brand-secondary))]',
+  success: 'text-[hsl(var(--status-ok))]',
+  warning: 'text-[hsl(var(--status-warning))]',
+  error: 'text-[hsl(var(--status-critical))]',
+}
+
+const POSITION_CLASSES: Record<NonNullable<NotificationStackProps['position']>, string> = {
+  'top-right': 'top-4 right-4',
+  'top-left': 'top-4 left-4',
+  'bottom-right': 'bottom-4 right-4',
+  'bottom-left': 'bottom-4 left-4',
+}
+
+const SLIDE_FROM: Record<NonNullable<NotificationStackProps['position']>, { x: number }> = {
+  'top-right': { x: 80 },
+  'top-left': { x: -80 },
+  'bottom-right': { x: 80 },
+  'bottom-left': { x: -80 },
+}
+
+/**
+ * @description A fixed-position notification stack with auto-dismiss progress bars,
+ * type-specific icons and colors, action buttons, and stacking overflow.
+ */
+export function NotificationStack({
+  notifications,
+  onDismiss,
+  position = 'top-right',
+  maxVisible = 5,
+  className,
+}: NotificationStackProps): React.JSX.Element {
+  const reduced = useReducedMotion()
+  const visible = notifications.slice(0, maxVisible)
+  const overflow = notifications.length - maxVisible
+
+  return (
+    <div
+      className={cn(
+        'fixed z-50 flex flex-col gap-2 w-[360px] max-w-[calc(100vw-2rem)]',
+        POSITION_CLASSES[position],
+        className,
+      )}
+      role="region"
+      aria-label="Notifications"
+    >
+      <AnimatePresence initial={false}>
+        {visible.map((notification, idx) => (
+          <motion.div
+            key={notification.id}
+            layout={!reduced}
+            initial={reduced ? { opacity: 1 } : { opacity: 0, ...SLIDE_FROM[position] }}
+            animate={{ opacity: 1, x: 0 }}
+            exit={reduced ? { opacity: 0 } : { opacity: 0, ...SLIDE_FROM[position], transition: { duration: 0.15 } }}
+            transition={{ type: 'spring', stiffness: 300, damping: 30 }}
+          >
+            <NotificationCard
+              notification={notification}
+              onDismiss={onDismiss}
+              reduced={!!reduced}
+            />
+          </motion.div>
+        ))}
+      </AnimatePresence>
+
+      {/* Overflow indicator */}
+      {overflow > 0 && (
+        <div className="text-center text-xs text-[hsl(var(--text-tertiary))] py-1">
+          +{overflow} more {overflow === 1 ? 'notification' : 'notifications'}
+        </div>
+      )}
+    </div>
+  )
+}
+
+function NotificationCard({
+  notification,
+  onDismiss,
+  reduced,
+}: {
+  notification: Notification
+  onDismiss: (id: string) => void
+  reduced: boolean
+}): React.JSX.Element {
+  const { id, title, message, type, action, dismissible = true, duration = 0 } = notification
+  const Icon = TYPE_ICON[type]
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+  const [progress, setProgress] = useState(100)
+  const startTimeRef = useRef(Date.now())
+
+  // Auto-dismiss timer
+  useEffect(() => {
+    if (duration <= 0) return
+
+    startTimeRef.current = Date.now()
+
+    // Progress countdown
+    const intervalId = setInterval(() => {
+      const elapsed = Date.now() - startTimeRef.current
+      const remaining = Math.max(0, 100 - (elapsed / duration) * 100)
+      setProgress(remaining)
+      if (remaining <= 0) {
+        clearInterval(intervalId)
+      }
+    }, 50)
+
+    timerRef.current = setTimeout(() => {
+      onDismiss(id)
+    }, duration)
+
+    return () => {
+      clearInterval(intervalId)
+      if (timerRef.current) clearTimeout(timerRef.current)
+    }
+  }, [id, duration, onDismiss])
+
+  const handleDismiss = useCallback(() => {
+    onDismiss(id)
+  }, [id, onDismiss])
+
+  return (
+    <div
+      className={cn(
+        'relative overflow-hidden rounded-xl border-l-[3px] shadow-lg',
+        'bg-[hsl(var(--bg-elevated))] border border-[hsl(var(--border-subtle))]',
+        TYPE_COLOR[type],
+      )}
+    >
+      <div className="flex items-start gap-3 p-4">
+        <Icon className={cn('size-5 shrink-0 mt-0.5', TYPE_ICON_COLOR[type])} />
+        <div className="flex-1 min-w-0">
+          <p className="text-sm font-medium text-[hsl(var(--text-primary))]">{title}</p>
+          {message && (
+            <p className="mt-0.5 text-xs text-[hsl(var(--text-secondary))] line-clamp-2">
+              {message}
+            </p>
+          )}
+          {action && (
+            <button
+              type="button"
+              onClick={action.onClick}
+              className={cn(
+                'mt-2 text-xs font-medium cursor-pointer',
+                'text-[hsl(var(--brand-primary))] hover:underline',
+              )}
+            >
+              {action.label}
+            </button>
+          )}
+        </div>
+        {dismissible && (
+          <button
+            type="button"
+            onClick={handleDismiss}
+            className={cn(
+              'shrink-0 p-0.5 rounded cursor-pointer',
+              'text-[hsl(var(--text-tertiary))] hover:text-[hsl(var(--text-primary))]',
+              'hover:bg-[hsl(var(--bg-overlay))] transition-colors duration-100',
+            )}
+            aria-label="Dismiss notification"
+          >
+            <X className="size-3.5" />
+          </button>
+        )}
+      </div>
+
+      {/* Auto-dismiss progress bar */}
+      {duration > 0 && (
+        <div className="h-0.5 bg-[hsl(var(--bg-overlay))]">
+          <div
+            className={cn('h-full transition-[width] duration-100', TYPE_COLOR[type].replace('border-l-', 'bg-'))}
+            style={{ width: `${progress}%` }}
+          />
+        </div>
+      )}
+    </div>
+  )
+}

package/src/components/pipeline-stage.tsx

@@ -1,5 +1,6 @@
 'use client'
 
+import type React from 'react'
 import { type ElementType } from 'react'
 import { motion, useReducedMotion } from 'framer-motion'
 import { ChevronRight } from 'lucide-react'
@@ -54,7 +55,7 @@ export function PipelineStage({
   stages,
   onStageClick,
   className,
-}: PipelineStageProps) {
+}: PipelineStageProps): React.JSX.Element {
   const reduced = useReducedMotion()
 
   return (

package/src/components/popover.tsx

@@ -1,5 +1,6 @@
 'use client'
 
+import type React from 'react'
 import { type ReactNode } from 'react'
 import * as PopoverPrimitive from '@radix-ui/react-popover'
 import { motion, AnimatePresence, useReducedMotion } from 'framer-motion'
@@ -28,7 +29,7 @@ const contentVariants = {
  * @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) {
+export function Popover({ trigger, children, side = 'bottom', align = 'center', className }: PopoverProps): React.JSX.Element {
   const prefersReducedMotion = useReducedMotion()
 
   return (

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

@@ -1,5 +1,6 @@
 'use client'
 
+import type React from 'react'
 import { motion, useReducedMotion } from 'framer-motion'
 import { cn } from '../utils'
 
@@ -58,7 +59,7 @@ export function PortStatusGrid({
   size = 'sm',
   onPortClick,
   className,
-}: PortStatusGridProps) {
+}: PortStatusGridProps): React.JSX.Element {
   const reduced = useReducedMotion()
 
   const gridStyle = columns

package/src/components/progress.tsx

@@ -1,5 +1,6 @@
 'use client'
 
+import type React from 'react'
 import { motion, useReducedMotion } from 'framer-motion'
 import { cn } from '../utils'
 
@@ -51,7 +52,7 @@ export function Progress({
   animated = true,
   indeterminate = false,
   className,
-}: ProgressProps) {
+}: ProgressProps): React.JSX.Element {
   const prefersReducedMotion = useReducedMotion()
   const pct = Math.min(100, Math.max(0, (value / max) * 100))
 

package/src/components/radio-group.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 { cn } from '../utils'
@@ -39,7 +40,7 @@ export function RadioGroup({
   onChange,
   orientation = 'vertical',
   className,
-}: RadioGroupProps) {
+}: RadioGroupProps): React.JSX.Element {
   const prefersReducedMotion = useReducedMotion()
   const groupRef = useRef<HTMLDivElement>(null)