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

package/dist/esm/src/components/navigation/context-tab/__tests__/useContextTabScroll.test.js

@@ -0,0 +1,589 @@
+// @vitest-environment jsdom
+//
+// useContextTabScroll 위험 경로 — 위험 목록표 CS-xx.
+// 하네스 컴포넌트(Pattern C)로 훅을 직접 마운트한다. ContextTab 쪽 버튼 연결은 ContextTab.test.ts(CT-06).
+// jsdom 은 레이아웃을 계산하지 않으므로 마운트 시점 측정은 Element.prototype getter spy,
+// 마운트 뒤 측정 변화는 bar 인스턴스에 값을 정의한 뒤 scroll·ResizeObserver 콜백으로 재계산시킨다.
+// scroll-snap 정렬·smooth 스크롤의 최종 위치(CS-10)는 실제 레이아웃이 필요해 단위 불가 — E2E 후보.
+import { createElement } from 'react';
+import { createRoot } from 'react-dom/client';
+import { act } from 'react-dom/test-utils';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { useContextTabScroll } from '../useContextTabScroll';
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+const EDGE_THRESHOLD = 1;
+const CLIENT_WIDTH = 300;
+const SCROLL_WIDTH = 1000;
+const MIDDLE_SCROLL_LEFT = 400;
+const END_SCROLL_LEFT = SCROLL_WIDTH - CLIENT_WIDTH;
+const observers = [];
+class ResizeObserverStub {
+  constructor(callback) {
+    this.record = {
+      callback,
+      targets: [],
+      disconnected: false
+    };
+    observers.push(this.record);
+  }
+  observe(target) {
+    this.record.targets.push(target);
+  }
+  unobserve() {
+    // 전체 해제(disconnect)만 검증 대상이다.
+  }
+  disconnect() {
+    this.record.disconnected = true;
+  }
+}
+const SCROLL_METHODS = ['scrollTo', 'scrollBy'];
+const METRIC_NAMES = ['scrollLeft', 'clientWidth', 'scrollWidth'];
+const originalMetricGetters = new Map(METRIC_NAMES.map(name => [name, Object.getOwnPropertyDescriptor(Element.prototype, name)?.get]));
+const originalOffsetLeftGetter = Object.getOwnPropertyDescriptor(HTMLElement.prototype, 'offsetLeft')?.get;
+let scrollTo;
+let scrollBy;
+let root = null;
+let container = null;
+beforeEach(() => {
+  scrollTo = vi.fn();
+  scrollBy = vi.fn();
+  Object.defineProperty(HTMLElement.prototype, 'scrollTo', {
+    configurable: true,
+    writable: true,
+    value: scrollTo
+  });
+  Object.defineProperty(HTMLElement.prototype, 'scrollBy', {
+    configurable: true,
+    writable: true,
+    value: scrollBy
+  });
+  vi.stubGlobal('ResizeObserver', ResizeObserverStub);
+});
+afterEach(() => {
+  if (root) {
+    act(() => {
+      root?.unmount();
+    });
+  }
+  root = null;
+  container = null;
+  observers.length = 0;
+  document.body.innerHTML = '';
+  for (const method of SCROLL_METHODS) {
+    delete HTMLElement.prototype[method];
+  }
+  vi.restoreAllMocks();
+  vi.unstubAllGlobals();
+  latest = null;
+});
+let latest = null;
+/** 훅 결과를 latest 로 노출하고 menus 수만큼 탭 자식을 그리는 관찰용 컴포넌트 */
+const Harness = _ref => {
+  let {
+    activeTab,
+    menus,
+    visibleTabsCount,
+    attachBar = true,
+    renderTabs = true
+  } = _ref;
+  const result = useContextTabScroll({
+    activeTab: activeTab,
+    menus,
+    visibleTabsCount
+  });
+  latest = result;
+  return /*#__PURE__*/createElement('div', {
+    ref: attachBar ? result.barRef : undefined,
+    className: 'bar'
+  }, ...(renderTabs ? menus.map((menu, index) => /*#__PURE__*/createElement('span', {
+    key: menu.id,
+    'data-id': menu.id,
+    'data-index': index
+  })) : []));
+};
+const render = props => {
+  if (!container) {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  }
+  act(() => {
+    root?.render(/*#__PURE__*/createElement(Harness, props));
+  });
+  return container;
+};
+const hook = () => latest;
+const barOf = view => view.querySelector('.bar');
+const menusOf = count => Array.from({
+  length: count
+}, (_, index) => ({
+  id: `m${index}`
+}));
+const MENU_COUNT = 10;
+const VISIBLE_COUNT = 3;
+const MENUS = menusOf(MENU_COUNT);
+/** 마운트 시점에 읽힐 측정값을 Element.prototype getter 로 고정한다. */
+const stubMountMetrics = metrics => {
+  for (const name of METRIC_NAMES) {
+    vi.spyOn(Element.prototype, name, 'get').mockReturnValue(metrics[name]);
+  }
+};
+/** 마운트 뒤 측정값 변화를 bar 인스턴스에 직접 정의한다. */
+const defineMetrics = (element, metrics) => {
+  for (const [key, value] of Object.entries(metrics)) {
+    Object.defineProperty(element, key, {
+      configurable: true,
+      writable: true,
+      value
+    });
+  }
+};
+/** 측정값을 정의한 뒤 scroll 이벤트로 에지를 다시 계산시킨다. */
+const scrollBarTo = (element, metrics) => {
+  defineMetrics(element, metrics);
+  act(() => {
+    element.dispatchEvent(new Event('scroll'));
+  });
+};
+const edges = () => ({
+  isBeginning: hook().isBeginning,
+  isEnd: hook().isEnd
+});
+const TAB_WIDTH = 120;
+const SHRUNK_MENU_COUNT = 9;
+const WIDER_VISIBLE_COUNT = 5;
+const FRACTIONAL_VISIBLE_COUNT = 2.5;
+/** m7 → 3개씩이면 페이지 시작 6, 5개씩이면 5 */
+const PAGE_START_OF_M7_BY_3 = 6;
+const PAGE_START_OF_M7_BY_5 = 5;
+/** 2.5개씩이면 m7 → floor(7 / 2.5) * 2.5 = 5, m8 → floor(8 / 2.5) * 2.5 = 7.5 */
+const PAGE_START_OF_M7_BY_2_5 = 5;
+/** 각 탭 자식의 offsetLeft 를 data-index × TAB_WIDTH 로 둔다 (마운트 시점 effect 도 읽을 수 있게 prototype getter). */
+const stubTabOffsets = () => {
+  vi.spyOn(HTMLElement.prototype, 'offsetLeft', 'get').mockImplementation(function () {
+    return Number(this.dataset.index ?? 0) * TAB_WIDTH;
+  });
+};
+const smoothTo = left => ({
+  left,
+  behavior: 'smooth'
+});
+describe('useContextTabScroll — 마운트 시 에지 계산 (CS-01)', () => {
+  it('CS-01 scrollLeft 0 이고 뒤에 더 있으면 isBeginning 만 true 다', () => {
+    stubMountMetrics({
+      scrollLeft: 0,
+      clientWidth: CLIENT_WIDTH,
+      scrollWidth: SCROLL_WIDTH
+    });
+    render({
+      menus: MENUS,
+      visibleTabsCount: VISIBLE_COUNT
+    });
+    expect(edges()).toEqual({
+      isBeginning: true,
+      isEnd: false
+    });
+  });
+  it('CS-01 중간 위치면 isBeginning·isEnd 모두 false 다', () => {
+    stubMountMetrics({
+      scrollLeft: MIDDLE_SCROLL_LEFT,
+      clientWidth: CLIENT_WIDTH,
+      scrollWidth: SCROLL_WIDTH
+    });
+    render({
+      menus: MENUS,
+      visibleTabsCount: VISIBLE_COUNT
+    });
+    expect(edges()).toEqual({
+      isBeginning: false,
+      isEnd: false
+    });
+  });
+  it('CS-01 끝까지 스크롤된 위치면 isEnd 만 true 다', () => {
+    stubMountMetrics({
+      scrollLeft: END_SCROLL_LEFT,
+      clientWidth: CLIENT_WIDTH,
+      scrollWidth: SCROLL_WIDTH
+    });
+    render({
+      menus: MENUS,
+      visibleTabsCount: VISIBLE_COUNT
+    });
+    expect(edges()).toEqual({
+      isBeginning: false,
+      isEnd: true
+    });
+  });
+  it('CS-01 시작 판정은 scrollLeft 1px 까지 true, 1px 을 넘으면 false 다', () => {
+    stubMountMetrics({
+      scrollLeft: EDGE_THRESHOLD,
+      clientWidth: CLIENT_WIDTH,
+      scrollWidth: SCROLL_WIDTH
+    });
+    const view = render({
+      menus: MENUS,
+      visibleTabsCount: VISIBLE_COUNT
+    });
+    expect(hook().isBeginning).toBe(true);
+    scrollBarTo(barOf(view), {
+      scrollLeft: EDGE_THRESHOLD + EDGE_THRESHOLD
+    });
+    expect(hook().isBeginning).toBe(false);
+  });
+  it('CS-01 끝 판정은 남은 거리 1px 까지 true, 1px 을 넘으면 false 다', () => {
+    stubMountMetrics({
+      scrollLeft: END_SCROLL_LEFT - EDGE_THRESHOLD,
+      clientWidth: CLIENT_WIDTH,
+      scrollWidth: SCROLL_WIDTH
+    });
+    const view = render({
+      menus: MENUS,
+      visibleTabsCount: VISIBLE_COUNT
+    });
+    expect(hook().isEnd).toBe(true);
+    scrollBarTo(barOf(view), {
+      scrollLeft: END_SCROLL_LEFT - EDGE_THRESHOLD - EDGE_THRESHOLD
+    });
+    expect(hook().isEnd).toBe(false);
+  });
+});
+describe('useContextTabScroll — scroll·리사이즈 시 재계산 (CS-02)', () => {
+  it('CS-02 bar 의 scroll 이벤트마다 에지를 다시 계산한다', () => {
+    const view = render({
+      menus: MENUS,
+      visibleTabsCount: VISIBLE_COUNT
+    });
+    const bar = barOf(view);
+    expect(edges()).toEqual({
+      isBeginning: true,
+      isEnd: true
+    });
+    scrollBarTo(bar, {
+      scrollLeft: MIDDLE_SCROLL_LEFT,
+      clientWidth: CLIENT_WIDTH,
+      scrollWidth: SCROLL_WIDTH
+    });
+    expect(edges()).toEqual({
+      isBeginning: false,
+      isEnd: false
+    });
+    scrollBarTo(bar, {
+      scrollLeft: END_SCROLL_LEFT
+    });
+    expect(edges()).toEqual({
+      isBeginning: false,
+      isEnd: true
+    });
+  });
+  it('CS-02 ResizeObserver 로 bar 를 관찰하고 콜백이 오면 에지를 다시 계산한다', () => {
+    const view = render({
+      menus: MENUS,
+      visibleTabsCount: VISIBLE_COUNT
+    });
+    const bar = barOf(view);
+    const [observer] = observers;
+    expect(observer.targets).toEqual([bar]);
+    defineMetrics(bar, {
+      scrollLeft: 0,
+      clientWidth: CLIENT_WIDTH,
+      scrollWidth: SCROLL_WIDTH
+    });
+    act(() => {
+      observer.callback();
+    });
+    expect(edges()).toEqual({
+      isBeginning: true,
+      isEnd: false
+    });
+  });
+});
+describe('useContextTabScroll — 페이지 단위 스크롤 (CS-03)', () => {
+  it('CS-03 scrollByPage(1) 은 보이는 폭만큼 오른쪽으로 smooth scrollBy 한다', () => {
+    const view = render({
+      menus: MENUS,
+      visibleTabsCount: VISIBLE_COUNT
+    });
+    defineMetrics(barOf(view), {
+      clientWidth: CLIENT_WIDTH
+    });
+    act(() => {
+      hook().scrollByPage(1);
+    });
+    expect(scrollBy).toHaveBeenCalledWith({
+      left: CLIENT_WIDTH,
+      behavior: 'smooth'
+    });
+  });
+  it('CS-03 scrollByPage(-1) 은 보이는 폭만큼 왼쪽으로 smooth scrollBy 한다', () => {
+    const view = render({
+      menus: MENUS,
+      visibleTabsCount: VISIBLE_COUNT
+    });
+    defineMetrics(barOf(view), {
+      clientWidth: CLIENT_WIDTH
+    });
+    act(() => {
+      hook().scrollByPage(-1);
+    });
+    expect(scrollBy).toHaveBeenCalledWith({
+      left: -CLIENT_WIDTH,
+      behavior: 'smooth'
+    });
+  });
+});
+describe('useContextTabScroll — 활성 탭 자동 스크롤 (CS-04)', () => {
+  it('CS-04 마운트 시 활성 탭이 속한 페이지의 첫 탭 offsetLeft 로 smooth scrollTo 한다', () => {
+    stubTabOffsets();
+    render({
+      activeTab: 'm7',
+      menus: MENUS,
+      visibleTabsCount: VISIBLE_COUNT
+    });
+    expect(scrollTo).toHaveBeenCalledWith(smoothTo(PAGE_START_OF_M7_BY_3 * TAB_WIDTH));
+  });
+  it('CS-04 activeTab 이 바뀌면 새 활성 탭의 페이지로 다시 스크롤한다', () => {
+    stubTabOffsets();
+    render({
+      activeTab: 'm7',
+      menus: MENUS,
+      visibleTabsCount: VISIBLE_COUNT
+    });
+    render({
+      activeTab: 'm1',
+      menus: MENUS,
+      visibleTabsCount: VISIBLE_COUNT
+    });
+    expect(scrollTo).toHaveBeenLastCalledWith(smoothTo(0));
+  });
+  it('CS-04 visibleTabsCount 가 바뀌면 새 페이지 크기로 다시 계산한다', () => {
+    stubTabOffsets();
+    render({
+      activeTab: 'm7',
+      menus: MENUS,
+      visibleTabsCount: VISIBLE_COUNT
+    });
+    render({
+      activeTab: 'm7',
+      menus: MENUS,
+      visibleTabsCount: WIDER_VISIBLE_COUNT
+    });
+    expect(scrollTo).toHaveBeenLastCalledWith(smoothTo(PAGE_START_OF_M7_BY_5 * TAB_WIDTH));
+  });
+  it('CS-04 menus 배열 식별자만 바뀐 리렌더에서는 다시 스크롤하지 않는다', () => {
+    stubTabOffsets();
+    render({
+      activeTab: 'm7',
+      menus: MENUS,
+      visibleTabsCount: VISIBLE_COUNT
+    });
+    scrollTo.mockClear();
+    render({
+      activeTab: 'm7',
+      menus: [...MENUS],
+      visibleTabsCount: VISIBLE_COUNT
+    });
+    expect(scrollTo).not.toHaveBeenCalled();
+  });
+});
+describe('useContextTabScroll — 자동 스크롤 가드 (CS-05)', () => {
+  it('CS-05 activeTab 이 undefined 면 scrollTo 를 호출하지 않는다', () => {
+    render({
+      menus: MENUS,
+      visibleTabsCount: VISIBLE_COUNT
+    });
+    expect(scrollTo).not.toHaveBeenCalled();
+  });
+  it('CS-05 activeTab 이 null 이어도 scrollTo 를 호출하지 않는다', () => {
+    render({
+      activeTab: null,
+      menus: MENUS,
+      visibleTabsCount: VISIBLE_COUNT
+    });
+    expect(scrollTo).not.toHaveBeenCalled();
+  });
+  it('CS-05 menus 에 없는 id 면 scrollTo 를 호출하지 않는다', () => {
+    render({
+      activeTab: 'unknown',
+      menus: MENUS,
+      visibleTabsCount: VISIBLE_COUNT
+    });
+    expect(scrollTo).not.toHaveBeenCalled();
+  });
+  it('CS-05 페이지 시작 위치에 탭 자식이 없으면 scrollTo 를 호출하지 않는다', () => {
+    render({
+      activeTab: 'm7',
+      menus: MENUS,
+      visibleTabsCount: VISIBLE_COUNT,
+      renderTabs: false
+    });
+    expect(scrollTo).not.toHaveBeenCalled();
+  });
+});
+describe('useContextTabScroll — 리스너 재구독·정리 (CS-06)', () => {
+  it('CS-06 menus.length 가 바뀌면 이전 scroll 리스너·observer 를 정리하고 다시 구독한다', () => {
+    const view = render({
+      menus: MENUS,
+      visibleTabsCount: VISIBLE_COUNT
+    });
+    const bar = barOf(view);
+    const addListener = vi.spyOn(bar, 'addEventListener');
+    const removeListener = vi.spyOn(bar, 'removeEventListener');
+    render({
+      menus: menusOf(SHRUNK_MENU_COUNT),
+      visibleTabsCount: VISIBLE_COUNT
+    });
+    const [first, second] = observers;
+    expect(removeListener).toHaveBeenCalledWith('scroll', expect.any(Function));
+    expect(addListener).toHaveBeenCalledWith('scroll', expect.any(Function), {
+      passive: true
+    });
+    expect(first.disconnected).toBe(true);
+    expect(second.disconnected).toBe(false);
+    expect(second.targets).toEqual([bar]);
+  });
+  it('CS-06 visibleTabsCount 가 바뀌어도 다시 구독한다', () => {
+    render({
+      menus: MENUS,
+      visibleTabsCount: VISIBLE_COUNT
+    });
+    render({
+      menus: MENUS,
+      visibleTabsCount: WIDER_VISIBLE_COUNT
+    });
+    expect(observers.map(observer => observer.disconnected)).toEqual([true, false]);
+  });
+  it('CS-06 길이·노출 수가 같으면 menus 배열이 새로 와도 다시 구독하지 않는다', () => {
+    render({
+      menus: MENUS,
+      visibleTabsCount: VISIBLE_COUNT
+    });
+    render({
+      menus: [...MENUS],
+      visibleTabsCount: VISIBLE_COUNT
+    });
+    expect(observers).toHaveLength(1);
+    expect(observers[0].disconnected).toBe(false);
+  });
+  it('CS-06 언마운트하면 scroll 리스너를 해제하고 observer 를 disconnect 한다', () => {
+    const view = render({
+      menus: MENUS,
+      visibleTabsCount: VISIBLE_COUNT
+    });
+    const bar = barOf(view);
+    const removeListener = vi.spyOn(bar, 'removeEventListener');
+    act(() => {
+      root?.unmount();
+    });
+    root = null;
+    expect(removeListener).toHaveBeenCalledWith('scroll', expect.any(Function));
+    expect(observers[0].disconnected).toBe(true);
+  });
+  it('CS-06 언마운트 뒤 늦게 도착한 ResizeObserver 콜백은 bar 가 없어 예외 없이 무시한다', () => {
+    render({
+      menus: MENUS,
+      visibleTabsCount: VISIBLE_COUNT
+    });
+    const [observer] = observers;
+    act(() => {
+      root?.unmount();
+    });
+    root = null;
+    expect(() => observer.callback()).not.toThrow();
+  });
+});
+describe('useContextTabScroll — barRef 미부착 (CS-07)', () => {
+  it('CS-07 barRef 를 붙이지 않으면 isBeginning·isEnd 는 초기값 true 이고 구독하지 않는다', () => {
+    render({
+      menus: MENUS,
+      visibleTabsCount: VISIBLE_COUNT,
+      attachBar: false
+    });
+    expect(edges()).toEqual({
+      isBeginning: true,
+      isEnd: true
+    });
+    expect(observers).toHaveLength(0);
+  });
+  it('CS-07 barRef 가 없으면 scrollByPage·자동 스크롤이 예외 없이 아무것도 하지 않는다', () => {
+    render({
+      activeTab: 'm7',
+      menus: MENUS,
+      visibleTabsCount: VISIBLE_COUNT,
+      attachBar: false
+    });
+    expect(() => act(() => {
+      hook().scrollByPage(1);
+    })).not.toThrow();
+    expect(scrollBy).not.toHaveBeenCalled();
+    expect(scrollTo).not.toHaveBeenCalled();
+  });
+});
+describe('useContextTabScroll — menus 지연 도착 (CS-08)', () => {
+  it('CS-08 menus 가 마운트 뒤에 도착하면 activeTab 이 지정돼 있어도 활성 탭 페이지로 스크롤하지 않는다', () => {
+    // 현재 동작 고정 — 결함 후보: #593 (자동 스크롤 effect deps 가 [activeTab, visibleTabsCount] 뿐)
+    stubTabOffsets();
+    // ContextTab 은 menus 가 2개 미만이면 bar 를 그리지 않는다 — 처음엔 bar 없이 마운트.
+    render({
+      activeTab: 'm8',
+      menus: [],
+      visibleTabsCount: VISIBLE_COUNT,
+      attachBar: false
+    });
+    render({
+      activeTab: 'm8',
+      menus: MENUS,
+      visibleTabsCount: VISIBLE_COUNT
+    });
+    expect(barOf(container).children).toHaveLength(MENU_COUNT);
+    expect(scrollTo).not.toHaveBeenCalled();
+  });
+  it.todo('CS-08 bar 가 처음 생기거나 활성 탭 인덱스가 처음 확정될 때 활성 탭 페이지로 1회 스크롤한다 (#593)');
+});
+describe('useContextTabScroll — visibleTabsCount 검증 없음 (CS-09)', () => {
+  it('CS-09 visibleTabsCount 0 이면 페이지 시작이 NaN 이 돼 자동 스크롤하지 않는다', () => {
+    // 현재 동작 고정 — 결함 후보: #593 (visibleTabsCount 를 1 이상 정수로 검증·보정하지 않음)
+    stubTabOffsets();
+    render({
+      activeTab: 'm7',
+      menus: MENUS,
+      visibleTabsCount: 0
+    });
+    expect(scrollTo).not.toHaveBeenCalled();
+  });
+  it('CS-09 비정수(2.5)에서 페이지 시작이 소수(m8 → 7.5)면 해당 탭이 없어 스크롤하지 않는다', () => {
+    // 현재 동작 고정 — 결함 후보: #593 (visibleTabsCount 를 1 이상 정수로 검증·보정하지 않음)
+    stubTabOffsets();
+    render({
+      activeTab: 'm8',
+      menus: MENUS,
+      visibleTabsCount: FRACTIONAL_VISIBLE_COUNT
+    });
+    expect(scrollTo).not.toHaveBeenCalled();
+  });
+  it('CS-09 비정수(2.5)에서 페이지 시작이 정수(m7 → 5)면 5번째 탭으로 스크롤한다', () => {
+    // 현재 동작 고정 — 결함 후보: #593 (visibleTabsCount 를 1 이상 정수로 검증·보정하지 않음)
+    stubTabOffsets();
+    render({
+      activeTab: 'm7',
+      menus: MENUS,
+      visibleTabsCount: FRACTIONAL_VISIBLE_COUNT
+    });
+    expect(scrollTo).toHaveBeenCalledWith(smoothTo(PAGE_START_OF_M7_BY_2_5 * TAB_WIDTH));
+  });
+  it.todo('CS-09 visibleTabsCount 를 1 이상 정수로 보정(또는 기본값 대체)해 0·비정수에서도 활성 탭 페이지로 스크롤한다 (#593)');
+});
+describe('useContextTabScroll — 테스트 격리', () => {
+  it('측정값·offsetLeft getter spy 는 restoreAllMocks 로 원래 getter 로 돌아간다', () => {
+    stubMountMetrics({
+      scrollLeft: 0,
+      clientWidth: CLIENT_WIDTH,
+      scrollWidth: SCROLL_WIDTH
+    });
+    stubTabOffsets();
+    vi.restoreAllMocks();
+    for (const name of METRIC_NAMES) {
+      expect(Object.getOwnPropertyDescriptor(Element.prototype, name)?.get).toBe(originalMetricGetters.get(name));
+    }
+    expect(Object.getOwnPropertyDescriptor(HTMLElement.prototype, 'offsetLeft')?.get).toBe(originalOffsetLeftGetter);
+  });
+});