@nerdev/skillset 0.2.1

package/skills/ui/ask-cmdk/SKILL.md

@@ -0,0 +1,315 @@
+---
+name: ask-cmdk
+description: Library guide for cmdk: command palette, fuzzy search, keyboard navigation, groups, async loading. Load via ask-command-menu pattern skill.
+---
+
+# Ask Cmdk: Command Palette (⌘K)
+
+**When to use:** Global command palette, contextual command menus, search interfaces.
+
+**Package:** `cmdk`
+
+
+## Installation
+
+```bash
+npm i cmdk
+```
+
+
+## Core Components
+
+```tsx
+import {
+  Command,
+  CommandInput,
+  CommandList,
+  CommandGroup,
+  CommandItem,
+  CommandEmpty,
+  CommandLoading,
+  CommandSeparator,
+  CommandShortcut,
+} from 'cmdk'
+```
+
+
+## Basic Setup
+
+```tsx
+'use client'
+
+import { Command, CommandInput, CommandList, CommandGroup, CommandItem, CommandEmpty } from 'cmdk'
+import { useState } from 'react'
+
+interface CommandItem {
+  id: string
+  label: string
+  description?: string
+  shortcut?: string
+  icon?: React.ReactNode
+  action: () => void
+  keywords?: string[]
+  group?: string
+}
+
+export function CommandPalette({ items, isOpen, onClose }: { items: CommandItem[]; isOpen: boolean; onClose: () => void }) {
+  const [search, setSearch] = useState('')
+
+  // Simple fuzzy filter
+  const filtered = items.filter(item => {
+    if (!search) return true
+    const terms = search.toLowerCase().split(' ')
+    const haystack = `${item.label} ${item.description || ''} ${item.keywords?.join(' ') || ''}`.toLowerCase()
+    return terms.every(term => haystack.includes(term))
+  })
+
+  // Group by group
+  const grouped = filtered.reduce((acc, item) => {
+    const group = item.group || 'Commands'
+    if (!acc[group]) acc[group] = []
+    acc[group].push(item)
+    return acc
+  }, {} as Record<string, CommandItem[]>)
+
+  return (
+    <Command open={isOpen} onOpenChange={onClose}>
+      <CommandInput
+        placeholder="Search commands…"
+        value={search}
+        onValueChange={setSearch}
+        className="w-full px-3 py-2 text-base outline-none"
+        onKeyDown={(e) => { if (e.key === 'Escape') onClose() }}
+      />
+      <CommandList className="max-h-[400px] overflow-auto">
+        {Object.entries(grouped).length === 0 && search ? (
+          <CommandEmpty>No commands found</CommandEmpty>
+        ) : (
+          Object.entries(grouped).map(([groupLabel, commands]) => (
+            <CommandGroup key={groupLabel} heading={groupLabel}>
+              {commands.map((cmd) => (
+                <CommandItem
+                  key={cmd.id}
+                  onSelect={(e) => {
+                    e.preventDefault()
+                    cmd.action()
+                    onClose()
+                  }}
+                  className="flex items-center gap-3 px-3 py-2"
+                >
+                  {cmd.icon && <span className="text-gray-400">{cmd.icon}</span>}
+                  <div className="flex-1 text-left">
+                    <div className="font-medium">{cmd.label}</div>
+                    {cmd.description && <div className="text-sm text-gray-500">{cmd.description}</div>}
+                  </div>
+                  {cmd.shortcut && (
+                    <CommandShortcut>{cmd.shortcut}</CommandShortcut>
+                  )}
+                </CommandItem>
+              ))}
+            </CommandGroup>
+          ))
+        )}
+      </CommandList>
+    </Command>
+  )
+}
+```
+
+
+## Fuzzy Search with Fuse.js (Better Ranking)
+
+```tsx
+import Fuse from 'fuse.js'
+
+const fuse = new Fuse(items, {
+  keys: ['label', 'description', 'keywords'],
+  threshold: 0.3,
+  includeScore: true,
+  includeMatches: true,
+})
+
+const results = fuse.search(search)
+```
+
+
+## Highlight Matches
+
+```tsx
+function Highlight({ text, matches }: { text: string; matches?: Fuse.FuseResultMatch[] }) {
+  if (!matches || matches.length === 0) return text
+
+  const indices = matches.flatMap(m => m.indices || [])
+  indices.sort((a, b) => a[0] - b[0])
+
+  let result = []
+  let lastIndex = 0
+
+  for (const [start, end] of indices) {
+    if (start > lastIndex) result.push(text.slice(lastIndex, start))
+    result.push(<mark key={start} className="bg-yellow-200 dark:bg-yellow-800">{text.slice(start, end + 1)}</mark>)
+    lastIndex = end + 1
+  }
+
+  if (lastIndex < text.length) result.push(text.slice(lastIndex))
+  return result
+}
+```
+
+
+## Async Loading (Debounced)
+
+```tsx
+import { useState, useEffect, useCallback } from 'react'
+
+function AsyncCommandGroup({ loader, label }: { loader: (query: string) => Promise<CommandItem[]>; label: string }) {
+  const [items, setItems] = useState<CommandItem[]>([])
+  const [isLoading, setIsLoading] = useState(false)
+
+  const load = useCallback(
+    debounce(async (query: string) => {
+      setIsLoading(true)
+      try {
+        const data = await loader(query)
+        setItems(data)
+      } finally {
+        setIsLoading(false)
+      }
+    }, 150),
+    [loader]
+  )
+
+  useEffect(() => {
+    if (search) load(search)
+  }, [search, load])
+
+  return (
+    <CommandGroup heading={label}>
+      {isLoading && <CommandLoading>Loading…</CommandLoading>}
+      {items.map(cmd => (
+        <CommandItem key={cmd.id} onSelect={cmd.action}>{cmd.label}</CommandItem>
+      ))}
+    </CommandGroup>
+  )
+}
+
+function debounce(fn: Function, ms: number) {
+  let timeoutId: NodeJS.Timeout
+  return (...args: any[]) => {
+    clearTimeout(timeoutId)
+    timeoutId = setTimeout(() => fn(...args), ms)
+  }
+}
+```
+
+
+## Global Keyboard Listener
+
+```tsx
+// hooks/useCommandPalette.ts
+import { useState, useEffect, useCallback } from 'react'
+
+export function useCommandPalette() {
+  const [isOpen, setIsOpen] = useState(false)
+
+  const open = useCallback(() => setIsOpen(true), [])
+  const close = useCallback(() => setIsOpen(false), [])
+  const toggle = useCallback(() => setIsOpen(p => !p), [])
+
+  useEffect(() => {
+    function handleKeyDown(e: KeyboardEvent) {
+      // ⌘K / Ctrl+K
+      if ((e.metaKey || e.ctrlKey) && e.key === 'k') {
+        e.preventDefault()
+        toggle()
+      }
+      if (e.key === 'Escape') close()
+    }
+    window.addEventListener('keydown', handleKeyDown)
+    return () => window.removeEventListener('keydown', handleKeyDown)
+  }, [toggle, close])
+
+  return { isOpen, open, close, toggle }
+}
+```
+
+
+## Contextual Commands
+
+```tsx
+// In a page component
+const contextualItems: CommandItem[] = [
+  { id: 'edit', label: 'Edit', shortcut: '⌘E', action: () => openEdit(), group: 'Project' },
+  { id: 'duplicate', label: 'Duplicate', action: () => duplicate(), group: 'Project' },
+  { id: 'archive', label: 'Archive', action: () => archive(), group: 'Project' },
+]
+
+// Merge with global
+const allItems = [...globalCommands, ...contextualItems]
+```
+
+
+## Recent/History (MRU)
+
+```tsx
+// lib/commandHistory.ts
+const HISTORY_KEY = 'command-history'
+const MAX_HISTORY = 10
+
+export function getRecentCommands(): string[] {
+  if (typeof window === 'undefined') return []
+  return JSON.parse(localStorage.getItem(HISTORY_KEY) || '[]')
+}
+
+export function addToHistory(commandId: string) {
+  const history = getRecentCommands()
+  const filtered = history.filter(id => id !== commandId)
+  const updated = [commandId, ...filtered].slice(0, MAX_HISTORY)
+  localStorage.setItem(HISTORY_KEY, JSON.stringify(updated))
+}
+
+// In CommandPalette
+const recent = getRecentCommands()
+const recentItems = items.filter(i => recent.includes(i.id))
+
+{recentItems.length > 0 && (
+  <CommandGroup heading="Recent">
+    {recentItems.map(cmd => (
+      <CommandItem key={cmd.id} onSelect={() => { cmd.action(); addToHistory(cmd.id); onClose() }}>
+        {cmd.label}
+      </CommandItem>
+    ))}
+  </CommandGroup>
+)}
+```
+
+
+## Styling (Tailwind + Headless)
+
+```tsx
+// cmdk injects minimal styles: customize via className
+<Command className="fixed top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2 w-[600px] max-w-[90vw] rounded-xl border bg-white shadow-xl dark:bg-gray-900">
+  <CommandInput className="w-full px-4 py-3 text-lg border-b outline-none placeholder:text-gray-400" />
+  <CommandList className="max-h-[400px] overflow-auto p-1">
+    <CommandGroup heading="Group" className="px-2 py-1 text-xs font-semibold text-gray-500 uppercase" />
+    <CommandItem className="flex items-center gap-3 px-3 py-2 rounded-lg hover:bg-gray-100 dark:hover:bg-gray-800 [&[data-selected]]:bg-gray-100 dark:[&[data-selected]]:bg-gray-800" />
+  </CommandList>
+</Command>
+```
+
+
+## Common Issues
+
+| Issue | Fix |
+|-------|-----|
+| Not opening on ⌘K | Check global listener, ensure no conflicting handlers |
+| Items not filtering | Verify fuzzy search logic, check `keywords` field |
+| Focus lost on close | `Command` handles this: ensure `onOpenChange` closes properly |
+| Async loading flashes | Show `CommandLoading` skeleton, debounce |
+| Mobile keyboard issues | `CommandInput` is native input: works on mobile |
+
+
+## Related Skills
+
+- `ui/ask-command-menu` - Pattern guide for command palettes
+- `ui/ui-engineering` - Master orchestrator

package/skills/ui/ask-command-menu/SKILL.md

@@ -0,0 +1,262 @@
+---
+name: ask-command-menu
+description: Pattern guide for command palettes (⌘K): fuzzy search, keyboard nav, nested commands, groups, async loading. Load via ui-engineering. Invokes pick-ui-library → recommends cmdk → loads ask-cmdk for implementation.
+---
+
+# Ask Command Menu: Command Palette (⌘K)
+
+**When to use:** Global command palette, contextual menus, search interfaces, quick actions, help menus.
+
+
+## The Pattern
+
+| Feature | Quality Bar |
+|---------|-------------|
+| **Global shortcut** | ⌘K (Mac) / Ctrl+K (Win) opens everywhere |
+| **Fuzzy search** | Matches subsequences, ranks by relevance, highlights matches |
+| **Keyboard nav** | ↑↓ select, Enter execute, ESC close, ⌘+number quick select |
+| **Groups/Sections** | Commands grouped by category, collapsible |
+| **Nested commands** | Sub-menus, breadcrumbs, back navigation |
+| **Async loading** | Debounced search, loading skeletons, abort on new query |
+| **Keyboard hints** | Show shortcuts next to commands |
+| **Recent/history** | MRU at top, persisted |
+| **Contextual** | Different commands per route/context |
+| **Accessibility** | ARIA combobox, live region for results, focus management |
+
+
+## Quality Checklist
+
+- [ ] **cmdk**: Headless, accessible, keyboard-first
+- [ ] **Global listener**: Single ⌘K handler at app root
+- [ ] **Fuzzy matching**: `fuse.js` or cmdk built-in, highlight matches
+- [ ] **Command registry**: Centralized, typed, extensible
+- [ ] **Loading states**: Skeleton for async groups
+- [ ] **Empty state**: "No commands found" + help hint
+- [ ] **Close on execute**: Unless command returns `keepOpen: true`
+- [ ] **Focus restore**: Return focus to trigger on close
+- [ ] **Mobile**: Responsive, touch-friendly (or disable on mobile)
+
+
+## Anti-Patterns
+
+- ❌ Custom input + manual filtering → Reinventing, accessibility gaps
+- ❌ No fuzzy search → Exact match only = frustrating
+- ❌ No keyboard hints → Users don't discover shortcuts
+- ❌ No groups → Flat list = overwhelming
+- ❌ No async support → Blocks UI on search
+- ❌ Doesn't close on execute → Lingers awkwardly
+- ❌ No focus restore → Keyboard trap
+- ❌ No recent/history: Misses power user workflow
+
+
+## Implementation Flow
+
+```
+User needs command palette
+    │
+    ├─► ui-engineering detects "command palette/⌘K/quick actions"
+    │
+    ├─► pick-ui-library → recommends cmdk
+    │
+    ├─► load ask-cmdk (library skill)
+    │
+    └─► implement with cmdk + command registry + fuzzy search
+```
+
+
+## Command Registry (Centralized, Typed)
+
+```tsx
+// lib/commands.ts
+export interface Command {
+  id: string
+  label: string
+  description?: string
+  shortcut?: string
+  icon?: React.ReactNode
+  group?: string
+  action: () => void | Promise<void>
+  keepOpen?: boolean // For nested menus
+  keywords?: string[] // Extra search terms
+}
+
+export interface CommandGroup {
+  id: string
+  label: string
+  commands: Command[]
+  async?: boolean // Load commands on demand
+  loader?: () => Promise<Command[]>
+}
+
+// Registry: single source of truth
+export const commandRegistry: CommandGroup[] = [
+  {
+    id: 'navigation',
+    label: 'Navigation',
+    commands: [
+      { id: 'dashboard', label: 'Dashboard', shortcut: '⌘H', icon: <Home className="h-4 w-4" />, action: () => router.push('/') },
+      { id: 'projects', label: 'Projects', shortcut: '⌘P', icon: <Folder className="h-4 w-4" />, action: () => router.push('/projects') },
+      { id: 'settings', label: 'Settings', shortcut: '⌘,', icon: <Settings className="h-4 w-4" />, action: () => router.push('/settings') },
+    ],
+  },
+  {
+    id: 'actions',
+    label: 'Actions',
+    commands: [
+      { id: 'new-project', label: 'New Project', shortcut: '⌘N', icon: <Plus className="h-4 w-4" />, action: () => openNewProjectDialog() },
+      { id: 'new-task', label: 'New Task', shortcut: '⌘T', icon: <CheckSquare className="h-4 w-4" />, action: () => openNewTaskDialog() },
+    ],
+  },
+  {
+    id: 'help',
+    label: 'Help',
+    commands: [
+      { id: 'shortcuts', label: 'Keyboard Shortcuts', shortcut: '⌘/', icon: <Keyboard className="h-4 w-4" />, action: () => openShortcutsDialog() },
+      { id: 'docs', label: 'Documentation', icon: <BookOpen className="h-4 w-4" />, action: () => window.open('https://docs.example.com') },
+    ],
+  },
+]
+```
+
+
+## Command Palette Component (cmdk)
+
+```tsx
+// components/CommandPalette.tsx
+'use client'
+
+import { Command, CommandInput, CommandList, CommandGroup, CommandItem, CommandEmpty, CommandLoading } from 'cmdk'
+import { useEffect, useState } from 'react'
+import { commandRegistry, CommandGroup as CommandGroupType } from '@/lib/commands'
+import { Fuse } from 'fuse.js'
+
+export function CommandPalette({ isOpen, onClose }) {
+  const [groups, setGroups] = useState<CommandGroupType[]>(commandRegistry)
+
+  // Fuse for fuzzy search
+  const fuse = useMemo(() => new Fuse(
+    groups.flatMap(g => g.commands.map(c => ({ ...c, group: g.label }))),
+    { keys: ['label', 'description', 'keywords'], threshold: 0.3, includeScore: true }
+  ), [groups])
+
+  const filteredGroups = useMemo(() => {
+    if (!search) return groups
+    const results = fuse.search(search)
+    // Group by group label
+    const grouped = new Map<string, Command[]>()
+    results.forEach(r => {
+      const group = r.item.group
+      if (!grouped.has(group)) grouped.set(group, [])
+      grouped.get(group)!.push(r.item)
+    })
+    return Array.from(grouped.entries()).map(([label, commands]) => ({ id: label.toLowerCase(), label, commands }))
+  }, [search, groups, fuse])
+
+  return (
+    <Command open={isOpen} onOpenChange={onClose}>
+      <CommandInput
+        placeholder="Search commands…"
+        className="w-full px-3 py-2 text-base bg-transparent outline-none"
+        onKeyDown={(e) => {
+          if (e.key === 'Escape') onClose()
+        }}
+      />
+      <CommandList className="max-h-[400px] overflow-auto">
+        {filteredGroups.length === 0 && search ? (
+          <CommandEmpty>No commands found</CommandEmpty>
+        ) : (
+          filteredGroups.map((group) => (
+            <CommandGroup key={group.id} heading={group.label}>
+              {group.commands.map((cmd) => (
+                <CommandItem
+                  key={cmd.id}
+                  onSelect={(e) => {
+                    e.preventDefault()
+                    cmd.action()
+                    if (!cmd.keepOpen) onClose()
+                  }}
+                  className="flex items-center gap-3 px-3 py-2"
+                >
+                  {cmd.icon && <span className="text-gray-400">{cmd.icon}</span>}
+                  <div className="flex-1 text-left">
+                    <div className="font-medium">{highlightMatch(cmd.label, search)}</div>
+                    {cmd.description && <div className="text-sm text-gray-500">{cmd.description}</div>}
+                  </div>
+                  {cmd.shortcut && <kbd className="px-1.5 py-0.5 text-xs bg-gray-100 dark:bg-gray-800 rounded">{cmd.shortcut}</kbd>}
+                </CommandItem>
+              ))}
+            </CommandGroup>
+          ))
+        )}
+      </CommandList>
+    </Command>
+  )
+}
+
+function highlightMatch(text: string, query: string) {
+  if (!query) return text
+  const parts = text.split(new RegExp(`(${query})`, 'i'))
+  return parts.map((part, i) => i % 2 === 1 ? <mark key={i} className="bg-yellow-200 dark:bg-yellow-800">{part}</mark> : part)
+}
+```
+
+
+## Global Hook (App Root)
+
+```tsx
+// hooks/useCommandPalette.ts
+'use client'
+
+import { useState, useEffect, useCallback } from 'react'
+
+export function useCommandPalette() {
+  const [isOpen, setIsOpen] = useState(false)
+
+  const open = useCallback(() => setIsOpen(true), [])
+  const close = useCallback(() => setIsOpen(false), [])
+  const toggle = useCallback(() => setIsOpen(p => !p), [])
+
+  useEffect(() => {
+    function handleKeyDown(e: KeyboardEvent) {
+      if ((e.metaKey || e.ctrlKey) && e.key === 'k') {
+        e.preventDefault()
+        toggle()
+      }
+      if (e.key === 'Escape') close()
+    }
+    window.addEventListener('keydown', handleKeyDown)
+    return () => window.removeEventListener('keydown', handleKeyDown)
+  }, [toggle, close])
+
+  return { isOpen, open, close, toggle }
+}
+```
+
+
+## Contextual Commands (Per Route)
+
+```tsx
+// In a project page
+const projectCommands: CommandGroup = {
+  id: 'project',
+  label: 'Project',
+  commands: [
+    { id: 'edit', label: 'Edit Project', shortcut: '⌘E', action: () => openEditDialog(project) },
+    { id: 'duplicate', label: 'Duplicate', action: () => duplicateProject(project.id) },
+    { id: 'archive', label: 'Archive', action: () => archiveProject(project.id) },
+    { id: 'delete', label: 'Delete', action: () => deleteProject(project.id) },
+  ],
+}
+
+// Merge with global registry
+const allGroups = [...commandRegistry, projectCommands]
+```
+
+
+## When to Escalate
+
+| Need | Escalate To |
+|------|-------------|
+| Nested sub-menus | `ask-command-menu` recursive groups |
+| Async search (API) | `ask-command-menu` + `fuse.js` debounced |
+| Command history/MRU | localStorage + `ask-command-menu` |