@uniai-fe/uds-primitives 0.12.7 → 0.12.8

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,