@uniai-fe/uds-primitives 0.3.60 → 0.4.0

package/src/components/button/markup/Base.tsx

@@ -11,27 +11,29 @@ import {
 } from "../../form/utils/form-field";
 
 /**
- * uds-foundation 토큰 위에서 block/layout/priority/slot API를 제공하는 기본 Button 컴포넌트.
+ * Button Component; Default action button
  * @component
  * @param {ButtonProps} props
- * @param {ElementType} [props.as="button"] 커스텀 요소(Renderer).
- * @param {React.ReactNode} [props.children] 문자열이면 `.button-label` span으로 감싼다.
- * @param {React.ReactNode} [props.left] 라벨 왼쪽 커스텀 슬롯.
- * @param {React.ReactNode} [props.right] 라벨 오른쪽 커스텀 슬롯.
- * @param {
- *  "solid-xlarge" | "solid-large" | "solid-medium" | "solid-small" |
- *  "outlined-xlarge" | "outlined-large" | "outlined-medium" | "outlined-small"
- * } [props.scale="solid-medium"] legacy spacing 식별자. fill/size가 없을 때만 fallback 용도로 사용한다.
- * @param {"solid" | "outlined"} [props.fill] 채움 스타일. scale과 별개로 직접 지정할 수 있다.
- * @param {"xlarge" | "large" | "medium" | "small" | "table"} [props.size] 버튼 높이/타이포 스케일. table은 셀 액션용 compact(24px) 규격이다.
- * @param {"primary" | "secondary" | "tertiary"} [props.priority="primary"] semantic color 세트.
- * @param {"default" | "readonly" | "disabled"} [props.state="default"] 내부 state. disabled prop과 조합된다.
- * @param {boolean} [props.block=false] true면 width 100%.
- * @param {boolean} [props.loading=false] true면 readonly 처리 + aria-busy.
+ * @param {ElementType} [props.as="button"] 렌더링할 요소.
+ * @param {React.ReactNode} [props.children] 문자열/숫자는 `.button-label`로 래핑하고, 그 외 ReactNode는 그대로 렌더링한다.
+ * @param {"solid-xlarge" | "solid-large" | "solid-medium" | "solid-small" | "outlined-xlarge" | "outlined-large" | "outlined-medium" | "outlined-small"} [props.scale] legacy fill/size fallback 식별자.
+ * @param {"solid" | "outlined"} props.fill 채움 스타일.
+ * @param {"xlarge" | "large" | "medium" | "small" | "table"} props.size 버튼 크기. `table`은 Table 셀 액션용 compact 규격이다.
+ * @param {"primary" | "secondary" | "tertiary"} props.priority semantic color priority.
+ * @param {"default" | "readonly" | "disabled"} [props.state="default"] 내부 상태. `disabled`/`loading`과 병합된다.
+ * @param {boolean} [props.block=false] true면 폭을 100%로 확장한다.
+ * @param {"full" | "fit" | "fill" | "auto" | number | string} [props.width] Form.Field width preset 또는 custom width.
+ * @param {boolean} [props.loading=false] true면 readonly 상태와 `aria-busy`를 강제한다.
+ * @param {React.ReactNode} [props.left] 라벨 왼쪽 콘텐츠.
+ * @param {React.ReactNode} [props.right] 라벨 오른쪽 콘텐츠.
  * @param {string} [props.className] 추가 className.
- * @param {"button" | "submit" | "reset"} [props.type="button"] button 요소일 때 type.
- * @param {boolean} [props.disabled] native disabled. state보다 우선한다.
- * @param {"hover" | "pressed"} [props.data-user-action] Story 시각 상태 고정용 data attr.
+ * @param {"button" | "submit" | "reset"} [props.type="button"] `button` 태그일 때 native type.
+ * @param {boolean} [props.disabled] native disabled. `state`보다 우선한다.
+ * @param {"hover" | "pressed"} [props["data-user-action"]] Storybook 시각 상태 고정용 data attribute.
+ * @example
+ * <Button.Default fill="solid" size="medium" priority="primary">
+ *   확인
+ * </Button.Default>
  */
 const ButtonDefault = forwardRef<HTMLElement, ButtonProps>(
   (

package/src/components/button/markup/Rounded.tsx

@@ -4,12 +4,15 @@ import type { RoundButtonProps } from "../types";
 import { ButtonDefault } from "./Base";
 
 /**
- * 원형 버튼 템플릿. size만 받으면 적절한 scale을 선택하고 라운드 전용 className을 적용한다.
+ * Button Component; Rounded action button
  * @component
  * @param {RoundButtonProps} props
- * @param {"small" | "medium" | "large"} props.size size에 따라 scale을 매핑한다.
- * @param {"primary" | "secondary" | "tertiary"} props.priority semantic color.
- * @param {boolean} [props.block] width 확장 여부.
+ * @param {"small" | "medium" | "large"} props.size 라운드 버튼 크기 축.
+ * @param {"primary" | "secondary" | "tertiary"} props.priority semantic color priority.
+ * @example
+ * <Button.Rounded size="small" priority="primary" aria-label="추가">
+ *   <span aria-hidden="true">+</span>
+ * </Button.Rounded>
  */
 const ButtonRounded = forwardRef<HTMLElement, RoundButtonProps>(
   // 라운드 전용 템플릿도 fill/size/priority를 직접 주입해 공통 규칙을 따른다.

package/src/components/button/markup/Text.tsx

@@ -4,12 +4,15 @@ import type { TextButtonProps } from "../types";
 import { ButtonDefault } from "./Base";
 
 /**
- * 텍스트 링크형 버튼 템플릿. size/priority 조합만 노출하고 나머지는 ButtonDefault에서 처리한다.
+ * Button Component; Text action button
  * @component
  * @param {TextButtonProps} props
- * @param {"small" | "medium" | "large"} props.size size에 따른 scale 파생.
- * @param {"secondary" | "tertiary"} props.priority semantic color.
- * @param {boolean} [props.block] 텍스트 버튼도 block 확장 가능.
+ * @param {"small" | "medium" | "large"} props.size 텍스트 버튼 크기 축.
+ * @param {"secondary" | "tertiary"} props.priority 텍스트 버튼 priority 축.
+ * @example
+ * <Button.Text size="medium" priority="secondary">
+ *   자세히 보기
+ * </Button.Text>
  */
 const ButtonText = forwardRef<HTMLElement, TextButtonProps>(
   // 템플릿 레벨에서 fill/size/priority를 강제해 ButtonDefault 정책과 동기화한다.

package/src/components/calendar/index.tsx

@@ -1,3 +1,11 @@
+/**
+ * Calendar; date picker 조합 카테고리 배럴
+ * @desc
+ * - `Calendar.Root`: trigger + popover + core 조합 템플릿이다.
+ * - `Calendar.Container`: Header/Body/Footer 레이아웃 컨테이너다.
+ * - `Calendar.Core`: Mantine DatePicker SOT 렌더러다.
+ * - `CalendarHooks`, `CalendarUtils`: 관련 hook/util namespace다.
+ */
 import "./index.scss";
 
 export * from "./markup";

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

@@ -7,13 +7,13 @@ import CalendarRoot from "./Root";
 import { CalendarIcon } from "./Icon";
 
 /**
- * Calendar namespace.
- * - Root
- * - Container
- * - Header
- * - Body
- * - Footer
- * - Core
+ * Calendar; date picker namespace
+ * @desc
+ * - `Calendar.Root`: trigger + popover + core 조합 템플릿이다.
+ * - `Calendar.Container`: Header/Body/Footer 레이아웃 컨테이너다.
+ * - `Calendar.Header`, `Calendar.Body`, `Calendar.Footer`: depth 고정 레이아웃 섹션이다.
+ * - `Calendar.Core`: Mantine DatePicker SOT 렌더러다.
+ * - `Calendar.Icon`: 입력/네비게이션 아이콘 namespace다.
  */
 export const Calendar = {
   Root: CalendarRoot,

package/src/components/carousel/index.tsx

@@ -1,3 +1,11 @@
+/**
+ * Carousel; viewport scroll carousel 카테고리 배럴
+ * @desc
+ * - `Carousel.Provider`: viewport/track 상태 공유 루트다.
+ * - `Carousel.Track`: viewport + track 렌더러다.
+ * - `Carousel.Control`, `Carousel.Button.*`: 이동 제어 도구다.
+ * - `useCarousel`: provider context 접근 hook이다.
+ */
 import "./index.scss";
 
 export * from "./markup";

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

@@ -6,6 +6,15 @@ import { CarouselPrevButton } from "./button/Prev";
 import { CarouselProvider } from "./Provider";
 import { CarouselTrack } from "./Track";
 
+/**
+ * Carousel; viewport scroll carousel namespace
+ * @desc
+ * - `Carousel.Provider`: viewport/track 상태 공유 루트다.
+ * - `Carousel.Container`: Provider + Control 프리셋이다.
+ * - `Carousel.Control`: Prev/Track/Next 조합 컨트롤이다.
+ * - `Carousel.Track`: viewport + track 렌더러다.
+ * - `Carousel.Button.Base|Prev|Next`: 이동 제어 leaf 버튼이다.
+ */
 export const Carousel = {
   Provider: CarouselProvider,
   Container: CarouselContainer,

package/src/components/checkbox/index.tsx

@@ -1,3 +1,10 @@
+/**
+ * Checkbox; namespace 배럴 export
+ * @desc
+ * - `Checkbox`: leaf checkbox control
+ * - `CheckboxField`: label/helper 포함 field wrapper
+ * - hooks/types는 별도 배럴로 함께 export한다
+ */
 import "./index.scss";
 
 export * from "./markup";

package/src/components/chip/index.tsx

@@ -1,5 +1,11 @@
 /**
- * chips 카테고리 배럴
+ * Chip; filter/assist/input chip 카테고리 배럴
+ * @desc
+ * - `Chip.Default`: style 분기 루트 컴포넌트다.
+ * - `Chip.ClickableStyle`: filter/assist button 렌더 전용 leaf다.
+ * - `Chip.InputStyle`: input figure 렌더 전용 leaf다.
+ * - `Chip.List`: chip 목록 템플릿이다.
+ * - `ChipProps`, `ChipListRootProps`, `ChipListItemData`: public contract 타입이다.
  */
 import "./index.scss";
 

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

@@ -4,6 +4,15 @@ import ChipInputStyle from "./InputStyle";
 import ChipLabel from "./Label";
 import { ChipListRoot } from "./ListRoot";
 
+/**
+ * Chip; filter/assist/input namespace
+ * @desc
+ * - `Chip.Default`: style 분기 루트 컴포넌트다.
+ * - `Chip.ClickableStyle`: filter/assist button 렌더 전용 leaf다.
+ * - `Chip.InputStyle`: input figure 렌더 전용 leaf다.
+ * - `Chip.Label`: chip 텍스트 슬롯이다.
+ * - `Chip.List`: chip 목록 템플릿이다.
+ */
 export const Chip = {
   Default: ChipDefault,
   ClickableStyle: ChipClickableStyle,

package/src/components/divider/index.tsx

@@ -1,5 +1,9 @@
 import "./index.scss";
 
+/**
+ * Divider; 방향 전환형 구분선 엔트리
+ */
 import { Divider } from "./markup";
+export type * from "./types";
 
 export { Divider };

package/src/components/divider/markup/Divider.tsx

@@ -1,11 +1,15 @@
 import clsx from "clsx";
+import type { DividerProps } from "../types";
 
-export function Divider({
-  className,
-  direction = "vertical",
-}: {
-  className?: string;
-  direction?: "horizontal" | "vertical";
-}) {
+/**
+ * Divider; 수평/수직 구분선 마크업
+ * @component
+ * @param {DividerProps} props
+ * @param {string} [props.className] divider 루트 className
+ * @param {"horizontal" | "vertical"} [props.direction] 구분선 방향
+ * @example
+ * <Divider direction="horizontal" />
+ */
+export function Divider({ className, direction = "vertical" }: DividerProps) {
   return <div className={clsx("divider", direction, className)}></div>;
 }

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

@@ -0,0 +1 @@
+export type { DividerDirection, DividerProps } from "./props";

package/src/components/divider/types/props.ts

@@ -0,0 +1,27 @@
+import type { ComponentPropsWithoutRef } from "react";
+
+/**
+ * DividerDirection; divider 방향 축
+ * @typedef {"horizontal" | "vertical"} DividerDirection
+ */
+export type DividerDirection = "horizontal" | "vertical";
+
+/**
+ * Divider Props; divider 루트 속성
+ * @property {string} [className] divider 루트 className
+ * @property {"horizontal" | "vertical"} [direction] 구분선 방향
+ * @see React.ComponentPropsWithoutRef<"div">
+ */
+export interface DividerProps extends Omit<
+  ComponentPropsWithoutRef<"div">,
+  "children"
+> {
+  /**
+   * divider 루트 className
+   */
+  className?: string;
+  /**
+   * 구분선 방향
+   */
+  direction?: DividerDirection;
+}

package/src/components/drawer/index.tsx

@@ -1,3 +1,10 @@
+/**
+ * Drawer; bottom sheet 카테고리 배럴
+ * @desc
+ * - `DrawerRoot`, `DrawerTrigger`, `DrawerPortal`, `DrawerOverlay`, `DrawerContent`: 루트/레이어 조합 축이다.
+ * - `DrawerHeader`, `DrawerBody`, `DrawerFooter`, `DrawerTitle`, `DrawerDescription`, `DrawerClose`: anatomy 도구다.
+ * - `useDrawerDrag`: handle drag 제어 hook이다.
+ */
 import "./index.scss";
 
 export * from "./markup";

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

@@ -1,3 +1,9 @@
 "use client";
 
+/**
+ * Drawer; bottom sheet markup export 배럴
+ * @desc
+ * - `DrawerRoot`, `DrawerTrigger`, `DrawerPortal`, `DrawerOverlay`, `DrawerContent`: 루트/레이어 조합 축이다.
+ * - `DrawerHeader`, `DrawerBody`, `DrawerFooter`, `DrawerTitle`, `DrawerDescription`, `DrawerClose`: anatomy 도구다.
+ */
 export * from "./Drawer";

package/src/components/dropdown/index.tsx

@@ -1,3 +1,10 @@
+/**
+ * Dropdown; namespace 배럴 export
+ * @desc
+ * - `Dropdown.Root`, `Dropdown.Trigger`, `Dropdown.Container`: foundation 레이어
+ * - `Dropdown.Menu.*`: list/item 조합 레이어
+ * - `Dropdown.Template`: items[].selected + onChange(payload) preset
+ */
 import "./index.scss";
 
 export * from "./markup";

package/src/components/dropdown/markup/Template.tsx

@@ -27,8 +27,9 @@ import {
  * @param {ReactNode} props.trigger trigger 요소
  * @param {DropdownTemplateItem[]} props.items 렌더링할 menu item 리스트
  * @param {(payload: DropdownTemplateChangePayload) => void} [props.onChange] 선택 결과 변경 콜백
- * @param {"small" | "medium" | "large"} [props.size="medium"] menu size scale
+ * @param {"xsmall" | "small" | "medium" | "large"} [props.size="medium"] menu size scale
  * @param {"match" | "fit-content" | "max-content" | string | number} [props.width="match"] panel width 옵션
+ * @param {"match" | "fit-content" | "max-content" | string | number} [props.minWidth] panel 최소 너비 옵션
  * @param {DropdownMenuProps} [props.rootProps] Dropdown.Root 전달 props
  * @param {DropdownContainerProps} [props.containerProps] Dropdown.Container 전달 props
  * @param {DropdownMenuListProps} [props.menuListProps] Dropdown.Menu.List 전달 props
@@ -40,6 +41,7 @@ const DropdownTemplate = ({
   onChange,
   size = "medium",
   width = "match",
+  minWidth,
   rootProps,
   containerProps,
   menuListProps,
@@ -199,7 +201,12 @@ const DropdownTemplate = ({
   return (
     <DropdownRoot {...rootProps}>
       <DropdownTrigger asChild>{trigger}</DropdownTrigger>
-      <DropdownContainer {...containerProps} size={size} width={width}>
+      <DropdownContainer
+        {...containerProps}
+        size={size}
+        width={width}
+        minWidth={minWidth}
+      >
         <DropdownMenuList {...menuListProps}>
           {items.length > 0 ? (
             <>

package/src/components/dropdown/markup/foundation/Container.tsx

@@ -15,6 +15,7 @@ import { useDropdownContext } from "./Provider";
  * @param {string} [props.className] panel className
  * @param {DropdownSize} [props.size="medium"] option height scale
  * @param {DropdownPanelWidth} [props.width="match"] panel width 옵션
+ * @param {DropdownPanelMinWidth} [props.minWidth] panel 최소 너비 옵션
  * @param {HTMLElement | null} [props.portalContainer] portal 컨테이너
  * @param {"start" | "center" | "end"} [props.align="start"] 정렬 기준
  * @param {"top" | "right" | "bottom" | "left"} [props.side="bottom"] 패널 위치
@@ -33,6 +34,7 @@ const DropdownContainer = forwardRef<HTMLDivElement, DropdownContainerProps>(
       className,
       size = "medium",
       width = "match",
+      minWidth,
       portalContainer,
       align = "start",
       side = "bottom",
@@ -47,29 +49,46 @@ const DropdownContainer = forwardRef<HTMLDivElement, DropdownContainerProps>(
     const [panelWidth, setPanelWidth] = useState<number>();
     const shouldMatchTriggerWidth = width === "match";
 
-    const resolvedMinWidth = useMemo(() => {
-      if (shouldMatchTriggerWidth) {
+    const resolvePanelSizeValue = (
+      value?: string | number,
+      fallbackToMatch?: boolean,
+    ): string | undefined => {
+      if (value === undefined) {
         return undefined;
       }
 
-      if (typeof width === "number") {
-        return `${width}px`;
+      if (typeof value === "number") {
+        return `${value}px`;
       }
 
-      if (typeof width === "string") {
-        if (width === "fit-content") {
+      if (typeof value === "string") {
+        if (value === "fit-content") {
           return "fit-content";
         }
-        if (width === "max-content") {
+        if (value === "max-content") {
           return "max-content";
         }
-        if (width.trim().length > 0 && width !== "match") {
-          return width;
+        if (fallbackToMatch && value === "match" && panelWidth) {
+          return `${panelWidth}px`;
+        }
+        if (value.trim().length > 0 && value !== "match") {
+          return value;
         }
       }
 
       return undefined;
-    }, [shouldMatchTriggerWidth, width]);
+    };
+    const resolvedWidth = useMemo(() => {
+      if (shouldMatchTriggerWidth) {
+        return panelWidth ? `${panelWidth}px` : undefined;
+      }
+
+      return resolvePanelSizeValue(width);
+    }, [panelWidth, shouldMatchTriggerWidth, width]);
+    const resolvedMinWidth = useMemo(() => {
+      // 변경 설명: width 계약은 기준 폭, minWidth 계약은 최소 보장 폭으로 분리한다.
+      return resolvePanelSizeValue(minWidth, true);
+    }, [minWidth, panelWidth]);
 
     useEffect(() => {
       if (!shouldMatchTriggerWidth) {
@@ -110,8 +129,7 @@ const DropdownContainer = forwardRef<HTMLDivElement, DropdownContainerProps>(
         className={clsx("dropdown-panel", `dropdown-panel-${size}`, className)}
         style={{
           ...style,
-          width:
-            shouldMatchTriggerWidth && panelWidth ? panelWidth : style?.width,
+          width: resolvedWidth ?? style?.width,
           minWidth:
             resolvedMinWidth !== undefined ? resolvedMinWidth : style?.minWidth,
         }}

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

@@ -2,16 +2,15 @@ import { DropdownFoundation } from "./foundation";
 import DropdownTemplate from "./Template";
 
 /**
- * Dropdown
- * - Provider
- * - Root
- * - Container
- * - Menu
- *     - Item
- *     - List
- * - Panel
- * - Trigger
- * - Template
+ * Dropdown; 컴포넌트 모듈
+ * @namespace Dropdown
+ * - `Dropdown.Provider`
+ * - `Dropdown.Root`
+ * - `Dropdown.Trigger`
+ * - `Dropdown.Container`
+ * - `Dropdown.Menu.Item`
+ * - `Dropdown.Menu.List`
+ * - `Dropdown.Template`
  */
 export const Dropdown = {
   ...DropdownFoundation,

package/src/components/dropdown/types/base.ts

@@ -16,3 +16,16 @@ export type DropdownPanelWidth =
   | "max-content"
   | string
   | number;
+
+/**
+ * Dropdown panel min-width 옵션
+ * - "match": trigger width를 최소 폭으로 보장
+ * - "fit-content" | "max-content": 콘텐츠 기준 최소 폭
+ * - string/number: 커스텀 최소 폭
+ */
+export type DropdownPanelMinWidth =
+  | "match"
+  | "fit-content"
+  | "max-content"
+  | string
+  | number;

package/src/components/dropdown/types/props.ts

@@ -6,7 +6,11 @@ import type {
 import type { HTMLAttributes, ReactNode, RefObject } from "react";
 
 import type { CheckboxProps } from "../../checkbox/types";
-import type { DropdownPanelWidth, DropdownSize } from "./base";
+import type {
+  DropdownPanelMinWidth,
+  DropdownPanelWidth,
+  DropdownSize,
+} from "./base";
 
 /**
  * Dropdown template value 타입
@@ -17,6 +21,7 @@ export type DropdownTemplateValue = string | number;
  * Dropdown Container props
  * @property {DropdownSize} [size="medium"] option 높이 스케일
  * @property {DropdownPanelWidth} [width="match"] dropdown panel width 옵션
+ * @property {DropdownPanelMinWidth} [minWidth] dropdown panel 최소 너비 옵션
  * @property {HTMLElement | null} [portalContainer] portal을 렌더링할 DOM 컨테이너
  */
 export interface DropdownContainerProps extends DropdownMenuContentProps {
@@ -28,6 +33,10 @@ export interface DropdownContainerProps extends DropdownMenuContentProps {
    * trigger 너비에 맞춰 dropdown 너비를 맞출지 여부
    */
   width?: DropdownPanelWidth;
+  /**
+   * dropdown 최소 너비 제약
+   */
+  minWidth?: DropdownPanelMinWidth;
   /**
    * portal을 렌더링할 DOM 컨테이너
    */
@@ -191,6 +200,7 @@ export interface DropdownTemplateChangePayload {
  * @property {(payload: DropdownTemplateChangePayload) => void} [onChange] 선택 결과 변경 콜백
  * @property {DropdownSize} [size="medium"] surface height scale
  * @property {DropdownPanelWidth} [width="match"] panel width 옵션
+ * @property {DropdownPanelMinWidth} [minWidth] panel 최소 너비 옵션
  * @property {DropdownMenuProps} [rootProps] Root 에 전달할 props
  * @property {DropdownContainerProps} [containerProps] Container 에 전달할 props
  * @property {DropdownMenuListProps} [menuListProps] MenuList 에 전달할 props
@@ -205,6 +215,10 @@ export interface DropdownTemplateProps {
   onChange?: (payload: DropdownTemplateChangePayload) => void;
   size?: DropdownSize;
   width?: DropdownPanelWidth;
+  /**
+   * panel 최소 너비 옵션
+   */
+  minWidth?: DropdownPanelMinWidth;
   /**
    * Root 에 전달할 props
    * - 타입 출처를 명확히 하기 위해 Radix 원본 타입을 직접 사용한다.
@@ -213,7 +227,10 @@ export interface DropdownTemplateProps {
   /**
    * Container 에 전달할 props
    */
-  containerProps?: Omit<DropdownContainerProps, "children" | "size" | "width">;
+  containerProps?: Omit<
+    DropdownContainerProps,
+    "children" | "size" | "width" | "minWidth"
+  >;
   /**
    * MenuList 에 전달할 props
    */

package/src/components/form/index.tsx

@@ -1,3 +1,10 @@
+/**
+ * Form; provider + field layout 카테고리 배럴
+ * @desc
+ * - `Form.Provider`: react-hook-form provider 래퍼다.
+ * - `Form.Field.*`: Container/Header/Body/Footer/Template 레이아웃 도구다.
+ * - `getFormFieldWidthAttr`, `getFormFieldWidthValue`: width 계산 util이다.
+ */
 import "./index.scss";
 
 export { Form } from "./markup";

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

@@ -2,8 +2,12 @@ import FormProvider from "./Provider";
 import { FormField } from "./form-field";
 
 /**
- * Form namespace 조립 전용 파일.
- * - index.tsx 배럴 파일에서 로직/객체 생성을 분리한다.
+ * Form; provider + field layout namespace
+ * @desc
+ * - `Form.Provider`: react-hook-form provider 래퍼다.
+ * - `Form.Field.Container`: field 루트 wrapper다.
+ * - `Form.Field.Header`, `Form.Field.Body`, `Form.Field.Footer`: depth 고정 섹션이다.
+ * - `Form.Field.Template`: 반복 조합용 필드 템플릿이다.
  */
 export const Form = {
   Provider: FormProvider,

package/src/components/info-box/index.tsx

@@ -1,3 +1,10 @@
+/**
+ * InfoBox; 안내/상태 메시지 카테고리 배럴
+ * @desc
+ * - `InfoBox`: heading/body를 렌더링하는 루트 컴포넌트다.
+ * - `InfoBoxIcon`: state별 아이콘 맵이다.
+ * - `InfoBoxProps`, `InfoBoxState`: public contract 타입이다.
+ */
 import "./index.scss";
 
 export * from "./markup";

package/src/components/info-box/markup/InfoBox.tsx

@@ -7,7 +7,7 @@ import { InfoBoxIcon } from "./Icon";
  * InfoBox Component; 안내 메시지 전용 정보 박스
  * @component
  * @param {InfoBoxProps} props
- * @param {"info"} [props.state="info"] 현재는 info 상태만 지원한다.
+ * @param {"info" | "caution" | "success" | "error"} [props.state="info"] 안내/상태 메시지 시각 축이다.
  * @param {React.ReactNode} [props.heading] 상단 제목 영역.
  * @param {React.ReactNode} [props.children] 본문 콘텐츠.
  * @param {string} [props.className] 루트 section className.

package/src/components/info-box/markup/index.ts

@@ -1,2 +1,8 @@
+/**
+ * InfoBox; 안내/상태 메시지 markup export 배럴
+ * @desc
+ * - `InfoBox`: heading/body를 렌더링하는 루트 컴포넌트다.
+ * - `InfoBoxIcon`: state별 아이콘 맵이다.
+ */
 export { default as InfoBox } from "./InfoBox";
 export * from "./Icon";

package/src/components/info-box/types/props.ts

@@ -7,7 +7,7 @@ type NativeSectionProps = Omit<ComponentPropsWithoutRef<"section">, "title">;
 
 /**
  * InfoBox Props; info-box 루트 속성
- * @property {"info" | "caution" | "success" | "error"} [state] state 값. 현재는 info만 허용한다.
+ * @property {"info" | "caution" | "success" | "error"} [state] info/caution/success/error 상태 축이다.
  * @property {ReactNode} [heading] 상단 제목 콘텐츠
  * @property {ReactNode} [children] 본문 콘텐츠
  * @property {string} [className] 루트 section className
@@ -15,7 +15,7 @@ type NativeSectionProps = Omit<ComponentPropsWithoutRef<"section">, "title">;
  */
 export interface InfoBoxProps extends Omit<NativeSectionProps, "children"> {
   /**
-   * state 값. 현재는 info만 허용한다.
+   * info/caution/success/error 상태 축이다.
    * - info, caution, success, error
    */
   state?: InfoBoxState;

package/src/components/input/index.tsx

@@ -1,5 +1,10 @@
 /**
- * input 카테고리 배럴 placeholder: 실제 구현은 markup/ 하위에 추가한다.
+ * Input; namespace 배럴 export
+ * @desc
+ * - `Input.Base`, `Input.TextArea`: foundation control
+ * - `Input.Text.*`: text scenario wrappers
+ * - `Input.Date`, `Input.Address`, `Input.File`: category presets
+ * - hooks/utils/types는 별도 배럴로 함께 export한다
  */
 import "./index.scss";
 

package/src/components/input/markup/foundation/Input.tsx

@@ -34,7 +34,7 @@ import InputBaseUtil from "./Utility";
  * @param {"default" | "active" | "focused" | "success" | "error" | "disabled" | "loading"} [props.state="default"] 시각 상태(tertiary는 disabled 외 feedback color 미적용)
  * @param {boolean} [props.block=false] true면 width 100% (`priority="table"`은 width 미지정 시 full 기본)
  * @param {React.ReactNode} [props.inlineLabel] tertiary border 내부 상단 라벨
- * @param {FormFieldWidth} [props.width] width preset
+ * @param {"full" | "fit" | "fill" | "auto" | number | string} [props.width] width preset 또는 custom width
  * @param {React.ReactNode} [props.left] 입력 왼쪽 슬롯(아이콘/텍스트)
  * @param {React.ReactNode} [props.right] 입력 오른쪽 슬롯
  * @param {React.ReactNode} [props.clear] 입력값 초기화 아이콘. 지정하지 않으면 기본 Reset 아이콘
@@ -54,7 +54,7 @@ import InputBaseUtil from "./Utility";
  * @param {string | number | readonly string[]} [props.value] 제어형 값
  * @param {string | number | readonly string[]} [props.defaultValue] 비제어 초기값
  * @param {string} [props.type="text"] native input type
- * @param {boolean} [props.readOnly] native readOnly
+ * @param {boolean} [props.readOnly] native readOnly. value가 없으면 placeholder는 alternative 토큰으로 그대로 노출된다.
  */
 const InputBase = forwardRef<HTMLInputElement, InputProps>(
   (