@uniai-fe/uds-primitives 0.12.7 → 0.12.9

package/src/components/input/types/date.ts

@@ -1,4 +1,9 @@
-import type { MouseEvent, ReactNode } from "react";
+import type {
+  ComponentPropsWithoutRef,
+  FocusEvent,
+  MouseEvent,
+  ReactNode,
+} from "react";
 import type { UseFormRegisterReturn } from "react-hook-form";
 import type {
   CalendarColumns,
@@ -10,7 +15,18 @@ import type {
   CalendarRangeValue,
   CalendarValue,
 } from "../../calendar";
-import type { InputPriority, InputState } from "./foundation";
+import type { FormFieldWidth } from "../../form/types/props";
+import type { InputPriority, InputSize, InputState } from "./foundation";
+
+/**
+ * Input Date hidden input props.
+ * @typedef {Omit<ComponentPropsWithoutRef<"input">, "type" | "value" | "defaultValue" | "name">} InputCalendarHiddenInputProps
+ * @desc Template이 고정하는 type, value, defaultValue와 name을 제외한 native hidden input 계약
+ */
+export type InputCalendarHiddenInputProps = Omit<
+  ComponentPropsWithoutRef<"input">,
+  "type" | "value" | "defaultValue" | "name"
+>;
 
 /**
  * Calendar trigger(Input) 영역에서 필요한 속성 묶음.
@@ -22,8 +38,14 @@ import type { InputPriority, InputState } from "./foundation";
  * @property {boolean} [disabled] disabled 여부
  * @property {boolean} [readOnly] readOnly 여부
  * @property {string} [placeholder] trigger 내부 placeholder
- * @property {InputPriority} [priority] trigger input priority
- * @property {InputState} [state] trigger input state
+ * @property {"primary" | "secondary" | "tertiary" | "table"} [priority] trigger input priority
+ * @property {"small" | "medium" | "large"} [size] trigger input size
+ * @property {"default" | "active" | "focused" | "success" | "error" | "disabled" | "loading"} [state] trigger input state
+ * @property {boolean} [block] trigger width 100% 여부
+ * @property {"full" | "fit" | "fill" | "auto" | number | string} [width] trigger width preset 또는 custom width
+ * @property {(event: FocusEvent<HTMLInputElement>) => void} [onFocus] trigger focus 핸들러
+ * @property {(event: FocusEvent<HTMLInputElement>) => void} [onBlur] trigger blur 핸들러
+ * @desc Date trigger의 표시·상호작용 입력 계약. Template의 name/register는 hidden input 저장에 사용한다.
  */
 export interface InputCalendarTriggerProps {
   /**
@@ -59,16 +81,38 @@ export interface InputCalendarTriggerProps {
    * - table일 때 Trigger는 left icon 배치를 사용한다.
    */
   priority?: InputPriority;
+  /**
+   * "small" | "medium" | "large".
+   */
+  size?: InputSize;
   /**
    * trigger input state
    */
   state?: InputState;
+  /**
+   * trigger width 100% 여부.
+   */
+  block?: boolean;
+  /**
+   * "full" | "fit" | "fill" | "auto" | number | string.
+   */
+  width?: FormFieldWidth;
+  /**
+   * trigger focus 핸들러.
+   */
+  onFocus?: (event: FocusEvent<HTMLInputElement>) => void;
+  /**
+   * trigger blur 핸들러.
+   */
+  onBlur?: (event: FocusEvent<HTMLInputElement>) => void;
 }
 
 /**
  * Trigger view에서만 사용하는 부가 props.
  * @property {string} [className] trigger root className
  * @property {string} [displayValue] 표시 값 문자열
+ * @see InputCalendarTriggerProps
+ * @desc 기본 Date trigger가 InputFoundation.Base에 전달하는 view 계약
  */
 export interface InputCalendarTriggerViewProps extends InputCalendarTriggerProps {
   /**
@@ -90,8 +134,14 @@ export interface InputCalendarTriggerViewProps extends InputCalendarTriggerProps
  * @property {boolean} [disabled] disabled 여부
  * @property {boolean} [readOnly] readOnly 여부
  * @property {(event: MouseEvent<Element>) => void} [onClick] 트리거 클릭 핸들러
- * @property {InputPriority} [priority] trigger input priority
- * @property {InputState} [state] trigger input state
+ * @property {"primary" | "secondary" | "tertiary" | "table"} [priority] trigger input priority
+ * @property {"small" | "medium" | "large"} [size] trigger input size
+ * @property {"default" | "active" | "focused" | "success" | "error" | "disabled" | "loading"} [state] trigger input state
+ * @property {boolean} [block] trigger width 100% 여부
+ * @property {"full" | "fit" | "fill" | "auto" | number | string} [width] trigger width preset 또는 custom width
+ * @property {(event: FocusEvent<HTMLInputElement>) => void} [onFocus] trigger focus 핸들러
+ * @property {(event: FocusEvent<HTMLInputElement>) => void} [onBlur] trigger blur 핸들러
+ * @desc custom Date trigger에 전달하는 표시·상호작용 계약
  */
 export interface InputCalendarTriggerRenderProps {
   /**
@@ -127,57 +177,92 @@ export interface InputCalendarTriggerRenderProps {
    * - table일 때 Trigger는 left icon 배치를 사용한다.
    */
   priority?: InputPriority;
+  /**
+   * "small" | "medium" | "large".
+   */
+  size?: InputSize;
   /**
    * trigger input state
    */
   state?: InputState;
+  /**
+   * trigger width 100% 여부.
+   */
+  block?: boolean;
+  /**
+   * "full" | "fit" | "fill" | "auto" | number | string.
+   */
+  width?: FormFieldWidth;
+  /**
+   * trigger focus 핸들러.
+   */
+  onFocus?: (event: FocusEvent<HTMLInputElement>) => void;
+  /**
+   * trigger blur 핸들러.
+   */
+  onBlur?: (event: FocusEvent<HTMLInputElement>) => void;
 }
 
 /**
  * Input Calendar core props.
- * @property {CalendarMode} [mode="date"] 날짜/시간 모드
- * @property {CalendarColumns} [columns=1] 동시에 노출할 달력 열 수
- * @property {CalendarValue} [value] 제어형 값
- * @property {CalendarValue} [defaultValue] 비제어 초기값
- * @property {CalendarOnChange} [onChange] 값 변경 핸들러(직렬화 문자열 기준)
- * @property {CalendarOnChange} [onValueChange] onChange 별칭(추가 파이프라인용)
+ * @property {"date" | "date-time" | "time"} [mode="date"] Calendar layout mode. 선택 body는 date로 유지된다.
+ * @property {1 | 2} [columns=1] 동시에 노출할 달력 열 수
+ * @property {string | null} [value] 제어형 값
+ * @property {string | null} [defaultValue] 비제어 초기값
+ * @property {(value: string | null) => void} [onChange] 값 변경 핸들러(직렬화 문자열 기준)
+ * @property {(value: string | null) => void} [onValueChange] onChange 별칭(추가 파이프라인용)
  * @property {boolean} [readOnly] 읽기 전용 여부
  * @property {boolean} [disabled] disabled 여부
  * @property {CalendarDatePickerProps} [datePickerProps] Mantine DatePicker 직접 옵션
- * @property {InputPriority} [priority] trigger input priority
- * @property {InputState} [state] trigger input state
+ * @property {string} [id] trigger id
+ * @property {string} [name] hidden input form name
+ * @property {UseFormRegisterReturn} [register] hidden input react-hook-form register 결과
+ * @property {string} [placeholder] trigger 내부 placeholder
+ * @property {(event: MouseEvent<Element>) => void} [onClick] trigger 클릭 핸들러
+ * @property {"primary" | "secondary" | "tertiary" | "table"} [priority] trigger input priority
+ * @property {"small" | "medium" | "large"} [size] trigger input size
+ * @property {"default" | "active" | "focused" | "success" | "error" | "disabled" | "loading"} [state] trigger input state
+ * @property {boolean} [block] trigger width 100% 여부
+ * @property {"full" | "fit" | "fill" | "auto" | number | string} [width] trigger width preset 또는 custom width
+ * @property {string} [form] hidden input이 연결될 form id
+ * @property {boolean} [required] hidden input required 여부
+ * @property {InputCalendarHiddenInputProps} [hiddenInputProps] Template 고정값을 제외한 hidden input native props
+ * @property {(event: FocusEvent<HTMLInputElement>) => void} [onFocus] trigger focus 핸들러
+ * @property {(event: FocusEvent<HTMLInputElement>) => void} [onBlur] trigger blur 핸들러와 RHF touched 동기화 진입점
  * @property {ReactNode} [header] 커스텀 header 콘텐츠
  * @property {ReactNode} [footer] 커스텀 footer 콘텐츠
  * @property {InputCalendarTexts} [texts] 기본 Date 문구
- * @property {unknown} [timePicker] TimePicker 확장용 예약 슬롯(현재 미구현)
+ * @property {unknown} [timePicker] 미구현 compatibility prop. 시간 선택에는 Input.Time.Template을 사용한다.
  * @property {boolean} [calendarOpened] calendar 열림 제어 여부
  * @property {(open: boolean) => void} [onCalendarOpen] calendar 열림 변경 이벤트
  * @property {ReactNode} [trigger] 커스텀 trigger 슬롯
  * @property {(props: InputCalendarTriggerRenderProps) => ReactNode} [renderTrigger] 커스텀 trigger 렌더 함수
+ * @desc 단일 날짜 trigger, Calendar와 hidden form storage를 조합하는 공개 계약
  */
 export interface InputCalendarProps extends InputCalendarTriggerProps {
   /**
-   * 날짜/시간 모드
+   * "date" | "date-time" | "time".
+   * Calendar layout의 data-mode만 지정하며 선택 body는 date로 유지된다.
    */
   mode?: CalendarMode;
   /**
-   * 동시에 노출할 달력 열 수
+   * 1 | 2.
    */
   columns?: CalendarColumns;
   /**
-   * 제어형 값
+   * string | null.
    */
   value?: CalendarValue;
   /**
-   * 비제어 초기값
+   * string | null.
    */
   defaultValue?: CalendarValue;
   /**
-   * 값 변경 핸들러
+   * (value: string | null) => void.
    */
   onChange?: CalendarOnChange;
   /**
-   * onChange 별칭; 외부 파이프라인 시 사용
+   * (value: string | null) => void. onChange 별칭으로 외부 파이프라인에 사용한다.
    */
   onValueChange?: CalendarOnChange;
   /**
@@ -205,8 +290,8 @@ export interface InputCalendarProps extends InputCalendarTriggerProps {
    */
   texts?: InputCalendarTexts;
   /**
-   * TimePicker 확장용 예약 슬롯(현재 미구현).
-   * 추후 Calendar Body 조합 확장 시점에 구체 타입을 확정한다.
+   * TimePicker 확장용 미구현 compatibility prop.
+   * @deprecated 시간 선택에는 Input.Time.Template을 사용한다.
    */
   timePicker?: unknown;
   /**
@@ -226,14 +311,26 @@ export interface InputCalendarProps extends InputCalendarTriggerProps {
    * 커스텀 trigger 렌더 함수
    */
   renderTrigger?: (props: InputCalendarTriggerRenderProps) => ReactNode;
+  /**
+   * hidden input이 연결될 form id.
+   */
+  form?: string;
+  /**
+   * hidden input required 여부.
+   */
+  required?: boolean;
+  /**
+   * Template 고정값을 제외한 hidden input native props.
+   */
+  hiddenInputProps?: InputCalendarHiddenInputProps;
 }
 
 /**
  * Input Calendar Range Template props.
- * @property {CalendarRangeValue} [value] 제어형 range 값
- * @property {CalendarRangeValue} [defaultValue] 비제어 range 초기값
- * @property {CalendarRangeOnChange} [onChange] range 값 변경 핸들러
- * @property {CalendarRangeOnChange} [onValueChange] onChange 별칭
+ * @property {[string | null, string | null]} [value] 제어형 range 값
+ * @property {[string | null, string | null]} [defaultValue] 비제어 range 초기값
+ * @property {(value: [string | null, string | null]) => void} [onChange] range 값 변경 핸들러
+ * @property {(value: [string | null, string | null]) => void} [onValueChange] onChange 별칭
  * @property {boolean} [readOnly] 읽기 전용 여부
  * @property {boolean} [disabled] disabled 여부
  * @property {CalendarRangeDatePickerProps} [datePickerProps] Mantine range DatePicker 옵션
@@ -242,8 +339,17 @@ export interface InputCalendarProps extends InputCalendarTriggerProps {
  * @property {UseFormRegisterReturn} [startRegister] 시작일 react-hook-form register 결과
  * @property {UseFormRegisterReturn} [endRegister] 종료일 react-hook-form register 결과
  * @property {string} [placeholder] trigger 내부 placeholder
- * @property {InputPriority} [priority] trigger input priority
- * @property {InputState} [state] trigger input state
+ * @property {"primary" | "secondary" | "tertiary" | "table"} [priority] trigger input priority
+ * @property {"small" | "medium" | "large"} [size] trigger input size
+ * @property {"default" | "active" | "focused" | "success" | "error" | "disabled" | "loading"} [state] trigger input state
+ * @property {boolean} [block] trigger width 100% 여부
+ * @property {"full" | "fit" | "fill" | "auto" | number | string} [width] trigger width preset 또는 custom width
+ * @property {string} [form] start/end hidden input이 연결될 공통 form id
+ * @property {boolean} [required] start/end hidden input required 여부
+ * @property {InputCalendarHiddenInputProps} [startHiddenInputProps] 시작일 hidden input native props
+ * @property {InputCalendarHiddenInputProps} [endHiddenInputProps] 종료일 hidden input native props
+ * @property {(event: FocusEvent<HTMLInputElement>) => void} [onFocus] trigger focus 핸들러
+ * @property {(event: FocusEvent<HTMLInputElement>) => void} [onBlur] trigger blur 핸들러와 RHF touched 동기화 진입점
  * @property {ReactNode} [header] 커스텀 header 콘텐츠
  * @property {ReactNode} [footer] 커스텀 footer 콘텐츠
  * @property {InputCalendarTexts} [texts] 기본 Date 문구
@@ -253,22 +359,23 @@ export interface InputCalendarProps extends InputCalendarTriggerProps {
  * @property {ReactNode} [trigger] 커스텀 trigger 슬롯
  * @property {(props: InputCalendarTriggerRenderProps) => ReactNode} [renderTrigger] 커스텀 trigger 렌더 함수
  * @property {(event: MouseEvent<Element>) => void} [onClick] trigger 클릭 핸들러
+ * @desc 기간 trigger, Calendar.Range와 start/end hidden form storage를 조합하는 공개 계약
  */
 export interface InputCalendarRangeProps {
   /**
-   * 제어형 range 값
+   * [string | null, string | null].
    */
   value?: CalendarRangeValue;
   /**
-   * 비제어 range 초기값
+   * [string | null, string | null].
    */
   defaultValue?: CalendarRangeValue;
   /**
-   * range 값 변경 핸들러
+   * (value: [string | null, string | null]) => void.
    */
   onChange?: CalendarRangeOnChange;
   /**
-   * onChange 별칭; 외부 파이프라인 시 사용
+   * (value: [string | null, string | null]) => void. onChange 별칭으로 외부 파이프라인에 사용한다.
    */
   onValueChange?: CalendarRangeOnChange;
   /**
@@ -308,10 +415,46 @@ export interface InputCalendarRangeProps {
    * - table일 때 Trigger는 left icon 배치를 사용한다.
    */
   priority?: InputPriority;
+  /**
+   * "small" | "medium" | "large".
+   */
+  size?: InputSize;
   /**
    * trigger input state
    */
   state?: InputState;
+  /**
+   * trigger width 100% 여부.
+   */
+  block?: boolean;
+  /**
+   * "full" | "fit" | "fill" | "auto" | number | string.
+   */
+  width?: FormFieldWidth;
+  /**
+   * start/end hidden input이 연결될 공통 form id.
+   */
+  form?: string;
+  /**
+   * start/end hidden input required 여부.
+   */
+  required?: boolean;
+  /**
+   * 시작일 hidden input native props.
+   */
+  startHiddenInputProps?: InputCalendarHiddenInputProps;
+  /**
+   * 종료일 hidden input native props.
+   */
+  endHiddenInputProps?: InputCalendarHiddenInputProps;
+  /**
+   * trigger focus 핸들러.
+   */
+  onFocus?: (event: FocusEvent<HTMLInputElement>) => void;
+  /**
+   * trigger blur 핸들러.
+   */
+  onBlur?: (event: FocusEvent<HTMLInputElement>) => void;
   /**
    * 커스텀 header 콘텐츠
    */

package/src/components/input/types/time.ts

@@ -21,6 +21,8 @@ export type InputTimeIconPosition = "left" | "right";
 
 /**
  * Input Time hidden input props.
+ * @typedef {Omit<ComponentPropsWithoutRef<"input">, "type" | "value" | "defaultValue" | "name">} InputTimeHiddenInputProps
+ * @desc Template이 고정하는 type, value, defaultValue와 name을 제외한 native hidden input 계약
  */
 export type InputTimeHiddenInputProps = Omit<
   ComponentPropsWithoutRef<"input">,
@@ -32,6 +34,7 @@ export type InputTimeHiddenInputProps = Omit<
  * @property {string} hours 시 입력값
  * @property {string} minutes 분 입력값
  * @property {string} seconds 초 입력값
+ * @desc 입력 field에 표시하는 시·분·초 draft 문자열
  */
 export interface InputTimeDraftFields {
   /**
@@ -52,6 +55,7 @@ export interface InputTimeDraftFields {
  * Input Time 편집 중인 시간 값.
  * @property {InputTimeDraftFields} fields 시·분·초 입력값
  * @property {"am" | "pm"} period 오전·오후 구분
+ * @desc 저장값 commit 전의 field 문자열과 12시간제 period 상태
  */
 export interface InputTimeDraft {
   /**
@@ -99,6 +103,7 @@ export type InputTimeTriggerFields = InputTimeDraftFields;
  * @property {(period: "am" | "pm") => void} onPeriodChange 오전·오후 변경 핸들러
  * @property {(amount: 1 | -1) => void} onStep 활성 단위 증감 핸들러
  * @property {(event: FocusEvent<HTMLDivElement>) => void} onRootBlur root blur 핸들러
+ * @desc 시·분·초 field, period, stepper와 clock action을 렌더링하기 위한 trigger 계약
  */
 export interface InputTimeTriggerProps extends Omit<
   ComponentPropsWithoutRef<"div">,
@@ -225,8 +230,8 @@ export interface InputTimeTriggerProps extends Omit<
  * 저장값은 24시간 `HH:mm` 또는 `HH:mm:ss` 문자열을 사용한다.
  * @property {string} [value] 제어형 시간 값
  * @property {string} [defaultValue] 비제어 초기 시간 값
- * @property {(value:string)=>void} [onChange] 값 변경 핸들러
- * @property {(value:string)=>void} [onValueChange] 값 변경 별칭
+ * @property {(value: string) => void} [onChange] 값 변경 핸들러
+ * @property {(value: string) => void} [onValueChange] 값 변경 별칭
  * @property {string} [name] form name
  * @property {string} [form] form id
  * @property {UseFormRegisterReturn} [register] react-hook-form register 결과
@@ -257,8 +262,9 @@ export interface InputTimeTriggerProps extends Omit<
  * @property {string} [hoursPlaceholder] 시 placeholder
  * @property {string} [minutesPlaceholder] 분 placeholder
  * @property {string} [secondsPlaceholder] 초 placeholder
- * @property {(event:FocusEvent<HTMLInputElement>)=>void} [onFocus] focus 핸들러
- * @property {(event:FocusEvent<HTMLDivElement>)=>void} [onBlur] blur 핸들러
+ * @property {(event: FocusEvent<HTMLInputElement>) => void} [onFocus] focus 핸들러
+ * @property {(event: FocusEvent<HTMLDivElement>) => void} [onBlur] blur 핸들러
+ * @desc 시간 trigger, TimePicker panel과 24시간 문자열 hidden form storage를 조합하는 공개 계약
  */
 export interface InputTimeTemplateProps {
   /**

package/src/components/time-picker/markup/Footer.tsx

@@ -5,11 +5,11 @@ import type { TimePickerFooterProps } from "../types";
  * TimePicker Footer; 삭제와 적용 action을 렌더한다.
  * @component
  * @param {TimePickerFooterProps} props
- * @param {boolean} props.clearable 삭제 action 노출 여부
- * @param {boolean} props.disabled 비활성화 여부
- * @param {() => void} props.onClear 삭제 핸들러
- * @param {() => void} props.onApply 적용 핸들러
- * @returns {ReactNode} TimePicker footer
+ * @property {boolean} props.clearable 삭제 action 노출 여부
+ * @property {boolean} props.disabled 비활성화 여부
+ * @property {() => void} props.onClear 삭제 핸들러
+ * @property {() => void} props.onApply 적용 핸들러
+ * @desc clearable 상태에 따라 삭제 action을 노출하고 적용 action을 유지한다.
  * @example
  * <TimePickerFooter
  *   clearable

package/src/components/time-picker/markup/HourSection.tsx

@@ -12,13 +12,13 @@ const PERIOD_OPTIONS = [
  * TimePicker Hour Section; 오전·오후와 시 선택 grid를 렌더한다.
  * @component
  * @param {TimePickerHourSectionProps} props
- * @param {"12h" | "24h"} props.format 표시 형식
- * @param {number | null} props.selectedHour 선택한 표시 시
- * @param {"am" | "pm"} props.period 오전·오후
- * @param {boolean} props.disabled 비활성화 여부
- * @param {(hours: number) => void} props.onHourSelect 시 선택 핸들러
- * @param {(period: "am" | "pm") => void} props.onPeriodChange 오전·오후 변경 핸들러
- * @returns {ReactNode} 시간 선택 section
+ * @property {"12h" | "24h"} props.format 표시 형식
+ * @property {number | null} props.selectedHour 선택한 표시 시
+ * @property {"am" | "pm"} props.period 오전·오후
+ * @property {boolean} props.disabled 비활성화 여부
+ * @property {(hours: number) => void} props.onHourSelect 시 선택 핸들러
+ * @property {(period: "am" | "pm") => void} props.onPeriodChange 오전·오후 변경 핸들러
+ * @desc 12시간제와 24시간제에 맞는 시 목록과 period control을 렌더한다.
  * @example
  * <TimePickerHourSection
  *   format="12h"

package/src/components/time-picker/markup/MinuteSection.tsx

@@ -8,11 +8,11 @@ const MINUTES = Array.from({ length: 12 }, (_, index) => index * 5);
  * TimePicker Minute Section; 1분 stepper와 5분 선택 grid를 렌더한다.
  * @component
  * @param {TimePickerMinuteSectionProps} props
- * @param {number | null} props.selectedMinute 선택한 분
- * @param {boolean} props.disabled 비활성화 여부
- * @param {(amount: 1 | -1) => void} props.onMinuteStep 1분 증감 핸들러
- * @param {(minutes: number) => void} props.onMinuteSelect 분 선택 핸들러
- * @returns {ReactNode} 분 선택 section
+ * @property {number | null} props.selectedMinute 선택한 분
+ * @property {boolean} props.disabled 비활성화 여부
+ * @property {(amount: 1 | -1) => void} props.onMinuteStep 1분 증감 핸들러
+ * @property {(minutes: number) => void} props.onMinuteSelect 분 선택 핸들러
+ * @desc 5분 간격 빠른 선택과 1분 단위 미세 조정을 함께 제공한다.
  * @example
  * <TimePickerMinuteSection
  *   selectedMinute={30}

package/src/components/time-picker/markup/Summary.tsx

@@ -4,8 +4,8 @@ import type { TimePickerSummaryProps } from "../types";
  * TimePicker Summary; 현재 선택한 시간을 표시한다.
  * @component
  * @param {TimePickerSummaryProps} props
- * @param {string} props.summary 선택한 시간 표시값
- * @returns {ReactNode} 선택 시간 요약
+ * @property {string} props.summary 선택한 시간 표시값
+ * @desc TimePicker panel 상단에 현재 선택값 또는 빈 상태를 표시한다.
  * @example
  * <TimePickerSummary summary="09:30 오전" />
  */

package/src/components/time-picker/markup/Template.tsx

@@ -11,17 +11,17 @@ import TimePickerSummary from "./Summary";
  * TimePicker Template; Figma의 시간·분 선택과 footer action을 렌더한다.
  * @component
  * @param {TimePickerTemplateProps} props
- * @param {string} props.value 24시간 형식 시간 값
- * @param {"12h" | "24h"} props.format 표시 형식
- * @param {boolean} props.clearable 삭제 action 노출 여부
- * @param {boolean} props.disabled 비활성화 여부
- * @param {(hours: number) => void} props.onHourSelect 시 선택 핸들러
- * @param {(minutes: number) => void} props.onMinuteSelect 분 선택 핸들러
- * @param {(period: "am" | "pm") => void} props.onPeriodChange 오전·오후 변경 핸들러
- * @param {(amount: 1 | -1) => void} props.onMinuteStep 1분 증감 핸들러
- * @param {() => void} props.onClear 삭제 핸들러
- * @param {() => void} props.onApply 적용 핸들러
- * @returns {ReactNode} 시간 선택 panel
+ * @property {string} props.value 24시간 형식 시간 값
+ * @property {"12h" | "24h"} props.format 표시 형식
+ * @property {boolean} props.clearable 삭제 action 노출 여부
+ * @property {boolean} props.disabled 비활성화 여부
+ * @property {(hours: number) => void} props.onHourSelect 시 선택 핸들러
+ * @property {(minutes: number) => void} props.onMinuteSelect 분 선택 핸들러
+ * @property {(period: "am" | "pm") => void} props.onPeriodChange 오전·오후 변경 핸들러
+ * @property {(amount: 1 | -1) => void} props.onMinuteStep 1분 증감 핸들러
+ * @property {() => void} props.onClear 삭제 핸들러
+ * @property {() => void} props.onApply 적용 핸들러
+ * @desc 24시간 저장값을 표시 형식에 맞춰 시·분 선택 section과 action에 배분한다.
  * @example
  * <TimePicker.Template
  *   value="09:30"

package/src/components/time-picker/types/time-picker.ts

@@ -21,6 +21,7 @@ export type TimePickerUnit = "hours" | "minutes" | "seconds";
  * @property {number} hours 시
  * @property {number} minutes 분
  * @property {number} seconds 초
+ * @desc 24시간 저장값의 정규화된 시·분·초 숫자 구성
  */
 export interface TimePickerParts {
   /**
@@ -49,6 +50,7 @@ export interface TimePickerParts {
  * @property {(amount: 1 | -1) => void} onMinuteStep 1분 증감 핸들러
  * @property {() => void} onClear 삭제 핸들러
  * @property {() => void} onApply 적용 핸들러
+ * @desc TimePicker panel의 선택값, 표시 형식과 action 계약
  */
 export interface TimePickerTemplateProps {
   /**
@@ -96,6 +98,7 @@ export interface TimePickerTemplateProps {
 /**
  * TimePicker Summary props.
  * @property {string} summary 선택한 시간 표시값
+ * @desc panel 상단의 현재 선택값 표시 계약
  */
 export interface TimePickerSummaryProps {
   /**
@@ -112,6 +115,7 @@ export interface TimePickerSummaryProps {
  * @property {boolean} disabled 비활성화 여부
  * @property {(hours: number) => void} onHourSelect 시 선택 핸들러
  * @property {(period: "am" | "pm") => void} onPeriodChange 오전·오후 변경 핸들러
+ * @desc 표시 형식별 시 목록과 오전·오후 선택 계약
  */
 export interface TimePickerHourSectionProps {
   /**
@@ -146,6 +150,7 @@ export interface TimePickerHourSectionProps {
  * @property {boolean} disabled 비활성화 여부
  * @property {(amount: 1 | -1) => void} onMinuteStep 1분 증감 핸들러
  * @property {(minutes: number) => void} onMinuteSelect 분 선택 핸들러
+ * @desc 분 quick select와 1분 step action 계약
  */
 export interface TimePickerMinuteSectionProps {
   /**
@@ -172,6 +177,7 @@ export interface TimePickerMinuteSectionProps {
  * @property {boolean} disabled 비활성화 여부
  * @property {() => void} onClear 삭제 핸들러
  * @property {() => void} onApply 적용 핸들러
+ * @desc 삭제 노출 여부와 panel footer action 계약
  */
 export interface TimePickerFooterProps {
   /**

package/src/components/time-picker/utils/time.ts

@@ -12,8 +12,10 @@ const wrapTimePart = (value: number, limit: number) =>
 
 /**
  * TimePicker Utility; 24시간 문자열을 시간 값으로 파싱한다.
+ * @utility
  * @param {string} value HH:mm 또는 HH:mm:ss 값
- * @returns {TimePickerParts | null} 파싱 결과
+ * @desc 형식 또는 시·분·초 범위가 유효하지 않으면 null을 반환한다.
+ * @return {TimePickerParts | null} 파싱 결과
  */
 export const parseTimeValue = (value: string): TimePickerParts | null => {
   const match = /^(\d{2}):(\d{2})(?::(\d{2}))?$/.exec(value);
@@ -33,9 +35,11 @@ export const parseTimeValue = (value: string): TimePickerParts | null => {
 
 /**
  * TimePicker Utility; 시간 값을 24시간 문자열로 직렬화한다.
+ * @utility
  * @param {TimePickerParts} parts 시간 값
  * @param {boolean} withSeconds 초 포함 여부
- * @returns {string} HH:mm 또는 HH:mm:ss 값
+ * @desc 각 단위를 두 자리로 맞추고 withSeconds에 따라 초를 포함한다.
+ * @return {string} HH:mm 또는 HH:mm:ss 값
  */
 export const serializeTimeValue = (
   parts: TimePickerParts,
@@ -47,11 +51,13 @@ export const serializeTimeValue = (
 
 /**
  * TimePicker Utility; 지정 단위만 순환 증감한다.
+ * @utility
  * @param {string} value 시간 값
- * @param {TimePickerUnit} unit 증감 단위
+ * @param {"hours" | "minutes" | "seconds"} unit 증감 단위
  * @param {number} amount 증감량
  * @param {boolean} withSeconds 초 포함 여부
- * @returns {string} 증감한 시간 값
+ * @desc 빈 값은 00:00 기준으로 시작하고 시는 24, 분·초는 60을 경계로 순환한다.
+ * @return {string} 증감한 시간 값
  */
 export const stepTimeValue = (
   value: string,
@@ -73,27 +79,33 @@ export const stepTimeValue = (
 
 /**
  * TimePicker Utility; 저장 시를 표시 시로 변환한다.
+ * @utility
  * @param {number} hours 24시간 시 값
- * @param {TimePickerFormat} format 표시 형식
- * @returns {number} 표시 시 값
+ * @param {"12h" | "24h"} format 표시 형식
+ * @desc 12시간제에서는 0시와 12시를 12로 표시한다.
+ * @return {number} 표시 시 값
  */
 export const toDisplayHour = (hours: number, format: TimePickerFormat) =>
   format === "12h" ? hours % 12 || 12 : hours;
 
 /**
  * TimePicker Utility; 24시간 시 값의 오전·오후를 반환한다.
+ * @utility
  * @param {number} hours 24시간 시 값
- * @returns {TimePickerPeriod} 오전·오후
+ * @desc 12시 이상을 pm, 그 미만을 am으로 분류한다.
+ * @return {"am" | "pm"} 오전·오후
  */
 export const getTimePeriod = (hours: number): TimePickerPeriod =>
   hours >= 12 ? "pm" : "am";
 
 /**
  * TimePicker Utility; 오전·오후를 24시간 저장값에 반영한다.
+ * @utility
  * @param {string} value 시간 값
- * @param {TimePickerPeriod} period 오전·오후
+ * @param {"am" | "pm"} period 오전·오후
  * @param {boolean} withSeconds 초 포함 여부
- * @returns {string} 변경한 시간 값
+ * @desc 기존 분·초를 보존하고 선택한 period에 맞춰 저장 시만 변환한다.
+ * @return {string} 변경한 시간 값
  */
 export const setTimePeriod = (
   value: string,