@uniai-fe/uds-primitives 0.0.7 → 0.0.8

package/src/components/button/styles/round-button.scss

@@ -0,0 +1,56 @@
+@use "@uniai-fe/uds-foundation/css";
+
+.button.button-template-round {
+  min-width: auto;
+  padding-block: var(
+    --theme-button-round-padding-block,
+    var(--spacing-padding-2, 4px)
+  );
+  padding-inline: var(
+    --theme-button-round-padding-inline-medium,
+    var(--spacing-padding-6, 16px)
+  );
+  gap: var(--spacing-gap-2, 8px);
+}
+
+.button.button-template-round-size-small {
+  min-height: var(
+    --theme-button-round-min-height-small,
+    var(--theme-size-small-2, 24px)
+  );
+  padding-inline: var(
+    --theme-button-round-padding-inline-small,
+    var(--spacing-padding-5, 12px)
+  );
+  border-radius: var(
+    --theme-button-round-radius-small,
+    var(--theme-radius-xlarge-2, 16px)
+  );
+}
+
+.button.button-template-round-size-medium {
+  min-height: var(
+    --theme-button-round-min-height-medium,
+    var(--theme-size-small-3, 32px)
+  );
+  padding-inline: var(
+    --theme-button-round-padding-inline-medium,
+    var(--spacing-padding-6, 16px)
+  );
+  border-radius: var(
+    --theme-button-round-radius-medium,
+    var(--theme-radius-xlarge-2, 16px)
+  );
+}
+
+.button.button-template-round-size-large {
+  min-height: var(
+    --theme-button-round-min-height-large,
+    var(--theme-size-medium-1, 40px)
+  );
+  padding-inline: var(
+    --theme-button-round-padding-inline-large,
+    var(--spacing-padding-7, 20px)
+  );
+  border-radius: var(--theme-button-round-radius-large, 30px);
+}

package/src/components/button/styles/text-button.scss

@@ -0,0 +1,96 @@
+@use "@uniai-fe/uds-foundation/css";
+
+.button.button-template-text {
+  min-width: auto;
+  border-color: transparent;
+  background-color: transparent;
+  padding-block: var(
+    --theme-button-text-padding-block,
+    var(--spacing-padding-4, 8px)
+  );
+  padding-inline: var(
+    --theme-button-text-padding-inline-small,
+    var(--spacing-padding-4, 8px)
+  );
+  border-width: 0;
+  gap: var(--spacing-gap-1, 4px);
+  border-radius: var(
+    --theme-button-text-radius,
+    var(--theme-radius-small, 4px)
+  );
+}
+
+.button.button-template-text-size-small {
+  min-height: var(
+    --theme-button-text-min-height-small,
+    var(--theme-size-small-1, 20px)
+  );
+  padding-inline: var(
+    --theme-button-text-padding-inline-small,
+    var(--spacing-padding-4, 8px)
+  );
+}
+
+.button.button-template-text-size-medium {
+  min-height: var(
+    --theme-button-text-min-height-medium,
+    var(--theme-size-small-2, 24px)
+  );
+  padding-inline: var(
+    --theme-button-text-padding-inline-medium,
+    var(--spacing-padding-5, 12px)
+  );
+}
+
+.button.button-template-text-size-large {
+  min-height: var(
+    --theme-button-text-min-height-large,
+    var(--theme-size-small-3, 32px)
+  );
+  padding-inline: var(
+    --theme-button-text-padding-inline-large,
+    var(--spacing-padding-5, 12px)
+  );
+}
+
+.button.button-template-text:disabled {
+  background-color: transparent;
+  border-color: transparent;
+}
+
+.button.button-template-text.button-priority-secondary {
+  color: var(
+    --theme-button-color-primary-default,
+    var(--color-primary-default)
+  );
+
+  &:hover:not(:disabled),
+  &[data-user-action="hover"]:not(:disabled) {
+    background-color: var(
+      --color-bg-alternative-cool-gray,
+      var(--color-cool-gray-95)
+    );
+  }
+
+  &:active:not(:disabled),
+  &[data-user-action="pressed"]:not(:disabled) {
+    background-color: var(--color-secondary-strong, var(--color-blue-90));
+  }
+}
+
+.button.button-template-text.button-priority-tertiary {
+  color: var(--theme-button-color-cool-gray-10, var(--color-cool-gray-10));
+
+  &:hover:not(:disabled),
+  &[data-user-action="hover"]:not(:disabled) {
+    background-color: var(
+      --color-bg-alternative-cool-gray,
+      var(--color-cool-gray-95)
+    );
+  }
+
+  &:active:not(:disabled),
+  &[data-user-action="pressed"]:not(:disabled) {
+    background-color: var(--color-bg-surface-strong, var(--color-cool-gray-20));
+  }
+}

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

@@ -1,49 +1,116 @@
-import type { ComponentPropsWithoutRef, ReactNode, ReactElement } from "react";
+import type { ComponentPropsWithoutRef, ElementType, ReactNode } from "react";
 
 /**
- * 버튼 variant/axes는 `modules/_context/design-system/sot/current/components/assets-index.json`
- * 의 button 항목을 그대로 반영한다.
+ * 지원하는 priority 축. semantic color 세트를 결정할 때 사용한다.
+ */
+export const BUTTON_PRIORITIES = ["primary", "secondary", "tertiary"] as const;
+/**
+ * scale은 fill/size 조합을 묶어 버튼 spacing/height/타이포를 설정한다.
+ */
+export const BUTTON_SCALES = [
+  "solid-xlarge",
+  "solid-large",
+  "solid-medium",
+  "solid-small",
+  "outlined-xlarge",
+  "outlined-large",
+  "outlined-medium",
+  "outlined-small",
+] as const;
+/**
+ * state는 디자인 토큰에서 정의한 3단계만 노출한다.
  */
-export const BUTTON_VARIANTS = ["solid", "outlined", "text-button"] as const;
-export const BUTTON_INTENTS = ["primary", "secondary", "teritary"] as const;
-export const BUTTON_SIZES = ["xlarge", "large", "medium", "small"] as const;
-export const BUTTON_SHAPES = ["default", "round"] as const;
 export const BUTTON_STATES = ["default", "readonly", "disabled"] as const;
-export const BUTTON_SIMULATED_STATES = ["hover", "pressed"] as const;
+/**
+ * data-user-action attribute로 강제 표현할 수 있는 상호작용 모드.
+ */
+export const BUTTON_USER_ACTIONS = ["hover", "pressed"] as const;
 
-export type ButtonVariant = (typeof BUTTON_VARIANTS)[number];
-export type ButtonIntent = (typeof BUTTON_INTENTS)[number];
-export type ButtonSize = (typeof BUTTON_SIZES)[number];
-export type ButtonShape = (typeof BUTTON_SHAPES)[number];
+export type ButtonPriority = (typeof BUTTON_PRIORITIES)[number];
+export type ButtonScale = (typeof BUTTON_SCALES)[number];
 export type ButtonState = (typeof BUTTON_STATES)[number];
-export type ButtonSimulatedState = (typeof BUTTON_SIMULATED_STATES)[number];
+export type ButtonUserAction = (typeof BUTTON_USER_ACTIONS)[number];
 export type ButtonIconSlot = "none" | "left" | "right";
 
+export type ButtonFill = "solid" | "outlined";
+export type ButtonSize = "xlarge" | "large" | "medium" | "small";
+export type ButtonScaleGroup = ButtonFill;
+
+type ButtonScaleConfig = {
+  fill: ButtonFill;
+  group: ButtonScaleGroup;
+  size: ButtonSize;
+};
+
+const createScaleConfig = (
+  fill: ButtonFill,
+  size: ButtonSize,
+  group: ButtonScaleGroup,
+): ButtonScaleConfig => ({
+  fill,
+  size,
+  group,
+});
+
+/**
+ * scale 별 fill/size/group 메타데이터. className이나 slot 로직이 동일한 source를 참고할 수 있다.
+ */
+export const BUTTON_SCALE_CONFIG: Record<ButtonScale, ButtonScaleConfig> = {
+  "solid-xlarge": createScaleConfig("solid", "xlarge", "solid"),
+  "solid-large": createScaleConfig("solid", "large", "solid"),
+  "solid-medium": createScaleConfig("solid", "medium", "solid"),
+  "solid-small": createScaleConfig("solid", "small", "solid"),
+  "outlined-xlarge": createScaleConfig("outlined", "xlarge", "outlined"),
+  "outlined-large": createScaleConfig("outlined", "large", "outlined"),
+  "outlined-medium": createScaleConfig("outlined", "medium", "outlined"),
+  "outlined-small": createScaleConfig("outlined", "small", "outlined"),
+};
+
+/**
+ * 인터랙션 제약을 위해 fill 축으로 scale을 그룹화한 매핑.
+ */
+export const BUTTON_SCALE_GROUPS: Record<ButtonScaleGroup, ButtonScale[]> = {
+  solid: ["solid-xlarge", "solid-large", "solid-medium", "solid-small"],
+  outlined: [
+    "outlined-xlarge",
+    "outlined-large",
+    "outlined-medium",
+    "outlined-small",
+  ],
+};
+
+/**
+ * 우선순위 default. (primary)
+ */
+export const DEFAULT_BUTTON_PRIORITY: ButtonPriority = "primary";
+/**
+ * scale default. (solid-medium)
+ */
+export const DEFAULT_BUTTON_SCALE: ButtonScale = "solid-medium";
+
 type NativeButtonProps = ComponentPropsWithoutRef<"button">;
-export interface ButtonProps extends Omit<
-  NativeButtonProps,
-  "children" | "prefix" | "suffix"
-> {
-  /**
-   * 주 버튼 내용. 문자열이면 `<span class="button-label">`로 자동 감싼다.
-   */
-  children?: ReactNode;
+type AnchorProps = ComponentPropsWithoutRef<"a">;
+
+type SharedElementProps = Omit<NativeButtonProps, "children"> &
+  Omit<AnchorProps, "children">;
+
+export interface ButtonProps extends SharedElementProps {
   /**
-   * SOT에서 정의한 버튼 스타일 축(solid/outlined/text-button).
+   * 렌더링할 요소. 기본값은 button.
    */
-  variant?: ButtonVariant;
+  as?: ElementType;
   /**
-   * UX priority(semantic color). foundation semantic 색과 매핑된다.
+   * 주 버튼 내용. 문자열이면 `<span class="button-label">`로 자동 감싼다.
    */
-  intent?: ButtonIntent;
+  children?: ReactNode;
   /**
-   * 디자인 토큰 사이즈 alias(small~xlarge). Theme size 단계와 매핑된다.
+   * 레이아웃/spacing 집합. 예) `solid-large`, `outlined-medium`.
    */
-  size?: ButtonSize;
+  scale?: ButtonScale;
   /**
-   * radius alias. round는 full radius를 사용한다.
+   * semantic color priority.
    */
-  shape?: ButtonShape;
+  priority?: ButtonPriority;
   /**
    * UI state: readonly/disabled 를 명시적으로 설정할 수 있다.
    */
@@ -65,15 +132,23 @@ export interface ButtonProps extends Omit<
    */
   icon?: ReactNode;
   /**
-   * 라벨 앞에 표시할 prefix 슬롯.
+   * 라벨 왼쪽에 표시할 슬롯.
    */
-  prefix?: ReactElement;
+  left?: ReactNode;
   /**
-   * 라벨 뒤에 표시할 suffix 슬롯.
+   * 라벨 오른쪽에 표시할 슬롯.
    */
-  suffix?: ReactElement;
+  right?: ReactNode;
   /**
-   * Storybook에서 hover/pressed 상태를 강제로 보여주기 위한 data attribute.
+   * Storybook 등에서 hover/pressed 상태를 강제로 보여줄 때 사용하는 data attribute.
    */
-  "data-simulated-state"?: ButtonSimulatedState;
+  "data-user-action"?: ButtonUserAction;
 }
+
+export type {
+  TextButtonProps,
+  TextButtonPriority,
+  TextButtonSize,
+  RoundButtonProps,
+  RoundButtonSize,
+} from "./templates";

package/src/components/button/types/templates.ts

@@ -0,0 +1,33 @@
+import type { ButtonPriority, ButtonProps } from ".";
+
+/**
+ * TextButton 컴포넌트에서 허용하는 size 축.
+ */
+export type TextButtonSize = "small" | "medium" | "large";
+/**
+ * TextButton은 secondary/tertiary priority만 허용한다.
+ */
+export type TextButtonPriority = Exclude<ButtonPriority, "primary">;
+
+/**
+ * TextButton 템플릿 props. scale/priority는 템플릿에서 내부적으로 제어하므로 제거했다.
+ */
+export interface TextButtonProps extends Omit<
+  ButtonProps,
+  "scale" | "priority"
+> {
+  size?: TextButtonSize;
+  priority?: TextButtonPriority;
+}
+
+/**
+ * RoundButton 컴포넌트에서 지원하는 size 축.
+ */
+export type RoundButtonSize = "small" | "medium" | "large";
+
+/**
+ * RoundButton 템플릿 props. scale은 템플릿 안에서 size에 따라 파생된다.
+ */
+export interface RoundButtonProps extends Omit<ButtonProps, "scale"> {
+  size?: RoundButtonSize;
+}

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

@@ -1,18 +1,18 @@
 import clsx from "clsx";
 import type {
+  ButtonFill,
   ButtonIconSlot,
-  ButtonIntent,
-  ButtonShape,
+  ButtonPriority,
+  ButtonScale,
   ButtonSize,
   ButtonState,
-  ButtonVariant,
 } from "../types";
 
 type ButtonClassNameOptions = {
-  variant: ButtonVariant;
-  intent: ButtonIntent;
+  scale: ButtonScale;
+  fill: ButtonFill;
+  priority: ButtonPriority;
   size: ButtonSize;
-  shape: ButtonShape;
   block: boolean;
   loading: boolean;
   iconSlot: ButtonIconSlot;
@@ -24,13 +24,13 @@ type ButtonClassNameOptions = {
 const BUTTON_CLASSNAME = "button";
 
 /**
- * 버튼 클래스 조합 helper: variant/intent/size 별 modifier를 한 곳에서 관리한다.
+ * 버튼 클래스 조합 helper: scale/fill/priority/size 별 modifier를 한 곳에서 관리한다.
  */
 const composeButtonClassName = ({
-  variant,
-  intent,
+  scale,
+  fill,
+  priority,
   size,
-  shape,
   block,
   loading,
   iconSlot,
@@ -40,16 +40,16 @@ const composeButtonClassName = ({
 }: ButtonClassNameOptions) =>
   clsx(
     BUTTON_CLASSNAME,
-    `${BUTTON_CLASSNAME}--variant-${variant}`,
-    `${BUTTON_CLASSNAME}--intent-${intent}`,
-    `${BUTTON_CLASSNAME}--size-${size}`,
-    `${BUTTON_CLASSNAME}--shape-${shape}`,
+    `${BUTTON_CLASSNAME}-scale-${scale}`,
+    `${BUTTON_CLASSNAME}-fill-${fill}`,
+    `${BUTTON_CLASSNAME}-priority-${priority}`,
+    `${BUTTON_CLASSNAME}-size-${size}`,
     {
-      [`${BUTTON_CLASSNAME}--state-${state}`]: state !== "default",
-      [`${BUTTON_CLASSNAME}--block`]: block,
-      [`${BUTTON_CLASSNAME}--loading`]: loading,
-      [`${BUTTON_CLASSNAME}--icon-${iconSlot}`]: iconSlot !== "none",
-      [`${BUTTON_CLASSNAME}--icon-only`]: iconOnly,
+      [`${BUTTON_CLASSNAME}-state-${state}`]: state !== "default",
+      [`${BUTTON_CLASSNAME}-block`]: block,
+      [`${BUTTON_CLASSNAME}-loading`]: loading,
+      [`${BUTTON_CLASSNAME}-icon-${iconSlot}`]: iconSlot !== "none",
+      [`${BUTTON_CLASSNAME}-icon-only`]: iconOnly,
     },
     className,
   );

package/src/components/checkbox/markup/Checkbox.tsx

@@ -19,7 +19,14 @@ const getIndicatorIcon = (size: CheckboxSize) =>
  * 체크박스 컴포넌트; Radix Checkbox thin wrapper
  * @component
  * @param {CheckboxProps} props
- * @param {CheckboxSize} [props.size] medium, large
+ * @param {"medium" | "large"} [props.size="medium"] indicator/label spacing 크기.
+ * @param {boolean} [props.checked] 제어형 체크 상태.
+ * @param {boolean} [props.defaultChecked] 비제어 초기 체크 상태.
+ * @param {boolean} [props.disabled] disabled 상태.
+ * @param {(checked: CheckboxPrimitive.CheckedState) => void} [props.onCheckedChange]
+ *  체크 상태 변경 핸들러.
+ * @param {string} [props.className] root className.
+ * @param {string} [props.name] form name.
  * @example
  * <Checkbox size="medium" checked />
  */
@@ -51,7 +58,18 @@ export const Checkbox = forwardRef<HTMLButtonElement, CheckboxProps>(
  * 체크박스 필드 컴포넌트; label/helper 텍스트 래퍼
  * @component
  * @param {CheckboxFieldProps} props
- * @param {CheckboxSize} [props.size] medium, large
+ * @param {"medium" | "large"} [props.size="medium"] indicator 크기.
+ * @param {React.ReactNode} [props.label] `<label>` 텍스트/노드.
+ * @param {React.ReactNode} [props.helperText] helper 텍스트.
+ * @param {ComponentPropsWithoutRef<"label">} [props.labelProps] label attr.
+ * @param {ComponentPropsWithoutRef<"p">} [props.helperTextProps] helper attr.
+ * @param {string} [props.fieldClassName] `.checkbox-field` className.
+ * @param {string} [props.labelWrapperClassName] 라벨 wrapper className.
+ * @param {boolean} [props.checked] 제어형 체크 상태.
+ * @param {boolean} [props.defaultChecked] 비제어 초기 체크 상태.
+ * @param {(checked: CheckboxPrimitive.CheckedState) => void} [props.onCheckedChange]
+ *  체크 상태 변경 핸들러.
+ * @param {boolean} [props.disabled] disabled 상태.
  * @example
  * <CheckboxField label="약관 동의" helperText="필수" checked />
  */

package/src/components/checkbox/types/checkbox.ts

@@ -1,16 +1,32 @@
 import type { ComponentPropsWithoutRef, ReactNode } from "react";
 import type * as CheckboxPrimitive from "@radix-ui/react-checkbox";
 
+/**
+ * 지원하는 checkbox 사이즈. medium/large 두 단계.
+ */
 export type CheckboxSize = "medium" | "large";
 
 export type CheckboxPrimitiveProps = ComponentPropsWithoutRef<
   typeof CheckboxPrimitive.Root
 >;
 
+/**
+ * Radix Checkbox Root에 size/className 확장을 더한 props.
+ * @property {"medium" | "large"} [size="medium"] indicator/box 크기.
+ */
 export interface CheckboxProps extends CheckboxPrimitiveProps {
   size?: CheckboxSize;
 }
 
+/**
+ * label/helperText 등을 포함하는 CheckboxField 래퍼 props.
+ * @property {React.ReactNode} [label] `<label>`로 연결되는 텍스트/노드.
+ * @property {React.ReactNode} [helperText] label 하단 추가 설명.
+ * @property {ComponentPropsWithoutRef<"p">} [helperTextProps] helper container attr.
+ * @property {ComponentPropsWithoutRef<"label">} [labelProps] label attr.
+ * @property {string} [fieldClassName] `.checkbox-field` className override.
+ * @property {string} [labelWrapperClassName] label wrapper className.
+ */
 export interface CheckboxFieldProps extends CheckboxProps {
   label?: ReactNode;
   helperText?: ReactNode;

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

@@ -14,6 +14,14 @@ const isChipInputProps = (props: ChipProps): props is ChipInputProps =>
 
 /**
  * Chip 종류별로 interactive/input 구조가 달라 별도 분기한다.
+ * @component
+ * @param {ChipProps} props
+ * @param {"filter" | "filter-rounded" | "assist" | "input"} [props.kind="filter"] chip kind.
+ * @param {boolean} [props.selected] 선택 상태. filter 계열에서 aria-pressed로 노출.
+ * @param {React.ReactNode} [props.leading] assist kind 전용 leading slot.
+ * @param {string} [props.removeButtonLabel="선택 항목 삭제"] input kind 제거 버튼 라벨.
+ * @param {(event: MouseEvent<HTMLButtonElement>) => void} [props.onRemove] input kind 제거 핸들러.
+ * @param {string} [props.className] root className.
  */
 const Chip = forwardRef<HTMLElement, ChipProps>((props, ref) => {
   if (isChipInputProps(props)) {

package/src/components/dialog/markup/{confirm-dialog.tsx → ConfirmDialog.tsx}

@@ -36,6 +36,9 @@ const useConfirmDialogInternalContext = () => {
  * ConfirmDialogRoot; AlertDialog 루트
  * @component
  * @param {ConfirmDialogRootProps} props
+ * @param {boolean} [props.open] 제어형 open 상태.
+ * @param {boolean} [props.defaultOpen] 비제어 초기 open 상태.
+ * @param {(open: boolean) => void} [props.onOpenChange] open 변경 콜백.
  */
 const ConfirmDialogRoot = ({
   open: openProp,
@@ -80,6 +83,8 @@ const ConfirmDialogPortal = AlertDialogPrimitive.Portal;
  * ConfirmDialogOverlay; 취소 성격의 바깥 dim
  * @component
  * @param {ConfirmDialogOverlayProps} props
+ * @param {string} [props.className] overlay className.
+ * @param {boolean} [props.disableOutsideClose=false] dim 클릭으로 닫힘 방지 여부.
  */
 const ConfirmDialogOverlay = forwardRef<
   HTMLDivElement,
@@ -120,6 +125,8 @@ ConfirmDialogOverlay.displayName = "ConfirmDialogOverlay";
  * ConfirmDialogContent; AlertDialog 패널
  * @component
  * @param {ConfirmDialogContentProps} props
+ * @param {string} [props.className] content className.
+ * @param {React.ReactNode} [props.children] 패널 내용.
  */
 const ConfirmDialogContent = forwardRef<
   HTMLDivElement,
@@ -141,6 +148,9 @@ ConfirmDialogContent.displayName = "ConfirmDialogContent";
  * ConfirmDialogTitle; AlertDialog 제목
  * @component
  * @param {ConfirmDialogTitleProps} props
+ * @param {string} [props.className] title className.
+ * @param {boolean} [props.visuallyHidden=false] 제목 시각적 숨김 여부.
+ * @param {React.ReactNode} [props.children] 제목 텍스트.
  */
 const ConfirmDialogTitle = forwardRef<
   HTMLHeadingElement,
@@ -170,6 +180,9 @@ ConfirmDialogTitle.displayName = "ConfirmDialogTitle";
  * ConfirmDialogDescription; AlertDialog 설명
  * @component
  * @param {ConfirmDialogDescriptionProps} props
+ * @param {string} [props.className] description className.
+ * @param {boolean} [props.visuallyHidden=false] 설명 시각적 숨김 여부.
+ * @param {React.ReactNode} [props.children] 설명 텍스트.
  */
 const ConfirmDialogDescription = forwardRef<
   HTMLParagraphElement,
@@ -202,6 +215,8 @@ ConfirmDialogDescription.displayName = "ConfirmDialogDescription";
  * ConfirmDialogHeader; 헤더 영역
  * @component
  * @param {ConfirmDialogSectionProps} props
+ * @param {string} [props.className] 섹션 className.
+ * @param {React.ReactNode} [props.children] 헤더 콘텐츠.
  */
 const ConfirmDialogHeader = forwardRef<
   HTMLDivElement,
@@ -221,6 +236,8 @@ ConfirmDialogHeader.displayName = "ConfirmDialogHeader";
  * ConfirmDialogBody; 본문 영역
  * @component
  * @param {ConfirmDialogSectionProps} props
+ * @param {string} [props.className] 섹션 className.
+ * @param {React.ReactNode} [props.children] 본문 콘텐츠.
  */
 const ConfirmDialogBody = forwardRef<HTMLDivElement, ConfirmDialogSectionProps>(
   ({ className, ...props }, forwardedRef) => (
@@ -239,6 +256,8 @@ ConfirmDialogBody.displayName = "ConfirmDialogBody";
  * ConfirmDialogActions; 버튼 영역
  * @component
  * @param {ConfirmDialogSectionProps} props
+ * @param {string} [props.className] 섹션 className.
+ * @param {React.ReactNode} [props.children] 버튼 콘텐츠.
  */
 const ConfirmDialogActions = forwardRef<
   HTMLDivElement,
@@ -258,6 +277,8 @@ ConfirmDialogActions.displayName = "ConfirmDialogActions";
  * ConfirmDialogCancelButton; AlertDialog Cancel wrapper
  * @component
  * @param {ConfirmDialogCancelProps} props
+ * @param {string} [props.className] button className.
+ * @param {boolean} [props.asChild=false] slot mode 사용 여부.
  */
 const ConfirmDialogCancel = forwardRef<
   HTMLButtonElement,
@@ -281,6 +302,8 @@ ConfirmDialogCancel.displayName = "ConfirmDialogCancel";
  * ConfirmDialogActionButton; AlertDialog Action wrapper
  * @component
  * @param {ConfirmDialogActionProps} props
+ * @param {string} [props.className] button className.
+ * @param {boolean} [props.asChild=false] slot mode 사용 여부.
  */
 const ConfirmDialogAction = forwardRef<
   HTMLButtonElement,

package/src/components/dialog/markup/{notice-dialog.tsx → NoticeDialog.tsx}

@@ -14,6 +14,9 @@ import type {
  * NoticeDialogRoot; 공통 Dialog 상태 제어 루트
  * @component
  * @param {NoticeDialogRootProps} props
+ * @param {boolean} [props.open] 제어형 open 상태.
+ * @param {boolean} [props.defaultOpen] 비제어 초기 open 상태.
+ * @param {(open: boolean) => void} [props.onOpenChange] open 변경 콜백.
  */
 const NoticeDialogRoot = DialogPrimitive.Root;
 const NoticeDialogTrigger = DialogPrimitive.Trigger;
@@ -24,6 +27,7 @@ const NoticeDialogClose = DialogPrimitive.Close;
  * NoticeDialogOverlay; dim 영역
  * @component
  * @param {NoticeDialogOverlayProps} props
+ * @param {string} [props.className] overlay className.
  */
 const NoticeDialogOverlay = forwardRef<
   HTMLDivElement,
@@ -43,6 +47,8 @@ NoticeDialogOverlay.displayName = "NoticeDialogOverlay";
  * NoticeDialogContent; 콘텐츠 패널
  * @component
  * @param {NoticeDialogContentProps} props
+ * @param {string} [props.className] content className.
+ * @param {React.ReactNode} [props.children] panel 내용.
  */
 const NoticeDialogContent = forwardRef<
   HTMLDivElement,
@@ -64,6 +70,9 @@ NoticeDialogContent.displayName = "NoticeDialogContent";
  * NoticeDialogTitle; Dialog 제목
  * @component
  * @param {NoticeDialogTitleProps} props
+ * @param {string} [props.className] title className.
+ * @param {boolean} [props.visuallyHidden=false] 제목을 시각적으로 숨길지 여부.
+ * @param {React.ReactNode} [props.children] 제목 텍스트.
  */
 const NoticeDialogTitle = forwardRef<
   HTMLHeadingElement,
@@ -93,6 +102,9 @@ NoticeDialogTitle.displayName = "NoticeDialogTitle";
  * NoticeDialogDescription; Dialog 설명
  * @component
  * @param {NoticeDialogDescriptionProps} props
+ * @param {string} [props.className] description className.
+ * @param {boolean} [props.visuallyHidden=false] 설명을 시각적으로 숨길지 여부.
+ * @param {React.ReactNode} [props.children] 설명 텍스트.
  */
 const NoticeDialogDescription = forwardRef<
   HTMLParagraphElement,
@@ -125,6 +137,8 @@ NoticeDialogDescription.displayName = "NoticeDialogDescription";
  * NoticeDialogHeader; 헤더 레이아웃
  * @component
  * @param {NoticeDialogSectionProps} props
+ * @param {string} [props.className] 섹션 className.
+ * @param {React.HTMLAttributes<HTMLDivElement>["children"]} [props.children] 헤더 콘텐츠.
  */
 const NoticeDialogHeader = forwardRef<HTMLDivElement, NoticeDialogSectionProps>(
   ({ className, ...props }, forwardedRef) => (
@@ -143,6 +157,8 @@ NoticeDialogHeader.displayName = "NoticeDialogHeader";
  * NoticeDialogBody; 본문 영역
  * @component
  * @param {NoticeDialogSectionProps} props
+ * @param {string} [props.className] 섹션 className.
+ * @param {React.ReactNode} [props.children] 본문 콘텐츠.
  */
 const NoticeDialogBody = forwardRef<HTMLDivElement, NoticeDialogSectionProps>(
   ({ className, ...props }, forwardedRef) => (
@@ -161,6 +177,8 @@ NoticeDialogBody.displayName = "NoticeDialogBody";
  * NoticeDialogActions; 버튼 영역
  * @component
  * @param {NoticeDialogSectionProps} props
+ * @param {string} [props.className] 섹션 className.
+ * @param {React.ReactNode} [props.children] 버튼 콘텐츠.
  */
 const NoticeDialogActions = forwardRef<
   HTMLDivElement,