@ncds/ui-admin 1.8.27 → 1.8.28-alpha.1

package/dist/esm/src/components/feedback-and-status/progress-bar/__tests__/ProgressBar.test.js

@@ -0,0 +1,274 @@
+// @vitest-environment jsdom
+//
+// ProgressBar (React) 위험 경로 — 위험 목록표 RPB-xx. SegmentBar·SegmentLabels 는 렌더 결과로 함께 덮는다.
+// vanilla ProgressBar.ts(PB-xx)와 같은 계약 — 같은 입력에 다른 결과면 결함 후보로 적는다.
+import { createElement } from 'react';
+import { createRoot } from 'react-dom/client';
+import { act } from 'react-dom/test-utils';
+import { afterEach, describe, expect, it } from 'vitest';
+import { ProgressBar } from '../ProgressBar';
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+const VALUE = 40;
+const SEG_A = 30;
+const SEG_B = 10;
+/** 30 : 10 → 75 : 25 로 정규화 */
+const NORMALIZED_A = 75;
+const NORMALIZED_B = 25;
+/** 라벨 위치 — 앞 폭 합 + 자기 폭 / 2 : 75 / 2 = 37.5, 75 + 25 / 2 = 87.5 */
+const CENTER_DIVISOR = 2;
+const FIRST_LABEL_LEFT = NORMALIZED_A / CENTER_DIVISOR;
+const SECOND_LABEL_LEFT = NORMALIZED_A + NORMALIZED_B / CENTER_DIVISOR;
+/** 세그먼트 1개 float 라벨 값 */
+const FLOAT_VALUE = 15;
+/** 0 세그먼트 라벨 시작점 — 앞 폭 합 − 1 (최소 0) */
+const ZERO_LABEL_OFFSET = 1;
+let root = null;
+let container = null;
+const renderElement = element => {
+  if (!container) {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  }
+  act(() => {
+    root?.render(element);
+  });
+  return container;
+};
+const render = function () {
+  let props = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+  return renderElement(/*#__PURE__*/createElement(ProgressBar, props));
+};
+afterEach(() => {
+  if (root) {
+    act(() => {
+      root?.unmount();
+    });
+  }
+  container?.remove();
+  root = null;
+  container = null;
+});
+const requireElement = (scope, selector) => {
+  const element = scope.querySelector(selector);
+  if (!element) throw new Error(`요소를 찾을 수 없습니다: ${selector}`);
+  return element;
+};
+const fillsOf = view => Array.from(view.querySelectorAll('.ncua-progress-bar__fill'));
+const segmentLabelsOf = view => Array.from(view.querySelectorAll('.ncua-progress-bar__label--segment'));
+// ── P0 ─────────────────────────────────────────────────
+describe('ProgressBar — 단일 value (RPB-01)', () => {
+  it('RPB-01 fill 하나의 width 와 aria-valuenow 가 같은 값이고 aria 범위는 0~100', () => {
+    const view = render({
+      value: VALUE
+    });
+    const [fill] = fillsOf(view);
+    expect(fillsOf(view)).toHaveLength(1);
+    expect([fill.style.width, fill.getAttribute('aria-valuenow'), fill.getAttribute('aria-valuemin'), fill.getAttribute('aria-valuemax')]).toEqual([`${VALUE}%`, String(VALUE), '0', '100']);
+  });
+});
+describe('ProgressBar — 다중 세그먼트 (RPB-02)', () => {
+  it('RPB-02 SegmentBar 가 세그먼트마다 정규화 width·first/last·색 클래스로 fill 을 만든다', () => {
+    const view = render({
+      segments: [{
+        value: SEG_A,
+        color: 'blue'
+      }, {
+        value: SEG_B,
+        color: 'red'
+      }]
+    });
+    const [first, last] = fillsOf(view);
+    expect(fillsOf(view).map(fill => fill.style.width)).toEqual([`${NORMALIZED_A}%`, `${NORMALIZED_B}%`]);
+    expect([first.classList.contains('ncua-progress-bar__fill--first'), first.classList.contains('ncua-progress-bar__fill--last'), first.classList.contains('ncua-progress-bar__fill--color-blue'), last.classList.contains('ncua-progress-bar__fill--last'), last.classList.contains('ncua-progress-bar__fill--color-red')]).toEqual([true, false, true, true, true]);
+    expect(requireElement(view, '.ncua-progress-bar__bar').classList.contains('ncua-progress-bar__bar--segments')).toBe(true);
+  });
+  it('RPB-02 SegmentLabels 가 세그먼트마다 정규화 값 라벨과 색 클래스를 렌더한다', () => {
+    const view = render({
+      segments: [{
+        value: SEG_A,
+        color: 'blue'
+      }, {
+        value: SEG_B,
+        color: 'red'
+      }]
+    });
+    const labels = segmentLabelsOf(view);
+    expect(labels.map(label => label.textContent)).toEqual([`${NORMALIZED_A}%`, `${NORMALIZED_B}%`]);
+    expect([labels[0].classList.contains('ncua-progress-bar__label--color-blue'), labels[1].classList.contains('ncua-progress-bar__label--color-red')]).toEqual([true, true]);
+    expect(requireElement(view, '.ncua-progress-bar').classList.contains('ncua-progress-bar-bottom')).toBe(true);
+  });
+});
+describe('ProgressBar — 세그먼트 1개 (RPB-03)', () => {
+  it('RPB-03 색 fill 하나에 width·aria-valuenow 를 넣고 right 라벨에 값을 표시한다', () => {
+    const view = render({
+      label: 'right',
+      segments: [{
+        value: SEG_A,
+        color: 'green'
+      }]
+    });
+    const [fill] = fillsOf(view);
+    expect(fillsOf(view)).toHaveLength(1);
+    expect([fill.style.width, fill.getAttribute('aria-valuenow')]).toEqual([`${SEG_A}%`, String(SEG_A)]);
+    expect(fill.classList.contains('ncua-progress-bar__fill--color-green')).toBe(true);
+    expect(requireElement(view, '.ncua-progress-bar__label-right').textContent).toBe(`${SEG_A}%`);
+  });
+  it.each([['bottom', '.ncua-progress-bar__label-bottom'], ['top-float', '.ncua-progress-bar__label-top-float'], ['bottom-float', '.ncua-progress-bar__label-bottom-float']])('RPB-03 label %s 이면 SingleLabel 을 그 위치에 렌더한다', (label, selector) => {
+    const view = render({
+      label,
+      segments: [{
+        value: SEG_A,
+        color: 'green'
+      }]
+    });
+    expect(requireElement(view, selector).textContent).toBe(`${SEG_A}%`);
+    expect(view.querySelectorAll('.ncua-progress-bar__label')).toHaveLength(1);
+  });
+  it('RPB-03 세그먼트 1개 + float 라벨이면 컨테이너에 --progress-value 스타일을 준다', () => {
+    const view = render({
+      label: 'top-float',
+      segments: [{
+        value: FLOAT_VALUE
+      }]
+    });
+    expect(requireElement(view, '.ncua-progress-bar').style.getPropertyValue('--progress-value')).toBe(`${FLOAT_VALUE}%`);
+  });
+});
+// ── P1 ~ P3 ────────────────────────────────────────────
+const containerOf = view => requireElement(view, '.ncua-progress-bar');
+/** 컨테이너 직계 자식의 마지막 클래스(위치 modifier) — 라벨이 content 안/밖·앞/뒤 어디 있는지 본다 */
+const childOrderOf = view => Array.from(containerOf(view).children).map(child => child.classList[child.classList.length - 1] ?? '');
+describe('ProgressBar — 라벨 배치 (RPB-04)', () => {
+  it('RPB-04 right 라벨은 content 안 막대 뒤에 있고 컨테이너 클래스는 ncua-progress-bar-right', () => {
+    const view = render({
+      label: 'right',
+      value: VALUE
+    });
+    const content = requireElement(view, '.ncua-progress-bar__content');
+    expect(containerOf(view).classList.contains('ncua-progress-bar-right')).toBe(true);
+    expect(Array.from(content.children).map(child => child.classList[0])).toEqual(['ncua-progress-bar__bar', 'ncua-progress-bar__label']);
+    expect(requireElement(content, '.ncua-progress-bar__label-right').textContent).toBe(`${VALUE}%`);
+  });
+  it.each([['bottom', ['ncua-progress-bar__content', 'ncua-progress-bar__label-bottom']], ['top-float', ['ncua-progress-bar__label-top-float', 'ncua-progress-bar__content']], ['bottom-float', ['ncua-progress-bar__label-bottom-float', 'ncua-progress-bar__content']]])('RPB-04 %s 라벨은 content 밖 순서 %j', (label, order) => {
+    const view = render({
+      label,
+      value: VALUE
+    });
+    expect(childOrderOf(view)).toEqual(order);
+    expect(containerOf(view).classList.contains(`ncua-progress-bar-${label}`)).toBe(true);
+  });
+  it('RPB-04 float 라벨이면 컨테이너에 --progress-value 를 준다', () => {
+    const view = render({
+      label: 'bottom-float',
+      value: VALUE
+    });
+    expect(containerOf(view).style.getPropertyValue('--progress-value')).toBe(`${VALUE}%`);
+  });
+  it('RPB-04 세그먼트 1개 + bottom-float 도 라벨이 content 앞에 온다', () => {
+    const view = render({
+      label: 'bottom-float',
+      segments: [{
+        value: SEG_A
+      }]
+    });
+    expect(childOrderOf(view)).toEqual(['ncua-progress-bar__label-bottom-float', 'ncua-progress-bar__content']);
+  });
+});
+describe('ProgressBar — 0% 라벨 (RPB-05)', () => {
+  it.each([['기본(숨김)', undefined, null], ['showZeroLabel true', true, '0%']])('RPB-05 value 0 + %s → 라벨 %s', (_label, showZeroLabel, expected) => {
+    const view = render({
+      label: 'right',
+      value: 0,
+      showZeroLabel
+    });
+    expect(view.querySelector('.ncua-progress-bar__label')?.textContent ?? null).toBe(expected);
+  });
+  it('RPB-05 세그먼트 1개 값 0 도 기본은 라벨을 숨긴다', () => {
+    const view = render({
+      label: 'bottom',
+      segments: [{
+        value: 0
+      }]
+    });
+    expect(view.querySelector('.ncua-progress-bar__label')).toBeNull();
+  });
+  it('RPB-05 0 세그먼트 라벨은 기본 숨김, showZeroLabel 이면 앞 폭 합 − 1 위치에 translateX(0) 로 둔다', () => {
+    const segments = [{
+      value: SEG_A
+    }, {
+      value: 0
+    }, {
+      value: SEG_B
+    }];
+    const hidden = render({
+      segments
+    });
+    expect(segmentLabelsOf(hidden).map(label => label.textContent)).toEqual([`${NORMALIZED_A}%`, `${NORMALIZED_B}%`]);
+    const shown = render({
+      segments,
+      showZeroLabel: true
+    });
+    const zero = segmentLabelsOf(shown)[1];
+    expect([zero.textContent, zero.style.left, zero.style.transform]).toEqual(['0%', `${NORMALIZED_A - ZERO_LABEL_OFFSET}%`, 'translateX(0)']);
+  });
+  it('RPB-05 첫 세그먼트가 0 이면 시작점은 0 아래로 내려가지 않는다', () => {
+    const view = render({
+      segments: [{
+        value: 0
+      }, {
+        value: SEG_A
+      }],
+      showZeroLabel: true
+    });
+    expect(segmentLabelsOf(view)[0].style.left).toBe('0%');
+  });
+});
+describe('ProgressBar — 세그먼트 라벨 위치 (RPB-06)', () => {
+  it('RPB-06 라벨 left = 앞 세그먼트 폭 합 + 자기 폭 / 2, transform translateX(-50%)', () => {
+    const view = render({
+      segments: [{
+        value: SEG_A
+      }, {
+        value: SEG_B
+      }]
+    });
+    const labels = segmentLabelsOf(view);
+    expect(labels.map(label => [label.style.left, label.style.transform])).toEqual([[`${FIRST_LABEL_LEFT}%`, 'translateX(-50%)'], [`${SECOND_LABEL_LEFT}%`, 'translateX(-50%)']]);
+  });
+  it('RPB-06 색이 없으면 색 클래스를 붙이지 않는다', () => {
+    const view = render({
+      segments: [{
+        value: SEG_A
+      }, {
+        value: SEG_B
+      }]
+    });
+    expect(fillsOf(view).some(fill => Array.from(fill.classList).some(name => name.includes('--color-')))).toBe(false);
+  });
+});
+describe('ProgressBar — 다중 세그먼트 aria (RPB-07)', () => {
+  it('RPB-07 세그먼트 2개 이상이면 aria-valuenow 가 어디에도 없다', () => {
+    // 현재 동작 고정 — 결함 후보: #597 (다중 세그먼트에 진행 값 aria 가 없음 — vanilla ProgressBar.ts 와 같은 동작, 접근성)
+    const view = render({
+      segments: [{
+        value: SEG_A
+      }, {
+        value: SEG_B
+      }]
+    });
+    expect(view.querySelector('[aria-valuenow]')).toBeNull();
+  });
+  it.todo('RPB-07 세그먼트 2개 이상이면 role="progressbar" 와 합계 aria-valuenow 를 노출한다 (기대, #597)');
+});
+describe('ProgressBar — label 미지정 (RPB-08)', () => {
+  it('RPB-08 label 을 생략하면 컨테이너 클래스가 빈 modifier ncua-progress-bar- 를 갖고 라벨이 없다', () => {
+    // 현재 동작 고정 — 결함 후보: #597 (label 생략 시 빈 modifier "ncua-progress-bar-" 클래스가 붙음)
+    const view = render({
+      value: VALUE
+    });
+    expect(containerOf(view).classList.contains('ncua-progress-bar-')).toBe(true);
+    expect(view.querySelector('.ncua-progress-bar__label')).toBeNull();
+  });
+  it.todo('RPB-08 label 을 생략하면 빈 modifier 클래스 ncua-progress-bar- 를 붙이지 않는다 (기대, #597)');
+});

package/dist/esm/src/components/feedback-and-status/progress-bar/__tests__/useProgressBar.test.js

@@ -0,0 +1,246 @@
+// @vitest-environment jsdom
+//
+// useProgressBar 훅 위험 경로 — 위험 목록표 UPB-xx.
+// 훅은 작은 프로브 컴포넌트로 렌더해 반환값을 꺼낸다.
+import { createElement } from 'react';
+import { createRoot } from 'react-dom/client';
+import { act } from 'react-dom/test-utils';
+import { afterEach, describe, expect, it } from 'vitest';
+import { useProgressBar } from '../hooks/useProgressBar';
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+const MAX = 100;
+const OVER_MAX = 150;
+const NEGATIVE = -20;
+const FRACTION = 33.6;
+const FRACTION_ROUNDED = '34%';
+const SEG_A = 30;
+const SEG_B = 10;
+/** 30 : 10 → 75 : 25 로 정규화 */
+const NORMALIZED_A = 75;
+const NORMALIZED_B = 25;
+/** valueToPercent false · 합 100 초과 — 80 + 60 = 140 → 각 width ×100/140 */
+const RAW_A = 80;
+const RAW_B = 60;
+const RAW_TOTAL = RAW_A + RAW_B;
+/** 음수 세그먼트(NEGATIVE)가 분모를 줄이는 경우 — 30 + 30 − 20 = 40 → 정규화 75 · 75 · −50 → 클램프 후 75 · 75 · 0 */
+const INFLATED = 75;
+const HALF = 50;
+let root = null;
+let container = null;
+afterEach(() => {
+  if (root) {
+    act(() => {
+      root?.unmount();
+    });
+  }
+  container?.remove();
+  root = null;
+  container = null;
+});
+const runHook = function () {
+  let {
+    label,
+    value,
+    segments,
+    valueToPercent
+  } = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+  let result = null;
+  const Probe = () => {
+    result = useProgressBar(label, value, segments, valueToPercent);
+    return null;
+  };
+  if (!container) {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  }
+  act(() => {
+    root?.render(/*#__PURE__*/createElement(Probe));
+  });
+  if (!result) throw new Error('훅 결과가 없습니다');
+  return result;
+};
+const widthsOf = result => result.processedSegments.map(segment => segment.width);
+// ── P0 ─────────────────────────────────────────────────
+describe('useProgressBar — 단일 value (UPB-01)', () => {
+  it.each([['범위 안', SEG_A, SEG_A, `${SEG_A}%`], ['100 초과는 100', OVER_MAX, MAX, `${MAX}%`], ['음수는 0', NEGATIVE, 0, '0%'], ['소수는 표시만 반올림', FRACTION, FRACTION, FRACTION_ROUNDED]])('UPB-01 %s → totalValue·displayValue', (_label, value, total, display) => {
+    const result = runHook({
+      value
+    });
+    expect([result.totalValue, result.displayValue, result.processedSegments, result.hasSegments]).toEqual([total, display, [], false]);
+  });
+  it('UPB-01 value·segments 둘 다 없으면 0%', () => {
+    const result = runHook();
+    expect([result.totalValue, result.displayValue, result.segmentCount]).toEqual([0, '0%', 0]);
+  });
+  it('UPB-01 빈 segments 배열은 segments 없음으로 보고 value 를 쓴다', () => {
+    const result = runHook({
+      value: SEG_A,
+      segments: []
+    });
+    expect([result.hasSegments, result.totalValue]).toEqual([false, SEG_A]);
+  });
+});
+describe('useProgressBar — 다중 세그먼트 (UPB-02·03)', () => {
+  it('UPB-02 valueToPercent 기본(true) 이면 합계 대비 비율로 정규화하고 합 100 이 된다', () => {
+    const result = runHook({
+      segments: [{
+        value: SEG_A,
+        color: 'blue'
+      }, {
+        value: SEG_B,
+        color: 'red'
+      }]
+    });
+    expect(result.processedSegments).toEqual([{
+      value: NORMALIZED_A,
+      color: 'blue',
+      width: NORMALIZED_A
+    }, {
+      value: NORMALIZED_B,
+      color: 'red',
+      width: NORMALIZED_B
+    }]);
+    expect([result.totalValue, result.displayValue, result.segmentCount]).toEqual([MAX, `${MAX}%`, 2]);
+  });
+  it('UPB-03 valueToPercent false 이고 합 100 이하이면 값을 그대로 쓴다', () => {
+    const result = runHook({
+      segments: [{
+        value: SEG_A
+      }, {
+        value: SEG_B
+      }],
+      valueToPercent: false
+    });
+    expect(widthsOf(result)).toEqual([SEG_A, SEG_B]);
+    expect(result.totalValue).toBe(SEG_A + SEG_B);
+  });
+  it('UPB-03 valueToPercent false 이고 합이 100 을 넘으면 비율대로 줄여 width 합을 100 으로 맞춘다', () => {
+    const result = runHook({
+      segments: [{
+        value: RAW_A
+      }, {
+        value: RAW_B
+      }],
+      valueToPercent: false
+    });
+    expect(widthsOf(result)).toEqual([RAW_A / RAW_TOTAL * MAX, RAW_B / RAW_TOTAL * MAX]);
+    expect(result.processedSegments.map(segment => segment.value)).toEqual([RAW_A, RAW_B]);
+    expect(result.totalValue).toBe(MAX);
+  });
+  it('UPB-03 valueToPercent false 에서 각 값은 0~100 으로 자른다', () => {
+    const result = runHook({
+      segments: [{
+        value: OVER_MAX
+      }, {
+        value: NEGATIVE
+      }],
+      valueToPercent: false
+    });
+    expect(result.processedSegments.map(segment => segment.value)).toEqual([MAX, 0]);
+    expect(widthsOf(result)).toEqual([MAX, 0]);
+  });
+});
+describe('useProgressBar — 세그먼트 1개 (UPB-04)', () => {
+  it('UPB-04 세그먼트 1개는 valueToPercent 를 무시하고 값을 클램프해 그대로 쓴다', () => {
+    const single = runHook({
+      segments: [{
+        value: SEG_A,
+        color: 'green'
+      }]
+    });
+    expect([single.totalValue, single.displayValue, widthsOf(single)]).toEqual([SEG_A, `${SEG_A}%`, [SEG_A]]);
+    const over = runHook({
+      segments: [{
+        value: OVER_MAX
+      }]
+    });
+    expect([over.totalValue, widthsOf(over)]).toEqual([MAX, [MAX]]);
+  });
+});
+// ── P1 ~ P3 ────────────────────────────────────────────
+describe('useProgressBar — 라벨 (UPB-05)', () => {
+  it('UPB-05 세그먼트 2개 이상이면 label 과 무관하게 bottom 으로 고정한다', () => {
+    const result = runHook({
+      label: 'right',
+      segments: [{
+        value: SEG_A
+      }, {
+        value: SEG_B
+      }]
+    });
+    expect([result.effectiveLabel, result.progressValueStyle]).toEqual(['bottom', undefined]);
+  });
+  it.each([['단일 value', undefined], ['세그먼트 1개', [{
+    value: SEG_A
+  }]]])('UPB-05 %s 는 label 을 그대로 쓴다', (_label, segments) => {
+    const result = runHook({
+      label: 'right',
+      value: SEG_A,
+      segments
+    });
+    expect(result.effectiveLabel).toBe('right');
+  });
+  it.each(['top-float', 'bottom-float'])('UPB-05 %s 라벨이면 --progress-value 스타일을 만든다', label => {
+    const result = runHook({
+      label,
+      value: SEG_A
+    });
+    expect(result.progressValueStyle).toEqual({
+      '--progress-value': `${SEG_A}%`
+    });
+  });
+  it.each(['right', 'bottom', undefined])('UPB-05 float 가 아닌 라벨(%s)은 스타일이 없다', label => {
+    const result = runHook({
+      label,
+      value: SEG_A
+    });
+    expect(result.progressValueStyle).toBeUndefined();
+  });
+});
+describe('useProgressBar — 경계값 (UPB-06)', () => {
+  it('UPB-06 합계 0 세그먼트는 정규화를 건너뛰고 width 0·0% 이다', () => {
+    const result = runHook({
+      segments: [{
+        value: 0
+      }, {
+        value: 0
+      }]
+    });
+    expect([widthsOf(result), result.totalValue, result.displayValue]).toEqual([[0, 0], 0, '0%']);
+  });
+  it('UPB-06 음수 세그먼트가 정규화 분모를 줄여 나머지 세그먼트 값이 부풀려진다', () => {
+    // 현재 동작 고정 — 결함 후보: #597 (음수를 0 으로 보기 전에 합계를 내 30·30 이 75%·75% 로 표시 — PB-12 와 같은 동작)
+    const result = runHook({
+      segments: [{
+        value: SEG_A
+      }, {
+        value: SEG_A
+      }, {
+        value: NEGATIVE
+      }]
+    });
+    expect(result.processedSegments.map(segment => segment.value)).toEqual([INFLATED, INFLATED, 0]);
+    expect(widthsOf(result)).toEqual([HALF, HALF, 0]);
+  });
+  it('UPB-06 value NaN 은 클램프를 통과해 totalValue NaN·"NaN%" 가 된다', () => {
+    // 현재 동작 고정 — 결함 후보: #597 (clampValue 가 NaN 을 거르지 않음 — PB-12 와 같은 동작)
+    const result = runHook({
+      value: Number.NaN
+    });
+    expect([result.totalValue, result.displayValue]).toEqual([Number.NaN, 'NaN%']);
+  });
+  it('UPB-06 NaN 세그먼트가 섞이면 정규화를 건너뛰고 width 0·"NaN%" 가 된다', () => {
+    // 현재 동작 고정 — 결함 후보: #597 (NaN 합계로 정규화·width 계산이 무너짐)
+    const result = runHook({
+      segments: [{
+        value: Number.NaN
+      }, {
+        value: SEG_A
+      }]
+    });
+    expect([widthsOf(result), result.displayValue]).toEqual([[0, 0], 'NaN%']);
+  });
+  it.todo('UPB-06 음수 세그먼트는 0 으로 본 뒤 합계를 내 30·30·−20 이 50%·50%·0% 가 된다 (기대, #597)');
+  it.todo('UPB-06 value·세그먼트 NaN 은 0 으로 처리해 "0%" 를 표시한다 (기대, #597)');
+});

package/dist/esm/src/components/feedback-and-status/progress-bar/__tests__/utils.test.js

@@ -0,0 +1,19 @@
+// progress-bar utils 위험 경로 — 위험 목록표 PU-xx.
+import { describe, expect, it } from 'vitest';
+import { clampValue, getFillColorClass, getLabelColorClass } from '../utils';
+const MAX = 100;
+const ABOVE_MAX = 101;
+const MIDDLE = 55;
+describe('progress-bar utils — 색 클래스 (PU-01)', () => {
+  it.each([['blue', 'blue'], ['  Blue ', 'blue'], ['RED', 'red']])('PU-01 "%s" 는 소문자·trim 해 %s 클래스를 만든다', (color, normalized) => {
+    expect([getFillColorClass(color), getLabelColorClass(color)]).toEqual([`ncua-progress-bar__fill--color-${normalized}`, `ncua-progress-bar__label--color-${normalized}`]);
+  });
+  it.each([['undefined', undefined], ['빈 문자열', '']])('PU-01 색이 %s 면 빈 클래스', (_label, color) => {
+    expect([getFillColorClass(color), getLabelColorClass(color)]).toEqual(['', '']);
+  });
+});
+describe('progress-bar utils — clampValue (PU-02)', () => {
+  it.each([[-1, 0], [0, 0], [MIDDLE, MIDDLE], [MAX, MAX], [ABOVE_MAX, MAX]])('PU-02 clampValue(%s) → %s', (value, expected) => {
+    expect(clampValue(value)).toBe(expected);
+  });
+});

package/dist/esm/src/components/feedback-and-status/progress-circle/__tests__/ProgressCircle.test.js

@@ -0,0 +1,99 @@
+// @vitest-environment jsdom
+//
+// ProgressCircle (React) 위험 경로 — 위험 목록표 PC-xx.
+import { createElement } from 'react';
+import { createRoot } from 'react-dom/client';
+import { act } from 'react-dom/test-utils';
+import { afterEach, describe, expect, it } from 'vitest';
+import { ProgressCircle } from '../ProgressCircle';
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+const VALUE = 40;
+const MAX = 100;
+const OVER_MAX = 150;
+const NEGATIVE = -10;
+/** 반올림하지 않는 소수 — 100 / 3 */
+const THIRDS_DIVISOR = 3;
+const ONE_THIRD = MAX / THIRDS_DIVISOR;
+let root = null;
+let container = null;
+const renderElement = element => {
+  if (!container) {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  }
+  act(() => {
+    root?.render(element);
+  });
+  return container;
+};
+const render = function () {
+  let props = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+  return renderElement(/*#__PURE__*/createElement(ProgressCircle, {
+    size: 'sm',
+    value: VALUE,
+    ...props
+  }));
+};
+afterEach(() => {
+  if (root) {
+    act(() => {
+      root?.unmount();
+    });
+  }
+  container?.remove();
+  root = null;
+  container = null;
+});
+const requireElement = (scope, selector) => {
+  const element = scope.querySelector(selector);
+  if (!element) throw new Error(`요소를 찾을 수 없습니다: ${selector}`);
+  return element;
+};
+const valueLabelOf = view => requireElement(view, '.ncua-progress-circle__label').textContent ?? '';
+const dashOffsetOf = view => requireElement(view, '.ncua-progress-circle__progress').getAttribute('stroke-dashoffset');
+describe('ProgressCircle — 값 (PC-01)', () => {
+  it.each([['범위 안', VALUE, VALUE], ['100 초과는 100', OVER_MAX, MAX], ['음수는 0', NEGATIVE, 0]])('PC-01 %s → 라벨 {값}% 와 strokeDashoffset 식', (_label, value, clamped) => {
+    const view = render({
+      value
+    });
+    expect([valueLabelOf(view), dashOffsetOf(view)]).toEqual([`${clamped}%`, `calc(var(--circle-circumference) * (1 - ${clamped} / 100))`]);
+  });
+  it('PC-01 half-circle 은 반원 둘레 변수로 strokeDashoffset 을 계산한다', () => {
+    const view = render({
+      theme: 'half-circle'
+    });
+    expect(dashOffsetOf(view)).toBe(`calc(var(--half-circle-circumference) * (1 - ${VALUE} / 100))`);
+  });
+});
+describe('ProgressCircle — theme (PC-02)', () => {
+  it.each([['circle(기본)', undefined, 'circle', '0 0 100 100', 'circle'], ['half-circle', 'half-circle', 'half-circle', '0 0 100 50', 'path']])('PC-02 %s → 클래스·viewBox·도형', (_label, theme, themeClass, viewBox, shape) => {
+    const view = render({
+      theme,
+      size: 'md'
+    });
+    const circle = requireElement(view, '.ncua-progress-circle');
+    expect([circle.classList.contains(`ncua-progress-circle-${themeClass}`), circle.classList.contains('ncua-progress-circle-md'), requireElement(view, 'svg').getAttribute('viewBox'), view.querySelectorAll(`svg ${shape}`).length]).toEqual([true, true, viewBox, 2]);
+  });
+});
+describe('ProgressCircle — label 위치 (PC-03)', () => {
+  const labelsOf = view => [view.querySelector('.ncua-progress-circle__label-text')?.textContent ?? null, view.querySelector('.ncua-progress-circle__outside-label')?.textContent ?? null];
+  it.each([['circle', 'xxs', '진행률', [null, '진행률']], ['circle', 'sm', '진행률', ['진행률', null]], ['circle', 'sm', undefined, [null, null]], ['circle', 'xxs', undefined, [null, null]], ['half-circle', 'xxs', '진행률', [null, '진행률']], ['half-circle', 'lg', '진행률', ['진행률', null]], ['half-circle', 'lg', undefined, [null, null]]])('PC-03 %s · size %s · label %s → [안쪽, 바깥]', (theme, size, label, expected) => {
+    const view = render({
+      theme,
+      size,
+      label
+    });
+    expect(labelsOf(view)).toEqual(expected);
+  });
+});
+describe('ProgressCircle — 소수 값 (PC-04)', () => {
+  it('PC-04 소수 value 를 반올림하지 않고 그대로 표시한다', () => {
+    // 현재 동작 고정 — 결함 후보: #597 (라벨이 "33.333…%" — ProgressBar 는 toFixed(0) 로 반올림)
+    const view = render({
+      value: ONE_THIRD
+    });
+    expect(valueLabelOf(view)).toBe(`${ONE_THIRD}%`);
+  });
+  it.todo('PC-04 소수 value 는 ProgressBar 와 같이 정수로 반올림해 "33%" 로 표시한다 (기대, #597)');
+});