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

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

@@ -0,0 +1,26 @@
+// @vitest-environment node
+import { createElement, createRef } from 'react';
+import { renderToString } from 'react-dom/server';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { useFloatingPosition } from '../useFloatingPosition';
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+const FloatingProbe = () => {
+  useFloatingPosition({
+    enabled: true,
+    isOpen: true,
+    triggerRef: /*#__PURE__*/createRef(),
+    floatingRef: /*#__PURE__*/createRef(),
+    direction: 'down'
+  });
+  return null;
+};
+describe('useFloatingPosition — SSR', () => {
+  it('서버 렌더에서 useLayoutEffect 경고를 내지 않는다', () => {
+    const consoleError = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+    renderToString(/*#__PURE__*/createElement(FloatingProbe));
+    const layoutEffectWarnings = consoleError.mock.calls.filter(args => args.some(arg => typeof arg === 'string' && arg.includes('useLayoutEffect')));
+    expect(layoutEffectWarnings).toHaveLength(0);
+  });
+});

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

@@ -0,0 +1,319 @@
+// @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 { trackPortalPosition } from '../../utils/portal-position';
+import { useFloatingPosition } from '../useFloatingPosition';
+Object.assign(globalThis, {
+  IS_REACT_ACT_ENVIRONMENT: true
+});
+const installResizeObserverStub = () => {
+  class ResizeObserverStub {
+    constructor() {
+      this.observe = vi.fn();
+      this.unobserve = vi.fn();
+      this.disconnect = vi.fn();
+    }
+  }
+  vi.stubGlobal('ResizeObserver', ResizeObserverStub);
+};
+afterEach(() => {
+  document.body.innerHTML = '';
+  vi.unstubAllGlobals();
+  vi.restoreAllMocks();
+});
+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 CHANGED_OFFSET = 12;
+const EXPECTED_Z_INDEX = 1500;
+const toDomRect = rect => DOMRect.fromRect({
+  x: rect.left,
+  y: rect.top,
+  width: rect.width,
+  height: rect.bottom - rect.top
+});
+const createAnchor = function () {
+  let rect = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : makeAnchorRect();
+  const element = document.createElement('button');
+  document.body.appendChild(element);
+  vi.spyOn(element, 'getBoundingClientRect').mockReturnValue(toDomRect(rect));
+  return element;
+};
+const createPanel = () => {
+  const element = document.createElement('div');
+  document.body.appendChild(element);
+  Object.defineProperty(element, 'offsetHeight', {
+    value: PANEL_HEIGHT,
+    configurable: true
+  });
+  Object.defineProperty(element, 'offsetWidth', {
+    value: PANEL_WIDTH,
+    configurable: true
+  });
+  return element;
+};
+const makeRef = element => ({
+  current: element
+});
+const Probe = _ref => {
+  let {
+    params,
+    record
+  } = _ref;
+  record(useFloatingPosition(params));
+  return null;
+};
+const renderHook = initialParams => {
+  const container = document.createElement('div');
+  document.body.appendChild(container);
+  const root = createRoot(container);
+  const record = vi.fn();
+  const rerender = params => {
+    act(() => {
+      root.render(/*#__PURE__*/createElement(Probe, {
+        params,
+        record
+      }));
+    });
+  };
+  rerender(initialParams);
+  const unmount = () => {
+    act(() => {
+      root.unmount();
+    });
+    container.remove();
+  };
+  return {
+    rerender,
+    unmount,
+    latest: () => record.mock.lastCall?.[0]
+  };
+};
+const baseParams = function () {
+  let overrides = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+  return {
+    enabled: true,
+    isOpen: true,
+    triggerRef: makeRef(null),
+    floatingRef: makeRef(null),
+    direction: 'down',
+    ...overrides
+  };
+};
+const dispatchScroll = () => {
+  act(() => {
+    window.dispatchEvent(new Event('scroll'));
+  });
+};
+describe('useFloatingPosition ↔ trackPortalPosition 동등성 (E-1)', () => {
+  it.each([{
+    direction: 'down',
+    align: 'left',
+    matchTriggerWidth: false
+  }, {
+    direction: 'down',
+    align: 'right',
+    matchTriggerWidth: false
+  }, {
+    direction: 'up',
+    align: 'left',
+    matchTriggerWidth: true
+  }, {
+    direction: 'up',
+    align: 'right',
+    matchTriggerWidth: true
+  }])('direction=$direction · align=$align · matchTriggerWidth=$matchTriggerWidth 에서 훅 style 과 onUpdate 인자가 같다', _ref2 => {
+    let {
+      direction,
+      align,
+      matchTriggerWidth
+    } = _ref2;
+    installResizeObserverStub();
+    const anchor = createAnchor();
+    const panel = createPanel();
+    const onUpdate = vi.fn();
+    const hook = renderHook(baseParams({
+      triggerRef: makeRef(anchor),
+      floatingRef: makeRef(panel),
+      direction,
+      align,
+      matchTriggerWidth
+    }));
+    const cleanup = trackPortalPosition({
+      getAnchor: () => anchor,
+      getPanel: () => panel,
+      direction,
+      align,
+      matchAnchorWidth: matchTriggerWidth,
+      onUpdate
+    });
+    expect(hook.latest()).toEqual(onUpdate.mock.lastCall?.[0]);
+    expect(hook.latest()).toMatchObject({
+      position: 'fixed',
+      zIndex: EXPECTED_Z_INDEX
+    });
+    cleanup();
+    hook.unmount();
+  });
+});
+describe('useFloatingPosition — 비활성 (E-2)', () => {
+  it('enabled=false 이면 null 을 반환한다', () => {
+    installResizeObserverStub();
+    const hook = renderHook(baseParams({
+      enabled: false,
+      triggerRef: makeRef(createAnchor()),
+      floatingRef: makeRef(createPanel())
+    }));
+    expect(hook.latest()).toBeNull();
+    hook.unmount();
+  });
+  it('isOpen=false 이면 null 을 반환한다', () => {
+    installResizeObserverStub();
+    const hook = renderHook(baseParams({
+      isOpen: false,
+      triggerRef: makeRef(createAnchor()),
+      floatingRef: makeRef(createPanel())
+    }));
+    expect(hook.latest()).toBeNull();
+    hook.unmount();
+  });
+  it('열린 뒤 닫히면 style 이 null 로 돌아간다', () => {
+    installResizeObserverStub();
+    const triggerRef = makeRef(createAnchor());
+    const hook = renderHook(baseParams({
+      triggerRef
+    }));
+    expect(hook.latest()).not.toBeNull();
+    hook.rerender(baseParams({
+      triggerRef,
+      isOpen: false
+    }));
+    expect(hook.latest()).toBeNull();
+    hook.unmount();
+  });
+});
+describe('useFloatingPosition — 트리거 부재 (E-3)', () => {
+  it('triggerRef.current 가 null 이면 scroll·resize 리스너를 붙이지 않고 style 은 null 로 남는다', () => {
+    installResizeObserverStub();
+    const addEventListener = vi.spyOn(window, 'addEventListener');
+    const hook = renderHook(baseParams({
+      triggerRef: makeRef(null)
+    }));
+    const positionListeners = addEventListener.mock.calls.filter(_ref3 => {
+      let [type] = _ref3;
+      return type === 'scroll' || type === 'resize';
+    });
+    expect(positionListeners).toHaveLength(0);
+    expect(hook.latest()).toBeNull();
+    hook.unmount();
+  });
+  it('산출된 뒤 트리거가 사라지면 이전 style 을 유지한다', () => {
+    installResizeObserverStub();
+    const triggerRef = makeRef(createAnchor());
+    const hook = renderHook(baseParams({
+      triggerRef,
+      offset: DEFAULT_OFFSET
+    }));
+    const previous = hook.latest();
+    expect(previous).not.toBeNull();
+    triggerRef.current = null;
+    hook.rerender(baseParams({
+      triggerRef,
+      offset: CHANGED_OFFSET
+    }));
+    expect(hook.latest()).toEqual(previous);
+    hook.unmount();
+  });
+});
+describe('useFloatingPosition — 패널 지연 마운트 (E-4)', () => {
+  it('effect 시점에 패널이 없다가 마운트되면 scroll 시 panelHeight 가 반영된다', () => {
+    installResizeObserverStub();
+    const rect = makeAnchorRect();
+    const floatingRef = makeRef(null);
+    const hook = renderHook(baseParams({
+      triggerRef: makeRef(createAnchor(rect)),
+      floatingRef,
+      direction: 'up'
+    }));
+    expect(hook.latest()).toMatchObject({
+      top: rect.top - DEFAULT_OFFSET
+    });
+    floatingRef.current = createPanel();
+    dispatchScroll();
+    expect(hook.latest()).toMatchObject({
+      top: rect.top - PANEL_HEIGHT - DEFAULT_OFFSET
+    });
+    hook.unmount();
+  });
+});
+describe('useFloatingPosition — 프롭 변경 재구독 (E-5)', () => {
+  it('align 이 left→right 로 바뀌면 left 를 다시 계산한다', () => {
+    installResizeObserverStub();
+    const rect = makeAnchorRect();
+    const triggerRef = makeRef(createAnchor(rect));
+    const floatingRef = makeRef(createPanel());
+    const hook = renderHook(baseParams({
+      triggerRef,
+      floatingRef,
+      align: 'left'
+    }));
+    expect(hook.latest()).toMatchObject({
+      left: rect.left
+    });
+    hook.rerender(baseParams({
+      triggerRef,
+      floatingRef,
+      align: 'right'
+    }));
+    expect(hook.latest()).toMatchObject({
+      left: rect.right - PANEL_WIDTH
+    });
+    hook.unmount();
+  });
+  it('offset 이 바뀌면 top 을 다시 계산한다', () => {
+    installResizeObserverStub();
+    const rect = makeAnchorRect();
+    const triggerRef = makeRef(createAnchor(rect));
+    const hook = renderHook(baseParams({
+      triggerRef,
+      offset: DEFAULT_OFFSET
+    }));
+    expect(hook.latest()).toMatchObject({
+      top: rect.bottom + DEFAULT_OFFSET
+    });
+    hook.rerender(baseParams({
+      triggerRef,
+      offset: CHANGED_OFFSET
+    }));
+    expect(hook.latest()).toMatchObject({
+      top: rect.bottom + CHANGED_OFFSET
+    });
+    hook.unmount();
+  });
+  it('matchTriggerWidth=true 이면 minWidth 를 트리거 너비로 낸다', () => {
+    installResizeObserverStub();
+    const rect = makeAnchorRect();
+    const hook = renderHook(baseParams({
+      triggerRef: makeRef(createAnchor(rect)),
+      floatingRef: makeRef(createPanel()),
+      matchTriggerWidth: true
+    }));
+    expect(hook.latest()).toMatchObject({
+      minWidth: rect.width
+    });
+    hook.unmount();
+  });
+});

package/dist/esm/src/hooks/dropdown/useDropdown.js

@@ -10,6 +10,7 @@ export const useDropdown = config => {
   const {
     triggerRef,
     dropdownRef,
+    positionRef,
     maxHeight,
     itemCount,
     optionItems,
@@ -25,7 +26,7 @@ export const useDropdown = config => {
     direction,
     updatePosition
   } = useDropdownPosition({
-    triggerRef,
+    triggerRef: positionRef ?? triggerRef,
     maxHeight,
     itemCount
   });

package/dist/esm/src/hooks/useFloatingPosition.js

@@ -1,5 +1,6 @@
-import { useLayoutEffect, useState } from 'react';
-const FLOATING_Z_INDEX = 1500;
+import { useState } from 'react';
+import { trackPortalPosition } from '../utils/portal-position';
+import { useIsomorphicLayoutEffect } from './useIsomorphicLayoutEffect';
 export const useFloatingPosition = _ref => {
   let {
     enabled,
@@ -7,65 +8,25 @@ export const useFloatingPosition = _ref => {
     triggerRef,
     floatingRef,
     direction,
-    offset = 4,
-    align = 'left',
+    offset,
+    align,
     matchTriggerWidth = false
   } = _ref;
   const [style, setStyle] = useState(null);
-  useLayoutEffect(() => {
+  useIsomorphicLayoutEffect(() => {
     if (!enabled || !isOpen) {
       setStyle(null);
       return;
     }
-    const trigger = triggerRef.current;
-    if (!trigger) return;
-    const calculatePosition = (trigger, floatingHeight, floatingWidth) => {
-      const top = direction === 'up' ? trigger.top - floatingHeight - offset : trigger.bottom + offset;
-      const left = align === 'right' ? trigger.right - floatingWidth : trigger.left;
-      return {
-        top,
-        left
-      };
-    };
-    const update = () => {
-      const t = triggerRef.current;
-      const f = floatingRef.current;
-      if (!t) return;
-      const r = t.getBoundingClientRect();
-      const floatingHeight = f?.offsetHeight ?? 0;
-      const floatingWidth = matchTriggerWidth ? r.width : f?.offsetWidth ?? r.width;
-      const {
-        top,
-        left
-      } = calculatePosition(r, floatingHeight, floatingWidth);
-      // matchTriggerWidth=true: width는 max-content(콘텐츠 자연 너비), min-width만 trigger 너비로 보장.
-      // 옵션이 짧으면 trigger 너비, 길면 자연 확장 — 기존 absolute 모드와 동일한 UX.
-      setStyle({
-        position: 'fixed',
-        top,
-        left,
-        zIndex: FLOATING_Z_INDEX,
-        ...(matchTriggerWidth ? {
-          minWidth: r.width
-        } : {})
-      });
-    };
-    update();
-    window.addEventListener('scroll', update, true);
-    window.addEventListener('resize', update);
-    const triggerObserver = new ResizeObserver(update);
-    triggerObserver.observe(trigger);
-    let floatingObserver;
-    if (floatingRef.current) {
-      floatingObserver = new ResizeObserver(update);
-      floatingObserver.observe(floatingRef.current);
-    }
-    return () => {
-      window.removeEventListener('scroll', update, true);
-      window.removeEventListener('resize', update);
-      triggerObserver.disconnect();
-      floatingObserver?.disconnect();
-    };
+    return trackPortalPosition({
+      getAnchor: () => triggerRef.current,
+      getPanel: () => floatingRef.current,
+      direction,
+      align,
+      offset,
+      matchAnchorWidth: matchTriggerWidth,
+      onUpdate: setStyle
+    });
   }, [enabled, isOpen, direction, offset, align, matchTriggerWidth, triggerRef, floatingRef]);
   return style;
 };