Command

검색 가능한 명령 팔레트 메뉴 컴포넌트

개요

iCignal Command는 Foundation Command(cmdk 기반)를 래핑하여 메뉴 항목을 items 배열 데이터로 선언적으로 구성할 수 있도록 한 컴포넌트입니다. 검색 입력, 그룹, 구분선, 단축키 표시를 지원하며, dialog 옵션으로 모달 명령 팔레트로도 사용할 수 있습니다.

주요 특징

• ✅ 데이터 기반 구성: items 배열만으로 메뉴 렌더링
• ✅ 검색 필터링: searchable 옵션으로 입력 기반 실시간 필터링
• ✅ 그룹/구분선: group 타입으로 섹션 구분, separator로 시각적 분리
• ✅ 아이콘/단축키: 항목별 icon, shortcut 표시 지원
• ✅ 다이얼로그 모드: dialog 옵션으로 모달 명령 팔레트 전환
• ✅ 선택 콜백: onSelect로 선택된 항목 객체 전달

사용 예시

기본 (검색 가능)

searchable 옵션으로 검색 입력을 표시하고, 입력에 따라 항목이 필터링됩니다.

<Command
  searchable
  placeholder="명령어 검색..."
  className="w-full max-w-sm rounded-lg border"
  items={[
    {
      type: "group",
      label: "계정",
      items: [
        { label: "프로필", value: "profile", icon: <User />, shortcut: "⌘P" },
        { label: "설정", value: "settings", icon: <Settings />, shortcut: "⌘S" },
      ],
    },
    { type: "separator" },
    {
      type: "group",
      label: "일반",
      items: [
        { label: "캘린더", value: "calendar", icon: <Calendar /> },
        { label: "메일", value: "mail", icon: <Mail /> },
      ],
    },
  ]}
/>

비활성 및 위험 항목

disabled로 비활성 항목을, variant=“destructive”로 위험 항목을 표시합니다.

<Command
  className="w-full max-w-sm rounded-lg border"
  items={[
    { label: "새로 만들기", value: "new" },
    { label: "복제", value: "duplicate", disabled: true },
    { type: "separator" },
    { label: "삭제", value: "delete", icon: <Trash2 />, variant: "destructive", shortcut: "⌘⌫" },
  ]}
/>

검색 결과 없음

empty prop으로 검색 결과가 없을 때 표시할 내용을 변경할 수 있습니다.

<Command
  searchable
  empty="일치하는 명령어가 없습니다."
  items={[{ label: "프로필", value: "profile" }]}
/>

API Reference

Props

CommandItemProps

Events

기본 사용법

import { Command } from "@vortex/ui-icignal"
 
<Command
  searchable
  items={[
    { label: "프로필", value: "profile", icon: <User />, shortcut: "⌘P" },
    { type: "separator" },
    { label: "삭제", value: "delete", variant: "destructive" },
  ]}
  onSelect={(item) => console.log(item.value)}
/>

다이얼로그 모드

dialog 옵션과 open, onOpenChange를 함께 사용해 모달 명령 팔레트를 만듭니다. 항목 선택 시 onOpenChange(false)가 자동 호출되어 다이얼로그가 닫힙니다.

const [open, setOpen] = useState(false)
 
// ⌘K 단축키로 여는 명령 팔레트 예시
<Command
  dialog
  open={open}
  onOpenChange={setOpen}
  searchable
  items={[
    { label: "프로필", value: "profile" },
    { label: "설정", value: "settings" },
  ]}
  onSelect={(item) => router.push(`/${item.value}`)}
/>

접근성

ARIA 속성

cmdk 기반 Foundation Command가 자동으로 제공합니다:

• 검색 입력과 항목 목록 간 aria-activedescendant 연결
• 키보드 ↑/↓로 항목 탐색, Enter로 선택
• 비활성 항목은 키보드 탐색에서 제외
• dialog 모드에서는 포커스 트랩 및 ESC 닫기 지원

권장 사항

• ✅ 항목에 고유한 value를 지정해 onSelect에서 식별
• ✅ 검색 대상이 되는 label에 명확한 명령어 이름 사용
• ✅ 자주 쓰는 명령에는 shortcut 표시로 키보드 사용성 향상

관련 컴포넌트

• Command (Foundation): Compound 구조의 Foundation 레이어 커맨드
• Dialog (Foundation): 일반적인 모달 다이얼로그
• Combobox: 옵션 검색 선택 입력