@uniai-fe/uds-primitives 0.0.7 → 0.0.8

package/src/components/dialog/markup/index.tsx

@@ -1,4 +1,4 @@
 "use client";
 
-export * from "./notice-dialog";
-export * from "./confirm-dialog";
+export * from "./NoticeDialog";
+export * from "./ConfirmDialog";

package/src/components/dialog/types/index.ts

@@ -2,52 +2,95 @@ import type { ComponentPropsWithoutRef } from "react";
 import type * as AlertDialogPrimitive from "@radix-ui/react-alert-dialog";
 import type * as DialogPrimitive from "@radix-ui/react-dialog";
 
+/**
+ * NoticeDialog Root props. Radix Dialog Root 계약을 그대로 사용한다.
+ */
 type NoticeDialogRootProps = ComponentPropsWithoutRef<
   typeof DialogPrimitive.Root
 >;
+/**
+ * NoticeDialog Overlay props. className/data attr만 확장한다.
+ */
 type NoticeDialogOverlayProps = ComponentPropsWithoutRef<
   typeof DialogPrimitive.Overlay
 >;
+/**
+ * NoticeDialog Content props.
+ */
 type NoticeDialogContentProps = ComponentPropsWithoutRef<
   typeof DialogPrimitive.Content
 >;
+/**
+ * NoticeDialog section(div) props.
+ */
 type NoticeDialogSectionProps = ComponentPropsWithoutRef<"div">;
+/**
+ * NoticeDialog Title props. visuallyHidden 옵션으로 시각적 숨김 지원.
+ */
 type NoticeDialogTitleProps = ComponentPropsWithoutRef<
   typeof DialogPrimitive.Title
 > & {
   visuallyHidden?: boolean;
 };
+/**
+ * NoticeDialog Description props. visuallyHidden 옵션 포함.
+ */
 type NoticeDialogDescriptionProps = ComponentPropsWithoutRef<
   typeof DialogPrimitive.Description
 > & {
   visuallyHidden?: boolean;
 };
 
+/**
+ * ConfirmDialog Root props. Radix AlertDialog Root 계약.
+ */
 type ConfirmDialogRootProps = ComponentPropsWithoutRef<
   typeof AlertDialogPrimitive.Root
 >;
+/**
+ * ConfirmDialog Overlay props. disableOutsideClose 확장 포함.
+ * @property {boolean} [disableOutsideClose=false] dim 클릭 시 닫힘 방지 여부.
+ */
 type ConfirmDialogOverlayProps = ComponentPropsWithoutRef<
   typeof AlertDialogPrimitive.Overlay
 > & {
   disableOutsideClose?: boolean;
 };
+/**
+ * ConfirmDialog Content props.
+ */
 type ConfirmDialogContentProps = ComponentPropsWithoutRef<
   typeof AlertDialogPrimitive.Content
 >;
+/**
+ * ConfirmDialog section props.
+ */
 type ConfirmDialogSectionProps = ComponentPropsWithoutRef<"div">;
+/**
+ * ConfirmDialog Title props. visuallyHidden 옵션 포함.
+ */
 type ConfirmDialogTitleProps = ComponentPropsWithoutRef<
   typeof AlertDialogPrimitive.Title
 > & {
   visuallyHidden?: boolean;
 };
+/**
+ * ConfirmDialog Description props. visuallyHidden 옵션 포함.
+ */
 type ConfirmDialogDescriptionProps = ComponentPropsWithoutRef<
   typeof AlertDialogPrimitive.Description
 > & {
   visuallyHidden?: boolean;
 };
+/**
+ * ConfirmDialog Action button props.
+ */
 type ConfirmDialogActionProps = ComponentPropsWithoutRef<
   typeof AlertDialogPrimitive.Action
 >;
+/**
+ * ConfirmDialog Cancel button props.
+ */
 type ConfirmDialogCancelProps = ComponentPropsWithoutRef<
   typeof AlertDialogPrimitive.Cancel
 >;

package/src/components/drawer/markup/{drawer.tsx → Drawer.tsx}

@@ -35,6 +35,15 @@ import {
 
 const ANIMATION_DURATION = 320;
 
+/**
+ * DrawerRoot — open 상태/phase를 관리하는 컨텍스트 루트.
+ * @component
+ * @param {DrawerRootProps} props
+ * @param {boolean} [props.open] 제어형 open 상태.
+ * @param {boolean} [props.defaultOpen] 비제어 초기 open 상태.
+ * @param {(open: boolean) => void} [props.onOpenChange] open 변경 콜백.
+ * @param {React.ReactNode} props.children Drawer 하위 컴포넌트.
+ */
 const DrawerRoot = ({
   children,
   open: openProp,
@@ -122,6 +131,13 @@ const DrawerRoot = ({
   );
 };
 
+/**
+ * DrawerTrigger — Drawer를 여는 button/asChild.
+ * @component
+ * @param {DrawerTriggerProps} props
+ * @param {boolean} [props.asChild=false] button 대신 children을 직접 렌더할지 여부.
+ * @param {React.ReactNode} [props.children] trigger 콘텐츠.
+ */
 const DrawerTrigger = forwardRef<HTMLButtonElement, DrawerTriggerProps>(
   ({ asChild, children, onClick, ...props }, forwardedRef) => {
     const { setOpen } = useDrawerContext();
@@ -137,6 +153,11 @@ const DrawerTrigger = forwardRef<HTMLButtonElement, DrawerTriggerProps>(
 
 DrawerTrigger.displayName = "DrawerTrigger";
 
+/**
+ * DrawerPortal — Drawer overlay/content를 body로 포탈한다.
+ * @component
+ * @param {DrawerPortalProps} props
+ */
 const DrawerPortal = ({ children }: DrawerPortalProps) => {
   useDrawerContext();
   const [mounted, setMounted] = useState(false);
@@ -157,6 +178,8 @@ const DrawerPortal = ({ children }: DrawerPortalProps) => {
  * DrawerOverlay; 전체 dim
  * @component
  * @param {DrawerOverlayProps} props
+ * @param {string} [props.className] overlay className.
+ * @param {boolean} [props.onClick] dim 클릭 시 setOpen(false)와 함께 호출되는 핸들러.
  */
 const DrawerOverlay = forwardRef<HTMLDivElement, DrawerOverlayProps>(
   ({ className, onClick, ...props }, forwardedRef) => {
@@ -180,6 +203,9 @@ DrawerOverlay.displayName = "DrawerOverlay";
  * DrawerTitle; Drawer 제목
  * @component
  * @param {DrawerTitleProps} props
+ * @param {boolean} [props.visuallyHidden=false] 제목을 시각적으로 숨길지 여부.
+ * @param {string} [props.className] title className.
+ * @param {React.ReactNode} [props.children] 제목 콘텐츠.
  */
 const DrawerTitle = forwardRef<HTMLHeadingElement, DrawerTitleProps>(
   ({ visuallyHidden = false, className, children, ...props }, forwardedRef) => {
@@ -207,6 +233,9 @@ DrawerTitle.displayName = "DrawerTitle";
  * DrawerDescription; Drawer 본문 안내
  * @component
  * @param {DrawerDescriptionProps} props
+ * @param {boolean} [props.visuallyHidden=false] 설명을 시각적으로 숨길지 여부.
+ * @param {string} [props.className] description className.
+ * @param {React.ReactNode} [props.children] 설명 콘텐츠.
  */
 const DrawerDescription = forwardRef<
   HTMLParagraphElement,
@@ -235,6 +264,9 @@ DrawerDescription.displayName = "DrawerDescription";
  * DrawerSection; header/body/footer 레이아웃
  * @component
  * @param {DrawerSectionProps} props
+ * @param {"header" | "body" | "footer"} [props.section="body"] 섹션 variant.
+ * @param {string} [props.className] 섹션 className.
+ * @param {React.ReactNode} [props.children] 섹션 콘텐츠.
  */
 const DrawerSection = forwardRef<HTMLDivElement, DrawerSectionProps>(
   ({ className, section = "body", ...props }, forwardedRef) => (
@@ -249,6 +281,11 @@ const DrawerSection = forwardRef<HTMLDivElement, DrawerSectionProps>(
 
 DrawerSection.displayName = "DrawerSection";
 
+/**
+ * DrawerHeader; header 섹션 helper.
+ * @component
+ * @param {DrawerSectionProps} props
+ */
 const DrawerHeader = forwardRef<HTMLDivElement, DrawerSectionProps>(
   ({ className, ...props }, forwardedRef) => (
     <DrawerSection
@@ -262,6 +299,11 @@ const DrawerHeader = forwardRef<HTMLDivElement, DrawerSectionProps>(
 
 DrawerHeader.displayName = "DrawerHeader";
 
+/**
+ * DrawerBody; body 섹션 helper.
+ * @component
+ * @param {DrawerSectionProps} props
+ */
 const DrawerBody = forwardRef<HTMLDivElement, DrawerSectionProps>(
   ({ className, ...props }, forwardedRef) => (
     <DrawerSection
@@ -275,6 +317,11 @@ const DrawerBody = forwardRef<HTMLDivElement, DrawerSectionProps>(
 
 DrawerBody.displayName = "DrawerBody";
 
+/**
+ * DrawerFooter; footer 섹션 helper.
+ * @component
+ * @param {DrawerSectionProps} props
+ */
 const DrawerFooter = forwardRef<HTMLDivElement, DrawerSectionProps>(
   ({ className, ...props }, forwardedRef) => (
     <DrawerSection
@@ -292,6 +339,10 @@ DrawerFooter.displayName = "DrawerFooter";
  * DrawerContent; handle/closeButton 제어
  * @component
  * @param {DrawerContentProps} props
+ * @param {boolean} [props.closeButton=false] 헤더에 닫기 버튼 표시 여부.
+ * @param {string} [props.closeButtonLabel="닫기"] 닫기 버튼 aria-label.
+ * @param {string} [props.className] content className.
+ * @param {React.CSSProperties} [props.style] inline style.
  */
 const DrawerContent = forwardRef<HTMLDivElement, DrawerContentProps>(
   (
@@ -391,6 +442,13 @@ const DrawerContent = forwardRef<HTMLDivElement, DrawerContentProps>(
 
 DrawerContent.displayName = "DrawerContent";
 
+/**
+ * DrawerClose — Drawer를 닫는 button/asChild helper.
+ * @component
+ * @param {DrawerCloseProps} props
+ * @param {boolean} [props.asChild=false] 버튼 대신 children을 직접 렌더할지 여부.
+ * @param {React.ReactNode} [props.children] close trigger.
+ */
 const DrawerClose = forwardRef<HTMLButtonElement, DrawerCloseProps>(
   ({ asChild, children, onClick, ...props }, forwardedRef) => {
     const { setOpen } = useDrawerContext();

package/src/components/drawer/markup/index.tsx

@@ -1,3 +1,3 @@
 "use client";
 
-export * from "./drawer";
+export * from "./Drawer";

package/src/components/drawer/types/index.ts

@@ -8,6 +8,13 @@ export interface DrawerContextValue {
   phase: DrawerPhase;
 }
 
+/**
+ * DrawerRoot props. open 제어 및 상태 콜백을 정의한다.
+ * @property {React.ReactNode} children Drawer 하위 구성 요소.
+ * @property {boolean} [open] 제어형 open 상태.
+ * @property {boolean} [defaultOpen] 비제어 초기 상태.
+ * @property {(open: boolean) => void} [onOpenChange] open 변경 콜백.
+ */
 export interface DrawerRootProps {
   children: ReactNode;
   open?: boolean;
@@ -15,11 +22,19 @@ export interface DrawerRootProps {
   onOpenChange?: (open: boolean) => void;
 }
 
+/**
+ * DrawerTrigger props.
+ * @property {boolean} [asChild=false] children을 직접 버튼으로 사용할지 여부.
+ */
 export interface DrawerTriggerProps extends ComponentPropsWithoutRef<"button"> {
   asChild?: boolean;
   children?: ReactNode;
 }
 
+/**
+ * DrawerClose props.
+ * @property {boolean} [asChild=false] children을 직접 버튼으로 사용할지 여부.
+ */
 export interface DrawerCloseProps extends ComponentPropsWithoutRef<"button"> {
   asChild?: boolean;
   children?: ReactNode;
@@ -41,10 +56,19 @@ export type DrawerDescriptionProps = ComponentPropsWithoutRef<"p"> & {
 
 export type DrawerSectionVariant = "header" | "body" | "footer";
 
+/**
+ * DrawerSection props. section variant로 header/body/footer를 지정한다.
+ * @property {"header" | "body" | "footer"} [section="body"] 섹션 유형.
+ */
 export interface DrawerSectionProps extends ComponentPropsWithoutRef<"div"> {
   section?: DrawerSectionVariant;
 }
 
+/**
+ * DrawerContent props.
+ * @property {boolean} [closeButton=false] close 버튼을 표시할지 여부.
+ * @property {string} [closeButtonLabel="닫기"] close 버튼 aria-label.
+ */
 export interface DrawerContentProps extends ComponentPropsWithoutRef<"div"> {
   closeButton?: boolean;
   closeButtonLabel?: string;

package/src/components/input/markup/text/Base.tsx

@@ -22,8 +22,37 @@ import SuccessIcon from "../../img/success.svg";
 import ResetIcon from "../../img/reset.svg";
 
 /**
- * Native `<input>` 기반 텍스트 필드. appearance/size/state 축과 label/helper 슬롯을 모두 제공한다.
- * README와 Button 컴포넌트와 동일하게 props를 forwardRef 인자로 직접 구조분해한다.
+ * Native `<input>` 기반 텍스트 필드. appearance/size/state 축, prefix/suffix/reset/status 슬롯,
+ * label/helperText 같은 피드백 슬롯을 모두 제공한다.
+ * @component
+ * @param {InputProps} props
+ * @param {"primary" | "secondary" | "tertiary"} [props.appearance="primary"] 토큰 세트.
+ * @param {"small" | "medium" | "large"} [props.size="medium"] 높이/spacing 세트.
+ * @param {"default" | "active" | "focused" | "success" | "error" | "disabled"} [props.state="default"] 시각 상태.
+ * @param {boolean} [props.block=false] true면 width 100%.
+ * @param {React.ReactNode} [props.prefix] 입력 왼쪽 추가 슬롯.
+ * @param {React.ReactNode} [props.suffix] 입력 오른쪽 추가 슬롯.
+ * @param {React.ReactElement} [props.resetSlot] 값 초기화 버튼 슬롯. 미지정 시 기본 reset 아이콘.
+ * @param {React.ReactNode} [props.successIcon] success 상태에서 사용할 아이콘.
+ * @param {React.ReactNode} [props.errorIcon] error 상태에서 사용할 아이콘.
+ * @param {React.ReactNode} [props.label] 상단/inset label 콘텐츠.
+ * @param {React.ReactNode} [props.helperText] helper 영역 텍스트.
+ * @param {boolean} [props.hideHelperText] true면 helper 영역 숨김.
+ * @param {string} [props.inputClassName] 실제 `<input>` 요소 className.
+ * @param {string} [props.wrapperClassName] `.input-box` wrapper className.
+ * @param {object} [props.labelProps] label attr 커스터마이즈.
+ * @param {object} [props.helperTextProps] helper 영역 attr.
+ * @param {boolean} [props.disabled] native disabled.
+ * @param {string} [props.id] external id. label htmlFor 와 공유한다.
+ * @param {string} [props.className] root `.input` className 합성용.
+ * @param {"default" | "active" | "focused" | "success" | "error" | "disabled"} [props.data-simulated-state]
+ *  Storybook 등에서 강제 상태 표현.
+ * @param {string} [props.type="text"] native input type.
+ * @param {string | number | readonly string[]} [props.defaultValue] 비제어 초기값.
+ * @param {string | number | readonly string[]} [props.value] 제어형 값.
+ * @param {(event: ChangeEvent<HTMLInputElement>) => void} [props.onChange] 입력 변경 핸들러.
+ * @param {(event: FocusEvent<HTMLInputElement>) => void} [props.onFocus] focus 핸들러.
+ * @param {(event: FocusEvent<HTMLInputElement>) => void} [props.onBlur] blur 핸들러.
  */
 const Text = forwardRef<HTMLInputElement, InputProps>(
   (
@@ -159,7 +188,7 @@ const Text = forwardRef<HTMLInputElement, InputProps>(
       () => clsx("input-helper-text", helperTextProps?.className),
       [helperTextProps?.className],
     );
-    const shouldRenderInlineLabel = appearance === "teritary" && Boolean(label);
+    const shouldRenderInlineLabel = appearance === "tertiary" && Boolean(label);
     const labelClassName = useMemo(
       () =>
         clsx(

package/src/components/input/markup/text/Identification.tsx

@@ -11,6 +11,14 @@ import {
 } from "react";
 import type { InputProps } from "../../types";
 
+/**
+ * IdentificationInput props. 고정 길이 숫자 코드 입력에 필요한 label/helper/state/onComplete를 제공한다.
+ * @property {number} [length=6] 입력칸 개수(4~8 사이로 자동 보정).
+ * @property {InputProps["label"]} [label] 상단 라벨.
+ * @property {InputProps["helperText"]} [helperText] helper 텍스트.
+ * @property {InputProps["state"]} [state="default"] 시각 상태.
+ * @property {(code: string) => void} [onComplete] 모든 셀이 채워졌을 때 호출.
+ */
 export interface IdentificationInputProps {
   length?: number;
   label?: InputProps["label"];
@@ -21,8 +29,13 @@ export interface IdentificationInputProps {
 
 /**
  * IdentificationInput — 인증번호 입력 UI. 개별 입력칸을 제공하고 focus 이동/붙여넣기 등을 처리한다.
- * @param props.length 입력 필드 길이 (4~8 사이).
- * @param props.onComplete 모든 셀이 채워졌을 때 호출.
+ * @component
+ * @param {IdentificationInputProps} props
+ * @param {number} [props.length=6] 입력 필드 길이. 4~8 범위로 자동 보정된다.
+ * @param {InputProps["label"]} [props.label] 상단 label 콘텐츠.
+ * @param {InputProps["helperText"]} [props.helperText] helper 텍스트.
+ * @param {InputProps["state"]} [props.state] 시각 상태.
+ * @param {(code: string) => void} [props.onComplete] 모든 셀이 채워졌을 때 호출되는 콜백.
  */
 const IdentificationInput = forwardRef<
   HTMLInputElement[],

package/src/components/input/markup/text/Password.tsx

@@ -4,6 +4,12 @@ import { Text } from "./Base";
 import HideOffIcon from "../../img/hide-off.svg";
 import HideOnIcon from "../../img/hide-on.svg";
 
+/**
+ * PasswordInput 전용 props. Text Input props에서 type/defaultValue 제약을 재정의하고 toggle 옵션을 추가한다.
+ * @property {boolean} [defaultVisible=false] 초기 렌더 시 비밀번호를 드러낼지 여부.
+ * @property {{show: string; hide: string}} [toggleLabel] 토글 버튼에 사용할 라벨 텍스트 집합.
+ * @property {string} [defaultValue] 비제어 초기값.
+ */
 export interface PasswordInputProps extends Omit<
   InputProps,
   "type" | "defaultValue"
@@ -18,8 +24,35 @@ export interface PasswordInputProps extends Omit<
 
 /**
  * PasswordInput — 기본 Text 입력을 비밀번호 토글 UX로 확장.
- * @param props.defaultVisible 최초 노출 여부.
- * @param props.toggleLabel 토글 버튼의 라벨 텍스트.
+ * @component
+ * @param {PasswordInputProps} props
+ * @param {"primary" | "secondary" | "tertiary"} [props.appearance="primary"] 토큰 세트.
+ * @param {"small" | "medium" | "large"} [props.size="medium"] 높이/spacing.
+ * @param {"default" | "active" | "focused" | "success" | "error" | "disabled"} [props.state="default"] 시각 상태.
+ * @param {boolean} [props.block=false] true면 width 100%.
+ * @param {React.ReactNode} [props.prefix] prefix 슬롯(Password에서는 기본 제공하지 않음).
+ * @param {React.ReactNode} [props.suffix] suffix 슬롯. 미지정 시 보기/숨김 토글 버튼 자동 배치.
+ * @param {React.ReactNode} [props.successIcon] success 상태 아이콘.
+ * @param {React.ReactNode} [props.errorIcon] error 상태 아이콘.
+ * @param {React.ReactNode} [props.label] label 영역 콘텐츠.
+ * @param {React.ReactNode} [props.helperText] helper 영역 텍스트.
+ * @param {boolean} [props.hideHelperText] helper 숨김 여부.
+ * @param {string} [props.inputClassName] `<input>` className.
+ * @param {string} [props.wrapperClassName] `.input-box` className.
+ * @param {object} [props.labelProps] label attr.
+ * @param {object} [props.helperTextProps] helper attr.
+ * @param {boolean} [props.disabled] native disabled.
+ * @param {string} [props.id] 외부 id.
+ * @param {string} [props.className] root className.
+ * @param {"default" | "active" | "focused" | "success" | "error" | "disabled"} [props.data-simulated-state]
+ *  Storybook 시각 상태 강제용.
+ * @param {string} [props.defaultValue] 비제어 초기값.
+ * @param {string | number | readonly string[]} [props.value] 제어형 값.
+ * @param {(event: React.ChangeEvent<HTMLInputElement>) => void} [props.onChange] 변경 핸들러.
+ * @param {(event: React.FocusEvent<HTMLInputElement>) => void} [props.onFocus] focus 핸들러.
+ * @param {(event: React.FocusEvent<HTMLInputElement>) => void} [props.onBlur] blur 핸들러.
+ * @param {boolean} [props.defaultVisible=false] 초기 노출 여부.
+ * @param {{show: string; hide: string}} [props.toggleLabel] 토글 버튼 라벨.
  */
 const PasswordInput = forwardRef<HTMLInputElement, PasswordInputProps>(
   (

package/src/components/input/markup/text/Phone.tsx

@@ -4,6 +4,16 @@ import { forwardRef, useCallback, useMemo, useState } from "react";
 import type { InputProps } from "../../types";
 import { Text } from "./Base";
 
+/**
+ * PhoneInput 전용 props. Text Input 중 전화번호 UX에 필요한 필드를 정의한다.
+ * @property {string} [value] 제어형 포맷팅 값.
+ * @property {string} [defaultValue] 비제어 초기값(숫자/포맷 모두 허용).
+ * @property {(value: string, digits: string) => void} [onValueChange] 포맷팅 값/숫자만 값을 함께 전달.
+ * @property {ComponentPropsWithoutRef<"input">["onChange"]} [onChange] native onChange override.
+ * @property {() => void} [onRequestCode] suffix 버튼 클릭 시 호출.
+ * @property {string} [requestButtonLabel="인증번호 요청"] suffix 버튼 라벨.
+ * @property {boolean} [requestButtonDisabled] suffix 버튼 disabled 여부.
+ */
 export interface PhoneInputProps extends Omit<
   InputProps,
   | "type"
@@ -32,8 +42,34 @@ const formatPhoneNumber = (digits: string) => maskPhone(digits);
 
 /**
  * PhoneInput — 휴대폰 번호 마스킹과 인증번호 요청 버튼을 제공하는 입력.
- * @param props.onValueChange 포맷팅된 값 + 숫자만 별도로 전달.
- * @param props.onRequestCode 인증번호 요청 버튼 클릭 핸들러.
+ * @component
+ * @param {PhoneInputProps} props
+ * @param {"primary" | "secondary" | "tertiary"} [props.appearance="primary"] 토큰 세트.
+ * @param {"small" | "medium" | "large"} [props.size="medium"] 높이/spacing.
+ * @param {"default" | "active" | "focused" | "success" | "error" | "disabled"} [props.state="default"] 시각 상태.
+ * @param {boolean} [props.block=false] true면 width 100%.
+ * @param {React.ReactNode} [props.suffix] suffix 슬롯. 미지정 시 인증 버튼 자동 배치.
+ * @param {React.ReactNode} [props.successIcon] success 상태 아이콘.
+ * @param {React.ReactNode} [props.errorIcon] error 상태 아이콘.
+ * @param {React.ReactNode} [props.label] label 콘텐츠.
+ * @param {React.ReactNode} [props.helperText] helper 텍스트.
+ * @param {boolean} [props.hideHelperText] helper 숨김 여부.
+ * @param {string} [props.inputClassName] `<input>` className.
+ * @param {string} [props.wrapperClassName] `.input-box` className.
+ * @param {object} [props.labelProps] label attr.
+ * @param {object} [props.helperTextProps] helper attr.
+ * @param {boolean} [props.disabled] native disabled.
+ * @param {string} [props.id] 외부 id.
+ * @param {string} [props.className] root className.
+ * @param {"default" | "active" | "focused" | "success" | "error" | "disabled"} [props.data-simulated-state]
+ *  Storybook 시각 상태 강제용.
+ * @param {string} [props.value] 제어형 값(포맷팅).
+ * @param {string} [props.defaultValue] 비제어 초기값.
+ * @param {(value: string, digits: string) => void} [props.onValueChange] 포맷팅/숫자 값 동시 전달.
+ * @param {(event: ChangeEvent<HTMLInputElement>) => void} [props.onChange] native onChange override.
+ * @param {() => void} [props.onRequestCode] 인증번호 요청 버튼 핸들러.
+ * @param {string} [props.requestButtonLabel="인증번호 요청"] 버튼 라벨.
+ * @param {boolean} [props.requestButtonDisabled] 버튼 disabled.
  */
 const PhoneInput = forwardRef<HTMLInputElement, PhoneInputProps>(
   (

package/src/components/input/markup/text/Search.tsx

@@ -3,11 +3,40 @@ import type { InputProps } from "../../types";
 import { Text } from "./Base";
 import SearchIcon from "../../img/search.svg";
 
+/**
+ * SearchInput 전용 props. type을 search로 강제하고 나머지는 Text 입력과 동일하다.
+ */
 export interface SearchInputProps extends Omit<InputProps, "type"> {}
 
 /**
  * SearchInput — 기본 Text 입력에 검색 아이콘 prefix를 제공한다.
- * @param props.prefix prefix slot. 정의하지 않으면 검색 아이콘이 자동 배치된다.
+ * @component
+ * @param {SearchInputProps} props
+ * @param {"primary" | "secondary" | "tertiary"} [props.appearance="primary"] 토큰 세트.
+ * @param {"small" | "medium" | "large"} [props.size="medium"] 높이/spacing.
+ * @param {"default" | "active" | "focused" | "success" | "error" | "disabled"} [props.state="default"] 시각 상태.
+ * @param {boolean} [props.block=false] true면 width 100%.
+ * @param {React.ReactNode} [props.prefix] prefix 슬롯. 미지정 시 돋보기 아이콘이 자동 배치된다.
+ * @param {React.ReactNode} [props.suffix] suffix 슬롯.
+ * @param {React.ReactNode} [props.successIcon] success 상태 아이콘.
+ * @param {React.ReactNode} [props.errorIcon] error 상태 아이콘.
+ * @param {React.ReactNode} [props.label] label 콘텐츠.
+ * @param {React.ReactNode} [props.helperText] helper 텍스트.
+ * @param {boolean} [props.hideHelperText] helper 숨김 여부.
+ * @param {string} [props.inputClassName] `<input>` className.
+ * @param {string} [props.wrapperClassName] `.input-box` className.
+ * @param {object} [props.labelProps] label attr.
+ * @param {object} [props.helperTextProps] helper attr.
+ * @param {boolean} [props.disabled] native disabled.
+ * @param {string} [props.id] 외부 id.
+ * @param {string} [props.className] root className.
+ * @param {"default" | "active" | "focused" | "success" | "error" | "disabled"} [props.data-simulated-state]
+ *  Storybook 시각 상태 강제용.
+ * @param {string | number | readonly string[]} [props.defaultValue] 비제어 초기값.
+ * @param {string | number | readonly string[]} [props.value] 제어형 값.
+ * @param {(event: React.ChangeEvent<HTMLInputElement>) => void} [props.onChange] 입력 변경 핸들러.
+ * @param {(event: React.FocusEvent<HTMLInputElement>) => void} [props.onFocus] focus 핸들러.
+ * @param {(event: React.FocusEvent<HTMLInputElement>) => void} [props.onBlur] blur 핸들러.
  */
 const SearchInput = forwardRef<HTMLInputElement, SearchInputProps>(
   ({ prefix, ...restProps }, forwardedRef) => {

package/src/components/input/styles/index.scss

@@ -4,12 +4,12 @@
   --theme-input-height-small: var(--theme-size-medium-1);
   --theme-input-height-medium: var(--theme-size-medium-2);
   --theme-input-height-large: var(--theme-size-medium-3);
-  --theme-input-height-teritary: calc(var(--theme-size-medium-2) + 24px);
+  --theme-input-height-tertiary: calc(var(--theme-size-medium-2) + 24px);
   --theme-input-padding-x: var(--spacing-padding-6);
   --theme-input-padding-y: var(--spacing-padding-4);
   --theme-input-gap: var(--spacing-gap-4);
   --theme-input-radius-default: var(--theme-radius-large-1);
-  --theme-input-radius-teritary: var(--theme-radius-large-2);
+  --theme-input-radius-tertiary: var(--theme-radius-large-2);
   --theme-input-label-color: var(--color-label-standard);
   --theme-input-helper-color: var(--color-label-neutral);
   --theme-input-helper-disabled-color: var(--color-label-disabled);
@@ -106,10 +106,10 @@
     background-color: transparent;
   }
 
-  &[data-appearance="teritary"] {
-    border-radius: var(--theme-input-radius-teritary);
+  &[data-appearance="tertiary"] {
+    border-radius: var(--theme-input-radius-tertiary);
     background-color: var(--theme-input-surface);
-    min-height: var(--theme-input-height-teritary);
+    min-height: var(--theme-input-height-tertiary);
     flex-wrap: wrap;
     row-gap: var(--spacing-gap-1);
     column-gap: var(--theme-input-gap);
@@ -200,7 +200,7 @@
   padding-inline: 0;
 }
 
-.input-field[data-appearance="teritary"] .input-element {
+.input-field[data-appearance="tertiary"] .input-element {
   min-height: var(--theme-size-medium-2);
 }
 

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

@@ -1,7 +1,16 @@
 import type { ComponentPropsWithoutRef, ReactElement, ReactNode } from "react";
 
-export const INPUT_APPEARANCES = ["primary", "secondary", "teritary"] as const;
+/**
+ * appearance 축은 tokens 기반 테마 계층을 지정한다.
+ */
+export const INPUT_APPEARANCES = ["primary", "secondary", "tertiary"] as const;
+/**
+ * size 축은 높이/타이포/spacing을 결정한다.
+ */
 export const INPUT_SIZES = ["small", "medium", "large"] as const;
+/**
+ * 시각 상태는 success/error/disabled 를 포함한다.
+ */
 export const INPUT_STATES = [
   "default",
   "active",
@@ -17,6 +26,9 @@ export type InputState = (typeof INPUT_STATES)[number];
 
 type NativeInputProps = ComponentPropsWithoutRef<"input">;
 
+/**
+ * prefix/suffix와 status 아이콘 슬롯 정의.
+ */
 export interface InputAffix {
   prefix?: ReactNode;
   suffix?: ReactNode;
@@ -25,12 +37,18 @@ export interface InputAffix {
   errorIcon?: ReactNode;
 }
 
+/**
+ * label/helperText 등 피드백 슬롯 정의.
+ */
 export interface InputFeedback {
   label?: ReactNode;
   helperText?: ReactNode;
   hideHelperText?: boolean;
 }
 
+/**
+ * 텍스트 입력의 핵심 props. native input 속성에서 size/prefix/suffix는 제외하고 자체 슬롯으로 교체했다.
+ */
 export interface InputProps
   extends
     Omit<NativeInputProps, "prefix" | "suffix" | "size">,
@@ -47,6 +65,9 @@ export interface InputProps
   "data-simulated-state"?: InputState;
 }
 
+/**
+ * className composer helper가 필요로 하는 파라미터 집합.
+ */
 export interface InputClassNameOptions {
   appearance: InputAppearance;
   size: InputSize;

package/src/components/input/utils/index.ts

@@ -7,6 +7,9 @@ const INPUT_FIELD_CLASSNAME = "input-field";
 const INPUT_ELEMENT_CLASSNAME = "input-element";
 const INPUT_AFFIX_CLASSNAME = "input-affix";
 
+/**
+ * container `.input` element className을 조립한다.
+ */
 const composeInputClassName = ({
   appearance,
   size,
@@ -25,6 +28,9 @@ const composeInputClassName = ({
     className,
   );
 
+/**
+ * 박스(wrapper) `.input-box` className을 조립한다.
+ */
 const composeInputBoxClassName = ({
   appearance,
   size,

package/src/components/navigation/markup/mobile/BottomNavigation.tsx

@@ -10,6 +10,17 @@ import {
   isHrefNavigationItem,
 } from "../../utils";
 
+/**
+ * BottomNavigation — 모바일 하단 내비게이션.
+ * @component
+ * @param {BottomNavigationProps} props
+ * @param {NavigationItem[]} props.items 렌더링할 항목 배열.
+ * @param {NavigationItemKey | null} props.activeKey 현재 활성 key.
+ * @param {(key: NavigationItemKey) => void} [props.onActiveChange] active 변경 콜백.
+ * @param {string} [props.ariaLabel] nav 라벨. 없으면 전달된 `aria-label` 속성을 사용한다.
+ * @param {boolean} [props.fixed=false] true면 뷰포트 하단 고정 스타일.
+ * @param {string} [props.className] root className.
+ */
 const BottomNavigation = forwardRef<HTMLElement, BottomNavigationProps>(
   (
     {