@ncds/ui-admin 1.8.27 → 1.8.28-alpha.1

package/dist/esm/src/hooks/__tests__/useCallbackRef.test.js

@@ -0,0 +1,149 @@
+// @vitest-environment jsdom
+//
+// useCallbackRef (src/hooks/useCallbackRef.ts) 위험 경로 — 위험 목록표 CR-xx.
+// 훅을 ref 로 쓰는 최소 컴포넌트를 렌더하고, callback·cleanup 호출 순서를 로그로 비교한다.
+import { createElement } from 'react';
+import { createRoot } from 'react-dom/client';
+import { act } from 'react-dom/test-utils';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { useCallbackRef } from '../useCallbackRef';
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+const Probe = _ref => {
+  let {
+    tag,
+    callback
+  } = _ref;
+  return /*#__PURE__*/createElement(tag, {
+    ref: useCallbackRef(callback)
+  });
+};
+let root = null;
+let container = null;
+afterEach(() => {
+  if (root) {
+    act(() => {
+      root?.unmount();
+    });
+  }
+  root = null;
+  container?.remove();
+  container = null;
+  vi.restoreAllMocks();
+});
+const render = props => {
+  if (!container) {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  }
+  act(() => {
+    root?.render(/*#__PURE__*/createElement(Probe, props));
+  });
+};
+/** callback·cleanup 호출을 'callback:DIV' · 'cleanup:DIV' · 'callback:null' 형태로 기록한다 */
+const recorder = withCleanup => {
+  const log = [];
+  const callback = node => {
+    log.push(`callback:${node ? node.tagName : 'null'}`);
+    if (node && withCleanup) {
+      return () => {
+        log.push(`cleanup:${node.tagName}`);
+      };
+    }
+  };
+  return {
+    log,
+    callback
+  };
+};
+describe('useCallbackRef — 부착과 교체 (CR-01)', () => {
+  it('CR-01 노드가 붙으면 callback(node) 를 호출하고 그때는 cleanup 을 실행하지 않는다', () => {
+    const {
+      log,
+      callback
+    } = recorder(true);
+    render({
+      tag: 'div',
+      callback
+    });
+    expect(log).toEqual(['callback:DIV']);
+  });
+  it('CR-01 노드가 바뀌면 이전 노드의 cleanup 을 먼저 실행하고 새 노드로 callback 한다', () => {
+    const {
+      log,
+      callback
+    } = recorder(true);
+    render({
+      tag: 'div',
+      callback
+    });
+    render({
+      tag: 'span',
+      callback
+    });
+    expect(log).toEqual(['callback:DIV', 'cleanup:DIV', 'callback:null', 'callback:SPAN']);
+  });
+});
+describe('useCallbackRef — 언마운트 (CR-02)', () => {
+  it('CR-02 언마운트하면 cleanup 을 실행한 뒤 callback(null) 을 호출한다', () => {
+    const {
+      log,
+      callback
+    } = recorder(true);
+    render({
+      tag: 'div',
+      callback
+    });
+    act(() => {
+      root?.unmount();
+    });
+    root = null;
+    expect(log).toEqual(['callback:DIV', 'cleanup:DIV', 'callback:null']);
+  });
+});
+describe('useCallbackRef — cleanup 미반환 (CR-03)', () => {
+  it('CR-03 callback 이 cleanup 을 돌려주지 않으면 노드 교체 때 callback 만 이어서 호출한다', () => {
+    const {
+      log,
+      callback
+    } = recorder(false);
+    render({
+      tag: 'div',
+      callback
+    });
+    render({
+      tag: 'span',
+      callback
+    });
+    expect(log).toEqual(['callback:DIV', 'callback:null', 'callback:SPAN']);
+  });
+});
+describe('useCallbackRef — callback 교체 (CR-04)', () => {
+  it('CR-04 같은 노드라도 callback 참조가 바뀌면 이전 cleanup·이전 callback(null) 뒤 새 callback(node) 를 호출한다', () => {
+    const log = [];
+    const named = name => node => {
+      log.push(`${name}:${node ? node.tagName : 'null'}`);
+      if (node) {
+        return () => {
+          log.push(`${name}-cleanup:${node.tagName}`);
+        };
+      }
+      return undefined;
+    };
+    const first = named('first');
+    const second = named('second');
+    render({
+      tag: 'div',
+      callback: first
+    });
+    render({
+      tag: 'div',
+      callback: first
+    });
+    render({
+      tag: 'div',
+      callback: second
+    });
+    expect(log).toEqual(['first:DIV', 'first-cleanup:DIV', 'first:null', 'second:DIV']);
+  });
+});

package/dist/esm/src/hooks/__tests__/useMediaQuery.test.js

@@ -0,0 +1,116 @@
+// @vitest-environment jsdom
+import { createElement } from 'react';
+import { createRoot } from 'react-dom/client';
+import { act } from 'react-dom/test-utils';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { useMediaQuery } from '../useMediaQuery';
+// React 18에서 act() 사용 시 필요한 플래그 (미설정 시 console.error 경고 발생)
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+const QUERY = '(max-width: 768px)';
+/** change 리스너를 보관해 직접 호출할 수 있는 matchMedia 가짜 */
+const installMatchMedia = initialMatches => {
+  const listeners = new Set();
+  const queries = [];
+  vi.stubGlobal('matchMedia', query => {
+    queries.push(query);
+    return {
+      matches: initialMatches,
+      media: query,
+      addEventListener: (_type, listener) => listeners.add(listener),
+      removeEventListener: (_type, listener) => listeners.delete(listener)
+    };
+  });
+  const emit = matches => act(() => {
+    for (const listener of Array.from(listeners)) {
+      listener({
+        matches
+      });
+    }
+  });
+  return {
+    listeners,
+    queries,
+    emit
+  };
+};
+const mounted = [];
+afterEach(() => {
+  for (const {
+    root,
+    container
+  } of mounted.splice(0)) {
+    act(() => root.unmount());
+    container.remove();
+  }
+  vi.unstubAllGlobals();
+});
+/** 훅 결과를 data 속성으로 노출하는 프로브 컴포넌트 */
+const Probe = _ref => {
+  let {
+    onMatched
+  } = _ref;
+  const matches = useMediaQuery(QUERY, {
+    onMatched
+  });
+  return /*#__PURE__*/createElement('output', {
+    'data-matches': String(matches)
+  });
+};
+const mountProbe = onMatched => {
+  const container = document.createElement('div');
+  document.body.appendChild(container);
+  const root = createRoot(container);
+  const entry = {
+    root,
+    container
+  };
+  mounted.push(entry);
+  act(() => root.render(/*#__PURE__*/createElement(Probe, {
+    onMatched
+  })));
+  const read = () => container.querySelector('output')?.getAttribute('data-matches');
+  return {
+    read,
+    entry
+  };
+};
+describe('useMediaQuery (RSD-04)', () => {
+  it.each([[true, 'true'], [false, 'false']])('RSD-04 마운트 직후 matchMedia(query).matches %s 를 반영한다', (initial, expected) => {
+    const media = installMatchMedia(initial);
+    const probe = mountProbe();
+    expect(media.queries).toContain(QUERY);
+    expect(probe.read()).toBe(expected);
+  });
+  it('RSD-04 change(matches true) 는 값을 갱신하고 onMatched 를 부른다', () => {
+    const media = installMatchMedia(false);
+    const onMatched = vi.fn();
+    const probe = mountProbe(onMatched);
+    media.emit(true);
+    expect(probe.read()).toBe('true');
+    expect(onMatched).toHaveBeenCalled();
+  });
+  it('RSD-04 change(matches false) 는 값만 갱신하고 onMatched 를 부르지 않는다', () => {
+    const media = installMatchMedia(true);
+    const onMatched = vi.fn();
+    const probe = mountProbe(onMatched);
+    media.emit(false);
+    expect(probe.read()).toBe('false');
+    expect(onMatched).not.toHaveBeenCalled();
+  });
+  it('RSD-04 onMatched 없이도 change(true) 를 받는다', () => {
+    const media = installMatchMedia(false);
+    const probe = mountProbe();
+    media.emit(true);
+    expect(probe.read()).toBe('true');
+  });
+  it('RSD-04 unmount 하면 change 리스너를 해제한다', () => {
+    const media = installMatchMedia(false);
+    const probe = mountProbe();
+    const subscribedBefore = media.listeners.size;
+    mounted.splice(mounted.indexOf(probe.entry), 1);
+    act(() => probe.entry.root.unmount());
+    probe.entry.container.remove();
+    expect(subscribedBefore).toBeGreaterThan(0);
+    expect(media.listeners.size).toBe(0);
+  });
+});

package/dist/esm/src/hooks/__tests__/usePortalState.ssr.test.js

@@ -0,0 +1,22 @@
+// @vitest-environment node
+//
+// usePortalState 의 SSR 경로 — 위험 목록표 UPS-01 (PR-7c). useFloatingPosition.ssr.test.ts 선례처럼
+// document 가 없는 node 환경에서 renderToString 으로 훅을 부른다.
+import { createElement } from 'react';
+import { renderToString } from 'react-dom/server';
+import { describe, expect, it } from 'vitest';
+import { usePortalState } from '../usePortalState';
+describe('UPS-01 usePortalState — SSR', () => {
+  it('UPS-01 document 가 없으면 portalContainer 는 null 이고 Portal 을 쓰지 않는다', () => {
+    const results = [];
+    const PortalProbe = () => {
+      results.push(usePortalState());
+      return null;
+    };
+    renderToString(/*#__PURE__*/createElement(PortalProbe));
+    expect(results).toEqual([{
+      shouldPortal: false,
+      portalContainer: null
+    }]);
+  });
+});

package/dist/esm/src/hooks/dropdown/__tests__/dropdownHooks.test.js

@@ -0,0 +1,165 @@
+// @vitest-environment jsdom
+//
+// 드롭다운 훅의 컴포넌트 경유로 닿지 않는 분기 — 위험 목록표 DDH-01~03 (PR-7c).
+// 호출부(SelectBox·ComboBox)는 dropdownRef·target 을 항상 넘기고 isKeyboardNavigation 을 부르지 않으므로
+// 훅을 부르는 하네스 컴포넌트로 직접 구동한다.
+import { createElement, useRef } from 'react';
+import { createRoot } from 'react-dom/client';
+import { act } from 'react-dom/test-utils';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { useDropdown } from '../useDropdown';
+import { useDropdownKeyboard } from '../useDropdownKeyboard';
+import { useWindowResize } from '../useWindowResize';
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+const MAX_HEIGHT = 200;
+const OPTIONS = ['a', 'b'];
+const cleanups = [];
+afterEach(() => {
+  for (const cleanup of cleanups.splice(0)) cleanup();
+});
+const mount = element => {
+  const container = document.createElement('div');
+  document.body.appendChild(container);
+  const root = createRoot(container);
+  cleanups.push(() => {
+    act(() => root.unmount());
+    container.remove();
+  });
+  act(() => {
+    root.render(element);
+  });
+  return container;
+};
+const requireElement = (scope, selector) => {
+  const element = scope.querySelector(selector);
+  if (element === null) throw new Error(`요소를 찾을 수 없습니다: ${selector}`);
+  return element;
+};
+const dispatch = (target, event) => {
+  act(() => {
+    target.dispatchEvent(event);
+  });
+};
+describe('DDH-01 useDropdown — dropdownRef 생략', () => {
+  const DropdownProbe = () => {
+    const triggerRef = useRef(null);
+    const {
+      isOpen,
+      toggleDropdown
+    } = useDropdown({
+      triggerRef,
+      maxHeight: MAX_HEIGHT,
+      itemCount: OPTIONS.length,
+      optionItems: OPTIONS,
+      onSelect: () => undefined
+    });
+    return /*#__PURE__*/createElement('button', {
+      ref: triggerRef,
+      type: 'button',
+      'data-open': String(isOpen),
+      onClick: toggleDropdown
+    });
+  };
+  it('DDH-01 dropdownRef 없이도 트리거 안 mousedown 은 열린 채 두고, 바깥 mousedown 은 닫는다', () => {
+    const container = mount(/*#__PURE__*/createElement(DropdownProbe));
+    const trigger = requireElement(container, 'button');
+    act(() => {
+      trigger.click();
+    });
+    dispatch(trigger, new MouseEvent('mousedown', {
+      bubbles: true
+    }));
+    const afterInside = trigger.dataset.open;
+    dispatch(document.body, new MouseEvent('mousedown', {
+      bubbles: true
+    }));
+    expect([afterInside, trigger.dataset.open]).toEqual(['true', 'false']);
+  });
+});
+describe('DDH-02 useDropdownKeyboard — 직접 호출', () => {
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+  it('DDH-02 isKeyboardNavigation 은 화살표 뒤 true, mousemove 뒤 false 이고 옵션 목록 없는 dropdownRef 는 스크롤 보정을 건너뛴다', () => {
+    vi.useFakeTimers({
+      toFake: ['setTimeout']
+    });
+    const onFocusChange = vi.fn();
+    const captured = {
+      isKeyboardNavigation: null
+    };
+    const KeyboardProbe = () => {
+      // 옵션 목록(.ncua-select-dropdown__options)이 없는 요소를 dropdownRef 로 넘긴다
+      const dropdownRef = useRef(null);
+      const {
+        handleKeyDown,
+        handleMouseMove,
+        isKeyboardNavigation
+      } = useDropdownKeyboard({
+        isOpen: true,
+        disabled: false,
+        focusedIndex: -1,
+        optionItems: OPTIONS,
+        onToggle: () => undefined,
+        onSelect: () => undefined,
+        onClose: () => undefined,
+        onFocusChange,
+        dropdownRef
+      });
+      captured.isKeyboardNavigation = isKeyboardNavigation;
+      return /*#__PURE__*/createElement('div', {
+        ref: dropdownRef,
+        tabIndex: 0,
+        onKeyDown: handleKeyDown,
+        onMouseMove: handleMouseMove
+      });
+    };
+    const container = mount(/*#__PURE__*/createElement(KeyboardProbe));
+    const target = requireElement(container, 'div');
+    const isKeyboardNavigation = () => {
+      if (captured.isKeyboardNavigation === null) throw new Error('isKeyboardNavigation 을 얻지 못했습니다');
+      return captured.isKeyboardNavigation();
+    };
+    const initial = isKeyboardNavigation();
+    dispatch(target, new KeyboardEvent('keydown', {
+      key: 'ArrowDown',
+      bubbles: true,
+      cancelable: true
+    }));
+    const afterArrow = isKeyboardNavigation();
+    expect(() => act(() => {
+      vi.runOnlyPendingTimers();
+    })).not.toThrow();
+    dispatch(target, new MouseEvent('mousemove', {
+      bubbles: true
+    }));
+    expect([initial, afterArrow, isKeyboardNavigation()]).toEqual([false, true, false]);
+    expect(onFocusChange).toHaveBeenCalledWith(0);
+  });
+});
+describe('DDH-03 useWindowResize — target 생략', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+  it('DDH-03 target 을 넘기지 않으면 document.body 를 관찰한다', () => {
+    const observed = [];
+    class ResizeObserverStub {
+      observe(target) {
+        observed.push(target);
+      }
+      unobserve() {
+        return undefined;
+      }
+      disconnect() {
+        return undefined;
+      }
+    }
+    vi.stubGlobal('ResizeObserver', ResizeObserverStub);
+    const ResizeProbe = () => {
+      useWindowResize(() => undefined, true);
+      return null;
+    };
+    mount(/*#__PURE__*/createElement(ResizeProbe));
+    expect(observed.map(target => target === document.body)).toEqual([true]);
+  });
+});

package/dist/esm/src/types/component-meta.js

@@ -1,6 +1,2 @@
 /** AI 에이전트용 컴포넌트 메타데이터 타입 */
-/**
- * 컴포넌트 카테고리 — `src/components/` 하위 디렉토리명과 동일.
- * 타입과 런타임 값을 한 곳에서 정의해 추가/변경 시 동기화 누락을 막는다.
- */
 export const COMPONENT_CATEGORIES = ['action', 'data-display', 'feedback-and-status', 'forms-and-input', 'image-and-icons', 'layout', 'navigation', 'overlays'];

package/dist/esm/src/utils/__tests__/date-picker.test.js

@@ -1,6 +1,7 @@
 import moment from 'moment';
-import { describe, expect, it } from 'vitest';
-import { convertToMomentFormat } from '../date-picker';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { FIXED_TODAY, useFixedToday } from '../../__tests__/helpers/fixedToday';
+import { convertToMomentFormat, formatDateInput, formatHourInput, formatMinuteInput, getDateFormat, getSubtractDate, getToday } from '../date-picker';
 describe('convertToMomentFormat', () => {
   it('날짜 전용 포맷을 moment 토큰으로 변환한다 (기존 동작 보존)', () => {
     expect(convertToMomentFormat('Y-m-d')).toBe('YYYY-MM-DD');
@@ -23,4 +24,108 @@ describe('convertToMomentFormat', () => {
     expect(moment(date).format(convertToMomentFormat('Y-m-d H:i'))).toBe('2024-03-20 14:30');
     expect(moment(date).format(convertToMomentFormat('Y-m-d H:i:S'))).toBe('2024-03-20 14:30:05');
   });
+});
+// ── 위험 경로 DU-xx (PR-7a) ───────────────────────────────────────────────
+describe('DU-01 오늘 기준 기본값', () => {
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+  it('DU-01 getDateFormat() 은 인자가 없으면 오늘을 YYYY-MM-DD 로 돌려준다', () => {
+    useFixedToday();
+    expect(getDateFormat()).toBe('2026-10-21');
+    expect(getToday()).toEqual(FIXED_TODAY);
+  });
+  it('DU-01 getDateFormat 은 주어진 날짜를 YYYY-MM-DD 로 돌려준다', () => {
+    expect(getDateFormat('2026-01-05T09:30:00')).toBe('2026-01-05');
+  });
+  it('DU-01 getSubtractDate 는 date 가 없으면 오늘에서 period(unit) 를 뺀다', () => {
+    useFixedToday();
+    expect(getDateFormat(getSubtractDate({
+      period: 3,
+      unit: 'days'
+    }))).toBe('2026-10-18');
+  });
+  it('DU-01 getSubtractDate 는 date 가 있으면 그 날짜에서 빼고, 월 단위는 말일로 보정한다', () => {
+    expect(getDateFormat(getSubtractDate({
+      date: '2026-03-31',
+      period: 1,
+      unit: 'months'
+    }))).toBe('2026-02-28');
+  });
+  it.each([{
+    input: '20231112',
+    expected: '2023-11-12'
+  }, {
+    input: '2023-11-12',
+    expected: '2023-11-12'
+  },
+  // 실재하지 않는 월·일 8자리는 정리하지 않고 원문 유지 — 무효 판정·복원은 입력 핸들러 몫 (DPV-02 · #8)
+  {
+    input: '20231345',
+    expected: '20231345'
+  }])('DU-01 formatDateInput($input) → $expected', _ref => {
+    let {
+      input,
+      expected
+    } = _ref;
+    expect(formatDateInput(input)).toBe(expected);
+  });
+});
+describe('DU-02 시·분 입력 정리', () => {
+  it.each([{
+    input: '7a',
+    expected: '7'
+  }, {
+    input: '123',
+    expected: '12'
+  }, {
+    input: '23',
+    expected: '23'
+  }, {
+    input: '',
+    expected: ''
+  }])('DU-02 formatHourInput($input) → $expected', _ref2 => {
+    let {
+      input,
+      expected
+    } = _ref2;
+    expect(formatHourInput(input)).toBe(expected);
+  });
+  it.each([{
+    input: '5b',
+    expected: '5'
+  }, {
+    input: '599',
+    expected: '59'
+  }, {
+    input: '',
+    expected: ''
+  }])('DU-02 formatMinuteInput($input) → $expected', _ref3 => {
+    let {
+      input,
+      expected
+    } = _ref3;
+    expect(formatMinuteInput(input)).toBe(expected);
+  });
+  it.each([{
+    label: '시 24',
+    format: formatHourInput,
+    input: '24'
+  }, {
+    label: '시 99',
+    format: formatHourInput,
+    input: '99'
+  }, {
+    label: '분 60',
+    format: formatMinuteInput,
+    input: '60'
+  }])('DU-02 범위 밖 값($label)은 정리하지 않고 원문을 돌려준다', _ref4 => {
+    let {
+      format,
+      input
+    } = _ref4;
+    // 현재 동작 고정 — 결함 후보: 후속 이슈 (범위 밖을 원문 반환 → flatpickr blur 보정이 나머지 연산으로 감음 — RDP-11 과 같은 뿌리)
+    expect(format(input)).toBe(input);
+  });
+  it.todo('DU-02 시 24 이상 · 분 60 이상은 23 · 59 로 제한한다 (기대 동작)');
 });

package/dist/esm/src/utils/dropdown/__tests__/dropdownUtils.test.js

@@ -311,4 +311,28 @@ describe('findScrollableParent — 스크롤 부모 탐색 (characterisation)',
     }));
     expect(findScrollableParent(boundary, boundary)).toBe(boundary);
   });
+  it('UDD-01 boundary 밖 요소는 body 까지 올라가 boundary 를 만나지 못하고 null 을 반환한다', () => {
+    const [boundary] = mountChain(createScrollable({
+      overflowY: 'auto',
+      scrollable: true
+    }));
+    const [outside] = mountChain(createScrollable({
+      overflowY: 'visible',
+      scrollable: false
+    }), createScrollable({
+      overflowY: 'visible',
+      scrollable: false
+    }));
+    expect(findScrollableParent(outside, boundary)).toBeNull();
+  });
+  it('UDD-01 boundary 가 overflow auto 여도 내용이 넘치지 않으면 null 을 반환한다', () => {
+    const [boundary, target] = mountChain(createScrollable({
+      overflowY: 'auto',
+      scrollable: false
+    }), createScrollable({
+      overflowY: 'visible',
+      scrollable: false
+    }));
+    expect(findScrollableParent(target, boundary)).toBeNull();
+  });
 });

package/dist/esm/src/utils/dropdown/__tests__/multiSelect.test.js

@@ -0,0 +1,46 @@
+// @vitest-environment jsdom
+//
+// useMultiSelect 의 호출부 경유로 닿지 않는 방어 분기 — 위험 목록표 UDD-02 (PR-7c).
+// SelectBox·ComboBox 는 tryToggle 에 항상 배열을 넘기므로 훅을 하네스로 직접 부른다.
+import { createElement } from 'react';
+import { createRoot } from 'react-dom/client';
+import { act } from 'react-dom/test-utils';
+import { afterEach, describe, expect, it } from 'vitest';
+import { useMultiSelect } from '../multiSelect';
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+const OPTIONS = [{
+  id: 'a',
+  label: 'A'
+}, {
+  id: 'b',
+  label: 'B'
+}];
+const cleanups = [];
+afterEach(() => {
+  for (const cleanup of cleanups.splice(0)) cleanup();
+});
+const renderMultiSelect = () => {
+  const captured = {
+    current: null
+  };
+  const Probe = () => {
+    captured.current = useMultiSelect([], OPTIONS);
+    return null;
+  };
+  const container = document.createElement('div');
+  const root = createRoot(container);
+  cleanups.push(() => act(() => root.unmount()));
+  act(() => {
+    root.render(/*#__PURE__*/createElement(Probe));
+  });
+  if (captured.current === null) throw new Error('useMultiSelect 반환값을 얻지 못했습니다');
+  return captured.current;
+};
+describe('UDD-02 tryToggle 현재값 방어', () => {
+  it('UDD-02 현재값이 배열이 아니면 빈 배열 기준으로 추가한다', () => {
+    const {
+      tryToggle
+    } = renderMultiSelect();
+    expect(tryToggle('a', undefined)).toEqual(['a']);
+  });
+});