@startsimpli/ui 0.4.6 → 0.4.8

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/command-palette-context.tsx

@@ -0,0 +1,51 @@
+'use client'
+
+import { createContext, useContext, useState, useCallback, useEffect, ReactNode } from 'react'
+
+interface CommandPaletteContextType {
+  isOpen: boolean
+  open: () => void
+  close: () => void
+  toggle: () => void
+}
+
+const CommandPaletteContext = createContext<CommandPaletteContextType | undefined>(undefined)
+
+export function CommandPaletteProvider({ children }: { children: ReactNode }) {
+  const [isOpen, setIsOpen] = useState(false)
+
+  const open = useCallback(() => setIsOpen(true), [])
+  const close = useCallback(() => setIsOpen(false), [])
+  const toggle = useCallback(() => setIsOpen(prev => !prev), [])
+
+  // Global keyboard shortcut: CMD+K / Ctrl+K
+  useEffect(() => {
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if ((e.metaKey || e.ctrlKey) && e.key === 'k') {
+        e.preventDefault()
+        toggle()
+      }
+      if (e.key === 'Escape' && isOpen) {
+        e.preventDefault()
+        close()
+      }
+    }
+
+    document.addEventListener('keydown', handleKeyDown)
+    return () => document.removeEventListener('keydown', handleKeyDown)
+  }, [isOpen, toggle, close])
+
+  return (
+    <CommandPaletteContext.Provider value={{ isOpen, open, close, toggle }}>
+      {children}
+    </CommandPaletteContext.Provider>
+  )
+}
+
+export function useCommandPalette() {
+  const context = useContext(CommandPaletteContext)
+  if (!context) {
+    throw new Error('useCommandPalette must be used within a CommandPaletteProvider')
+  }
+  return context
+}

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

@@ -0,0 +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'

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

@@ -0,0 +1,114 @@
+'use client'
+
+import { useState, useEffect, useCallback, useMemo } from 'react'
+
+/** Unified command item for the palette */
+export interface CommandItem {
+  id: string
+  icon?: React.ElementType
+  label: string
+  detail?: string
+  shortcut?: string
+  group: string
+  /** Navigate path or action callback */
+  onSelect: (() => void) | string
+  /** Optional color class for icon container */
+  colorClass?: string
+}
+
+export interface CommandGroup {
+  label: string
+  items: CommandItem[]
+}
+
+export interface UseCommandPaletteOptions {
+  commands: CommandItem[]
+  onExecute: (command: CommandItem) => void
+  isOpen: boolean
+}
+
+export interface UseCommandPaletteReturn {
+  query: string
+  setQuery: (q: string) => void
+  filteredGroups: CommandGroup[]
+  selectedIndex: number
+  onKeyDown: (e: React.KeyboardEvent) => void
+}
+
+export function useCommandPaletteSearch(opts: UseCommandPaletteOptions): UseCommandPaletteReturn {
+  const { commands, onExecute, isOpen } = opts
+  const [query, setQuery] = useState('')
+  const [selectedIndex, setSelectedIndex] = useState(0)
+
+  // Filter commands by query and group them
+  const filteredGroups = useMemo(() => {
+    const lowerQuery = query.toLowerCase()
+    const filtered = query
+      ? commands.filter(
+          (cmd) =>
+            cmd.label.toLowerCase().includes(lowerQuery) ||
+            (cmd.detail && cmd.detail.toLowerCase().includes(lowerQuery))
+        )
+      : commands
+
+    // Group by group label, preserving insertion order
+    const groupMap = new Map<string, CommandItem[]>()
+    for (const cmd of filtered) {
+      const existing = groupMap.get(cmd.group)
+      if (existing) {
+        existing.push(cmd)
+      } else {
+        groupMap.set(cmd.group, [cmd])
+      }
+    }
+
+    const groups: CommandGroup[] = []
+    for (const [label, items] of groupMap) {
+      groups.push({ label, items })
+    }
+    return groups
+  }, [commands, query])
+
+  // Flat list for keyboard nav
+  const flatItems = useMemo(
+    () => filteredGroups.flatMap((g) => g.items),
+    [filteredGroups]
+  )
+
+  // Reset state when palette opens/closes
+  useEffect(() => {
+    if (isOpen) {
+      setQuery('')
+      setSelectedIndex(0)
+    }
+  }, [isOpen])
+
+  // Reset selection when filtered results change
+  useEffect(() => {
+    setSelectedIndex(0)
+  }, [filteredGroups])
+
+  const onKeyDown = useCallback(
+    (e: React.KeyboardEvent) => {
+      if (e.key === 'ArrowDown') {
+        e.preventDefault()
+        setSelectedIndex((prev) => Math.min(prev + 1, flatItems.length - 1))
+      } else if (e.key === 'ArrowUp') {
+        e.preventDefault()
+        setSelectedIndex((prev) => Math.max(prev - 1, 0))
+      } else if (e.key === 'Enter' && flatItems[selectedIndex]) {
+        e.preventDefault()
+        onExecute(flatItems[selectedIndex])
+      }
+    },
+    [flatItems, selectedIndex, onExecute]
+  )
+
+  return {
+    query,
+    setQuery,
+    filteredGroups,
+    selectedIndex,
+    onKeyDown,
+  }
+}