@annondeveloper/ui-kit 0.1.0

package/src/components/radio-group.tsx

@@ -0,0 +1,162 @@
+'use client'
+
+import { useCallback, useRef, type KeyboardEvent } from 'react'
+import { motion, useReducedMotion } from 'framer-motion'
+import { cn } from '../utils'
+
+/** A single radio option definition. */
+export interface RadioOption {
+  /** Unique value. */
+  value: string
+  /** Display label. */
+  label: string
+  /** Optional description text below the label. */
+  description?: string
+  /** Whether this option is disabled. */
+  disabled?: boolean
+}
+
+export interface RadioGroupProps {
+  /** Array of radio option definitions. */
+  options: RadioOption[]
+  /** Currently selected value. */
+  value: string
+  /** Callback when selection changes. */
+  onChange: (value: string) => void
+  /** Layout direction. */
+  orientation?: 'horizontal' | 'vertical'
+  /** Additional class name for the root element. */
+  className?: string
+}
+
+/**
+ * @description A custom-styled radio button group with Framer Motion selection indicator.
+ * Supports keyboard navigation (arrow keys, Home, End) and ARIA roles.
+ */
+export function RadioGroup({
+  options,
+  value,
+  onChange,
+  orientation = 'vertical',
+  className,
+}: RadioGroupProps) {
+  const prefersReducedMotion = useReducedMotion()
+  const groupRef = useRef<HTMLDivElement>(null)
+
+  const enabledOptions = options.filter((o) => !o.disabled)
+
+  const handleKeyDown = useCallback(
+    (e: KeyboardEvent<HTMLDivElement>) => {
+      const currentIdx = enabledOptions.findIndex((o) => o.value === value)
+      if (currentIdx === -1) return
+
+      const isVertical = orientation === 'vertical'
+      const nextKey = isVertical ? 'ArrowDown' : 'ArrowRight'
+      const prevKey = isVertical ? 'ArrowUp' : 'ArrowLeft'
+
+      let nextIdx: number | null = null
+
+      if (e.key === nextKey) {
+        e.preventDefault()
+        nextIdx = (currentIdx + 1) % enabledOptions.length
+      } else if (e.key === prevKey) {
+        e.preventDefault()
+        nextIdx = (currentIdx - 1 + enabledOptions.length) % enabledOptions.length
+      } else if (e.key === 'Home') {
+        e.preventDefault()
+        nextIdx = 0
+      } else if (e.key === 'End') {
+        e.preventDefault()
+        nextIdx = enabledOptions.length - 1
+      }
+
+      if (nextIdx !== null) {
+        onChange(enabledOptions[nextIdx].value)
+        const radios = groupRef.current?.querySelectorAll<HTMLDivElement>('[role="radio"]:not([aria-disabled="true"])')
+        radios?.[nextIdx]?.focus()
+      }
+    },
+    [enabledOptions, value, onChange, orientation],
+  )
+
+  return (
+    <div
+      ref={groupRef}
+      role="radiogroup"
+      aria-orientation={orientation}
+      onKeyDown={handleKeyDown}
+      className={cn(
+        'flex',
+        orientation === 'vertical' ? 'flex-col gap-2' : 'flex-row flex-wrap gap-4',
+        className,
+      )}
+    >
+      {options.map((option) => {
+        const isSelected = option.value === value
+
+        return (
+          <div
+            key={option.value}
+            role="radio"
+            aria-checked={isSelected}
+            aria-disabled={option.disabled}
+            tabIndex={isSelected ? 0 : -1}
+            onClick={() => {
+              if (!option.disabled) onChange(option.value)
+            }}
+            className={cn(
+              'flex items-start gap-3 cursor-pointer select-none group',
+              'focus-visible:outline-none',
+              option.disabled && 'opacity-40 pointer-events-none',
+            )}
+          >
+            {/* Radio circle */}
+            <div
+              className={cn(
+                'relative mt-0.5 h-[18px] w-[18px] shrink-0 rounded-full border-2 transition-colors duration-150',
+                'flex items-center justify-center',
+                isSelected
+                  ? 'border-[hsl(var(--brand-primary))]'
+                  : 'border-[hsl(var(--border-strong))] group-hover:border-[hsl(var(--brand-primary))]',
+                '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))]',
+              )}
+            >
+              {isSelected && (
+                <motion.div
+                  layoutId="radio-indicator"
+                  initial={prefersReducedMotion ? false : { scale: 0 }}
+                  animate={{ scale: 1 }}
+                  transition={
+                    prefersReducedMotion
+                      ? { duration: 0 }
+                      : { type: 'spring', stiffness: 500, damping: 30 }
+                  }
+                  className="h-2.5 w-2.5 rounded-full bg-[hsl(var(--brand-primary))]"
+                />
+              )}
+            </div>
+
+            {/* Label + description */}
+            <div className="min-w-0">
+              <span
+                className={cn(
+                  'text-sm font-medium',
+                  isSelected
+                    ? 'text-[hsl(var(--text-primary))]'
+                    : 'text-[hsl(var(--text-secondary))]',
+                )}
+              >
+                {option.label}
+              </span>
+              {option.description && (
+                <p className="mt-0.5 text-xs text-[hsl(var(--text-tertiary))]">
+                  {option.description}
+                </p>
+              )}
+            </div>
+          </div>
+        )
+      })}
+    </div>
+  )
+}

package/src/components/select.stories.tsx

@@ -0,0 +1,52 @@
+import type { Meta, StoryObj } from '@storybook/react'
+import { useState } from 'react'
+import { Select } from './select'
+
+const sampleOptions = [
+  { value: 'us-east', label: 'US East' },
+  { value: 'us-west', label: 'US West' },
+  { value: 'eu-central', label: 'EU Central' },
+  { value: 'ap-south', label: 'AP South' },
+]
+
+const meta: Meta<typeof Select> = {
+  title: 'Components/Select',
+  component: Select,
+  tags: ['autodocs'],
+  argTypes: {
+    disabled: { control: 'boolean' },
+    placeholder: { control: 'text' },
+  },
+}
+export default meta
+type Story = StoryObj<typeof Select>
+
+export const Default: Story = {
+  render: (args) => {
+    const [value, setValue] = useState('us-east')
+    return <Select {...args} value={value} onValueChange={setValue} options={sampleOptions} />
+  },
+  args: {},
+}
+
+export const WithPlaceholder: Story = {
+  render: (args) => {
+    const [value, setValue] = useState('')
+    return (
+      <Select
+        {...args}
+        value={value}
+        onValueChange={setValue}
+        options={sampleOptions}
+        placeholder="Select a region..."
+      />
+    )
+  },
+}
+
+export const Disabled: Story = {
+  render: () => {
+    const [value, setValue] = useState('eu-central')
+    return <Select value={value} onValueChange={setValue} options={sampleOptions} disabled />
+  },
+}

package/src/components/select.tsx

@@ -0,0 +1,92 @@
+'use client'
+
+import * as RadixSelect from '@radix-ui/react-select'
+import { ChevronDown, Check } from 'lucide-react'
+import { cn } from '../utils'
+
+export interface SelectOption {
+  value: string
+  label: string
+}
+
+export interface SelectProps {
+  /** Currently selected value. */
+  value: string
+  /** Callback when selection changes. */
+  onValueChange: (v: string) => void
+  /** Available options. */
+  options: SelectOption[]
+  /** Placeholder text when no value is selected. */
+  placeholder?: string
+  className?: string
+  /** Disable the select. */
+  disabled?: boolean
+}
+
+/**
+ * @description A themed select dropdown built on Radix UI Select.
+ * Supports dark/light mode via CSS custom property tokens.
+ */
+export function Select({
+  value, onValueChange, options, placeholder, className, disabled,
+}: SelectProps) {
+  return (
+    <RadixSelect.Root value={value} onValueChange={onValueChange} disabled={disabled}>
+      <RadixSelect.Trigger
+        suppressHydrationWarning
+        className={cn(
+          'flex w-full items-center justify-between gap-2 rounded-lg',
+          'border border-[hsl(var(--border-default))] bg-[hsl(var(--bg-base))]',
+          'px-3 py-2 text-sm text-[hsl(var(--text-primary))]',
+          'hover:border-[hsl(var(--border-strong))] focus:outline-none',
+          'focus:ring-2 focus:ring-[hsl(var(--brand-primary))]',
+          'disabled:opacity-50 disabled:cursor-not-allowed',
+          'data-[placeholder]:text-[hsl(var(--text-tertiary))]',
+          className,
+        )}
+      >
+        <RadixSelect.Value placeholder={placeholder} />
+        <RadixSelect.Icon>
+          <ChevronDown className="size-4 text-[hsl(var(--text-tertiary))] shrink-0" />
+        </RadixSelect.Icon>
+      </RadixSelect.Trigger>
+
+      <RadixSelect.Portal>
+        <RadixSelect.Content
+          position="popper"
+          sideOffset={4}
+          className={cn(
+            'z-50 min-w-[var(--radix-select-trigger-width)] overflow-hidden',
+            'rounded-xl border border-[hsl(var(--border-default))]',
+            'bg-[hsl(var(--bg-elevated))] shadow-xl',
+            'data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95',
+            'data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95',
+          )}
+        >
+          <RadixSelect.Viewport className="p-1">
+            {options.map((opt) => (
+              <RadixSelect.Item
+                key={opt.value}
+                value={opt.value}
+                className={cn(
+                  'relative flex cursor-pointer select-none items-center',
+                  'rounded-lg py-2 pl-8 pr-3 text-sm',
+                  'text-[hsl(var(--text-primary))]',
+                  'outline-none',
+                  'hover:bg-[hsl(var(--bg-overlay))]',
+                  'focus:bg-[hsl(var(--brand-primary))]/10 focus:text-[hsl(var(--brand-primary))]',
+                  'data-[state=checked]:text-[hsl(var(--brand-primary))]',
+                )}
+              >
+                <RadixSelect.ItemIndicator className="absolute left-2 flex items-center">
+                  <Check className="size-4" />
+                </RadixSelect.ItemIndicator>
+                <RadixSelect.ItemText>{opt.label}</RadixSelect.ItemText>
+              </RadixSelect.Item>
+            ))}
+          </RadixSelect.Viewport>
+        </RadixSelect.Content>
+      </RadixSelect.Portal>
+    </RadixSelect.Root>
+  )
+}

package/src/components/severity-timeline.tsx

@@ -0,0 +1,125 @@
+'use client'
+
+import { useRef } from 'react'
+import { motion, AnimatePresence, useReducedMotion } from 'framer-motion'
+import { cn } from '../utils'
+
+export interface TimelineEvent {
+  /** ISO 8601 timestamp. */
+  time: string
+  /** Short event label. */
+  label: string
+  /** Severity determines dot color. */
+  severity: 'critical' | 'warning' | 'info' | 'ok'
+  /** Optional detail text shown on click/hover. */
+  detail?: string
+}
+
+export interface SeverityTimelineProps {
+  /** Events to display (most recent should be first). */
+  events: TimelineEvent[]
+  /** Maximum number of visible events. */
+  maxVisible?: number
+  /** Callback when an event dot/label is clicked. */
+  onEventClick?: (event: TimelineEvent) => void
+  className?: string
+}
+
+const severityDot: Record<string, string> = {
+  critical: 'bg-[hsl(var(--status-critical))]',
+  warning: 'bg-[hsl(var(--status-warning))]',
+  info: 'bg-[hsl(var(--brand-primary))]',
+  ok: 'bg-[hsl(var(--status-ok))]',
+}
+
+const severityRing: Record<string, string> = {
+  critical: 'ring-[hsl(var(--status-critical))]/30',
+  warning: 'ring-[hsl(var(--status-warning))]/30',
+  info: 'ring-[hsl(var(--brand-primary))]/30',
+  ok: 'ring-[hsl(var(--status-ok))]/30',
+}
+
+function formatTime(iso: string): string {
+  try {
+    const d = new Date(iso)
+    return d.toLocaleTimeString(undefined, { hour: '2-digit', minute: '2-digit' })
+  } catch {
+    return iso
+  }
+}
+
+/**
+ * @description A horizontal scrollable timeline showing events with severity-colored
+ * dots. Most recent events appear on the left. Click events for detail callbacks.
+ * Designed for alert timelines and incident history strips.
+ */
+export function SeverityTimeline({
+  events,
+  maxVisible = 20,
+  onEventClick,
+  className,
+}: SeverityTimelineProps) {
+  const reduced = useReducedMotion()
+  const scrollRef = useRef<HTMLDivElement>(null)
+  const visible = events.slice(0, maxVisible)
+
+  if (visible.length === 0) return null
+
+  return (
+    <div
+      ref={scrollRef}
+      className={cn(
+        'relative overflow-x-auto scrollbar-thin py-2',
+        className,
+      )}
+    >
+      <div className="flex items-start gap-0 min-w-max">
+        <AnimatePresence initial={false}>
+          {visible.map((ev, i) => (
+            <motion.div
+              key={`${ev.time}-${i}`}
+              initial={reduced ? false : { opacity: 0, scale: 0.8 }}
+              animate={{ opacity: 1, scale: 1 }}
+              exit={{ opacity: 0, scale: 0.8 }}
+              transition={{ duration: 0.15, delay: reduced ? 0 : i * 0.03 }}
+              className="flex flex-col items-center relative"
+              style={{ minWidth: 64 }}
+            >
+              {/* Connector line */}
+              {i < visible.length - 1 && (
+                <div
+                  className="absolute top-[11px] left-1/2 h-px bg-[hsl(var(--border-default))]"
+                  style={{ width: 64 }}
+                />
+              )}
+
+              {/* Dot */}
+              <button
+                type="button"
+                onClick={() => onEventClick?.(ev)}
+                className={cn(
+                  'relative z-10 size-[10px] rounded-full ring-4 shrink-0',
+                  'transition-transform hover:scale-125 cursor-pointer',
+                  severityDot[ev.severity] ?? severityDot.info,
+                  severityRing[ev.severity] ?? severityRing.info,
+                )}
+                title={ev.detail ?? ev.label}
+                aria-label={`${ev.label} — ${ev.severity}`}
+              />
+
+              {/* Label */}
+              <span className="mt-1.5 text-[0.6875rem] font-medium text-[hsl(var(--text-primary))] text-center max-w-[56px] truncate">
+                {ev.label}
+              </span>
+
+              {/* Timestamp */}
+              <span className="text-[0.625rem] text-[hsl(var(--text-tertiary))] tabular-nums">
+                {formatTime(ev.time)}
+              </span>
+            </motion.div>
+          ))}
+        </AnimatePresence>
+      </div>
+    </div>
+  )
+}

package/src/components/sheet.tsx

@@ -0,0 +1,164 @@
+'use client'
+
+import { useEffect, useCallback, useRef, type ReactNode } from 'react'
+import { motion, AnimatePresence, useReducedMotion } from 'framer-motion'
+import { X } from 'lucide-react'
+import { cn } from '../utils'
+
+export interface SheetProps {
+  /** Whether the sheet is open. */
+  open: boolean
+  /** Callback to close the sheet. */
+  onClose: () => void
+  /** Edge from which the sheet slides in. */
+  side?: 'right' | 'left' | 'top' | 'bottom'
+  /** Title displayed in the sheet header. */
+  title?: string
+  /** Description text below the title. */
+  description?: string
+  /** Width class for left/right sheets, height class for top/bottom. */
+  width?: string
+  /** Sheet content. */
+  children: ReactNode
+  /** Additional class name for the panel. */
+  className?: string
+}
+
+const slideVariants = {
+  right: { initial: { x: '100%' }, animate: { x: 0 }, exit: { x: '100%' } },
+  left: { initial: { x: '-100%' }, animate: { x: 0 }, exit: { x: '-100%' } },
+  top: { initial: { y: '-100%' }, animate: { y: 0 }, exit: { y: '-100%' } },
+  bottom: { initial: { y: '100%' }, animate: { y: 0 }, exit: { y: '100%' } },
+}
+
+const positionClasses = {
+  right: 'inset-y-0 right-0',
+  left: 'inset-y-0 left-0',
+  top: 'inset-x-0 top-0',
+  bottom: 'inset-x-0 bottom-0',
+}
+
+/**
+ * @description A slide-over panel (drawer) from any edge of the screen.
+ * Features backdrop overlay, spring animation, Escape to close, backdrop click to close,
+ * and focus trapping within the panel.
+ */
+export function Sheet({
+  open,
+  onClose,
+  side = 'right',
+  title,
+  description,
+  width = 'max-w-md',
+  children,
+  className,
+}: SheetProps) {
+  const prefersReducedMotion = useReducedMotion()
+  const panelRef = useRef<HTMLDivElement>(null)
+
+  // Close on Escape
+  const handleKeyDown = useCallback(
+    (e: KeyboardEvent) => {
+      if (e.key === 'Escape') onClose()
+    },
+    [onClose],
+  )
+
+  useEffect(() => {
+    if (open) {
+      document.addEventListener('keydown', handleKeyDown)
+      // Prevent body scroll
+      const prevOverflow = document.body.style.overflow
+      document.body.style.overflow = 'hidden'
+      return () => {
+        document.removeEventListener('keydown', handleKeyDown)
+        document.body.style.overflow = prevOverflow
+      }
+    }
+  }, [open, handleKeyDown])
+
+  // Focus the panel when opened
+  useEffect(() => {
+    if (open) {
+      requestAnimationFrame(() => {
+        panelRef.current?.focus()
+      })
+    }
+  }, [open])
+
+  const isHorizontal = side === 'left' || side === 'right'
+  const variants = slideVariants[side]
+
+  return (
+    <AnimatePresence>
+      {open && (
+        <div className="fixed inset-0 z-50">
+          {/* Backdrop */}
+          <motion.div
+            initial={{ opacity: 0 }}
+            animate={{ opacity: 1 }}
+            exit={{ opacity: 0 }}
+            transition={prefersReducedMotion ? { duration: 0 } : { duration: 0.2 }}
+            className="absolute inset-0 bg-[hsl(var(--bg-base)/0.6)] backdrop-blur-sm"
+            onClick={onClose}
+          />
+
+          {/* Panel */}
+          <motion.div
+            ref={panelRef}
+            tabIndex={-1}
+            role="dialog"
+            aria-modal="true"
+            aria-label={title}
+            initial={variants.initial}
+            animate={variants.animate}
+            exit={variants.exit}
+            transition={
+              prefersReducedMotion
+                ? { duration: 0 }
+                : { type: 'spring', stiffness: 400, damping: 35 }
+            }
+            className={cn(
+              'absolute flex flex-col',
+              'bg-[hsl(var(--bg-surface))] border-[hsl(var(--border-default))]',
+              'shadow-2xl focus:outline-none',
+              positionClasses[side],
+              isHorizontal
+                ? cn('w-full h-full', width, side === 'right' ? 'border-l' : 'border-r')
+                : cn('h-auto w-full', side === 'top' ? 'border-b' : 'border-t'),
+              className,
+            )}
+          >
+            {/* Header */}
+            {(title || description) && (
+              <div className="flex items-start justify-between gap-4 px-6 pt-6 pb-4 border-b border-[hsl(var(--border-subtle))]">
+                <div className="min-w-0">
+                  {title && (
+                    <h2 className="text-base font-semibold text-[hsl(var(--text-primary))]">{title}</h2>
+                  )}
+                  {description && (
+                    <p className="mt-1 text-sm text-[hsl(var(--text-secondary))]">{description}</p>
+                  )}
+                </div>
+                <button
+                  onClick={onClose}
+                  className={cn(
+                    'shrink-0 p-1.5 rounded-lg transition-colors',
+                    'text-[hsl(var(--text-tertiary))] hover:text-[hsl(var(--text-primary))]',
+                    'hover:bg-[hsl(var(--bg-elevated))]',
+                    'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[hsl(var(--brand-primary))]',
+                  )}
+                >
+                  <X className="h-4 w-4" />
+                </button>
+              </div>
+            )}
+
+            {/* Content */}
+            <div className="flex-1 overflow-y-auto px-6 py-4">{children}</div>
+          </motion.div>
+        </div>
+      )}
+    </AnimatePresence>
+  )
+}

package/src/components/skeleton.stories.tsx

@@ -0,0 +1,64 @@
+import type { Meta, StoryObj } from '@storybook/react'
+import { Skeleton, SkeletonText, SkeletonCard } from './skeleton'
+
+const meta: Meta<typeof Skeleton> = {
+  title: 'Components/Skeleton',
+  component: Skeleton,
+  tags: ['autodocs'],
+}
+export default meta
+
+type SkeletonStory = StoryObj<typeof Skeleton>
+type SkeletonTextStory = StoryObj<typeof SkeletonText>
+type SkeletonCardStory = StoryObj<typeof SkeletonCard>
+
+export const Default: SkeletonStory = {
+  render: () => <Skeleton className="h-4 w-48" />,
+}
+
+export const VariousSizes: SkeletonStory = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '0.75rem', width: '300px' }}>
+      <Skeleton className="h-3 w-24" />
+      <Skeleton className="h-4 w-48" />
+      <Skeleton className="h-6 w-64" />
+      <Skeleton className="h-8 w-full" />
+      <Skeleton className="h-12 w-12 rounded-full" />
+    </div>
+  ),
+}
+
+export const TextSingleLine: SkeletonTextStory = {
+  render: () => (
+    <div style={{ width: '300px' }}>
+      <SkeletonText lines={1} />
+    </div>
+  ),
+}
+
+export const TextMultiLine: SkeletonTextStory = {
+  render: () => (
+    <div style={{ width: '300px' }}>
+      <SkeletonText lines={4} />
+    </div>
+  ),
+}
+
+export const Card: SkeletonCardStory = {
+  render: () => (
+    <div style={{ width: '320px' }}>
+      <SkeletonCard />
+    </div>
+  ),
+}
+
+export const CardGrid: SkeletonCardStory = {
+  render: () => (
+    <div style={{ display: 'grid', gridTemplateColumns: 'repeat(2, 280px)', gap: '0.75rem' }}>
+      <SkeletonCard />
+      <SkeletonCard />
+      <SkeletonCard />
+      <SkeletonCard />
+    </div>
+  ),
+}