YepAPI/skills

명령 팔레트

규칙

• cmdk 라이브러리 사용 — 구성 가능하고, 접근성이 뛰어나며, 빠른 퍼지 검색이 내장되어 있습니다.
• 트리거: Cmd+K (Mac) / Ctrl+K (Windows/Linux) — 전역 키보드 리스너 등록
• 액션 그룹화: 내비게이션(페이지), 명령어(액션), 최근(최근 사용) — 그룹 제목 표시
• 키보드 탐색: 화살표 키로 이동, Enter로 선택, Escape로 닫기 — 모두 cmdk가 처리
• 퍼지 검색: cmdk가 자동으로 필터링 — 점수 기반 순위로 일치 강조 표시
• 최근 항목: localStorage에 최근 선택한 5~10개 항목 저장 — 입력이 비어 있을 때 상단에 표시
• 동적 액션: 앱의 여러 부분에서 액션 등록 — 컨텍스트 인식(다른 페이지에서 다른 액션 표시)
• 로딩 상태: 비동기 검색 결과(예: API 검색) — 결과 영역에 로딩 표시기 표시

패턴

import { Command } from "cmdk";
import { useEffect, useState } from "react";
import { useRouter } from "next/navigation";

function CommandPalette() {
  const [open, setOpen] = useState(false);
  const router = useRouter();

  // 전역 키보드 단축키
  useEffect(() => {
    const handleKeyDown = (e: KeyboardEvent) => {
      if (e.key === "k" && (e.metaKey || e.ctrlKey)) {
        e.preventDefault();
        setOpen((prev) => !prev);
      }
    };
    document.addEventListener("keydown", handleKeyDown);
    return () => document.removeEventListener("keydown", handleKeyDown);
  }, []);

  return (
    <Command.Dialog open={open} onOpenChange={setOpen} label="명령 팔레트">
      <Command.Input placeholder="명령어 검색 또는 입력..." />
      <Command.List>
        <Command.Empty>결과를 찾을 수 없습니다.</Command.Empty>

        <Command.Group heading="최근">
          {recentItems.map((item) => (
            <Command.Item key={item.id} onSelect={() => { router.push(item.href); setOpen(false); }}>
              {item.label}
            </Command.Item>
          ))}
        </Command.Group>

        <Command.Group heading="내비게이션">
          <Command.Item onSelect={() => { router.push("/dashboard"); setOpen(false); }}>
            대시보드
          </Command.Item>
          <Command.Item onSelect={() => { router.push("/settings"); setOpen(false); }}>
            설정
          </Command.Item>
        </Command.Group>

        <Command.Group heading="명령어">
          <Command.Item onSelect={() => { toggleTheme(); setOpen(false); }}>
            다크 모드 전환
          </Command.Item>
          <Command.Item onSelect={() => { logout(); setOpen(false); }}>
            로그아웃
          </Command.Item>
        </Command.Group>
      </Command.List>
    </Command.Dialog>
  );
}

피해야 할 것

• 커스텀 퍼지 검색 구현 — cmdk가 필터링, 스코어링, 랭킹을 기본 제공합니다.
• Cmd+K에서 e.preventDefault()를 누락 — 누락 시 브라우저의 기본 검색/주소 표시줄이 열립니다.
• Escape 키 처리 누락 — cmdk가 onOpenChange를 통해 처리하지만, 초점이 이전 요소로 돌아가도록 확인하세요.
• 정적 액션만 사용 — 페이지 컨텍스트에서 동적으로 액션을 등록하세요(예: "이 게시물 수정"은 게시물 페이지에서만 표시).
• 빈 상태 없음 — 검색 결과가 없을 때 항상 "결과를 찾을 수 없습니다"를 표시하세요.