@carbonid1/design-system 0.1.0

package/src/ProgressRing/ProgressRing.vi.tsx

@@ -0,0 +1,51 @@
+import { render, screen } from '@testing-library/react'
+import { describe, expect, it } from 'vitest'
+import { ProgressRing } from './ProgressRing'
+import { CIRCUMFERENCE } from './ProgressRing.consts'
+
+describe('ProgressRing', () => {
+  it('renders zero dashoffset at 0% progress', () => {
+    render(<ProgressRing progress={0} colorClass="text-primary" label="Empty" testId="ring" />)
+    const circle = screen.getByTestId('ring')
+    const offset = Number(circle.getAttribute('stroke-dashoffset'))
+    expect(offset).toBeCloseTo(CIRCUMFERENCE, 1)
+  })
+
+  it('renders correct dashoffset at 50% progress', () => {
+    render(<ProgressRing progress={0.5} colorClass="text-primary" label="Half" testId="ring" />)
+    const circle = screen.getByTestId('ring')
+    const offset = Number(circle.getAttribute('stroke-dashoffset'))
+    expect(offset).toBeCloseTo(CIRCUMFERENCE * 0.5, 1)
+  })
+
+  it('renders zero dashoffset at 100% progress', () => {
+    render(<ProgressRing progress={1} colorClass="text-success" label="Full" testId="ring" />)
+    const circle = screen.getByTestId('ring')
+    const offset = Number(circle.getAttribute('stroke-dashoffset'))
+    expect(offset).toBeCloseTo(0, 1)
+  })
+
+  it('applies colorClass to fill circle', () => {
+    render(<ProgressRing progress={0.5} colorClass="text-success" label="Test" testId="ring" />)
+    const circle = screen.getByTestId('ring')
+    expect(circle.classList.toString()).toContain('text-success')
+  })
+
+  it('applies pulse animation when animate is true', () => {
+    render(<ProgressRing progress={0.5} colorClass="text-primary" label="Pulsing" animate />)
+    const svg = screen.getByRole('img', { hidden: true })
+    expect(svg.classList.toString()).toContain('animate-buffer-pulse')
+  })
+
+  it('does not apply pulse animation when animate is false', () => {
+    render(<ProgressRing progress={0.5} colorClass="text-primary" label="Idle" />)
+    const svg = screen.getByRole('img', { hidden: true })
+    expect(svg.classList.toString()).not.toContain('animate-buffer-pulse')
+  })
+
+  it('sets aria-label from label prop', () => {
+    render(<ProgressRing progress={0.5} colorClass="text-primary" label="42 paragraphs ready" />)
+    const svg = screen.getByRole('img', { hidden: true })
+    expect(svg.getAttribute('aria-label')).toBe('42 paragraphs ready')
+  })
+})

package/src/Select/Select.tsx

@@ -0,0 +1,156 @@
+'use client'
+
+import { ChevronDown } from 'lucide-react'
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import type { SelectOption, SelectProps } from './Select.types'
+
+export const Select = ({
+  value,
+  onChange,
+  options,
+  groups,
+  placeholder,
+  id,
+  className,
+  menuClassName,
+  renderOption,
+  onOpenChange,
+  'aria-label': ariaLabel,
+}: SelectProps) => {
+  const [open, setOpen] = useState(false)
+  const [highlightedIndex, setHighlightedIndex] = useState(-1)
+  const containerRef = useRef<HTMLDivElement>(null)
+
+  const changeOpen = useCallback(
+    (next: boolean) => {
+      setOpen(next)
+      onOpenChange?.(next)
+    },
+    [onOpenChange],
+  )
+
+  // Build flat items list with group metadata
+  const { items, groupStartIndices } = useMemo(() => {
+    const flat: SelectOption[] = [...(options ?? [])]
+    const starts: { index: number; label: string }[] = []
+
+    for (const group of groups ?? []) {
+      starts.push({ index: flat.length, label: group.label })
+      flat.push(...group.options)
+    }
+
+    return { items: flat, groupStartIndices: starts }
+  }, [options, groups])
+
+  const selectedOption = items.find(o => o.value === value)
+  const displayText = selectedOption?.label ?? placeholder ?? value
+
+  // Click outside to close
+  useEffect(() => {
+    const handleClickOutside = (e: MouseEvent) => {
+      if (containerRef.current && !containerRef.current.contains(e.target as Node)) {
+        changeOpen(false)
+      }
+    }
+    document.addEventListener('mousedown', handleClickOutside)
+    return () => document.removeEventListener('mousedown', handleClickOutside)
+  }, [changeOpen])
+
+  const selectItem = (itemValue: string) => {
+    onChange(itemValue)
+    changeOpen(false)
+    setHighlightedIndex(-1)
+  }
+
+  const handleKeyDown = (e: React.KeyboardEvent) => {
+    if (e.key === 'Escape') {
+      changeOpen(false)
+      setHighlightedIndex(-1)
+      return
+    }
+
+    if (!open) {
+      if (e.key === 'ArrowDown' || e.key === 'ArrowUp' || e.key === 'Enter' || e.key === ' ') {
+        e.preventDefault()
+        changeOpen(true)
+        setHighlightedIndex(0)
+      }
+      return
+    }
+
+    if (e.key === 'ArrowDown') {
+      e.preventDefault()
+      setHighlightedIndex(prev => (prev + 1) % items.length)
+    } else if (e.key === 'ArrowUp') {
+      e.preventDefault()
+      setHighlightedIndex(prev => (prev - 1 + items.length) % items.length)
+    } else if (e.key === 'Enter') {
+      e.preventDefault()
+      const highlighted = items[highlightedIndex]
+      if (highlighted) {
+        selectItem(highlighted.value)
+      }
+    }
+  }
+
+  const itemClassName = (index: number, itemValue: string) => {
+    const base = 'px-3 py-2.5 cursor-pointer'
+    const highlight = index === highlightedIndex ? 'bg-primary-muted' : 'hover:bg-primary-muted'
+    const selected = itemValue === value ? 'font-medium' : ''
+    return `${base} ${highlight} ${selected}`
+  }
+
+  return (
+    <div className="relative" ref={containerRef} onKeyDown={handleKeyDown}>
+      <button
+        type="button"
+        id={id}
+        className={`flex items-center justify-between gap-2 ${className ?? ''}`}
+        aria-expanded={open}
+        aria-haspopup="listbox"
+        aria-label={ariaLabel}
+        onClick={() => changeOpen(!open)}
+      >
+        <span className="truncate">{displayText}</span>
+        <ChevronDown
+          className={`size-4 shrink-0 transition-transform ${open ? 'rotate-180' : ''}`}
+        />
+      </button>
+
+      {open && (
+        <ul
+          role="listbox"
+          className={`border-border bg-background absolute z-50 mt-1 max-h-60 w-max min-w-full overflow-y-auto rounded-lg border shadow-lg ${menuClassName ?? ''}`}
+        >
+          {items.map((item, index) => {
+            const groupHeader = groupStartIndices.find(g => g.index === index)
+
+            return (
+              <li key={item.value} role="presentation">
+                {groupHeader && (
+                  <div className="text-muted-foreground px-3 pt-2 pb-1 text-xs font-medium uppercase">
+                    {groupHeader.label}
+                  </div>
+                )}
+                <div
+                  role="option"
+                  aria-selected={value === item.value}
+                  className={itemClassName(index, item.value)}
+                  onClick={() => selectItem(item.value)}
+                  onMouseEnter={() => setHighlightedIndex(index)}
+                >
+                  {renderOption
+                    ? renderOption(item, {
+                        highlighted: index === highlightedIndex,
+                        selected: value === item.value,
+                      })
+                    : item.label}
+                </div>
+              </li>
+            )
+          })}
+        </ul>
+      )}
+    </div>
+  )
+}

package/src/Select/Select.types.ts

@@ -0,0 +1,30 @@
+import type { ReactNode } from 'react'
+
+export type SelectOption = {
+  value: string
+  label: string
+}
+
+export type SelectGroup = {
+  label: string
+  options: SelectOption[]
+}
+
+export type SelectOptionState = {
+  highlighted: boolean
+  selected: boolean
+}
+
+export type SelectProps = {
+  value: string
+  onChange: (value: string) => void
+  options?: SelectOption[]
+  groups?: SelectGroup[]
+  placeholder?: string
+  id?: string
+  className?: string
+  menuClassName?: string
+  renderOption?: (option: SelectOption, state: SelectOptionState) => ReactNode
+  onOpenChange?: (open: boolean) => void
+  'aria-label'?: string
+}

package/src/Select/Select.vi.tsx

@@ -0,0 +1,129 @@
+import { fireEvent, render, screen } from '@testing-library/react'
+import { StrictMode } from 'react'
+import { describe, expect, it, vi } from 'vitest'
+import { Select } from './Select'
+import type { SelectGroup } from './Select.types'
+
+const options = [
+  { value: 'a', label: 'Alpha' },
+  { value: 'b', label: 'Bravo' },
+  { value: 'c', label: 'Charlie' },
+]
+
+const groups: SelectGroup[] = [
+  {
+    label: 'Letters',
+    options: [
+      { value: 'a', label: 'Alpha' },
+      { value: 'b', label: 'Bravo' },
+    ],
+  },
+  {
+    label: 'Numbers',
+    options: [
+      { value: '1', label: 'One' },
+      { value: '2', label: 'Two' },
+    ],
+  },
+]
+
+const renderWith = (ui: React.ReactElement) => render(<StrictMode>{ui}</StrictMode>)
+
+describe('Select', () => {
+  it('renders selected label and chevron in button', () => {
+    renderWith(<Select options={options} value="b" onChange={vi.fn()} />)
+
+    const button = screen.getByRole('button', { name: /bravo/i })
+    expect(button).toBeInTheDocument()
+    expect(button.querySelector('svg')).toBeInTheDocument()
+  })
+
+  it('opens menu on click showing all options', () => {
+    renderWith(<Select options={options} value="a" onChange={vi.fn()} />)
+
+    fireEvent.click(screen.getByRole('button', { name: /alpha/i }))
+
+    expect(screen.getByRole('listbox')).toBeInTheDocument()
+    expect(screen.getByRole('option', { name: /alpha/i })).toBeInTheDocument()
+    expect(screen.getByRole('option', { name: /bravo/i })).toBeInTheDocument()
+    expect(screen.getByRole('option', { name: /charlie/i })).toBeInTheDocument()
+  })
+
+  it('calls onChange and closes menu when an option is selected', () => {
+    const onChange = vi.fn()
+    renderWith(<Select options={options} value="a" onChange={onChange} />)
+
+    fireEvent.click(screen.getByRole('button', { name: /alpha/i }))
+    fireEvent.click(screen.getByRole('option', { name: /charlie/i }))
+
+    expect(onChange).toHaveBeenCalledWith('c')
+    expect(screen.queryByRole('listbox')).not.toBeInTheDocument()
+  })
+
+  it('closes on Escape key', () => {
+    renderWith(<Select options={options} value="a" onChange={vi.fn()} />)
+
+    const button = screen.getByRole('button', { name: /alpha/i })
+    fireEvent.click(button)
+    expect(screen.getByRole('listbox')).toBeInTheDocument()
+
+    fireEvent.keyDown(button, { key: 'Escape' })
+    expect(screen.queryByRole('listbox')).not.toBeInTheDocument()
+  })
+
+  it('closes on click outside', () => {
+    renderWith(<Select options={options} value="a" onChange={vi.fn()} />)
+
+    fireEvent.click(screen.getByRole('button', { name: /alpha/i }))
+    expect(screen.getByRole('listbox')).toBeInTheDocument()
+
+    fireEvent.mouseDown(document.body)
+    expect(screen.queryByRole('listbox')).not.toBeInTheDocument()
+  })
+
+  it('navigates with arrow keys and selects with Enter', () => {
+    const onChange = vi.fn()
+    renderWith(<Select options={options} value="a" onChange={onChange} />)
+
+    const button = screen.getByRole('button', { name: /alpha/i })
+    fireEvent.click(button)
+
+    fireEvent.keyDown(button, { key: 'ArrowDown' })
+    fireEvent.keyDown(button, { key: 'ArrowDown' })
+    fireEvent.keyDown(button, { key: 'Enter' })
+
+    expect(onChange).toHaveBeenCalledWith('b')
+  })
+
+  it('renders groups with headers', () => {
+    renderWith(<Select groups={groups} value="a" onChange={vi.fn()} />)
+
+    fireEvent.click(screen.getByRole('button', { name: /alpha/i }))
+
+    expect(screen.getByText('Letters')).toBeInTheDocument()
+    expect(screen.getByText('Numbers')).toBeInTheDocument()
+    expect(screen.getByRole('option', { name: /one/i })).toBeInTheDocument()
+  })
+
+  it('uses renderOption for custom item rendering', () => {
+    renderWith(
+      <Select
+        options={options}
+        value="a"
+        onChange={vi.fn()}
+        renderOption={option => <span data-testid="custom">{option.label.toUpperCase()}</span>}
+      />,
+    )
+
+    fireEvent.click(screen.getByRole('button', { name: /alpha/i }))
+
+    expect(screen.getAllByTestId('custom')).toHaveLength(3)
+    expect(screen.getByText('BRAVO')).toBeInTheDocument()
+  })
+
+  it('shows placeholder when value does not match any option', () => {
+    renderWith(<Select options={options} value="x" onChange={vi.fn()} placeholder="Pick one" />)
+
+    expect(screen.getByRole('button', { name: /pick one/i })).toBeInTheDocument()
+  })
+})

package/src/Slider/Slider.tsx

@@ -0,0 +1,53 @@
+'use client'
+
+import { cn } from '../helpers/cn/cn'
+import { Slider as SliderPrimitive } from '@base-ui/react/slider'
+
+type SliderProps = {
+  value: number
+  onChange: (value: number) => void
+  onCommit?: (value: number) => void
+  min: number
+  max: number
+  step?: number
+  disabled?: boolean
+  'aria-label'?: string
+  className?: string
+}
+
+export const Slider = ({
+  value,
+  onChange,
+  onCommit,
+  min,
+  max,
+  step = 1,
+  disabled,
+  'aria-label': ariaLabel,
+  className,
+}: SliderProps) => (
+  <SliderPrimitive.Root
+    value={value}
+    onValueChange={v => onChange(v as number)}
+    onValueCommitted={v => onCommit?.(v as number)}
+    min={min}
+    max={max}
+    step={step}
+    disabled={disabled}
+    aria-label={ariaLabel}
+    className={cn('relative flex w-full touch-none items-center py-2', className)}
+  >
+    <SliderPrimitive.Control className="relative flex h-1.5 w-full items-center">
+      <SliderPrimitive.Track className="bg-input h-full w-full overflow-hidden rounded-full">
+        <SliderPrimitive.Indicator className="bg-primary h-full rounded-full" />
+      </SliderPrimitive.Track>
+      <SliderPrimitive.Thumb
+        className={cn(
+          'bg-primary border-background block size-4 rounded-full border-2 shadow-sm',
+          'focus-visible:ring-ring/50 focus-visible:ring-3 focus-visible:outline-hidden',
+          disabled && 'pointer-events-none opacity-50',
+        )}
+      />
+    </SliderPrimitive.Control>
+  </SliderPrimitive.Root>
+)

package/src/Slider/Slider.vi.tsx

@@ -0,0 +1,29 @@
+import { cleanup, render, screen } from '@testing-library/react'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { Slider } from './Slider'
+
+afterEach(cleanup)
+
+describe('Slider', () => {
+  it('renders a slider with the correct value', () => {
+    render(<Slider value={50} onChange={() => {}} min={0} max={100} aria-label="Volume" />)
+    const slider = screen.getByRole('slider')
+    expect(slider).toHaveAttribute('aria-valuenow', '50')
+  })
+
+  it('calls onCommit when interaction ends', () => {
+    const onCommit = vi.fn()
+    render(
+      <Slider
+        value={50}
+        onChange={() => {}}
+        onCommit={onCommit}
+        min={0}
+        max={100}
+        aria-label="Volume"
+      />,
+    )
+    // Just verify it renders without error — slider drag testing is unreliable in jsdom
+    expect(screen.getByRole('slider')).toBeInTheDocument()
+  })
+})

package/src/Switch/Switch.tsx

@@ -0,0 +1,41 @@
+'use client'
+
+import { cn } from '../helpers/cn/cn'
+import { Switch as SwitchPrimitive } from '@base-ui/react/switch'
+
+type SwitchProps = {
+  checked: boolean
+  onChange: (checked: boolean) => void
+  disabled?: boolean
+  'aria-label'?: string
+  className?: string
+}
+
+export const Switch = ({
+  checked,
+  onChange,
+  disabled,
+  'aria-label': ariaLabel,
+  className,
+}: SwitchProps) => (
+  <SwitchPrimitive.Root
+    checked={checked}
+    onCheckedChange={checked => onChange(checked)}
+    disabled={disabled}
+    aria-label={ariaLabel}
+    className={cn(
+      'relative inline-flex h-6 w-11 shrink-0 cursor-pointer items-center rounded-full transition-colors',
+      'focus-visible:ring-ring/50 focus-visible:border-ring focus-visible:ring-3 focus-visible:outline-hidden',
+      checked ? 'bg-primary' : 'bg-input',
+      disabled && 'pointer-events-none opacity-50',
+      className,
+    )}
+  >
+    <SwitchPrimitive.Thumb
+      className={cn(
+        'bg-background pointer-events-none block size-[18px] rounded-full shadow-sm transition-transform',
+        checked ? 'translate-x-5.5' : 'translate-x-[3px]',
+      )}
+    />
+  </SwitchPrimitive.Root>
+)

package/src/Switch/Switch.vi.tsx

@@ -0,0 +1,31 @@
+import { cleanup, render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { Switch } from './Switch'
+
+afterEach(cleanup)
+
+describe('Switch', () => {
+  it('renders as a switch with the correct checked state', () => {
+    render(<Switch checked={true} onChange={() => {}} aria-label="Toggle" />)
+    expect(screen.getByRole('switch')).toBeChecked()
+  })
+
+  it('calls onChange when clicked', async () => {
+    const user = userEvent.setup()
+    const onChange = vi.fn()
+    render(<Switch checked={false} onChange={onChange} aria-label="Toggle" />)
+
+    await user.click(screen.getByRole('switch'))
+    expect(onChange).toHaveBeenCalledWith(true)
+  })
+
+  it('does not call onChange when disabled', async () => {
+    const user = userEvent.setup()
+    const onChange = vi.fn()
+    render(<Switch checked={false} onChange={onChange} disabled aria-label="Toggle" />)
+
+    await user.click(screen.getByRole('switch'))
+    expect(onChange).not.toHaveBeenCalled()
+  })
+})

package/src/ThemeCycler/ThemeCycler.tsx

@@ -0,0 +1,37 @@
+'use client'
+
+import { useTheme } from 'next-themes'
+import { useCallback, useSyncExternalStore } from 'react'
+import { useHotkeys } from 'react-hotkeys-hook'
+import { toast } from 'sonner'
+
+const THEME_CYCLE = ['system', 'light', 'dark'] as const
+
+const THEME_LABELS: Record<string, string> = {
+  system: 'System',
+  light: 'Light',
+  dark: 'Dark',
+}
+
+const emptySubscribe = () => () => {}
+const getSnapshot = () => true
+const getServerSnapshot = () => false
+
+export const ThemeCycler = () => {
+  const { theme, setTheme } = useTheme()
+  const mounted = useSyncExternalStore(emptySubscribe, getSnapshot, getServerSnapshot)
+
+  const cycleTheme = useCallback(() => {
+    if (!mounted) return
+    const current = theme ?? 'system'
+    const currentIndex = THEME_CYCLE.indexOf(current as (typeof THEME_CYCLE)[number])
+    const nextIndex = (currentIndex + 1) % THEME_CYCLE.length
+    const next = THEME_CYCLE[nextIndex] ?? 'system'
+    setTheme(next)
+    toast(`Theme: ${THEME_LABELS[next]}`, { duration: 2000 })
+  }, [theme, setTheme, mounted])
+
+  useHotkeys('shift+t', cycleTheme, { preventDefault: true })
+
+  return null
+}

package/src/ThemeProvider/ThemeProvider.tsx

@@ -0,0 +1,18 @@
+'use client'
+
+import { ThemeProvider as NextThemesProvider } from 'next-themes'
+
+type Props = {
+  children: React.ReactNode
+}
+
+export const ThemeProvider = ({ children }: Props) => (
+  <NextThemesProvider
+    attribute="class"
+    defaultTheme="system"
+    enableSystem
+    disableTransitionOnChange
+  >
+    {children}
+  </NextThemesProvider>
+)

package/src/Toaster/Toaster.tsx

@@ -0,0 +1,7 @@
+'use client'
+
+import { Toaster as Sonner, type ToasterProps } from 'sonner'
+
+export const Toaster = (props: ToasterProps) => (
+  <Sonner theme="system" className="toaster group" position="bottom-right" {...props} />
+)