@ihabdevteam/core 0.8.0

package/dist/packages/core/src/hooks/useEditableList.js

@@ -0,0 +1,73 @@
+'use client';
+import { useCallback, useEffect, useRef, useState } from 'react';
+/**
+ * 목록 + 선택 항목 + 편집 폼 상태를 통합하는 제네릭 훅.
+ *
+ * @public
+ */
+export function useEditableList(emptyItem, initialList = []) {
+    const [list, setList] = useState(initialList);
+    const [selected, setSelected] = useState(null);
+    const [isEditing, setIsEditing] = useState(false);
+    const [editForm, setEditForm] = useState(emptyItem);
+    // initialList(호출부에서 넘기는 prop 기반 초기 목록, 예: visits)가 팝업이 이미 열린 뒤에
+    // 뒤늦게 도착하거나 갱신되는 경우를 반영한다. useState(initialList)는 최초 마운트 시점의
+    // 값만 캡처하므로 이 effect가 없으면 이후 prop 변경이 화면에 전혀 반영되지 않는다.
+    // 단, 사용자가 이 목록의 항목을 수정 중(isEditing)일 때 리셋하면 아직 list에 반영되지
+    // 않은 진행 중인 편집(editForm)이 저장 시 조용히 무시될 수 있으므로 그 사이엔 건너뛴다.
+    // isEditing은 ref로만 참조해 effect가 initialList 변경 시에만 실행되게 한다 — 편집을
+    // 끝내는 순간(isEditing만 바뀌는 렌더)에는 재실행되지 않아, 방금 커밋된 편집 결과가
+    // 곧바로 stale한 initialList로 덮어써지는 것도 막는다.
+    //
+    // 비교는 참조가 아니라 **내용**으로 한다. 호출부가 배열을 인라인으로 넘기면
+    // (useEditableList(EMPTY, [a, b]) — 가장 자연스러운 호출 방식이고, 인자를 생략해
+    // 기본값 []를 쓸 때도 마찬가지다) 렌더마다 참조가 새로 생긴다. 참조로 비교하면
+    // 그때마다 이 effect가 다시 돌아 setList → 리렌더 → 새 참조 → effect … 로
+    // 무한 루프가 되고, 그 사이 remove/setList로 바꾼 목록이 곧바로 initialList로
+    // 되돌아간다(내용이 그대로인데도). 실측으로 확인한 동작이다.
+    /* 갱신은 렌더가 아니라 효과에서 한다 — 렌더 중에 쓰면 커밋되지 않을 렌더의 값이 남는다.
+       읽는 곳은 바로 아래 동기화 효과뿐이고, 그것이 뒤에 선언돼 있어 순서도 맞다.
+       (효과는 선언 순서대로 돈다.) */
+    const isEditingRef = useRef(isEditing);
+    useEffect(() => { isEditingRef.current = isEditing; });
+    const prevInitialRef = useRef(null);
+    useEffect(() => {
+        if (isEditingRef.current)
+            return;
+        const prev = prevInitialRef.current;
+        const same = prev !== null
+            && prev.length === initialList.length
+            && prev.every((v, i) => v === initialList[i]);
+        if (same)
+            return;
+        prevInitialRef.current = initialList;
+        setList(initialList);
+    }, [initialList]);
+    const openDetail = useCallback((item) => {
+        setSelected(item);
+        setIsEditing(false);
+        setEditForm({ ...item });
+    }, []);
+    const startEditing = useCallback(() => setIsEditing(true), []);
+    const cancelEditing = useCallback(() => setIsEditing(false), []);
+    const commitEdit = useCallback((updater, updated) => {
+        setList(updater);
+        setSelected(updated);
+        setIsEditing(false);
+    }, []);
+    const remove = useCallback((item) => {
+        setList(prev => prev.filter(v => v !== item));
+        setSelected(null);
+    }, []);
+    return {
+        list, setList,
+        selected, setSelected,
+        isEditing, setIsEditing,
+        editForm, setEditForm,
+        openDetail,
+        startEditing,
+        cancelEditing,
+        commitEdit,
+        remove,
+    };
+}

package/dist/packages/core/src/hooks/useEscToClose.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Esc 키를 누르면 onClose를 호출하는 훅.
+ * 모달/다이얼로그 오버레이의 키보드 접근성을 위해 사용.
+ * handler는 ref로 래핑하므로 매번 새 함수를 넘겨도 재구독하지 않음.
+ *
+ * 공유 ESC 스택(escStack)에 등록하므로, 여러 오버레이가 쌓여 있어도
+ * ESC는 가장 최근에 열린(최상단) 것 하나만 닫는다.
+ *
+ * @param onClose Esc 입력 시 호출할 콜백
+ * @param enabled false면 리스너를 등록하지 않음 (기본 true)
+ *
+ * @example
+ * useEscToClose(onCancel)
+ */
+/**
+ * @public
+ */
+export declare function useEscToClose(onClose?: () => void, enabled?: boolean): void;
+export default useEscToClose;

package/dist/packages/core/src/hooks/useEscToClose.js

@@ -0,0 +1,30 @@
+'use client';
+import { useEffect } from 'react';
+import { pushEsc } from './escStack';
+import { useLatestRef } from './useLatestRef';
+/**
+ * Esc 키를 누르면 onClose를 호출하는 훅.
+ * 모달/다이얼로그 오버레이의 키보드 접근성을 위해 사용.
+ * handler는 ref로 래핑하므로 매번 새 함수를 넘겨도 재구독하지 않음.
+ *
+ * 공유 ESC 스택(escStack)에 등록하므로, 여러 오버레이가 쌓여 있어도
+ * ESC는 가장 최근에 열린(최상단) 것 하나만 닫는다.
+ *
+ * @param onClose Esc 입력 시 호출할 콜백
+ * @param enabled false면 리스너를 등록하지 않음 (기본 true)
+ *
+ * @example
+ * useEscToClose(onCancel)
+ */
+/**
+ * @public
+ */
+export function useEscToClose(onClose, enabled = true) {
+    const onCloseRef = useLatestRef(onClose);
+    useEffect(() => {
+        if (!enabled)
+            return;
+        return pushEsc(() => { onCloseRef.current?.(); });
+    }, [enabled, onCloseRef]);
+}
+export default useEscToClose;

package/dist/packages/core/src/hooks/useFocusTrap.d.ts

@@ -0,0 +1,19 @@
+import { type RefObject } from 'react';
+/**
+ * 다이얼로그 안에서 Tab 이 빠져나가지 못하게 가둔다 — WAI-ARIA 다이얼로그 패턴.
+ *
+ * 같은 열두 줄이 **네 곳**에 그대로 있었다(Popup · PagePopup · InquiryPopup ·
+ * TrainingPagePopup). 그리고 이미 갈라져 있었다 —
+ *   · 고르개 문자열이 네 벌인데 그중 하나는 공백까지 달랐고(`FOCUSABLE_SELECTORS`),
+ *   · InquiryPopup 은 상수를 안 쓰고 문자열을 제 안에 박아 뒀다.
+ * 고르개를 고칠 일이 생기면(예: `[contenteditable]` 을 더한다) 한 곳만 고치고 나머지
+ * 셋은 뒤처진다 — 그러면 어떤 팝업에서만 Tab 이 배경으로 새는데, 눈으로는 안 보인다.
+ *
+ * @param panelRef 가둘 판
+ * @param enabled  false 면 걸지 않는다(InquiryPopup 은 inline 으로도 쓰인다 —
+ *                 그때는 다이얼로그가 아니라 페이지 안의 한 조각이다)
+ * @public
+ */
+export declare function useFocusTrap(panelRef: RefObject<HTMLElement | null>, enabled?: boolean): void;
+/** 포커스를 받을 수 있는 것들 — 가둠과 '열 때 첫 칸으로'가 같은 기준을 쓴다 @public */
+export declare const FOCUSABLE_SELECTOR = "a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex=\"-1\"])";

package/dist/packages/core/src/hooks/useFocusTrap.js

@@ -0,0 +1,50 @@
+'use client';
+import { useEffect } from 'react';
+/**
+ * 다이얼로그 안에서 Tab 이 빠져나가지 못하게 가둔다 — WAI-ARIA 다이얼로그 패턴.
+ *
+ * 같은 열두 줄이 **네 곳**에 그대로 있었다(Popup · PagePopup · InquiryPopup ·
+ * TrainingPagePopup). 그리고 이미 갈라져 있었다 —
+ *   · 고르개 문자열이 네 벌인데 그중 하나는 공백까지 달랐고(`FOCUSABLE_SELECTORS`),
+ *   · InquiryPopup 은 상수를 안 쓰고 문자열을 제 안에 박아 뒀다.
+ * 고르개를 고칠 일이 생기면(예: `[contenteditable]` 을 더한다) 한 곳만 고치고 나머지
+ * 셋은 뒤처진다 — 그러면 어떤 팝업에서만 Tab 이 배경으로 새는데, 눈으로는 안 보인다.
+ *
+ * @param panelRef 가둘 판
+ * @param enabled  false 면 걸지 않는다(InquiryPopup 은 inline 으로도 쓰인다 —
+ *                 그때는 다이얼로그가 아니라 페이지 안의 한 조각이다)
+ * @public
+ */
+export function useFocusTrap(panelRef, enabled = true) {
+    useEffect(() => {
+        if (!enabled)
+            return;
+        const panel = panelRef.current;
+        if (!panel)
+            return;
+        const handleKeyDown = (e) => {
+            if (e.key !== 'Tab')
+                return;
+            const focusables = Array.from(panel.querySelectorAll(FOCUSABLE_SELECTOR));
+            /* 안에 갈 곳이 없으면 Tab 자체를 막는다 — 안 막으면 배경으로 나간다 */
+            if (!focusables.length) {
+                e.preventDefault();
+                return;
+            }
+            const first = focusables[0];
+            const last = focusables[focusables.length - 1];
+            if (e.shiftKey && document.activeElement === first) {
+                e.preventDefault();
+                last.focus();
+            }
+            else if (!e.shiftKey && document.activeElement === last) {
+                e.preventDefault();
+                first.focus();
+            }
+        };
+        panel.addEventListener('keydown', handleKeyDown);
+        return () => panel.removeEventListener('keydown', handleKeyDown);
+    }, [panelRef, enabled]);
+}
+/** 포커스를 받을 수 있는 것들 — 가둠과 '열 때 첫 칸으로'가 같은 기준을 쓴다 @public */
+export const FOCUSABLE_SELECTOR = 'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';

package/dist/packages/core/src/hooks/useFontScale.d.ts

@@ -0,0 +1,20 @@
+/** @public */
+export type UseFontScaleOptions = {
+    storageKey?: string;
+    baseFont?: number;
+    minScale?: number;
+    maxScale?: number;
+    step?: number;
+    lineHeightRatio?: number;
+};
+/** @public */
+export default function useFontScale({ storageKey, baseFont, minScale, maxScale, step, lineHeightRatio, }?: UseFontScaleOptions): {
+    scale: number;
+    setScale: (v: number | ((s: number) => number)) => void;
+    increase: () => void;
+    decrease: () => void;
+    canIncrease: boolean;
+    canDecrease: boolean;
+    fontSize: number;
+    lineHeight: number;
+};

package/dist/packages/core/src/hooks/useFontScale.js

@@ -0,0 +1,51 @@
+'use client';
+import { useEffect, useState } from 'react';
+/** @public */
+export default function useFontScale({ storageKey = 'fontScale', 
+// 기본값을 중앙화: Training/Tooltip 텍스트 박스 공통값
+baseFont = 20, minScale = 0.8, maxScale = 1.4, step = 0.1, lineHeightRatio = 1.4, } = {}) {
+    const clamp = (v) => Math.max(minScale, Math.min(maxScale, Number(v)));
+    const [scale, setScaleRaw] = useState(() => {
+        try {
+            const raw = localStorage.getItem(storageKey);
+            const parsed = raw ? Number(raw) : 1;
+            // 손상된/비숫자 저장값(Number(raw) === NaN)이 그대로 초기값이 되면 scale이 NaN으로
+            // 고정되어 canIncrease/canDecrease 비교가 항상 false가 되고 fontSize/lineHeight도
+            // NaN이 된다 — 파싱 실패 시 기본값(1)으로 폴백한다.
+            return Number.isFinite(parsed) ? parsed : 1;
+        }
+        catch (e) {
+            return 1;
+        }
+    });
+    useEffect(() => {
+        try {
+            localStorage.setItem(storageKey, String(scale));
+        }
+        catch (e) { }
+    }, [storageKey, scale]);
+    const setScale = (v) => {
+        if (typeof v === 'function') {
+            setScaleRaw((s) => clamp(v(s)));
+        }
+        else {
+            setScaleRaw(clamp(v));
+        }
+    };
+    const increase = () => setScale((s) => +(s + step).toFixed(6));
+    const decrease = () => setScale((s) => +(s - step).toFixed(6));
+    const canIncrease = scale < maxScale - Number.EPSILON;
+    const canDecrease = scale > minScale + Number.EPSILON;
+    const fontSize = Math.round(baseFont * scale);
+    const lineHeight = Math.round(fontSize * lineHeightRatio);
+    return {
+        scale,
+        setScale,
+        increase,
+        decrease,
+        canIncrease,
+        canDecrease,
+        fontSize,
+        lineHeight,
+    };
+}

package/dist/packages/core/src/hooks/useHoverAnchor.d.ts

@@ -0,0 +1,33 @@
+/** getBoundingClientRect()만 있으면 되는 최소 인터페이스(주로 이벤트의 currentTarget). */
+type Rectable = {
+    getBoundingClientRect(): DOMRect;
+};
+/**
+ * @public 호버/포커스로 여는 툴팁의 앵커 rect 상태 훅.
+ * "?" 정보버튼·단어 카드·음소 선택칩 등이 마우스를 올린 요소의 위치(DOMRect)를
+ * 잡아 Tooltip을 그 자리에 띄우는 관용구를 한곳으로 모은다. 렌더링·이벤트 바인딩은
+ * 사용하는 쪽에서 하고, 이 훅은 앵커 위치 상태(열림 여부 포함)만 소유한다.
+ */
+export declare function useHoverAnchor(): {
+    anchorRect: DOMRect | null;
+    isOpen: boolean;
+    openAt: (el: Rectable) => void;
+    close: () => void;
+    toggleAt: (el: Rectable) => void;
+};
+/**
+ * @public 마우스를 잠깐 올려 두어야 열리는 미리보기 툴팁의 상태 훅.
+ *
+ * {@link useHoverAnchor} 와 두 가지가 다르다 — **뜸을 들이고**(지나가는 마우스에 툴팁이
+ * 번쩍이지 않게), **무엇을 보여 줄지도 함께 들고 있다**(어느 훈련 카드인지 등).
+ *
+ * 말귀자료실 카드와 훈련 설정 카드가 이 관용구를 한 벌씩 따로 적어 두고 있었다. 타이머를
+ * 지우는 뒷정리가 빠지면 화면을 떠난 뒤에 setState 가 불리므로, 그 부분까지 여기 담는다.
+ */
+export declare function useDelayedHoverAnchor<T>(delayMs: number): {
+    payload: T | null;
+    anchorRect: DOMRect | null;
+    openAfterDelay: (next: T, rect: DOMRect) => void;
+    close: () => void;
+};
+export {};

package/dist/packages/core/src/hooks/useHoverAnchor.js

@@ -0,0 +1,49 @@
+'use client';
+import { useCallback, useEffect, useRef, useState } from 'react';
+/**
+ * @public 호버/포커스로 여는 툴팁의 앵커 rect 상태 훅.
+ * "?" 정보버튼·단어 카드·음소 선택칩 등이 마우스를 올린 요소의 위치(DOMRect)를
+ * 잡아 Tooltip을 그 자리에 띄우는 관용구를 한곳으로 모은다. 렌더링·이벤트 바인딩은
+ * 사용하는 쪽에서 하고, 이 훅은 앵커 위치 상태(열림 여부 포함)만 소유한다.
+ */
+export function useHoverAnchor() {
+    const [anchorRect, setAnchorRect] = useState(null);
+    /** 대상 요소 위치로 툴팁을 연다(보통 openAt(e.currentTarget)). */
+    const openAt = useCallback((el) => setAnchorRect(el.getBoundingClientRect()), []);
+    const close = useCallback(() => setAnchorRect(null), []);
+    /** 열려 있으면 닫고, 닫혀 있으면 대상 위치로 연다(클릭 토글용). */
+    const toggleAt = useCallback((el) => {
+        const rect = el.getBoundingClientRect();
+        setAnchorRect(prev => (prev ? null : rect));
+    }, []);
+    return { anchorRect, isOpen: anchorRect != null, openAt, close, toggleAt };
+}
+/**
+ * @public 마우스를 잠깐 올려 두어야 열리는 미리보기 툴팁의 상태 훅.
+ *
+ * {@link useHoverAnchor} 와 두 가지가 다르다 — **뜸을 들이고**(지나가는 마우스에 툴팁이
+ * 번쩍이지 않게), **무엇을 보여 줄지도 함께 들고 있다**(어느 훈련 카드인지 등).
+ *
+ * 말귀자료실 카드와 훈련 설정 카드가 이 관용구를 한 벌씩 따로 적어 두고 있었다. 타이머를
+ * 지우는 뒷정리가 빠지면 화면을 떠난 뒤에 setState 가 불리므로, 그 부분까지 여기 담는다.
+ */
+export function useDelayedHoverAnchor(delayMs) {
+    const [payload, setPayload] = useState(null);
+    const [anchorRect, setAnchorRect] = useState(null);
+    const timer = useRef(null);
+    /* 화면을 떠날 때 예약된 타이머를 지운다 — 없으면 사라진 컴포넌트에 setState 가 간다 */
+    useEffect(() => () => { if (timer.current)
+        clearTimeout(timer.current); }, []);
+    const openAfterDelay = useCallback((next, rect) => {
+        if (timer.current)
+            clearTimeout(timer.current);
+        timer.current = setTimeout(() => { setPayload(next); setAnchorRect(rect); }, delayMs);
+    }, [delayMs]);
+    const close = useCallback(() => {
+        if (timer.current)
+            clearTimeout(timer.current);
+        setPayload(null);
+        setAnchorRect(null);
+    }, []);
+    return { payload, anchorRect, openAfterDelay, close };
+}

package/dist/packages/core/src/hooks/useIcon.d.ts

@@ -0,0 +1,7 @@
+/** @public */
+export default function useIcon(icon?: string | null): {
+    iconToUse: string | null;
+    mode: "img" | "mask" | "none" | "inline" | null;
+    svgText: string | null;
+    blobUrl: string | null;
+};

package/dist/packages/core/src/hooks/useIcon.js

@@ -0,0 +1,124 @@
+'use client';
+import { useState, useEffect } from 'react';
+import DOMPurify from 'dompurify';
+import { resolveAssetUrl } from '../utils';
+function sanitizeSvg(raw) {
+    if (typeof window === 'undefined')
+        return '';
+    return DOMPurify.sanitize(raw, {
+        USE_PROFILES: { svg: true, svgFilters: true },
+        FORBID_TAGS: ['script', 'use'],
+        FORBID_ATTR: ['xlink:href', 'href'],
+    });
+}
+/** @public */
+export default function useIcon(icon) {
+    const [iconToUse, setIconToUse] = useState(null);
+    const [mode, setMode] = useState(null);
+    const [svgText, setSvgText] = useState(null);
+    const [blobUrl, setBlobUrl] = useState(null);
+    // icon prop이 바뀔 때마다 파생 상태를 리셋/재계산하는 의도된 동기화다
+    /* eslint-disable react-hooks/set-state-in-effect */
+    useEffect(() => {
+        if (!icon || typeof icon !== 'string' || !icon.endsWith('.svg')) {
+            setIconToUse(null);
+            setMode(null);
+            setSvgText(null);
+            return;
+        }
+        const base = icon.split('/').pop();
+        let normalized = icon;
+        if (base) {
+            if (icon.startsWith('/')) {
+                normalized = resolveAssetUrl(icon);
+            }
+            else if (/^(Logo|Symbol)/i.test(base)) {
+                normalized = resolveAssetUrl(`logo/${base}`);
+            }
+            else if (/^https?:\/\//i.test(icon) || icon.startsWith('data:')) {
+                normalized = icon;
+            }
+            else {
+                normalized = icon;
+            }
+        }
+        setIconToUse(normalized);
+    }, [icon]);
+    /* eslint-enable react-hooks/set-state-in-effect */
+    useEffect(() => {
+        if (!iconToUse)
+            return;
+        let canceled = false;
+        async function probe() {
+            try {
+                let res = await fetch(iconToUse);
+                if (!res.ok)
+                    res = await fetch(iconToUse);
+                const ct = res.headers.get('content-type') || '';
+                if (canceled)
+                    return;
+                if (ct.includes('svg')) {
+                    setMode('mask');
+                    return;
+                }
+                if (ct.startsWith('image/')) {
+                    setMode('img');
+                    return;
+                }
+                const textRes = await fetch(iconToUse);
+                if (!textRes.ok)
+                    throw new Error('not ok');
+                const text = await textRes.text();
+                if (canceled)
+                    return;
+                if (/^\s*<svg[\s>]/i.test(text)) {
+                    // DOMPurify로 위험한 스크립트/이벤트 핸들러 제거 후 삽입
+                    const safe = sanitizeSvg(text);
+                    if (!safe) {
+                        setMode('none');
+                        return;
+                    }
+                    setSvgText(safe);
+                    setMode('inline');
+                    return;
+                }
+                setMode('none');
+            }
+            catch (e) {
+                if (!canceled)
+                    setMode('none');
+            }
+        }
+        probe();
+        return () => { canceled = true; };
+    }, [iconToUse]);
+    useEffect(() => {
+        let canceled = false;
+        let created = null;
+        if (mode === 'mask' && iconToUse) {
+            fetch(iconToUse)
+                .then((r) => {
+                if (!r.ok)
+                    throw new Error('fetch failed');
+                return r.blob();
+            })
+                .then((b) => {
+                if (canceled)
+                    return;
+                created = URL.createObjectURL(b);
+                setBlobUrl(created);
+            })
+                .catch(() => {
+                if (!canceled)
+                    setMode('img');
+            });
+        }
+        return () => {
+            canceled = true;
+            if (created)
+                URL.revokeObjectURL(created);
+            setBlobUrl(null);
+        };
+    }, [mode, iconToUse]);
+    return { iconToUse, mode, svgText, blobUrl };
+}

package/dist/packages/core/src/hooks/useLatestRef.d.ts

@@ -0,0 +1,12 @@
+import { type MutableRefObject } from 'react';
+/**
+ * @public
+ * 매 렌더마다 최신 값으로 갱신되는 ref. 콜백을 effect 의존성에 넣지 않고도(=재구독 없이)
+ * 항상 최신 함수를 호출하고 싶을 때 쓴다. 이벤트 리스너/타이머/외부 구독에서 흔한 관용구.
+ *
+ * @example
+ * const onCloseRef = useLatestRef(onClose)
+ * useEffect(() => pushEsc(() => onCloseRef.current?.()), [])
+ */
+export declare function useLatestRef<T>(value: T): MutableRefObject<T>;
+export default useLatestRef;

package/dist/packages/core/src/hooks/useLatestRef.js

@@ -0,0 +1,17 @@
+'use client';
+import { useRef, useEffect } from 'react';
+/**
+ * @public
+ * 매 렌더마다 최신 값으로 갱신되는 ref. 콜백을 effect 의존성에 넣지 않고도(=재구독 없이)
+ * 항상 최신 함수를 호출하고 싶을 때 쓴다. 이벤트 리스너/타이머/외부 구독에서 흔한 관용구.
+ *
+ * @example
+ * const onCloseRef = useLatestRef(onClose)
+ * useEffect(() => pushEsc(() => onCloseRef.current?.()), [])
+ */
+export function useLatestRef(value) {
+    const ref = useRef(value);
+    useEffect(() => { ref.current = value; });
+    return ref;
+}
+export default useLatestRef;

package/dist/packages/core/src/hooks/useLucideIcon.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 아이콘 이름을 받아 lucide 컴포넌트를 돌려줍니다.
+ *
+ * 자주 쓰는 아이콘은 정적으로 번들되어 첫 렌더에, 서버 렌더에서도 바로
+ * 나옵니다. 목록에 없는 이름만 아이콘 하나를 지연 로드하므로 그때만 잠깐
+ * 비어 보입니다 — 어떤 아이콘이 목록에 있는지는
+ * `utils/lucideIconSet.ts` 참조.
+ *
+ * @example
+ * const HomeIcon = useLucideIcon('home')
+ * return HomeIcon ? <HomeIcon size={20} /> : null
+ *
+ * @public
+ */
+export default function useLucideIcon(icon?: string | null): unknown;

package/dist/packages/core/src/hooks/useLucideIcon.js

@@ -0,0 +1,71 @@
+'use client';
+import { useEffect, useState } from 'react';
+import { getStaticLucideIcon, loadLucideIcon } from '../utils/lucideLoader';
+// ─── 이름 변환 유틸 ───────────────────────────────────────────────────────────
+const toKebab = (s) => s
+    // 'XCircle' → 'X-Circle'. 대문자가 이어지다 단어가 시작되는 자리를 끊는다.
+    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1-$2')
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    // 'Volume2' → 'Volume-2'. lucide 는 변형 아이콘을 'volume-2' 로 부른다.
+    .replace(/([A-Za-z])([0-9])/g, '$1-$2')
+    .replace(/[_ ]+/g, '-')
+    .toLowerCase();
+// ─── rawKey 추출 ──────────────────────────────────────────────────────────────
+function toRawKey(icon) {
+    const lower = icon.toLowerCase();
+    // URL 또는 에셋 경로는 아이콘 이름이 아님
+    if (lower.startsWith('http://') ||
+        lower.startsWith('https://') ||
+        lower.startsWith('data:'))
+        return null;
+    if (icon.includes('/assets/'))
+        return null;
+    const baseFile = icon.split('/').pop() || '';
+    // 주의: lucide 아이콘명 규약("trash-2", "edit-2", "link-2" 등)은 끝의 숫자가
+    // "-2/-3" 변형 아이콘을 가리키는 유의미한 부분이라 잘라내면 안 됨(예: trash-2 ≠ trash).
+    const rawKey = baseFile.replace(/\.svg$/, '');
+    if (!rawKey)
+        return null;
+    // 'FolderOpen' 같은 PascalCase 도 받아 준다 — lucide 의 정식 이름은 kebab 이다.
+    return toKebab(rawKey);
+}
+// ─── 지연 로드 결과 캐시 ─────────────────────────────────────────────────────
+// 이름당 한 번만 받아오고, 이후 같은 이름은 첫 렌더부터 동기로 나온다.
+const lazyCache = new Map();
+// ─── 훅 ──────────────────────────────────────────────────────────────────────
+/**
+ * 아이콘 이름을 받아 lucide 컴포넌트를 돌려줍니다.
+ *
+ * 자주 쓰는 아이콘은 정적으로 번들되어 첫 렌더에, 서버 렌더에서도 바로
+ * 나옵니다. 목록에 없는 이름만 아이콘 하나를 지연 로드하므로 그때만 잠깐
+ * 비어 보입니다 — 어떤 아이콘이 목록에 있는지는
+ * `utils/lucideIconSet.ts` 참조.
+ *
+ * @example
+ * const HomeIcon = useLucideIcon('home')
+ * return HomeIcon ? <HomeIcon size={20} /> : null
+ *
+ * @public
+ */
+export default function useLucideIcon(icon) {
+    const key = typeof icon === 'string' ? toRawKey(icon) : null;
+    // 정적 목록과 이미 받아 둔 것은 렌더 중에 바로 정해진다.
+    const immediate = key
+        ? getStaticLucideIcon(key) ?? lazyCache.get(key) ?? null
+        : null;
+    const [lazy, setLazy] = useState(null);
+    useEffect(() => {
+        if (!key || immediate)
+            return;
+        let cancelled = false;
+        loadLucideIcon(key).then(component => {
+            lazyCache.set(key, component);
+            if (!cancelled)
+                setLazy(component);
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [key, immediate]);
+    return immediate ?? lazy;
+}

package/dist/packages/core/src/hooks/useMediaQuery.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 미디어쿼리 결과를 강제로 덮어쓰기 위한 컨텍스트.
+ * 랜딩페이지 폰 목업처럼 데스크탑 뷰포트에서 모바일 화면을 재현해야 할 때,
+ * `<MediaQueryOverrideContext.Provider value={{ mobile: true }}>`로 감싸면
+ * 하위 컴포넌트의 `useMediaQuery('(max-width: 767px)')`가 강제로 true를 반환한다.
+ * 일반 앱에서는 Provider가 없으므로(null) 실제 matchMedia 결과를 그대로 사용한다.
+ *
+ * @public
+ */
+export interface MediaQueryOverride {
+    /** '(max-width: 767px)' 계열(모바일 판정) 쿼리에 강제할 값 */
+    mobile?: boolean;
+}
+/** @public */
+export declare const MediaQueryOverrideContext: import("react").Context<MediaQueryOverride | null>;
+/** @public */
+export default function useMediaQuery(query: string): boolean;