@carbonid1/design-system 0.1.0

package/src/Tooltip/Tooltip.stories.tsx

@@ -0,0 +1,161 @@
+import type { ComponentProps } from 'react'
+import { expect, waitFor } from 'storybook/test'
+import preview from '../../../.storybook/preview'
+import { Tooltip } from './Tooltip'
+
+type TooltipProps = ComponentProps<typeof Tooltip>
+
+const meta = preview.type<{ args: TooltipProps }>().meta({
+  component: Tooltip,
+  argTypes: {
+    position: {
+      control: 'select',
+      options: ['top', 'bottom'],
+    },
+    disabled: { control: 'boolean' },
+    delay: { control: 'number' },
+    maxWidth: { control: 'number' },
+  },
+  args: {
+    label: 'Tooltip label',
+    children: <button style={{ padding: '8px 16px' }}>Hover me</button>,
+  },
+  decorators: [
+    Story => (
+      <div style={{ padding: 80, display: 'flex', justifyContent: 'center' }}>
+        <Story />
+      </div>
+    ),
+  ],
+})
+
+// --- Variants ---
+
+/** Label-only tooltip with no shortcut — the most common usage. */
+export const Default = meta.story({
+  args: { label: 'Default tooltip' },
+})
+Default.test('is hidden by default', async ({ canvas }) => {
+  await expect(canvas.queryByRole('tooltip')).toBeNull()
+})
+Default.test('shows on hover and hides on leave', async ({ canvas, userEvent }) => {
+  const button = await canvas.findByRole('button')
+  await userEvent.hover(button)
+  await waitFor(() => expect(canvas.getByRole('tooltip')).toHaveTextContent('Default tooltip'))
+  await userEvent.unhover(button)
+  await waitFor(() => expect(canvas.queryByRole('tooltip')).toBeNull())
+})
+Default.test('shows on focus and hides on blur', async ({ canvas }) => {
+  const button = await canvas.findByRole('button')
+  button.focus()
+  await waitFor(() => expect(canvas.getByRole('tooltip')).toHaveTextContent('Default tooltip'))
+  button.blur()
+  await waitFor(() => expect(canvas.queryByRole('tooltip')).toBeNull())
+})
+Default.test('does not render kbd when shortcut omitted', async ({ canvas, userEvent }) => {
+  const button = await canvas.findByRole('button')
+  await userEvent.hover(button)
+  await waitFor(() => {
+    expect(canvas.getByRole('tooltip').querySelector('kbd')).toBeNull()
+  })
+})
+Default.test('hides on pointerdown', async ({ canvas, userEvent }) => {
+  const button = await canvas.findByRole('button')
+  await userEvent.hover(button)
+  await waitFor(() => expect(canvas.getByRole('tooltip')).toBeInTheDocument())
+  await userEvent.pointer({ keys: '[MouseLeft>]', target: button })
+  await waitFor(() => expect(canvas.queryByRole('tooltip')).toBeNull())
+})
+
+/** Single-key shortcut badge shown alongside the label. */
+export const WithShortcut = meta.story({
+  args: { label: 'Play', shortcut: 'Space' },
+})
+WithShortcut.test('renders shortcut kbd on hover', async ({ canvas, userEvent }) => {
+  const button = await canvas.findByRole('button')
+  await userEvent.hover(button)
+  await waitFor(() => {
+    const tooltip = canvas.getByRole('tooltip')
+    expect(tooltip).toHaveTextContent('Play')
+    expect(tooltip.querySelector('kbd')).not.toBeNull()
+  })
+})
+
+/** Multi-key combo shortcut — each key rendered as a separate Kbd element. */
+export const WithComboShortcut = meta.story({
+  args: { label: 'Search', shortcut: ['mod', 'F'] },
+})
+WithComboShortcut.test('renders multiple kbd elements for combo', async ({ canvas, userEvent }) => {
+  const button = await canvas.findByRole('button')
+  await userEvent.hover(button)
+  await waitFor(() => {
+    const kbdElements = canvas.getByRole('tooltip').querySelectorAll('kbd')
+    expect(kbdElements.length).toBe(2)
+  })
+})
+
+/** Tooltip anchored below the trigger — used in headers and top-of-page areas. */
+export const BottomPosition = meta.story({
+  args: { label: 'Bottom tooltip', position: 'bottom' },
+})
+
+/** Long text constrained to a max width, wrapping across multiple lines. */
+export const WithMaxWidth = meta.story({
+  args: {
+    label: 'This is a very long tooltip that should wrap to multiple lines when maxWidth is set',
+    maxWidth: 200,
+  },
+})
+WithMaxWidth.test('applies max-width style and wraps text', async ({ canvas, userEvent }) => {
+  const button = await canvas.findByRole('button')
+  await userEvent.hover(button)
+  await waitFor(() => {
+    const tooltip = canvas.getByRole('tooltip')
+    expect(tooltip).toHaveStyle({ maxWidth: '200px' })
+    expect(tooltip.className).toContain('whitespace-normal')
+  })
+})
+
+/** Tooltip suppressed while a popover or menu is open. */
+export const Disabled = meta.story({
+  args: { label: 'Disabled tooltip', disabled: true },
+})
+Disabled.test('does not show when disabled', async ({ canvas, userEvent }) => {
+  const button = await canvas.findByRole('button')
+  await userEvent.hover(button)
+  await new Promise(r => setTimeout(r, 300))
+  await expect(canvas.queryByRole('tooltip')).toBeNull()
+})
+
+/** Longer delay for progressive-disclosure tooltips on data visualizations. */
+export const CustomDelay = meta.story({
+  args: { label: 'Slow tooltip', delay: 500 },
+})
+
+/** Icon-only button that gets its accessible name from the tooltip label. */
+export const IconOnlyTrigger = meta.story({
+  args: {
+    label: 'Previous Sentence',
+    children: (
+      <button>
+        <span>icon</span>
+      </button>
+    ),
+  },
+})
+IconOnlyTrigger.test('sets aria-label from label prop', async ({ canvas }) => {
+  const button = await canvas.findByRole('button')
+  await expect(button).toHaveAttribute('aria-label', 'Previous Sentence')
+})
+
+/** Trigger with a pre-existing aria-label that should not be overwritten. */
+export const CustomAriaLabel = meta.story({
+  args: {
+    label: 'Previous Sentence',
+    children: <button aria-label="Custom label">icon</button>,
+  },
+})
+CustomAriaLabel.test('preserves existing aria-label on trigger', async ({ canvas }) => {
+  const button = await canvas.findByRole('button')
+  await expect(button).toHaveAttribute('aria-label', 'Custom label')
+})

package/src/Tooltip/Tooltip.tsx

@@ -0,0 +1,107 @@
+'use client'
+
+import { Kbd } from '../Kbd/Kbd'
+import { type ReactElement, cloneElement, useCallback, useEffect, useRef, useState } from 'react'
+
+type TooltipProps = {
+  label: string
+  shortcut?: string | string[]
+  position?: 'top' | 'bottom'
+  delay?: number
+  maxWidth?: number
+  disabled?: boolean
+  className?: string
+  children: ReactElement<{ 'aria-label'?: string }>
+}
+
+const DEFAULT_DELAY = 200
+
+export const Tooltip = ({
+  label,
+  shortcut,
+  position = 'top',
+  delay = DEFAULT_DELAY,
+  maxWidth,
+  disabled,
+  className,
+  children,
+}: TooltipProps) => {
+  const [visible, setVisible] = useState(false)
+  const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+  const wrapperRef = useRef<HTMLDivElement>(null)
+
+  const show = useCallback(() => {
+    if (disabled) return
+    timeoutRef.current = setTimeout(() => setVisible(true), delay)
+  }, [disabled, delay])
+
+  const hide = useCallback(() => {
+    if (timeoutRef.current) {
+      clearTimeout(timeoutRef.current)
+      timeoutRef.current = null
+    }
+    setVisible(false)
+  }, [])
+
+  useEffect(() => {
+    if (disabled && timeoutRef.current) {
+      clearTimeout(timeoutRef.current)
+      timeoutRef.current = null
+    }
+  }, [disabled])
+
+  useEffect(() => {
+    return () => {
+      if (timeoutRef.current) clearTimeout(timeoutRef.current)
+    }
+  }, [])
+
+  useEffect(() => {
+    if (!visible) return
+    let lastCheck = 0
+    const handlePointerMove = (e: PointerEvent) => {
+      if (e.timeStamp - lastCheck < 100) return
+      lastCheck = e.timeStamp
+      const rect = wrapperRef.current?.getBoundingClientRect()
+      if (!rect) return
+      const inside =
+        e.clientX >= rect.left &&
+        e.clientX <= rect.right &&
+        e.clientY >= rect.top &&
+        e.clientY <= rect.bottom
+      if (!inside) hide()
+    }
+    document.addEventListener('pointermove', handlePointerMove, { passive: true })
+    return () => document.removeEventListener('pointermove', handlePointerMove)
+  }, [visible, hide])
+
+  const positionClasses = position === 'top' ? 'bottom-full mb-2' : 'top-full mt-2'
+
+  return (
+    <div
+      ref={wrapperRef}
+      className={`relative inline-flex${className ? ` ${className}` : ''}`}
+      onMouseEnter={show}
+      onMouseLeave={hide}
+      onPointerDown={hide}
+      onFocus={show}
+      onBlur={hide}
+    >
+      {cloneElement(children, {
+        'aria-label': children.props['aria-label'] ?? label,
+      })}
+      {visible && !disabled && (
+        <div
+          role="tooltip"
+          style={maxWidth ? { maxWidth } : undefined}
+          className={`absolute left-1/2 z-50 -translate-x-1/2 ${maxWidth ? 'whitespace-normal' : 'whitespace-nowrap'} bg-foreground text-background pointer-events-none flex items-center gap-1.5 rounded-lg px-2.5 py-1.5 text-xs shadow-lg ${positionClasses}`}
+        >
+          {label}
+          {shortcut && (
+            <Kbd keys={shortcut} size="sm" className="bg-background/15 border-transparent" />
+          )}
+        </div>
+      )}
+    </div>
+  )
+}

package/src/helpers/cn/cn.ts

@@ -0,0 +1,6 @@
+import { clsx, type ClassValue } from 'clsx'
+import { twMerge } from 'tailwind-merge'
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}

package/src/helpers/getModKey/getModKey.ts

@@ -0,0 +1,2 @@
+export const getModKey = (): string =>
+  typeof navigator !== 'undefined' && /Mac|iPhone|iPad/.test(navigator.userAgent) ? 'Cmd' : 'Ctrl'

package/src/helpers/getModKey/getModKey.vi.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

@@ -0,0 +1,30 @@
+export { Button, buttonVariants } from './Button/Button'
+export type { ButtonProps } from './Button/Button.types'
+
+export { Kbd, kbdVariants } from './Kbd/Kbd'
+export type { KbdProps } from './Kbd/Kbd.types'
+
+export { ProgressRing } from './ProgressRing/ProgressRing'
+
+export { Slider } from './Slider/Slider'
+
+export { Switch } from './Switch/Switch'
+
+export { Select } from './Select/Select'
+export type {
+  SelectOption,
+  SelectGroup,
+  SelectOptionState,
+  SelectProps,
+} from './Select/Select.types'
+
+export { Tooltip } from './Tooltip/Tooltip'
+
+export { ThemeProvider } from './ThemeProvider/ThemeProvider'
+
+export { ThemeCycler } from './ThemeCycler/ThemeCycler'
+
+export { Toaster } from './Toaster/Toaster'
+
+export { cn } from './helpers/cn/cn'
+export { getModKey } from './helpers/getModKey/getModKey'