@ihabdevteam/core 0.8.0

package/dist/packages/core/src/components/Popup/ConfirmPopup.js

@@ -0,0 +1,59 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cx } from '../../utils/cx';
+import { useRef, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+import Popup from './Popup';
+import Panel, { PanelRow } from '../Panel';
+/**
+ * 취소/확인 두 버튼을 가진 표준 확인 다이얼로그.
+ * 삭제 확인 등 단순 yes/no 흐름을 매번 Popup+buttons로 직접 짜지 않도록 분리한 래퍼.
+ * 로딩/에러(children)·조건부 닫힘(closeOnConfirm)도 지원한다.
+ * @public
+ */
+export default function ConfirmPopup(props) {
+    const { title, message, topContent, details, children, confirmLabel, cancelLabel, hideCancel = false, extraAction, confirmVariant = 'main', confirmDisabled = false, onConfirm, closeOnConfirm = true, onClose, inline, size = 'small', className, } = props;
+    const { t } = useTranslation();
+    // 처리 중(async onConfirm) 재진입 방지 — Popup이 onClick을 await하지 않아 closeOnConfirm:false
+    // 흐름(결제/환불)에서 더블클릭 시 RPC가 2회 발화될 수 있어, 여기서 in-flight를 직접 막는다.
+    const busyRef = useRef(false);
+    const [busy, setBusy] = useState(false);
+    return (_jsxs(Popup, { title: title, onClose: onClose, 
+        // onConfirm(서버 요청 등)이 진행 중일 때 X/ESC로 닫으면, 팝업은 즉시 사라지는데
+        // 이미 시작된 요청은 계속 진행돼 완료 후 부모 state/토스트가 뒤늦게 갱신된다 —
+        // 사용자는 "취소했다"고 믿었는데 실제로는 실행된 것처럼 보이는 문제를 막는다.
+        closeDisabled: busy, inline: inline, size: size, className: cx('confirm-popup', className), buttons: [
+            ...(extraAction ? [{
+                    label: extraAction.label,
+                    variant: extraAction.variant ?? 'default',
+                    disabled: busy,
+                    onClick: ({ closeWithAnimation }) => { extraAction.onClick(); closeWithAnimation(); },
+                }] : []),
+            ...(hideCancel ? [] : [{
+                    label: cancelLabel ?? t('common.cancel', '취소'),
+                    variant: 'default',
+                    disabled: busy,
+                    onClick: ({ closeWithAnimation }) => closeWithAnimation(),
+                }]),
+            {
+                label: confirmLabel ?? t('common.confirm', '확인'),
+                variant: confirmVariant,
+                disabled: confirmDisabled || busy,
+                onClick: async ({ closeWithAnimation }) => {
+                    if (busyRef.current)
+                        return;
+                    busyRef.current = true;
+                    setBusy(true);
+                    try {
+                        await onConfirm(closeWithAnimation);
+                        if (closeOnConfirm)
+                            closeWithAnimation();
+                    }
+                    finally {
+                        busyRef.current = false;
+                        setBusy(false);
+                    }
+                },
+            },
+        ], children: [topContent != null && _jsx("div", { className: "confirm-popup__top", children: topContent }), details && details.length > 0 && (_jsx(Panel, { children: details.map((d, i) => (_jsx(PanelRow, { label: d.label, children: _jsx("span", { className: "panel-row__text body-2", children: d.value }) }, i))) })), _jsx("p", { className: "body-2 confirm-popup__message", children: message }), children] }));
+}

package/dist/packages/core/src/components/Popup/CouponInputPopup.css

@@ -0,0 +1,28 @@
+.coupon-input-popup__input {
+  width: 100%;
+  height: 48px;
+  padding: 0 14px;
+  border: 1px solid var(--color-whiteLine);
+  border-radius: var(--radius-s);
+  background: var(--color-white);
+  color: var(--color-darkGray);
+  font-family: inherit;
+  box-sizing: border-box;
+  transition: border-color 0.15s;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+}
+.coupon-input-popup__input:focus {
+  outline: none;
+  border-color: var(--color-main);
+}
+.coupon-input-popup__input::placeholder {
+  color: var(--color-lightGray);
+  text-transform: none;
+  letter-spacing: normal;
+}
+
+.coupon-input-popup__error {
+  color: var(--color-red, #e84040);
+  margin: var(--spacing-xs) 0 0;
+}

package/dist/packages/core/src/components/Popup/CouponInputPopup.d.ts

@@ -0,0 +1,8 @@
+import './CouponInputPopup.css';
+/** @public */
+export interface CouponInputPopupProps {
+    onApply: (code: string) => Promise<void>;
+    onCancel: () => void;
+}
+/** @public */
+export default function CouponInputPopup({ onApply, onCancel }: CouponInputPopupProps): import("react").JSX.Element;

package/dist/packages/core/src/components/Popup/CouponInputPopup.js

@@ -0,0 +1,45 @@
+'use client';
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { getErrorMessage } from '../../utils/errorMessage';
+import { useTranslation } from 'react-i18next';
+import Popup from './Popup';
+import './CouponInputPopup.css';
+/** @public */
+export default function CouponInputPopup({ onApply, onCancel }) {
+    const { t } = useTranslation();
+    const [code, setCode] = useState('');
+    const [loading, setLoading] = useState(false);
+    const [error, setError] = useState(null);
+    const inputRef = useRef(null);
+    // Popup 자체 포커스 로직(패널 내 첫 focusable = 헤더 닫기 버튼)보다 먼저 실행되도록
+    // 자식 effect가 부모보다 먼저 도는 순서를 이용해 입력창을 선점 포커스한다.
+    useEffect(() => { inputRef.current?.focus(); }, []);
+    const handleApply = useCallback(async (closeWithAnimation) => {
+        const trimmed = code.trim();
+        if (!trimmed)
+            return;
+        setLoading(true);
+        setError(null);
+        try {
+            await onApply(trimmed);
+            closeWithAnimation();
+        }
+        catch (e) {
+            setError(getErrorMessage(e));
+            setLoading(false);
+        }
+    }, [code, onApply]);
+    const handleKey = useCallback((e, closeWithAnimation) => {
+        if (e.key === 'Enter')
+            void handleApply(closeWithAnimation);
+    }, [handleApply]);
+    const handleChange = (e) => {
+        setCode(e.target.value);
+        setError(null);
+    };
+    return (_jsx(Popup, { className: "coupon-input-popup", title: t('usage.couponButton', '쿠폰 입력'), size: "small", onClose: onCancel, closeDisabled: loading, buttons: [
+            { label: t('common.cancel', '취소'), variant: 'default', disabled: loading, onClick: ({ closeWithAnimation }) => closeWithAnimation() },
+            { label: t('coupons.applyButton', '적용'), variant: 'main', disabled: !code.trim() || loading, onClick: ({ closeWithAnimation }) => void handleApply(closeWithAnimation) },
+        ], children: ({ closeWithAnimation }) => (_jsxs(_Fragment, { children: [_jsx("input", { ref: inputRef, className: "coupon-input-popup__input body-2", "aria-label": t('coupons.input.label', '쿠폰 코드'), placeholder: t('coupons.input.placeholder', '쿠폰 코드 입력'), value: code, onChange: handleChange, onKeyDown: e => handleKey(e, closeWithAnimation), disabled: loading, autoComplete: "off", spellCheck: false }), error && _jsx("p", { className: "coupon-input-popup__error caption-1", role: "alert", children: error })] })) }));
+}

package/dist/packages/core/src/components/Popup/DeviceListPopup.css

@@ -0,0 +1,78 @@
+.dlp-popup .popup-panel { max-width: 600px; }
+
+.dlp-empty {
+  padding: 32px 20px;
+  text-align: center;
+  color: var(--color-gray);
+}
+
+.dlp-table {
+  width: 100%;
+  border-collapse: collapse;
+  font-size: 13px;
+}
+
+.dlp-table thead tr {
+  border-bottom: 1px solid var(--color-darkWhite);
+}
+
+.dlp-table th {
+  padding: 8px 12px;
+  text-align: left;
+  color: var(--color-lightGray);
+  font-weight: 500;
+  white-space: nowrap;
+}
+
+.dlp-row {
+  cursor: pointer;
+  border-bottom: 1px solid var(--color-darkWhite);
+  transition: background 0.1s;
+}
+
+.dlp-row:hover { background: var(--color-hoverBg, #f5f5f5); }
+.dlp-row:last-child { border-bottom: none; }
+
+.dlp-table td {
+  padding: 10px 12px;
+  vertical-align: middle;
+  color: var(--color-darkGray);
+}
+
+
+.dlp-date {
+  white-space: nowrap;
+  color: var(--color-lightGray);
+}
+
+.dlp-delete {
+  background: none;
+  border: none;
+  cursor: pointer;
+  color: var(--color-lightGray);
+  font-size: 12px;
+  padding: 4px 8px;
+  border-radius: 4px;
+  transition: color 0.1s, background 0.1s;
+}
+
+.dlp-delete:hover {
+  color: var(--color-error, #e53935);
+  background: var(--color-errorBg, #fdecea);
+}
+
+/* 팝업 밖(고객 상세의 기기 탭)에서도 쓰는 표 — 좌/우 고르개가 표 위에 얹힌다. */
+.dlp-side-table { margin-top: 0; }
+.dlp-side-pick {
+  display: flex;
+  justify-content: flex-start;
+  margin-bottom: 8px;
+}
+
+/* 줄 오른쪽의 착용·제거 — 붙어 보이지 않게만 벌린다 */
+.dlp-worn-check { display: inline-flex; align-items: center; }
+/* 줄 끝의 삭제 — 삭제를 넘겨준 화면(기기 이력 팝업)에서만 선다 */
+.dlp-row-actions { display: flex; align-items: center; justify-content: flex-end; }
+
+/* 맨 왼쪽 '착용중' 열 — 값이 있는 줄만 눈에 띄게 */
+.dlp-worn-side { font-weight: 600; color: var(--color-main, #3b82f6); }

package/dist/packages/core/src/components/Popup/DeviceListPopup.d.ts

@@ -0,0 +1,28 @@
+import type { DeviceEntry } from '../HearingDeviceInfo';
+import type { DeviceSide } from '../Panel';
+import type { DeviceForm } from '../../types/device';
+import './DeviceListPopup.css';
+interface DeviceListPopupProps {
+    devices: {
+        좌: DeviceEntry | null;
+        우: DeviceEntry | null;
+    };
+    deviceHistory: {
+        좌: DeviceEntry[];
+        우: DeviceEntry[];
+    };
+    onClose: () => void;
+    onSelect: (d: DeviceForm) => void;
+    onDelete: (side: DeviceSide, index: number) => void;
+}
+/**
+ * 기기 이력 팝업 — 표는 DeviceSideTable 한 벌만 쓴다.
+ *
+ * 고객 상세의 기기 탭이 그 표를 그대로 품게 되면서 그 탭에서는 더 쓰지 않는다.
+ * 표를 두 벌로 갈라 두지 않으려고 껍데기만 남겨 둔다 — 메모리 목록(좌/우 배열)을
+ * 표가 쓰는 줄 모양으로 옮겨 넘긴다.
+ *
+ * @public
+ */
+export default function DeviceListPopup({ devices, deviceHistory, onClose, onSelect, onDelete }: DeviceListPopupProps): import("react").JSX.Element;
+export {};

package/dist/packages/core/src/components/Popup/DeviceListPopup.js

@@ -0,0 +1,31 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useMemo } from 'react';
+import { useTranslation } from 'react-i18next';
+import Popup from './Popup';
+import DeviceSideTable from './DeviceSideTable';
+import './DeviceListPopup.css';
+/**
+ * 기기 이력 팝업 — 표는 DeviceSideTable 한 벌만 쓴다.
+ *
+ * 고객 상세의 기기 탭이 그 표를 그대로 품게 되면서 그 탭에서는 더 쓰지 않는다.
+ * 표를 두 벌로 갈라 두지 않으려고 껍데기만 남겨 둔다 — 메모리 목록(좌/우 배열)을
+ * 표가 쓰는 줄 모양으로 옮겨 넘긴다.
+ *
+ * @public
+ */
+export default function DeviceListPopup({ devices, deviceHistory, onClose, onSelect, onDelete }) {
+    const { t } = useTranslation();
+    const rows = useMemo(() => ['좌', '우'].flatMap(side => deviceHistory[side].map((d, index) => ({
+        index, side,
+        brand: d.brand, device: d.device,
+        fitType: d.fitType ?? '', productName: d.productName ?? '',
+        wornYear: d.wornYear, wornMonth: d.wornMonth, wornDay: d.wornDay,
+        worn: devices[side] === d,
+    }))), [deviceHistory, devices]);
+    return (_jsx(Popup, { className: "dlp-popup", ariaLabel: t('customers.device.historyTitle', '청각재활기기 이력'), onClose: onClose, children: _jsx(DeviceSideTable, { rows: rows, onSelect: row => onSelect({
+                direction: row.side, brand: row.brand, device: row.device,
+                fitType: row.fitType, productName: row.productName,
+                wornYear: row.wornYear, wornMonth: row.wornMonth, wornDay: row.wornDay,
+            }), onDelete: row => onDelete(row.side, row.index) }) }));
+}

package/dist/packages/core/src/components/Popup/DeviceSideTable.d.ts

@@ -0,0 +1,41 @@
+import type { DeviceSide } from '../Panel';
+import './DeviceListPopup.css';
+/**
+ * 표에 놓이는 한 줄 — 서버에서 온 것이든 아직 메모리에만 있는 것이든 같은 꼴이다.
+ * `id` 는 서버 행일 때만 있다(지우기가 그 id 로 간다).
+ *
+ * @public
+ */
+export interface DeviceRow {
+    id?: string;
+    side: DeviceSide;
+    brand: string;
+    device: string;
+    fitType: string;
+    productName: string;
+    wornYear: string;
+    wornMonth: string;
+    wornDay: string;
+    /** 지금 그 쪽에 끼고 있는 기기인가 */
+    worn: boolean;
+}
+export interface DeviceSideTableProps {
+    rows: DeviceRow[];
+    /** 줄을 누르면 그 기기로 등록 폼을 채워 연다 */
+    onSelect: (row: DeviceRow) => void;
+    /**
+     * 있으면 줄 끝에 '삭제'가 선다.
+     *
+     * 고객 상세의 기기 탭은 **안 넘긴다** — 거기서는 줄을 눌러 연 수정 창 바닥에 삭제가
+     * 있다(표에서 바로 지우면 무엇을 지우는지 확인할 겨를이 없다). 그 창을 안 쓰는
+     * 화면(기기 이력 팝업)은 지울 다른 길이 없으므로 여기서 받는다.
+     */
+    onDelete?: (row: DeviceRow) => void;
+    /** 이 기기를 그 쪽의 '지금 착용중'으로 세운다 */
+    onWear?: (row: DeviceRow) => void;
+    /** 지금 끼고 있는 기기를 내린다 — 이력은 남는다 */
+    onRelease?: (row: DeviceRow) => void;
+    /** 툴바 오른쪽 끝의 '기기 추가' */
+    onAdd?: () => void;
+}
+export default function DeviceSideTable({ rows, onSelect, onDelete, onWear, onRelease, onAdd }: DeviceSideTableProps): import("react").JSX.Element;

package/dist/packages/core/src/components/Popup/DeviceSideTable.js

@@ -0,0 +1,92 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useMemo } from 'react';
+import { useTranslation } from 'react-i18next';
+import Toolbar from '../Toolbar';
+import Table from '../Table';
+import Button from '../Button';
+import Checkbox from '../Checkbox';
+import Badge from '../Badge';
+import { deviceKindVariant } from '../../utils/deviceKind';
+import { useTablePaging, useTableSort } from '../../hooks/useTablePaging';
+import './DeviceListPopup.css';
+/**
+ * 정렬에 쓸 문자열. 날짜는 **자리수를 채워** 잰다 — '2026.5.2' 와 '2026.11.5' 를
+ * 글자 그대로 견주면 5월이 11월보다 뒤로 간다.
+ */
+function 정렬값(r, key) {
+    if (key !== 'wornAt')
+        return String(r[key] ?? '');
+    if (!r.wornYear)
+        return '';
+    return `${r.wornYear}-${r.wornMonth.padStart(2, '0')}-${r.wornDay.padStart(2, '0')}`;
+}
+export default function DeviceSideTable({ rows, onSelect, onDelete, onWear, onRelease, onAdd }) {
+    const { t } = useTranslation();
+    const 방향이름 = (side) => side === '좌' ? t('device.direction.left', '좌') : t('device.direction.right', '우');
+    /* 머리행을 누르면 그 칸으로 정렬한다 — 같은 칸을 다시 누르면 방향이 뒤집힌다.
+       쪽넘김보다 **앞에서** 정렬한다(훅에 이미 정렬된 줄을 건넨다). */
+    const { 정렬, 칸 } = useTableSort();
+    const sortedRows = useMemo(() => {
+        if (!정렬)
+            return rows;
+        const { key, asc } = 정렬;
+        return [...rows].sort((a, b) => {
+            const cmp = key === 'worn'
+                ? Number(b.worn) - Number(a.worn) // 켜진 것이 먼저
+                : 정렬값(a, key).localeCompare(정렬값(b, key), 'ko');
+            return asc ? cmp : -cmp;
+        });
+    }, [rows, 정렬]);
+    /* 개수 보기·쪽넘김은 방문 표와 같은 것을 쓴다 — 같은 자리에서 같은 뜻으로 읽히게 */
+    const { pageRows, pageSizeProps, paginationProps } = useTablePaging(sortedRows, 정렬);
+    return (_jsxs("div", { className: "dlp-side-table", children: [_jsx(Toolbar, { count: { value: rows.length, unit: t('customers.device.unit', '개') }, pageSize: pageSizeProps, pagination: paginationProps, actions: onAdd && (_jsx(Button, { size: 40, type: "bar", variant: "main", icon: "plus", label: t('customers.device.addButton', '기기 추가'), onClick: onAdd })) }), _jsx(Table, { resizable: true, resizeMode: "fit", resizeStorageKey: "customer-device-history-v2", fields: [
+                    /* 맨 왼쪽 — 지금 끼고 있는 것만 좌/우를 적는다. 이 열만 훑으면 "오늘 이 사람이
+                       무엇을 쓰고 있나" 가 한눈에 보인다(나머지 줄은 비어 있어 눈에 안 걸린다). */
+                    /* 체크박스 칸은 폭을 늘릴 것이 없다 — 손잡이를 주면 잡히는데 아무 일도
+                       일어나지 않는다. Table 이 이 경우를 위해 resizable:false 를 둔다. */
+                    { ...칸(t('customers.device.wearingNow', '착용'), 'worn'), resizable: false },
+                    칸(t('device.direction.label', '방향'), 'side'),
+                    칸(t('device.deviceType', '종류'), 'device'),
+                    칸(t('device.brand', '브랜드'), 'brand'),
+                    칸(t('device.fitType', '착용형태'), 'fitType'),
+                    칸(t('device.productName', '제품명'), 'productName'),
+                    칸(t('device.wornDate', '착용일'), 'wornAt'),
+                    /* 삭제 칸은 그 길을 준 화면에서만 — 머리행과 줄의 칸 수가 어긋나면 표가 밀린다 */
+                    ...(onDelete ? [{ label: '', resizable: false }] : []),
+                ], items: pageRows.map((r, i) => ({ id: r.id ?? `${r.side}-${i}`, row: r })), gridTemplateColumns: `56px 110px 110px minmax(120px, 1fr) 100px minmax(120px, 1fr) 110px${onDelete ? ' 80px' : ''}`, renderRow: ({ row }) => [
+                    {
+                        /* 착용 여부를 **여기서 바로 켜고 끈다** — 예전엔 이 칸이 배지로 상태만
+                           말하고, 바꾸려면 줄 오른쪽 끝의 다른 단추를 눌러야 했다. 보는 자리와
+                           바꾸는 자리가 갈려 있으면 무엇이 무엇을 바꾸는지 짚이지 않는다.
+                           체크가 눌림을 삼키게 해 줄이 함께 열리지 않도록 막는다. */
+                        content: (_jsx("span", { className: "dlp-worn-check", onClick: e => e.stopPropagation(), children: _jsx(Checkbox, { checked: row.worn, disabled: !onWear || !onRelease, ariaLabel: row.worn
+                                    ? t('customers.device.unwear', '착용 해제')
+                                    : t('customers.device.wear', '착용'), onChange: next => { if (next)
+                                    onWear?.(row);
+                                else
+                                    onRelease?.(row); } }) })),
+                    },
+                    /* 방향 칸은 좌/우만 말한다 — 착용 여부는 맨 왼쪽 체크가 다룬다 */
+                    { content: _jsx("span", { children: 방향이름(row.side) }) },
+                    /* 종류는 위 패널의 종류 배지와 같은 모양으로 — 같은 값을 두 곳에서 다르게
+                       그리면 같은 것인 줄 모른다. 값이 비면 배지도 세우지 않는다(빈 배지는
+                       '무언가 있다'는 거짓 신호다). */
+                    { content: row.device ? _jsx(Badge, { size: "small", variant: deviceKindVariant(row.device), fill: "soft", label: row.device }) : _jsx("span", {}) },
+                    { content: _jsx("span", { children: row.brand }) },
+                    { content: _jsx("span", { children: row.fitType || '-' }) },
+                    { content: _jsx("span", { children: row.productName || '-' }) },
+                    {
+                        content: _jsx("span", { className: "dlp-date", children: row.wornYear ? `${row.wornYear}.${row.wornMonth}.${row.wornDay}` : '-' }),
+                    },
+                    /* 삭제를 넘겨준 화면에서만 이 칸이 선다 — 안 넘기면 칸 자체가 없어,
+                       못 하는 일을 내밀지 않는다. 눌림은 줄로 새지 않게 막는다(줄을 누르면
+                       수정 창이 열린다). */
+                    ...(onDelete ? [{
+                            content: (_jsx("span", { className: "dlp-row-actions", children: _jsx(Button, { size: 28, type: "bar", variant: "transparent-gray", label: t('common.delete', '삭제'), onClick: e => { e?.stopPropagation(); onDelete(row); } }) })),
+                        }] : []),
+                ], onRowClick: ({ row }) => onSelect(row), 
+                /* Table 이 이미 TableRow variant="empty" 로 감싼다 — div 를 한 겹 더 씌우면
+                   가운데 정렬·글꼴이 두 번 걸린다. 문구만 넘긴다. */
+                empty: t('customers.device.historyEmpty', '등록된 기기 이력이 없습니다.') })] }));
+}

package/dist/packages/core/src/components/Popup/ListPopup.css

@@ -0,0 +1,44 @@
+/* ── ListPopup — 공용 리스트 팝업 ──────────────────────────────── */
+
+.popup-list .popup-panel {
+  max-width: 880px;
+  width: calc(100% - 40px);
+  max-height: calc(100% - 60px);
+}
+.popup-list .popup-content {
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-m);
+  min-height: 0;
+  overflow: hidden;
+}
+/* Table — 내부 스크롤 */
+.popup-list .table-wrap {
+  flex: 1;
+  min-height: 0;
+  overflow-y: auto;
+  overscroll-behavior-y: contain;
+  /* 가로로도 민다. 좁은 화면에서는 칸이 뭉개지는데(아래 min-width 참고) 밀 수도
+     없어서, 이름이 두 글자만 보이는 채로 갇혔다. */
+  overflow-x: auto;
+}
+
+/* 표는 부르는 쪽이 준 격자(예: `1fr 120px 1fr 110px`)로 그린다. 폰(375px)에서는
+   팝업 안쪽이 293px 뿐이라 고정 칸 230px 를 빼고 남는 자리를 1fr 둘이 나눠 갖는다 —
+   실측 **한 칸 32px**. 숙제 보내기 창이 그 꼴이었다: 어느 고객에게 보내는지 화면에서
+   알 수 없었다. 줄이 이 폭 아래로는 안 줄게 하고, 남는 만큼은 위에서 밀어 본다
+   (실측: 이름 칸 32 → 145, 감싼 칸 293 보임 / 520 담김).
+
+   머리행도 **같은 값**을 받아야 칸이 어긋나지 않는다.
+   넓은 화면에서는 팝업이 880px 까지 벌어져 이 폭을 넘으므로 아무것도 달라지지 않는다. */
+.popup-list .table-fields,
+.popup-list .table-row {
+  min-width: 520px;
+}
+
+/* 선택된 행 강조 */
+.popup-list__row--selected {
+  background: var(--color-deepWhite);
+  color: var(--color-main);
+  font-weight: 600;
+}

package/dist/packages/core/src/components/Popup/ListPopup.d.ts

@@ -0,0 +1,75 @@
+import { type ReactNode } from 'react';
+import './ListPopup.css';
+/** @public */
+export interface PopupListColumn<T> {
+    /** 데이터 키 (정렬/접근용). 기본 렌더 시 `item[key]`로 표시 */
+    key: string;
+    /** 컬럼 헤더 라벨 */
+    label: string;
+    /** 셀 커스텀 렌더러 (없으면 item[key] 표시) */
+    render?: (item: T) => ReactNode;
+    /** 정렬 가능 여부 (기본 true) */
+    sortable?: boolean;
+    /** 셀 className */
+    className?: string;
+}
+/** @public */
+export interface PopupListProps<T extends {
+    id?: string | number;
+}> {
+    /** 팝업 제목 */
+    title: string;
+    /** 표시할 아이템 배열 */
+    items: T[];
+    /** 컬럼 정의 */
+    columns: PopupListColumn<T>[];
+    /** Table grid template columns (예: "20% 10% 22% 26% 22%") */
+    gridTemplateColumns?: string;
+    /** 검색 placeholder */
+    searchPlaceholder?: string;
+    /**
+     * 검색 함수. 미지정 시 모든 columns의 key 값 문자열을 includes로 검사.
+     * `null` 전달 시 검색창 자체를 숨김.
+     */
+    searchFn?: ((item: T, query: string) => boolean) | null;
+    /** 기본 정렬 키 */
+    defaultSortKey?: string;
+    /** 기본 정렬 방향 (기본 asc) */
+    defaultSortAsc?: boolean;
+    /** 현재 선택된 아이템 id — 해당 행 강조 (단일) */
+    selectedId?: string | number;
+    /** 현재 선택된 아이템 id Set — 다중 선택 강조 (`selectedId`보다 우선) */
+    selectedIds?: Set<string | number>;
+    /** 행 클릭 후에도 팝업을 닫지 않음 (다중 선택용). 기본 false */
+    keepOpenOnSelect?: boolean;
+    /** 행 선택 콜백 */
+    onSelect: (item: T) => void;
+    /** 닫기 콜백 */
+    onClose: () => void;
+    /** 페이지당 항목 수 옵션. 미지정 시 기본 [10, 25, 50, 100] */
+    pageSizeOptions?: number[];
+    /** 초기 페이지 크기 */
+    initialPageSize?: number;
+    /** 빈 상태 텍스트 */
+    emptyText?: string;
+    /**
+     * 좌측에 표시할 총 개수 라벨. 미지정 시 "총 N개" 형식.
+     * - 함수: `(n) => 'XXX'`
+     * - 문자열: `{n}` 토큰을 개수로 치환 (예: "총 {n}명")
+     */
+    countLabel?: ((total: number) => ReactNode) | string;
+    /**
+     * 목록 위에 얹는 요약 — 표를 읽기 전에 먼저 보아야 하는 것을 둔다.
+     *
+     * 훈련 현황이 이걸 쓴다. 회차가 325줄이면 표를 아무리 잘 만들어도 '그래서 정답률이
+     * 얼마인가'는 사람이 세어야 한다. 목록과 요약은 같은 자료의 두 시점이라 한 화면에
+     * 있어야 하고, 요약 쪽이 먼저다.
+     */
+    topContent?: ReactNode;
+    /** 추가 className */
+    className?: string;
+}
+/** @public */
+export default function ListPopup<T extends {
+    id?: string | number;
+}>(props: PopupListProps<T>): import("react").JSX.Element;

package/dist/packages/core/src/components/Popup/ListPopup.js

@@ -0,0 +1,85 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+import Popup from './Popup';
+import Table from '../Table';
+import Toolbar from '../Toolbar';
+import './ListPopup.css';
+/** @public */
+export default function ListPopup(props) {
+    const { title, items, columns, gridTemplateColumns, searchPlaceholder, searchFn, defaultSortKey, defaultSortAsc = true, selectedId, selectedIds, onSelect, onClose, pageSizeOptions = [10, 25, 50, 100], initialPageSize, emptyText, countLabel, topContent, className = '', } = props;
+    const { t } = useTranslation();
+    const resolvedSearchPlaceholder = searchPlaceholder ?? t('common.search', '검색');
+    const resolvedEmptyText = emptyText ?? t('common.emptyList', '항목이 없습니다.');
+    const [search, setSearch] = useState('');
+    const [sortKey, setSortKey] = useState(defaultSortKey ?? columns[0]?.key ?? '');
+    const [sortAsc, setSortAsc] = useState(defaultSortAsc);
+    const [pageSize, setPageSize] = useState(String(initialPageSize ?? pageSizeOptions[0] ?? 10));
+    const [page, setPage] = useState(1);
+    // 검색어/페이지 크기 변경 시 페이지를 1로 리셋하는 의도된 상태 조정이다
+    // eslint-disable-next-line react-hooks/set-state-in-effect
+    useEffect(() => { setPage(1); }, [search, pageSize]);
+    const searchEnabled = searchFn !== null;
+    // 기본 검색: 모든 column key 값을 문자열로 변환해 includes
+    const defaultSearchFn = useCallback((item, query) => {
+        if (!query)
+            return true;
+        const q = query.toLowerCase();
+        return columns.some(col => {
+            const v = item[col.key];
+            if (v == null)
+                return false;
+            return String(v).toLowerCase().includes(q);
+        });
+    }, [columns]);
+    const effectiveSearchFn = searchFn ?? defaultSearchFn;
+    const filtered = useMemo(() => {
+        const filteredItems = searchEnabled ? items.filter(it => effectiveSearchFn(it, search)) : items;
+        if (!sortKey)
+            return filteredItems;
+        return [...filteredItems].sort((a, b) => {
+            const va = a[sortKey] ?? '';
+            const vb = b[sortKey] ?? '';
+            if (va === vb)
+                return 0;
+            return sortAsc ? (va > vb ? 1 : -1) : (va < vb ? 1 : -1);
+        });
+    }, [items, search, sortKey, sortAsc, searchEnabled, effectiveSearchFn]);
+    const totalPages = Math.max(1, Math.ceil(filtered.length / Number(pageSize)));
+    const paged = filtered.slice((page - 1) * Number(pageSize), page * Number(pageSize));
+    const handleSort = useCallback((key) => {
+        if (sortKey === key)
+            setSortAsc(a => !a);
+        else {
+            setSortKey(key);
+            setSortAsc(true);
+        }
+    }, [sortKey]);
+    // countLabel("총 {n}명")을 Toolbar count의 prefix/suffix로 분해
+    const countParts = useMemo(() => {
+        if (typeof countLabel === 'string' && countLabel.includes('{n}')) {
+            const [prefix, suffix] = countLabel.split('{n}');
+            return { prefix, suffix };
+        }
+        return { prefix: t('common.totalCountPrefix', '총 '), suffix: t('common.totalCountSuffix', '개') };
+    }, [countLabel, t]);
+    const tableFields = useMemo(() => columns.map(col => ({
+        label: col.label,
+        onClick: col.sortable !== false ? () => handleSort(col.key) : undefined,
+        className: col.className,
+        sortDir: col.sortable !== false && sortKey === col.key ? (sortAsc ? 'asc' : 'desc') : null,
+    })), [columns, sortKey, sortAsc, handleSort]);
+    const pageSizeOpts = useMemo(() => pageSizeOptions.map(n => ({ value: String(n), label: t('common.pageSizeLabel', { n }) })), [pageSizeOptions, t]);
+    return (_jsxs(Popup, { className: `popup-list ${className}`, title: title, onClose: onClose, children: [topContent, _jsx(Toolbar, { count: { value: filtered.length, prefix: countParts.prefix, suffix: countParts.suffix }, search: searchEnabled ? { value: search, onChange: setSearch, placeholder: resolvedSearchPlaceholder } : undefined, pageSize: { options: pageSizeOpts, value: pageSize, onChange: setPageSize }, pagination: { page, total: totalPages, onChange: setPage } }), _jsx(Table, { size: "medium", gridTemplateColumns: gridTemplateColumns, resizable: true, fields: tableFields, items: paged, onRowClick: onSelect, renderRow: (it) => {
+                    const isSelected = selectedIds != null
+                        ? (it.id != null && selectedIds.has(it.id))
+                        : (selectedId != null && it.id === selectedId);
+                    return columns.map(col => ({
+                        content: (col.render
+                            ? col.render(it)
+                            : (it[col.key] ?? '')),
+                        className: isSelected ? 'popup-list__row--selected' : col.className,
+                    }));
+                }, empty: resolvedEmptyText })] }));
+}