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

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)');
+});

package/dist/esm/src/components/feedback-and-status/spinner/__tests__/Spinner.test.js

@@ -0,0 +1,73 @@
+// @vitest-environment jsdom
+//
+// Spinner (React) 위험 경로 — 위험 목록표 SP-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 { Spinner } from '../Spinner';
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+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(Spinner, 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 spinnerOf = view => requireElement(view, '.ncua-spinner');
+describe('Spinner — 클래스·텍스트 (SP-01)', () => {
+  it('SP-01 기본값은 size sm 이고 backdrop·텍스트가 없다', () => {
+    const view = render();
+    expect([spinnerOf(view).classList.contains('ncua-spinner--sm'), spinnerOf(view).classList.contains('ncua-spinner--backdrop'), view.querySelector('.ncua-spinner__text')]).toEqual([true, false, null]);
+  });
+  it('SP-01 size·backdrop 을 클래스로 반영한다', () => {
+    const view = render({
+      size: 'xl',
+      backdrop: true
+    });
+    expect([spinnerOf(view).classList.contains('ncua-spinner--xl'), spinnerOf(view).classList.contains('ncua-spinner--backdrop')]).toEqual([true, true]);
+  });
+  it.each([['as 생략 → p', undefined, 'P'], ['as span', 'span', 'SPAN']])('SP-01 children 이 있으면 %s 태그로 텍스트를 렌더한다', (_label, as, tagName) => {
+    const view = render({
+      as,
+      children: '불러오는 중'
+    });
+    const text = requireElement(view, '.ncua-spinner__content > .ncua-spinner__text');
+    expect([text.tagName, text.textContent]).toEqual([tagName, '불러오는 중']);
+  });
+});
+describe('Spinner — 로딩 알림 (SP-02)', () => {
+  it('SP-02 role·aria-live·aria-busy 등 로딩 알림 속성이 없다', () => {
+    // 현재 동작 고정 — 결함 후보: #597 (스크린 리더에 로딩 상태가 알려지지 않음 — 접근성)
+    const view = render({
+      children: '불러오는 중'
+    });
+    expect(view.querySelector('[role], [aria-live], [aria-busy]')).toBeNull();
+  });
+  it.todo('SP-02 role="status"·aria-live="polite" 로 로딩 상태를 알린다 (기대, #597)');
+});