@ncds/ui-admin 1.8.24 → 1.8.25-alpha.1

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

@@ -0,0 +1,314 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { adjustDropdownPosition, calculateDropdownPosition, calculateNextFocusIndex, findScrollableParent } from '../dropdownUtils';
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.restoreAllMocks();
+});
+const VIEWPORT_HEIGHT = 800;
+const MAX_HEIGHT = 300;
+const ITEM_HEIGHT = 40;
+const ITEM_COUNT = 10;
+const PANEL_HEIGHT = Math.min(MAX_HEIGHT, ITEM_COUNT * ITEM_HEIGHT);
+const DEFAULT_GAP = 20;
+const EXTRA_SPACE = 200;
+const SHORTFALL = 100;
+const TRIGGER_HEIGHT = 40;
+const TRIGGER_WIDTH = 200;
+const createTriggerRef = _ref => {
+  let {
+    bottom
+  } = _ref;
+  const element = document.createElement('button');
+  vi.spyOn(element, 'getBoundingClientRect').mockReturnValue(DOMRect.fromRect({
+    x: 0,
+    y: bottom - TRIGGER_HEIGHT,
+    width: TRIGGER_WIDTH,
+    height: TRIGGER_HEIGHT
+  }));
+  return {
+    current: element
+  };
+};
+const nullTriggerRef = () => ({
+  current: null
+});
+describe('calculateDropdownPosition — 위임 후 반환 불변 (E-9)', () => {
+  it('triggerRef.current 가 null 이면 down · maxHeight 를 그대로 반환한다', () => {
+    vi.stubGlobal('innerHeight', VIEWPORT_HEIGHT);
+    const result = calculateDropdownPosition({
+      triggerRef: nullTriggerRef(),
+      maxHeight: MAX_HEIGHT,
+      itemCount: ITEM_COUNT
+    });
+    expect(result).toEqual({
+      direction: 'down',
+      maxHeight: MAX_HEIGHT
+    });
+  });
+  it.each([{
+    label: '공간 충분',
+    spaceBelow: PANEL_HEIGHT + EXTRA_SPACE,
+    direction: 'down'
+  }, {
+    label: '공간 부족',
+    spaceBelow: PANEL_HEIGHT - SHORTFALL,
+    direction: 'up'
+  }, {
+    label: '경계 (panelHeight+20)',
+    spaceBelow: PANEL_HEIGHT + DEFAULT_GAP,
+    direction: 'down'
+  }, {
+    label: '경계 -1 (panelHeight+19)',
+    spaceBelow: PANEL_HEIGHT + DEFAULT_GAP - 1,
+    direction: 'up'
+  }, {
+    label: '경계 +1 (panelHeight+21)',
+    spaceBelow: PANEL_HEIGHT + DEFAULT_GAP + 1,
+    direction: 'down'
+  }])('$label → $direction', _ref2 => {
+    let {
+      spaceBelow,
+      direction
+    } = _ref2;
+    vi.stubGlobal('innerHeight', VIEWPORT_HEIGHT);
+    const result = calculateDropdownPosition({
+      triggerRef: createTriggerRef({
+        bottom: VIEWPORT_HEIGHT - spaceBelow
+      }),
+      maxHeight: MAX_HEIGHT,
+      itemCount: ITEM_COUNT,
+      itemHeight: ITEM_HEIGHT
+    });
+    expect(result).toEqual({
+      direction,
+      maxHeight: MAX_HEIGHT
+    });
+  });
+  it('itemCount×itemHeight 가 maxHeight 보다 작으면 그 값을 패널 높이로 쓴다', () => {
+    vi.stubGlobal('innerHeight', VIEWPORT_HEIGHT);
+    const shortPanelHeight = 2 * ITEM_HEIGHT;
+    const result = calculateDropdownPosition({
+      triggerRef: createTriggerRef({
+        bottom: VIEWPORT_HEIGHT - (shortPanelHeight + DEFAULT_GAP)
+      }),
+      maxHeight: MAX_HEIGHT,
+      itemCount: 2,
+      itemHeight: ITEM_HEIGHT
+    });
+    expect(result.direction).toBe('down');
+  });
+  it('offset 을 지정하면 그 간격으로 반전 여부를 판정한다', () => {
+    vi.stubGlobal('innerHeight', VIEWPORT_HEIGHT);
+    const result = calculateDropdownPosition({
+      triggerRef: createTriggerRef({
+        bottom: VIEWPORT_HEIGHT - (PANEL_HEIGHT + DEFAULT_GAP)
+      }),
+      maxHeight: MAX_HEIGHT,
+      itemCount: ITEM_COUNT,
+      itemHeight: ITEM_HEIGHT,
+      offset: DEFAULT_GAP + 1
+    });
+    expect(result.direction).toBe('up');
+  });
+});
+describe('calculateNextFocusIndex — 순환 포커스 이동 (characterisation)', () => {
+  const LENGTH = 5;
+  const LAST = LENGTH - 1;
+  it('옵션이 없으면 -1 을 반환한다', () => {
+    expect(calculateNextFocusIndex(0, 'down', 0)).toBe(-1);
+    expect(calculateNextFocusIndex(2, 'up', 0)).toBe(-1);
+  });
+  it.each([{
+    label: 'down · 중간',
+    current: 2,
+    direction: 'down',
+    expected: 3
+  }, {
+    label: 'down · 마지막 → 첫 번째로 순환',
+    current: LAST,
+    direction: 'down',
+    expected: 0
+  }, {
+    label: 'up · 중간',
+    current: 2,
+    direction: 'up',
+    expected: 1
+  }, {
+    label: 'up · 첫 번째 → 마지막으로 순환',
+    current: 0,
+    direction: 'up',
+    expected: LAST
+  }, {
+    label: 'up · 초기값 -1 → 마지막',
+    current: -1,
+    direction: 'up',
+    expected: LAST
+  }])('$label', _ref3 => {
+    let {
+      current,
+      direction,
+      expected
+    } = _ref3;
+    expect(calculateNextFocusIndex(current, direction, LENGTH)).toBe(expected);
+  });
+});
+const VIEWPORT_WIDTH = 1000;
+const EDGE_MARGIN = 10;
+const createDropdownElement = rect => {
+  const element = document.createElement('div');
+  vi.spyOn(element, 'getBoundingClientRect').mockReturnValue(DOMRect.fromRect({
+    x: rect.left,
+    y: rect.bottom - rect.height,
+    width: rect.right - rect.left,
+    height: rect.height
+  }));
+  return element;
+};
+describe('adjustDropdownPosition — 뷰포트 이탈 보정 (characterisation)', () => {
+  it('뷰포트 안에 있으면 style 을 변경하지 않는다', () => {
+    vi.stubGlobal('innerWidth', VIEWPORT_WIDTH);
+    vi.stubGlobal('innerHeight', VIEWPORT_HEIGHT);
+    const element = createDropdownElement({
+      left: 100,
+      right: 300,
+      bottom: 400,
+      height: 200
+    });
+    adjustDropdownPosition(element);
+    expect(element.style.left).toBe('');
+    expect(element.style.maxHeight).toBe('');
+  });
+  it('우측 이탈 시 초과분 + 여백만큼 left 를 음수로 이동한다', () => {
+    vi.stubGlobal('innerWidth', VIEWPORT_WIDTH);
+    vi.stubGlobal('innerHeight', VIEWPORT_HEIGHT);
+    const overflow = 50;
+    const element = createDropdownElement({
+      left: 800,
+      right: VIEWPORT_WIDTH + overflow,
+      bottom: 400,
+      height: 200
+    });
+    adjustDropdownPosition(element);
+    expect(element.style.left).toBe(`${-overflow - EDGE_MARGIN}px`);
+  });
+  it('좌측 이탈 시 left 를 여백값으로 고정한다', () => {
+    vi.stubGlobal('innerWidth', VIEWPORT_WIDTH);
+    vi.stubGlobal('innerHeight', VIEWPORT_HEIGHT);
+    const element = createDropdownElement({
+      left: -30,
+      right: 170,
+      bottom: 400,
+      height: 200
+    });
+    adjustDropdownPosition(element);
+    expect(element.style.left).toBe(`${EDGE_MARGIN}px`);
+  });
+  it('하단 이탈 시 초과분 + 여백만큼 maxHeight 를 줄인다', () => {
+    vi.stubGlobal('innerWidth', VIEWPORT_WIDTH);
+    vi.stubGlobal('innerHeight', VIEWPORT_HEIGHT);
+    const overflow = 60;
+    const height = 200;
+    const element = createDropdownElement({
+      left: 100,
+      right: 300,
+      bottom: VIEWPORT_HEIGHT + overflow,
+      height
+    });
+    adjustDropdownPosition(element);
+    expect(element.style.maxHeight).toBe(`${height - overflow - EDGE_MARGIN}px`);
+  });
+});
+const CLIENT_HEIGHT = 100;
+const OVERFLOWING_SCROLL_HEIGHT = 500;
+const createScrollable = _ref4 => {
+  let {
+    overflowY,
+    scrollable
+  } = _ref4;
+  const element = document.createElement('div');
+  element.style.overflowY = overflowY;
+  Object.defineProperty(element, 'scrollHeight', {
+    value: scrollable ? OVERFLOWING_SCROLL_HEIGHT : CLIENT_HEIGHT,
+    configurable: true
+  });
+  Object.defineProperty(element, 'clientHeight', {
+    value: CLIENT_HEIGHT,
+    configurable: true
+  });
+  return element;
+};
+const mountChain = function () {
+  for (var _len = arguments.length, chain = new Array(_len), _key = 0; _key < _len; _key++) {
+    chain[_key] = arguments[_key];
+  }
+  chain.reduce((parent, child) => {
+    parent.appendChild(child);
+    return child;
+  });
+  document.body.appendChild(chain[0]);
+  return chain;
+};
+describe('findScrollableParent — 스크롤 부모 탐색 (characterisation)', () => {
+  afterEach(() => {
+    document.body.innerHTML = '';
+  });
+  it('boundary 이전에 overflow auto 이고 내용이 넘치는 조상이 있으면 그 요소를 반환한다', () => {
+    const [boundary, scrollParent,, target] = mountChain(createScrollable({
+      overflowY: 'visible',
+      scrollable: false
+    }), createScrollable({
+      overflowY: 'auto',
+      scrollable: true
+    }), createScrollable({
+      overflowY: 'visible',
+      scrollable: false
+    }), createScrollable({
+      overflowY: 'visible',
+      scrollable: false
+    }));
+    expect(findScrollableParent(target, boundary)).toBe(scrollParent);
+  });
+  it('overflow scroll 이어도 내용이 넘치지 않으면 건너뛴다', () => {
+    const [boundary,, target] = mountChain(createScrollable({
+      overflowY: 'visible',
+      scrollable: false
+    }), createScrollable({
+      overflowY: 'scroll',
+      scrollable: false
+    }), createScrollable({
+      overflowY: 'visible',
+      scrollable: false
+    }));
+    expect(findScrollableParent(target, boundary)).toBeNull();
+  });
+  it('조상 중 없고 boundary 자체가 스크롤 가능하면 boundary 를 반환한다', () => {
+    const [boundary,, target] = mountChain(createScrollable({
+      overflowY: 'auto',
+      scrollable: true
+    }), createScrollable({
+      overflowY: 'visible',
+      scrollable: false
+    }), createScrollable({
+      overflowY: 'visible',
+      scrollable: false
+    }));
+    expect(findScrollableParent(target, boundary)).toBe(boundary);
+  });
+  it('boundary 까지 스크롤 가능한 요소가 없으면 null 을 반환한다', () => {
+    const [boundary, target] = mountChain(createScrollable({
+      overflowY: 'hidden',
+      scrollable: true
+    }), createScrollable({
+      overflowY: 'visible',
+      scrollable: false
+    }));
+    expect(findScrollableParent(target, boundary)).toBeNull();
+  });
+  it('element 가 boundary 자신이면 boundary 의 스크롤 가능 여부로만 판정한다', () => {
+    const [boundary] = mountChain(createScrollable({
+      overflowY: 'scroll',
+      scrollable: true
+    }));
+    expect(findScrollableParent(boundary, boundary)).toBe(boundary);
+  });
+});

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

@@ -1,3 +1,4 @@
+import { resolveDropdownDirection } from '../portal-position';
 /**
  * 드롭다운 위치를 계산하는 유틸리티 함수
  */
@@ -15,19 +16,14 @@ export const calculateDropdownPosition = _ref => {
       maxHeight
     };
   }
-  const rect = triggerRef?.current.getBoundingClientRect();
-  const viewportHeight = window.innerHeight;
-  const dropdownHeight = Math.min(maxHeight, itemCount * itemHeight);
-  // 아래쪽 공간이 충분한지 확인
-  const spaceBelow = viewportHeight - rect.bottom;
-  if (spaceBelow < dropdownHeight + offset) {
-    return {
-      direction: 'up',
-      maxHeight
-    };
-  }
+  const direction = resolveDropdownDirection({
+    anchorRect: triggerRef.current.getBoundingClientRect(),
+    panelHeight: Math.min(maxHeight, itemCount * itemHeight),
+    viewportHeight: window.innerHeight,
+    gap: offset
+  });
   return {
-    direction: 'down',
+    direction,
     maxHeight
   };
 };

package/dist/esm/src/utils/portal-position/__tests__/portalPosition.test.js

@@ -0,0 +1,225 @@
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import { buildPortalPanelStyle, computePortalPosition, PORTAL_PANEL_Z_INDEX, resolveDropdownDirection } from '..';
+const makeAnchorRect = function () {
+  let overrides = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+  return {
+    top: 100,
+    bottom: 140,
+    left: 50,
+    right: 250,
+    width: 200,
+    ...overrides
+  };
+};
+const PANEL_HEIGHT = 300;
+const PANEL_WIDTH = 180;
+const DEFAULT_OFFSET = 4;
+const CUSTOM_OFFSET = 10;
+const DEFAULT_GAP = 20;
+const EXPECTED_Z_INDEX = 1500;
+const VIEWPORT_HEIGHT = 800;
+describe('portalPosition — 모듈 로드 (P-8)', () => {
+  it('Node 환경에서 window 없이 import 된다', () => {
+    expect(typeof window).toBe('undefined');
+    expect(computePortalPosition).toBeTypeOf('function');
+    expect(resolveDropdownDirection).toBeTypeOf('function');
+    expect(buildPortalPanelStyle).toBeTypeOf('function');
+  });
+});
+describe('computePortalPosition — 좌표 공식 (P-1)', () => {
+  const anchorRect = makeAnchorRect();
+  it.each([{
+    direction: 'down',
+    align: 'left',
+    top: 144,
+    left: 50
+  }, {
+    direction: 'down',
+    align: 'right',
+    top: 144,
+    left: 70
+  }, {
+    direction: 'up',
+    align: 'left',
+    top: -204,
+    left: 50
+  }, {
+    direction: 'up',
+    align: 'right',
+    top: -204,
+    left: 70
+  }])('direction=$direction · align=$align → top=$top · left=$left', _ref => {
+    let {
+      direction,
+      align,
+      top,
+      left
+    } = _ref;
+    const position = computePortalPosition({
+      anchorRect,
+      panelHeight: PANEL_HEIGHT,
+      panelWidth: PANEL_WIDTH,
+      direction,
+      align,
+      offset: DEFAULT_OFFSET
+    });
+    expect(position).toEqual({
+      top,
+      left
+    });
+  });
+});
+describe('computePortalPosition — 기본값 (P-2)', () => {
+  it('offset 을 생략하면 4px 을 적용한다', () => {
+    const anchorRect = makeAnchorRect();
+    const position = computePortalPosition({
+      anchorRect,
+      panelHeight: PANEL_HEIGHT,
+      panelWidth: PANEL_WIDTH,
+      direction: 'down'
+    });
+    expect(position.top).toBe(anchorRect.bottom + DEFAULT_OFFSET);
+  });
+  it('align 을 생략하면 left 정렬로 산출한다', () => {
+    const anchorRect = makeAnchorRect();
+    const position = computePortalPosition({
+      anchorRect,
+      panelHeight: PANEL_HEIGHT,
+      panelWidth: PANEL_WIDTH,
+      direction: 'down'
+    });
+    expect(position.left).toBe(anchorRect.left);
+  });
+  it('offset 을 지정하면 그 값으로 간격을 계산한다', () => {
+    const anchorRect = makeAnchorRect();
+    const down = computePortalPosition({
+      anchorRect,
+      panelHeight: PANEL_HEIGHT,
+      panelWidth: PANEL_WIDTH,
+      direction: 'down',
+      offset: CUSTOM_OFFSET
+    });
+    const up = computePortalPosition({
+      anchorRect,
+      panelHeight: PANEL_HEIGHT,
+      panelWidth: PANEL_WIDTH,
+      direction: 'up',
+      offset: CUSTOM_OFFSET
+    });
+    expect(down.top).toBe(anchorRect.bottom + CUSTOM_OFFSET);
+    expect(up.top).toBe(anchorRect.top - PANEL_HEIGHT - CUSTOM_OFFSET);
+  });
+});
+describe('buildPortalPanelStyle — 스타일 조립 (P-3)', () => {
+  it('matchAnchorWidth=false 이고 panelWidth 가 숫자면 그 너비로 계산하고 minWidth 를 내지 않는다', () => {
+    const anchorRect = makeAnchorRect();
+    const style = buildPortalPanelStyle({
+      anchorRect,
+      panelHeight: PANEL_HEIGHT,
+      panelWidth: PANEL_WIDTH,
+      direction: 'down',
+      align: 'right'
+    });
+    expect(style.left).toBe(anchorRect.right - PANEL_WIDTH);
+    expect(style).not.toHaveProperty('minWidth');
+  });
+  it('matchAnchorWidth=false 이고 panelWidth 가 null 이면 anchor 너비로 대체하고 minWidth 를 내지 않는다', () => {
+    const anchorRect = makeAnchorRect();
+    const style = buildPortalPanelStyle({
+      anchorRect,
+      panelHeight: PANEL_HEIGHT,
+      panelWidth: null,
+      direction: 'down',
+      align: 'right'
+    });
+    expect(style.left).toBe(anchorRect.right - anchorRect.width);
+    expect(style).not.toHaveProperty('minWidth');
+  });
+  it('matchAnchorWidth=true 이면 panelWidth 를 무시하고 anchor 너비를 minWidth 로 낸다 — align:right 조합에서 콘텐츠가 앵커보다 넓으면 우측 정렬이 보장되지 않는다', () => {
+    const anchorRect = makeAnchorRect();
+    const style = buildPortalPanelStyle({
+      anchorRect,
+      panelHeight: PANEL_HEIGHT,
+      panelWidth: PANEL_WIDTH,
+      direction: 'down',
+      align: 'right',
+      matchAnchorWidth: true
+    });
+    expect(style.left).toBe(anchorRect.right - anchorRect.width);
+    expect(style.minWidth).toBe(anchorRect.width);
+  });
+  it('direction=up 이면 panelHeight 만큼 위로 올린 top 을 낸다', () => {
+    const anchorRect = makeAnchorRect();
+    const style = buildPortalPanelStyle({
+      anchorRect,
+      panelHeight: PANEL_HEIGHT,
+      panelWidth: PANEL_WIDTH,
+      direction: 'up'
+    });
+    expect(style.top).toBe(anchorRect.top - PANEL_HEIGHT - DEFAULT_OFFSET);
+  });
+});
+describe('buildPortalPanelStyle — 고정 필드 (P-4)', () => {
+  it('position 은 fixed, zIndex 는 PORTAL_PANEL_Z_INDEX(1500) 이다', () => {
+    const style = buildPortalPanelStyle({
+      anchorRect: makeAnchorRect(),
+      panelHeight: PANEL_HEIGHT,
+      panelWidth: PANEL_WIDTH,
+      direction: 'down'
+    });
+    expect(PORTAL_PANEL_Z_INDEX).toBe(EXPECTED_Z_INDEX);
+    expect(style.position).toBe('fixed');
+    expect(style.zIndex).toBe(EXPECTED_Z_INDEX);
+  });
+  it('PortalPanelStyle 은 CSSProperties 에 할당 가능하다 (P-7)', () => {
+    expectTypeOf().toExtend();
+  });
+});
+describe('resolveDropdownDirection — 경계값 (P-5)', () => {
+  it.each([{
+    spaceBelow: PANEL_HEIGHT + DEFAULT_GAP,
+    expected: 'down'
+  }, {
+    spaceBelow: PANEL_HEIGHT + DEFAULT_GAP - 1,
+    expected: 'up'
+  }, {
+    spaceBelow: PANEL_HEIGHT + DEFAULT_GAP + 1,
+    expected: 'down'
+  }, {
+    spaceBelow: 0,
+    expected: 'up'
+  }])('spaceBelow=$spaceBelow → $expected', _ref2 => {
+    let {
+      spaceBelow,
+      expected
+    } = _ref2;
+    const direction = resolveDropdownDirection({
+      anchorRect: {
+        bottom: VIEWPORT_HEIGHT - spaceBelow
+      },
+      panelHeight: PANEL_HEIGHT,
+      viewportHeight: VIEWPORT_HEIGHT
+    });
+    expect(direction).toBe(expected);
+  });
+  it('gap 을 지정하면 그 간격으로 판정한다 (gap=0: 등호는 반전하지 않는다)', () => {
+    const exact = resolveDropdownDirection({
+      anchorRect: {
+        bottom: VIEWPORT_HEIGHT - PANEL_HEIGHT
+      },
+      panelHeight: PANEL_HEIGHT,
+      viewportHeight: VIEWPORT_HEIGHT,
+      gap: 0
+    });
+    const short = resolveDropdownDirection({
+      anchorRect: {
+        bottom: VIEWPORT_HEIGHT - PANEL_HEIGHT + 1
+      },
+      panelHeight: PANEL_HEIGHT,
+      viewportHeight: VIEWPORT_HEIGHT,
+      gap: 0
+    });
+    expect(exact).toBe('down');
+    expect(short).toBe('up');
+  });
+});