@thewrong/ui 0.1.0

package/dist/src/components/input/types.d.ts

@@ -0,0 +1,131 @@
+import { ComponentPropsWithoutRef, ReactNode, Ref } from 'react';
+/**
+ * Input 컴포넌트의 Variant 타입
+ */
+export type InputVariant = "box" | "line" | "big" | "hero";
+/**
+ * Input 컴포넌트의 사이즈. Button/Select/Textarea와 동일 토큰. box variant에서만 적용.
+ * - mini: 다건 입력/표 형식 컴팩트 모드(특히 모바일)
+ * - small: 다건 입력/표 형식 기본
+ * - medium: 폼 단독 입력 기본
+ * - large: 메인 페이지의 강조 입력
+ */
+export type InputSize = "mini" | "small" | "medium" | "large";
+/**
+ * Input 컴포넌트의 Label 표시 방식 타입
+ */
+export type InputLabelOption = "appear" | "sustain";
+/**
+ * Input 컴포넌트의 Value 타입
+ */
+export type InputValue = string | number;
+/**
+ * Format 함수 타입
+ */
+export type FormatTransform = (value: InputValue) => InputValue;
+export type FormatReset = (formattedValue: InputValue) => InputValue;
+/**
+ * Format 옵션
+ */
+export interface InputFormat {
+    /**
+     * 입력값을 포맷팅된 값으로 변환해요.
+     * 예: "1000000" → "1,000,000"
+     */
+    transform: FormatTransform;
+    /**
+     * 포맷팅된 값을 원본 값으로 복원해요.
+     * 예: "1,000,000" → "1000000"
+     */
+    reset?: FormatReset;
+}
+/**
+ * Input 컴포넌트의 공통 Props
+ */
+export interface InputCommonProps {
+    /**
+     * 텍스트 필드의 모양
+     */
+    variant: InputVariant;
+    /**
+     * 사이즈 — box variant에서만 동작.
+     * @default 'medium'
+     */
+    inputSize?: InputSize;
+    /**
+     * 텍스트 필드의 상단의 라벨
+     */
+    label?: string;
+    /**
+     * label 표시 방식
+     * 'appear': value가 있을 때만 label이 보여요
+     * 'sustain': 항상 label이 보여요
+     * @default 'appear'
+     */
+    labelOption?: InputLabelOption;
+    /**
+     * 텍스트 필드의 하단의 도움말
+     */
+    help?: ReactNode;
+    /**
+     * 텍스트 필드의 에러 여부
+     * @default false
+     */
+    hasError?: boolean;
+    /**
+     * 텍스트 필드의 비활성화 여부
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * 입력 필드 앞에 표시될 텍스트
+     */
+    prefix?: string;
+    /**
+     * 입력 필드 뒤에 표시될 텍스트 (예: "원", "%"). 우측 슬롯의 가장 좌측.
+     */
+    suffix?: string;
+    /**
+     * 우측 트레일링 아이콘 (lucide-react 등). suffix 다음, clearable 앞에 위치.
+     */
+    trailingIcon?: ReactNode;
+    /**
+     * 값이 있을 때 우측에 X 버튼(CircleX)을 노출. 클릭 시 onChange로 빈 값을 emit.
+     * disabled에서는 노출하지 않는다. trailingIcon 다음, badge 앞에 위치.
+     * @default false
+     */
+    clearable?: boolean;
+    /**
+     * 우측 가장 끝에 표시할 뱃지/라벨 ReactNode. 단위 표시나 상태 라벨용.
+     */
+    badge?: ReactNode;
+    /**
+     * placeholder 텍스트
+     */
+    placeholder?: string;
+    /**
+     * 금액, 휴대폰번호 등 특정 형식으로 변환해요
+     */
+    format?: InputFormat;
+    /**
+     * 컨테이너의 추가 props
+     */
+    containerProps?: ComponentPropsWithoutRef<"div">;
+    /**
+     * 컨테이너의 ref
+     */
+    containerRef?: Ref<HTMLDivElement>;
+}
+/**
+ * Input 컴포넌트의 Props
+ */
+export interface InputProps extends Omit<ComponentPropsWithoutRef<"input">, "color" | "value" | "defaultValue">, InputCommonProps {
+    /**
+     * 입력값
+     */
+    value?: InputValue;
+    /**
+     * 기본값
+     */
+    defaultValue?: InputValue;
+}

package/dist/src/components/input/utils.d.ts

@@ -0,0 +1,17 @@
+import { InputSize, InputVariant } from './types';
+/**
+ * Input Variant에 따른 컨테이너(input wrapper) 클래스 매핑.
+ * box variant는 새 디자인 적용. line/big/hero는 레거시.
+ */
+export declare const getInputVariantClasses: (variant: InputVariant, hasError: boolean, disabled: boolean, size?: InputSize) => string;
+/**
+ * input 엘리먼트 자체의 텍스트/배경 클래스.
+ */
+export declare const getInputClasses: (variant: InputVariant, hasError: boolean, disabled: boolean, filled: boolean, size?: InputSize) => string;
+/**
+ * Trailing 영역(아이콘/clear/라벨) 색상 — 상태에 따라.
+ */
+export declare const getInputTrailingIconColor: (hasError: boolean, disabled: boolean, filledOrFocused: boolean) => string;
+export declare const getInputContainerClasses: () => string;
+export declare const getInputLabelClasses: (_variant: InputVariant, hasError: boolean) => string;
+export declare const getInputHelpClasses: (hasError: boolean) => string;

package/dist/src/components/loading-spinner/LoadingSpinner.d.ts

@@ -0,0 +1,16 @@
+export interface LoadingSpinnerProps {
+    message?: string;
+    size?: "sm" | "md" | "lg";
+    className?: string;
+}
+export declare function Spinner({ size }: {
+    size?: "sm" | "md" | "lg";
+}): import("react").JSX.Element;
+/**
+ * 영역 중앙에 스피너 + 메시지를 표시하는 로딩 표시. 데이터 페칭 중 컨테이너에 채워 쓴다.
+ */
+export declare function LoadingSpinner({ message, size, className, }: LoadingSpinnerProps): import("react").JSX.Element;
+/** 인라인(작은) 스피너 — 리스트 하단 더보기 로딩 등. */
+export declare function InlineSpinner({ size }: {
+    size?: "sm" | "md" | "lg";
+}): import("react").JSX.Element;

package/dist/src/components/loading-spinner/index.d.ts

@@ -0,0 +1,2 @@
+export { LoadingSpinner, InlineSpinner, Spinner } from './LoadingSpinner';
+export type { LoadingSpinnerProps } from './LoadingSpinner';

package/dist/src/components/modal/Modal.d.ts

@@ -0,0 +1,51 @@
+export interface ModalProps {
+    isOpen: boolean;
+    onClose: () => void;
+    title?: string;
+    /**
+     * 데스크탑(sm+) 모달의 고정 폭(px). 지정하지 않으면 콘텐츠 폭에 fit (`sm:w-auto`).
+     *
+     * 모달은 너비를 애니메이션하지 않는 것이 정책이다(컴포넌트 설명 참고). 따라서 콘텐츠 폭이
+     * 인터랙션으로 변할 수 있는 모달은 `widthPx`로 폭을 고정해 폭 변동에 따른 시각적 흔들림을 막는다.
+     * 폭이 변하지 않는 단순 모달은 생략해 콘텐츠 폭에 맞춰도 된다.
+     * 모바일은 무조건 w-full (이 값 무시).
+     */
+    widthPx?: number;
+    /**
+     * 푸터 영역. 지정하면 헤더-바디-푸터 3단 구조로 동작 — 푸터는 스크롤 영역 밖에 고정되고
+     * children(=바디)만 자체 스크롤된다. 미지정이면 children 전체가 한 영역에서 스크롤(기본).
+     */
+    footer?: React.ReactNode;
+    /**
+     * 바디 스크롤 컨테이너 자체에 좌우 패딩을 부여해 스크롤바가 시트 가장자리가 아니라 안쪽에
+     * 떠 있는 모양을 만든다. 이 옵션을 켜면 사용처 본문에서는 좌우 패딩을 제거하고 세로만 둘 것.
+     */
+    bodyPadded?: boolean;
+    /**
+     * 모달 바디 위에 우측에서 슬라이드 인 하는 서브뷰. ModalSubView 컴포넌트를 그대로 넘기면 된다.
+     * 별도 wrapper(scroll-isolated)에 두어 본문 스크롤과 무관하게 viewport 100% 덮음.
+     * subView가 있으면 시트 높이가 자동으로 viewport 기준으로 강제된다 (콘텐츠 따라 자라지 않음).
+     */
+    subView?: React.ReactNode;
+    children: React.ReactNode;
+}
+/**
+ * 데스크탑(`sm`+)에서는 중앙 정렬 모달, 모바일에서는 화면 하단에서 올라오는 bottom-sheet으로 동작.
+ *
+ * - 모바일: 시트가 화면 하단에 붙고 상단 모서리만 둥글다. 핸들 바 표시.
+ *   진입/퇴장 모션은 화면 밖에서 슬라이드 (`y: "100%" → 0 → "100%"`).
+ * - 데스크탑: 중앙 카드. 살짝 위로 올라오면서 페이드 인/아웃.
+ *
+ * **높이 변화**: 콘텐츠 높이가 변하는 인터랙션(토글/조건부 영역)은 본문을 `<AnimatedHeight>`로
+ * 감싸면 시트 높이가 부드럽게 이행된다. 미적용 시 instant jump.
+ *
+ * **너비는 고정한다**: 동적 너비 트랜지션은 데스크탑 중앙 정렬(`translateX(-50%)`)의 기준점과
+ * 함께 움직여 한쪽으로 밀리는 부자연스러운 모션이 된다(framer-motion `layout`도 transform 정렬과
+ * 충돌). 그래서 높이만 애니메이션하고 너비는 고정하는 것을 정책으로 한다. 콘텐츠 폭이 모드 전환
+ * 등으로 변할 수 있으면 `widthPx`로 고정해 시트가 흔들리지 않게 할 것.
+ *
+ * **레이어드 오버레이**: ESC/백드롭은 `overlayStack`에서 자신이 top일 때만 반응한다.
+ * ActionToast나 ModalSubView가 위에 떠 있으면(더 높은 priority/나중 push) 자동으로 양보된다.
+ * 모달 위에 또 모달을 쌓는 대신 ModalSubView(푸시 네비)나 ActionToast(재확인)로 푸는 것을 권장.
+ */
+export declare function Modal({ isOpen, onClose, title, widthPx, footer, bodyPadded, subView, children, }: ModalProps): import("react").JSX.Element;

package/dist/src/components/modal/ModalSubView.d.ts

@@ -0,0 +1,61 @@
+import { ReactNode } from 'react';
+export interface ModalSubViewProps {
+    open: boolean;
+    /** 뒤로가기 버튼 / ESC 키로 트리거됨. */
+    onBack: () => void;
+    title?: ReactNode;
+    /** 헤더 우측에 추가 액션. 예: 새로고침 버튼. */
+    headerRight?: ReactNode;
+    /**
+     * 바디 스크롤 컨테이너에 좌우 margin(mx-4)을 부여해 스크롤바가 시트 가장자리가 아닌 안쪽에
+     * 떠 있는 모양을 만든다. 본 Modal의 bodyPadded와 동일 정책. 디폴트 true.
+     * 본문이 카드/테이블처럼 가장자리까지 가야 하면 false로 끄고 호출부가 padding 책임.
+     */
+    bodyPadded?: boolean;
+    /**
+     * children을 px-4 py-5 wrapper로 자동 감싼다 (StandardModal과 동일 정책).
+     * 호출부가 자체 padding을 가지면 false로 끌 것. 디폴트 true.
+     */
+    contentPadded?: boolean;
+    /**
+     * 표시 방식.
+     * - "full" (기본): 부모 시트를 통째로 덮으며 우측에서 슬라이드 인.
+     * - "drawer": 백드롭 + 우측 일부 영역만 차지하는 사이드 드로어. 부모 본문이 백드롭 뒤로 흐릿하게
+     *   보이며 드로어는 우측에서 슬라이드 인.
+     */
+    variant?: "full" | "drawer";
+    children: ReactNode;
+}
+/**
+ * 모달 본문 위에 우측에서 슬라이드 인 하는 서브뷰.
+ *
+ * 데스크탑/모바일 동일하게 부모 Modal의 영역을 `absolute inset-0`로 덮어 한 번에 한 화면만
+ * 보이게 한다. 모바일 바텀시트에서 두 시트를 겹치는 어색함 없이 자연스러운 푸시 네비.
+ * (레이어드 모달 회피)
+ *
+ * **부모 Modal 요구사항**: 자식이 `absolute inset-0`로 자리 잡으려면 어딘가에 `position: relative`가
+ * 있어야 한다. Modal 컴포넌트 자체가 `relative` 시트라 별도 처리 불필요.
+ *
+ * **높이 정책 — 서브뷰 콘텐츠 ≤ 부모 모달 콘텐츠**: 서브뷰는 부모 시트 영역을 `absolute inset-0`로
+ * 덮으므로 부모 시트의 높이를 그대로 물려받는다. 모달 너비를 애니메이션하지 않는 것과 같은 이유로
+ * 시트 높이도 서브뷰 진입 때마다 출렁이게 하지 않는다. 따라서 **서브뷰 콘텐츠 높이는 부모 모달
+ * 본문 높이와 같거나 작게** 설계하는 것을 권장한다. "작은 모달인데 서브뷰에만 아주 긴 내용"이
+ * 들어가면 서브뷰 안에서만 스크롤이 생겨 부모와 높이가 어긋나 보인다. 긴 목록은 부모 모달 자체를
+ * 그만큼 키우거나(`widthPx`/콘텐츠 양 조정), 별도 페이지/Drawer로 분리할 것.
+ *
+ * **ESC 동작**: SubView가 열려있는 동안 ESC는 SubView의 `onBack`을 부르고 모달은 유지된다.
+ * `overlayStack`을 push해 Modal보다 위 layer로 등록 — Modal의 ESC 핸들러는 자기가 top일 때만 실행.
+ *
+ * @example
+ * ```tsx
+ * const [subOpen, setSubOpen] = useState(false);
+ *
+ * <Modal isOpen={open} onClose={onClose} title="한도 수정">
+ *   <button onClick={() => setSubOpen(true)}>변경 이력 보기</button>
+ *   <ModalSubView open={subOpen} onBack={() => setSubOpen(false)} title="변경 이력">
+ *     <AuditLogList ... />
+ *   </ModalSubView>
+ * </Modal>
+ * ```
+ */
+export declare function ModalSubView({ open, onBack, title, headerRight, bodyPadded, contentPadded, variant, children, }: ModalSubViewProps): import("react").JSX.Element;

package/dist/src/components/modal/StandardModal.d.ts

@@ -0,0 +1,59 @@
+import { ReactNode } from 'react';
+import { ButtonAppearance, ButtonVariant } from '../../../components/button';
+export interface StandardModalAction {
+    label: ReactNode;
+    onClick: () => void;
+    variant?: ButtonVariant;
+    appearance?: ButtonAppearance;
+    /** 좌측에 아이콘. 우측 액션엔 거의 안 쓰지만 leftAction(예: 변경이력)에선 자주 사용. */
+    leadingIcon?: ReactNode;
+    loading?: boolean;
+    disabled?: boolean;
+}
+export interface StandardModalProps {
+    isOpen: boolean;
+    onClose: () => void;
+    title?: string;
+    widthPx?: number;
+    /** 우측 슬라이드 서브뷰. ModalSubView 그대로 전달. */
+    subView?: ReactNode;
+    /**
+     * 우측 주 액션. 보통 "저장" / "확인" 등. variant 기본 primary.
+     * 미지정이면 footer 자체가 안 그려진다 (단순 알림성 모달은 base Modal로).
+     */
+    primaryAction?: StandardModalAction;
+    /** 우측 보조 액션. 보통 "취소" / "닫기". variant 기본 secondary, appearance 기본 outlined. */
+    secondaryAction?: StandardModalAction;
+    /**
+     * 좌측 보조 액션. 비대칭 footer (예: 좌측 "변경이력", 우측 "닫기/저장")가 필요할 때.
+     * 일반 모달에서는 미지정.
+     */
+    leftAction?: StandardModalAction;
+    /**
+     * 본문 자동 padding(`px-4 py-5`)을 끄고 호출부가 직접 padding 책임진다.
+     * 본문이 카드/테이블/이미지처럼 자체 가장자리까지 가야 하는 경우.
+     */
+    bodyNoPadding?: boolean;
+    children: ReactNode;
+}
+/**
+ * 표준 폼 모달 — Modal 위에 표준 footer + 본문 padding을 강제로 입힌 고수준 컴포넌트.
+ *
+ * 80% 폼 모달 케이스를 한 번에 표준화한다. 비대칭 액션도 `leftAction` 으로 커버.
+ * 자유도가 더 필요한 케이스(footer 자체 자유 배치, 본문에 다른 인터랙션 영역)는
+ * base `Modal`로 직접 내려가서 footer/bodyPadded prop을 자유롭게 쓸 것.
+ *
+ * @example
+ * ```tsx
+ * <StandardModal
+ *   isOpen={open}
+ *   onClose={onClose}
+ *   title="역할 수정"
+ *   primaryAction={{ label: "저장", onClick: handleSave, loading: isSaving }}
+ *   secondaryAction={{ label: "닫기", onClick: onClose }}
+ * >
+ *   <Input ... />
+ * </StandardModal>
+ * ```
+ */
+export declare function StandardModal({ isOpen, onClose, title, widthPx, subView, primaryAction, secondaryAction, leftAction, bodyNoPadding, children, }: StandardModalProps): import("react").JSX.Element;

package/dist/src/components/modal/index.d.ts

@@ -0,0 +1,6 @@
+export { Modal } from './Modal';
+export type { ModalProps } from './Modal';
+export { ModalSubView } from './ModalSubView';
+export type { ModalSubViewProps } from './ModalSubView';
+export { StandardModal } from './StandardModal';
+export type { StandardModalAction, StandardModalProps } from './StandardModal';

package/dist/src/components/page-title/PageTitle.d.ts

@@ -0,0 +1,17 @@
+interface Props {
+    /** 메인 타이틀. 페이지 식별의 1순위 정보. */
+    title: string;
+    /** 한 줄 설명. title 옆에 baseline 정렬로 표시(없으면 생략). */
+    subtitle?: string;
+    className?: string;
+}
+/**
+ * 페이지 헤더 좌측에 표시되는 타이틀 영역.
+ *
+ * Breadcrumb 자리를 대체. 라우트 뎁스가 얕을 때 빵부스러기보단 굵은 타이틀 + 부제목이
+ * 페이지 식별에 적합. subtitle은 title 옆에 baseline 정렬로 가로 배치 — 좁은 화면에서는 wrap.
+ *
+ * subtitle 매핑은 `usePageTitle` 훅이 메뉴 데이터의 `description` 필드를 읽어 전달.
+ */
+export declare function PageTitle({ title, subtitle, className }: Props): import("react").JSX.Element;
+export {};

package/dist/src/components/page-title/index.d.ts

@@ -0,0 +1 @@
+export { PageTitle } from './PageTitle';

package/dist/src/components/popover/Popover.d.ts

@@ -0,0 +1,28 @@
+import { ReactNode } from 'react';
+export interface PopoverProps {
+    /**
+     * 팝오버를 여는 트리거. **비대화형 노드(텍스트·아이콘·span 등)를 권장한다.**
+     * 래퍼 span이 `role="button"` + `tabIndex`로 버튼 시맨틱과 키보드 포커스를 부여하기 때문에,
+     * 이미 대화형인 요소(`<button>`/`<a>`)를 넘기면 포커스가 중첩되고 role이 겹친다.
+     * 대화형 트리거가 꼭 필요하면 그 요소를 직접 쓰지 말고 비대화형 콘텐츠로 감싸 전달할 것.
+     */
+    trigger: ReactNode;
+    /**
+     * 팝오버 내용. 함수로 주면 `close` 콜백을 주입받아 내부에서 팝오버를 닫을 수 있다
+     * (예: 메뉴 항목 클릭 후 닫기). ReactNode를 그대로 줘도 된다.
+     */
+    content: ReactNode | ((close: () => void) => ReactNode);
+    /** 배치 방향. floating-ui 기반이라 공간 부족 시 자동 flip된다. 기본 bottom. */
+    placement?: "top" | "bottom" | "left" | "right";
+    /** 열림/닫힘 변화 콜백. 호출처가 open 상태에 따라 폴링 등을 제어할 때 사용. */
+    onOpenChange?: (open: boolean) => void;
+}
+/**
+ * Popover — `@floating-ui/react` 기반.
+ *
+ * - **클릭 토글** + 외부 클릭/ESC 자동 닫힘(useDismiss)
+ * - **자동 flip / shift**: 공간 부족하면 반대편으로, viewport 경계로 clamp
+ * - **스크롤/resize 자동 추적**(autoUpdate)
+ * - **Portal 렌더**: 부모 overflow:hidden에 잘리지 않음
+ */
+export declare function Popover({ trigger, content, placement, onOpenChange, }: PopoverProps): import("react").JSX.Element;

package/dist/src/components/popover/index.d.ts

@@ -0,0 +1,2 @@
+export { Popover } from './Popover';
+export type { PopoverProps } from './Popover';

package/dist/src/components/search-box/ExactMatchToggle.d.ts

@@ -0,0 +1,14 @@
+interface Props {
+    value: boolean;
+    onChange: (next: boolean) => void;
+    size: "mini" | "small";
+}
+/**
+ * SearchBox "완전일치" 토글.
+ *
+ * 시안(`완전일치.png`): 박스 없는 인라인 체크 아이콘 + 라벨.
+ * - 비활성: 회색 체크 + 회색 라벨
+ * - 활성: 파란 체크 + 파란 라벨
+ */
+export declare function ExactMatchToggle({ value, onChange, size }: Props): import("react").JSX.Element;
+export {};

package/dist/src/components/search-box/SearchBox.d.ts

@@ -0,0 +1,35 @@
+import { SearchField, SearchValues } from './types';
+interface Props {
+    /** 호출부가 `as const satisfies readonly SearchField[]` 패턴을 쓰면 parseSearchValues가
+     * 타입을 정확히 추론하므로 readonly 시그니처로 받는다. */
+    fields: readonly SearchField[];
+    /** 외부에서 적용된 값. 초기값 + 외부에서 강제 변경(예: URL 동기화) 시 반영. */
+    values: SearchValues;
+    /** [검색] 또는 Enter로 commit. */
+    onSearch: (next: SearchValues) => void;
+    /** [초기화]. 미지정 시 빈 객체로 onSearch 호출. */
+    onClear?: () => void;
+    /** 검색 요청 진행 중 — 검색 버튼 비활성화 + Enter/submit no-op. */
+    isSubmitting?: boolean;
+    /** "완전일치" 옵션 — 지정하면 검색/초기화 좌측에 토글 노출. value/onChange 같이 받는다. */
+    exactMatch?: {
+        value: boolean;
+        onChange: (next: boolean) => void;
+    };
+    /** className for outer wrapper. */
+    className?: string;
+}
+/**
+ * 공용 검색박스.
+ *
+ * 동작 요약:
+ * - 입력 즉시 검색 X — [검색]/Enter/[적용](모바일 시트) 시점에만 commit
+ * - select 활성값만 칩으로 표시
+ * - 데스크톱: 페이지 배경 위에 투명하게 떠 있는 플로팅 라벨 필드 + 우측 액션 버튼
+ * - 모바일: 헤더 없이 우측 [초기화][검색][필터] 아이콘 3개만. 필터 클릭 시 바텀시트로 본체 표시.
+ *   바텀시트 안에서 입력 후 [적용]을 눌러야 commit (시트 외부 클릭/닫기는 입력 폐기).
+ *
+ * 페이지에서는 `fields` 배열만 정의해서 넘기고, draft 관리는 SearchBox 내부가 담당.
+ */
+export declare function SearchBox({ fields, values, onSearch, onClear, isSubmitting, exactMatch, className, }: Props): import("react").JSX.Element;
+export {};

package/dist/src/components/search-box/SearchBoxChips.d.ts

@@ -0,0 +1,12 @@
+interface ChipData {
+    key: string;
+    label: string;
+    valueLabel: string;
+}
+interface Props {
+    chips: ChipData[];
+    onRemove: (key: string) => void;
+}
+/** 적용된 select 필드를 칩으로 표시. 칩 클릭 시 해당 필터 제거. hover 시 전체 텍스트 툴팁. */
+export declare function SearchBoxChips({ chips, onRemove }: Props): import("react").JSX.Element | null;
+export {};

package/dist/src/components/search-box/SearchBoxDateRange.d.ts

@@ -0,0 +1,20 @@
+import { DateRangePreset } from './types';
+interface Props {
+    /** "from~to" CSV. 빈 문자열이면 양쪽 모두 비어있음. */
+    value: string;
+    onChange: (next: string) => void;
+    presets?: DateRangePreset[];
+    size: "mini" | "small";
+}
+/**
+ * 날짜 범위 입력 — DateInput 2개 (직접 타이핑 + 캘린더 popover) + 프리셋 버튼.
+ *
+ * 레이아웃 그룹화:
+ * - 인풋 묶음(from `~` to)은 절대 분리되지 않음. 좁아지면 한 묶음 통째로 다음 줄로.
+ * - 프리셋 묶음도 통째로 유지(버튼 텍스트 nowrap).
+ * - 두 묶음은 부모 flex-wrap이라 viewport에 따라 한 줄/두 줄 자동 전환.
+ *
+ * URL 직렬화: 단일 SearchValues 키에 `"from~to"`. 빈 값은 미입력.
+ */
+export declare function SearchBoxDateRange({ value, onChange, presets, size }: Props): import("react").JSX.Element;
+export {};

package/dist/src/components/search-box/SearchBoxDateSingle.d.ts

@@ -0,0 +1,17 @@
+import { DateSinglePreset } from './types';
+interface Props {
+    /** yyyy-MM-dd 또는 빈 문자열. */
+    value: string;
+    onChange: (next: string) => void;
+    ariaLabel?: string;
+    presets?: DateSinglePreset[];
+    size: "mini" | "small";
+}
+/**
+ * 단일 날짜 입력 — DateInput 1개 + 옵션 프리셋 버튼.
+ *
+ * SearchBoxDateRange의 단일 버전. 단일 SearchValues 키에 yyyy-MM-dd 직접 저장.
+ * 다른 필드 없이 dateSingle만 있는 페이지에서 SearchBox flex-wrap에 자연스럽게 배치된다.
+ */
+export declare function SearchBoxDateSingle({ value, onChange, ariaLabel, presets, size, }: Props): import("react").JSX.Element;
+export {};

package/dist/src/components/search-box/SearchBoxField.d.ts

@@ -0,0 +1,11 @@
+import { SearchField } from './types';
+interface Props {
+    field: SearchField;
+    value: string;
+    onChange: (value: string) => void;
+    onEnter?: () => void;
+    size: "mini" | "small";
+}
+/** 단일 필드 렌더. type별 컴포넌트 분기. SearchBox 본체에서 분리해 갓 컴포넌트 회피. */
+export declare function SearchBoxField({ field, value, onChange, onEnter, size, }: Props): import("react").JSX.Element;
+export {};

package/dist/src/components/search-box/SearchBoxFloatingInput.d.ts

@@ -0,0 +1,24 @@
+interface Props {
+    /** 라벨 — 비어 있을 땐 placeholder처럼 인풋 안에 위치, 포커스/값 있을 땐 상단 보더로 부유. */
+    label: string;
+    value: string;
+    onChange: (next: string) => void;
+    onEnter?: () => void;
+    size: "mini" | "small";
+    inputMode?: "text" | "numeric";
+    /** 우측 슬롯 — 검색 아이콘/액션 등. 키보드 포커스 색에 영향 X. */
+    trailing?: React.ReactNode;
+}
+/**
+ * SearchBox 전용 플로팅 라벨 인풋 (MUI outlined TextField 패턴).
+ *
+ * 동작:
+ * - 값 없음 + 미포커스: 라벨이 인풋 중앙 (placeholder 역할)
+ * - 포커스 OR 값 있음: 라벨이 상단 보더로 올라가며 작아짐
+ * - 보더는 라벨 부유 위치에 노치(틈)를 두지 않고 단순 white 배경으로 라벨이 덮어 가리는 방식.
+ *   (배경이 투명/이미지일 땐 시안과 차이날 수 있지만 SearchBox 컨테이너는 페이지 배경 위라 OK.)
+ *
+ * 공용 Input을 건드리지 않기 위해 SearchBox 전용 wrapper로 격리.
+ */
+export declare function SearchBoxFloatingInput({ label, value, onChange, onEnter, size, inputMode, trailing, }: Props): import("react").JSX.Element;
+export {};

package/dist/src/components/search-box/SearchBoxFloatingSelect.d.ts

@@ -0,0 +1,19 @@
+import { SelectOption } from '../../../components/select';
+interface Props {
+    /** 라벨 — 미선택일 땐 인풋 안의 placeholder처럼, 선택/포커스 시 상단 보더로 부유. */
+    label: string;
+    options: SelectOption[];
+    value: string;
+    onChange: (next: string) => void;
+    size: "mini" | "small";
+}
+/**
+ * SearchBox 전용 플로팅 라벨 셀렉트.
+ *
+ * 단일 선택 — value가 빈 문자열이면 미선택(라벨이 안에 머무름).
+ * 선택되면 라벨이 상단 보더로 떠오르고 트리거에는 선택 옵션 라벨이 표시됨.
+ *
+ * SearchBoxFloatingInput과 시각적 일관성을 위해 동일한 사이즈/라벨 규칙 적용.
+ */
+export declare function SearchBoxFloatingSelect({ label, options, value, onChange, size, }: Props): import("react").JSX.Element;
+export {};

package/dist/src/components/search-box/SearchBoxMonth.d.ts

@@ -0,0 +1,14 @@
+interface Props {
+    /** "yyyy-MM" 또는 빈 문자열. */
+    value: string;
+    onChange: (next: string) => void;
+    ariaLabel?: string;
+    size: "mini" | "small";
+}
+/**
+ * 년월 선택 — MonthPicker 1개. 단일 SearchValues 키에 "yyyy-MM" 직접 저장.
+ *
+ * dateSingle의 년월 버전. 미선택(빈 값)이면 "년월 선택" placeholder.
+ */
+export declare function SearchBoxMonth({ value, onChange, ariaLabel, size }: Props): import("react").JSX.Element;
+export {};

package/dist/src/components/search-box/SearchBoxMultiSelect.d.ts

@@ -0,0 +1,25 @@
+import { SelectOption } from '../../../components/select';
+interface Props {
+    /** 라벨 — 미선택일 땐 트리거 안의 placeholder처럼, 선택/오픈 시 상단 보더로 부유. */
+    label: string;
+    options: SelectOption[];
+    /** CSV 직렬화된 값. 빈 문자열이면 선택 없음. */
+    value: string;
+    onChange: (csv: string) => void;
+    size: "mini" | "small";
+}
+/**
+ * SearchBox 전용 다중 선택. 트리거 버튼 + 드롭다운 체크박스 리스트.
+ *
+ * 값은 CSV(string) 직렬화 — URL/zod schema와의 호환을 위해 SearchValues `Record<string, string>`
+ * 시그니처를 유지한다. 빈 값이면 미선택, "A,B"면 두 항목 선택.
+ *
+ * SearchBoxFloatingInput/Select와 동일한 플로팅 라벨 UX. 보더와 라벨이 포커스/오픈 시
+ * primary-500으로 통일된다.
+ *
+ * number[] 전용 드롭다운은 적합하지 않아 별도 inline 컴포넌트로 둔다.
+ *
+ * 위치 계산은 floating-ui 위임 — autoUpdate가 스크롤/리사이즈 시 좌표를 자동 갱신.
+ */
+export declare function SearchBoxMultiSelect({ label, options, value, onChange, size, }: Props): import("react").JSX.Element;
+export {};

package/dist/src/components/search-box/SearchBoxSheetContext.d.ts

@@ -0,0 +1,8 @@
+/**
+ * SearchBox 모바일 바텀시트 내부 여부를 자식에게 알리는 컨텍스트.
+ *
+ * 자식 컴포넌트(예: SearchBoxDateRange)가 자체 popover/시트를 띄울 때, 부모 바텀시트가
+ * 이미 떠 있는지 알아야 한다. 떠 있으면 시트 두 개가 겹치는 어색함을 피하기 위해
+ * ModalSubView(drawer 변형)로 분기.
+ */
+export declare const SearchBoxSheetContext: import('react').Context<boolean>;

package/dist/src/components/search-box/dateRangePresets.d.ts

@@ -0,0 +1,10 @@
+import { DateRangePreset } from './types';
+/** 당일 from/to. 페이지 진입 시 기본 range로 사용. */
+export declare function getTodayDateRange(): {
+    from: string;
+    to: string;
+};
+/** "from~to" CSV 형태의 당일 SearchValues 값. */
+export declare function getTodayDateRangeValue(): string;
+/** 기본 4종 프리셋 — 전일 / 당일 / 당월 / 전월. 호출 시점의 날짜 기준으로 계산. */
+export declare const DEFAULT_DATE_RANGE_PRESETS: DateRangePreset[];

package/dist/src/components/search-box/index.d.ts

@@ -0,0 +1,5 @@
+export { SearchBox } from './SearchBox';
+export { parseSearchValues, parseMultiSelectValue, } from './parseSearchValues';
+export { parseDateRangeValue, serializeDateRangeValue, type DateRangeValue, } from './parseDateRange';
+export { DEFAULT_DATE_RANGE_PRESETS, getTodayDateRange, getTodayDateRangeValue, } from './dateRangePresets';
+export type { SearchField, SearchFieldText, SearchFieldSelect, SearchFieldMultiSelect, SearchFieldDateRange, SearchFieldDateSingle, DateRangePreset, DateSinglePreset, SearchValues, } from './types';