@thewrong/ui 0.1.0

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

@@ -0,0 +1,15 @@
+/**
+ * dateRange 필드 직렬화 헬퍼.
+ *
+ * SearchValues는 평면 `Record<string, string>`이라 from/to 두 값을 단일 키에 묶어야 한다.
+ * 형식: `"from~to"`. 한쪽만 있어도 OK (`"~2026-05-06"`, `"2026-05-01~"`).
+ * 빈 문자열은 미입력.
+ */
+export interface DateRangeValue {
+    from: string;
+    to: string;
+}
+/** SearchValues 문자열 → { from, to } */
+export declare function parseDateRangeValue(raw: string | undefined): DateRangeValue;
+/** 양쪽 모두 빈 값이면 빈 문자열 (URL에서 자동 제거되도록). */
+export declare function serializeDateRangeValue(from: string, to: string): string;

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

@@ -0,0 +1,38 @@
+import { DateRangeValue } from './parseDateRange';
+import { SearchField, SearchValues } from './types';
+/**
+ * SearchValues를 type-aware하게 파싱한 결과.
+ * - text/select 필드: `string` 그대로 (빈 값이면 `""`)
+ * - multiSelect 필드: `string[]` 으로 split (CSV → array)
+ * - dateRange 필드: `{ from, to }` 객체 (한쪽만 있어도 OK, 둘 다 비면 빈 문자열)
+ *
+ * 호출부가 SearchBox의 직렬화 형식을 알 필요 없이 바로 API 파라미터로 사용 가능.
+ */
+export type ParsedSearchValues<TFields extends readonly SearchField[]> = {
+    [K in TFields[number] as K["key"]]: K["type"] extends "multiSelect" ? string[] : K["type"] extends "dateRange" ? DateRangeValue : string;
+};
+/**
+ * multiSelect의 CSV 값을 array로 변환. 빈 값이면 `[]`.
+ *
+ * SearchBox의 CSV 직렬화는 `Record<string, string>` 시그니처/URL 호환을 위한 내부 표현이고,
+ * 호출부는 array가 필요. 이 헬퍼로 매번 split 보일러플레이트를 줄인다.
+ */
+export declare function parseMultiSelectValue(value: string | undefined): string[];
+/**
+ * SearchValues 전체를 fields 정의 기준으로 파싱.
+ *
+ * @example
+ * ```ts
+ * const SEARCH_FIELDS = [
+ *   { type: "text", key: "name", label: "이름" },
+ *   { type: "multiSelect", key: "type", label: "유형", options: [...] },
+ * ] as const satisfies readonly SearchField[];
+ *
+ * const parsed = parseSearchValues(SEARCH_FIELDS, search);
+ * //   ^? { name: string; type: string[] }
+ *
+ * // 그대로 axios에 전달 — split 보일러플레이트 없음.
+ * useApiQuery({ params: { name: parsed.name || undefined, type: parsed.type } });
+ * ```
+ */
+export declare function parseSearchValues<const TFields extends readonly SearchField[]>(fields: TFields, values: SearchValues): ParsedSearchValues<TFields>;

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

@@ -0,0 +1,67 @@
+import { SelectOption } from '../../../components/select';
+/** 검색 필드 정의 — discriminated union. 새 타입은 여기에 추가. */
+export type SearchField = SearchFieldText | SearchFieldSelect | SearchFieldMultiSelect | SearchFieldDateRange | SearchFieldDateSingle | SearchFieldMonth;
+/**
+ * 검색 값 형태. key → 값(빈 문자열 = 미입력).
+ * - text/select: "값"
+ * - multiSelect: "값1,값2" (CSV 직렬화. URL/zod schema와의 호환을 위해 string 일관성 유지)
+ * - dateRange: "from~to" (둘 다 yyyy-MM-dd, 한쪽만 있어도 OK. 예: "2026-05-01~2026-05-06")
+ * - dateSingle: "yyyy-MM-dd" 단일 값
+ * - month: "yyyy-MM" 단일 값
+ */
+export type SearchValues = Record<string, string>;
+interface SearchFieldCommon {
+    /** 결과 객체의 키. */
+    key: string;
+    /** 라벨 — 칩에서 prefix로 사용 가능. */
+    label: string;
+    /** 폼 영역에서의 폭. 미지정 시 자동(grid) 분배. 단위는 tailwind w-* 또는 임의 className. */
+    className?: string;
+    /** true면 입력 UI/칩/parse/state 모든 곳에서 제외 — 권한 기반 가시성 분기에 사용. */
+    hidden?: boolean;
+}
+export interface SearchFieldText extends SearchFieldCommon {
+    type: "text";
+    /** placeholder. 미지정 시 label. */
+    placeholder?: string;
+    inputMode?: "text" | "numeric";
+}
+export interface SearchFieldSelect extends SearchFieldCommon {
+    type: "select";
+    options: SelectOption[];
+    /** placeholder(첫 옵션 자동 생성용). 미지정 시 "{label} 전체". */
+    placeholder?: string;
+}
+export interface SearchFieldMultiSelect extends SearchFieldCommon {
+    type: "multiSelect";
+    options: SelectOption[];
+    /** placeholder. 미지정 시 "{label} 선택". */
+    placeholder?: string;
+}
+/** 날짜 범위 프리셋. label은 버튼 표기, range()는 호출 시점의 from/to(yyyy-MM-dd) 반환. */
+export interface DateRangePreset {
+    label: string;
+    range: () => {
+        from: string;
+        to: string;
+    };
+}
+export interface SearchFieldDateRange extends SearchFieldCommon {
+    type: "dateRange";
+    /** 단일 key에 "from~to" CSV로 직렬화. parseSearchValues가 { from, to }로 풀어준다. */
+    presets?: DateRangePreset[];
+}
+/** 단일 날짜 프리셋. label은 버튼 표기, date()는 호출 시점의 yyyy-MM-dd 반환. */
+export interface DateSinglePreset {
+    label: string;
+    date: () => string;
+}
+export interface SearchFieldDateSingle extends SearchFieldCommon {
+    type: "dateSingle";
+    /** yyyy-MM-dd 단일 값. parseSearchValues가 그대로 string으로 반환. */
+    presets?: DateSinglePreset[];
+}
+export interface SearchFieldMonth extends SearchFieldCommon {
+    type: "month";
+}
+export {};

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

@@ -0,0 +1,30 @@
+import { SearchField, SearchValues } from './types';
+interface UseSearchBoxStateArgs {
+    fields: readonly SearchField[];
+    /** 외부에서 적용된 값. 외부가 commit한 값이라 내부 draft와 별개. */
+    values: SearchValues;
+    /** 사용자가 [검색]/Enter로 commit할 때 호출. */
+    onSearch: (next: SearchValues) => void;
+    /** [초기화] 호출. 미지정 시 빈 객체로 onSearch 호출. */
+    onClear?: () => void;
+}
+/**
+ * SearchBox의 입력/적용 상태 관리.
+ * - draft: 사용자가 입력 중인 값 (외부에 노출 X)
+ * - values: 외부가 commit한 적용 값 (칩 표시·재적용 시 draft 동기화 기준)
+ *
+ * 핵심: **입력 즉시 onSearch 호출하지 않는다.** [검색] 버튼/Enter 시점에만 commit.
+ */
+export declare function useSearchBoxState({ fields, values, onSearch, onClear, }: UseSearchBoxStateArgs): {
+    draft: SearchValues;
+    setFieldValue: (key: string, value: string) => void;
+    submit: () => boolean;
+    clear: () => void;
+    chips: {
+        key: string;
+        label: string;
+        valueLabel: string;
+    }[];
+    removeChip: (key: string) => void;
+};
+export {};

package/dist/src/components/select/MultiSelect.d.ts

@@ -0,0 +1,69 @@
+import { SelectCommonProps, SelectOption } from './types';
+/**
+ * MultiSelect의 search 관련 props discriminated union.
+ * `searchable=true`일 때만 검색 prop이 의미가 있다 — Select와 동일 패턴.
+ */
+type MultiSelectSearchProps = {
+    searchable?: false;
+    searchPlaceholder?: never;
+    onSearchChange?: never;
+    isSearchLoading?: never;
+} | {
+    searchable: true;
+    /** 패널 검색 input placeholder. */
+    searchPlaceholder?: string;
+    /** 외부 검색(서버) 콜백. 제공 시 클라이언트 필터를 끄고 입력만 외부에 전달. */
+    onSearchChange?: (query: string) => void;
+    /** 외부 검색 로딩 상태. 패널 검색 input 옆 LoadingDots. */
+    isSearchLoading?: boolean;
+};
+type MultiSelectBaseProps = Omit<SelectCommonProps, "searchable" | "searchPlaceholder" | "onSearchChange" | "isSearchLoading"> & {
+    /** 선택 옵션 목록. */
+    options: SelectOption[];
+    /** 선택된 값들. 빈 배열이면 placeholder 노출. */
+    value: string[];
+    /** 값 변경 콜백. options 순서를 보존한 배열로 전달. */
+    onChange: (values: string[]) => void;
+    /** 트리거 추가 className. */
+    className?: string;
+    /** 드롭다운 패널 추가 className. */
+    panelClassName?: string;
+    /**
+     * 트리거에 보여줄 풀 텍스트 포맷터. 기본은 라벨을 콤마로 연결.
+     * 폭이 부족하면 자동으로 `formatCollapsed`로 폴백 (`disableAutoCollapse`로 끄기 가능).
+     */
+    formatTrigger?: (selectedOptions: SelectOption[]) => string;
+    /**
+     * 폭 부족 시 폴백 텍스트 포맷터. 기본은 `${count}개 선택`.
+     * 호출부 사용 예: `(sel) => sel.length > 0 ? `${sel.length}건 선택` : ""`
+     */
+    formatCollapsed?: (selectedOptions: SelectOption[]) => string;
+    /**
+     * 트리거 폭에 풀 텍스트가 안 들어갈 때 자동으로 `formatCollapsed`로 전환하는 동작 비활성화.
+     * 항상 풀 텍스트 + truncate ellipsis로 보고 싶을 때.
+     * @default false
+     */
+    disableAutoCollapse?: boolean;
+    /**
+     * 패널 상단에 "전체 선택/해제" 토글 버튼 노출.
+     * searchable 모드에서는 검색 결과(`filteredOptions`) 기준으로 동작.
+     * disabled 옵션은 자동 제외.
+     * @default false
+     */
+    showSelectAll?: boolean;
+    /** id (label htmlFor 연결용). */
+    id?: string;
+    /** name (form 제출용 hidden input. CSV 직렬화). */
+    name?: string;
+};
+type MultiSelectProps = MultiSelectBaseProps & MultiSelectSearchProps;
+/**
+ * 다중 선택 Select. 옵션 리스트에 체크박스를 표시하고 토글 방식으로 동작.
+ * 트리거/패널/슬롯/사이즈 정합은 단일 `Select`와 동일 (`shared/ui/input/utils` 공유).
+ *
+ * - searchable: 옵션 안 검색. `onSearchChange` 제공 시 외부 검색.
+ * - value는 string[]. options 순서를 보존해 emit.
+ * - 트리거에는 라벨을 콤마로 연결 — 길어지면 `formatTrigger`로 커스텀.
+ */
+export declare const MultiSelect: import('react').ForwardRefExoticComponent<MultiSelectProps & import('react').RefAttributes<HTMLButtonElement>>;
+export {};

package/dist/src/components/select/Select.d.ts

@@ -0,0 +1,81 @@
+import { SelectCommonProps, SelectOption } from './types';
+/**
+ * Select의 search 관련 props discriminated union.
+ * `searchable=true`일 때만 onSearchChange/isSearchLoading/onLoadMore/hasMore/searchDebounceMs/searchPlaceholder가 의미가 있다.
+ * 호출부가 `searchable=false`인데 검색 관련 prop을 넘기면 컴파일 에러로 차단.
+ */
+type SelectSearchProps = {
+    searchable?: false;
+    searchPlaceholder?: never;
+    onSearchChange?: never;
+    isSearchLoading?: never;
+    onLoadMore?: never;
+    hasMore?: never;
+    searchDebounceMs?: never;
+} | {
+    searchable: true;
+    /** 트리거 input의 검색 placeholder. selected 있을 때 fallback으로 노출. */
+    searchPlaceholder?: string;
+    /** 외부 검색(서버) 콜백. 제공 시 클라이언트 필터를 끄고 입력만 외부에 전달. */
+    onSearchChange?: (query: string) => void;
+    /** 외부 검색 로딩 상태. true면 트리거 우측에 스피너 + 무한스크롤 sentinel 동작 가드. */
+    isSearchLoading?: boolean;
+    /**
+     * 무한스크롤: 옵션 패널 끝에 도달하면 호출. 호출부가 다음 페이지 fetch + options append.
+     * `hasMore=true`일 때만 sentinel이 활성화되며, `isSearchLoading` 상태에서는 중복 호출 안 함.
+     */
+    onLoadMore?: () => void;
+    /** 무한스크롤: 더 가져올 페이지가 있는지. true일 때만 sentinel 노출. */
+    hasMore?: boolean;
+    /**
+     * `onSearchChange` 호출 디바운스 (ms). 0 또는 false면 즉시 호출.
+     * 클라이언트 필터(`onSearchChange` 미제공)에는 영향 없음.
+     * @default 300
+     */
+    searchDebounceMs?: number | false;
+};
+/** Select의 search 외 base props (SelectCommonProps에서 search 관련 제외). */
+type SelectBaseProps = Omit<SelectCommonProps, "searchable" | "searchPlaceholder" | "onSearchChange" | "isSearchLoading"> & {
+    /** 선택 옵션 목록. */
+    options: SelectOption[];
+    /** 선택된 값. 제어 컴포넌트로 사용. 빈 문자열이면 placeholder 노출. */
+    value: string;
+    /** 값 변경 콜백. clearable로 비울 때도 빈 문자열로 호출. */
+    onChange: (value: string) => void;
+    /** 드롭다운 패널 추가 className. */
+    panelClassName?: string;
+    /** 트리거 추가 className. */
+    className?: string;
+    /** id (label htmlFor 연결용). */
+    id?: string;
+    /** name (form 제출용 hidden input). */
+    name?: string;
+};
+type SelectProps = SelectBaseProps & SelectSearchProps;
+/**
+ * 단일 선택 Select. floating-ui 기반으로 트리거 폭과 패널 폭이 정합되며 a11y 표준 키보드 동작을 갖춘다.
+ *
+ * - 트리거 외관(슬롯/사이즈/variant)은 Input과 동일 토큰을 공유 (`shared/ui/input/utils`).
+ * - searchable: 옵션 안 검색 input. `onSearchChange` 제공 시 외부 검색(서버), 미제공 시 클라이언트 필터.
+ * - description/trailing은 옵션 리스트에서만 노출 — 트리거에는 label만.
+ *
+ * 자유 입력(옵션 외 값 허용)은 후속 `Autocomplete`로 분리.
+ *
+ * @example
+ * ```tsx
+ * <Select
+ *   variant="box"
+ *   options={[{ value: "kr", label: "한국" }]}
+ *   value={value}
+ *   onChange={setValue}
+ *   placeholder="국가 선택"
+ * />
+ * ```
+ */
+/**
+ * ref 타입은 trigger element를 가리킨다. searchable=false면 button, searchable=true면 input.
+ * 외부에서 보통 `.focus()` 정도만 사용하므로 union으로 정직하게 노출.
+ */
+export type SelectTriggerRef = HTMLButtonElement | HTMLInputElement;
+export declare const Select: import('react').ForwardRefExoticComponent<SelectProps & import('react').RefAttributes<SelectTriggerRef>>;
+export {};

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

@@ -0,0 +1,4 @@
+export { Select } from './Select';
+export type { SelectTriggerRef } from './Select';
+export { MultiSelect } from './MultiSelect';
+export type { SelectProps, SelectOption, SelectVariant, SelectSize, SelectLabelOption, } from './types';

package/dist/src/components/select/loading-dots.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 점 3개 점진적 페이드 로딩 인디케이터.
+ * 검색/페이지 fetch 중 부담 없는 시각 신호로 Select/MultiSelect 양쪽에서 공용.
+ *
+ * @keyframes는 tailwind animate-pulse를 stagger로 사용 — animationDelay만 inline.
+ */
+export declare const LoadingDots: ({ className }: {
+    className?: string;
+}) => import("react").JSX.Element;

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

@@ -0,0 +1,141 @@
+import { ComponentPropsWithoutRef, ReactNode, Ref } from 'react';
+/**
+ * Select 컴포넌트의 Variant 타입
+ */
+export type SelectVariant = "box" | "line" | "big" | "hero";
+/**
+ * Select 컴포넌트의 사이즈. Button/Input/Textarea와 동일 토큰. box variant에서만 적용.
+ * - mini: 모바일/매우 좁은 영역의 다건 입력
+ * - small: 다건 입력/표 형식 기본
+ * - medium: 폼 단독 입력 기본
+ * - large: 메인 페이지의 강조 선택
+ */
+export type SelectSize = "mini" | "small" | "medium" | "large";
+/**
+ * Select 컴포넌트의 Label 표시 방식 타입
+ */
+export type SelectLabelOption = "appear" | "sustain";
+/**
+ * Select 컴포넌트의 공통 Props
+ */
+export interface SelectCommonProps {
+    /**
+     * Select 필드의 모양
+     */
+    variant: SelectVariant;
+    /**
+     * Select 필드의 크기
+     * @default 'medium'
+     */
+    selectSize?: SelectSize;
+    /**
+     * Select 필드의 상단의 라벨
+     */
+    label?: string;
+    /**
+     * label 표시 방식
+     * 'appear': value가 있을 때만 label이 보여요
+     * 'sustain': 항상 label이 보여요
+     * @default 'sustain'
+     */
+    labelOption?: SelectLabelOption;
+    /**
+     * Select 필드의 하단의 도움말
+     */
+    help?: ReactNode;
+    /**
+     * placeholder 텍스트 (첫 번째 옵션의 라벨로 표시)
+     */
+    placeholder?: string;
+    /**
+     * Select 필드의 에러 여부
+     * @default false
+     */
+    hasError?: boolean;
+    /**
+     * Select 필드의 비활성화 여부
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * 트리거 텍스트 뒤에 붙는 단위 텍스트 (예: "원"). chevron 앞쪽 슬롯의 가장 좌측.
+     */
+    suffix?: string;
+    /**
+     * 우측 트레일링 아이콘 (lucide-react 등). suffix 다음, clearable 앞.
+     */
+    trailingIcon?: ReactNode;
+    /**
+     * 값이 있을 때 우측에 X 버튼(CircleX)을 노출. 클릭 시 onChange로 빈 값을 emit.
+     * disabled에서는 노출하지 않는다. trailingIcon 다음, badge 앞.
+     * @default false
+     */
+    clearable?: boolean;
+    /**
+     * chevron 바로 앞에 표시할 뱃지/라벨 ReactNode.
+     */
+    badge?: ReactNode;
+    /**
+     * 검색 기능 활성화 여부
+     * @default false
+     */
+    searchable?: boolean;
+    /**
+     * 검색 입력 필드 placeholder
+     * @default "검색..."
+     */
+    searchPlaceholder?: string;
+    /**
+     * 검색어 변경 시 호출되는 콜백 (서버 필터링용)
+     * 이 콜백이 제공되면 클라이언트 필터링을 비활성화하고 외부에서 options를 업데이트해야 함
+     */
+    onSearchChange?: (query: string) => void;
+    /**
+     * 서버 검색 중 로딩 상태
+     * @default false
+     */
+    isSearchLoading?: boolean;
+    /**
+     * 컨테이너의 추가 props
+     */
+    containerProps?: ComponentPropsWithoutRef<"div">;
+    /**
+     * 컨테이너의 ref
+     */
+    containerRef?: Ref<HTMLDivElement>;
+    /**
+     * 테스트 ID (data-testid)
+     */
+    "data-testid"?: string;
+}
+/**
+ * Select Option 타입
+ */
+export interface SelectOption {
+    value: string | number;
+    label: string;
+    /**
+     * 라벨 아래에 작게 표시되는 보조 설명. 두 줄 옵션이 필요할 때 사용.
+     * 트리거(닫힌 상태)에는 노출되지 않고 드롭다운 옵션 리스트에서만 보인다.
+     */
+    description?: string;
+    /**
+     * 라벨 우측에 작게 표시되는 보조 정보. 잔고/금액 등 정렬해서 보여주고 싶을 때.
+     * 트리거에는 노출되지 않고 드롭다운 옵션 리스트에서만 보인다.
+     */
+    trailing?: string;
+    disabled?: boolean;
+}
+/**
+ * Select 컴포넌트의 Props
+ */
+export interface SelectProps extends Omit<ComponentPropsWithoutRef<"select">, "color">, SelectCommonProps {
+    /**
+     * Select 옵션 목록
+     */
+    options?: SelectOption[];
+    /**
+     * children으로 option을 직접 전달할 수도 있어요
+     */
+    children?: ReactNode;
+}

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

@@ -0,0 +1,16 @@
+import { SelectSize, SelectVariant } from './types';
+/**
+ * Select Variant에 따른 컨테이너 클래스. 2026 리디자인 box variant는 Button/Input과 동일 토큰.
+ * line/big/hero는 레거시 — Input과 동일하게 추후 정리.
+ */
+export declare const getSelectVariantClasses: (variant: SelectVariant, hasError?: boolean, disabled?: boolean, size?: SelectSize) => string;
+/**
+ * Select의 텍스트 토큰 — Input과 동일한 색 위계.
+ * disabled / error / filled / placeholder 4단계.
+ */
+export declare const getSelectBaseClasses: (variant?: SelectVariant, hasError?: boolean, disabled?: boolean, filled?: boolean, size?: SelectSize) => string;
+/** trailing chevron 색 — Input의 trailing icon과 동일 위계. */
+export declare const getSelectTrailingIconColor: (hasError: boolean, disabled: boolean, filledOrFocused: boolean) => string;
+export declare const getSelectContainerClasses: () => string;
+export declare const getSelectLabelClasses: (_variant: SelectVariant, hasError: boolean) => string;
+export declare const getSelectHelpClasses: (hasError: boolean) => string;

package/dist/src/components/switch/Switch.d.ts

@@ -0,0 +1,17 @@
+import { SwitchProps } from './types';
+/**
+ * On/Off 토글 스위치.
+ *
+ * `<input type="checkbox">`를 시각적으로 가리고(`sr-only peer`) 트랙·노브를 그린다.
+ * 키보드(스페이스), 클릭, label 클릭 모두 native 동작 그대로 작동.
+ *
+ * @example
+ * ```tsx
+ * <Switch
+ *   checked={enabled}
+ *   onCheckedChange={setEnabled}
+ *   label="잔여한도 지급 기능 사용"
+ * />
+ * ```
+ */
+export declare const Switch: import('react').ForwardRefExoticComponent<SwitchProps & import('react').RefAttributes<HTMLInputElement>>;

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

@@ -0,0 +1,2 @@
+export { Switch } from './Switch';
+export type { SwitchProps, SwitchSize } from './types';

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

@@ -0,0 +1,10 @@
+import { InputHTMLAttributes } from 'react';
+export type SwitchSize = "small" | "medium";
+export interface SwitchProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "size" | "type"> {
+    /** 트랙·노브 사이즈. 기본 medium. */
+    size?: SwitchSize;
+    /** 우측 라벨. 지정하면 클릭 가능한 label로 감싸진다. */
+    label?: string;
+    /** 체크 상태 변경 콜백. onChange와 함께 호출된다. */
+    onCheckedChange?: (checked: boolean) => void;
+}

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

@@ -0,0 +1,14 @@
+import { SwitchSize } from './types';
+/**
+ * 트랙(외곽) 사이즈 매핑.
+ * 노브는 트랙 안에서 padding 2px만큼 들어가 있고, ON 시 (트랙 width − 노브 width − padding × 2)만큼 우측 이동.
+ */
+export declare const SWITCH_SIZE_MAP: Record<SwitchSize, {
+    track: string;
+    thumb: string;
+    translate: string;
+}>;
+/** 트랙(외곽 박스) 클래스. peer-checked로 ON/OFF 색 전환. */
+export declare function getSwitchTrackClasses(size: SwitchSize, disabled: boolean): string;
+/** 노브(원형) 클래스. translateX로 좌→우 이동. wrapper 기준 absolute로 트랙 위에 뜬다. */
+export declare function getSwitchThumbClasses(size: SwitchSize): string;

package/dist/src/components/table/accordion-table.d.ts

@@ -0,0 +1,31 @@
+import { ReactNode } from 'react';
+import { PaginatedTableProps } from './types';
+export type ExpandedRowId = string | number;
+export interface AccordionExpandable<T> {
+    /** 펼친 행 안에 그릴 콘텐츠 */
+    renderRow: (row: T) => ReactNode;
+    /** 현재 펼쳐진 행 id 집합 */
+    expandedIds: Set<ExpandedRowId>;
+    /**
+     * 토글 콜백. single/multiple 동작은 호출부에서 결정 — 컴포넌트는 단순히 행 토글 의도만 전달한다.
+     * - multiple: `setExpanded(prev => prev.has(id) ? new Set([...prev].filter(x => x !== id)) : new Set([...prev, id]))`
+     * - single: `setExpanded(prev => prev.has(id) ? new Set() : new Set([id]))`
+     */
+    onToggle: (id: ExpandedRowId) => void;
+    /** 행 → 안정 식별자 */
+    getRowId: (row: T) => ExpandedRowId;
+    /**
+     * 펼침 콘텐츠가 가로스크롤에 따라 좌측에 sticky 하게 따라오게 할지 여부.
+     * @default true
+     */
+    stickyDetail?: boolean;
+}
+export interface AccordionTableProps<T> extends PaginatedTableProps<T> {
+    /**
+     * 행 펼침 설정. 미지정 시 PaginatedTable과 동일하게 동작 (토글 컬럼/펼침 행 없음).
+     */
+    expandable?: AccordionExpandable<T>;
+}
+export declare const AccordionTable: <T>(props: AccordionTableProps<T> & {
+    ref?: React.ForwardedRef<HTMLDivElement>;
+}) => React.ReactElement;

package/dist/src/components/table/column-group-utils.d.ts

@@ -0,0 +1,49 @@
+import { TableColumn, TableColumnGroupMeta } from './types';
+/**
+ * 슬롯(그룹 또는 단일 컬럼) 단위 표현.
+ *
+ * 옵션 2 정책의 핵심 — columnOrder/hiddenColumns가 다루는 단위는 슬롯이지 평면 컬럼이 아니다.
+ * - 그룹: 묶음 고정. 하위 컬럼 키들은 슬롯에 속하지만 columnOrder에는 들어가지 않는다.
+ * - 단일 컬럼: 슬롯과 컬럼이 1:1.
+ */
+export interface ColumnSlot<T> {
+    kind: "group" | "column";
+    /** 슬롯 키. 그룹키 또는 컬럼키. */
+    key: string;
+    header: TableColumn<T>["header"];
+    /** 그룹이면 하위 컬럼 배열, 단일 컬럼이면 자기 자신 한 개. */
+    leafColumns: TableColumn<T>[];
+    /** hideOnMobile: 그룹 메타의 옵션 또는 단일 컬럼의 hideOnMobile. */
+    hideOnMobile?: boolean;
+    /** 그룹 메타 원본 (그룹일 때만). */
+    group?: TableColumnGroupMeta;
+}
+/**
+ * 평면 컬럼 배열 + 그룹 메타를 받아 슬롯 단위로 묶는다.
+ *
+ * 그룹에 속한 컬럼들은 그룹 슬롯 1개로 합쳐지고, 속하지 않은 컬럼은 각자 슬롯이 된다.
+ * 그룹 내부 컬럼 순서는 `group.columnKeys` 순서대로 강제 — `columns` 배열 내 등장 순서와 다를 수 있다.
+ *
+ * 그룹 메타에 정의된 columnKey가 columns에 없으면 무시(방어).
+ */
+export declare function buildColumnSlots<T>(columns: TableColumn<T>[], groups?: TableColumnGroupMeta[]): ColumnSlot<T>[];
+/**
+ * 슬롯 키 배열을 columnState.columnOrder의 기본값으로 변환. (그룹키 또는 컬럼키)
+ */
+export declare function getDefaultSlotOrder<T>(slots: ColumnSlot<T>[]): string[];
+/**
+ * columnOrder(슬롯 키 배열) + hiddenSlots를 적용해 가시 슬롯만 추려낸다.
+ * 정의에 `hidden: true`로 박힌 단일 컬럼도 함께 제거.
+ *
+ * columnOrder에 없는 신규 슬롯(저장된 프리셋 이후 추가된 컬럼/그룹)은 끝에 자동 append —
+ * useColumnPresets의 mergeColumnOrders가 effect로 합쳐주기 전 첫 렌더에서 빠지는 깜빡임을 막는다.
+ */
+export declare function applyColumnState<T>(slots: ColumnSlot<T>[], columnOrder: string[], hiddenSlotKeys: Set<string>): ColumnSlot<T>[];
+/**
+ * 가시 슬롯 → 평면 leaf 컬럼 시퀀스 (tbody td 매핑/colgroup/너비계산에 사용).
+ */
+export declare function flattenLeafColumns<T>(visibleSlots: ColumnSlot<T>[]): TableColumn<T>[];
+/**
+ * 가시 슬롯 중 하나라도 그룹이 있는지 — thead 2-row 분기 신호.
+ */
+export declare function hasGroupSlot<T>(visibleSlots: ColumnSlot<T>[]): boolean;

package/dist/src/components/table/components/ColumnPresetSelector.d.ts

@@ -0,0 +1,36 @@
+import { PresetNumber } from '../../../../lib/column-preset-storage';
+import { TableColumn, TableColumnGroupMeta } from '../types';
+interface ColumnPresetSelectorProps<T> {
+    columns: TableColumn<T>[];
+    columnGroups?: TableColumnGroupMeta[];
+    activePreset: PresetNumber;
+    columnOrder: string[];
+    hiddenColumns: string[];
+    columnWidths: Record<string, number>;
+    isDirty: boolean;
+    hasPreset: (num: PresetNumber) => boolean;
+    onApplyPreset: (num: PresetNumber) => void;
+    /** 현재 편집 중 상태를 활성 프리셋에 저장(commit). 저장 불가하면 false. */
+    onSaveActivePreset: () => boolean;
+    /** 활성 프리셋을 기본값으로 되돌리기. */
+    onResetActivePreset: () => void;
+    /** 편집 중 컬럼 순서 갱신. */
+    onColumnOrderChange: (next: string[]) => void;
+    /** 편집 중 숨김 컬럼 갱신. */
+    onHiddenColumnsChange: (next: string[]) => void;
+    /** 단일 컬럼 너비 갱신. 0 이하면 키 제거(기본값 복원). */
+    onSetColumnWidth: (key: string, width: number) => void;
+    className?: string;
+}
+/**
+ * 컬럼 프리셋 셀렉터 + 설정 드롭다운
+ *
+ * pill 형태 세그먼트 컨트롤. 톱니(설정) + 세로 디바이더 + 프리셋 1·2·3.
+ * 활성 프리셋은 흰 배경이 layoutId로 슬라이드되며 이동.
+ * 위치 계산은 floating-ui 위임 — flip으로 공간 부족 시 위로 뒤집고, shift로 viewport 안에 클램프.
+ *
+ * 편집 중 변경은 외부(useColumnPresets)에 즉시 반영되고, 명시 저장 시에만 영구화.
+ * isDirty가 true면 톱니 옆에 점을 표시한다.
+ */
+export declare function ColumnPresetSelector<T>({ columns, columnGroups, activePreset, columnOrder, hiddenColumns, columnWidths, isDirty, hasPreset, onApplyPreset, onSaveActivePreset, onResetActivePreset, onColumnOrderChange, onHiddenColumnsChange, onSetColumnWidth, className, }: ColumnPresetSelectorProps<T>): import("react").JSX.Element;
+export {};