@carbonid1/design-system 4.0.0 → 4.1.0

package/README.md

@@ -1,11 +1,11 @@
 # @carbonid1/design-system
 
-Shared React UI primitives themed via [`@carbonid1/tailwind-config`](../tailwind-config).
+Shared React UI primitives + Tailwind v4 theme presets (`reader`, `dashboard`) + postcss config.
 
 ## Install
 
 ```sh
-pnpm add @carbonid1/design-system @carbonid1/tailwind-config react react-dom @base-ui/react class-variance-authority clsx tailwind-merge lucide-react sonner next-themes react-hotkeys-hook
+pnpm add @carbonid1/design-system react react-dom @base-ui/react class-variance-authority clsx tailwind-merge lucide-react sonner next-themes react-hotkeys-hook
 ```
 
 And Tailwind CSS v4 (with `tw-animate-css` + `shadcn/tailwind.css` if you want matching utilities/base):
@@ -24,7 +24,7 @@ In your entry CSS (Next.js: `src/app/globals.css`):
 @import 'tailwindcss';
 @import 'tw-animate-css';
 @import 'shadcn/tailwind.css';
-@import '@carbonid1/tailwind-config/reader';
+@import '@carbonid1/design-system/themes/reader';
 ```
 
 ### 2. Transpile the package in Next.js
@@ -84,8 +84,8 @@ export default function RootLayout({ children }: { children: React.ReactNode })
 
 ## Theming
 
-Components use semantic color utilities (`bg-primary`, `text-muted-foreground`, etc.) that resolve via `@carbonid1/tailwind-config`. Switching theme → swap the tailwind-config import. Dark mode is toggled by adding `class="dark"` to a root ancestor (`ThemeProvider` handles this).
+Components use semantic color utilities (`bg-primary`, `text-muted-foreground`, etc.) that resolve via the imported theme preset. Switching theme → swap the `@carbonid1/design-system/themes/*` import. Dark mode is toggled by adding `class="dark"` to a root ancestor (`ThemeProvider` handles this).
 
 ## Build
 
-No build step — package ships raw `.tsx` via `files: ["src"]`. Consumers transpile at build time. Stories (`*.stories.tsx`) and tests (`*.vi.{ts,tsx}`) are excluded from the published tarball.
+No build step — package ships raw `.tsx`. Consumers transpile at build time. Stories (`*.stories.tsx`) and tests (`*.test.{ts,tsx}`) are excluded from the published tarball.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carbonid1/design-system",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "description": "Shared React UI primitives + design tokens (themes, postcss config)",
   "repository": {
     "type": "git",
@@ -10,6 +10,9 @@
   "license": "MIT",
   "author": "Andrew Korin",
   "type": "module",
+  "sideEffects": [
+    "**/*.css"
+  ],
   "exports": {
     ".": "./src/index.ts",
     "./themes/reader": "./themes/reader.css",
@@ -67,9 +70,7 @@
     "tailwindcss": "^4.2.2",
     "vite": "^8.0.8",
     "vitest": "^4.1.4",
-    "@carbonid1/tsconfig": "0.2.0",
-    "@carbonid1/vitest-config": "0.1.0",
-    "@carbonid1/storybook-config": "0.1.0"
+    "@carbonid1/tsconfig": "0.2.1"
   },
   "scripts": {
     "storybook": "storybook dev -p 6006",

package/src/ContextMenu/ContextMenu.tsx

@@ -0,0 +1,159 @@
+'use client'
+
+import { ContextMenu as BaseContextMenu } from '@base-ui/react/context-menu'
+import { ChevronRight } from 'lucide-react'
+import type { ComponentPropsWithoutRef, Ref } from 'react'
+import { cn } from '../helpers/cn/cn'
+
+type BasePopupProps = ComponentPropsWithoutRef<typeof BaseContextMenu.Popup>
+type BasePositionerProps = ComponentPropsWithoutRef<typeof BaseContextMenu.Positioner>
+type BaseItemProps = ComponentPropsWithoutRef<typeof BaseContextMenu.Item>
+type BaseSeparatorProps = ComponentPropsWithoutRef<typeof BaseContextMenu.Separator>
+type BaseGroupLabelProps = ComponentPropsWithoutRef<typeof BaseContextMenu.GroupLabel>
+type BaseSubmenuTriggerProps = ComponentPropsWithoutRef<typeof BaseContextMenu.SubmenuTrigger>
+type BaseCheckboxItemProps = ComponentPropsWithoutRef<typeof BaseContextMenu.CheckboxItem>
+type BaseRadioItemProps = ComponentPropsWithoutRef<typeof BaseContextMenu.RadioItem>
+
+type ItemVariant = 'default' | 'destructive'
+
+type PositionerProps = BasePositionerProps & { ref?: Ref<HTMLDivElement> }
+type PopupProps = BasePopupProps & { ref?: Ref<HTMLDivElement> }
+type SeparatorProps = BaseSeparatorProps & { ref?: Ref<HTMLDivElement> }
+type GroupLabelProps = BaseGroupLabelProps & { ref?: Ref<HTMLDivElement> }
+type ItemProps = BaseItemProps & { ref?: Ref<HTMLDivElement>; variant?: ItemVariant }
+type CheckboxItemProps = BaseCheckboxItemProps & { ref?: Ref<HTMLDivElement> }
+type RadioItemProps = BaseRadioItemProps & { ref?: Ref<HTMLDivElement> }
+type SubmenuTriggerProps = BaseSubmenuTriggerProps & { ref?: Ref<HTMLDivElement> }
+
+const popupClasses =
+  'bg-popover text-popover-foreground border-border z-50 min-w-45 origin-[var(--transform-origin)] rounded-lg border py-1 shadow-lg outline-hidden transition-[transform,opacity] data-[ending-style]:scale-95 data-[ending-style]:opacity-0 data-[starting-style]:scale-95 data-[starting-style]:opacity-0'
+
+const itemBaseClasses =
+  'relative flex h-7 cursor-default items-center gap-1.5 px-2.5 text-[0.8rem] outline-hidden select-none [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*=size-])]:size-4 data-[disabled]:pointer-events-none data-[disabled]:opacity-50'
+
+const itemVariantClasses: Record<ItemVariant, string> = {
+  default:
+    'data-[highlighted]:bg-accent data-[highlighted]:text-accent-foreground',
+  destructive:
+    'text-destructive data-[highlighted]:bg-destructive/10 data-[highlighted]:text-destructive',
+}
+
+const Positioner = ({ className, sideOffset = 4, ...props }: PositionerProps) => (
+  <BaseContextMenu.Positioner
+    sideOffset={sideOffset}
+    className={cn('z-50 outline-hidden', className)}
+    {...props}
+  />
+)
+
+const Popup = ({ className, ...props }: PopupProps) => (
+  <BaseContextMenu.Popup className={cn(popupClasses, className)} {...props} />
+)
+
+const Item = ({ className, variant = 'default', ...props }: ItemProps) => (
+  <BaseContextMenu.Item
+    className={cn(itemBaseClasses, itemVariantClasses[variant], className)}
+    {...props}
+  />
+)
+
+const Separator = ({ className, ...props }: SeparatorProps) => (
+  <BaseContextMenu.Separator
+    className={cn('bg-border my-1 h-px', className)}
+    {...props}
+  />
+)
+
+const GroupLabel = ({ className, ...props }: GroupLabelProps) => (
+  <BaseContextMenu.GroupLabel
+    className={cn('text-muted-foreground px-2.5 py-1 text-xs', className)}
+    {...props}
+  />
+)
+
+const CheckboxItem = ({ className, children, ...props }: CheckboxItemProps) => (
+  <BaseContextMenu.CheckboxItem
+    className={cn(itemBaseClasses, itemVariantClasses.default, 'pl-7', className)}
+    {...props}
+  >
+    <span
+      aria-hidden
+      className="absolute left-2 flex size-3.5 items-center justify-center"
+    >
+      <BaseContextMenu.CheckboxItemIndicator className="size-3.5">
+        <CheckIcon />
+      </BaseContextMenu.CheckboxItemIndicator>
+    </span>
+    {children}
+  </BaseContextMenu.CheckboxItem>
+)
+
+const RadioItem = ({ className, children, ...props }: RadioItemProps) => (
+  <BaseContextMenu.RadioItem
+    className={cn(itemBaseClasses, itemVariantClasses.default, 'pl-7', className)}
+    {...props}
+  >
+    <span
+      aria-hidden
+      className="absolute left-2 flex size-3.5 items-center justify-center"
+    >
+      <BaseContextMenu.RadioItemIndicator className="size-3.5">
+        <DotIcon />
+      </BaseContextMenu.RadioItemIndicator>
+    </span>
+    {children}
+  </BaseContextMenu.RadioItem>
+)
+
+const SubmenuTrigger = ({ className, children, ...props }: SubmenuTriggerProps) => (
+  <BaseContextMenu.SubmenuTrigger
+    className={cn(
+      itemBaseClasses,
+      itemVariantClasses.default,
+      'data-popup-open:bg-accent data-popup-open:text-accent-foreground pr-2',
+      className,
+    )}
+    {...props}
+  >
+    {children}
+    <ChevronRight className="ml-auto size-4 opacity-60" aria-hidden />
+  </BaseContextMenu.SubmenuTrigger>
+)
+
+const CheckIcon = () => (
+  <svg viewBox="0 0 14 14" fill="none" className="size-3.5">
+    <path
+      d="M3 7.5 6 10.5 11 4.5"
+      stroke="currentColor"
+      strokeWidth="1.75"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    />
+  </svg>
+)
+
+const DotIcon = () => (
+  <svg viewBox="0 0 14 14" className="size-3.5">
+    <circle cx="7" cy="7" r="3" fill="currentColor" />
+  </svg>
+)
+
+export const ContextMenu = {
+  Root: BaseContextMenu.Root,
+  Trigger: BaseContextMenu.Trigger,
+  Portal: BaseContextMenu.Portal,
+  Backdrop: BaseContextMenu.Backdrop,
+  Positioner,
+  Popup,
+  Arrow: BaseContextMenu.Arrow,
+  Group: BaseContextMenu.Group,
+  GroupLabel,
+  Separator,
+  Item,
+  LinkItem: BaseContextMenu.LinkItem,
+  CheckboxItem,
+  RadioGroup: BaseContextMenu.RadioGroup,
+  RadioItem,
+  SubmenuRoot: BaseContextMenu.SubmenuRoot,
+  SubmenuTrigger,
+}

package/src/ProgressRing/ProgressRing.test.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.test.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.test.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.test.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/helpers/getModKey/getModKey.test.ts

@@ -0,0 +1,23 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { getModKey } from './getModKey'
+
+describe('getModKey', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals()
+  })
+
+  it('returns "Cmd" on Mac', () => {
+    vi.stubGlobal('navigator', { userAgent: 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)' })
+    expect(getModKey()).toBe('Cmd')
+  })
+
+  it('returns "Ctrl" on Windows', () => {
+    vi.stubGlobal('navigator', { userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64)' })
+    expect(getModKey()).toBe('Ctrl')
+  })
+
+  it('returns "Ctrl" when navigator is undefined', () => {
+    vi.stubGlobal('navigator', undefined)
+    expect(getModKey()).toBe('Ctrl')
+  })
+})

package/src/index.ts

@@ -10,6 +10,8 @@ export { Slider } from './Slider/Slider'
 
 export { Switch } from './Switch/Switch'
 
+export { ContextMenu } from './ContextMenu/ContextMenu'
+
 export { Select } from './Select/Select'
 export type {
   SelectOption,

package/themes/dashboard.css

@@ -12,6 +12,10 @@
 
 @import 'tailwindcss';
 
+/* Scan design-system components so consumers pick up classes used inside
+ * Button/Kbd/etc. — Tailwind v4 skips node_modules by default. */
+@source "../src/**/*.{ts,tsx}";
+
 @custom-variant dark (&:is(.dark *));
 
 @theme inline {
@@ -117,6 +121,18 @@
   --success-foreground: oklch(0.82 0.1 149);
 }
 
+/* Global focus-visible ring for raw interactive elements. Primitives (Button,
+ * etc.) override this with their own tuned focus styling. */
+@layer base {
+  button:focus-visible,
+  [role='button']:focus-visible,
+  a:focus-visible {
+    outline: 2px solid var(--primary);
+    outline-offset: 2px;
+    border-radius: 0.375rem;
+  }
+}
+
 /* Keyframes referenced by the theme's --animate-* tokens */
 @keyframes ring-spin {
   to {

package/themes/reader.css

@@ -14,6 +14,10 @@
 
 @import 'tailwindcss';
 
+/* Scan design-system components so consumers pick up classes used inside
+ * Button/Kbd/etc. — Tailwind v4 skips node_modules by default. */
+@source "../src/**/*.{ts,tsx}";
+
 @custom-variant dark (&:is(.dark *));
 
 @theme inline {
@@ -119,6 +123,18 @@
   --success-foreground: oklch(0.82 0.1 149);
 }
 
+/* Global focus-visible ring for raw interactive elements. Primitives (Button,
+ * etc.) override this with their own tuned focus styling. */
+@layer base {
+  button:focus-visible,
+  [role='button']:focus-visible,
+  a:focus-visible {
+    outline: 2px solid var(--primary);
+    outline-offset: 2px;
+    border-radius: 0.375rem;
+  }
+}
+
 /* Keyframes referenced by the theme's --animate-* tokens */
 @keyframes ring-spin {
   to {