@ihabdevteam/core 0.8.0

package/dist/packages/core/src/utils/categories.js

@@ -0,0 +1,70 @@
+/**
+ * 훈련 카테고리 데이터 DI — 앱에서 주입하는 함수 기반 인터페이스.
+ *
+ * 패키지는 특정 앱의 카테고리 데이터를 직접 참조하지 않습니다.
+ * configureTrainingCategories()로 한 번 등록하면,
+ * 패키지 내부의 getTopicTypes() / getTrainingTypes()가 해당 데이터를 사용합니다.
+ *
+ * 등록하지 않으면 패키지 내장 기본값(SpeechEar 기본 카테고리)을 사용합니다.
+ *
+ * @example
+ * ```ts
+ * // main.tsx
+ * import { configureTrainingCategories } from '\@ihabdevteam/core'
+ * import { TOPIC_TYPES, TRAINING_TYPES } from './data/categories'
+ *
+ * configureTrainingCategories({ topicTypes: TOPIC_TYPES, trainingTypes: TRAINING_TYPES })
+ * ```
+ *
+ * @public
+ */
+// ─── 기본값 (SpeechEar 기본 카테고리) ────────────────────────────────────────
+// configureTrainingCategories() 미호출 시 사용됩니다.
+const DEFAULT_TOPIC_TYPES = [
+    { key: 'FOOD', label: '음식', icon: 'salad', color: '#FF8A65', subs: [{ key: 'TRKRFD', label: '한국 전통음식' }, { key: 'MDKRFD', label: '한국 현대음식' }, { key: 'WRLDFD', label: '세계의 음식' }, { key: 'MTRFRT', label: '식재료와 과일' }, { key: 'GEFDKL', label: '음식 상식' }] },
+    { key: 'HLTH', label: '건강', icon: 'heart', color: '#66BB6A', subs: [{ key: 'HTETHB', label: '건강한 식습관' }, { key: 'DISILL', label: '병과 질환' }, { key: 'EXCISE', label: '운동' }, { key: 'GEHTKL', label: '건강상식' }] },
+    { key: 'WETH', label: '날씨', icon: 'sun-medium', color: '#42A5F5', subs: [{ key: 'GESSKL', label: '계절상식' }, { key: 'SNWRAN', label: '눈과 비' }, { key: 'WTHFCT', label: '일기예보' }, { key: 'GEWTKL', label: '날씨상식' }] },
+    { key: 'PRSN', label: '인물', icon: 'user-round', color: '#AB47BC', subs: [{ key: 'JODYPS', label: '조선시대' }, { key: 'MDKRPS', label: '한국 근현대' }, { key: 'THKDPS', label: '삼국시대' }, { key: 'WRLART', label: '세계의 예술가' }, { key: 'WRLPSN', label: '세계의 인물' }] },
+    { key: 'KRCT', label: '한국문화', icon: 'bow-arrow', color: '#EC407A', subs: [{ key: 'KRLANG', label: '우리말' }, { key: 'TRPLCT', label: '전통놀이' }, { key: 'HERITG', label: '문화재' }, { key: 'EVTFES', label: '행사와 축제' }, { key: 'GECTKL', label: '상식' }] },
+    { key: 'STRY', label: '이야기', icon: 'message-circle', color: '#8D6E63', subs: [{ key: 'FRYTAL', label: '동화' }, { key: 'AMZING', label: '신기한 이야기' }, { key: 'DAYSTR', label: '일상 속 이야기' }] },
+    { key: 'LOCA', label: '지역', icon: 'map-pin', color: '#26A69A', subs: [{ key: 'KRLDMK', label: '한국의 명소' }, { key: 'SELNMK', label: '서울의 명소' }, { key: 'WRDTRB', label: '세계여행' }, { key: 'NAVIGT', label: '길 찾기' }] },
+    { key: 'SOAR', label: '사회와 예술', icon: 'landmark', color: '#5C6BC0', subs: [{ key: 'KRSOCI', label: '한국' }, { key: 'ECONEW', label: '경제와 뉴스' }, { key: 'GENART', label: '예술' }, { key: 'GELFKL', label: '생활 상식' }] },
+    { key: 'NTSC', label: '자연과 과학', icon: 'leaf', color: '#9CCC65', subs: [{ key: 'ANIMAL', label: '동물' }, { key: 'PLANTS', label: '식물' }, { key: 'ETHPLT', label: '지구' }, { key: 'TOLELC', label: '도구와 전자제품' }, { key: 'GESCKL', label: '과학상식' }] },
+    { key: 'SPRT', label: '스포츠', icon: 'trophy', color: '#FFCA28', subs: [{ key: 'INVDSP', label: '개인경기' }, { key: 'MARART', label: '격투기' }, { key: 'TEAMSP', label: '단체경기' }, { key: 'FOOTBL', label: '축구' }, { key: 'GESPKL', label: '스포츠 상식' }] },
+];
+const DEFAULT_TRAINING_TYPES = [
+    { key: 'LISTEN_IN_NOISE', label: '소음 하 문장 듣기', icon: 'party-popper', desc: '소음 환경 속 문장 이해 훈련' },
+    { key: 'SHORT_STORY', label: '짧은 이야기 듣기', icon: 'message-square', desc: '짧은 이야기 + 4문제' },
+    { key: 'LONG_STORY', label: '긴 이야기 듣기', icon: 'message-square-text', desc: '긴 이야기 심화 훈련' },
+    { key: 'ORDERING_SENTENCE', label: '문장 순서화 하기', icon: 'align-start-vertical', desc: '순서 배열 훈련' },
+];
+// ─── 런타임 상태 ──────────────────────────────────────────────────────────────
+let _config = null;
+/**
+ * 훈련 카테고리 데이터를 런타임에 주입합니다.
+ * 앱 초기화 시점에 한 번만 호출하세요.
+ * 호출하지 않으면 패키지 내장 기본값을 사용합니다.
+ *
+ * @public
+ */
+export function configureTrainingCategories(config) {
+    _config = config;
+}
+/**
+ * 등록된 주제 카테고리 목록을 반환합니다.
+ * configureTrainingCategories() 미호출 시 기본값을 반환합니다.
+ *
+ * @public
+ */
+export function getTopicTypes() {
+    return _config?.topicTypes ?? DEFAULT_TOPIC_TYPES;
+}
+/**
+ * 등록된 훈련 타입 목록을 반환합니다.
+ * configureTrainingCategories() 미호출 시 기본값을 반환합니다.
+ *
+ * @public
+ */
+export function getTrainingTypes() {
+    return _config?.trainingTypes ?? DEFAULT_TRAINING_TYPES;
+}

package/dist/packages/core/src/utils/clipboard.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 텍스트를 클립보드에 복사. 성공 여부를 boolean으로 반환.
+ *
+ * 클릭 등 사용자 제스처 핸들러에서 직접 호출해야 한다(앞에 await가 끼면 제스처가 풀려 실패할 수 있음).
+ *
+ * 순서:
+ *  1) execCommand('copy') — 동기 호출이라 제스처가 유지되고, 프리뷰 iframe·비-secure 환경에서도 동작.
+ *  2) Async Clipboard API — execCommand가 막힌 환경(엄격한 CSP 등)을 위한 폴백.
+ */
+export declare function copyText(text: string): Promise<boolean>;

package/dist/packages/core/src/utils/clipboard.js

@@ -0,0 +1,46 @@
+/**
+ * 텍스트를 클립보드에 복사. 성공 여부를 boolean으로 반환.
+ *
+ * 클릭 등 사용자 제스처 핸들러에서 직접 호출해야 한다(앞에 await가 끼면 제스처가 풀려 실패할 수 있음).
+ *
+ * 순서:
+ *  1) execCommand('copy') — 동기 호출이라 제스처가 유지되고, 프리뷰 iframe·비-secure 환경에서도 동작.
+ *  2) Async Clipboard API — execCommand가 막힌 환경(엄격한 CSP 등)을 위한 폴백.
+ */
+export async function copyText(text) {
+    // 1순위: execCommand (동기 — 제스처 유지, iframe 대응)
+    if (typeof document !== 'undefined') {
+        try {
+            const ta = document.createElement('textarea');
+            ta.value = text;
+            ta.setAttribute('readonly', '');
+            ta.style.position = 'fixed';
+            ta.style.top = '0';
+            ta.style.left = '0';
+            ta.style.opacity = '0';
+            ta.style.pointerEvents = 'none';
+            document.body.appendChild(ta);
+            ta.focus();
+            ta.select();
+            ta.setSelectionRange(0, text.length);
+            const ok = document.execCommand('copy');
+            document.body.removeChild(ta);
+            if (ok)
+                return true;
+        }
+        catch {
+            /* 폴백으로 진행 */
+        }
+    }
+    // 2순위: Async Clipboard API
+    try {
+        if (typeof navigator !== 'undefined' && navigator.clipboard && typeof navigator.clipboard.writeText === 'function') {
+            await navigator.clipboard.writeText(text);
+            return true;
+        }
+    }
+    catch {
+        /* 무시 */
+    }
+    return false;
+}

package/dist/packages/core/src/utils/companyTypes.d.ts

@@ -0,0 +1,2 @@
+export declare const COMPANY_TYPE_VALUES: readonly ["audiologist", "slp", "hospital", "hearing", "public", "university", "special", "other"];
+export declare function companyTypeLabel(value?: string | null): string;

package/dist/packages/core/src/utils/companyTypes.js

@@ -0,0 +1,6 @@
+export const COMPANY_TYPE_VALUES = [
+    'audiologist', 'slp', 'hospital', 'hearing', 'public', 'university', 'special', 'other',
+];
+export function companyTypeLabel(value) {
+    return value ?? '';
+}

package/dist/packages/core/src/utils/csv.d.ts

@@ -0,0 +1,22 @@
+/**
+ * CSV 한 칸을 안전하게 적는 법 — 한 군데.
+ *
+ * 두 가지를 동시에 막아야 한다.
+ *
+ * 1. **행이 깨지지 않게.** 쉼표·따옴표·줄바꿈이 든 값(고객명에 쉼표, 붙여넣기로 섞인
+ *    캐리지리턴)을 그냥 이으면 열이 밀린다. `\r` 도 줄바꿈으로 세는 파서가 있다 —
+ *    `\r\n` 은 `\n` 덕에 우연히 걸리지만 홀로 있는 `\r` 은 그대로 새어 나가, 그 행부터
+ *    뒤 열이 통째로 밀린다.
+ * 2. **수식으로 실행되지 않게.** `=`·`+`·`-`·`@` 로 시작하는 값을 엑셀·시트가 수식으로
+ *    실행한다(CSV Injection). 탭이나 CR 로 시작하는 경우도 파서가 앞의 공백문자를 버리고
+ *    그다음 글자를 첫 글자로 읽으므로 같은 결과가 된다(OWASP 권고).
+ *
+ * 이 규칙이 두 군데에 따로 적혀 있었고, 고객 목록 쪽 사본이 `\r` 둘 다를 빠뜨린 채
+ * "어드민과 동일한 규칙"이라고 주석까지 달고 있었다.
+ */
+export declare function escapeCsvField(v: unknown): string;
+/**
+ * 브라우저에서 CSV 파일을 내려받게 한다. 앞에 BOM 을 붙인다 — 없으면 엑셀이 한글을
+ * 깨뜨린다.
+ */
+export declare function downloadCsvText(filename: string, csv: string): void;

package/dist/packages/core/src/utils/csv.js

@@ -0,0 +1,35 @@
+/**
+ * CSV 한 칸을 안전하게 적는 법 — 한 군데.
+ *
+ * 두 가지를 동시에 막아야 한다.
+ *
+ * 1. **행이 깨지지 않게.** 쉼표·따옴표·줄바꿈이 든 값(고객명에 쉼표, 붙여넣기로 섞인
+ *    캐리지리턴)을 그냥 이으면 열이 밀린다. `\r` 도 줄바꿈으로 세는 파서가 있다 —
+ *    `\r\n` 은 `\n` 덕에 우연히 걸리지만 홀로 있는 `\r` 은 그대로 새어 나가, 그 행부터
+ *    뒤 열이 통째로 밀린다.
+ * 2. **수식으로 실행되지 않게.** `=`·`+`·`-`·`@` 로 시작하는 값을 엑셀·시트가 수식으로
+ *    실행한다(CSV Injection). 탭이나 CR 로 시작하는 경우도 파서가 앞의 공백문자를 버리고
+ *    그다음 글자를 첫 글자로 읽으므로 같은 결과가 된다(OWASP 권고).
+ *
+ * 이 규칙이 두 군데에 따로 적혀 있었고, 고객 목록 쪽 사본이 `\r` 둘 다를 빠뜨린 채
+ * "어드민과 동일한 규칙"이라고 주석까지 달고 있었다.
+ */
+export function escapeCsvField(v) {
+    let s = v == null ? '' : String(v);
+    if (/^[=+\-@\t\r]/.test(s))
+        s = '\t' + s;
+    return /[",\n\r]/.test(s) ? `"${s.replaceAll('"', '""')}"` : s;
+}
+/**
+ * 브라우저에서 CSV 파일을 내려받게 한다. 앞에 BOM 을 붙인다 — 없으면 엑셀이 한글을
+ * 깨뜨린다.
+ */
+export function downloadCsvText(filename, csv) {
+    const blob = new Blob(['' + csv], { type: 'text/csv;charset=utf-8' });
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement('a');
+    a.href = url;
+    a.download = filename;
+    a.click();
+    URL.revokeObjectURL(url);
+}

package/dist/packages/core/src/utils/cx.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 조건부 className 합치기 유틸.
+ * falsy(''·false·null·undefined) 인자를 걸러 공백으로 join한다.
+ * `['a', cond && 'b', className].filter(Boolean).join(' ')` idiom을 대체한다.
+ * @public
+ */
+export declare function cx(...parts: (string | false | null | undefined)[]): string;

package/dist/packages/core/src/utils/cx.js

@@ -0,0 +1,9 @@
+/**
+ * 조건부 className 합치기 유틸.
+ * falsy(''·false·null·undefined) 인자를 걸러 공백으로 join한다.
+ * `['a', cond && 'b', className].filter(Boolean).join(' ')` idiom을 대체한다.
+ * @public
+ */
+export function cx(...parts) {
+    return parts.filter(Boolean).join(' ');
+}

package/dist/packages/core/src/utils/dailySelectionUtils.d.ts

@@ -0,0 +1,15 @@
+import type { TrainingItem } from '../types/training';
+export type Selection = Record<string, TrainingItem[]>;
+export declare function hasItems(s: Selection | null | undefined): boolean;
+export declare function resolveSelection(_forceRefresh?: boolean, counts?: {
+    LISTEN_IN_NOISE: number;
+    SHORT_STORY: number;
+    LONG_STORY: number;
+    ORDERING_SENTENCE: number;
+}, userId?: string): {
+    today: Selection;
+    yesterday: null;
+} | {
+    today: Selection;
+    yesterday: Selection;
+};

package/dist/packages/core/src/utils/dailySelectionUtils.js

@@ -0,0 +1,68 @@
+import { LONG_STORIES, NOISE_DATAS, ORDER_SETS, SHORT_STORIES } from './getTrainingData';
+import { sample } from './array';
+// KST 기준 'YYYY-MM-DD' — 서버 완료집계/일수와 같은 기준이라야 날짜 경계가 어긋나지 않는다.
+import { toKstYmd } from './date';
+// ─── 시드 PRNG (결정적 추출) ──────────────────────────────────────────────────
+/** 문자열 → 32bit 시드 (FNV-1a 변형) */
+function hashSeed(str) {
+    let h = 2166136261 >>> 0;
+    for (let i = 0; i < str.length; i++) {
+        h ^= str.charCodeAt(i);
+        h = Math.imul(h, 16777619);
+    }
+    return h >>> 0;
+}
+/** mulberry32 — 시드 기반 결정적 난수 [0,1) */
+function mulberry32(seed) {
+    let a = seed >>> 0;
+    return () => {
+        a |= 0;
+        a = (a + 0x6D2B79F5) | 0;
+        let t = Math.imul(a ^ (a >>> 15), 1 | a);
+        t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+// shuffle/sample은 공용 utils/array로 통일(시드 rng 지원 동일). 여기선 sampleArray 이름만 유지해 내부에서 사용.
+const sampleArray = sample;
+// 시드가 주어지면 한 PRNG로 모든 타입을 결정적 추출 → 기기/세션 무관 동일 선택
+function createSelection(counts, seed) {
+    const rng = seed ? mulberry32(hashSeed(seed)) : Math.random;
+    return {
+        LISTEN_IN_NOISE: sampleArray(NOISE_DATAS, Math.max(0, counts.LISTEN_IN_NOISE || 0), rng),
+        SHORT_STORY: sampleArray(SHORT_STORIES, Math.max(0, counts.SHORT_STORY || 0), rng),
+        LONG_STORY: sampleArray(LONG_STORIES, Math.max(0, counts.LONG_STORY || 0), rng),
+        ORDERING_SENTENCE: sampleArray(ORDER_SETS, Math.max(0, counts.ORDERING_SENTENCE || 0), rng),
+    };
+}
+export function hasItems(s) {
+    if (!s)
+        return false;
+    return !!(s.LISTEN_IN_NOISE?.length || s.SHORT_STORY?.length ||
+        s.LONG_STORY?.length || s.ORDERING_SENTENCE?.length);
+}
+// ─── 오늘 훈련 선택 해석/생성 ────────────────────────────────────────────────
+const DEFAULT_TRAINING_COUNTS = {
+    LISTEN_IN_NOISE: 3,
+    SHORT_STORY: 2,
+    LONG_STORY: 1,
+    ORDERING_SENTENCE: 2,
+};
+// userId 시드 → (user, 날짜)별 결정적 선택. 모든 기기/세션에서 동일하므로
+// localStorage 캐시 없이 매번 결정적으로 재계산한다(저장 없음).
+export function resolveSelection(_forceRefresh = false, counts = DEFAULT_TRAINING_COUNTS, userId) {
+    // 서버 완료집계와 동일하게 KST 기준 날짜. userId 없어도 날짜로 결정적(Math.random 비결정성 제거)
+    const today = toKstYmd(Date.now());
+    const yesterday = toKstYmd(Date.now() - 86400000);
+    const seedToday = `${userId ?? ''}|${today}`;
+    const seedYesterday = `${userId ?? ''}|${yesterday}`;
+    const hasSource = NOISE_DATAS.length > 0 || SHORT_STORIES.length > 0 ||
+        LONG_STORIES.length > 0 || ORDER_SETS.length > 0;
+    if (!hasSource) {
+        return { today: createSelection(counts, seedToday), yesterday: null };
+    }
+    return {
+        today: createSelection(counts, seedToday),
+        yesterday: createSelection(counts, seedYesterday),
+    };
+}

package/dist/packages/core/src/utils/date.d.ts

@@ -0,0 +1,86 @@
+/**
+ * 날짜 포맷 유틸 — 산재한 Date 파싱 로직을 공유.
+ * 각 화면의 표시 형식 차이는 옵션으로 흡수.
+ */
+export declare function formatDateKo(iso: string): string;
+/** "2024년 1월 15일 오후 03:30" (long month + time) */
+export declare function formatDateLongKo(iso: string): string;
+/**
+ * 로케일 인식 날짜 포맷 — formatDateKo와 달리 en 로케일에선 "Jan 15, 2024"로 표시된다.
+ * t()로 번역되는 문장 안에 날짜값을 끼워 넣는 곳(예: "{{name}}님께 {{date}}에 전송")에서
+ * formatDateKo를 그대로 쓰면 en 로케일 문장에도 한국어 날짜 형식이 섞여 나온다.
+ * @param lang useTranslation()의 i18n.language
+ */
+export declare function formatDateLocale(iso: string, lang: string): string;
+/** formatDateLongKo의 로케일 인식 버전 — en: "January 15, 2024, 03:30 PM" */
+export declare function formatDateLongLocale(iso: string, lang: string): string;
+/** "2024. 01. 15. 오후 03:30" (2-digit month + time) */
+export declare function formatDatetimeKo(iso: string): string;
+/**
+ * KST 기준 '시:분'(24시간, 두 자리).
+ *
+ * 날짜는 toKstYmd·formatYmd 가 KST 로 읽는데, 시각을 곁들여 적는 자리는 각자
+ * `getHours()/getMinutes()` 로 읽고 있었다 — 그러면 날짜는 KST, 시각은 기기
+ * 시간대가 되어 **한 줄 안에서 기준이 갈린다.** 시각도 여기 한 벌로 읽는다.
+ *
+ * @public
+ */
+export declare function toKstHm(when?: string | number | Date | null): string;
+/** KST(Asia/Seoul) 기준 오늘 날짜를 'YYYY-MM-DD'로 반환. DB 날짜 비교 기준선으로 사용. */
+export declare function getTodayKst(): string;
+/**
+ * 'YYYY-MM-DD' 날짜 전용 문자열(예: 서버가 KST 기준으로 집계해 내려주는 log_date)을
+ * 로컬 타임존 자정 Date로 파싱한다. new Date('YYYY-MM-DD')는 UTC 자정으로 해석되어,
+ * UTC보다 서쪽 시간대(예: 미국)에서 getDate()/getMonth() 같은 로컬 getter로 읽으면
+ * 하루 전으로 밀린다 — 차트를 날짜별로 버킷팅할 때 특히 문제가 된다.
+ */
+export declare function parseLocalYmd(ymd: string): Date;
+/**
+ * 어떤 시각이든 KST 달력 날짜 'YYYY-MM-DD'로 옮긴다.
+ * `iso.slice(0,10)`은 UTC 날짜라 자정~9시(KST) 사이 값은 하루 어긋난다.
+ *
+ * ISO 문자열뿐 아니라 Date 와 epoch ms 도 받는다. 같은 계산이 저장소 곳곳에
+ * `toLocaleDateString('en-CA', { timeZone: 'Asia/Seoul' })` 로 따로 적혀 있었는데,
+ * 문자열이 아닌 값을 넘길 수 없어서 그랬다. ('en-CA' 와 'fr-CA' 는 이 용도에서 같은
+ * 문자열을 낸다 — 연·월·일 경계 표본으로 대조했다.)
+ *
+ * 빈 값·못 읽는 값은 빈 문자열이다. 0(epoch)은 유효한 값이라 그대로 옮긴다.
+ */
+export declare function toKstYmd(when?: string | number | Date | null): string;
+type TranslateFn = import('i18next').TFunction;
+/**
+ * ISO 문자열을 'store.time.*' i18n 키 기반 상대시간 문자열로 변환.
+ * (예: 방금 전 / N분 전 / N시간 전 / N일 전 …)
+ * 빈/유효하지 않은 입력은 빈 문자열을 반환한다.
+ */
+export declare function formatRelativeTime(input: string | null | undefined, t: TranslateFn): string;
+export interface FormatYmdOptions {
+    /** 연·월·일 구분자 (기본 '.') */
+    sep?: string;
+    /** 월·일 두 자리 zero-pad 여부 (기본 true) */
+    pad?: boolean;
+    /** 끝에 마침표 추가 여부 (기본 false) */
+    trailingDot?: boolean;
+    /** 파싱 불가/빈 입력 시 반환값 (기본 '—') */
+    fallback?: string;
+}
+/**
+ * ISO 문자열 또는 Date를 'YYYY{sep}MM{sep}DD' 형태로 포맷.
+ *
+ * **날짜는 KST 달력으로 읽는다 — 기계의 지역 날짜가 아니다.**
+ *
+ * 예전에는 `getFullYear()/getMonth()/getDate()` 로 읽었다. 그건 보는 사람의 기기
+ * 시간대를 따르므로, KST 밖에서는 **하루 어긋난 날짜가 화면에 뜬다**: 서버가
+ * `2026-08-01T00:00:00Z`(= KST 8/1 오전 9시)로 준 등록일이 뉴욕에서는 7월 31일로
+ * 보인다. 날짜만 있는 값('YYYY-MM-DD')도 UTC 자정으로 파싱되어 같은 방향으로 밀린다.
+ *
+ * 이웃 함수 normalizeDate 가 똑같은 일을 겪고 이미 toKstYmd 로 옮겼는데(그 주석에
+ * 경위가 있다) 이 함수만 옛 꼴로 남아 있었다. 셈은 한 곳에서만 한다.
+ * (TZ=America/New_York 으로 시험을 돌리자 그대로 잡혔다.)
+ *
+ * @example
+ * formatYmd('2026-05-01')                          // '2026.05.01'
+ * formatYmd('2026-05-01', { sep: '. ', pad: false, trailingDot: true }) // '2026. 5. 1.'
+ */
+export declare function formatYmd(input?: string | Date | null, opts?: FormatYmdOptions): string;
+export {};

package/dist/packages/core/src/utils/date.js

@@ -0,0 +1,171 @@
+/**
+ * 날짜 포맷 유틸 — 산재한 Date 파싱 로직을 공유.
+ * 각 화면의 표시 형식 차이는 옵션으로 흡수.
+ */
+/** "2024년 1월 15일" */
+/**
+ * 이 저장소의 날짜·시각은 **KST 하나로 읽는다.**
+ *
+ * `toLocaleDateString(locale, …)` 을 시간대 없이 부르면 **보는 사람의 기기 시간대**로
+ * 그린다. 그런데 서버는 KST 로 집계하고, 목록도 KST 달력으로 거르고, 같은 파일의
+ * toKstYmd·formatYmd 도 KST 로 읽는다. 여기만 기기를 따르면 같은 값이 화면마다 다른
+ * 날로 보인다 — 서버가 준 `2026-08-01T00:00:00Z`(= KST 8/1 오전 9시)가 뉴욕에서는
+ * 7월 31일이 된다.
+ *
+ * 로케일(ko/en)은 **글자 모양**의 문제이고, 시간대는 **어느 날인가**의 문제다.
+ * 영어로 보더라도 가리키는 날은 같아야 한다.
+ */
+const KST = 'Asia/Seoul';
+export function formatDateKo(iso) {
+    return new Date(iso).toLocaleDateString('ko-KR', { timeZone: KST, year: 'numeric', month: 'short', day: 'numeric' });
+}
+/** "2024년 1월 15일 오후 03:30" (long month + time) */
+export function formatDateLongKo(iso) {
+    return new Date(iso).toLocaleString('ko-KR', {
+        timeZone: KST,
+        year: 'numeric', month: 'long', day: 'numeric',
+        hour: '2-digit', minute: '2-digit',
+    });
+}
+/**
+ * 로케일 인식 날짜 포맷 — formatDateKo와 달리 en 로케일에선 "Jan 15, 2024"로 표시된다.
+ * t()로 번역되는 문장 안에 날짜값을 끼워 넣는 곳(예: "{{name}}님께 {{date}}에 전송")에서
+ * formatDateKo를 그대로 쓰면 en 로케일 문장에도 한국어 날짜 형식이 섞여 나온다.
+ * @param lang useTranslation()의 i18n.language
+ */
+export function formatDateLocale(iso, lang) {
+    const locale = lang.startsWith('ko') ? 'ko-KR' : 'en-US';
+    return new Date(iso).toLocaleDateString(locale, { timeZone: KST, year: 'numeric', month: 'short', day: 'numeric' });
+}
+/** formatDateLongKo의 로케일 인식 버전 — en: "January 15, 2024, 03:30 PM" */
+export function formatDateLongLocale(iso, lang) {
+    const locale = lang.startsWith('ko') ? 'ko-KR' : 'en-US';
+    return new Date(iso).toLocaleString(locale, {
+        timeZone: KST,
+        year: 'numeric', month: 'long', day: 'numeric',
+        hour: '2-digit', minute: '2-digit',
+    });
+}
+/** "2024. 01. 15. 오후 03:30" (2-digit month + time) */
+export function formatDatetimeKo(iso) {
+    return new Date(iso).toLocaleString('ko-KR', {
+        timeZone: KST,
+        year: 'numeric', month: '2-digit', day: '2-digit',
+        hour: '2-digit', minute: '2-digit',
+    });
+}
+/**
+ * KST 기준 '시:분'(24시간, 두 자리).
+ *
+ * 날짜는 toKstYmd·formatYmd 가 KST 로 읽는데, 시각을 곁들여 적는 자리는 각자
+ * `getHours()/getMinutes()` 로 읽고 있었다 — 그러면 날짜는 KST, 시각은 기기
+ * 시간대가 되어 **한 줄 안에서 기준이 갈린다.** 시각도 여기 한 벌로 읽는다.
+ *
+ * @public
+ */
+export function toKstHm(when) {
+    if (when === null || when === undefined || when === '')
+        return '';
+    const d = when instanceof Date ? when : new Date(when);
+    if (isNaN(d.getTime()))
+        return '';
+    return new Intl.DateTimeFormat('en-GB', {
+        timeZone: KST, hour: '2-digit', minute: '2-digit', hour12: false,
+    }).format(d);
+}
+/** KST(Asia/Seoul) 기준 오늘 날짜를 'YYYY-MM-DD'로 반환. DB 날짜 비교 기준선으로 사용. */
+export function getTodayKst() {
+    return toKstYmd(new Date());
+}
+/**
+ * 'YYYY-MM-DD' 날짜 전용 문자열(예: 서버가 KST 기준으로 집계해 내려주는 log_date)을
+ * 로컬 타임존 자정 Date로 파싱한다. new Date('YYYY-MM-DD')는 UTC 자정으로 해석되어,
+ * UTC보다 서쪽 시간대(예: 미국)에서 getDate()/getMonth() 같은 로컬 getter로 읽으면
+ * 하루 전으로 밀린다 — 차트를 날짜별로 버킷팅할 때 특히 문제가 된다.
+ */
+export function parseLocalYmd(ymd) {
+    const [y, m, d] = ymd.split('-').map(Number);
+    return new Date(y, (m || 1) - 1, d || 1);
+}
+/**
+ * 어떤 시각이든 KST 달력 날짜 'YYYY-MM-DD'로 옮긴다.
+ * `iso.slice(0,10)`은 UTC 날짜라 자정~9시(KST) 사이 값은 하루 어긋난다.
+ *
+ * ISO 문자열뿐 아니라 Date 와 epoch ms 도 받는다. 같은 계산이 저장소 곳곳에
+ * `toLocaleDateString('en-CA', { timeZone: 'Asia/Seoul' })` 로 따로 적혀 있었는데,
+ * 문자열이 아닌 값을 넘길 수 없어서 그랬다. ('en-CA' 와 'fr-CA' 는 이 용도에서 같은
+ * 문자열을 낸다 — 연·월·일 경계 표본으로 대조했다.)
+ *
+ * 빈 값·못 읽는 값은 빈 문자열이다. 0(epoch)은 유효한 값이라 그대로 옮긴다.
+ */
+export function toKstYmd(when) {
+    if (when === null || when === undefined || when === '')
+        return '';
+    const d = when instanceof Date ? when : new Date(when);
+    if (isNaN(d.getTime()))
+        return '';
+    return new Intl.DateTimeFormat('fr-CA', { timeZone: 'Asia/Seoul' }).format(d);
+}
+/**
+ * ISO 문자열을 'store.time.*' i18n 키 기반 상대시간 문자열로 변환.
+ * (예: 방금 전 / N분 전 / N시간 전 / N일 전 …)
+ * 빈/유효하지 않은 입력은 빈 문자열을 반환한다.
+ */
+export function formatRelativeTime(input, t) {
+    if (!input)
+        return '';
+    const then = new Date(input).getTime();
+    if (Number.isNaN(then))
+        return '';
+    const sec = Math.max(0, Math.floor((Date.now() - then) / 1000));
+    const min = Math.floor(sec / 60), hour = Math.floor(min / 60), day = Math.floor(hour / 24);
+    const week = Math.floor(day / 7), month = Math.floor(day / 30), year = Math.floor(day / 365);
+    if (min < 1)
+        return t('store.time.justNow', '방금 전');
+    if (min < 60)
+        return t('store.time.minutesAgo', { n: min });
+    if (hour < 24)
+        return t('store.time.hoursAgo', { n: hour });
+    if (day < 7)
+        return t('store.time.daysAgo', { n: day });
+    if (week < 5)
+        return t('store.time.weeksAgo', { n: week });
+    // 연 단위 전환은 **365일**을 기준으로 한다. 예전엔 month(=day/30)가 12가 되는 순간
+    // 넘겼는데, 그 시점(day 360)의 year(=day/365)는 아직 0이라 **"0년 전"** 이 나왔다
+    // (실측: day 360~364 → yearsAgo{n=0}).
+    // month 를 11로 조이는 이유: 360~364일을 "12개월 전" 이라 하면 "1년 전" 과 같은 말이라
+    // 어색하다. 이미 330~359일이 "11개월 전" 이므로 그 구간에 붙인다.
+    if (day < 365)
+        return t('store.time.monthsAgo', { n: Math.min(month, 11) });
+    return t('store.time.yearsAgo', { n: year });
+}
+/**
+ * ISO 문자열 또는 Date를 'YYYY{sep}MM{sep}DD' 형태로 포맷.
+ *
+ * **날짜는 KST 달력으로 읽는다 — 기계의 지역 날짜가 아니다.**
+ *
+ * 예전에는 `getFullYear()/getMonth()/getDate()` 로 읽었다. 그건 보는 사람의 기기
+ * 시간대를 따르므로, KST 밖에서는 **하루 어긋난 날짜가 화면에 뜬다**: 서버가
+ * `2026-08-01T00:00:00Z`(= KST 8/1 오전 9시)로 준 등록일이 뉴욕에서는 7월 31일로
+ * 보인다. 날짜만 있는 값('YYYY-MM-DD')도 UTC 자정으로 파싱되어 같은 방향으로 밀린다.
+ *
+ * 이웃 함수 normalizeDate 가 똑같은 일을 겪고 이미 toKstYmd 로 옮겼는데(그 주석에
+ * 경위가 있다) 이 함수만 옛 꼴로 남아 있었다. 셈은 한 곳에서만 한다.
+ * (TZ=America/New_York 으로 시험을 돌리자 그대로 잡혔다.)
+ *
+ * @example
+ * formatYmd('2026-05-01')                          // '2026.05.01'
+ * formatYmd('2026-05-01', { sep: '. ', pad: false, trailingDot: true }) // '2026. 5. 1.'
+ */
+export function formatYmd(input, opts = {}) {
+    const { sep = '.', pad = true, trailingDot = false, fallback = '—' } = opts;
+    if (!input)
+        return fallback;
+    const ymd = toKstYmd(input instanceof Date ? input : String(input));
+    if (!ymd)
+        return fallback;
+    const [y, mm, dd] = ymd.split('-');
+    const m = pad ? mm : String(Number(mm));
+    const day = pad ? dd : String(Number(dd));
+    return `${y}${sep}${m}${sep}${day}${trailingDot ? '.' : ''}`;
+}

package/dist/packages/core/src/utils/deviceKind.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 기기 종류(보청기·인공와우·기타)에 붙는 배지 색.
+ *
+ * 표(DeviceSideTable)와 '사용중인 기기' 패널(PanelRowDevice)이 같은 값을 각자
+ * 그리므로 **규칙을 한 곳에 둔다** — 두 곳에서 따로 정하면 같은 인공와우가 한쪽은
+ * 파랑, 한쪽은 초록으로 떠서 다른 것인 줄 알게 된다.
+ *
+ * 값은 저장된 그대로의 한국어다(managed_device.type). 목록에 없는 값·빈 값은
+ * 'default'(무채색)로 떨어뜨린다 — 모르는 종류를 아는 색으로 칠하지 않는다.
+ *
+ * @public
+ */
+export declare function deviceKindVariant(device: string | null | undefined): string;

package/dist/packages/core/src/utils/deviceKind.js

@@ -0,0 +1,19 @@
+/**
+ * 기기 종류(보청기·인공와우·기타)에 붙는 배지 색.
+ *
+ * 표(DeviceSideTable)와 '사용중인 기기' 패널(PanelRowDevice)이 같은 값을 각자
+ * 그리므로 **규칙을 한 곳에 둔다** — 두 곳에서 따로 정하면 같은 인공와우가 한쪽은
+ * 파랑, 한쪽은 초록으로 떠서 다른 것인 줄 알게 된다.
+ *
+ * 값은 저장된 그대로의 한국어다(managed_device.type). 목록에 없는 값·빈 값은
+ * 'default'(무채색)로 떨어뜨린다 — 모르는 종류를 아는 색으로 칠하지 않는다.
+ *
+ * @public
+ */
+export function deviceKindVariant(device) {
+    switch (device) {
+        case '보청기': return 'main';
+        case '인공와우': return 'sub';
+        default: return 'default';
+    }
+}

package/dist/packages/core/src/utils/encoding.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 문자열을 UTF-8 바이트로 인코딩 후 소문자 hex 문자열로 반환.
+ * 스토리지 파일명에 사용 — hex는 단일 케이스(0-9a-f)라 대소문자를 구분하지 않는
+ * 파일시스템(macOS APFS 등)에서도 절대 충돌하지 않는다.
+ *   가  →  eab080
+ * @public
+ */
+export declare function toStorageName(text: string): string;
+/**
+ * @deprecated 대소문자 충돌 위험으로 사용 중단. 스토리지 파일명은 {@link toStorageName}(hex) 사용.
+ * 외부 호환을 위해 별칭만 유지한다.
+ * @public
+ */
+export declare const toBase64UrlSafe: typeof toStorageName;
+/**
+ * @public 정식 음원이 저장소에 놓이는 자리.
+ *
+ * `{목소리}/{표준발음을 hex 로}.mp3` — 어드민(검수 화면)과 회원 앱(재생)이 **같은 자리를
+ * 가리켜야 한다**. 다르면 어드민에서는 "있다"고 보이는데 회원 앱에서는 안 나오는(또는 그
+ * 반대) 상태가 되고, 그건 파일이 없는 것과 구별되지 않는다.
+ *
+ * 실시간 합성이 만들어 두는 `{목소리}/auto/…` 캐시는 여기 해당하지 않는다 — 그건
+ * '아직 없어서 임시로 만든 것'이라, 정식 음원과 같은 자리로 세면 채워야 할 낱말이
+ * 채워진 것처럼 보인다.
+ */
+export declare function officialSoundPath(voiceType: string, pronunciation: string): string;