@ncds/ui-admin 1.8.22-alpha.1 → 1.8.22-alpha.3

package/dist/esm/src/components/data-display/table/__tests__/useTableScrollbars.regression.test.js

@@ -0,0 +1,336 @@
+// @vitest-environment jsdom
+/**
+ * 훅에 새로 추가한 동작만 다룬다.
+ * 기존 동작 무변경은 `useTableScrollbars.characterisation.test.ts` 가 고정한다.
+ */
+import { createElement, useEffect, useRef } 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 { SCROLLBAR_ATTRS, SCROLLBAR_OWNERS } from '../../../../../assets/scripts/table/scrollbar/const';
+import { useTableHorizontalScrollbar, useTableVerticalScrollbar } from '../useTableScrollbars';
+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() {
+    this.record.disconnected = true;
+  }
+}
+const defineMetrics = (element, metrics) => {
+  for (const [key, value] of Object.entries(metrics)) {
+    Object.defineProperty(element, key, {
+      configurable: true,
+      writable: true,
+      value
+    });
+  }
+};
+let container;
+let root;
+const probe = {
+  markerAtPassiveEffect: false
+};
+const render = element => {
+  act(() => {
+    root.render(element);
+  });
+};
+const VerticalHarness = _ref => {
+  let {
+    enabled = true
+  } = _ref;
+  const scrollContainerRef = useRef(null);
+  const scrollAreaRef = useRef(null);
+  const scrollbarRef = useRef(null);
+  const thumbRef = useRef(null);
+  // 훅보다 먼저 선언한 passive effect. 훅이 layout effect 를 쓰면 이 시점에 이미 부착돼 있다.
+  useEffect(() => {
+    probe.markerAtPassiveEffect = scrollContainerRef.current?.hasAttribute(SCROLLBAR_ATTRS.ready) ?? false;
+  });
+  const {
+    handleThumbMouseDown
+  } = useTableVerticalScrollbar({
+    enabled,
+    layoutKey: false,
+    scrollContainerRef,
+    scrollAreaRef,
+    scrollbarRef,
+    thumbRef
+  });
+  return /*#__PURE__*/createElement('div', {
+    className: 'ncua-table ncua-table--fixed-header'
+  }, /*#__PURE__*/createElement('div', {
+    ref: scrollAreaRef,
+    className: 'ncua-table__scroll-area'
+  }, /*#__PURE__*/createElement('div', {
+    ref: scrollContainerRef,
+    className: 'ncua-table__scroll-container'
+  }, /*#__PURE__*/createElement('table', {
+    className: 'ncua-table__table'
+  }, /*#__PURE__*/createElement('tbody', null))), /*#__PURE__*/createElement('div', {
+    ref: scrollbarRef,
+    className: 'ncua-table__scrollbar'
+  }, /*#__PURE__*/createElement('div', {
+    ref: thumbRef,
+    className: 'ncua-table__scrollbar-thumb',
+    onMouseDown: handleThumbMouseDown
+  }))));
+};
+const HorizontalHarness = () => {
+  const hScrollContainerRef = useRef(null);
+  const hScrollbarRef = useRef(null);
+  const hThumbRef = useRef(null);
+  const {
+    handleHThumbMouseDown
+  } = useTableHorizontalScrollbar({
+    enabled: true,
+    hScrollContainerRef,
+    hScrollbarRef,
+    hThumbRef
+  });
+  return /*#__PURE__*/createElement('div', {
+    className: 'ncua-table'
+  }, /*#__PURE__*/createElement('div', {
+    ref: hScrollContainerRef,
+    className: 'ncua-table__h-scroll-container'
+  }, /*#__PURE__*/createElement('div', {
+    className: 'ncua-table__h-scroll-inner'
+  }, /*#__PURE__*/createElement('table', {
+    className: 'ncua-table__table'
+  }, /*#__PURE__*/createElement('tbody', null))), /*#__PURE__*/createElement('div', {
+    ref: hScrollbarRef,
+    className: 'ncua-table__h-scrollbar'
+  }, /*#__PURE__*/createElement('div', {
+    ref: hThumbRef,
+    className: 'ncua-table__h-scrollbar-thumb',
+    onMouseDown: handleHThumbMouseDown
+  }))));
+};
+/** 누적 여부를 드러내기 위한 반복 드래그 횟수 */
+const DRAG_REPEAT = 5;
+const query = selector => container.querySelector(selector);
+beforeEach(() => {
+  vi.stubGlobal('ResizeObserver', ResizeObserverStub);
+  observers.length = 0;
+  probe.markerAtPassiveEffect = false;
+  container = document.createElement('div');
+  document.body.appendChild(container);
+  act(() => {
+    root = createRoot(container);
+  });
+});
+afterEach(() => {
+  act(() => {
+    root.unmount();
+  });
+  container.remove();
+  vi.unstubAllGlobals();
+  vi.restoreAllMocks();
+});
+describe('표식 부착', () => {
+  it('마운트 시 스크롤 컨테이너에 data-scrollbar-ready 를 부착한다', () => {
+    render(/*#__PURE__*/createElement(VerticalHarness));
+    expect(query('.ncua-table__scroll-container').hasAttribute(SCROLLBAR_ATTRS.ready)).toBe(true);
+  });
+  it('표식을 layout effect 에서 부착해 페인트 전에 반영한다', () => {
+    render(/*#__PURE__*/createElement(VerticalHarness));
+    expect(probe.markerAtPassiveEffect).toBe(true);
+  });
+  it('소유자 표식(react)을 함께 부착한다', () => {
+    render(/*#__PURE__*/createElement(VerticalHarness));
+    expect(query('.ncua-table__scroll-container').getAttribute(SCROLLBAR_ATTRS.owner)).toBe(SCROLLBAR_OWNERS.react);
+  });
+  it('언마운트 시 표식과 소유자 표식을 모두 제거한다', () => {
+    render(/*#__PURE__*/createElement(VerticalHarness));
+    const scrollEl = query('.ncua-table__scroll-container');
+    act(() => {
+      root.unmount();
+    });
+    expect(scrollEl.hasAttribute(SCROLLBAR_ATTRS.ready)).toBe(false);
+    expect(scrollEl.hasAttribute(SCROLLBAR_ATTRS.owner)).toBe(false);
+    act(() => {
+      root = createRoot(container);
+    });
+  });
+  it('가로축도 자기 스크롤 컨테이너에 표식을 부착한다', () => {
+    render(/*#__PURE__*/createElement(HorizontalHarness));
+    expect(query('.ncua-table__h-scroll-container').hasAttribute(SCROLLBAR_ATTRS.ready)).toBe(true);
+  });
+  it('타 소유자가 선점한 컨테이너는 덮어쓰지 않고 바인딩도 하지 않는다', () => {
+    render(/*#__PURE__*/createElement(VerticalHarness, {
+      enabled: false
+    }));
+    const scrollEl = query('.ncua-table__scroll-container');
+    scrollEl.setAttribute(SCROLLBAR_ATTRS.ready, '');
+    scrollEl.setAttribute(SCROLLBAR_ATTRS.owner, SCROLLBAR_OWNERS.cdn);
+    observers.length = 0;
+    render(/*#__PURE__*/createElement(VerticalHarness, {
+      enabled: true
+    }));
+    expect(scrollEl.getAttribute(SCROLLBAR_ATTRS.owner)).toBe(SCROLLBAR_OWNERS.cdn);
+    expect(observers).toHaveLength(0);
+  });
+  it('타 소유자가 선점한 표식은 언마운트에서도 제거하지 않는다', () => {
+    render(/*#__PURE__*/createElement(VerticalHarness, {
+      enabled: false
+    }));
+    const scrollEl = query('.ncua-table__scroll-container');
+    scrollEl.setAttribute(SCROLLBAR_ATTRS.ready, '');
+    scrollEl.setAttribute(SCROLLBAR_ATTRS.owner, SCROLLBAR_OWNERS.cdn);
+    render(/*#__PURE__*/createElement(VerticalHarness, {
+      enabled: true
+    }));
+    act(() => {
+      root.unmount();
+    });
+    expect(scrollEl.hasAttribute(SCROLLBAR_ATTRS.ready)).toBe(true);
+    expect(scrollEl.getAttribute(SCROLLBAR_ATTRS.owner)).toBe(SCROLLBAR_OWNERS.cdn);
+    act(() => {
+      root = createRoot(container);
+    });
+  });
+});
+describe('ResizeObserver 관찰 대상', () => {
+  it('세로축이 스크롤 콘텐츠 루트(<table>)를 함께 관찰한다', () => {
+    render(/*#__PURE__*/createElement(VerticalHarness));
+    expect(observers[0]?.targets).toContain(query('.ncua-table__table'));
+  });
+  it('컨테이너 치수 불변 + 콘텐츠 증가 통지에 썸 높이를 재산출한다', () => {
+    render(/*#__PURE__*/createElement(VerticalHarness));
+    const scrollEl = query('.ncua-table__scroll-container');
+    const thumbEl = query('.ncua-table__scrollbar-thumb');
+    defineMetrics(scrollEl, {
+      clientHeight: 200,
+      scrollHeight: 400,
+      scrollTop: 0
+    });
+    defineMetrics(query('.ncua-table__scrollbar'), {
+      clientHeight: 160
+    });
+    act(() => {
+      observers[0]?.callback();
+    });
+    expect(thumbEl.style.height).toBe('80px');
+    // 컨테이너 박스는 그대로인 채 콘텐츠만 늘어난 경우
+    defineMetrics(scrollEl, {
+      scrollHeight: 800
+    });
+    act(() => {
+      observers[0]?.callback();
+    });
+    expect(thumbEl.style.height).toBe('40px');
+  });
+  it('가로축이 __h-scroll-inner 와 콘텐츠 루트를 함께 관찰한다', () => {
+    render(/*#__PURE__*/createElement(HorizontalHarness));
+    expect(observers[0]?.targets).toContain(query('.ncua-table__h-scroll-inner'));
+    expect(observers[0]?.targets).toContain(query('.ncua-table__table'));
+  });
+});
+describe('드래그 해제 경로', () => {
+  it('pointercancel 로도 드래그가 종료된다', () => {
+    render(/*#__PURE__*/createElement(VerticalHarness));
+    const scrollEl = query('.ncua-table__scroll-container');
+    const thumbEl = query('.ncua-table__scrollbar-thumb');
+    const areaEl = query('.ncua-table__scroll-area');
+    defineMetrics(scrollEl, {
+      clientHeight: 200,
+      scrollHeight: 800,
+      scrollTop: 0
+    });
+    defineMetrics(thumbEl, {
+      offsetHeight: 40
+    });
+    act(() => {
+      thumbEl.dispatchEvent(new MouseEvent('mousedown', {
+        bubbles: true,
+        clientY: 100
+      }));
+    });
+    act(() => {
+      document.dispatchEvent(new Event('pointercancel'));
+      document.dispatchEvent(new MouseEvent('mousemove', {
+        clientY: 400
+      }));
+    });
+    expect(scrollEl.scrollTop).toBe(0);
+    expect(areaEl.hasAttribute(SCROLLBAR_ATTRS.dragging)).toBe(false);
+  });
+  it('드래그를 반복해도 해제 신호에 리스너가 누적되지 않는다', () => {
+    render(/*#__PURE__*/createElement(VerticalHarness));
+    const scrollEl = query('.ncua-table__scroll-container');
+    const thumbEl = query('.ncua-table__scrollbar-thumb');
+    const areaEl = query('.ncua-table__scroll-area');
+    defineMetrics(scrollEl, {
+      clientHeight: 200,
+      scrollHeight: 800,
+      scrollTop: 0
+    });
+    defineMetrics(thumbEl, {
+      offsetHeight: 40
+    });
+    // 누적이 있으면 잔존 클로저가 언마운트 시 드래그 횟수만큼 추가 발화한다.
+    for (let i = 0; i < DRAG_REPEAT; i += 1) {
+      act(() => {
+        thumbEl.dispatchEvent(new MouseEvent('mousedown', {
+          bubbles: true,
+          clientY: 100
+        }));
+        document.dispatchEvent(new MouseEvent('mouseup'));
+      });
+    }
+    const removeSpy = vi.spyOn(areaEl, 'removeAttribute');
+    act(() => {
+      root.unmount();
+    });
+    const draggingRemovals = removeSpy.mock.calls.filter(_ref2 => {
+      let [name] = _ref2;
+      return name === SCROLLBAR_ATTRS.dragging;
+    });
+    expect(draggingRemovals).toHaveLength(0);
+    act(() => {
+      root = createRoot(container);
+    });
+  });
+  it('언마운트가 드래그보다 먼저 일어나도 document 리스너가 남지 않는다', () => {
+    render(/*#__PURE__*/createElement(VerticalHarness));
+    const scrollEl = query('.ncua-table__scroll-container');
+    const thumbEl = query('.ncua-table__scrollbar-thumb');
+    defineMetrics(scrollEl, {
+      clientHeight: 200,
+      scrollHeight: 800,
+      scrollTop: 0
+    });
+    defineMetrics(thumbEl, {
+      offsetHeight: 40
+    });
+    act(() => {
+      thumbEl.dispatchEvent(new MouseEvent('mousedown', {
+        bubbles: true,
+        clientY: 100
+      }));
+    });
+    act(() => {
+      root.unmount();
+    });
+    document.dispatchEvent(new MouseEvent('mousemove', {
+      clientY: 400
+    }));
+    expect(scrollEl.scrollTop).toBe(0);
+    act(() => {
+      root = createRoot(container);
+    });
+  });
+});

package/dist/esm/src/components/data-display/table/useTableScrollbars.js

@@ -1,67 +1,23 @@
-import { useEffect } from 'react';
-// ──────────────────────────────────────────────
-// 상수 — Table.tsx 와 _table.scss 양쪽에서 동기화 필요
-// ──────────────────────────────────────────────
-// $table-header-height
-export const TABLE_HEADER_HEIGHT = 40;
-// 세로/가로 thumb 최소 크기
-export const SCROLLBAR_THUMB_MIN_HEIGHT = 40;
-export const H_SCROLLBAR_THUMB_MIN_WIDTH = 40;
-// SCSS .ncua-table__h-scrollbar { left/right: var(--spacing-s) = 8px } 와 동기화
-export const H_SCROLLBAR_SIDE_GAP = 8;
-// 세로 트랙 상하 여백 합계 — top 8 + bottom 8 = 16 (header 회피분 40 은 별도 처리)
-// biome-ignore lint/style/useExportsLast: 상수는 문서 주석과 함께 상단에 정의
-export const SCROLLBAR_TRACK_OFFSET = 16;
-const startDrag = (e, options) => {
-  e.preventDefault();
-  const {
-    axis,
-    scrollEl,
-    thumbEl,
-    draggingTarget = scrollEl,
-    sideGap = 0
-  } = options;
-  draggingTarget.setAttribute('data-dragging', '');
-  if (axis === 'y') {
-    const startY = e.clientY;
-    const startScrollTop = scrollEl.scrollTop;
-    const {
-      scrollHeight,
-      clientHeight
-    } = scrollEl;
-    const thumbHeight = thumbEl.offsetHeight;
-    const ratio = (scrollHeight - clientHeight) / (clientHeight - thumbHeight);
-    const onMove = ev => {
-      scrollEl.scrollTop = startScrollTop + (ev.clientY - startY) * ratio;
-    };
-    const onUp = () => {
-      draggingTarget.removeAttribute('data-dragging');
-      document.removeEventListener('mousemove', onMove);
-      document.removeEventListener('mouseup', onUp);
-    };
-    document.addEventListener('mousemove', onMove);
-    document.addEventListener('mouseup', onUp);
-    return;
-  }
-  const startX = e.clientX;
-  const startScrollLeft = scrollEl.scrollLeft;
-  const {
-    scrollWidth,
-    clientWidth
-  } = scrollEl;
-  const thumbWidth = thumbEl.offsetWidth;
-  const trackWidth = clientWidth - sideGap * 2;
-  const ratio = (scrollWidth - clientWidth) / (trackWidth - thumbWidth);
-  const onMove = ev => {
-    scrollEl.scrollLeft = startScrollLeft + (ev.clientX - startX) * ratio;
-  };
-  const onUp = () => {
-    draggingTarget.removeAttribute('data-dragging');
-    document.removeEventListener('mousemove', onMove);
-    document.removeEventListener('mouseup', onUp);
-  };
-  document.addEventListener('mousemove', onMove);
-  document.addEventListener('mouseup', onUp);
+import { useRef } from 'react';
+import { H_SCROLLBAR_SIDE_GAP, H_SCROLLBAR_THUMB_MIN_WIDTH, SCROLLBAR_ATTRS, SCROLLBAR_OWNERS, SCROLLBAR_THUMB_MIN_HEIGHT, SCROLLBAR_TRACK_OFFSET, TABLE_HEADER_HEIGHT } from '../../../../assets/scripts/table/scrollbar/const';
+import { startThumbDrag } from '../../../../assets/scripts/table/scrollbar/drag';
+import { computeHorizontalTrackBox, computeThumbGeometry } from '../../../../assets/scripts/table/scrollbar/geometry';
+import { useIsomorphicLayoutEffect } from '../../../hooks/useIsomorphicLayoutEffect';
+// CDN 바인딩과 같은 값을 쓰기 위해 재노출한다. 정의는 scrollbar/const.ts 에 있다.
+export { H_SCROLLBAR_SIDE_GAP, H_SCROLLBAR_THUMB_MIN_WIDTH, SCROLLBAR_THUMB_MIN_HEIGHT, SCROLLBAR_TRACK_OFFSET, TABLE_HEADER_HEIGHT };
+/** 타 소유자가 선점한 컨테이너는 덮어쓰지 않는다. CDN 생성자의 소유권 검사와 대칭이다 */
+const claimMarkers = el => {
+  const owner = el.getAttribute(SCROLLBAR_ATTRS.owner);
+  if (el.hasAttribute(SCROLLBAR_ATTRS.ready) && owner !== null && owner !== SCROLLBAR_OWNERS.react) return false;
+  el.setAttribute(SCROLLBAR_ATTRS.ready, '');
+  el.setAttribute(SCROLLBAR_ATTRS.owner, SCROLLBAR_OWNERS.react);
+  return true;
+};
+/** 자기가 붙인 표식만 뗀다. CDN 인스턴스가 살아 있는 표식을 훅이 떼면 양쪽이 모두 어긋난다 */
+const releaseMarkers = el => {
+  if (el.getAttribute(SCROLLBAR_ATTRS.owner) !== SCROLLBAR_OWNERS.react) return;
+  el.removeAttribute(SCROLLBAR_ATTRS.ready);
+  el.removeAttribute(SCROLLBAR_ATTRS.owner);
 };
 export const useTableVerticalScrollbar = _ref => {
   let {
@@ -72,27 +28,40 @@ export const useTableVerticalScrollbar = _ref => {
     scrollbarRef,
     thumbRef
   } = _ref;
-  // biome-ignore lint/correctness/useExhaustiveDependencies: layoutKey는 직접 참조하지 않지만 horizontalScroll 토글로 스크롤바 DOM이 리마운트될 때 effect를 재바인딩하기 위한 트리거로 의도적으로 포함한다.
-  useEffect(() => {
+  const releaseRef = useRef(null);
+  // 표식을 페인트 전에 붙여야 스크롤바가 한 프레임 늦게 나타나지 않는다.
+  // layoutKey 는 직접 참조하지 않지만, horizontalScroll 토글로 스크롤바 DOM 이 리마운트될 때
+  // effect 를 재바인딩하기 위한 트리거로 의존성 배열에 넣는다.
+  useIsomorphicLayoutEffect(() => {
     if (!enabled) return;
     const scrollEl = scrollContainerRef.current;
     const thumbEl = thumbRef.current;
     if (!scrollEl || !thumbEl) return;
+    // 소유자 표식이 있어야 CDN 자동 초기화가 이 테이블을 건드리지 않는다.
+    // 선점 실패 시 리스너·옵저버 등록 전에 빠져야 이중 구동이 생기지 않는다.
+    if (!claimMarkers(scrollEl)) return;
+    const controller = new AbortController();
+    releaseRef.current = controller;
     const update = () => {
       const {
         scrollTop,
         scrollHeight,
         clientHeight
       } = scrollEl;
-      if (scrollHeight <= clientHeight) {
+      const trackSize = scrollbarRef.current?.clientHeight || (scrollAreaRef.current?.clientHeight ?? clientHeight) - TABLE_HEADER_HEIGHT - SCROLLBAR_TRACK_OFFSET;
+      const geometry = computeThumbGeometry({
+        scrollOffset: scrollTop,
+        scrollSize: scrollHeight,
+        clientSize: clientHeight,
+        trackSize,
+        thumbMinSize: SCROLLBAR_THUMB_MIN_HEIGHT
+      });
+      if (!geometry.visible) {
         thumbEl.style.height = '0';
         return;
       }
-      const trackHeight = scrollbarRef.current?.clientHeight || (scrollAreaRef.current?.clientHeight ?? clientHeight) - TABLE_HEADER_HEIGHT - SCROLLBAR_TRACK_OFFSET;
-      const thumbHeight = Math.max(SCROLLBAR_THUMB_MIN_HEIGHT, clientHeight / scrollHeight * trackHeight);
-      const thumbTop = scrollTop / (scrollHeight - clientHeight) * (trackHeight - thumbHeight);
-      thumbEl.style.height = `${thumbHeight}px`;
-      thumbEl.style.transform = `translateY(${thumbTop}px)`;
+      thumbEl.style.height = `${geometry.size}px`;
+      thumbEl.style.transform = `translateY(${geometry.offset}px)`;
     };
     scrollEl.addEventListener('scroll', update, {
       passive: true
@@ -101,10 +70,16 @@ export const useTableVerticalScrollbar = _ref => {
     observer.observe(scrollEl);
     if (scrollAreaRef.current) observer.observe(scrollAreaRef.current);
     if (scrollbarRef.current) observer.observe(scrollbarRef.current);
+    // 컨테이너는 maxHeight 로 고정되므로 콘텐츠 루트까지 관찰해야 행 추가가 통지된다.
+    const contentEl = scrollEl.querySelector('.ncua-table__table');
+    if (contentEl) observer.observe(contentEl);
     update();
     return () => {
       scrollEl.removeEventListener('scroll', update);
       observer.disconnect();
+      controller.abort();
+      releaseRef.current = null;
+      releaseMarkers(scrollEl);
     };
   }, [enabled, layoutKey, scrollContainerRef, scrollAreaRef, scrollbarRef, thumbRef]);
   const handleThumbMouseDown = e => {
@@ -112,11 +87,13 @@ export const useTableVerticalScrollbar = _ref => {
     const thumbEl = thumbRef.current;
     const areaEl = scrollAreaRef.current;
     if (!scrollEl || !thumbEl) return;
-    startDrag(e, {
+    startThumbDrag(e, {
       axis: 'y',
       scrollEl,
       thumbEl,
-      draggingTarget: areaEl ?? scrollEl
+      draggingTarget: areaEl ?? scrollEl,
+      measureDragBasisSize: clientSize => clientSize,
+      releaseSignal: releaseRef.current?.signal
     });
   };
   return {
@@ -130,51 +107,73 @@ export const useTableHorizontalScrollbar = _ref2 => {
     hScrollbarRef,
     hThumbRef
   } = _ref2;
-  useEffect(() => {
+  const releaseRef = useRef(null);
+  useIsomorphicLayoutEffect(() => {
     if (!enabled) return;
     const hScrollEl = hScrollContainerRef.current;
     const hScrollbarEl = hScrollbarRef.current;
     const hThumbEl = hThumbRef.current;
     if (!hScrollEl || !hScrollbarEl || !hThumbEl) return;
+    if (!claimMarkers(hScrollEl)) return;
+    const controller = new AbortController();
+    releaseRef.current = controller;
     const update = () => {
       const {
         scrollLeft,
         scrollWidth,
         clientWidth
       } = hScrollEl;
-      if (scrollWidth <= clientWidth) {
+      const box = computeHorizontalTrackBox({
+        clientWidth,
+        scrollLeft,
+        sideGap: H_SCROLLBAR_SIDE_GAP
+      });
+      const geometry = computeThumbGeometry({
+        scrollOffset: scrollLeft,
+        scrollSize: scrollWidth,
+        clientSize: clientWidth,
+        trackSize: box.width,
+        thumbMinSize: H_SCROLLBAR_THUMB_MIN_WIDTH
+      });
+      if (!geometry.visible) {
         hThumbEl.style.width = '0';
         return;
       }
-      // transform으로 스크롤 오프셋 보정 — reflow 없이 compositor-only 이동
-      hScrollbarEl.style.transform = `translateX(${scrollLeft}px)`;
-      hScrollbarEl.style.width = `${clientWidth - H_SCROLLBAR_SIDE_GAP * 2}px`;
-      const trackWidth = clientWidth - H_SCROLLBAR_SIDE_GAP * 2;
-      const thumbWidth = Math.max(H_SCROLLBAR_THUMB_MIN_WIDTH, clientWidth / scrollWidth * trackWidth);
-      const thumbLeft = scrollLeft / (scrollWidth - clientWidth) * (trackWidth - thumbWidth);
-      hThumbEl.style.width = `${thumbWidth}px`;
-      hThumbEl.style.transform = `translateX(${thumbLeft}px)`;
+      hScrollbarEl.style.transform = `translateX(${box.translateX}px)`;
+      hScrollbarEl.style.width = `${box.width}px`;
+      hThumbEl.style.width = `${geometry.size}px`;
+      hThumbEl.style.transform = `translateX(${geometry.offset}px)`;
     };
     hScrollEl.addEventListener('scroll', update, {
       passive: true
     });
     const ro = new ResizeObserver(update);
     ro.observe(hScrollEl);
+    // 컨테이너 폭이 그대로인 채 콘텐츠 폭만 변하는 경우를 포착한다.
+    const innerEl = hScrollEl.querySelector('.ncua-table__h-scroll-inner');
+    if (innerEl) ro.observe(innerEl);
+    const contentEl = hScrollEl.querySelector('.ncua-table__table');
+    if (contentEl) ro.observe(contentEl);
     update();
     return () => {
       hScrollEl.removeEventListener('scroll', update);
       ro.disconnect();
+      controller.abort();
+      releaseRef.current = null;
+      releaseMarkers(hScrollEl);
     };
   }, [enabled, hScrollContainerRef, hScrollbarRef, hThumbRef]);
   const handleHThumbMouseDown = e => {
     const hScrollEl = hScrollContainerRef.current;
     const hThumbEl = hThumbRef.current;
     if (!hScrollEl || !hThumbEl) return;
-    startDrag(e, {
+    startThumbDrag(e, {
       axis: 'x',
       scrollEl: hScrollEl,
       thumbEl: hThumbEl,
-      sideGap: H_SCROLLBAR_SIDE_GAP
+      draggingTarget: hScrollEl,
+      measureDragBasisSize: clientSize => clientSize - H_SCROLLBAR_SIDE_GAP * 2,
+      releaseSignal: releaseRef.current?.signal
     });
   };
   return {