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

package/dist/cjs/assets/scripts/table/scrollbar/const.js

@@ -0,0 +1,50 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.TABLE_HEADER_HEIGHT = exports.SCROLLBAR_TRACK_OFFSET = exports.SCROLLBAR_THUMB_MIN_HEIGHT = exports.SCROLLBAR_OWNER_VALUES = exports.SCROLLBAR_OWNERS = exports.SCROLLBAR_CLASS_NAMES = exports.SCROLLBAR_ATTRS = exports.OPT_OUT_VALUE = exports.LOG_PREFIX = exports.H_SCROLLBAR_THUMB_MIN_WIDTH = exports.H_SCROLLBAR_SIDE_GAP = exports.DEFAULT_AXIS = exports.AXIS_VALUES = void 0;
+/** Table 커스텀 스크롤바의 클래스명·속성명·수치 상수. React 와 CDN 이 함께 참조한다. */
+/** `_table.scss` 의 `--ncua-table-header-height` 와 같은 값 */
+const TABLE_HEADER_HEIGHT = exports.TABLE_HEADER_HEIGHT = 40;
+/** `.ncua-table__scrollbar-thumb { height }` 와 같은 값 */
+const SCROLLBAR_THUMB_MIN_HEIGHT = exports.SCROLLBAR_THUMB_MIN_HEIGHT = 40;
+/** `.ncua-table__h-scrollbar-thumb { width }` 와 같은 값 */
+const H_SCROLLBAR_THUMB_MIN_WIDTH = exports.H_SCROLLBAR_THUMB_MIN_WIDTH = 40;
+/** `.ncua-table__h-scrollbar { left/right: var(--spacing-s) }` 와 같은 값 */
+const H_SCROLLBAR_SIDE_GAP = exports.H_SCROLLBAR_SIDE_GAP = 8;
+/** 세로 트랙 상하 여백 합계. 헤더 회피분은 `TABLE_HEADER_HEIGHT` 로 따로 뺀다 */
+const SCROLLBAR_TRACK_OFFSET = exports.SCROLLBAR_TRACK_OFFSET = 16;
+const SCROLLBAR_CLASS_NAMES = exports.SCROLLBAR_CLASS_NAMES = {
+  table: 'ncua-table',
+  tableWrapper: 'ncua-table-wrapper',
+  dataGrid: 'ncua-data-grid',
+  scrollArea: 'ncua-table__scroll-area',
+  scrollContainer: 'ncua-table__scroll-container',
+  scrollbar: 'ncua-table__scrollbar',
+  scrollbarThumb: 'ncua-table__scrollbar-thumb',
+  hScrollContainer: 'ncua-table__h-scroll-container',
+  hScrollInner: 'ncua-table__h-scroll-inner',
+  hScrollbar: 'ncua-table__h-scrollbar',
+  hScrollbarThumb: 'ncua-table__h-scrollbar-thumb',
+  tableElement: 'ncua-table__table'
+};
+/** `optOut` 을 제외한 전부가 런타임에만 부착된다. 마크업에 직접 기재하지 않는다. */
+const SCROLLBAR_ATTRS = exports.SCROLLBAR_ATTRS = {
+  ready: 'data-scrollbar-ready',
+  /** `ready` 와 항상 함께 부착·제거한다 */
+  owner: 'data-scrollbar-owner',
+  generated: 'data-scrollbar-generated',
+  fallbackArmed: 'data-ncua-scrollbar-fallback',
+  dragging: 'data-dragging',
+  optOut: 'data-ncua-scrollbar'
+};
+const SCROLLBAR_OWNERS = exports.SCROLLBAR_OWNERS = {
+  cdn: 'cdn',
+  react: 'react'
+};
+const SCROLLBAR_OWNER_VALUES = exports.SCROLLBAR_OWNER_VALUES = Object.values(SCROLLBAR_OWNERS);
+const OPT_OUT_VALUE = exports.OPT_OUT_VALUE = 'off';
+const AXIS_VALUES = exports.AXIS_VALUES = ['both', 'x', 'y'];
+const DEFAULT_AXIS = exports.DEFAULT_AXIS = 'both';
+const LOG_PREFIX = exports.LOG_PREFIX = '[ncua.TableScrollbar]';

package/dist/cjs/assets/scripts/table/scrollbar/drag.js

@@ -0,0 +1,75 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.startThumbDrag = void 0;
+var _const = require("./const");
+var _geometry = require("./geometry");
+var _isolate = require("./isolate");
+/**
+ * 썸 드래그 와이어링. React 훅과 CDN 바인딩이 공유한다.
+ * 모듈 평가 시점에는 `document`·`window` 를 참조하지 않는다 — SSR 경로에서 함께 평가된다.
+ */
+
+const startThumbDrag = (event, input) => {
+  const {
+    axis,
+    scrollEl,
+    thumbEl,
+    draggingTarget,
+    measureDragBasisSize,
+    releaseSignal
+  } = input;
+  event.preventDefault();
+  const isVertical = axis === 'y';
+  // 측정을 속성 부착보다 앞에 둔다. 부착이 스타일을 무효화한 뒤 읽으면 강제 재계산이 1회 붙는다.
+  const startPointer = isVertical ? event.clientY : event.clientX;
+  const startOffset = isVertical ? scrollEl.scrollTop : scrollEl.scrollLeft;
+  const scrollSize = isVertical ? scrollEl.scrollHeight : scrollEl.scrollWidth;
+  const clientSize = isVertical ? scrollEl.clientHeight : scrollEl.clientWidth;
+  const thumbSize = isVertical ? thumbEl.offsetHeight : thumbEl.offsetWidth;
+  const dragBasisSize = measureDragBasisSize(clientSize);
+  draggingTarget.setAttribute(_const.SCROLLBAR_ATTRS.dragging, '');
+  const dragController = new AbortController();
+  const dragSignal = dragController.signal;
+  // 리스너 해제를 먼저 끝낸다. 뒤 문장이 실패해도 드래그가 계속 붙어 있지 않게 한다.
+  const endDrag = (0, _isolate.isolate)('드래그 종료', () => {
+    dragController.abort();
+    draggingTarget.removeAttribute(_const.SCROLLBAR_ATTRS.dragging);
+  });
+  const onMove = (0, _isolate.isolate)('드래그 이동', moveEvent => {
+    const delta = (0, _geometry.computeDragScrollDelta)({
+      pointerDelta: (isVertical ? moveEvent.clientY : moveEvent.clientX) - startPointer,
+      scrollSize,
+      clientSize,
+      dragBasisSize,
+      thumbSize
+    });
+    if (isVertical) {
+      scrollEl.scrollTop = startOffset + delta;
+      return;
+    }
+    scrollEl.scrollLeft = startOffset + delta;
+  });
+  document.addEventListener('mousemove', onMove, {
+    signal: dragSignal
+  });
+  document.addEventListener('mouseup', endDrag, {
+    signal: dragSignal
+  });
+  // 창 밖 릴리즈·탭 전환으로 mouseup 을 놓치는 경우가 상시 발생한다.
+  document.addEventListener('pointercancel', endDrag, {
+    signal: dragSignal
+  });
+  window.addEventListener('blur', endDrag, {
+    signal: dragSignal
+  });
+  // `dragSignal` 을 함께 넘기지 않으면 정상 종료한 드래그의 리스너가 해제 신호에 남아
+  // 반복할수록 누적된다.
+  releaseSignal?.addEventListener('abort', endDrag, {
+    once: true,
+    signal: dragSignal
+  });
+};
+exports.startThumbDrag = startThumbDrag;

package/dist/cjs/assets/scripts/table/scrollbar/geometry.js

@@ -0,0 +1,69 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.computeThumbGeometry = exports.computeHorizontalTrackBox = exports.computeDragScrollDelta = exports.DRAG_BASIS = void 0;
+/**
+ * 썸 치수·위치 산출. React 훅과 CDN 바인딩이 공유한다.
+ * SSR 경로에서도 평가되므로 `document`·`window` 를 참조하지 않는다.
+ */
+const HIDDEN = {
+  visible: false,
+  size: 0,
+  offset: 0
+};
+const clamp = (value, min, max) => Math.min(Math.max(value, min), max);
+const computeThumbGeometry = metrics => {
+  const {
+    scrollOffset,
+    scrollSize,
+    clientSize,
+    trackSize,
+    thumbMinSize
+  } = metrics;
+  if (!(scrollSize > clientSize)) return HIDDEN;
+  if (!(trackSize > 0)) return HIDDEN;
+  const size = Math.min(trackSize, Math.max(thumbMinSize, clientSize / scrollSize * trackSize));
+  const travel = trackSize - size;
+  if (travel <= 0) return {
+    visible: true,
+    size,
+    offset: 0
+  };
+  const offset = clamp(scrollOffset / (scrollSize - clientSize) * travel, 0, travel);
+  return {
+    visible: true,
+    size,
+    offset
+  };
+};
+/** 호출자가 넘겨야 하는 축별 `dragBasisSize` 기준 */
+exports.computeThumbGeometry = computeThumbGeometry;
+const DRAG_BASIS = exports.DRAG_BASIS = {
+  y: 'clientSize',
+  x: 'trackSize'
+};
+/**
+ * 포인터 이동량(px) → 스크롤 오프셋 변화량(px).
+ * 환산 분모 기준이 축마다 다르므로 `dragBasisSize` 는 호출자가 `DRAG_BASIS` 대로 넘긴다.
+ */
+const computeDragScrollDelta = input => {
+  const {
+    pointerDelta,
+    scrollSize,
+    clientSize,
+    dragBasisSize,
+    thumbSize
+  } = input;
+  const denominator = dragBasisSize - thumbSize;
+  if (denominator <= 0) return 0;
+  return pointerDelta * ((scrollSize - clientSize) / denominator);
+};
+/** 가로 트랙은 스크롤 컨테이너 안에 있어 함께 밀리므로, 되돌릴 오프셋과 폭을 산출한다. */
+exports.computeDragScrollDelta = computeDragScrollDelta;
+const computeHorizontalTrackBox = input => ({
+  translateX: input.scrollLeft,
+  width: Math.max(0, input.clientWidth - input.sideGap * 2)
+});
+exports.computeHorizontalTrackBox = computeHorizontalTrackBox;

package/dist/cjs/assets/scripts/table/scrollbar/isolate.js

@@ -0,0 +1,36 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.runIsolated = exports.isolate = void 0;
+var _const = require("./const");
+/**
+ * 라이브러리가 스스로 부르는 콜백(리스너·옵저버·정리 루프)을 감싼다.
+ * 소비처 페이지로 예외가 새면 그 페이지의 전역 오류 처리기가 발화하므로 여기서 가둔다.
+ * 생성자처럼 호출자가 결과를 판정해야 하는 경로에는 쓰지 않는다.
+ */
+
+/** 스크롤·리사이즈는 초당 수십 회 불리므로 같은 지점의 실패는 1회만 기록한다 */
+const isolate = (label, run) => {
+  let reported = false;
+  return function () {
+    try {
+      run(...arguments);
+    } catch (error) {
+      if (reported) return;
+      reported = true;
+      console.error(`${_const.LOG_PREFIX} ${label} 중 오류가 발생했습니다. 이후 같은 오류는 기록을 생략합니다.`, error);
+    }
+  };
+};
+/** 1회성 호출용. 실패해도 나머지 정리·순회가 이어지도록 한다 */
+exports.isolate = isolate;
+const runIsolated = (label, run) => {
+  try {
+    run();
+  } catch (error) {
+    console.error(`${_const.LOG_PREFIX} ${label} 중 오류가 발생했습니다.`, error);
+  }
+};
+exports.runIsolated = runIsolated;

package/dist/cjs/src/components/data-display/table/Table.js

@@ -496,6 +496,7 @@ const TableComponent = /*#__PURE__*/(0, _react.forwardRef)((_ref17, ref) => {
     footerContent,
     paginationContent
   } = sortChildren(children);
+  // maxHeight 를 본문 영역 높이로 해석해 헤더 높이를 가산한다.
   const scrollStyle = fixedHeader && maxHeight ? {
     maxHeight: typeof maxHeight === 'number' ? `${maxHeight + _useTableScrollbars.TABLE_HEADER_HEIGHT}px` : `calc(${maxHeight} + ${_useTableScrollbars.TABLE_HEADER_HEIGHT}px)`
   } : undefined;

package/dist/cjs/src/components/data-display/table/__tests__/useTableScrollbars.characterisation.test.js

@@ -0,0 +1,390 @@
+"use strict";
+
+var _react = require("react");
+var _client = require("react-dom/client");
+var _testUtils = require("react-dom/test-utils");
+var _vitest = require("vitest");
+var _useTableScrollbars = require("../useTableScrollbars");
+// @vitest-environment jsdom
+/**
+ * 특성화 테스트. 기대값은 "이래야 한다"가 아니라 "현재 이렇게 동작한다"이며,
+ * 산출 로직을 CDN 과 공유한 뒤에도 같은 값이 나오는지 판정하는 기준선이다.
+ */
+
+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;
+  }
+}
+/** jsdom 은 레이아웃을 계산하지 않으므로 측정 속성을 직접 정의한다. */
+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 render = element => {
+  (0, _testUtils.act)(() => {
+    root.render(element);
+  });
+};
+const VerticalHarness = _ref => {
+  let {
+    enabled = true
+  } = _ref;
+  const scrollContainerRef = (0, _react.useRef)(null);
+  const scrollAreaRef = (0, _react.useRef)(null);
+  const scrollbarRef = (0, _react.useRef)(null);
+  const thumbRef = (0, _react.useRef)(null);
+  const {
+    handleThumbMouseDown
+  } = (0, _useTableScrollbars.useTableVerticalScrollbar)({
+    enabled,
+    layoutKey: false,
+    scrollContainerRef,
+    scrollAreaRef,
+    scrollbarRef,
+    thumbRef
+  });
+  return /*#__PURE__*/(0, _react.createElement)('div', {
+    className: 'ncua-table ncua-table--horizontal ncua-table--fixed-header'
+  }, /*#__PURE__*/(0, _react.createElement)('div', {
+    ref: scrollAreaRef,
+    className: 'ncua-table__scroll-area'
+  }, /*#__PURE__*/(0, _react.createElement)('div', {
+    ref: scrollContainerRef,
+    className: 'ncua-table__scroll-container'
+  }, /*#__PURE__*/(0, _react.createElement)('table', {
+    className: 'ncua-table__table'
+  }, /*#__PURE__*/(0, _react.createElement)('tbody', null))), /*#__PURE__*/(0, _react.createElement)('div', {
+    ref: scrollbarRef,
+    className: 'ncua-table__scrollbar',
+    'aria-hidden': true
+  }, /*#__PURE__*/(0, _react.createElement)('div', {
+    ref: thumbRef,
+    className: 'ncua-table__scrollbar-thumb',
+    onMouseDown: handleThumbMouseDown
+  }))));
+};
+const HorizontalHarness = _ref2 => {
+  let {
+    enabled = true
+  } = _ref2;
+  const hScrollContainerRef = (0, _react.useRef)(null);
+  const hScrollbarRef = (0, _react.useRef)(null);
+  const hThumbRef = (0, _react.useRef)(null);
+  const {
+    handleHThumbMouseDown
+  } = (0, _useTableScrollbars.useTableHorizontalScrollbar)({
+    enabled,
+    hScrollContainerRef,
+    hScrollbarRef,
+    hThumbRef
+  });
+  return /*#__PURE__*/(0, _react.createElement)('div', {
+    className: 'ncua-table ncua-table--horizontal'
+  }, /*#__PURE__*/(0, _react.createElement)('div', {
+    ref: hScrollContainerRef,
+    className: 'ncua-table__h-scroll-container'
+  }, /*#__PURE__*/(0, _react.createElement)('div', {
+    className: 'ncua-table__h-scroll-inner'
+  }, /*#__PURE__*/(0, _react.createElement)('table', {
+    className: 'ncua-table__table'
+  }, /*#__PURE__*/(0, _react.createElement)('tbody', null))), /*#__PURE__*/(0, _react.createElement)('div', {
+    ref: hScrollbarRef,
+    className: 'ncua-table__h-scrollbar',
+    'aria-hidden': true
+  }, /*#__PURE__*/(0, _react.createElement)('div', {
+    ref: hThumbRef,
+    className: 'ncua-table__h-scrollbar-thumb',
+    onMouseDown: handleHThumbMouseDown
+  }))));
+};
+const query = selector => {
+  const found = container.querySelector(selector);
+  if (!found) throw new Error(`선택자에 해당하는 요소가 없습니다: ${selector}`);
+  return found;
+};
+const fireScroll = element => {
+  (0, _testUtils.act)(() => {
+    element.dispatchEvent(new Event('scroll'));
+  });
+};
+(0, _vitest.beforeEach)(() => {
+  _vitest.vi.stubGlobal('ResizeObserver', ResizeObserverStub);
+  observers.length = 0;
+  container = document.createElement('div');
+  document.body.appendChild(container);
+  (0, _testUtils.act)(() => {
+    root = (0, _client.createRoot)(container);
+  });
+});
+(0, _vitest.afterEach)(() => {
+  (0, _testUtils.act)(() => {
+    root.unmount();
+  });
+  container.remove();
+  _vitest.vi.unstubAllGlobals();
+  _vitest.vi.restoreAllMocks();
+});
+/**
+ * 가상 레이아웃 수치. 기대값은 구현 상수를 쓰지 않고 리터럴로 적는다 —
+ * 상수를 참조하면 값이 바뀔 때 기대값도 함께 움직여 수치 회귀를 놓친다.
+ */
+const LAYOUT = {
+  viewportHeight: 200,
+  contentHeight: 800,
+  shortContentHeight: 400,
+  trackHeight: 150,
+  thumbHeight: 40,
+  scrollTop: 300,
+  areaHeight: 240,
+  viewportWidth: 600,
+  contentWidth: 1500,
+  thumbWidth: 234,
+  scrollLeft: 120,
+  pointerDelta: 10
+};
+/** toBeCloseTo 자릿수 */
+const PRECISION = 5;
+/** (1500 - 600) / (584 - 234) 비율로 10px 을 끌었을 때의 scrollLeft */
+const EXPECTED_HORIZONTAL_SCROLL_LEFT = 25.714285;
+(0, _vitest.describe)('useTableVerticalScrollbar', () => {
+  const setUpOverflow = () => {
+    render(/*#__PURE__*/(0, _react.createElement)(VerticalHarness));
+    const scrollEl = query('.ncua-table__scroll-container');
+    const thumbEl = query('.ncua-table__scrollbar-thumb');
+    const trackEl = query('.ncua-table__scrollbar');
+    defineMetrics(scrollEl, {
+      clientHeight: LAYOUT.viewportHeight,
+      scrollHeight: LAYOUT.contentHeight,
+      scrollTop: 0
+    });
+    defineMetrics(trackEl, {
+      clientHeight: LAYOUT.trackHeight
+    });
+    return {
+      scrollEl,
+      thumbEl
+    };
+  };
+  (0, _vitest.it)('오버플로 발생 시 트랙 길이 기준으로 썸 높이를 산출한다', () => {
+    const {
+      scrollEl,
+      thumbEl
+    } = setUpOverflow();
+    fireScroll(scrollEl);
+    // max(40, (200 / 800) * 150) = max(40, 37.5) = 40
+    (0, _vitest.expect)(thumbEl.style.height).toBe('40px');
+    (0, _vitest.expect)(thumbEl.style.transform).toBe('translateY(0px)');
+  });
+  (0, _vitest.it)('스크롤 오프셋에 비례해 썸을 이동시킨다', () => {
+    const {
+      scrollEl,
+      thumbEl
+    } = setUpOverflow();
+    defineMetrics(scrollEl, {
+      scrollTop: LAYOUT.scrollTop
+    });
+    fireScroll(scrollEl);
+    // (300 / (800 - 200)) * (150 - 40) = 0.5 * 110 = 55
+    (0, _vitest.expect)(thumbEl.style.transform).toBe('translateY(55px)');
+  });
+  (0, _vitest.it)('트랙 clientHeight 가 0 이면 scroll-area 높이에서 헤더·여백을 차감한 값을 트랙 길이로 쓴다', () => {
+    render(/*#__PURE__*/(0, _react.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: LAYOUT.viewportHeight,
+      scrollHeight: LAYOUT.shortContentHeight,
+      scrollTop: 0
+    });
+    defineMetrics(query('.ncua-table__scrollbar'), {
+      clientHeight: 0
+    });
+    defineMetrics(areaEl, {
+      clientHeight: LAYOUT.areaHeight
+    });
+    fireScroll(scrollEl);
+    // trackHeight = 240 - 40(헤더) - 16(상하 여백) = 184 → max(40, (200/400) * 184) = 92
+    (0, _vitest.expect)(thumbEl.style.height).toBe('92px');
+  });
+  (0, _vitest.it)('오버플로가 없으면 썸 높이를 0 으로 둔다', () => {
+    render(/*#__PURE__*/(0, _react.createElement)(VerticalHarness));
+    const scrollEl = query('.ncua-table__scroll-container');
+    const thumbEl = query('.ncua-table__scrollbar-thumb');
+    defineMetrics(scrollEl, {
+      clientHeight: LAYOUT.shortContentHeight,
+      scrollHeight: LAYOUT.shortContentHeight,
+      scrollTop: 0
+    });
+    fireScroll(scrollEl);
+    (0, _vitest.expect)(thumbEl.style.height).toBe('0px');
+  });
+  (0, _vitest.it)('썸 드래그는 (scrollHeight − clientHeight) / (clientHeight − thumbHeight) 비율로 환산한다', () => {
+    const {
+      scrollEl,
+      thumbEl
+    } = setUpOverflow();
+    defineMetrics(thumbEl, {
+      offsetHeight: 40
+    });
+    const areaEl = query('.ncua-table__scroll-area');
+    (0, _testUtils.act)(() => {
+      thumbEl.dispatchEvent(new MouseEvent('mousedown', {
+        bubbles: true,
+        clientY: 100
+      }));
+    });
+    (0, _vitest.expect)(areaEl.hasAttribute('data-dragging')).toBe(true);
+    (0, _testUtils.act)(() => {
+      document.dispatchEvent(new MouseEvent('mousemove', {
+        clientY: 110
+      }));
+    });
+    // ratio = (800 - 200) / (200 - 40) = 3.75 → 10px 이동 = 37.5
+    const verticalRatio = (LAYOUT.contentHeight - LAYOUT.viewportHeight) / (LAYOUT.viewportHeight - LAYOUT.thumbHeight);
+    (0, _vitest.expect)(scrollEl.scrollTop).toBe(LAYOUT.pointerDelta * verticalRatio);
+    (0, _testUtils.act)(() => {
+      document.dispatchEvent(new MouseEvent('mouseup'));
+    });
+    (0, _vitest.expect)(areaEl.hasAttribute('data-dragging')).toBe(false);
+  });
+  (0, _vitest.it)('mouseup 이후에는 포인터 이동이 스크롤에 반영되지 않는다', () => {
+    const {
+      scrollEl,
+      thumbEl
+    } = setUpOverflow();
+    defineMetrics(thumbEl, {
+      offsetHeight: 40
+    });
+    (0, _testUtils.act)(() => {
+      thumbEl.dispatchEvent(new MouseEvent('mousedown', {
+        bubbles: true,
+        clientY: 100
+      }));
+      document.dispatchEvent(new MouseEvent('mouseup'));
+      document.dispatchEvent(new MouseEvent('mousemove', {
+        clientY: 400
+      }));
+    });
+    (0, _vitest.expect)(scrollEl.scrollTop).toBe(0);
+  });
+  (0, _vitest.it)('enabled 가 false 이면 바인딩하지 않는다', () => {
+    render(/*#__PURE__*/(0, _react.createElement)(VerticalHarness, {
+      enabled: false
+    }));
+    (0, _vitest.expect)(observers).toHaveLength(0);
+  });
+  (0, _vitest.it)('언마운트 시 ResizeObserver 를 해제한다', () => {
+    render(/*#__PURE__*/(0, _react.createElement)(VerticalHarness));
+    (0, _testUtils.act)(() => {
+      root.unmount();
+    });
+    (0, _vitest.expect)(observers.every(observer => observer.disconnected)).toBe(true);
+    (0, _testUtils.act)(() => {
+      root = (0, _client.createRoot)(container);
+    });
+  });
+});
+(0, _vitest.describe)('useTableHorizontalScrollbar', () => {
+  const setUpOverflow = () => {
+    render(/*#__PURE__*/(0, _react.createElement)(HorizontalHarness));
+    const hScrollEl = query('.ncua-table__h-scroll-container');
+    const hThumbEl = query('.ncua-table__h-scrollbar-thumb');
+    const hTrackEl = query('.ncua-table__h-scrollbar');
+    defineMetrics(hScrollEl, {
+      clientWidth: LAYOUT.viewportWidth,
+      scrollWidth: LAYOUT.contentWidth,
+      scrollLeft: 0
+    });
+    return {
+      hScrollEl,
+      hThumbEl,
+      hTrackEl
+    };
+  };
+  (0, _vitest.it)('트랙 wrapper 를 스크롤 오프셋만큼 보정하고 좌우 여백을 차감한 폭으로 맞춘다', () => {
+    const {
+      hScrollEl,
+      hTrackEl
+    } = setUpOverflow();
+    defineMetrics(hScrollEl, {
+      scrollLeft: LAYOUT.scrollLeft
+    });
+    fireScroll(hScrollEl);
+    (0, _vitest.expect)(hTrackEl.style.transform).toBe('translateX(120px)');
+    // 600 - 8(좌) - 8(우) = 584
+    (0, _vitest.expect)(hTrackEl.style.width).toBe('584px');
+  });
+  (0, _vitest.it)('썸 폭은 트랙 유효 길이 기준으로 산출한다', () => {
+    const {
+      hScrollEl,
+      hThumbEl
+    } = setUpOverflow();
+    fireScroll(hScrollEl);
+    // trackWidth = 600 - 16 = 584 → max(40, (600 / 1500) * 584) = 233.6
+    (0, _vitest.expect)(hThumbEl.style.width).toBe('233.60000000000002px');
+    (0, _vitest.expect)(hThumbEl.style.transform).toBe('translateX(0px)');
+  });
+  (0, _vitest.it)('오버플로가 없으면 썸 폭을 0 으로 둔다', () => {
+    render(/*#__PURE__*/(0, _react.createElement)(HorizontalHarness));
+    const hScrollEl = query('.ncua-table__h-scroll-container');
+    const hThumbEl = query('.ncua-table__h-scrollbar-thumb');
+    defineMetrics(hScrollEl, {
+      clientWidth: LAYOUT.viewportWidth,
+      scrollWidth: LAYOUT.viewportWidth,
+      scrollLeft: 0
+    });
+    fireScroll(hScrollEl);
+    (0, _vitest.expect)(hThumbEl.style.width).toBe('0px');
+  });
+  (0, _vitest.it)('썸 드래그는 (scrollWidth − clientWidth) / (trackWidth − thumbWidth) 비율로 환산한다', () => {
+    const {
+      hScrollEl,
+      hThumbEl
+    } = setUpOverflow();
+    defineMetrics(hThumbEl, {
+      offsetWidth: LAYOUT.thumbWidth
+    });
+    (0, _testUtils.act)(() => {
+      hThumbEl.dispatchEvent(new MouseEvent('mousedown', {
+        bubbles: true,
+        clientX: 50
+      }));
+    });
+    (0, _vitest.expect)(hScrollEl.hasAttribute('data-dragging')).toBe(true);
+    (0, _testUtils.act)(() => {
+      document.dispatchEvent(new MouseEvent('mousemove', {
+        clientX: 60
+      }));
+    });
+    // ratio = (1500 - 600) / (584 - 234) = 900 / 350 → 10px 이동 = 25.714…
+    (0, _vitest.expect)(hScrollEl.scrollLeft).toBeCloseTo(EXPECTED_HORIZONTAL_SCROLL_LEFT, PRECISION);
+    (0, _testUtils.act)(() => {
+      document.dispatchEvent(new MouseEvent('mouseup'));
+    });
+    (0, _vitest.expect)(hScrollEl.hasAttribute('data-dragging')).toBe(false);
+  });
+});