@startsimpli/ui 0.4.7 → 0.4.9

package/src/components/command-palette/__tests__/CommandResultItem.test.tsx

@@ -0,0 +1,166 @@
+import { render, screen, fireEvent } from '@testing-library/react'
+import { CommandResultItem } from '../CommandResultItem'
+
+// lucide-react icons are SVGs — mock them as simple elements so tests are
+// not sensitive to SVG implementation details while still being renderable.
+jest.mock('lucide-react', () => ({
+  Search: (props: React.SVGProps<SVGSVGElement>) => (
+    <svg data-testid="icon-search" {...props} />
+  ),
+  ArrowRight: (props: React.SVGProps<SVGSVGElement>) => (
+    <svg data-testid="icon-arrow-right" {...props} />
+  ),
+}))
+
+const StarIcon = (props: React.SVGProps<SVGSVGElement>) => (
+  <svg data-testid="icon-star" {...props} />
+)
+
+describe('CommandResultItem', () => {
+  const defaultProps = {
+    label: 'Go to Dashboard',
+    selected: false,
+    onClick: jest.fn(),
+  }
+
+  beforeEach(() => {
+    jest.clearAllMocks()
+  })
+
+  describe('label', () => {
+    it('renders the label text', () => {
+      render(<CommandResultItem {...defaultProps} />)
+      expect(screen.getByText('Go to Dashboard')).toBeInTheDocument()
+    })
+  })
+
+  describe('detail', () => {
+    it('renders detail text when provided', () => {
+      render(<CommandResultItem {...defaultProps} detail="Overview of metrics" />)
+      expect(screen.getByText('Overview of metrics')).toBeInTheDocument()
+    })
+
+    it('does not render detail element when omitted', () => {
+      render(<CommandResultItem {...defaultProps} />)
+      // Only the label paragraph should be present; no second <p>
+      const paragraphs = document.querySelectorAll('p')
+      expect(paragraphs).toHaveLength(1)
+    })
+  })
+
+  describe('shortcut', () => {
+    it('renders the shortcut in a kbd element when provided', () => {
+      render(<CommandResultItem {...defaultProps} shortcut="⌘K" />)
+      const kbd = screen.getByText('⌘K')
+      expect(kbd.tagName).toBe('KBD')
+    })
+
+    it('does not render a kbd element when shortcut is omitted', () => {
+      const { container } = render(<CommandResultItem {...defaultProps} />)
+      expect(container.querySelector('kbd')).not.toBeInTheDocument()
+    })
+  })
+
+  describe('icon', () => {
+    it('renders the provided icon', () => {
+      render(<CommandResultItem {...defaultProps} icon={StarIcon} />)
+      expect(screen.getByTestId('icon-star')).toBeInTheDocument()
+    })
+
+    it('falls back to Search icon when no icon prop is given', () => {
+      render(<CommandResultItem {...defaultProps} />)
+      expect(screen.getByTestId('icon-search')).toBeInTheDocument()
+    })
+  })
+
+  describe('showArrow', () => {
+    it('does not render ArrowRight by default', () => {
+      render(<CommandResultItem {...defaultProps} />)
+      expect(screen.queryByTestId('icon-arrow-right')).not.toBeInTheDocument()
+    })
+
+    it('renders ArrowRight when showArrow is true', () => {
+      render(<CommandResultItem {...defaultProps} showArrow />)
+      expect(screen.getByTestId('icon-arrow-right')).toBeInTheDocument()
+    })
+  })
+
+  describe('selected state', () => {
+    it('sets aria-selected="true" when selected', () => {
+      render(<CommandResultItem {...defaultProps} selected />)
+      const item = screen.getByRole('option')
+      expect(item).toHaveAttribute('aria-selected', 'true')
+    })
+
+    it('sets aria-selected="false" when not selected', () => {
+      render(<CommandResultItem {...defaultProps} selected={false} />)
+      const item = screen.getByRole('option')
+      expect(item).toHaveAttribute('aria-selected', 'false')
+    })
+
+    it('applies bg-blue-50 highlight class when selected', () => {
+      render(<CommandResultItem {...defaultProps} selected />)
+      const item = screen.getByRole('option')
+      expect(item.className).toMatch(/bg-blue-50/)
+    })
+
+    it('does not apply bg-blue-50 when not selected', () => {
+      render(<CommandResultItem {...defaultProps} selected={false} />)
+      const item = screen.getByRole('option')
+      expect(item.className).not.toMatch(/bg-blue-50/)
+    })
+  })
+
+  describe('colorClass', () => {
+    it('applies the default color class to the icon container', () => {
+      const { container } = render(<CommandResultItem {...defaultProps} />)
+      const iconContainer = container.querySelector('.w-8.h-8')
+      expect(iconContainer?.className).toMatch(/bg-gray-100/)
+      expect(iconContainer?.className).toMatch(/text-gray-600/)
+    })
+
+    it('applies a custom colorClass to the icon container', () => {
+      const { container } = render(
+        <CommandResultItem {...defaultProps} colorClass="bg-blue-100 text-blue-600" />
+      )
+      const iconContainer = container.querySelector('.w-8.h-8')
+      expect(iconContainer?.className).toMatch(/bg-blue-100/)
+      expect(iconContainer?.className).toMatch(/text-blue-600/)
+    })
+  })
+
+  describe('onClick', () => {
+    it('fires onClick when the item is clicked', () => {
+      const onClick = jest.fn()
+      render(<CommandResultItem {...defaultProps} onClick={onClick} />)
+      fireEvent.click(screen.getByRole('option'))
+      expect(onClick).toHaveBeenCalledTimes(1)
+    })
+
+    it('does not fire onClick when a different element is clicked', () => {
+      const onClick = jest.fn()
+      render(
+        <div>
+          <CommandResultItem {...defaultProps} onClick={onClick} label="Target" />
+          <button data-testid="other">Other</button>
+        </div>
+      )
+      fireEvent.click(screen.getByTestId('other'))
+      expect(onClick).not.toHaveBeenCalled()
+    })
+  })
+
+  describe('label typography without detail', () => {
+    it('uses text-gray-700 on label when no detail is present', () => {
+      render(<CommandResultItem {...defaultProps} />)
+      const label = screen.getByText('Go to Dashboard')
+      expect(label.className).toMatch(/text-gray-700/)
+    })
+
+    it('uses text-gray-900 on label when detail is present', () => {
+      render(<CommandResultItem {...defaultProps} detail="some detail" />)
+      const label = screen.getByText('Go to Dashboard')
+      expect(label.className).toMatch(/text-gray-900/)
+    })
+  })
+})

package/src/components/command-palette/__tests__/command-palette-context.test.tsx

@@ -0,0 +1,166 @@
+import { render, screen, act } from '@testing-library/react'
+import { fireEvent } from '@testing-library/react'
+import { renderHook } from '@testing-library/react'
+import { CommandPaletteProvider, useCommandPalette } from '../command-palette-context'
+
+// Wrapper that exposes the context value through data attributes so we can
+// assert on it without tying tests to component internals.
+function ContextProbe() {
+  const { isOpen, open, close, toggle } = useCommandPalette()
+  return (
+    <div
+      data-testid="probe"
+      data-open={String(isOpen)}
+    >
+      <button data-testid="btn-open" onClick={open}>open</button>
+      <button data-testid="btn-close" onClick={close}>close</button>
+      <button data-testid="btn-toggle" onClick={toggle}>toggle</button>
+    </div>
+  )
+}
+
+function renderWithProvider() {
+  return render(
+    <CommandPaletteProvider>
+      <ContextProbe />
+    </CommandPaletteProvider>
+  )
+}
+
+function probe() {
+  return screen.getByTestId('probe')
+}
+
+describe('CommandPaletteProvider / useCommandPalette', () => {
+  describe('initial state', () => {
+    it('starts with isOpen = false', () => {
+      renderWithProvider()
+      expect(probe().dataset.open).toBe('false')
+    })
+  })
+
+  describe('open()', () => {
+    it('sets isOpen to true', () => {
+      renderWithProvider()
+      fireEvent.click(screen.getByTestId('btn-open'))
+      expect(probe().dataset.open).toBe('true')
+    })
+
+    it('is idempotent — calling open twice leaves isOpen true', () => {
+      renderWithProvider()
+      fireEvent.click(screen.getByTestId('btn-open'))
+      fireEvent.click(screen.getByTestId('btn-open'))
+      expect(probe().dataset.open).toBe('true')
+    })
+  })
+
+  describe('close()', () => {
+    it('sets isOpen to false', () => {
+      renderWithProvider()
+      fireEvent.click(screen.getByTestId('btn-open'))
+      fireEvent.click(screen.getByTestId('btn-close'))
+      expect(probe().dataset.open).toBe('false')
+    })
+
+    it('is idempotent — calling close when already closed keeps isOpen false', () => {
+      renderWithProvider()
+      fireEvent.click(screen.getByTestId('btn-close'))
+      expect(probe().dataset.open).toBe('false')
+    })
+  })
+
+  describe('toggle()', () => {
+    it('opens when currently closed', () => {
+      renderWithProvider()
+      fireEvent.click(screen.getByTestId('btn-toggle'))
+      expect(probe().dataset.open).toBe('true')
+    })
+
+    it('closes when currently open', () => {
+      renderWithProvider()
+      fireEvent.click(screen.getByTestId('btn-open'))
+      fireEvent.click(screen.getByTestId('btn-toggle'))
+      expect(probe().dataset.open).toBe('false')
+    })
+
+    it('toggles back and forth correctly', () => {
+      renderWithProvider()
+      const btn = screen.getByTestId('btn-toggle')
+      fireEvent.click(btn)
+      expect(probe().dataset.open).toBe('true')
+      fireEvent.click(btn)
+      expect(probe().dataset.open).toBe('false')
+      fireEvent.click(btn)
+      expect(probe().dataset.open).toBe('true')
+    })
+  })
+
+  describe('Cmd+K / Ctrl+K keyboard shortcut', () => {
+    it('toggles isOpen on Cmd+K (metaKey)', () => {
+      renderWithProvider()
+      act(() => {
+        fireEvent.keyDown(document, { key: 'k', metaKey: true })
+      })
+      expect(probe().dataset.open).toBe('true')
+    })
+
+    it('toggles isOpen on Ctrl+K (ctrlKey)', () => {
+      renderWithProvider()
+      act(() => {
+        fireEvent.keyDown(document, { key: 'k', ctrlKey: true })
+      })
+      expect(probe().dataset.open).toBe('true')
+    })
+
+    it('toggles closed on second Cmd+K', () => {
+      renderWithProvider()
+      act(() => { fireEvent.keyDown(document, { key: 'k', metaKey: true }) })
+      act(() => { fireEvent.keyDown(document, { key: 'k', metaKey: true }) })
+      expect(probe().dataset.open).toBe('false')
+    })
+
+    it('does not toggle on plain k keypress', () => {
+      renderWithProvider()
+      act(() => { fireEvent.keyDown(document, { key: 'k' }) })
+      expect(probe().dataset.open).toBe('false')
+    })
+
+    it('removes the global keydown listener on unmount (no state update after unmount)', () => {
+      const { unmount } = renderWithProvider()
+      unmount()
+      // Should not throw when dispatching after unmount
+      expect(() => {
+        act(() => { fireEvent.keyDown(document, { key: 'k', metaKey: true }) })
+      }).not.toThrow()
+    })
+  })
+
+  describe('Escape key', () => {
+    it('closes the palette when open', () => {
+      renderWithProvider()
+      // Open it first
+      fireEvent.click(screen.getByTestId('btn-open'))
+      expect(probe().dataset.open).toBe('true')
+
+      act(() => { fireEvent.keyDown(document, { key: 'Escape' }) })
+      expect(probe().dataset.open).toBe('false')
+    })
+
+    it('does nothing when palette is already closed', () => {
+      renderWithProvider()
+      act(() => { fireEvent.keyDown(document, { key: 'Escape' }) })
+      expect(probe().dataset.open).toBe('false')
+    })
+  })
+
+  describe('useCommandPalette — usage outside provider', () => {
+    it('throws when used outside CommandPaletteProvider', () => {
+      // Suppress the expected React error boundary console output
+      const spy = jest.spyOn(console, 'error').mockImplementation(() => {})
+      expect(() => {
+        renderHook(() => useCommandPalette())
+      }).toThrow('useCommandPalette must be used within a CommandPaletteProvider')
+      spy.mockRestore()
+    })
+  })
+})

package/src/components/command-palette/__tests__/useCommandPaletteSearch.test.ts

@@ -0,0 +1,271 @@
+import { renderHook, act } from '@testing-library/react'
+import { useCommandPaletteSearch, CommandItem } from '../useCommandPaletteSearch'
+
+const Home = () => null
+Home.displayName = 'Home'
+
+const Settings = () => null
+Settings.displayName = 'Settings'
+
+const COMMANDS: CommandItem[] = [
+  {
+    id: 'nav-home',
+    label: 'Go to Home',
+    detail: 'Dashboard overview',
+    group: 'Navigation',
+    onSelect: '/home',
+    icon: Home,
+  },
+  {
+    id: 'nav-settings',
+    label: 'Go to Settings',
+    detail: 'Account preferences',
+    group: 'Navigation',
+    onSelect: '/settings',
+    icon: Settings,
+  },
+  {
+    id: 'action-invite',
+    label: 'Invite User',
+    detail: 'Send invite email',
+    group: 'Actions',
+    onSelect: jest.fn(),
+    shortcut: '⌘I',
+  },
+  {
+    id: 'action-export',
+    label: 'Export Data',
+    group: 'Actions',
+    onSelect: jest.fn(),
+  },
+]
+
+function makeOpts(overrides: Partial<Parameters<typeof useCommandPaletteSearch>[0]> = {}) {
+  return {
+    commands: COMMANDS,
+    onExecute: jest.fn(),
+    isOpen: true,
+    ...overrides,
+  }
+}
+
+function makeKeyEvent(key: string): React.KeyboardEvent {
+  return { key, preventDefault: jest.fn() } as unknown as React.KeyboardEvent
+}
+
+describe('useCommandPaletteSearch', () => {
+  describe('initial state', () => {
+    it('returns empty query on open', () => {
+      const { result } = renderHook(() => useCommandPaletteSearch(makeOpts()))
+      expect(result.current.query).toBe('')
+    })
+
+    it('selects first item (index 0) on open', () => {
+      const { result } = renderHook(() => useCommandPaletteSearch(makeOpts()))
+      expect(result.current.selectedIndex).toBe(0)
+    })
+
+    it('exposes setQuery and onKeyDown functions', () => {
+      const { result } = renderHook(() => useCommandPaletteSearch(makeOpts()))
+      expect(typeof result.current.setQuery).toBe('function')
+      expect(typeof result.current.onKeyDown).toBe('function')
+    })
+  })
+
+  describe('filtering', () => {
+    it('shows all commands when query is empty', () => {
+      const { result } = renderHook(() => useCommandPaletteSearch(makeOpts()))
+      const allItems = result.current.filteredGroups.flatMap((g) => g.items)
+      expect(allItems).toHaveLength(COMMANDS.length)
+    })
+
+    it('narrows results by label match (case-insensitive)', () => {
+      const { result } = renderHook(() => useCommandPaletteSearch(makeOpts()))
+      act(() => { result.current.setQuery('invite') })
+      const items = result.current.filteredGroups.flatMap((g) => g.items)
+      expect(items).toHaveLength(1)
+      expect(items[0].id).toBe('action-invite')
+    })
+
+    it('matches on detail field', () => {
+      const { result } = renderHook(() => useCommandPaletteSearch(makeOpts()))
+      act(() => { result.current.setQuery('dashboard') })
+      const items = result.current.filteredGroups.flatMap((g) => g.items)
+      expect(items).toHaveLength(1)
+      expect(items[0].id).toBe('nav-home')
+    })
+
+    it('is case-insensitive', () => {
+      const { result } = renderHook(() => useCommandPaletteSearch(makeOpts()))
+      act(() => { result.current.setQuery('EXPORT') })
+      const items = result.current.filteredGroups.flatMap((g) => g.items)
+      expect(items).toHaveLength(1)
+      expect(items[0].id).toBe('action-export')
+    })
+
+    it('returns empty groups when no commands match', () => {
+      const { result } = renderHook(() => useCommandPaletteSearch(makeOpts()))
+      act(() => { result.current.setQuery('zzznomatch') })
+      expect(result.current.filteredGroups).toHaveLength(0)
+    })
+
+    it('resets selection to 0 when query changes', () => {
+      const { result } = renderHook(() => useCommandPaletteSearch(makeOpts()))
+      // Move selection down first
+      act(() => { result.current.onKeyDown(makeKeyEvent('ArrowDown')) })
+      expect(result.current.selectedIndex).toBe(1)
+      // Now type to filter
+      act(() => { result.current.setQuery('Settings') })
+      expect(result.current.selectedIndex).toBe(0)
+    })
+  })
+
+  describe('grouping', () => {
+    it('groups items by their group field', () => {
+      const { result } = renderHook(() => useCommandPaletteSearch(makeOpts()))
+      const labels = result.current.filteredGroups.map((g) => g.label)
+      expect(labels).toContain('Navigation')
+      expect(labels).toContain('Actions')
+    })
+
+    it('places each item in the correct group', () => {
+      const { result } = renderHook(() => useCommandPaletteSearch(makeOpts()))
+      const nav = result.current.filteredGroups.find((g) => g.label === 'Navigation')!
+      expect(nav.items.map((i) => i.id)).toEqual(['nav-home', 'nav-settings'])
+      const actions = result.current.filteredGroups.find((g) => g.label === 'Actions')!
+      expect(actions.items.map((i) => i.id)).toEqual(['action-invite', 'action-export'])
+    })
+
+    it('preserves group insertion order', () => {
+      const { result } = renderHook(() => useCommandPaletteSearch(makeOpts()))
+      const labels = result.current.filteredGroups.map((g) => g.label)
+      expect(labels[0]).toBe('Navigation')
+      expect(labels[1]).toBe('Actions')
+    })
+
+    it('produces a single group when all matches share a group', () => {
+      const { result } = renderHook(() => useCommandPaletteSearch(makeOpts()))
+      act(() => { result.current.setQuery('Go to') })
+      expect(result.current.filteredGroups).toHaveLength(1)
+      expect(result.current.filteredGroups[0].label).toBe('Navigation')
+    })
+  })
+
+  describe('keyboard navigation — ArrowDown', () => {
+    it('moves selectedIndex down by one', () => {
+      const { result } = renderHook(() => useCommandPaletteSearch(makeOpts()))
+      act(() => { result.current.onKeyDown(makeKeyEvent('ArrowDown')) })
+      expect(result.current.selectedIndex).toBe(1)
+    })
+
+    it('calls preventDefault on ArrowDown', () => {
+      const { result } = renderHook(() => useCommandPaletteSearch(makeOpts()))
+      const e = makeKeyEvent('ArrowDown')
+      act(() => { result.current.onKeyDown(e) })
+      expect(e.preventDefault).toHaveBeenCalled()
+    })
+
+    it('clamps at the last item', () => {
+      const { result } = renderHook(() => useCommandPaletteSearch(makeOpts()))
+      const lastIndex = COMMANDS.length - 1
+      // Jump to end then try to go further
+      for (let i = 0; i <= lastIndex + 2; i++) {
+        act(() => { result.current.onKeyDown(makeKeyEvent('ArrowDown')) })
+      }
+      expect(result.current.selectedIndex).toBe(lastIndex)
+    })
+  })
+
+  describe('keyboard navigation — ArrowUp', () => {
+    it('moves selectedIndex up by one', () => {
+      const { result } = renderHook(() => useCommandPaletteSearch(makeOpts()))
+      // Go down first so we have room to go up
+      act(() => { result.current.onKeyDown(makeKeyEvent('ArrowDown')) })
+      act(() => { result.current.onKeyDown(makeKeyEvent('ArrowDown')) })
+      act(() => { result.current.onKeyDown(makeKeyEvent('ArrowUp')) })
+      expect(result.current.selectedIndex).toBe(1)
+    })
+
+    it('calls preventDefault on ArrowUp', () => {
+      const { result } = renderHook(() => useCommandPaletteSearch(makeOpts()))
+      act(() => { result.current.onKeyDown(makeKeyEvent('ArrowDown')) })
+      const e = makeKeyEvent('ArrowUp')
+      act(() => { result.current.onKeyDown(e) })
+      expect(e.preventDefault).toHaveBeenCalled()
+    })
+
+    it('clamps at index 0', () => {
+      const { result } = renderHook(() => useCommandPaletteSearch(makeOpts()))
+      act(() => { result.current.onKeyDown(makeKeyEvent('ArrowUp')) })
+      act(() => { result.current.onKeyDown(makeKeyEvent('ArrowUp')) })
+      expect(result.current.selectedIndex).toBe(0)
+    })
+  })
+
+  describe('keyboard navigation — Enter', () => {
+    it('calls onExecute with the currently selected item', () => {
+      const onExecute = jest.fn()
+      const { result } = renderHook(() => useCommandPaletteSearch(makeOpts({ onExecute })))
+      // selectedIndex is 0 → nav-home
+      const e = makeKeyEvent('Enter')
+      act(() => { result.current.onKeyDown(e) })
+      expect(onExecute).toHaveBeenCalledTimes(1)
+      expect(onExecute).toHaveBeenCalledWith(COMMANDS[0])
+    })
+
+    it('calls preventDefault on Enter', () => {
+      const { result } = renderHook(() => useCommandPaletteSearch(makeOpts()))
+      const e = makeKeyEvent('Enter')
+      act(() => { result.current.onKeyDown(e) })
+      expect(e.preventDefault).toHaveBeenCalled()
+    })
+
+    it('executes the correct item after navigating down', () => {
+      const onExecute = jest.fn()
+      const { result } = renderHook(() => useCommandPaletteSearch(makeOpts({ onExecute })))
+      act(() => { result.current.onKeyDown(makeKeyEvent('ArrowDown')) })
+      act(() => { result.current.onKeyDown(makeKeyEvent('ArrowDown')) })
+      act(() => { result.current.onKeyDown(makeKeyEvent('Enter')) })
+      expect(onExecute).toHaveBeenCalledWith(COMMANDS[2])
+    })
+
+    it('does not call onExecute when filtered list is empty', () => {
+      const onExecute = jest.fn()
+      const { result } = renderHook(() => useCommandPaletteSearch(makeOpts({ onExecute })))
+      act(() => { result.current.setQuery('zzznomatch') })
+      act(() => { result.current.onKeyDown(makeKeyEvent('Enter')) })
+      expect(onExecute).not.toHaveBeenCalled()
+    })
+  })
+
+  describe('isOpen lifecycle', () => {
+    it('resets query when palette opens', () => {
+      const { result, rerender } = renderHook(
+        (props: Parameters<typeof useCommandPaletteSearch>[0]) =>
+          useCommandPaletteSearch(props),
+        { initialProps: makeOpts({ isOpen: true }) }
+      )
+      act(() => { result.current.setQuery('home') })
+      expect(result.current.query).toBe('home')
+
+      // Close then re-open
+      rerender(makeOpts({ isOpen: false }))
+      rerender(makeOpts({ isOpen: true }))
+      expect(result.current.query).toBe('')
+    })
+
+    it('resets selectedIndex when palette opens', () => {
+      const { result, rerender } = renderHook(
+        (props: Parameters<typeof useCommandPaletteSearch>[0]) =>
+          useCommandPaletteSearch(props),
+        { initialProps: makeOpts({ isOpen: true }) }
+      )
+      act(() => { result.current.onKeyDown(makeKeyEvent('ArrowDown')) })
+      expect(result.current.selectedIndex).toBe(1)
+
+      rerender(makeOpts({ isOpen: false }))
+      rerender(makeOpts({ isOpen: true }))
+      expect(result.current.selectedIndex).toBe(0)
+    })
+  })
+})

package/src/components/command-palette/index.ts

@@ -1,3 +1,9 @@
 export { CommandPalette } from './CommandPalette'
 export type { CommandPaletteProps, SearchResult, QuickAction, NavigationItem } from './CommandPalette'
 export { CommandPaletteProvider, useCommandPalette } from './command-palette-context'
+export { useCommandPaletteSearch } from './useCommandPaletteSearch'
+export type { CommandItem, CommandGroup as CommandGroupType, UseCommandPaletteOptions, UseCommandPaletteReturn } from './useCommandPaletteSearch'
+export { CommandGroup } from './CommandGroup'
+export type { CommandGroupProps } from './CommandGroup'
+export { CommandResultItem } from './CommandResultItem'
+export type { CommandResultItemProps } from './CommandResultItem'