@annondeveloper/ui-kit 0.1.0 → 0.2.0

package/src/components/heatmap-calendar.tsx

@@ -0,0 +1,213 @@
+'use client'
+
+import type React from 'react'
+import { useMemo, useState } from 'react'
+import { cn } from '../utils'
+
+export interface DayValue {
+  /** Date in YYYY-MM-DD format. */
+  date: string
+  /** Numeric value for this day. */
+  value: number
+}
+
+export interface HeatmapCalendarProps {
+  /** Array of day values. */
+  data: DayValue[]
+  /** Start date (YYYY-MM-DD). Defaults to 365 days ago. */
+  startDate?: string
+  /** End date (YYYY-MM-DD). Defaults to today. */
+  endDate?: string
+  /** 5 colors from lightest to darkest. Defaults to green scale. */
+  colorScale?: string[]
+  /** Callback when a day cell is clicked. */
+  onDayClick?: (day: DayValue) => void
+  /** Show month labels at top. */
+  showMonthLabels?: boolean
+  /** Show day-of-week labels (Mon, Wed, Fri) on the left. */
+  showDayLabels?: boolean
+  /** Custom tooltip format function. */
+  tooltipFormat?: (day: DayValue) => string
+  className?: string
+}
+
+const DEFAULT_COLORS = [
+  'bg-[hsl(var(--bg-overlay))]',
+  'bg-[hsl(var(--status-ok))]/20',
+  'bg-[hsl(var(--status-ok))]/40',
+  'bg-[hsl(var(--status-ok))]/65',
+  'bg-[hsl(var(--status-ok))]',
+]
+
+const MONTH_NAMES = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']
+const DAY_LABELS = ['', 'Mon', '', 'Wed', '', 'Fri', '']
+
+function toDateKey(d: Date): string {
+  return d.toISOString().slice(0, 10)
+}
+
+function parseDate(s: string): Date {
+  const [y, m, d] = s.split('-').map(Number)
+  return new Date(y, m - 1, d)
+}
+
+/**
+ * @description A GitHub-style contribution heatmap calendar with configurable color scale,
+ * hover tooltips, month/day labels, and click handlers.
+ */
+export function HeatmapCalendar({
+  data,
+  startDate,
+  endDate,
+  colorScale = DEFAULT_COLORS,
+  onDayClick,
+  showMonthLabels = true,
+  showDayLabels = true,
+  tooltipFormat,
+  className,
+}: HeatmapCalendarProps): React.JSX.Element {
+  const [hoveredDay, setHoveredDay] = useState<DayValue | null>(null)
+
+  const { weeks, months, maxValue } = useMemo(() => {
+    const end = endDate ? parseDate(endDate) : new Date()
+    const start = startDate
+      ? parseDate(startDate)
+      : new Date(end.getFullYear() - 1, end.getMonth(), end.getDate() + 1)
+
+    // Build value lookup
+    const lookup = new Map<string, number>()
+    let maxVal = 0
+    for (const d of data) {
+      lookup.set(d.date, d.value)
+      if (d.value > maxVal) maxVal = d.value
+    }
+
+    // Generate weeks (columns) starting from the start date's week
+    const weeks: (DayValue | null)[][] = []
+    const monthChanges: { col: number; label: string }[] = []
+
+    // Align start to the beginning of its week (Sunday)
+    const cursor = new Date(start)
+    cursor.setDate(cursor.getDate() - cursor.getDay())
+
+    let prevMonth = -1
+
+    while (cursor <= end || weeks.length === 0) {
+      const week: (DayValue | null)[] = []
+      for (let dow = 0; dow < 7; dow++) {
+        const key = toDateKey(cursor)
+        if (cursor >= start && cursor <= end) {
+          week.push({ date: key, value: lookup.get(key) ?? 0 })
+        } else {
+          week.push(null)
+        }
+
+        // Track month boundaries
+        if (cursor.getMonth() !== prevMonth && cursor >= start && cursor <= end) {
+          if (dow === 0) {
+            monthChanges.push({ col: weeks.length, label: MONTH_NAMES[cursor.getMonth()] })
+          }
+          prevMonth = cursor.getMonth()
+        }
+
+        cursor.setDate(cursor.getDate() + 1)
+      }
+      weeks.push(week)
+    }
+
+    return { weeks, months: monthChanges, maxValue: maxVal }
+  }, [data, startDate, endDate])
+
+  const getColorClass = (value: number): string => {
+    if (value === 0 || maxValue === 0) return colorScale[0]
+    const idx = Math.min(
+      colorScale.length - 1,
+      Math.ceil((value / maxValue) * (colorScale.length - 1))
+    )
+    return colorScale[idx]
+  }
+
+  const defaultTooltip = (day: DayValue): string =>
+    `${day.date}: ${day.value}`
+
+  const formatTooltip = tooltipFormat ?? defaultTooltip
+
+  return (
+    <div className={cn('overflow-x-auto', className)}>
+      <div className="inline-flex flex-col gap-0.5">
+        {/* Month labels */}
+        {showMonthLabels && (
+          <div className="flex" style={{ marginLeft: showDayLabels ? '2rem' : 0 }}>
+            {weeks.map((_, col) => {
+              const monthEntry = months.find((m) => m.col === col)
+              return (
+                <div
+                  key={`m-${col}`}
+                  className="text-[10px] text-[hsl(var(--text-tertiary))]"
+                  style={{ width: 13, minWidth: 13 }}
+                >
+                  {monthEntry?.label ?? ''}
+                </div>
+              )
+            })}
+          </div>
+        )}
+
+        {/* Grid rows (7 days) */}
+        <div className="flex gap-0">
+          {/* Day labels column */}
+          {showDayLabels && (
+            <div className="flex flex-col gap-[2px] mr-1">
+              {DAY_LABELS.map((label, i) => (
+                <div
+                  key={i}
+                  className="text-[10px] text-[hsl(var(--text-tertiary))] h-[11px] flex items-center justify-end pr-1"
+                  style={{ width: '1.75rem' }}
+                >
+                  {label}
+                </div>
+              ))}
+            </div>
+          )}
+
+          {/* Week columns */}
+          {weeks.map((week, wIdx) => (
+            <div key={wIdx} className="flex flex-col gap-[2px]">
+              {week.map((day, dIdx) => (
+                <div
+                  key={dIdx}
+                  className={cn(
+                    'w-[11px] h-[11px] rounded-sm',
+                    day ? getColorClass(day.value) : 'bg-transparent',
+                    day && onDayClick && 'cursor-pointer',
+                    day && 'hover:ring-1 hover:ring-[hsl(var(--text-tertiary))]',
+                  )}
+                  onClick={day && onDayClick ? () => onDayClick(day) : undefined}
+                  onMouseEnter={day ? () => setHoveredDay(day) : undefined}
+                  onMouseLeave={() => setHoveredDay(null)}
+                  title={day ? formatTooltip(day) : undefined}
+                  role={day && onDayClick ? 'button' : undefined}
+                  tabIndex={day && onDayClick ? 0 : undefined}
+                  onKeyDown={
+                    day && onDayClick
+                      ? (e) => { if (e.key === 'Enter' || e.key === ' ') onDayClick(day) }
+                      : undefined
+                  }
+                />
+              ))}
+            </div>
+          ))}
+        </div>
+
+        {/* Legend */}
+        <div className="flex items-center gap-1 mt-1" style={{ marginLeft: showDayLabels ? '2rem' : 0 }}>
+          <span className="text-[10px] text-[hsl(var(--text-tertiary))] mr-1">Less</span>
+          {colorScale.map((color, i) => (
+            <div key={i} className={cn('w-[11px] h-[11px] rounded-sm', color)} />
+          ))}
+          <span className="text-[10px] text-[hsl(var(--text-tertiary))] ml-1">More</span>
+        </div>
+      </div>
+    </div>
+  )
+}

package/src/components/infinite-scroll.tsx

@@ -0,0 +1,243 @@
+'use client'
+
+import type React from 'react'
+import { useState, useEffect, useRef, useCallback, useMemo } from 'react'
+import { motion, AnimatePresence, useReducedMotion } from 'framer-motion'
+import { ArrowUp, Loader2 } from 'lucide-react'
+import { cn } from '../utils'
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Props for the InfiniteScroll component. */
+export interface InfiniteScrollProps<T> {
+  /** Array of loaded items. */
+  items: T[]
+  /** Render function for each item. */
+  renderItem: (item: T, index: number) => React.JSX.Element
+  /** Called when more items should be loaded. */
+  loadMore: () => void | Promise<void>
+  /** Whether more items are available. */
+  hasMore: boolean
+  /** Whether a load operation is in progress. */
+  isLoading?: boolean
+  /** Pixels from bottom to trigger loadMore. Default 200. */
+  threshold?: number
+  /** Fixed item height for virtualization. If omitted, all items render (no virtualization). */
+  itemHeight?: number
+  /** Content to display when items array is empty. */
+  emptyState?: React.ReactNode
+  /** Additional class name for the scroll container. */
+  className?: string
+}
+
+// ---------------------------------------------------------------------------
+// InfiniteScroll
+// ---------------------------------------------------------------------------
+
+/**
+ * @description A virtualized infinite-scroll list using IntersectionObserver.
+ * Supports optional height-based virtualization, loading indicators, scroll-to-top,
+ * empty states, and skeleton placeholders. No scroll event listeners used.
+ */
+export function InfiniteScroll<T>({
+  items,
+  renderItem,
+  loadMore,
+  hasMore,
+  isLoading = false,
+  threshold = 200,
+  itemHeight,
+  emptyState,
+  className,
+}: InfiniteScrollProps<T>): React.JSX.Element {
+  const prefersReducedMotion = useReducedMotion()
+  const containerRef = useRef<HTMLDivElement>(null)
+  const sentinelRef = useRef<HTMLDivElement>(null)
+  const [showScrollTop, setShowScrollTop] = useState(false)
+  const loadingRef = useRef(false)
+
+  // IntersectionObserver for infinite load trigger
+  useEffect(() => {
+    const sentinel = sentinelRef.current
+    if (!sentinel) return
+
+    const observer = new IntersectionObserver(
+      (entries) => {
+        const entry = entries[0]
+        if (entry?.isIntersecting && hasMore && !isLoading && !loadingRef.current) {
+          loadingRef.current = true
+          const result = loadMore()
+          if (result && typeof result.then === 'function') {
+            result.then(() => { loadingRef.current = false }).catch(() => { loadingRef.current = false })
+          } else {
+            loadingRef.current = false
+          }
+        }
+      },
+      {
+        root: containerRef.current,
+        rootMargin: `0px 0px ${threshold}px 0px`,
+      },
+    )
+
+    observer.observe(sentinel)
+    return () => observer.disconnect()
+  }, [hasMore, isLoading, loadMore, threshold])
+
+  // Update loadingRef when isLoading changes
+  useEffect(() => {
+    if (!isLoading) loadingRef.current = false
+  }, [isLoading])
+
+  // Scroll position tracking for scroll-to-top button
+  useEffect(() => {
+    const container = containerRef.current
+    if (!container) return
+
+    const handler = () => {
+      setShowScrollTop(container.scrollTop > 400)
+    }
+    container.addEventListener('scroll', handler, { passive: true })
+    return () => container.removeEventListener('scroll', handler)
+  }, [])
+
+  const scrollToTop = useCallback(() => {
+    containerRef.current?.scrollTo({ top: 0, behavior: prefersReducedMotion ? 'instant' : 'smooth' })
+  }, [prefersReducedMotion])
+
+  // Virtualization
+  const [scrollTop, setScrollTop] = useState(0)
+  const containerHeight = useRef(0)
+
+  useEffect(() => {
+    if (!itemHeight) return
+    const container = containerRef.current
+    if (!container) return
+
+    containerHeight.current = container.clientHeight
+    const handler = () => {
+      setScrollTop(container.scrollTop)
+      containerHeight.current = container.clientHeight
+    }
+    container.addEventListener('scroll', handler, { passive: true })
+    return () => container.removeEventListener('scroll', handler)
+  }, [itemHeight])
+
+  const virtualizedContent = useMemo(() => {
+    if (!itemHeight) return null
+
+    const visibleHeight = containerHeight.current || 600
+    const buffer = 5
+    const startIdx = Math.max(0, Math.floor(scrollTop / itemHeight) - buffer)
+    const endIdx = Math.min(
+      items.length,
+      Math.ceil((scrollTop + visibleHeight) / itemHeight) + buffer,
+    )
+
+    const totalHeight = items.length * itemHeight
+    const offsetTop = startIdx * itemHeight
+
+    return {
+      totalHeight,
+      offsetTop,
+      visibleItems: items.slice(startIdx, endIdx),
+      startIdx,
+    }
+  }, [items, itemHeight, scrollTop])
+
+  // Empty state
+  if (items.length === 0 && !isLoading && !hasMore) {
+    return (
+      <div className={cn('flex items-center justify-center min-h-[200px]', className)}>
+        {emptyState ?? (
+          <div className="text-center py-12">
+            <p className="text-sm text-[hsl(var(--text-tertiary))]">No items to display.</p>
+          </div>
+        )}
+      </div>
+    )
+  }
+
+  return (
+    <div
+      ref={containerRef}
+      className={cn('relative overflow-y-auto', className)}
+    >
+      {/* Virtualized rendering */}
+      {virtualizedContent ? (
+        <div style={{ height: virtualizedContent.totalHeight, position: 'relative' }}>
+          <div style={{ position: 'absolute', top: virtualizedContent.offsetTop, left: 0, right: 0 }}>
+            {virtualizedContent.visibleItems.map((item, i) => (
+              <div key={virtualizedContent.startIdx + i} style={{ height: itemHeight }}>
+                {renderItem(item, virtualizedContent.startIdx + i)}
+              </div>
+            ))}
+          </div>
+        </div>
+      ) : (
+        /* Non-virtualized rendering */
+        items.map((item, index) => (
+          <div key={index}>
+            {renderItem(item, index)}
+          </div>
+        ))
+      )}
+
+      {/* Loading indicator */}
+      {isLoading && (
+        <div className="flex items-center justify-center py-6 gap-2">
+          <Loader2 className="h-5 w-5 text-[hsl(var(--brand-primary))] animate-spin" />
+          <span className="text-sm text-[hsl(var(--text-tertiary))]">Loading more...</span>
+        </div>
+      )}
+
+      {/* Skeleton placeholders while loading with no items yet */}
+      {isLoading && items.length === 0 && (
+        <div className="space-y-3 p-4">
+          {Array.from({ length: 6 }).map((_, i) => (
+            <div key={i} className="skeleton-shimmer h-16 rounded-xl" />
+          ))}
+        </div>
+      )}
+
+      {/* No more items */}
+      {!hasMore && items.length > 0 && (
+        <div className="py-4 text-center">
+          <span className="text-[11px] text-[hsl(var(--text-tertiary))]">
+            All {items.length} item{items.length !== 1 ? 's' : ''} loaded
+          </span>
+        </div>
+      )}
+
+      {/* Sentinel for IntersectionObserver */}
+      <div ref={sentinelRef} className="h-px w-full" aria-hidden="true" />
+
+      {/* Scroll to top button */}
+      <AnimatePresence>
+        {showScrollTop && (
+          <motion.button
+            initial={prefersReducedMotion ? undefined : { opacity: 0, scale: 0.8 }}
+            animate={prefersReducedMotion ? undefined : { opacity: 1, scale: 1 }}
+            exit={prefersReducedMotion ? undefined : { opacity: 0, scale: 0.8 }}
+            transition={{ duration: 0.15 }}
+            onClick={scrollToTop}
+            className={cn(
+              'sticky bottom-4 left-1/2 -translate-x-1/2 z-10',
+              'inline-flex items-center gap-1.5 rounded-full',
+              'px-3 py-2 text-[11px] font-medium',
+              'bg-[hsl(var(--bg-elevated))] border border-[hsl(var(--border-default))]',
+              'text-[hsl(var(--text-secondary))] shadow-lg',
+              'hover:bg-[hsl(var(--bg-overlay))] hover:text-[hsl(var(--text-primary))] transition-colors',
+              'cursor-pointer',
+            )}
+          >
+            <ArrowUp className="h-3.5 w-3.5" />
+            Back to top
+          </motion.button>
+        )}
+      </AnimatePresence>
+    </div>
+  )
+}

package/src/components/kanban-column.tsx

@@ -0,0 +1,198 @@
+'use client'
+
+import type React from 'react'
+import { motion, useReducedMotion } from 'framer-motion'
+import { cn } from '../utils'
+import { Plus } from 'lucide-react'
+
+export type KanbanBadgeColor =
+  | 'brand' | 'blue' | 'green' | 'yellow' | 'red' | 'orange'
+  | 'purple' | 'pink' | 'teal' | 'gray'
+
+export interface KanbanItem {
+  id: string
+  title: string
+  description?: string
+  tags?: { label: string; color: KanbanBadgeColor }[]
+  assignee?: { name: string; avatar?: string }
+}
+
+export interface KanbanColumnProps {
+  /** Column title. */
+  title: string
+  /** Items to display in this column. */
+  items: KanbanItem[]
+  /** Optional override for the count badge. */
+  count?: number
+  /** Column header accent color (CSS value or token). */
+  color?: string
+  /** Callback when a card is clicked. */
+  onItemClick?: (item: KanbanItem) => void
+  /** Callback when the add button is clicked. */
+  onAddItem?: () => void
+  className?: string
+}
+
+const TAG_COLOR_MAP: Record<KanbanBadgeColor, string> = {
+  brand:  'bg-[hsl(var(--brand-primary))]/15 text-[hsl(var(--brand-primary))]',
+  blue:   'bg-[hsl(var(--brand-secondary))]/15 text-[hsl(var(--brand-secondary))]',
+  green:  'bg-[hsl(var(--status-ok))]/15 text-[hsl(var(--status-ok))]',
+  yellow: 'bg-[hsl(var(--status-warning))]/15 text-[hsl(var(--status-warning))]',
+  red:    'bg-[hsl(var(--status-critical))]/15 text-[hsl(var(--status-critical))]',
+  orange: 'bg-[hsl(var(--status-warning))]/20 text-[hsl(var(--status-warning))]',
+  purple: 'bg-[hsl(270,60%,60%)]/15 text-[hsl(270,60%,65%)]',
+  pink:   'bg-[hsl(330,60%,60%)]/15 text-[hsl(330,60%,65%)]',
+  teal:   'bg-[hsl(180,60%,40%)]/15 text-[hsl(180,60%,55%)]',
+  gray:   'bg-[hsl(var(--bg-overlay))] text-[hsl(var(--text-secondary))]',
+}
+
+/**
+ * @description A kanban board column with title, count badge, scrollable card list,
+ * hover states, staggered Framer Motion entrance, and empty state.
+ */
+export function KanbanColumn({
+  title,
+  items,
+  count,
+  color,
+  onItemClick,
+  onAddItem,
+  className,
+}: KanbanColumnProps): React.JSX.Element {
+  const reduced = useReducedMotion()
+  const displayCount = count ?? items.length
+
+  return (
+    <div
+      className={cn(
+        'flex flex-col w-72 min-w-[18rem] rounded-2xl',
+        'bg-[hsl(var(--bg-surface))] border border-[hsl(var(--border-subtle))]',
+        className,
+      )}
+    >
+      {/* Header */}
+      <div className="flex items-center justify-between px-4 py-3 border-b border-[hsl(var(--border-subtle))]">
+        <div className="flex items-center gap-2">
+          {color && (
+            <span
+              className="w-2 h-2 rounded-full shrink-0"
+              style={{ backgroundColor: color }}
+            />
+          )}
+          <span className="text-sm font-semibold text-[hsl(var(--text-primary))]">
+            {title}
+          </span>
+          <span className="inline-flex items-center justify-center min-w-[1.25rem] h-5 px-1.5 rounded-full text-[10px] font-medium tabular-nums bg-[hsl(var(--bg-overlay))] text-[hsl(var(--text-secondary))]">
+            {displayCount}
+          </span>
+        </div>
+        {onAddItem && (
+          <button
+            type="button"
+            onClick={onAddItem}
+            className={cn(
+              'p-1 rounded-lg cursor-pointer',
+              'text-[hsl(var(--text-tertiary))] hover:text-[hsl(var(--text-primary))]',
+              'hover:bg-[hsl(var(--bg-overlay))] transition-colors duration-150',
+            )}
+            aria-label={`Add item to ${title}`}
+          >
+            <Plus className="size-4" />
+          </button>
+        )}
+      </div>
+
+      {/* Card list */}
+      <div className="flex-1 overflow-y-auto p-2 space-y-2">
+        {items.length === 0 ? (
+          <div className="flex items-center justify-center py-8 text-xs text-[hsl(var(--text-tertiary))]">
+            No items
+          </div>
+        ) : (
+          items.map((item, idx) => (
+            <motion.div
+              key={item.id}
+              initial={reduced ? undefined : { opacity: 0, y: 8 }}
+              animate={{ opacity: 1, y: 0 }}
+              transition={reduced ? { duration: 0 } : { delay: idx * 0.04, duration: 0.2 }}
+            >
+              <KanbanCard item={item} onClick={onItemClick} />
+            </motion.div>
+          ))
+        )}
+      </div>
+    </div>
+  )
+}
+
+function KanbanCard({
+  item,
+  onClick,
+}: {
+  item: KanbanItem
+  onClick?: (item: KanbanItem) => void
+}): React.JSX.Element {
+  return (
+    <div
+      role={onClick ? 'button' : undefined}
+      tabIndex={onClick ? 0 : undefined}
+      onClick={onClick ? () => onClick(item) : undefined}
+      onKeyDown={
+        onClick
+          ? (e) => { if (e.key === 'Enter' || e.key === ' ') onClick(item) }
+          : undefined
+      }
+      className={cn(
+        'rounded-xl p-3 border border-[hsl(var(--border-subtle))]',
+        'bg-[hsl(var(--bg-base))]',
+        onClick && 'cursor-pointer hover:bg-[hsl(var(--bg-elevated))] hover:shadow-sm',
+        'transition-all duration-150',
+      )}
+    >
+      <p className="text-sm font-medium text-[hsl(var(--text-primary))] line-clamp-2">
+        {item.title}
+      </p>
+      {item.description && (
+        <p className="mt-1 text-xs text-[hsl(var(--text-secondary))] line-clamp-2">
+          {item.description}
+        </p>
+      )}
+
+      {/* Tags + Assignee row */}
+      {(item.tags?.length || item.assignee) && (
+        <div className="flex items-center justify-between mt-2.5 gap-2">
+          {item.tags && item.tags.length > 0 && (
+            <div className="flex flex-wrap gap-1 min-w-0">
+              {item.tags.map((tag, i) => (
+                <span
+                  key={i}
+                  className={cn(
+                    'inline-flex items-center px-1.5 py-0.5 rounded-full text-[10px] font-medium whitespace-nowrap',
+                    TAG_COLOR_MAP[tag.color],
+                  )}
+                >
+                  {tag.label}
+                </span>
+              ))}
+            </div>
+          )}
+          {item.assignee && (
+            <div className="shrink-0" title={item.assignee.name}>
+              {item.assignee.avatar ? (
+                <img
+                  src={item.assignee.avatar}
+                  alt={item.assignee.name}
+                  className="size-6 rounded-full object-cover"
+                />
+              ) : (
+                <div className="size-6 rounded-full bg-[hsl(var(--bg-overlay))] flex items-center justify-center text-[10px] font-semibold text-[hsl(var(--text-secondary))]">
+                  {item.assignee.name.slice(0, 2).toUpperCase()}
+                </div>
+              )}
+            </div>
+          )}
+        </div>
+      )}
+    </div>
+  )
+}