명령 검색 | Surflane

사용 가능Product composition

미리보기

로컬 미리보기입니다. 실제 계정, 환경, 실행 데이터에는 영향을 주지 않습니다.

카탈로그 페이지를 검색하거나 외관을 변경하세요. 이 페이지가 마운트된 동안 Ctrl+K 또는 ⌘K로 검색이 열립니다. 텍스트 필드는 자체 단축키를 유지합니다.

실행된 명령이 없습니다.

사용법

명령 검색으로 빠르게 이동하세요. Dialog, 인라인 Combobox, ScrollArea로 구성합니다.
검색은 이름, 설명, 카테고리의 공백으로 구분된 단어를 한글 또는 라틴 텍스트에서 매칭합니다.
계획된 항목은 Planned 라벨을 가지며 선택할 수 없습니다.
예시는 카탈로그 레지스트리에서 대상을 가져오고 로컬 테마 명령을 별도 액션으로 추가합니다.
페이지 단축키는 예시가 마운트된 동안에만 동작합니다.

명령 검색을 유일한 이동 수단으로 만들지 마세요. 일반 내비게이션을 함께 유지하세요.
입력 필드, IME 조합 중, 다른 모달에서 단축키를 가로채지 마세요. 그 키가 포커스된 필드나 모달에 도달하게 하세요.
검색 선택만으로 파괴적 액션을 실행하지 마세요. 확인 플로우를 거치게 하세요.
프리미티브가 실제 권한, 검색 서버, 대용량 데이터 제한, 개인 데이터와 최근 검색 저장을 처리하길 기대하지 마세요. 이들은 제품이 소유합니다.
예시는 로컬 레지스트리만 검색하며 계정이나 서비스를 호출하지 않습니다.

구성

Trigger / scoped shortcut → Dialog(Title, Description) → Combobox.Input → result count + ScrollArea(Empty, List, disabled/planned Item) → route or local command

키보드와 접근성

Ctrl+K, ⌘K 또는 버튼으로 검색을 열고 입력에 포커스를 둡니다. Tab은 Dialog 안에 머뭅니다.
위 화살표 키, 아래 화살표 키, Enter는 Base UI Combobox의 활성 항목 규칙을 따릅니다. 계획된 항목은 건너뜁니다.
페이지를 선택하면 라우터가 대상 heading과 스크롤을 관리합니다. 테마 액션은 현재 페이지에서 실행되고 열기 버튼으로 포커스를 돌려줍니다.
Escape 또는 닫기로 열기 버튼에 포커스를 돌려줍니다.

각 컨트롤에 목적을 설명하는 이름을 지정하세요. 오류 메시지를 해당 컨트롤에 연결하고, 상태를 색만으로 알리지 마세요. 자동 검사는 수동 키보드 및 보조 기술 테스트를 대신하지 않습니다.

예시 코드

공유 컴포넌트는 디자인 토큰에서 스타일을 가져옵니다. 각 예시는 자체 구성과 접근성 속성을 설정합니다. 호출하는 화면이 콜백, ref, 제품 데이터를 정의합니다.

import { Combobox, Dialog, ScrollArea } from '@surflane/ui'

<Combobox.Root
  inline
  open={open}
  onOpenChange={setOpen}
  items={commands}
  filter={matches}
  value={null}
  autoHighlight
  onValueChange={executeAllowedCommand}
>
  <Dialog.Root open={open} onOpenChange={setOpen}>
    <Dialog.Trigger>Search documentation</Dialog.Trigger>
    <Dialog.Content initialFocus={inputRef}>
      <Dialog.Title>Command search</Dialog.Title>
      <Dialog.Description>Choose a destination or command.</Dialog.Description>
      <Combobox.Input ref={inputRef} aria-label='Search pages and actions' />
      <ScrollArea orientation='vertical' label='Command results'>
        <Combobox.Empty>No results.</Combobox.Empty>
        <Combobox.List>
          {(command) => (
            <Combobox.Item value={command} disabled={!command.allowed}>
              {command.label}
            </Combobox.Item>
          )}
        </Combobox.List>
      </ScrollArea>
    </Dialog.Content>
  </Dialog.Root>
</Combobox.Root>

// Share open state; preserve destination focus after modal dismissal.
// Guard repeated execution and unregister route-scoped keyboard handlers.
// Permission checks and destructive-action confirmation belong to the product.

주요 API

명령 검색 — 공통 래퍼 props
Prop	설명	기본값
`Source`	카탈로그 레지스트리 대상 + 로컬 테마 액션	caller-owned
`Matching`	NFKC, 대소문자 구분 없이 이름/요약/카테고리의 공백 구분 용어 전체 매칭	local
`Unavailable result`	Planned 라벨, 비활성 옵션, 액션 없음	registry stage
`Shortcut`	Ctrl+K / Meta+K; 입력, IME, 반복, 다른 모달 무시	mounted route only
`Selection`	열 때마다 한 번 실행; 라우팅 전에 닫기; 다시 열면 쿼리 초기화	controlled
`Focus`	취소/액션 → 트리거; 내비게이션 → 대상 heading	Dialog + router

표는 공통 래퍼의 주요 props를 나열합니다. 전체 타입은 패키지 타입 선언을 참조하세요.

미리보기

사용법

구성

키보드와 접근성

예시 코드

주요 API

관련 토큰