SearchField (검색필드)

Va.SearchField — 라벨 + 검색 입력 + 검증까지 감싼 폼 필드

Va.Search가 순수 검색 입력이라면, Va.SearchField는 그 위에 라벨·필수 표시·검증 메시지·설명 텍스트를 얹은 "완성된 검색 폼 필드" 입니다. Va.InputField와 완전히 같은 아키텍처를 따르되, 내부에 Va.Input 대신 Va.Search 를 소유합니다.

• 클래스: Va.SearchField — va_component.js:5436
• short name: searchField
• 상속: Va.Field (InputField와 형제)
• 내부 컴포넌트: Va.Search 인스턴스를 자식으로 소유 (fieldComponent)
• isContainer: true
• 베이스 CSS: va-field

---

1. 기본 사용

{
    tagName: 'searchField',
    label: '검색',
    placeholder: '이름/이메일로 검색',
    onKeydown: 'onSearchKey'
}

라벨 · 필드 · 검증 영역이 자동 세팅되고, 내부 <input type="search">가 브라우저의 지우기(×) 버튼까지 자동 제공합니다.

---

2. Field 계열 아키텍처에서의 위치

이미 InputField 설명 때 봤던 그 구조입니다. PureField(값) + Field(라벨) 두 계층의 조합.

Va.Field
   ├─ Va.InputField      ← 내부에 Va.Input
   ├─ Va.SearchField     ← 내부에 Va.Search    ← 이 문서
   ├─ Va.TextareaField
   ├─ Va.NumberField
   ├─ Va.ComboboxField
   └─ ...

SearchField의 정체: Field 베이스가 라벨/필드/검증 영역을 만들고, 필드 영역에 새로 만든 Va.Search를 꽂아 넣는 Composition (va_component.js:5465):

this.fieldComponent = new Va.Search(optionField);

즉, SearchField = Field 껍데기 + Va.Search 인스턴스 입니다.

---

3. Va.InputField / Va.Search와의 차이

항목Va.SearchVa.SearchFieldVa.InputField

라벨	✕	✓	✓
검증 메시지	✕	✓	✓
설명 텍스트	✕	✓	✓
info 툴팁	✕	✓	✓
input type	search 고정	search 고정	text 기본 (변경 가능)
브라우저 지우기(×) 버튼	✓	✓	✕ (type이 search일 때만)
모바일 "검색" 키보드	✓	✓	조건부
numberComma	✕	✕	✓

한 줄 요약: InputField의 검색 전용 사촌.

---

4. 주요 속성

라벨 관련 (Field 상속 — InputField와 동일)

속성기본값설명

label	—	라벨 텍스트 또는 옵션 객체
labelPosition	'top'	top / bottom / left / right
labelWidth	자동	라벨 영역 폭
labelAlign	—	라벨 정렬
noLabel	false	라벨 영역 숨김
seperator	자동	라벨-필드 사이 구분선
infoButton	—	라벨 옆 info 아이콘
required	false	필수 표시 (별표)

필드 관련 (Search로 위임되는 옵션)

속성설명

value	검색어 값
placeholder	플레이스홀더
readonly / disabled	상태
textAlign	정렬
size	크기
appearance / shape	시각 스타일
masking	마스킹 (거의 안 씀)
valueType	값 타입 힌트
stopPropagation / preventParentFieldEvent	이벤트 제어

⚠️ type 속성은 무시됨 — 내부에서 this.type = 'search'로 고정되어 옵션으로 넘겨도 반영 안 됩니다. type='text'가 필요하면 Va.InputField를 쓰세요.

검증

속성설명

validation	{state, size, message} 객체
validationState	success / warning / error
validationMessage	메시지 텍스트
validationSize	메시지 크기

세부 커스터마이즈

{
    tagName: 'searchField',
    label: '이름 검색',
    search: {              // ← 내부 Search에 직접 전달할 추가 옵션
        maxLength: 50,
        autocomplete: 'off'
    }
}

search 옵션 객체는 va_component.js:5462에서 내부 Va.Search 생성 시 spread됩니다. (InputField에서는 input 키를 쓰지만 여기서는 search)

---

5. 이벤트 (Field 상속 — InputField와 동일)

이벤트시그니처발생 시점

change	(component, element, evt)	값 변경 확정. 발생 시 검증 자동 리셋
focus / blur	(component, element, evt)	blur는 200ms debounce
click	(component, element, evt)	필드 클릭
keydown	(component, element, keyCode, evt)	검증 자동 리셋
keyup	(component, element, evt)	Enter 감지 등에 자주 씀
keypress	(component, element, evt)	—
contextmenu	(component, element, evt)	우클릭
mousedown	(component, element, evt)	—

자주 쓰는 패턴: Enter로 검색 실행

{
    tagName: 'searchField',
    label: '검색',
    onKeydown: 'onSearchKey'
}

onSearchKey(component, element, keyCode, evt) {
    if (keyCode === 13) {   // Enter
        this.doSearch(component.getValue());
    }
}

브라우저 × 버튼으로 지웠을 때

<input type="search">의 지우기 버튼을 누르면 표준 change 이벤트가 발생 → 빈 문자열로. 별도 이벤트 없음.

---

6. 메서드 (Field 상속)

InputField와 완전히 동일한 세트:

값

메서드설명

getValue()	내부 Search의 getValue() 위임
setValue(value)	값 세팅 + 검증 자동 리셋

상태

메서드설명

setDisabled(bool) / getDisabled()	비활성화
setReadOnly(bool) / setReadonly(bool)	읽기 전용
setLabel(label)	라벨 변경
setPlaceholder(text)	플레이스홀더 변경
setSize(size)	크기 변경

검증

메서드설명

setValidation(state, message)	검증 표시 (error 클래스 + aria 자동 세팅)
clearValidation()	검증 해제

포커스

메서드설명

focus() / blur()

내부 Search에 위임

---

7. 내부 구조

<div elname="element" class="va-field va-input [vertical|horizontal] [disabled]" field="true">
  <div elname="inner" class="field-inner">
    <div elname="labelDiv" class="label-div">
      <label cpname="label">검색 <span class="required">*</span></label>
    </div>
    <div elname="comment" class="field-comment"></div>
    <div elname="fieldDiv" class="field-div">
      <div cpname="field" class="va-input">              ← 내부 Va.Search
        <div class="field-wrapper">
          <input type="search" ...>                      ← 실제 검색 input
          <div class="focus-line"></div>
        </div>
      </div>
    </div>
  </div>
  <div elname="validationDiv" style="display:none">
    <div class="va-validation">에러 메시지</div>
  </div>
</div>

InputField와 구조는 완전히 동일. 딱 한 곳, innermost <input>의 type이 search 라는 것만 다릅니다.

---

8. Va.Search vs Va.SearchField vs Va.SearchPanel

세 컴포넌트 이름이 비슷해서 혼동 잦으니 다시 정리:

컴포넌트역할언제

Va.Search	순수 검색 입력 (라벨 없음)	헤더/툴바/사이드바 인라인
Va.SearchField	Search + 라벨 + 검증	폼 안 검색 필드
Va.SearchPanel	검색 조건들을 담는 패널 컨테이너	검색 화면 상단 조건 영역 전체

---

9. 언제 쓰나

SearchField가 맞을 때

• 폼 안에 라벨 붙은 검색 입력이 필요할 때
• 여러 검색 조건 중 하나의 검색어 필드
• 검증 메시지("검색어를 입력하세요")를 표시해야 할 때
• info 툴팁("2글자 이상 입력하세요") 등 부가 설명이 필요할 때

다른 걸 쓸 때

• 헤더/툴바의 심플 검색창 → Va.Search
• 검색 화면 상단 조건 영역 전체 → Va.SearchPanel 안에 여러 Field 조합
• 옵션 선택 (자동완성 드롭다운) → Va.ComboboxField / Va.FilterboxField
• 일반 텍스트 입력 → Va.InputField

---

10. 알아두면 좋을 주의사항 (InputField와 대부분 동일)

1. 내부에 Va.Search를 새로 생성 — SearchField 하나 만들면 실제로는 컴포넌트 2개(Field + Search)가 생성.
2. type 변경 불가 — search로 고정. text가 필요하면 InputField 사용.
3. numberComma 없음 — Search가 미지원이라 SearchField에서도 안 됨.
4. 값 접근은 getValue()로 — 마스킹 등이 걸려 있으면 반영됨.
5. change/keydown 시 검증 자동 리셋 — 사용자가 검색어를 수정하기 시작하면 이전 에러가 자연스럽게 사라짐.
6. 라벨 옵션 객체 스타일 — label: '검색' 대신 label: {label: '검색', infoButton: {...}}로 세밀 제어.
7. 브라우저 × 버튼 — 크롬/사파리/엣지는 자동, 파이어폭스는 CSS 커스텀 필요. 표시 위치가 브라우저마다 미묘하게 다름.
8. 모바일 키보드 — 확인 버튼이 자동으로 "검색"/"Search"로 표시.
9. 폼 안이면 Enter 자동 submit 위험 — <input type="search">가 폼 안에 있으면 Enter 시 브라우저가 submit 시도. 원치 않으면 onKeydown에서 preventDefault.
10. search 옵션 키 vs input 옵션 키 혼동 주의 — InputField는 input, SearchField는 search, NumberField는 number 등, 각 Field 계열마다 다른 옵션 키를 사용.

---

11. 검색 폼에서 흔한 조합 예시

{
    tagName: 'searchPanel',
    tags: [
        {
            tagName: 'searchField',
            label: '이름',
            placeholder: '이름 검색',
            onKeydown: 'onSearchKey'
        },
        {
            tagName: 'comboboxField',
            label: '부서',
            data: [...]
        },
        {
            tagName: 'datePickerField',
            label: '입사일'
        },
        {
            tagName: 'button',
            text: '조회',
            appearance: 'primary',
            onClick: 'onSearch'
        }
    ]
}

SearchField는 이런 검색 화면의 "검색어 필드" 자리에 정확히 어울립니다.