@ehfuse/mui-form-controls 3.0.59 → 3.0.61

package/README.md

@@ -23,6 +23,7 @@ MUI 기반 폼 컨트롤과 텍스트 필드 컴포넌트 모음
 | **PhoneTextField**            | 자동 포맷팅, prefix 고정 기능이 있는 전화번호 필드               | [API](./docs/ko/api.md#phonetextfield)            |
 | **SearchTextField**           | 클리어 버튼, 로딩 상태, 디바운스 기능이 있는 검색 필드           | [API](./docs/ko/api.md#searchtextfield)           |
 | **TextArea**                  | 여러 줄 텍스트 입력 필드                                         | [API](./docs/ko/api.md#textarea)                  |
+| **TagsTextField**             | 태그(칩) 목록 입력 · 드래그 정렬 · 선택적 삭제/클릭 콜백         | [API](./docs/ko/api.md#tagstextfield)             |
 | **TextField**                 | MUI TextField 래퍼 (폼 통합)                                     | [API](./docs/ko/api.md#textfield)                 |
 | **TimeTextField**             | 시간 입력 필드 (자동 포맷팅, 시간 범위 제한)                     | [API](./docs/ko/api.md#timetextfield)             |
 | **VerificationCodeTextField** | 인증번호 입력 필드 (숫자/영문/혼합)                              | [API](./docs/ko/api.md#verificationcodetextfield) |
@@ -111,6 +112,7 @@ import {
   Slider,
   DateRange,
   TextArea,
+  TagsTextField,
   useKoreanHolidays,
   useKoreanHolidaysRange,
 } from '@ehfuse/mui-form-controls';
@@ -247,10 +249,47 @@ import { AddressTextField } from '@ehfuse/mui-form-controls/address';
   form={form}
   minRows={4}
 />
+
+// 태그(칩) 입력 — `onDelete`·`onTagClick`은 모두 선택. 지정하지 않으면 X는 즉시 삭제, 칩 클릭 핸들러 없음
+<TagsTextField
+  name="tags"
+  label="태그"
+  form={form}
+  placeholder="입력 후 콤마 또는 스페이스"
+  onDeleteBefore={(e, tag, index) => {
+    /* 선택: false 반환 시 X 삭제 전체 취소(onDelete·내부 삭제 모두 안 함) */
+  }}
+  onDelete={(e, tag, index) => {
+    /* onDelete 지정 시 내부 삭제 없음 → 모달 확인 뒤 form.setFormValue("tags", ...) 등으로 배열 갱신 */
+  }}
+  onTagClick={(e, tag, index) => {
+    /* 예: 상세 모달·라우팅 — 삭제 아이콘(X) 클릭과는 별도 */
+  }}
+/>
 ```
 
 > 선택 입력은 예제/문서 기준으로 `LabelSelect`를 사용합니다.
 
+## TagsTextField (태그 입력)
+
+문자열 배열을 태그 칩으로 표시하고, 콤마·스페이스 등으로 태그를 확정합니다. `draggable`(기본 `true`)일 때 드래그로 순서를 바꿀 수 있습니다.
+
+### 칩 X(삭제 아이콘) 클릭 시 순서
+
+1. **`onDeleteBefore`**가 있으면 먼저 호출됩니다. **`false`를 반환하면 여기서 끝**이며, `onDelete`도 호출되지 않고 내부에서도 태그를 제거하지 않습니다.
+2. 그다음 **`onDelete`가 있으면** 그것만 호출하고 **내부 자동 삭제는 하지 않습니다.** 모달에서 “삭제”를 누른 뒤 등, 반드시 `form.setFormValue` / `onChange`로 `string[]`에서 해당 태그를 빼 주어야 화면이 맞습니다.
+3. **`onDelete`가 없으면** 컴포넌트가 곧바로 그 태그를 배열에서 제거합니다(기본 즉시 삭제).
+
+`onDelete`만 두고 `onDeleteBefore`는 생략할 수 있고, 그 반대로 **`onDeleteBefore`만** 두고 `onDelete`는 생략하면: 가드에서 막지 않았을 때만 **기본 즉시 삭제**가 실행됩니다.
+
+| 콜백 / 동작        | 옵션 여부 | 설명 |
+| ------------------ | --------- | ---- |
+| `onDeleteBefore`   | 선택      | X 클릭 **가장 먼저**. `false`면 이후 단계 전부 취소. |
+| `onDelete`         | 선택      | 가드 통과 후 호출 시 **전적으로 소비자가 배열 갱신**. 없으면 내부 즉시 삭제. |
+| `onTagClick`       | 선택      | 칩 **본문** 클릭 시. 상세 모달·상세 페이지 등. `chipProps.onClick`이 먼저 호출되고, `event.defaultPrevented`이면 `onTagClick`은 호출되지 않음. |
+
+`draggable`이 `true`이면 짧은 클릭과 드래그 시작이 겹칠 수 있습니다(기본 포인터 센서는 약 5px 이동 후 드래그). 자세한 props는 [한국어 API](./docs/ko/api.md#tagstextfield)를 참고하세요.
+
 ## Boolean 필드 표준 패턴
 
 `Switch`를 boolean 입력의 기본 form-binding 컴포넌트로 사용합니다.

package/dist/TagsTextField.d.ts

@@ -0,0 +1,10 @@
+/**
+ * TagsTextField.tsx
+ *
+ * @license MIT
+ * @copyright 2025 김영진 (Kim Young Jin)
+ * @author 김영진 (ehfuse@gmail.com)
+ */
+import React from "react";
+import type { TagsTextFieldProps } from "./types";
+export declare const TagsTextField: React.ForwardRefExoticComponent<Omit<TagsTextFieldProps, "ref"> & React.RefAttributes<HTMLDivElement>>;

package/dist/index.d.ts

@@ -7,6 +7,7 @@
  */
 export { SearchTextField } from "./SearchTextField";
 export { ClearTextField } from "./ClearTextField";
+export { TagsTextField } from "./TagsTextField";
 export { PasswordTextField } from "./PasswordTextField";
 export { TextField } from "./TextField";
 export { TextArea } from "./TextArea";
@@ -39,4 +40,4 @@ export { BizNumTextField } from "./BizNumTextField";
 export { CardNumTextField } from "./CardNumTextField";
 export { useKoreanHolidays, useKoreanHolidaysRange } from "./hooks";
 export { CardIcon, VisaIcon, MastercardIcon, AmexIcon, JcbIcon, DinersIcon, DiscoverIcon, UnionPayIcon, BcIcon, } from "./icons";
-export type { SearchTextFieldProps, ClearTextFieldProps, PasswordTextFieldProps, TextFieldProps, TextAreaProps, CheckboxProps, SwitchProps, RadioGroupProps, RadioOption, DateRangeProps, SliderProps, RatingProps, ToggleButtonProps, ToggleButtonGroupProps, ToggleButtonGroupOption, ButtonGroupProps, StepperProps, AutocompleteProps, AutocompleteOption, SelectProps, SelectOption, LabelSelectProps, LabelSelectOption, AddressTextFieldProps, DaumPostcodeData, PasswordValidationRules, PasswordValidationResult, PhoneTextFieldProps, PhoneFormat, NumberTextFieldProps, JuminTextFieldProps, JuminInfo, VerificationCodeTextFieldProps, VerificationCodeType, EmailTextFieldProps, CustomDomain, DateTextFieldProps, DateFormat, TimeTextFieldProps, TimeFormat, DateTimeTextFieldProps, DateTimeFormat, BizNumTextFieldProps, CardNumTextFieldProps, SelectChangeEvent, } from "./types";
+export type { SearchTextFieldProps, ClearTextFieldProps, TagsTextFieldProps, PasswordTextFieldProps, TextFieldProps, TextAreaProps, CheckboxProps, SwitchProps, RadioGroupProps, RadioOption, DateRangeProps, SliderProps, RatingProps, ToggleButtonProps, ToggleButtonGroupProps, ToggleButtonGroupOption, ButtonGroupProps, StepperProps, AutocompleteProps, AutocompleteOption, SelectProps, SelectOption, LabelSelectProps, LabelSelectOption, AddressTextFieldProps, DaumPostcodeData, PasswordValidationRules, PasswordValidationResult, PhoneTextFieldProps, PhoneFormat, NumberTextFieldProps, JuminTextFieldProps, JuminInfo, VerificationCodeTextFieldProps, VerificationCodeType, EmailTextFieldProps, CustomDomain, DateTextFieldProps, DateFormat, TimeTextFieldProps, TimeFormat, DateTimeTextFieldProps, DateTimeFormat, BizNumTextFieldProps, CardNumTextFieldProps, SelectChangeEvent, } from "./types";