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

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

@@ -0,0 +1,244 @@
+// @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 = ({ enabled = true }) => {
+    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 createElement('div', { className: 'ncua-table ncua-table--fixed-header' }, createElement('div', { ref: scrollAreaRef, className: 'ncua-table__scroll-area' }, createElement('div', { ref: scrollContainerRef, className: 'ncua-table__scroll-container' }, createElement('table', { className: 'ncua-table__table' }, createElement('tbody', null))), createElement('div', { ref: scrollbarRef, className: 'ncua-table__scrollbar' }, 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 createElement('div', { className: 'ncua-table' }, createElement('div', { ref: hScrollContainerRef, className: 'ncua-table__h-scroll-container' }, createElement('div', { className: 'ncua-table__h-scroll-inner' }, createElement('table', { className: 'ncua-table__table' }, createElement('tbody', null))), createElement('div', { ref: hScrollbarRef, className: 'ncua-table__h-scrollbar' }, 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(createElement(VerticalHarness));
+        expect(query('.ncua-table__scroll-container').hasAttribute(SCROLLBAR_ATTRS.ready)).toBe(true);
+    });
+    it('표식을 layout effect 에서 부착해 페인트 전에 반영한다', () => {
+        render(createElement(VerticalHarness));
+        expect(probe.markerAtPassiveEffect).toBe(true);
+    });
+    it('소유자 표식(react)을 함께 부착한다', () => {
+        render(createElement(VerticalHarness));
+        expect(query('.ncua-table__scroll-container').getAttribute(SCROLLBAR_ATTRS.owner)).toBe(SCROLLBAR_OWNERS.react);
+    });
+    it('언마운트 시 표식과 소유자 표식을 모두 제거한다', () => {
+        render(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(createElement(HorizontalHarness));
+        expect(query('.ncua-table__h-scroll-container').hasAttribute(SCROLLBAR_ATTRS.ready)).toBe(true);
+    });
+    it('타 소유자가 선점한 컨테이너는 덮어쓰지 않고 바인딩도 하지 않는다', () => {
+        render(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(createElement(VerticalHarness, { enabled: true }));
+        expect(scrollEl.getAttribute(SCROLLBAR_ATTRS.owner)).toBe(SCROLLBAR_OWNERS.cdn);
+        expect(observers).toHaveLength(0);
+    });
+    it('타 소유자가 선점한 표식은 언마운트에서도 제거하지 않는다', () => {
+        render(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(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(createElement(VerticalHarness));
+        expect(observers[0]?.targets).toContain(query('.ncua-table__table'));
+    });
+    it('컨테이너 치수 불변 + 콘텐츠 증가 통지에 썸 높이를 재산출한다', () => {
+        render(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(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(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(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(([name]) => name === SCROLLBAR_ATTRS.dragging);
+        expect(draggingRemovals).toHaveLength(0);
+        act(() => {
+            root = createRoot(container);
+        });
+    });
+    it('언마운트가 드래그보다 먼저 일어나도 document 리스너가 남지 않는다', () => {
+        render(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/temp/src/components/data-display/table/useTableScrollbars.d.ts

@@ -1,9 +1,6 @@
 import { type MouseEvent, type RefObject } from 'react';
-export declare const TABLE_HEADER_HEIGHT = 40;
-export declare const SCROLLBAR_THUMB_MIN_HEIGHT = 40;
-export declare const H_SCROLLBAR_THUMB_MIN_WIDTH = 40;
-export declare const H_SCROLLBAR_SIDE_GAP = 8;
-export declare const SCROLLBAR_TRACK_OFFSET = 16;
+import { H_SCROLLBAR_SIDE_GAP, H_SCROLLBAR_THUMB_MIN_WIDTH, SCROLLBAR_THUMB_MIN_HEIGHT, SCROLLBAR_TRACK_OFFSET, TABLE_HEADER_HEIGHT } from '../../../../assets/scripts/table/scrollbar/const';
+export { H_SCROLLBAR_SIDE_GAP, H_SCROLLBAR_THUMB_MIN_WIDTH, SCROLLBAR_THUMB_MIN_HEIGHT, SCROLLBAR_TRACK_OFFSET, TABLE_HEADER_HEIGHT, };
 type VerticalScrollbarOptions = {
     enabled: boolean;
     layoutKey: unknown;
@@ -24,4 +21,3 @@ type HorizontalScrollbarOptions = {
 export declare const useTableHorizontalScrollbar: ({ enabled, hScrollContainerRef, hScrollbarRef, hThumbRef, }: HorizontalScrollbarOptions) => {
     handleHThumbMouseDown: (e: MouseEvent<HTMLDivElement>) => void;
 };
-export {};

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

@@ -1,77 +1,61 @@
-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);
+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;
-    }
-    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);
+    el.removeAttribute(SCROLLBAR_ATTRS.ready);
+    el.removeAttribute(SCROLLBAR_ATTRS.owner);
 };
 export const useTableVerticalScrollbar = ({ enabled, layoutKey, scrollContainerRef, scrollAreaRef, scrollbarRef, thumbRef, }) => {
-    // 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 });
         const observer = new ResizeObserver(update);
@@ -80,10 +64,17 @@ export const useTableVerticalScrollbar = ({ enabled, layoutKey, scrollContainerR
             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) => {
@@ -92,12 +83,20 @@ export const useTableVerticalScrollbar = ({ enabled, layoutKey, scrollContainerR
         const areaEl = scrollAreaRef.current;
         if (!scrollEl || !thumbEl)
             return;
-        startDrag(e, { axis: 'y', scrollEl, thumbEl, draggingTarget: areaEl ?? scrollEl });
+        startThumbDrag(e, {
+            axis: 'y',
+            scrollEl,
+            thumbEl,
+            draggingTarget: areaEl ?? scrollEl,
+            measureDragBasisSize: (clientSize) => clientSize,
+            releaseSignal: releaseRef.current?.signal,
+        });
     };
     return { handleThumbMouseDown };
 };
 export const useTableHorizontalScrollbar = ({ enabled, hScrollContainerRef, hScrollbarRef, hThumbRef, }) => {
-    useEffect(() => {
+    const releaseRef = useRef(null);
+    useIsomorphicLayoutEffect(() => {
         if (!enabled)
             return;
         const hScrollEl = hScrollContainerRef.current;
@@ -105,28 +104,50 @@ export const useTableHorizontalScrollbar = ({ enabled, hScrollContainerRef, hScr
         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) => {
@@ -134,7 +155,14 @@ export const useTableHorizontalScrollbar = ({ enabled, hScrollContainerRef, hScr
         const hThumbEl = hThumbRef.current;
         if (!hScrollEl || !hThumbEl)
             return;
-        startDrag(e, { axis: 'x', scrollEl: hScrollEl, thumbEl: hThumbEl, sideGap: H_SCROLLBAR_SIDE_GAP });
+        startThumbDrag(e, {
+            axis: 'x',
+            scrollEl: hScrollEl,
+            thumbEl: hThumbEl,
+            draggingTarget: hScrollEl,
+            measureDragBasisSize: (clientSize) => clientSize - H_SCROLLBAR_SIDE_GAP * 2,
+            releaseSignal: releaseRef.current?.signal,
+        });
     };
     return { handleHThumbMouseDown };
 };