@lovett/ui 0.0.10 → 0.1.0

package/src/__tests__/tooltip.test.tsx

@@ -0,0 +1,355 @@
+/**
+ * Tooltip — hover / focus label on lib/anchor + lib/layer-stack.
+ *
+ * Contract under test: the child is the trigger (no wrapper), role=tooltip
+ * + aria-describedby wiring while open, the 300 ms hover delay and 0 ms
+ * close, immediate open on keyboard focus but NOT on pointer focus,
+ * press-to-dismiss, Escape through the layer stack (a tooltip in a Modal
+ * closes alone), never focusable / pointer-events none, controlled state,
+ * child handler + ref composition, and positioning with mocked geometry.
+ */
+import { createRef } from 'react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { act, render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import Modal from '../modal'
+import { Tooltip } from '../tooltip'
+import { mockGeometry, setViewport } from './helpers/geometry'
+
+const trigger = () => screen.getByRole('button', { name: 'Archive' })
+const tip = () => screen.getByRole('tooltip')
+const advance = (ms: number) =>
+  act(() => {
+    vi.advanceTimersByTime(ms)
+  })
+
+describe('Tooltip', () => {
+  let user: ReturnType<typeof userEvent.setup>
+  beforeEach(() => {
+    vi.useFakeTimers()
+    // RTL's asyncWrapper drains with a real setTimeout(0) unless it finds a
+    // jest-style advanceTimersByTime; without this shim every user-event
+    // call hangs under vitest fake timers.
+    vi.stubGlobal('jest', {
+      advanceTimersByTime: (ms: number) => vi.advanceTimersByTime(ms),
+    })
+    user = userEvent.setup({ advanceTimers: vi.advanceTimersByTime })
+  })
+  afterEach(() => {
+    vi.useRealTimers()
+    vi.unstubAllGlobals()
+  })
+
+  function Basic(props: Partial<React.ComponentProps<typeof Tooltip>> = {}) {
+    return (
+      <Tooltip content="Archive this task" {...props}>
+        <button type="button" aria-label="Archive">
+          A
+        </button>
+      </Tooltip>
+    )
+  }
+
+  describe('rendering', () => {
+    it('renders the child as-is: no wrapper, no tooltip, no aria-describedby while closed', () => {
+      const { container } = render(<Basic />)
+      expect(container.firstElementChild).toBe(trigger())
+      expect(screen.queryByRole('tooltip')).toBeNull()
+      expect(trigger()).not.toHaveAttribute('aria-describedby')
+    })
+
+    it('forwards the child ref', () => {
+      const ref = createRef<HTMLButtonElement>()
+      render(
+        <Tooltip content="x">
+          <button ref={ref} type="button" aria-label="Archive" />
+        </Tooltip>,
+      )
+      expect(ref.current).toBe(trigger())
+    })
+
+    it('throws for a non-element child', () => {
+      const spy = vi.spyOn(console, 'error').mockImplementation(() => {})
+      expect(() =>
+        render(
+          // @ts-expect-error — the contract is one element child; this pins the runtime guard.
+          <Tooltip content="x">plain text</Tooltip>,
+        ),
+      ).toThrow(/exactly one element child/)
+      spy.mockRestore()
+    })
+
+    it('with null content, the child passes through and nothing ever opens', async () => {
+      render(<Basic content={null} />)
+      await user.hover(trigger())
+      advance(1000)
+      expect(screen.queryByRole('tooltip')).toBeNull()
+    })
+  })
+
+  describe('hover', () => {
+    it('opens after the 300 ms delay, portaled to body, and wires aria-describedby', async () => {
+      const { container } = render(<Basic />)
+      await user.hover(trigger())
+      expect(screen.queryByRole('tooltip')).toBeNull()
+      advance(299)
+      expect(screen.queryByRole('tooltip')).toBeNull()
+      advance(1)
+      const t = tip()
+      expect(t).toHaveTextContent('Archive this task')
+      expect(t.parentElement).toBe(document.body)
+      expect(container.contains(t)).toBe(false)
+      expect(trigger()).toHaveAttribute('aria-describedby', t.id)
+      expect(t).toHaveAttribute('data-slot', 'tooltip')
+    })
+
+    it('closes immediately on unhover and drops aria-describedby', async () => {
+      render(<Basic />)
+      await user.hover(trigger())
+      advance(300)
+      expect(tip()).toBeInTheDocument()
+      await user.unhover(trigger())
+      expect(screen.queryByRole('tooltip')).toBeNull()
+      expect(trigger()).not.toHaveAttribute('aria-describedby')
+    })
+
+    it('leaving before the delay cancels the open', async () => {
+      render(<Basic />)
+      await user.hover(trigger())
+      advance(150)
+      await user.unhover(trigger())
+      advance(1000)
+      expect(screen.queryByRole('tooltip')).toBeNull()
+    })
+
+    it('honours custom openDelay / closeDelay', async () => {
+      render(<Basic openDelay={50} closeDelay={100} />)
+      await user.hover(trigger())
+      advance(50)
+      expect(tip()).toBeInTheDocument()
+      await user.unhover(trigger())
+      expect(tip()).toBeInTheDocument()
+      advance(100)
+      expect(screen.queryByRole('tooltip')).toBeNull()
+    })
+
+    it('merges an existing aria-describedby rather than replacing it', async () => {
+      render(
+        <>
+          <p id="hint">hint</p>
+          <Tooltip content="x">
+            <button type="button" aria-label="Archive" aria-describedby="hint" />
+          </Tooltip>
+        </>,
+      )
+      await user.hover(trigger())
+      advance(300)
+      expect(trigger().getAttribute('aria-describedby')).toBe(`hint ${tip().id}`)
+      await user.unhover(trigger())
+      expect(trigger()).toHaveAttribute('aria-describedby', 'hint')
+    })
+  })
+
+  describe('focus', () => {
+    it('opens immediately on keyboard focus and closes on blur', async () => {
+      render(
+        <>
+          <Basic />
+          <button type="button">Next</button>
+        </>,
+      )
+      await user.tab()
+      expect(document.activeElement).toBe(trigger())
+      expect(tip()).toBeInTheDocument()
+      expect(trigger()).toHaveAttribute('aria-describedby', tip().id)
+      await user.tab()
+      expect(screen.queryByRole('tooltip')).toBeNull()
+    })
+
+    it('a focus that arrives by pointer (a click) does not open it', async () => {
+      render(<Basic />)
+      await user.click(trigger())
+      expect(document.activeElement).toBe(trigger())
+      advance(1000)
+      expect(screen.queryByRole('tooltip')).toBeNull()
+    })
+
+    it('pressing the trigger dismisses an open tooltip', async () => {
+      render(<Basic />)
+      await user.hover(trigger())
+      advance(300)
+      expect(tip()).toBeInTheDocument()
+      await user.pointer({ keys: '[MouseLeft>]', target: trigger() })
+      expect(screen.queryByRole('tooltip')).toBeNull()
+      await user.pointer({ keys: '[/MouseLeft]', target: trigger() })
+    })
+
+    it('removes its document press listeners on release and on unmount (no stale closure per interrupted press)', async () => {
+      const added = vi.spyOn(document, 'addEventListener')
+      const removed = vi.spyOn(document, 'removeEventListener')
+      try {
+        const { unmount } = render(<Basic />)
+        const pressListeners = () =>
+          added.mock.calls.filter(([type]) => type === 'pointerup' || type === 'pointercancel')
+        const removedPressListeners = () =>
+          removed.mock.calls.filter(([type]) => type === 'pointerup' || type === 'pointercancel')
+
+        // A full press: the listeners go on at pointerdown and come off at pointerup.
+        await user.pointer({ keys: '[MouseLeft>]', target: trigger() })
+        expect(pressListeners()).toHaveLength(2)
+        await user.pointer({ keys: '[/MouseLeft]', target: trigger() })
+        expect(removedPressListeners().map(([, fn]) => fn)).toEqual(
+          pressListeners().map(([, fn]) => fn),
+        )
+
+        // An interrupted press: unmount mid-press must remove them too.
+        added.mockClear()
+        removed.mockClear()
+        await user.pointer({ keys: '[MouseLeft>]', target: trigger() })
+        expect(pressListeners()).toHaveLength(2)
+        unmount()
+        expect(removedPressListeners().map(([, fn]) => fn)).toEqual(
+          pressListeners().map(([, fn]) => fn),
+        )
+      } finally {
+        added.mockRestore()
+        removed.mockRestore()
+      }
+    })
+
+    it('never traps or moves focus: the tip is not focusable and does not take the pointer', async () => {
+      render(<Basic />)
+      await user.tab()
+      const t = tip()
+      expect(t).not.toHaveAttribute('tabindex')
+      expect(t).toHaveClass('pointer-events-none')
+      expect(document.activeElement).toBe(trigger())
+    })
+
+    it('composes the child handlers', async () => {
+      const onFocus = vi.fn()
+      const onPointerEnter = vi.fn()
+      render(
+        <Tooltip content="x">
+          <button type="button" aria-label="Archive" onFocus={onFocus} onPointerEnter={onPointerEnter} />
+        </Tooltip>,
+      )
+      await user.hover(trigger())
+      await user.tab()
+      expect(onPointerEnter).toHaveBeenCalledTimes(1)
+      expect(onFocus).toHaveBeenCalledTimes(1)
+    })
+  })
+
+  describe('Escape + layers', () => {
+    it('Escape dismisses and leaves focus where it was', async () => {
+      render(<Basic />)
+      await user.tab()
+      expect(tip()).toBeInTheDocument()
+      await user.keyboard('{Escape}')
+      expect(screen.queryByRole('tooltip')).toBeNull()
+      expect(document.activeElement).toBe(trigger())
+    })
+
+    it('inside a Modal, Escape closes only the tooltip; the next Escape closes the modal', async () => {
+      const onClose = vi.fn()
+      render(
+        <Modal isOpen onClose={onClose} title="Settings">
+          <Basic />
+        </Modal>,
+      )
+      await user.hover(trigger())
+      advance(300)
+      expect(tip()).toBeInTheDocument()
+      await user.keyboard('{Escape}')
+      expect(screen.queryByRole('tooltip')).toBeNull()
+      expect(onClose).not.toHaveBeenCalled()
+      await user.keyboard('{Escape}')
+      expect(onClose).toHaveBeenCalledTimes(1)
+    })
+
+    it('does not listen for Escape while closed', async () => {
+      const onOpenChange = vi.fn()
+      render(<Basic onOpenChange={onOpenChange} />)
+      await user.keyboard('{Escape}')
+      expect(onOpenChange).not.toHaveBeenCalled()
+    })
+  })
+
+  describe('controlled / uncontrolled', () => {
+    it('defaultOpen renders it open', () => {
+      render(<Basic defaultOpen />)
+      expect(tip()).toBeInTheDocument()
+    })
+
+    it('controlled `open` renders regardless of hover; onOpenChange reports intent', async () => {
+      const onOpenChange = vi.fn()
+      render(<Basic open={false} onOpenChange={onOpenChange} />)
+      await user.hover(trigger())
+      advance(300)
+      expect(onOpenChange).toHaveBeenCalledWith(true)
+      expect(screen.queryByRole('tooltip')).toBeNull()
+    })
+
+    it('controlled open=true shows it and unhover reports false', async () => {
+      const onOpenChange = vi.fn()
+      render(<Basic open onOpenChange={onOpenChange} />)
+      expect(tip()).toBeInTheDocument()
+      await user.hover(trigger())
+      await user.unhover(trigger())
+      expect(onOpenChange).toHaveBeenCalledWith(false)
+      expect(tip()).toBeInTheDocument()
+    })
+  })
+
+  describe('surface + positioning (mocked geometry)', () => {
+    let restore: () => void
+    beforeEach(() => {
+      restore = mockGeometry()
+      setViewport(1000, 800)
+    })
+    afterEach(() => restore())
+
+    it('sits above the trigger, centred, with the popover-family chrome and the entry motion', async () => {
+      render(
+        <Tooltip content="x" className="mine">
+          <button type="button" aria-label="Archive" data-rect="400,300,80,32" />
+        </Tooltip>,
+      )
+      await user.tab()
+      const t = tip()
+      expect(t.style.position).toBe('fixed')
+      expect(t).toHaveAttribute('data-side', 'top')
+      expect(t).toHaveAttribute('data-align', 'center')
+      expect(t.style.left).toBe('440px')
+      expect(t.style.top).toBe(`${300 - 6}px`)
+      expect(t).toHaveAttribute('data-positioned', 'true')
+      expect(t).toHaveClass('ds-enter-pop', 'mine')
+      expect(t.style.background).toContain('--popover')
+      expect(t.style.padding).toContain('--space-1')
+    })
+
+    it('flips below the trigger at the top of the viewport', async () => {
+      render(
+        <Tooltip content="x">
+          <button type="button" aria-label="Archive" data-rect="400,4,80,32" />
+        </Tooltip>,
+      )
+      await user.tab()
+      expect(tip()).toHaveAttribute('data-side', 'bottom')
+      expect(tip().style.top).toBe(`${4 + 32 + 6}px`)
+    })
+
+    it('honours side / align / offset', async () => {
+      render(
+        <Tooltip content="x" side="right" align="start" offset={10}>
+          <button type="button" aria-label="Archive" data-rect="400,300,80,32" />
+        </Tooltip>,
+      )
+      await user.tab()
+      expect(tip()).toHaveAttribute('data-side', 'right')
+      expect(tip().style.left).toBe(`${480 + 10}px`)
+      expect(tip().style.top).toBe('300px')
+    })
+  })
+})