@uniai-fe/uds-primitives 0.12.7 → 0.12.8

package/src/components/input/markup/time/Template.tsx

@@ -46,6 +46,14 @@ const defaultClockIcon = (
   </svg>
 );
 
+/**
+ * Input Time Utility; 24시간 저장 문자열을 trigger draft로 변환한다.
+ * @utility
+ * @param {string} value `HH:mm` 또는 `HH:mm:ss` 저장값
+ * @param {"12h" | "24h"} format 표시 형식
+ * @desc 유효하지 않거나 빈 저장값은 빈 field와 `am` period로 초기화한다.
+ * @return {InputTimeDraft} 표시용 field 문자열과 period
+ */
 const getInputTimeDraft = (
   value: string,
   format: "12h" | "24h",
@@ -73,11 +81,43 @@ const getInputTimeDraft = (
  * 저장값은 24시간 `HH:mm` 또는 `HH:mm:ss` 문자열로 유지한다.
  * @component
  * @param {InputTimeTemplateProps} props
- * @param {"primary" | "secondary" | "tertiary" | "table"} [props.priority="primary"] input priority
- * @param {"small" | "medium" | "large"} [props.size="medium"] input size
- * @param {"12h" | "24h"} [props.format="24h"] 표시 형식
- * @param {boolean} [props.withSeconds=false] 초 field 노출 여부
- * @returns {ReactNode} 시간 입력과 선택 panel
+ * @property {string} [props.value] 제어형 24시간 저장값
+ * @property {string} [props.defaultValue] 비제어 초기 24시간 저장값
+ * @property {(value: string) => void} [props.onChange] 값 변경 핸들러
+ * @property {(value: string) => void} [props.onValueChange] 값 변경 별칭
+ * @property {string} [props.name] hidden input form name
+ * @property {string} [props.form] hidden input form id
+ * @property {UseFormRegisterReturn} [props.register] hidden input react-hook-form register 결과
+ * @property {"primary" | "secondary" | "tertiary" | "table"} [props.priority="primary"] input priority
+ * @property {"small" | "medium" | "large"} [props.size="medium"] input size
+ * @property {"default" | "active" | "focused" | "success" | "error" | "disabled" | "loading"} [props.state="default"] input state
+ * @property {boolean} [props.block=false] width 100% 여부
+ * @property {"full" | "fit" | "fill" | "auto" | number | string} [props.width] width preset 또는 custom width
+ * @property {string} [props.className] root className
+ * @property {boolean} [props.disabled] disabled 여부
+ * @property {boolean} [props.readOnly=false] readOnly 여부
+ * @property {boolean} [props.required] hidden input required 여부
+ * @property {string} [props.id] trigger root id
+ * @property {"12h" | "24h"} [props.format="24h"] 표시 형식
+ * @property {boolean} [props.withSeconds=false] 초 field 노출 여부
+ * @property {boolean} [props.clearable=true] 삭제 action 노출 여부
+ * @property {number} [props.hoursStep=1] 시 증감 단위
+ * @property {number} [props.minutesStep=5] 분 증감 단위
+ * @property {number} [props.secondsStep=1] 초 증감 단위
+ * @property {ReactNode} [props.icon] clock icon override
+ * @property {"left" | "right"} [props.iconPosition] clock icon 위치
+ * @property {string} [props.iconLabel="시간 선택"] clock icon 접근성 라벨
+ * @property {InputTimeHiddenInputProps} [props.hiddenInputProps] hidden input native props
+ * @property {string} [props.hoursInputLabel="시"] 시 input 접근성 라벨
+ * @property {string} [props.minutesInputLabel="분"] 분 input 접근성 라벨
+ * @property {string} [props.secondsInputLabel="초"] 초 input 접근성 라벨
+ * @property {string} [props.amPmInputLabel="오전 또는 오후"] 오전·오후 input 접근성 라벨
+ * @property {string} [props.hoursPlaceholder="HH"] 시 placeholder
+ * @property {string} [props.minutesPlaceholder="MM"] 분 placeholder
+ * @property {string} [props.secondsPlaceholder="SS"] 초 placeholder
+ * @property {(event: FocusEvent<HTMLInputElement>) => void} [props.onFocus] field focus 핸들러
+ * @property {(event: FocusEvent<HTMLDivElement>) => void} [props.onBlur] trigger root blur 핸들러
+ * @desc 표시 draft를 편집·정규화하고 TimePicker 선택값과 hidden input 저장값을 동기화한다.
  */
 const InputTimeTemplate = forwardRef<HTMLDivElement, InputTimeTemplateProps>(
   (
@@ -136,6 +176,7 @@ const InputTimeTemplate = forwardRef<HTMLDivElement, InputTimeTemplateProps>(
       getInputTimeDraft(value ?? defaultValue ?? "", format),
     );
 
+    // 외부 value 또는 표시 형식 변경 시 저장값을 기준으로 편집 draft를 다시 계산한다.
     useEffect(() => {
       setDraft(getInputTimeDraft(timeValue, format));
     }, [format, timeValue]);
@@ -165,6 +206,13 @@ const InputTimeTemplate = forwardRef<HTMLDivElement, InputTimeTemplateProps>(
       ? { width: widthValue }
       : undefined;
 
+    /**
+     * Input Time Utility; RHF hidden input 변경 이벤트 동기화 함수.
+     * @utility
+     * @param {string} nextValue 다음 24시간 저장값
+     * @desc 표시 field와 분리된 hidden input register에 synthetic change를 전달한다.
+     * @return {void}
+     */
     const emitRegisterChange = useCallback(
       (nextValue: string) => {
         register?.onChange({
@@ -175,6 +223,13 @@ const InputTimeTemplate = forwardRef<HTMLDivElement, InputTimeTemplateProps>(
       [register],
     );
 
+    /**
+     * Input Time Utility; 시간 저장값 갱신 함수.
+     * @utility
+     * @param {string} nextValue 다음 24시간 저장값
+     * @desc draft, controlled/uncontrolled value와 RHF 저장값을 같은 값으로 동기화한다.
+     * @return {void}
+     */
     const updateValue = useCallback(
       (nextValue: string) => {
         setDraft(getInputTimeDraft(nextValue, format));
@@ -184,6 +239,13 @@ const InputTimeTemplate = forwardRef<HTMLDivElement, InputTimeTemplateProps>(
       [emitRegisterChange, format, setTimeValue],
     );
 
+    /**
+     * Input Time Utility; 완성된 trigger draft를 저장값으로 commit한다.
+     * @utility
+     * @param {InputTimeDraft} nextDraft 다음 field 문자열과 period
+     * @desc 필요한 field가 두 자리이고 범위가 유효할 때만 24시간 문자열로 직렬화한다.
+     * @return {void}
+     */
     const commitDraft = useCallback(
       (nextDraft: InputTimeDraft) => {
         const { hours, minutes, seconds } = nextDraft.fields;
@@ -224,6 +286,14 @@ const InputTimeTemplate = forwardRef<HTMLDivElement, InputTimeTemplateProps>(
       [format, updateValue, withSeconds],
     );
 
+    /**
+     * Input Time Utility; field 입력 정규화 함수.
+     * @utility
+     * @param {"hours" | "minutes" | "seconds"} unit 변경 단위
+     * @param {string} rawValue 입력 문자열
+     * @desc 숫자 두 자리만 draft에 남기고 완성된 값은 즉시 commit한다.
+     * @return {void}
+     */
     const handleFieldChange = (unit: TimePickerUnit, rawValue: string) => {
       const nextValue = rawValue.replace(/\D/g, "").slice(0, 2);
       const nextDraft = {
@@ -243,6 +313,13 @@ const InputTimeTemplate = forwardRef<HTMLDivElement, InputTimeTemplateProps>(
       onFocus?.(event);
     };
 
+    /**
+     * Input Time Utility; field blur 정규화 함수.
+     * @utility
+     * @param {"hours" | "minutes" | "seconds"} unit blur 단위
+     * @desc 빈 field는 유지하고 입력값은 단위·표시 형식 범위로 clamp한 뒤 commit한다.
+     * @return {void}
+     */
     const handleFieldBlur = (unit: TimePickerUnit) => {
       const currentValue = draft.fields[unit];
       if (!currentValue) {
@@ -262,6 +339,14 @@ const InputTimeTemplate = forwardRef<HTMLDivElement, InputTimeTemplateProps>(
       commitDraft(nextDraft);
     };
 
+    /**
+     * Input Time Utility; field 방향키 증감 함수.
+     * @utility
+     * @param {"hours" | "minutes" | "seconds"} unit 활성 단위
+     * @param {KeyboardEvent<HTMLInputElement>} event field keyboard event
+     * @desc 위·아래 방향키만 단위별 step으로 순환 증감한다.
+     * @return {void}
+     */
     const handleFieldKeyDown = (
       unit: TimePickerUnit,
       event: KeyboardEvent<HTMLInputElement>,
@@ -280,6 +365,13 @@ const InputTimeTemplate = forwardRef<HTMLDivElement, InputTimeTemplateProps>(
       updateValue(stepTimeValue(timeValue, unit, amount * step, withSeconds));
     };
 
+    /**
+     * Input Time Utility; trigger stepper 증감 함수.
+     * @utility
+     * @param {1 | -1} amount 증감 방향
+     * @desc focus된 단위가 있을 때만 해당 단위 step으로 저장값을 순환 증감한다.
+     * @return {void}
+     */
     const handleStep = (amount: 1 | -1) => {
       if (!activeUnit) {
         return;
@@ -300,6 +392,13 @@ const InputTimeTemplate = forwardRef<HTMLDivElement, InputTimeTemplateProps>(
       updateValue(nextValue);
     };
 
+    /**
+     * Input Time Utility; TimePicker 시 선택 반영 함수.
+     * @utility
+     * @param {number} hours 선택한 표시 시
+     * @desc 12시간제는 현재 draft period를 결합해 24시간 저장 시로 변환한다.
+     * @return {void}
+     */
     const handleHourSelect = (hours: number) => {
       const parts = parseTimeValue(timeValue) ?? {
         hours: 0,
@@ -324,6 +423,13 @@ const InputTimeTemplate = forwardRef<HTMLDivElement, InputTimeTemplateProps>(
       updateValue(serializeTimeValue({ ...parts, minutes }, withSeconds));
     };
 
+    /**
+     * Input Time Utility; trigger root blur와 RHF touched 상태 동기화 함수.
+     * @utility
+     * @param {FocusEvent<HTMLDivElement>} event trigger root blur event
+     * @desc root 내부 focus 이동은 무시하고 외부로 벗어날 때만 register와 소비자 callback을 호출한다.
+     * @return {void}
+     */
     const handleRootBlur = (event: FocusEvent<HTMLDivElement>) => {
       if (
         event.relatedTarget instanceof Node &&
@@ -339,6 +445,13 @@ const InputTimeTemplate = forwardRef<HTMLDivElement, InputTimeTemplateProps>(
       onBlur?.(event);
     };
 
+    /**
+     * Input Time Utility; TimePicker panel open 상태 갱신 함수.
+     * @utility
+     * @param {boolean} nextOpen 다음 open 상태
+     * @desc disabled 또는 readOnly 상태에서는 panel을 열지 않는다.
+     * @return {void}
+     */
     const handleOpenChange = (nextOpen: boolean) => {
       setIsOpen(nextOpen && !isDisabled && !readOnly);
     };

package/src/components/input/markup/time/Trigger.tsx

@@ -12,7 +12,34 @@ import type { InputTimeTriggerProps } from "../../types";
  * Input Time trigger; 시·분·초 field와 focus 단위 stepper를 렌더한다.
  * @component
  * @param {InputTimeTriggerProps} props
- * @returns {ReactNode} 시간 입력 trigger
+ * @property {InputTimeTriggerFields} props.fields 시·분·초 입력값
+ * @property {"am" | "pm"} props.period 오전·오후 구분
+ * @property {"hours" | "minutes" | "seconds" | null} props.activeUnit 현재 활성 단위
+ * @property {"primary" | "secondary" | "tertiary" | "table"} props.priority input priority
+ * @property {"small" | "medium" | "large"} props.size input size
+ * @property {"default" | "active" | "focused" | "success" | "error" | "disabled" | "loading"} props.state input state
+ * @property {"12h" | "24h"} props.format 표시 형식
+ * @property {boolean} props.withSeconds 초 field 노출 여부
+ * @property {boolean} props.disabled 비활성화 여부
+ * @property {boolean} props.readOnly 읽기 전용 여부
+ * @property {ReactNode} props.icon clock icon
+ * @property {"left" | "right"} props.iconPosition clock icon 위치
+ * @property {string} props.iconLabel clock icon 접근성 라벨
+ * @property {string} props.hoursInputLabel 시 input 접근성 라벨
+ * @property {string} props.minutesInputLabel 분 input 접근성 라벨
+ * @property {string} props.secondsInputLabel 초 input 접근성 라벨
+ * @property {string} props.amPmInputLabel 오전·오후 input 접근성 라벨
+ * @property {string} props.hoursPlaceholder 시 placeholder
+ * @property {string} props.minutesPlaceholder 분 placeholder
+ * @property {string} props.secondsPlaceholder 초 placeholder
+ * @property {(unit: "hours" | "minutes" | "seconds", value: string) => void} props.onFieldChange field 변경 핸들러
+ * @property {(unit: "hours" | "minutes" | "seconds", event: FocusEvent<HTMLInputElement>) => void} props.onFieldFocus field focus 핸들러
+ * @property {(unit: "hours" | "minutes" | "seconds") => void} props.onFieldBlur field blur 핸들러
+ * @property {(unit: "hours" | "minutes" | "seconds", event: KeyboardEvent<HTMLInputElement>) => void} props.onFieldKeyDown field keyboard 핸들러
+ * @property {(period: "am" | "pm") => void} props.onPeriodChange 오전·오후 변경 핸들러
+ * @property {(amount: 1 | -1) => void} props.onStep 활성 단위 증감 핸들러
+ * @property {(event: FocusEvent<HTMLDivElement>) => void} props.onRootBlur root blur 핸들러
+ * @desc field별 입력과 focus를 Template의 draft·commit pipeline으로 전달한다.
  */
 const InputTimeTrigger = forwardRef<HTMLDivElement, InputTimeTriggerProps>(
   (
@@ -73,7 +100,13 @@ const InputTimeTrigger = forwardRef<HTMLDivElement, InputTimeTriggerProps>(
     const onClockClick = () => {
       hoursRef.current?.focus();
     };
-    // PopOver.Trigger가 주입한 click은 clock button에서만 popup toggle로 위임한다.
+    /**
+     * Input Time Utility; PopOver trigger click 위임 함수.
+     * @utility
+     * @param {MouseEvent<HTMLDivElement>} event trigger root click event
+     * @desc field 편집 click은 panel을 toggle하지 않고 clock button click만 PopOver에 전달한다.
+     * @return {void}
+     */
     const onRootClick = (event: MouseEvent<HTMLDivElement>) => {
       if (
         event.target instanceof Element &&

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 {
   /**