@startsimpli/ui 0.4.6 → 0.4.8

package/src/components/command-palette/CommandPalette.tsx

@@ -0,0 +1,327 @@
+'use client'
+
+import { useState, useEffect, useRef, useMemo, useCallback, Fragment } from 'react'
+import { Search } from 'lucide-react'
+import { useCommandPalette } from './command-palette-context'
+import { useCommandPaletteSearch } from './useCommandPaletteSearch'
+import { CommandGroup } from './CommandGroup'
+import { CommandResultItem } from './CommandResultItem'
+import type { CommandItem } from './useCommandPaletteSearch'
+
+export interface SearchResult {
+  id: string
+  type: string
+  name: string
+  detail: string
+  path: string
+}
+
+export interface QuickAction {
+  id: string
+  icon: React.ElementType
+  name: string
+  shortcut?: string
+  action: () => void
+}
+
+export interface NavigationItem {
+  id: string
+  icon: React.ElementType
+  name: string
+  path: string
+}
+
+export interface CommandPaletteProps {
+  searchFn?: (query: string) => Promise<SearchResult[]>
+  quickActions?: QuickAction[]
+  navigationItems?: NavigationItem[]
+  recentItems?: SearchResult[]
+  typeIcons?: Record<string, React.ElementType>
+  typeColors?: Record<string, string>
+  placeholder?: string
+  onNavigate: (path: string) => void
+}
+
+/**
+ * Convert the heterogeneous props into a unified CommandItem[] for the hook.
+ * Async search results are injected separately since they arrive after debounce.
+ */
+function buildCommands(
+  results: SearchResult[],
+  quickActions: QuickAction[],
+  navigationItems: NavigationItem[],
+  recentItems: SearchResult[],
+  hasQuery: boolean,
+  typeIcons: Record<string, React.ElementType>,
+  typeColors: Record<string, string>,
+): CommandItem[] {
+  const commands: CommandItem[] = []
+
+  // Search results (only when query is active - injected externally)
+  for (const r of results) {
+    commands.push({
+      id: r.id,
+      icon: typeIcons[r.type],
+      label: r.name,
+      detail: r.detail,
+      group: '__results__',
+      onSelect: r.path,
+      colorClass: typeColors[r.type] || 'bg-gray-100 text-gray-600',
+    })
+  }
+
+  // Quick actions (always shown)
+  for (const a of quickActions) {
+    commands.push({
+      id: a.id,
+      icon: a.icon,
+      label: a.name,
+      shortcut: a.shortcut,
+      group: 'Quick Actions',
+      onSelect: () => a.action(),
+      colorClass: 'bg-gray-100 text-gray-600',
+    })
+  }
+
+  // Recent items (only when no query)
+  if (!hasQuery) {
+    for (const r of recentItems.slice(0, 5)) {
+      commands.push({
+        id: r.id,
+        icon: typeIcons[r.type],
+        label: r.name,
+        detail: r.detail,
+        group: 'Recent',
+        onSelect: r.path,
+        colorClass: 'bg-gray-100 text-gray-600',
+      })
+    }
+  }
+
+  // Navigation items (only included when query is active - filtered by hook)
+  if (hasQuery) {
+    for (const n of navigationItems) {
+      commands.push({
+        id: n.id,
+        icon: n.icon,
+        label: n.name,
+        group: 'Go to',
+        onSelect: n.path,
+        colorClass: 'bg-gray-100 text-gray-600',
+      })
+    }
+  }
+
+  return commands
+}
+
+export function CommandPalette({
+  searchFn,
+  quickActions = [],
+  navigationItems = [],
+  recentItems = [],
+  typeIcons = {},
+  typeColors = {},
+  placeholder = 'Search or type a command...',
+  onNavigate,
+}: CommandPaletteProps) {
+  const { isOpen, close } = useCommandPalette()
+  const inputRef = useRef<HTMLInputElement>(null)
+  const [asyncResults, setAsyncResults] = useState<SearchResult[]>([])
+  const [isLoading, setIsLoading] = useState(false)
+  // Track query locally so we can build commands with the right hasQuery flag
+  const [localQuery, setLocalQuery] = useState('')
+
+  const commands = useMemo(
+    () =>
+      buildCommands(
+        asyncResults,
+        quickActions,
+        navigationItems,
+        recentItems,
+        !!localQuery,
+        typeIcons,
+        typeColors,
+      ),
+    [asyncResults, quickActions, navigationItems, recentItems, localQuery, typeIcons, typeColors]
+  )
+
+  const handleExecute = useCallback(
+    (command: CommandItem) => {
+      if (typeof command.onSelect === 'string') {
+        onNavigate(command.onSelect)
+      } else {
+        command.onSelect()
+      }
+      close()
+    },
+    [onNavigate, close]
+  )
+
+  const {
+    query,
+    setQuery,
+    filteredGroups,
+    selectedIndex,
+    onKeyDown,
+  } = useCommandPaletteSearch({
+    commands,
+    onExecute: handleExecute,
+    isOpen,
+  })
+
+  // Sync local query with hook query
+  useEffect(() => {
+    setLocalQuery(query)
+  }, [query])
+
+  // Focus input when opened
+  useEffect(() => {
+    if (isOpen) {
+      setAsyncResults([])
+      setLocalQuery('')
+      setTimeout(() => inputRef.current?.focus(), 0)
+    }
+  }, [isOpen])
+
+  // Search debounce for async results
+  useEffect(() => {
+    if (!query.trim() || !searchFn) {
+      setAsyncResults([])
+      return
+    }
+
+    const timer = setTimeout(async () => {
+      setIsLoading(true)
+      try {
+        const data = await searchFn(query)
+        setAsyncResults(data)
+      } catch (error) {
+        console.error('Search error:', error)
+        setAsyncResults([])
+      } finally {
+        setIsLoading(false)
+      }
+    }, 200)
+
+    return () => clearTimeout(timer)
+  }, [query, searchFn])
+
+  if (!isOpen) return null
+
+  // Compute flat index offset for each group to match selectedIndex
+  let flatIndex = 0
+
+  return (
+    <div
+      className="fixed inset-0 z-50 flex items-start justify-center pt-20"
+      onClick={close}
+    >
+      {/* Backdrop */}
+      <div className="absolute inset-0 bg-black/50 backdrop-blur-sm pointer-events-none" />
+
+      {/* Palette */}
+      <div
+        role="dialog"
+        aria-modal="true"
+        aria-label="Command palette"
+        className="relative w-full max-w-xl bg-white rounded-xl shadow-2xl border border-gray-200 overflow-hidden"
+        onClick={(e) => e.stopPropagation()}
+      >
+        {/* Search input */}
+        <div className="flex items-center gap-3 px-4 py-3 border-b border-gray-200">
+          <Search className="w-5 h-5 text-gray-400" />
+          <input
+            ref={inputRef}
+            type="text"
+            value={query}
+            onChange={(e) => {
+              setQuery(e.target.value)
+              setLocalQuery(e.target.value)
+            }}
+            onKeyDown={onKeyDown}
+            placeholder={placeholder}
+            className="flex-1 outline-none text-lg bg-transparent"
+          />
+          <kbd className="px-2 py-1 bg-gray-100 text-gray-500 text-xs rounded">ESC</kbd>
+        </div>
+
+        {/* Results */}
+        <div role="listbox" aria-label="Search results" className="max-h-96 overflow-y-auto">
+          {/* Search results group header with query text */}
+          {query && asyncResults.length > 0 && (
+            <div className="px-3 py-2">
+              <p className="text-xs font-medium text-gray-500 uppercase tracking-wider">
+                Results for &quot;{query}&quot;
+              </p>
+            </div>
+          )}
+
+          {/* Loading state */}
+          {isLoading && (
+            <div className="px-4 py-3 text-gray-500 text-sm">
+              Searching...
+            </div>
+          )}
+
+          {/* No results */}
+          {query && !isLoading && asyncResults.length === 0 && (
+            <div className="px-4 py-3 text-gray-500 text-sm">
+              No results found for &quot;{query}&quot;
+            </div>
+          )}
+
+          {filteredGroups.map((group, gi) => {
+            // Skip the __results__ group label -- we render a custom header above
+            const isResultsGroup = group.label === '__results__'
+            const showBorder = !isResultsGroup && gi > 0
+
+            const groupStartIndex = flatIndex
+
+            const renderedItems = group.items.map((item, i) => {
+              const itemIndex = groupStartIndex + i
+              const showArrow = typeof item.onSelect === 'string'
+
+              return (
+                <CommandResultItem
+                  key={item.id}
+                  icon={item.icon}
+                  label={item.label}
+                  detail={item.detail}
+                  shortcut={item.shortcut}
+                  selected={selectedIndex === itemIndex}
+                  colorClass={item.colorClass}
+                  showArrow={showArrow}
+                  onClick={() => handleExecute(item)}
+                />
+              )
+            })
+
+            flatIndex += group.items.length
+
+            if (isResultsGroup) {
+              // Results rendered with custom header above
+              return <Fragment key={group.label}>{renderedItems}</Fragment>
+            }
+
+            return (
+              <CommandGroup key={group.label} label={group.label} showBorder={showBorder}>
+                {renderedItems}
+              </CommandGroup>
+            )
+          })}
+        </div>
+
+        {/* Footer */}
+        <div className="flex items-center justify-between px-4 py-2 bg-gray-50 border-t border-gray-200 text-xs text-gray-500">
+          <div className="flex items-center gap-4">
+            <span><kbd className="px-1.5 py-0.5 bg-white border rounded">&uarr;&darr;</kbd> Navigate</span>
+            <span><kbd className="px-1.5 py-0.5 bg-white border rounded">&crarr;</kbd> Select</span>
+            <span><kbd className="px-1.5 py-0.5 bg-white border rounded">ESC</kbd> Close</span>
+          </div>
+          <span>Press <kbd className="px-1.5 py-0.5 bg-white border rounded">&#8984;K</kbd> anywhere</span>
+        </div>
+      </div>
+    </div>
+  )
+}

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

@@ -0,0 +1,59 @@
+'use client'
+
+import React from 'react'
+import { Search, ArrowRight } from 'lucide-react'
+
+export interface CommandResultItemProps {
+  icon?: React.ElementType
+  label: string
+  detail?: string
+  shortcut?: string
+  selected: boolean
+  /** Color class for icon container, e.g. 'bg-blue-100 text-blue-600' */
+  colorClass?: string
+  /** Whether to show a trailing arrow (for navigation items) */
+  showArrow?: boolean
+  onClick: () => void
+}
+
+export function CommandResultItem({
+  icon,
+  label,
+  detail,
+  shortcut,
+  selected,
+  colorClass = 'bg-gray-100 text-gray-600',
+  showArrow = false,
+  onClick,
+}: CommandResultItemProps) {
+  const Icon = icon || Search
+
+  return (
+    <div
+      role="option"
+      aria-selected={selected}
+      className={`flex items-center gap-3 px-4 py-3 cursor-pointer ${
+        selected ? 'bg-blue-50' : 'hover:bg-gray-50'
+      }`}
+      onClick={onClick}
+    >
+      <div
+        className={`w-8 h-8 rounded-full flex items-center justify-center ${colorClass}`}
+      >
+        <Icon className="w-4 h-4" />
+      </div>
+      <div className="flex-1">
+        <p className={detail ? 'font-medium text-gray-900' : 'font-medium text-gray-700'}>
+          {label}
+        </p>
+        {detail && <p className="text-sm text-gray-500">{detail}</p>}
+      </div>
+      {shortcut && (
+        <kbd className="px-2 py-1 bg-gray-100 text-gray-500 text-xs rounded font-mono">
+          {shortcut}
+        </kbd>
+      )}
+      {showArrow && <ArrowRight className="w-4 h-4 text-gray-400" />}
+    </div>
+  )
+}

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

@@ -0,0 +1,81 @@
+import { render, screen } from '@testing-library/react'
+import { CommandGroup } from '../CommandGroup'
+
+describe('CommandGroup', () => {
+  describe('label', () => {
+    it('renders the provided label text', () => {
+      render(<CommandGroup label="Navigation"><div /></CommandGroup>)
+      expect(screen.getByText('Navigation')).toBeInTheDocument()
+    })
+
+    it('renders label in uppercase via CSS class', () => {
+      render(<CommandGroup label="Actions"><div /></CommandGroup>)
+      const label = screen.getByText('Actions')
+      expect(label.className).toMatch(/uppercase/)
+    })
+
+    it('applies text-xs styling to the label', () => {
+      render(<CommandGroup label="Recent"><div /></CommandGroup>)
+      const label = screen.getByText('Recent')
+      expect(label.className).toMatch(/text-xs/)
+    })
+  })
+
+  describe('children', () => {
+    it('renders children inside the fragment', () => {
+      render(
+        <CommandGroup label="Navigation">
+          <div data-testid="child-item">Item A</div>
+        </CommandGroup>
+      )
+      expect(screen.getByTestId('child-item')).toBeInTheDocument()
+    })
+
+    it('renders multiple children', () => {
+      render(
+        <CommandGroup label="Navigation">
+          <div data-testid="item-1">One</div>
+          <div data-testid="item-2">Two</div>
+          <div data-testid="item-3">Three</div>
+        </CommandGroup>
+      )
+      expect(screen.getByTestId('item-1')).toBeInTheDocument()
+      expect(screen.getByTestId('item-2')).toBeInTheDocument()
+      expect(screen.getByTestId('item-3')).toBeInTheDocument()
+    })
+  })
+
+  describe('showBorder prop', () => {
+    it('does not add border class by default', () => {
+      const { container } = render(
+        <CommandGroup label="First"><div /></CommandGroup>
+      )
+      const header = container.querySelector('.px-3.py-2')
+      expect(header?.className).not.toMatch(/border-t/)
+    })
+
+    it('does not add border class when showBorder is false', () => {
+      const { container } = render(
+        <CommandGroup label="First" showBorder={false}><div /></CommandGroup>
+      )
+      const header = container.querySelector('.px-3.py-2')
+      expect(header?.className).not.toMatch(/border-t/)
+    })
+
+    it('adds border-t class when showBorder is true', () => {
+      const { container } = render(
+        <CommandGroup label="Second" showBorder><div /></CommandGroup>
+      )
+      const header = container.querySelector('.px-3.py-2')
+      expect(header?.className).toMatch(/border-t/)
+    })
+
+    it('adds border-gray-100 class when showBorder is true', () => {
+      const { container } = render(
+        <CommandGroup label="Second" showBorder><div /></CommandGroup>
+      )
+      const header = container.querySelector('.px-3.py-2')
+      expect(header?.className).toMatch(/border-gray-100/)
+    })
+  })
+})

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/)
+    })
+  })
+})