@ncds/ui-admin 1.8.26-alpha.0 → 1.8.26-alpha.2

package/dist/esm/src/components/forms-and-input/combo-box/ComboBox.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { ChevronSelectorVertical, SearchLg } from '@ncds/ui-admin-icon';
 import classNames from 'classnames';
-import { forwardRef, useImperativeHandle, useRef, useState } from 'react';
+import { forwardRef, useEffect, useImperativeHandle, useRef, useState } from 'react';
 import { useDropdown } from '../../../hooks/dropdown';
 import { useFloatingPosition } from '../../../hooks/useFloatingPosition';
 import { usePortalState } from '../../../hooks/usePortalState';
@@ -23,6 +23,112 @@ const notifyFormChange = (register, multiple, newValue) => {
     });
   }
 };
+/** '' · undefined · null 이면 빈 값. 숫자 0은 빈 값이 아니다 */
+const isEmptyValue = value => value === '' || value == null;
+/** react-hook-form hidden input 값 — Tag 와 같은 빈 값 규칙(0은 값)을 따른다 */
+const toHiddenInputValue = (value, multiple) => {
+  if (multiple) return JSON.stringify(value || []);
+  return isEmptyValue(value) ? '' : String(value);
+};
+/** SelectDropdown 은 null 을 받지 않으므로 undefined 로 바꾼다 */
+const toDropdownValue = value => value ?? undefined;
+/** multiple 용 — 배열이 아니면(null · undefined 포함) 빈 배열 */
+const toIdArray = value => Array.isArray(value) ? value : [];
+/** 두 id 목록이 같은 id 들로 이루어졌는지 — 순서는 보지 않는다 (사용처가 onChange 값을 정렬해 돌려줘도 같은 값) */
+const isSameIds = (currentIds, nextIds) => currentIds.length === nextIds.length && currentIds.every(id => nextIds.includes(id));
+const isSameTags = (nextTags, prevTags) => nextTags.length === prevTags.length && nextTags.every((tag, index) => tag.id === prevTags[index].id && tag.label === prevTags[index].label);
+const findOption = (optionItems, id) => optionItems.find(option => option.id === id);
+/** 단일 모드 value 에 해당하는 옵션 — 빈 값·배열이면 없음 */
+const findSingleOption = (value, optionItems) => {
+  if (isEmptyValue(value) || Array.isArray(value)) return undefined;
+  return findOption(optionItems, value);
+};
+/**
+ * 단일 모드 Tag — value 와 optionItems 에서 계산한다.
+ * 검색 필터로 목록에서 빠진 경우에만, 같은 id 로 기억해 둔 Tag 를 대신 쓴다.
+ */
+const resolveSingleTag = (value, optionItems, lastResolvedTag) => {
+  if (isEmptyValue(value) || Array.isArray(value)) return null;
+  const found = findOption(optionItems, value);
+  if (found) return {
+    id: found.id,
+    label: found.label
+  };
+  return lastResolvedTag?.id === value ? lastResolvedTag : null;
+};
+/** 단일 모드 Tag 목록 (0~1개). 목록에서 찾은 Tag 를 기억해 검색 필터 중에도 라벨을 유지한다 */
+const useSingleSelectedTags = (value, optionItems, enabled) => {
+  const [lastResolvedTag, setLastResolvedTag] = useState(null);
+  const found = enabled ? findSingleOption(value, optionItems) : undefined;
+  const foundId = found?.id;
+  const foundLabel = found?.label;
+  useEffect(() => {
+    if (foundId === undefined || foundLabel === undefined) return;
+    setLastResolvedTag({
+      id: foundId,
+      label: foundLabel
+    });
+  }, [foundId, foundLabel]);
+  const selectedTag = enabled ? resolveSingleTag(value, optionItems, lastResolvedTag) : null;
+  return selectedTag ? [selectedTag] : [];
+};
+/** multiple 모드 Tag — 목록에서 못 찾은 id 는 이미 표시 중인 Tag 의 라벨을 쓴다 */
+const resolveMultipleTags = (ids, optionItems, prevTags) => {
+  const nextTags = ids.map(id => {
+    const found = findOption(optionItems, id);
+    return found ? {
+      id: found.id,
+      label: found.label
+    } : prevTags.find(tag => tag.id === id);
+  }).filter(tag => tag !== undefined);
+  // 결과가 같으면 이전 배열을 그대로 돌려준다 — 새 배열로 바꾸면 effect 가 다시 렌더를 일으킨다
+  return isSameTags(nextTags, prevTags) ? prevTags : nextTags;
+};
+/**
+ * multiple 모드 Tag — 「선택 완료」·X 클릭·외부 value 변경 때만 확정 id 를 바꾼다.
+ * ComboBox 가 직접 onChange 로 내보낸 값은 markEmitted 로 기록해 두고, 그 값이 value 로 돌아오면 한 번만 무시한다(확정 아님).
+ * 바깥 값이 들어오면 남아 있던 기록도 지운다 — 오래된 기록 때문에 이후 같은 바깥 값이 무시되지 않게 하기 위함.
+ * optionItems 만 바뀌면 확정 id 는 그대로 두고 라벨만 다시 찾는다 — 「선택 완료」 전 검색으로 Tag 가 확정되지 않게 하기 위함.
+ */
+const useMultipleSelectedTags = (value, optionItems, enabled) => {
+  const [selectedTags, setSelectedTags] = useState([]);
+  const lastEmittedRef = useRef(null);
+  const committedIdsRef = useRef([]);
+  const prevValueIdsRef = useRef(null);
+  useEffect(() => {
+    if (!enabled) return;
+    const ids = toIdArray(value);
+    const isEcho = lastEmittedRef.current !== null && isSameIds(ids, lastEmittedRef.current);
+    const isValueChanged = prevValueIdsRef.current === null || !isSameIds(ids, prevValueIdsRef.current);
+    prevValueIdsRef.current = ids;
+    if (isEcho) {
+      lastEmittedRef.current = null;
+    } else if (isValueChanged) {
+      committedIdsRef.current = ids;
+      lastEmittedRef.current = null;
+    }
+    setSelectedTags(prev => resolveMultipleTags(committedIdsRef.current, optionItems, prev));
+  }, [enabled, value, optionItems]);
+  /** 「선택 완료」로 Tag 를 확정한다 */
+  const commitTags = ids => {
+    committedIdsRef.current = ids;
+    setSelectedTags(prev => resolveMultipleTags(ids, optionItems, prev));
+  };
+  /** X 클릭 — 확정 id 에서 그 id 만 뺀다. value 기준으로 계산하면 「선택 완료」 전에 클릭한 항목까지 확정된다 */
+  const removeCommittedTag = tagId => {
+    commitTags(committedIdsRef.current.filter(id => id !== tagId));
+  };
+  /** ComboBox 가 onChange 로 내보낸 값을 기록한다 — value 로 돌아왔을 때 확정으로 보지 않기 위함 */
+  const markEmitted = ids => {
+    lastEmittedRef.current = ids;
+  };
+  return {
+    selectedTags,
+    commitTags,
+    removeCommittedTag,
+    markEmitted
+  };
+};
 const ComboBox = /*#__PURE__*/forwardRef((_ref, ref) => {
   let {
     placeholder = '검색하세요',
@@ -62,22 +168,24 @@ const ComboBox = /*#__PURE__*/forwardRef((_ref, ref) => {
   } = usePortalState(usePortal);
   const [inputValue, setInputValue] = useState(searchValue);
   const [showAllItems, setShowAllItems] = useState(false);
-  const [selectedTags, setSelectedTags] = useState([]);
+  const singleTags = useSingleSelectedTags(value, optionItems, !multiple);
+  const {
+    selectedTags,
+    commitTags,
+    removeCommittedTag,
+    markEmitted
+  } = useMultipleSelectedTags(value, optionItems, multiple);
   const handleOptionSelect = option => {
     if (disabled) return;
     if (multiple) {
       const newValue = tryToggle(option.id, Array.isArray(value) ? value : []);
       if (newValue === null) return;
+      markEmitted(newValue);
       onChange?.(newValue);
       notifyFormChange(register, multiple, newValue);
       return;
     }
     const newValue = option.id;
-    const tag = {
-      id: option.id,
-      label: option.label
-    };
-    setSelectedTags([tag]);
     onChange?.(newValue);
     notifyFormChange(register, multiple, newValue);
   };
@@ -184,7 +292,6 @@ const ComboBox = /*#__PURE__*/forwardRef((_ref, ref) => {
   const {
     buttonText: selectAllButtonText,
     toggleSelectAll,
-    getSelectedTagsData,
     removeTag,
     isMaxSelectionActive,
     tryToggle
@@ -194,6 +301,7 @@ const ComboBox = /*#__PURE__*/forwardRef((_ref, ref) => {
   const handleSelectAll = () => {
     if (!multiple || !onChange) return;
     const newSelectedValues = toggleSelectAll();
+    markEmitted(newSelectedValues);
     onChange(newSelectedValues);
   };
   const handleEdit = () => {
@@ -201,30 +309,32 @@ const ComboBox = /*#__PURE__*/forwardRef((_ref, ref) => {
   };
   const handleComplete = completedValue => {
     if (!multiple) return;
-    const tags = getSelectedTagsData();
-    setSelectedTags(tags);
+    commitTags(toIdArray(completedValue));
     setInputValue('');
     closeDropdown();
     onComplete?.(completedValue);
   };
   const handleRemoveTag = tagId => {
+    // X 버튼은 disabled 에서 숨기지만, 다른 호출 경로가 생겨도 값이 지워지지 않게 함수에서도 막는다
+    if (disabled) return;
     if (!onChange) return;
     if (multiple) {
       const newSelectedValues = removeTag(tagId);
+      markEmitted(newSelectedValues);
       onChange(newSelectedValues);
-      setSelectedTags(prev => prev.filter(tag => tag.id !== tagId));
+      removeCommittedTag(tagId);
       return;
     }
     onChange('');
-    setSelectedTags([]);
   };
   const comboboxId = `combobox-options-${id || 'default'}`;
   const hasVisibleOptions = showAllItems || inputValue;
   const displayedOptions = hasVisibleOptions ? optionItems : [];
   const showNoResults = !hasVisibleOptions || optionItems.length === 0;
   const showFooter = multiple || showFooterButtons;
-  const hiddenInputValue = multiple ? JSON.stringify(value || []) : String(value || '');
-  const hasTags = selectedTags.length > 0;
+  const hiddenInputValue = toHiddenInputValue(value, multiple);
+  const tags = multiple ? selectedTags : singleTags;
+  const hasTags = tags.length > 0;
   const {
     className: portalPanelClassName,
     style: portalPanelStyle
@@ -235,7 +345,7 @@ const ComboBox = /*#__PURE__*/forwardRef((_ref, ref) => {
     direction: dropdownDirection,
     size: size,
     options: displayedOptions,
-    value: value,
+    value: toDropdownValue(value),
     focusedIndex: focusedIndex,
     maxHeight: maxHeight,
     listboxId: comboboxId,
@@ -314,10 +424,10 @@ const ComboBox = /*#__PURE__*/forwardRef((_ref, ref) => {
       })]
     }), hasTags && _jsx("div", {
       className: "ncua-combobox__tags",
-      children: selectedTags.map(tag => _jsx(Tag, {
+      children: tags.map(tag => _jsx(Tag, {
         text: tag.label,
         size: "sm",
-        close: true,
+        close: !disabled,
         onButtonClick: () => handleRemoveTag(tag.id)
       }, tag.id))
     })]

package/dist/esm/src/components/forms-and-input/combo-box/__tests__/ComboBox.portal.test.js

@@ -473,7 +473,7 @@ describe('C-9 기본 경로 회귀 기준선', () => {
     expect(onSearch).toHaveBeenCalledWith('사');
     expect(view.content.querySelectorAll('.ncua-select-dropdown__option')).toHaveLength(createOptions().length);
   });
-  it('옵션을 선택하면 onChange 가 호출되고 선택 태그가 표시된다', () => {
+  it('옵션을 선택하면 onChange 가 호출된다', () => {
     // Given: 옵션이 노출된 기본 모드 ComboBox 에서
     const onChange = vi.fn();
     const view = mountComboBox({
@@ -486,9 +486,9 @@ describe('C-9 기본 경로 회귀 기준선', () => {
     act(() => {
       requireElement(view.content, '.ncua-select-dropdown__option').click();
     });
-    // Then: onChange 가 선택 값으로 호출되고 태그가 표시된다
+    // Then: onChange 가 선택 값으로 호출된다
+    // 선택 태그는 value 를 따르므로(#530) onChange 값을 value 로 돌려주는 경우의 태그 표시는 ComboBox.test.ts S-10 에서 검증한다
     expect(onChange).toHaveBeenCalledWith('apple');
-    expect(view.container.querySelectorAll('.ncua-combobox__tags .ncua-tag')).toHaveLength(1);
   });
   it('Escape 를 누르면 인라인 패널이 닫힌다', () => {
     // Given: 열려 있는 기본 모드 ComboBox 에서

package/dist/esm/src/components/forms-and-input/combo-box/__tests__/ComboBox.test.js

@@ -0,0 +1,452 @@
+// @vitest-environment jsdom
+import { createElement, useState } from 'react';
+import { createRoot } from 'react-dom/client';
+import { act } from 'react-dom/test-utils';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { ComboBox } from '../ComboBox';
+// React 18에서 act() 사용 시 필요한 플래그 (미설정 시 console.error 경고 발생)
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+const OPTIONS = [{
+  id: 1,
+  label: '사과'
+}, {
+  id: 2,
+  label: '바나나'
+}, {
+  id: 3,
+  label: '체리'
+}];
+/** id 1·2가 빠진 목록 — 검색 필터로 optionItems가 줄어든 상황 */
+const FILTERED_OPTIONS = [{
+  id: 3,
+  label: '체리'
+}];
+/** optionItems에 없는 id */
+const MISSING_ID = 99;
+/** 바깥에서 reset 으로 넣는 값 — 기존 선택(1·2)과 겹치지 않는 id */
+const RESET_ID = 3;
+/** 「전체 선택」 결과 — OPTIONS 의 모든 id */
+const ALL_IDS = OPTIONS.map(option => option.id);
+let root = null;
+let container = null;
+/** 같은 root에 다시 render하면 props 변경(rerender)이 된다. */
+function render(props) {
+  if (!container) {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  }
+  act(() => {
+    root?.render(/*#__PURE__*/createElement(ComboBox, props));
+  });
+  return container;
+}
+/** onChange로 받은 값을 value로 되돌려주는 사용처 흉내 (controlled) */
+function Harness(_ref) {
+  let {
+    initialValue,
+    onChangeSpy,
+    transform,
+    ...rest
+  } = _ref;
+  const [value, setValue] = useState(initialValue);
+  return /*#__PURE__*/createElement(ComboBox, {
+    ...rest,
+    value,
+    onChange: next => {
+      onChangeSpy(next);
+      setValue(transform ? transform(next) : next);
+    }
+  });
+}
+function renderHarness(props) {
+  if (!container) {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  }
+  act(() => {
+    root?.render(/*#__PURE__*/createElement(Harness, props));
+  });
+  return container;
+}
+function getTagTexts(el) {
+  return Array.from(el.querySelectorAll('.ncua-combobox__tags .ncua-tag .ncua-tag__text')).map(node => node.textContent ?? '');
+}
+function getCloseButtons(el) {
+  return Array.from(el.querySelectorAll('.ncua-combobox__tags .ncua-tag__close'));
+}
+function click(target) {
+  if (!target) throw new Error('클릭 대상을 찾을 수 없습니다');
+  act(() => {
+    target.click();
+  });
+}
+/** 「전체」 버튼으로 드롭다운을 연다 (입력값이 없어도 전체 목록 표시). */
+function openDropdown(el) {
+  click(el.querySelector('.ncua-input__right-icon'));
+}
+function clickOption(el, label) {
+  const option = Array.from(el.querySelectorAll('.ncua-select-dropdown__option')).find(node => node.textContent === label);
+  click(option);
+}
+function clickButton(el, label) {
+  const button = Array.from(el.querySelectorAll('button')).find(node => node.textContent?.includes(label));
+  click(button);
+}
+afterEach(() => {
+  act(() => {
+    root?.unmount();
+  });
+  container?.remove();
+  root = null;
+  container = null;
+});
+describe('ComboBox — 단일 모드 외부 value Tag', () => {
+  it('S-01: value에 해당하는 옵션이 있으면 Tag 1개를 라벨로 표시한다', () => {
+    const el = render({
+      value: 1,
+      optionItems: OPTIONS
+    });
+    expect(getTagTexts(el)).toEqual(['사과']);
+  });
+  it('S-02: optionItems가 늦게 도착하면 도착 시 Tag를 표시한다', () => {
+    const el = render({
+      value: 1,
+      optionItems: []
+    });
+    expect(getTagTexts(el)).toEqual([]);
+    render({
+      value: 1,
+      optionItems: OPTIONS
+    });
+    expect(getTagTexts(el)).toEqual(['사과']);
+  });
+  it.each([['빈 문자열', ''], ['undefined', undefined], ['null', null]])('S-03: value가 %s이면 Tag를 표시하지 않는다', (_, value) => {
+    const el = render({
+      value: value,
+      optionItems: OPTIONS
+    });
+    expect(el.querySelector('.ncua-combobox__tags')).toBeNull();
+  });
+  it.each([['빈 문자열', ''], ['undefined', undefined]])('S-04: Tag 표시 중 value가 %s로 바뀌면 Tag가 사라진다', (_, value) => {
+    const el = render({
+      value: 1,
+      optionItems: OPTIONS
+    });
+    expect(getTagTexts(el)).toEqual(['사과']);
+    render({
+      value,
+      optionItems: OPTIONS
+    });
+    expect(el.querySelector('.ncua-combobox__tags')).toBeNull();
+  });
+  it('S-05: 검색 필터로 optionItems에서 선택 항목이 빠져도 같은 라벨로 Tag를 유지한다', () => {
+    const el = render({
+      value: 1,
+      optionItems: OPTIONS
+    });
+    expect(getTagTexts(el)).toEqual(['사과']);
+    render({
+      value: 1,
+      optionItems: FILTERED_OPTIONS
+    });
+    expect(getTagTexts(el)).toEqual(['사과']);
+  });
+  it('S-06: 목록에 없는 다른 id로 바뀌면 이전 라벨을 쓰지 않고 Tag를 표시하지 않는다', () => {
+    const el = render({
+      value: 1,
+      optionItems: OPTIONS
+    });
+    expect(getTagTexts(el)).toEqual(['사과']);
+    render({
+      value: MISSING_ID,
+      optionItems: OPTIONS
+    });
+    expect(el.querySelector('.ncua-combobox__tags')).toBeNull();
+  });
+  it('S-07: value가 다른 id로 바뀌면 그 id의 라벨로 Tag를 바꾼다', () => {
+    const el = render({
+      value: 1,
+      optionItems: OPTIONS
+    });
+    render({
+      value: 2,
+      optionItems: OPTIONS
+    });
+    expect(getTagTexts(el)).toEqual(['바나나']);
+  });
+  it('S-08: disabled면 Tag는 표시하고 X 버튼은 표시하지 않는다', () => {
+    const el = render({
+      value: 1,
+      optionItems: OPTIONS,
+      disabled: true
+    });
+    expect(getTagTexts(el)).toEqual(['사과']);
+    expect(getCloseButtons(el)).toHaveLength(0);
+  });
+  it('S-09: value가 0이어도 빈 값으로 보지 않고 Tag를 표시한다', () => {
+    const el = render({
+      value: 0,
+      optionItems: [{
+        id: 0,
+        label: '없음'
+      }, ...OPTIONS]
+    });
+    expect(getTagTexts(el)).toEqual(['없음']);
+  });
+  it.each([[0, '0'], [null, '']])('S-12: register 사용 시 value가 %s이면 hidden input 값은 %j이다 (Tag 표시 규칙과 같게 0은 값으로 본다)', (value, expected) => {
+    const register = {
+      name: 'item',
+      onChange: vi.fn(),
+      onBlur: vi.fn(),
+      ref: vi.fn()
+    };
+    const el = render({
+      value,
+      register,
+      optionItems: [{
+        id: 0,
+        label: '없음'
+      }, ...OPTIONS]
+    });
+    expect(el.querySelector('input[type="hidden"]')?.value).toBe(expected);
+  });
+  it('S-10 (회귀): 옵션을 클릭하면 onChange(id)를 호출하고 Tag를 표시한다', () => {
+    const onChangeSpy = vi.fn();
+    const el = renderHarness({
+      initialValue: '',
+      onChangeSpy,
+      optionItems: OPTIONS
+    });
+    openDropdown(el);
+    clickOption(el, '바나나');
+    expect(onChangeSpy).toHaveBeenCalledWith(2);
+    expect(getTagTexts(el)).toEqual(['바나나']);
+  });
+  it('S-11 (회귀): X를 클릭하면 onChange("")를 호출하고 Tag가 사라진다', () => {
+    const onChangeSpy = vi.fn();
+    const el = renderHarness({
+      initialValue: 1,
+      onChangeSpy,
+      optionItems: OPTIONS
+    });
+    click(getCloseButtons(el)[0]);
+    expect(onChangeSpy).toHaveBeenCalledWith('');
+    expect(el.querySelector('.ncua-combobox__tags')).toBeNull();
+  });
+});
+describe('ComboBox — multiple 모드 외부 value Tag', () => {
+  it('M-01: value 배열에 해당하는 Tag를 모두 표시한다', () => {
+    const el = render({
+      multiple: true,
+      value: [1, 2],
+      optionItems: OPTIONS
+    });
+    expect(getTagTexts(el)).toEqual(['사과', '바나나']);
+  });
+  it('M-02: optionItems가 늦게 도착하면 도착 시 Tag를 표시한다', () => {
+    const el = render({
+      multiple: true,
+      value: [1, 2],
+      optionItems: []
+    });
+    expect(getTagTexts(el)).toEqual([]);
+    render({
+      multiple: true,
+      value: [1, 2],
+      optionItems: OPTIONS
+    });
+    expect(getTagTexts(el)).toEqual(['사과', '바나나']);
+  });
+  it.each([['빈 배열', []], ['undefined', undefined], ['null', null]])('M-03: value가 %s이면 Tag를 표시하지 않는다', (_, value) => {
+    const el = render({
+      multiple: true,
+      value: value,
+      optionItems: OPTIONS
+    });
+    expect(el.querySelector('.ncua-combobox__tags')).toBeNull();
+  });
+  it.each([['빈 배열', []], ['undefined', undefined]])('M-04: Tag 표시 중 value가 %s로 바뀌면 Tag가 사라진다', (_, value) => {
+    const el = render({
+      multiple: true,
+      value: [1, 2],
+      optionItems: OPTIONS
+    });
+    expect(getTagTexts(el)).toEqual(['사과', '바나나']);
+    render({
+      multiple: true,
+      value,
+      optionItems: OPTIONS
+    });
+    expect(el.querySelector('.ncua-combobox__tags')).toBeNull();
+  });
+  it('M-05: 바깥에서 value를 바꾸면(reset) 새 value로 Tag를 다시 그린다', () => {
+    const el = render({
+      multiple: true,
+      value: [1, 2],
+      optionItems: OPTIONS
+    });
+    render({
+      multiple: true,
+      value: [RESET_ID],
+      optionItems: OPTIONS
+    });
+    expect(getTagTexts(el)).toEqual(['체리']);
+  });
+  it('M-06: 검색 필터로 optionItems에서 선택 항목이 빠져도 Tag를 유지한다', () => {
+    const el = render({
+      multiple: true,
+      value: [1, 2],
+      optionItems: OPTIONS
+    });
+    render({
+      multiple: true,
+      value: [1, 2],
+      optionItems: FILTERED_OPTIONS
+    });
+    expect(getTagTexts(el)).toEqual(['사과', '바나나']);
+  });
+  it('M-07: disabled면 Tag는 표시하고 X 버튼은 표시하지 않는다', () => {
+    const el = render({
+      multiple: true,
+      value: [1],
+      optionItems: OPTIONS,
+      disabled: true
+    });
+    expect(getTagTexts(el)).toEqual(['사과']);
+    expect(getCloseButtons(el)).toHaveLength(0);
+  });
+  it('M-08 (회귀): 옵션을 클릭하면 onChange만 호출하고 Tag는 「선택 완료」 전까지 그대로다', () => {
+    const onChangeSpy = vi.fn();
+    const el = renderHarness({
+      multiple: true,
+      initialValue: [1],
+      onChangeSpy,
+      optionItems: OPTIONS
+    });
+    expect(getTagTexts(el)).toEqual(['사과']);
+    openDropdown(el);
+    clickOption(el, '바나나');
+    expect(onChangeSpy).toHaveBeenCalledWith([1, 2]);
+    expect(getTagTexts(el)).toEqual(['사과']);
+  });
+  it('M-09 (회귀): 옵션 클릭 후 「선택 완료」를 누르면 Tag를 반영하고 onComplete를 호출한다', () => {
+    const onChangeSpy = vi.fn();
+    const onComplete = vi.fn();
+    const el = renderHarness({
+      multiple: true,
+      initialValue: [1],
+      onChangeSpy,
+      onComplete,
+      optionItems: OPTIONS
+    });
+    openDropdown(el);
+    clickOption(el, '바나나');
+    clickButton(el, '선택 완료');
+    expect(getTagTexts(el)).toEqual(['사과', '바나나']);
+    expect(onComplete).toHaveBeenCalledWith([1, 2]);
+  });
+  it('M-10 (회귀): X를 클릭하면 onChange(남은 배열)를 호출하고 해당 Tag만 제거한다', () => {
+    const onChangeSpy = vi.fn();
+    const el = renderHarness({
+      multiple: true,
+      initialValue: [1, 2],
+      onChangeSpy,
+      optionItems: OPTIONS
+    });
+    click(getCloseButtons(el)[0]);
+    expect(onChangeSpy).toHaveBeenCalledWith([2]);
+    expect(getTagTexts(el)).toEqual(['바나나']);
+  });
+  it('M-11 (회귀): 「전체 선택」을 누르면 onChange(전체 id)만 호출하고 Tag는 그대로다', () => {
+    const onChangeSpy = vi.fn();
+    const el = renderHarness({
+      multiple: true,
+      initialValue: [],
+      onChangeSpy,
+      optionItems: OPTIONS
+    });
+    openDropdown(el);
+    clickButton(el, '전체 선택');
+    expect(onChangeSpy).toHaveBeenCalledWith(ALL_IDS);
+    expect(el.querySelector('.ncua-combobox__tags')).toBeNull();
+  });
+  it('M-12: 클릭으로 고른 값과 같은 값을 바깥에서 비웠다가 다시 넣어도 Tag를 표시한다', () => {
+    const props = {
+      multiple: true,
+      optionItems: OPTIONS,
+      onChange: vi.fn()
+    };
+    const el = render({
+      ...props,
+      value: []
+    });
+    openDropdown(el);
+    clickOption(el, '사과');
+    render({
+      ...props,
+      value: [1]
+    });
+    clickButton(el, '선택 완료');
+    expect(getTagTexts(el)).toEqual(['사과']);
+    render({
+      ...props,
+      value: []
+    });
+    expect(getTagTexts(el)).toEqual([]);
+    render({
+      ...props,
+      value: [1]
+    });
+    expect(getTagTexts(el)).toEqual(['사과']);
+  });
+  it('M-13 (회귀): 클릭 후 「선택 완료」 전에 optionItems가 바뀌어도(검색) Tag는 그대로다', () => {
+    const onChangeSpy = vi.fn();
+    const el = renderHarness({
+      multiple: true,
+      initialValue: [1],
+      onChangeSpy,
+      optionItems: OPTIONS
+    });
+    openDropdown(el);
+    clickOption(el, '바나나');
+    renderHarness({
+      multiple: true,
+      initialValue: [1],
+      onChangeSpy,
+      optionItems: FILTERED_OPTIONS
+    });
+    expect(onChangeSpy).toHaveBeenCalledWith([1, 2]);
+    expect(getTagTexts(el)).toEqual(['사과']);
+  });
+  it('M-14 (회귀): 「선택 완료」 전에 클릭한 항목이 있을 때 X를 누르면 그 Tag만 빠지고 클릭한 항목은 확정되지 않는다', () => {
+    const onChangeSpy = vi.fn();
+    const el = renderHarness({
+      multiple: true,
+      initialValue: [1],
+      onChangeSpy,
+      optionItems: OPTIONS
+    });
+    openDropdown(el);
+    clickOption(el, '바나나');
+    click(getCloseButtons(el)[0]);
+    expect(onChangeSpy).toHaveBeenLastCalledWith([2]);
+    expect(el.querySelector('.ncua-combobox__tags')).toBeNull();
+  });
+  it('M-15 (회귀): 사용처가 onChange 값의 순서를 바꿔 돌려줘도 「선택 완료」 전에는 Tag가 그대로다', () => {
+    const onChangeSpy = vi.fn();
+    const sortIds = value => Array.isArray(value) ? [...value].sort() : value;
+    const el = renderHarness({
+      multiple: true,
+      initialValue: [RESET_ID],
+      onChangeSpy,
+      transform: sortIds,
+      optionItems: OPTIONS
+    });
+    openDropdown(el);
+    clickOption(el, '사과');
+    expect(onChangeSpy).toHaveBeenCalledWith([RESET_ID, 1]);
+    expect(getTagTexts(el)).toEqual(['체리']);
+  });
+});