@uniai-fe/uds-primitives 0.12.6 → 0.12.7

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

@@ -21,8 +21,6 @@ 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">,
@@ -34,7 +32,6 @@ export type InputTimeHiddenInputProps = Omit<
  * @property {string} hours 시 입력값
  * @property {string} minutes 분 입력값
  * @property {string} seconds 초 입력값
- * @desc 입력 field에 표시하는 시·분·초 draft 문자열
  */
 export interface InputTimeDraftFields {
   /**
@@ -55,7 +52,6 @@ export interface InputTimeDraftFields {
  * Input Time 편집 중인 시간 값.
  * @property {InputTimeDraftFields} fields 시·분·초 입력값
  * @property {"am" | "pm"} period 오전·오후 구분
- * @desc 저장값 commit 전의 field 문자열과 12시간제 period 상태
  */
 export interface InputTimeDraft {
   /**
@@ -103,7 +99,6 @@ 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">,
@@ -230,8 +225,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 결과
@@ -262,9 +257,8 @@ 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 핸들러
- * @desc 시간 trigger, TimePicker panel과 24시간 문자열 hidden form storage를 조합하는 공개 계약
+ * @property {(event:FocusEvent<HTMLInputElement>)=>void} [onFocus] focus 핸들러
+ * @property {(event:FocusEvent<HTMLDivElement>)=>void} [onBlur] blur 핸들러
  */
 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
- * @property {boolean} props.clearable 삭제 action 노출 여부
- * @property {boolean} props.disabled 비활성화 여부
- * @property {() => void} props.onClear 삭제 핸들러
- * @property {() => void} props.onApply 적용 핸들러
- * @desc clearable 상태에 따라 삭제 action을 노출하고 적용 action을 유지한다.
+ * @param {boolean} props.clearable 삭제 action 노출 여부
+ * @param {boolean} props.disabled 비활성화 여부
+ * @param {() => void} props.onClear 삭제 핸들러
+ * @param {() => void} props.onApply 적용 핸들러
+ * @returns {ReactNode} TimePicker footer
  * @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
- * @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을 렌더한다.
+ * @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
  * @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
- * @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분 단위 미세 조정을 함께 제공한다.
+ * @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
  * @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
- * @property {string} props.summary 선택한 시간 표시값
- * @desc TimePicker panel 상단에 현재 선택값 또는 빈 상태를 표시한다.
+ * @param {string} props.summary 선택한 시간 표시값
+ * @returns {ReactNode} 선택 시간 요약
  * @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
- * @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에 배분한다.
+ * @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
  * @example
  * <TimePicker.Template
  *   value="09:30"

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

@@ -21,7 +21,6 @@ export type TimePickerUnit = "hours" | "minutes" | "seconds";
  * @property {number} hours 시
  * @property {number} minutes 분
  * @property {number} seconds 초
- * @desc 24시간 저장값의 정규화된 시·분·초 숫자 구성
  */
 export interface TimePickerParts {
   /**
@@ -50,7 +49,6 @@ export interface TimePickerParts {
  * @property {(amount: 1 | -1) => void} onMinuteStep 1분 증감 핸들러
  * @property {() => void} onClear 삭제 핸들러
  * @property {() => void} onApply 적용 핸들러
- * @desc TimePicker panel의 선택값, 표시 형식과 action 계약
  */
 export interface TimePickerTemplateProps {
   /**
@@ -98,7 +96,6 @@ export interface TimePickerTemplateProps {
 /**
  * TimePicker Summary props.
  * @property {string} summary 선택한 시간 표시값
- * @desc panel 상단의 현재 선택값 표시 계약
  */
 export interface TimePickerSummaryProps {
   /**
@@ -115,7 +112,6 @@ export interface TimePickerSummaryProps {
  * @property {boolean} disabled 비활성화 여부
  * @property {(hours: number) => void} onHourSelect 시 선택 핸들러
  * @property {(period: "am" | "pm") => void} onPeriodChange 오전·오후 변경 핸들러
- * @desc 표시 형식별 시 목록과 오전·오후 선택 계약
  */
 export interface TimePickerHourSectionProps {
   /**
@@ -150,7 +146,6 @@ 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 {
   /**
@@ -177,7 +172,6 @@ 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,10 +12,8 @@ const wrapTimePart = (value: number, limit: number) =>
 
 /**
  * TimePicker Utility; 24시간 문자열을 시간 값으로 파싱한다.
- * @utility
  * @param {string} value HH:mm 또는 HH:mm:ss 값
- * @desc 형식 또는 시·분·초 범위가 유효하지 않으면 null을 반환한다.
- * @return {TimePickerParts | null} 파싱 결과
+ * @returns {TimePickerParts | null} 파싱 결과
  */
 export const parseTimeValue = (value: string): TimePickerParts | null => {
   const match = /^(\d{2}):(\d{2})(?::(\d{2}))?$/.exec(value);
@@ -35,11 +33,9 @@ export const parseTimeValue = (value: string): TimePickerParts | null => {
 
 /**
  * TimePicker Utility; 시간 값을 24시간 문자열로 직렬화한다.
- * @utility
  * @param {TimePickerParts} parts 시간 값
  * @param {boolean} withSeconds 초 포함 여부
- * @desc 각 단위를 두 자리로 맞추고 withSeconds에 따라 초를 포함한다.
- * @return {string} HH:mm 또는 HH:mm:ss 값
+ * @returns {string} HH:mm 또는 HH:mm:ss 값
  */
 export const serializeTimeValue = (
   parts: TimePickerParts,
@@ -51,13 +47,11 @@ export const serializeTimeValue = (
 
 /**
  * TimePicker Utility; 지정 단위만 순환 증감한다.
- * @utility
  * @param {string} value 시간 값
- * @param {"hours" | "minutes" | "seconds"} unit 증감 단위
+ * @param {TimePickerUnit} unit 증감 단위
  * @param {number} amount 증감량
  * @param {boolean} withSeconds 초 포함 여부
- * @desc 빈 값은 00:00 기준으로 시작하고 시는 24, 분·초는 60을 경계로 순환한다.
- * @return {string} 증감한 시간 값
+ * @returns {string} 증감한 시간 값
  */
 export const stepTimeValue = (
   value: string,
@@ -79,33 +73,27 @@ export const stepTimeValue = (
 
 /**
  * TimePicker Utility; 저장 시를 표시 시로 변환한다.
- * @utility
  * @param {number} hours 24시간 시 값
- * @param {"12h" | "24h"} format 표시 형식
- * @desc 12시간제에서는 0시와 12시를 12로 표시한다.
- * @return {number} 표시 시 값
+ * @param {TimePickerFormat} format 표시 형식
+ * @returns {number} 표시 시 값
  */
 export const toDisplayHour = (hours: number, format: TimePickerFormat) =>
   format === "12h" ? hours % 12 || 12 : hours;
 
 /**
  * TimePicker Utility; 24시간 시 값의 오전·오후를 반환한다.
- * @utility
  * @param {number} hours 24시간 시 값
- * @desc 12시 이상을 pm, 그 미만을 am으로 분류한다.
- * @return {"am" | "pm"} 오전·오후
+ * @returns {TimePickerPeriod} 오전·오후
  */
 export const getTimePeriod = (hours: number): TimePickerPeriod =>
   hours >= 12 ? "pm" : "am";
 
 /**
  * TimePicker Utility; 오전·오후를 24시간 저장값에 반영한다.
- * @utility
  * @param {string} value 시간 값
- * @param {"am" | "pm"} period 오전·오후
+ * @param {TimePickerPeriod} period 오전·오후
  * @param {boolean} withSeconds 초 포함 여부
- * @desc 기존 분·초를 보존하고 선택한 period에 맞춰 저장 시만 변환한다.
- * @return {string} 변경한 시간 값
+ * @returns {string} 변경한 시간 값
  */
 export const setTimePeriod = (
   value: string,